Skip to main content

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 object
object
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.
Store private keys securely - Never share or expose your epriv (encryption private key). The shared secret is only secure if both parties protect their private keys.

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

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

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