Module handshake 

This module provides an authenticated key exchange protocol, or handshake.

Design

The dialer and the listener both have a public identity, known to each other in advance. The goal of the handshake is to establish a shared, encrypted, and authenticated communication channel between these two parties. No third party should be able to read messages, or send messates along the channel.

A three-message handshake is used to authenticate peers and establish a shared secret. The dialer initiates the connection, and the listener responds.

Syn The dialer starts by sending a signed message with their ephemeral key.

SynAck The listener responds by sending back their ephemeral key, along with a signature over the protocol transcript thus far. They can also derive a shared secret, which they use to generate a confirmation tag, also sent to the dialer.

Ack The dialer verifies the signed message, then derives the same secret, and uses that to send their own confirmation back to the listener.

The listener then verifies this confirmation.

The shared secret can then be used to derive to AEAD keys, for the sending data (SendCipher) and receiving data (RecvCipher). These use ChaCha20-Poly1305 as the AEAD. Each direction has a 12 byte counter to used as a nonce, with every call to SendCipher::send on one end, or RecvCipher::recv on the other end incrementing this counter. Note that this guarantees that messages sent are received in order.

Security Features

The protocol includes timestamp validation to protect against replay attacks and clock skew:

• Messages with timestamps too old are rejected to prevent replay attacks
• Messages with timestamps too far in the future are rejected to safeguard against clock skew

Structs

Ack

Third handshake message sent by the dialer. Contains dialer’s confirmation tag to complete the handshake.

Context

Handshake context containing timing and identity information. Used by both dialer and listener to initialize handshake state.

DialState

State maintained by the dialer during handshake. Tracks ephemeral secret, peer identity, and protocol transcript.

ListenState

State maintained by the listener during handshake. Tracks expected confirmation and derived ciphers.

RecvCipher

SendCipher

Syn

First handshake message sent by the dialer. Contains dialer’s ephemeral key and timestamp signature.

SynAck

Second handshake message sent by the listener. Contains listener’s ephemeral key, signature, and confirmation tag.

Enums

Error

Errors relating to the handshake, or to encryption.

Constants

CIPHERTEXT_OVERHEAD

The amount of overhead in a ciphertext, compared to the plain message.

Functions

dial_end

Completes a handshake as the dialer. Verifies the listener’s response and returns final message and ciphers.

dial_start

Initiates a handshake as the dialer. Returns the dialer state and the first message to send.

listen_end

Completes the handshake as the listener. Verifies the dialer’s confirmation and returns established ciphers.

listen_start

Processes the first handshake message as the listener. Verifies the dialer’s message and returns state and response.