Ratchet Chat

Ratchet is a chat client that utilizes X3DH Double Ratchet protocols over the salty msgbus to ensure E2E encryption with forward secrecy and self healing properties.

This protocol builds on the infrastructure established by the Salty Protocols. In particular:

• The EdX25519 key for X3DH, EdDSA, and Curve25519 signatures.
• The MsgBus inbox delivery.
• Salty autodiscovery URLs.
• Salty message and event format for chat content.

Find the full spec here: https://salty.im/spec.html

Binary Protocol

All messages are wrapped with the following envelope.

  "!RAT!" | '1' - '5' | ... | "!CHT!"

A prefix/suffix of !RAT! !CHT! and a byte that indicates message type. The remaining bytes are URL Safe Base64 without padding.

Offer Message

Message Type = '1'

| 0 .. 31 | 32 .. 63 | 64 .. 127 | 128 .. 143 | 144 .. + |
| Pubkey  | SP Key   | SP Sig    | Session ID | Nick     |

Pubkey

Public ed25519 key of offering party. (Ack party verifies against salty discovery pubkey.)

SP Kkey

The X25519 signed prekey

SP Sig

The signature for X25519 signed prekey

Session ID

A random ULID used by the offering party to identify the session

Nick

The nickname of the offering party using (see salty lookup for usage)

Ack Message

Message Type = '2'

| 0 .. 31 | 32 .. 63 | 64 .. 79  | 80 .. 179 |
| Pubkey  | E Key    | SessionID | Encrypted |

Encrypted Payload
| 0 .. 15   | 16 .. 100 |
| SessionID | Random    |

Pubkey

Public ed25519 key of acking party. (Offering party verified against salty discovery pubkey.) E Kkey

The X25519 Ephemeral key of the acking party.

Session ID

The ULID used by the offering party to identify the session.

Encrypted

Initial payload with contents below

Encrypted Payload:

SessionID

Random ULID used by ack party to identify the session.

Random

Random bytes to fill the rest of payload

Data Message

Message Type = '3'

| 0 .. 15   | 16 .. +   |
| SessionID | Encrypted |

SessionID

Random ULID used by receiving party to identify the session.

Encrypted

Payload data that is decoded f

Close Message

Message Type = '4'

| 0 .. 15   | 16   |
| SessionID | 0xFF |

SessionID

Random ULID used by receiving party to identify the session.

0xFF

Encrypted value that matches the value 0xFF when decrypted.

Sealed Message

Sealed messages offer additonal privacy around the offer message to protect interception by other actors. The parameters are safe to be exposed as they utilize EdDSA to prevent exposing the secret values. The encryption is to protect the offer party nick from being exposed.

Message Type = '5'

| 0 .. 31  | 32 .. +   |
| E Pubkey | Encrypted |

Encrypted Payload

| 0    | 1 .. +         |
| Type | Message Content|

E Pubkey

Ephemeral Pubkey used to seal using the nacl anonymous box algorithem.

Encrypted

Encrypted payload

Encrypted Payload

Type

Message type of content

Message Content

Content as indicated by type

Xochimilco

An implementation of the Signal Protocols X3DH and Double Ratchet. Plus a simple straightforward usable E2E encryption library build on top, named Xochimilco.

For both implementation details and examples, take a look at the documentation.

Some background, the lake Xochimilco seems to be the last native habitat for the axolotl. This salamander, also called Mexican walking fish, has incredibly self healing abilities. For this reason, the Double Ratchet algorithm was initially named after this animal.