unMessage Protocol

The unMessage protocol is based on the Double Ratchet Algorithm to establish conversations and exchange messages privately and anonymously.

Note

unMessage uses Tor Onion Services to anonymously connect peers as we believe that it is the best transport for this kind of application, but other approaches such as posting the packets to a public mailing list should also work (as long as the packets are anonymously posted).

In the Double Ratchet Algorithm, a secret key must be agreed on to derive all the other keys involved in the conversation. The secret key used by unMessage is generated with the Triple Diffie-Hellman Key Agreement, using one party’s public identity and handshake keys, and another’s private identity and handshake keys.

Each party must have its mode assigned to as either Alice or Bob. The one who starts the initialization is Bob and can send messages right after the secret key is generated. As part of the initialization, Bob must send his public ratchet key to Alice so that she is able to start the Diffie-Hellman ratcheting and also send messages immediately.

unMessage conversations have the following stages:

  1. Request sent
  2. Request accepted
  3. Conversation established

In order to send requests, both parties must launch unMessage to generate their Onion Service and Double Ratchet keypairs. unMessage is a serverless application, so a peer who wishes to receive requests must send/publish their Onion Service address and Double Ratchet public identity key through some other communication channel.

unMessage assigns Bob to the one who sends a request and Alice to the one who receives it.

Important

In the following sections, the shared request key and conversation ID are described as the direct input of hash and encryption functions for simplicity. In fact, these keys are input of a Key Derivation Function (KDF) along with its respective salt, and the output keys of the KDF that are actually used by such functions.

Stage 1: Request sent

A request keypair is generated by Bob’s unMessage to derive a Diffie-Hellman shared request key using the private request key and Alice’s public identity key. The shared request key, is used to encrypt the following information needed by Alice to initialize a conversation with Bob:

  • Bob’s identity address
  • Bob’s identity public key
  • Bob’s handshake public key
  • Bob’s ratchet public key

This set composes the handshake packet, which after encrypted is used to compose the request packet:

  • IV
  • hash(IV + Alice’s public identity key + shared request key)
  • keyed_hash(shared request key, encrypted handshake packet)
  • public request key
  • encrypted handshake packet

The packet is then sent to Alice’s Onion Address and Stage 1 is completed.

Important

The handshake packet should be signed by the Onion Service and Double Ratchet keys so that a peer cannot advertise keys they do not own. This will be implemented in a future version of unMessage.

Stage 2: Request accepted

After receiving the request packet, Alice’s unMessage derives the shared request key using Alice’s private identity key and the public request key. The shared request key is hashed with the IV and the handshake packet to make sure that is indeed an unMessage request packet and the handshake packet can be decrypted. Alice is notified that the request was received from Bob and accepts it to initialize the Double Ratchet conversation.

Bob’s public identity and handshake keys sent in the handshake packet are used to generate the Double Ratchet secret key with Alice’s private identity and handshake keys (the former was generated when unMessage was launched by the first time and the latter when the request was accepted, to be used for this specific conversation). The Double Ratchet conversation is finally initialized using the secret key and Bob’s public ratchet key (also sent in the handshake packet). At this point, Stage 2 is completed and Alice can start sending encrypted messages. However, as Bob does not have Alice’s public handshake key, it is encrypted (using the shared request key) and sent along with the unMessage reply packet:

  • IV
  • hash(IV + Bob’s public identity key + shared request key)
  • keyed_hash(shared request key, encrypted handshake key + encrypted payload)
  • Alice’s encrypted public handshake key
  • encrypted payload

Stage 3: Conversation established

When messages from Alice are received, Bob’s unMessage hashes the shared request key with the IV and Alice’s encrypted public handshake key concatenated with the encrypted payload to make sure that is indeed an unMessage packet from Alice, and her public handshake key can be decrypted. Bob now can also generate the secret key with his private identity and handshake keys, and Alice’s public identity and handshake keys. With his part of the conversation initialized, he can start sending unMessage regular packets:

  • IV
  • hash(IV + Alice’s public identity key + conversation ID)
  • keyed_hash(conversation ID, encrypted payload)
  • encrypted payload

Stage 3 is completed when Alice receives a regular packet from Bob, which means that he was able to initialize the conversation with her public handshake key and there is no need to send reply packets anymore, so her unMessage also starts sending regular packets.

Identifying conversations

All of the identifying information of an unMessage packet is encrypted so that an attacker who intercepts it cannot tell who are the receiver and sender.

When a packet is received, unMessage assumes it is a regular packet and attempts to use all of the peer’s conversation IDs to derive the IV hash. If the hash matches the packet’s IV hash, unMessage identifies the sender and is able to decrypt the payload (after verifying its integrity). If the IV hash does not match, unMessage assumes the packet is a request packet and derives a shared request key using the public request key from the packet and the peer’s public identity key. unMessage attempts to use the shared request key and the IV to derive a hash that matches the packet’s IV hash. If it matches, unMessage checks the integrity of the rest of the packet and processes the request as described in Stage 2.

When unMessage fails to identify or check the integrity of packets, they are ignored.

Note

The IV hash also uses the receiver’s public identity key as part of the hash so that, for example, Alice can tell the difference between messages she sent to Bob and messages she received from Bob.

The IV hash is another implementation of an hSub.