@enclave-vm/stream by hand between a client and a server that you write yourself: a key exchange, two session keys, and enc envelopes around the messages.
Overview
The example has two endpoints:POST /handshaketakes aClientHelloand answers with a session id and aServerHello.POST /executetakes oneencenvelope with the code and answers with an NDJSON stream ofencenvelopes.
Messages
The content of an envelope can be any JSON value. This example uses its own small messages:Server
Client
Usage Example
What Is Left to You
The primitives encrypt and authenticate messages between two parties that already share keys. The rest is the application’s work:- Authenticate the key exchange -
ServerHello.signatureB64is neither created nor verified, and there is no key confirmation. Sign the hello messages with a key the client pins, or rely on TLS for the identity of the server. - Authenticate the callers - Both endpoints of the example accept requests from anyone. Protect them like any other API.
- One context per direction -
deriveSessionKeysreturnsclientToServerKeyandserverToClientKey. Never use oneSessionEncryptionContextfor both directions. - Check sequence numbers - An envelope authenticates its sequence number, but the receiver decides whether a number is new. The client above accepts only the next number;
SequenceTrackerkeeps the last number received when gaps are expected. - Exchange keys again when a context is used up - A
SessionEncryptionContextrefuses to encrypt after 2^30 messages (needsRotation()then returnstrue). There is no rotation. - Protect key material -
deriveSessionKeysreturns raw key bytes, and so doescontext.toKeyInfo(). Do not log or store them. - Expire sessions - Remove the keys of sessions that are over, as the server above does.
Next Steps
- @enclave-vm/stream - The encryption primitives
- Security Hardening - More security practices
- Streaming Protocol - Protocol details
- Production Deployment - Deploy securely