Skip to main content
Transport TLS protects one hop. End-to-end encryption protects stanza content between the two entity clients, and optional peer-to-peer (P2P) communication can bypass broker data paths for privacy or bandwidth reasons.

​
Publish direct connection data

A device behind an Internet gateway first obtains a local address/port and an externally reachable address/port using an operator-selected mechanism such as UPnP. It publishes both to approved presence subscribers:
Peers sharing the same external address connect to the local endpoint; otherwise they use the external endpoint. Refresh presence whenever the mapping changes.

​
Authenticate the P2P peer

Network location is only a first check. The receiver verifies that the claimed full JID is an approved, present roster contact whose published endpoint matches the incoming address. All P2P stanzas then use E2E protection; the sender’s signature binds the stream claim to its published key. Reject the connection if any check fails. Do not use local-network location as an authentication substitute.

​
End-to-end encryption

E2E uses a hybrid cipher:
  • an asymmetric endpoint publishes a short-lived public key, derives or transports a per-stanza secret, and signs plaintext;
  • a symmetric algorithm encrypts the message or complete IQ payload;
  • the receiver decrypts with its private key and validates the sender signature.
The namespace defines AES-256, ChaCha20, and AEAD ChaCha20-Poly1305 stanza wrappers. Asymmetric families can include RSA, elliptic curves, and supported post-quantum mechanisms. Algorithms are feature-negotiated; implementations must not assume that every peer shares the same set.
Publishing keys in presence avoids a separate handshake before the first encrypted stanza. Keep the current and immediately previous private key during rotation so in-flight messages encrypted to the prior presence can still be processed.

​
Security requirements

  • Generate keys and nonces with a cryptographically secure random source.
  • Rotate asymmetric keys according to data sensitivity and after a session/compromise.
  • Authenticate associated stanza metadata; reject altered sender, recipient, type, or request ID.
  • Reject algorithm downgrade and unadvertised keys.
  • Never reuse a per-stanza symmetric key or nonce.
  • Bound retention of the previous private key.
  • Treat decryption, signature, replay, and recipient failures as hard failures without exposing an oracle.