Overview
SEA.secret() creates a shared secret between two users using Elliptic Curve Diffie-Hellman (ECDH) key exchange. This enables two parties to communicate securely without exchanging encryption keys over the network.
Syntax
Parameters
string | object
required
The other user’s public encryption key (
epub) or their full key pair objectobject
required
Your key pair object containing
epub and epriv (encryption keys)function
Optional callback function called with the derived secret
object
Optional configuration object
Returns
A Promise that resolves to a base64-encoded shared secret string that both parties can use for encryption/decryption.How it works
From~/workspace/source/sea/secret.js:1:
ECDH key exchange
1
Alice generates her key pair
Alice creates her public/private encryption key pair using
SEA.pair()2
Bob generates his key pair
Bob also creates his own public/private encryption key pair
3
Exchange public keys
Alice and Bob exchange only their public encryption keys (epub)
4
Derive shared secret
Both parties use
SEA.secret() to derive the same shared secret:- Alice:
SEA.secret(bob.epub, alice) - Bob:
SEA.secret(alice.epub, bob)
5
Encrypt/decrypt messages
Both can now encrypt and decrypt messages using the shared secret
Basic usage
Generate shared secret
Encrypted messaging
End-to-end encrypted chat
Private data sharing
Security properties
Perfect Forward Secrecy - Each key pair generates a unique shared secret. Compromising one secret doesn’t affect others.
No key exchange required - Public keys can be shared openly. Only the private keys must remain secret.
Technical details
Cryptographic algorithm
- Key exchange: ECDH (Elliptic Curve Diffie-Hellman)
- Curve: P-256 (secp256r1)
- Derived key: AES-GCM 256-bit
- Output: Base64-encoded JWK key material
Key format
The derived secret is a base64-encoded string representing the symmetric encryption key:Use cases
Private messaging
End-to-end encrypted chat between two users
File sharing
Share encrypted files with specific recipients
Collaborative editing
Share documents encrypted for specific collaborators
Peer-to-peer sync
Sync private data between user’s devices
Common patterns
Group encryption
Key caching
Troubleshooting
Different secrets generated
Why are my derived secrets different?
Why are my derived secrets different?
Ensure both parties are using the correct public keys:Common mistakes:
- Using the wrong public key (pub vs epub)
- Using signing keys instead of encryption keys
- Key pair not fully generated before deriving secret
Decryption fails
Why can't I decrypt the message?
Why can't I decrypt the message?
Verify the shared secret matches:If secrets don’t match:
- Check that public keys were exchanged correctly
- Ensure key pairs are complete (have both epub and epriv)
- Verify no corruption during key transmission
See also
SEA.pair()
Generate key pairs for ECDH
SEA.encrypt()
Encrypt data with shared secret
SEA.decrypt()
Decrypt data with shared secret
User Authentication
Authenticate users to access key pairs