Module public_key 

Communicate with an authenticated peer over an encrypted connection.

This module provides a lightweight, self-contained transport layer for systems where peers already know one another’s cryptographic identities (any commonware_cryptography::Signer). It offers mutual authentication and encrypted communication using a simplified handshake, eliminating the need for complex protocols like TLS or X.509 certificates. The implementation uses a fixed, non-negotiable cryptographic protocol to simplify implementation and reduce overhead, resulting in a minimal performance impact.

Design

Handshake

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

The dialer initiates the connection to a known peer identity, while the listener accepts incoming connections. Much like a SYN / SYN-ACK / ACK handshake, the dialer and listener exchange messages in three rounds.

The SYN-equivalent is a handshake::Hello message that contains:

• The listener’s expected public key (prevents wrong-target attacks)
• The dialer’s ephemeral public key (for Diffie-Hellman key exchange)
• The current timestamp (prevents replay attacks)
• The dialer’s static public key and signature

The ACK-equivalent is a handshake::Confirmation message that proves that each party can derive the correct shared secret.

Thus:

• Message 1 is a Hello message from the dialer to the listener
• Message 2 is a Hello (with a continuation tag) and Confirmation message from the listener to the dialer
• Message 3 is a Confirmation message from the dialer to the listener

The continuation tag binds the listener’s handshake::Hello response to a particular dialer’s handshake::Hello message, preventing exfiltration to a different session.

Encryption

All traffic is encrypted using ChaCha20-Poly1305. A shared secret is established using an ephemeral X25519 Diffie-Hellman key exchange. This secret, combined with the handshake transcript, is used to derive keys for both the handshake’s key confirmation messages and the post-handshake data traffic. Binding the derived keys to the handshake transcript prevents man-in-the-middle and transcript substitution attacks.

Each directional cipher uses a 12-byte nonce derived from a counter that is incremented for each message sent. This counter has sufficient cardinality for over 2.5 trillion years of continuous communication at a rate of 1 billion messages per second—sufficient for all practical use cases. This ensures that well-behaving peers can remain connected indefinitely as long as they both remain online (maximizing p2p network stability). In the unlikely case of counter overflow, the connection will be terminated and a new connection should be established. This method prevents nonce reuse (which would compromise message confidentiality) while saving bandwidth (as there is no need to transmit nonces explicitly).

Security

Requirements

• Pre-Shared Namespace: Peers must agree on a unique, application-specific namespace out-of-band to prevent cross-application replay attacks.
• Time Synchronization: Peer clocks must be synchronized to within the synchrony_bound to correctly validate timestamps.

Provided

• Mutual Authentication: Both parties prove ownership of their static private keys through signatures.
• Forward Secrecy: Ephemeral encryption keys ensure that any compromise of long-term static keys doesn’t expose the contents of previous sessions.
• Session Uniqueness: A listener’s handshake::Hello is bound to the dialer’s handshake::Hello message and handshake::Confirmations are bound to the complete handshake transcript, preventing replay attacks and ensuring message integrity.
• Handshake Timeout: A configurable deadline is enforced for handshake completion to protect against malicious peers that create connections but abandon handshakes.

Not Provided

• Anonymity: Peer identities are not hidden during handshakes from network observers (both active and passive).
• Padding: Messages are encrypted as-is, allowing an attacker to perform traffic analysis.
• Future Secrecy: If a peer’s static private key is compromised, future sessions will be exposed.
• 0-RTT: The protocol does not support 0-RTT handshakes (resumed sessions).

Modules

handshake

Operations over handshake messages.

x25519

Operations over x25519 keys.

Structs

Config

Configuration for a connection.

Connection

A fully initialized connection with some peer.

IncomingConnection

An incoming connection with a verified peer handshake.

Receiver

The half of a Connection that implements crate::Receiver.

Sender

The half of the Connection that implements crate::Sender.