Engine/Echo Protocol

Introduction and rationale

Echo is a protocol in the Distribution family.

Echo does not deliver any security property: it is only used to initiate TOFU. The Echo protocol partly destroys privacy – which is why it can be switched off, session-wise. It is enabled by default.

Echo and allows the first message with content in an exchange to be protected, when it otherwise would not be.


Echo is a stateless protocol.

There are two messages:

  • Ping
  • Pong

The only message fields are a challenge (random UUID) in Ping, and a response (UUID equal to the one in the Ping message to which the Pong message is a reply) in Pong. The challenge/response machinery is only intended to protect from forged Pong messages.

A communication partner Alice can send a Ping message to a communication partner Bob. Bob, if he desires, can reply with a Pong message to Alice. The Pong message will usually carry Bob’s sender_key, which allows Alice to protect her next message to Bob.

Engine API

The API is very simple.


void config_enable_echo_protocol(PEP_SESSION session,
                                 bool enable);

In the given session, enable or disable the Distribution.Echo protocol: enable iff enable is true. The protocol is enabled by default.


PEP_STATUS send_ping(PEP_SESSION session,
                     const pEp_identity *from,
                     const pEp_identity *to);

In the given session send a Ping message from the given identity, which must be own, to the given identity. Return PEP_ILLEGAL_VALUE if session, from or to are NULL or if from is non-own, PEP_OUT_OF_MEMORY in case of out-of-memory errors, or otherwise the result of messageToSend, which will be PEP_STATUS_OK in case of success.

Unnecessary API functions

There is no API call for sending Pong messages: a Pong message is automatically sent as a reply to Ping when the Distribution.Echo protocol is enabled.

There is no API for handling a Ping or Pong message: Ping messages are automatically handled by decrypt_message, and Pong messages (after decrypting and, crucially, importing keys) are simply ignored.

Protocol use cases

  • When a secure message is received and some recipients are unknown to us, we automatically send them a Ping message each. This will help retrieving their keys, which will be useful in the event of a message from us to them.