Variable: Envelope
constEnvelope:object
Defined in: envelope.ts:214
Authenticated public-key encryption: hybrid KEM + AES-256-GCM, interoperable with quantum-safe-py's Envelope. A pure ML-KEM-1024 key produces envelope version 2 (HKDF-SHA-384); hybrid keys produce version 1.
Type Declaration
open()
readonlyopen(sealed,secretKey,options?):Uint8Array
Decrypts a sealed message. The returned plaintext is a copy in the JS heap: wipe it with wipe() when it is sensitive and no longer needed.
The AAD travels inside the message and is checked for tampering, but anyone holding the recipient's public key can seal a message with any AAD. To bind a message to a context (a user id, a record id) pass options.expectedAad: opening then fails unless the message's AAD equals it. This is anonymous encryption: it does not tell you who sent the message (sign it separately for that). Without expectedAad, a message that carries AAD triggers a QS_AAD_OMITTED warning.
Parameters
sealed
Uint8Array<ArrayBufferLike> | SealedMessage
A SealedMessage or its CBOR bytes.
secretKey
The recipient's KEM secret key.
options?
expectedAad?
Uint8Array<ArrayBufferLike>
The AAD the message must carry. Default: not checked.
Returns
Uint8Array
The plaintext bytes.
Throws
on a wrong key, wrong AAD, an AAD that differs from expectedAad, or any tampering.
Throws
if the message is structurally invalid.
Throws
if the message algorithm differs from the secret key's.
Throws
if the message carries an unsupported suite or version.
Throws
if secretKey is not a SecretKey or an argument is not a byte array.
rewrap()
readonlyrewrap(sealed,oldSecretKey,newPublicKey,options?):SealedMessage
Moves a message from one recipient key to another: opens sealed under oldSecretKey and seals the plaintext to newPublicKey, keeping the AAD. The original message is not modified, and nothing is returned if opening fails. This is the single step of a migration to a hybrid or stronger key; rewrapDirectory from quantum-safe-ts/rewrap applies it to a directory.
Parameters
sealed
Uint8Array<ArrayBufferLike> | SealedMessage
A SealedMessage or its CBOR bytes.
oldSecretKey
The secret key the message is currently sealed to.
newPublicKey
The public key to seal to: a hybrid key, or a pure ML-KEM-1024 key.
options?
aad?
Uint8Array<ArrayBufferLike>
AAD for the new message. Default: the message's own AAD, unchanged.
expectedAad?
Uint8Array<ArrayBufferLike>
The AAD the message must carry, as for Envelope.open. Omitted: any AAD is accepted (it is authenticated) and a QS_AAD_OMITTED warning is emitted when the message carries AAD.
Returns
A new sealed message; the decrypted plaintext is wiped before returning.
Throws
on a wrong key, an AAD mismatch or any tampering.
Throws
if the message is structurally invalid.
Throws
if the message algorithm differs from oldSecretKey's.
Throws
if the old message or the new key uses an unsupported suite.
Throws
if a key argument has the wrong type.
seal()
readonlyseal(plaintext,publicKey,options?):SealedMessage
Encrypts plaintext to publicKey.
Parameters
plaintext
Uint8Array
The bytes to encrypt.
publicKey
Recipient KEM public key: a hybrid key, or a pure ML-KEM-1024 key.
options?
SealOptions = {}
See SealOptions; aad defaults to empty.
Returns
The sealed message.
Throws
if the key is neither a hybrid KEM key nor a pure ML-KEM-1024 key.
Throws
if publicKey is not a PublicKey or plaintext / aad is not a byte array.
Throws
if the key bytes are invalid.
Example
const kem = new HybridKEM();
using pair = kem.generateKeyPair();
const sealed = Envelope.seal(utf8('secret'), pair.publicKey, { aad: utf8('item-42') });
const plain = Envelope.open(sealed, pair.secretKey); // Uint8Array