Skip to main content
This example wires the encryption primitives of @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.
Read this before using the example:
  • The EnclaveJS client and broker do not do this. @enclave-vm/client, @enclave-vm/react, @enclave-vm/broker and @enclave-vm/runtime do not encrypt, perform no handshake and have no encryption option. Both endpoints below are your own code.
  • The key exchange is not authenticated. It protects against a party that can only read the connection. A party that can change messages can replace both public keys.
  • The server reads the code. The server you send code to has to decrypt it to run it, and it sees the results. Encryption covers the path between the two endpoints, not the server.
  • TLS is still required. Serve both endpoints over HTTPS. The envelopes are a layer on top of TLS, not a replacement for it.

Overview

The example has two endpoints:
  • POST /handshake takes a ClientHello and answers with a session id and a ServerHello.
  • POST /execute takes one enc envelope with the code and answers with an NDJSON stream of enc envelopes.

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:
  1. Authenticate the key exchange - ServerHello.signatureB64 is 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.
  2. Authenticate the callers - Both endpoints of the example accept requests from anyone. Protect them like any other API.
  3. One context per direction - deriveSessionKeys returns clientToServerKey and serverToClientKey. Never use one SessionEncryptionContext for both directions.
  4. 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; SequenceTracker keeps the last number received when gaps are expected.
  5. Exchange keys again when a context is used up - A SessionEncryptionContext refuses to encrypt after 2^30 messages (needsRotation() then returns true). There is no rotation.
  6. Protect key material - deriveSessionKeys returns raw key bytes, and so does context.toKeyInfo(). Do not log or store them.
  7. Expire sessions - Remove the keys of sessions that are over, as the server above does.

Next Steps