quantum-safe-ts

Appearance

Class: StreamSealer ​

Defined in: stream.ts:129

Low-level sealer: one object per stream. It owns the key and the chunk counter, so a nonce cannot be reused or skipped. Every chunk except the last must be exactly chunkSize bytes; the last may be shorter or empty. Free it (or use using) when done.

Chunk cipher: when the chunk size is 16 KiB or more (NATIVE_AEAD_MIN_BYTES) and the runtime has registered a native AES-256-GCM (Node.js), the chunks are encrypted with it; otherwise the WebAssembly cipher is used. The choice is made once, in StreamSealer.start. Either way the output bytes are the same, and the WebAssembly core stays in charge of the stream: for each chunk it checks that the stream is open and that the length is allowed, issues the nonce from its own counter, and advances the counter only after the chunk is encrypted. The native path holds a copy of the stream key, which StreamSealer.free wipes.

Example ​

ts
using sealer = StreamSealer.start(pair.publicKey, { chunkSize: 4096 });
const first = sealer.seal(chunk, false); // `chunk` is exactly 4096 bytes
const final = sealer.seal(rest, true); // `rest` is 0 to 4096 bytes
// `sealer.header` is what StreamOpener.start needs; `sealStream` adds the magic and the length framing around it.

Implements ​

  • Disposable

Properties ​

chunkSize ​

readonly chunkSize: number

Defined in: stream.ts:135

Plaintext chunk size in bytes.

readonly header: Uint8Array

Defined in: stream.ts:133

The header bytes to send first (the recipient needs them to open the stream).

Methods ​

[dispose]() ​

[dispose](): void

Defined in: stream.ts:189

Calls StreamSealer.free, so the sealer can be declared with using.

Returns ​

void

Implementation of ​

Disposable.[dispose]

free() ​

free(): void

Defined in: stream.ts:184

Wipes the native key copy, if any, and releases the core cipher and its key.

Returns ​

void

seal() ​

seal(plaintext, last?): Uint8Array

Defined in: stream.ts:171

Seals the next chunk; pass last = true for the final one (exactly once). Returns the ciphertext (plaintext length + 16 bytes).

The core checks the length (exactly chunkSize bytes unless last, then 0 to chunkSize) and that the stream is still open. After the last chunk the sealer refuses further calls.

Parameters ​

plaintext ​

Uint8Array

The chunk to seal.

last? ​

boolean = false

True for the final chunk of the stream.

Returns ​

Uint8Array

The ciphertext followed by the 16-byte tag.

Throws ​

if plaintext is not bytes, its length is not allowed, the stream is already finished, or the chunk counter is exhausted.

start() ​

static start(publicKey, options?): StreamSealer

Defined in: stream.ts:153

Starts a stream to publicKey: encapsulates once, derives the stream key and builds the header.

Parameters ​

publicKey ​

PublicKey

The recipient's hybrid KEM key or ML-KEM-1024 key.

options? ​

SealStreamOptions = {}

aad bound to every chunk (default none) and chunkSize (default 65,536 bytes; 1,024 to 16,777,216).

Returns ​

StreamSealer

A sealer; send StreamSealer.header first.

Throws ​

if publicKey is not a PublicKey, chunkSize is not an integer in range, or aad is not bytes.

Throws ​

if the key is not a hybrid KEM key or ML-KEM-1024.

Apache-2.0.