Class: StreamOpener
Defined in: stream.ts:215
Low-level opener: feed the ciphertext of each chunk in order, saying whether it is the last one. A failure ends the stream.
Chunk cipher: as for StreamSealer, a chunk size of 16 KiB or more on a runtime with a registered native AES-256-GCM (Node.js) uses it, and otherwise the WebAssembly cipher is used; the choice is made once, in StreamOpener.start. In both cases the core checks the ciphertext length and the stream state, owns the counter and issues the nonce. When the native cipher reports an authentication failure, the core opens the same chunk itself, so the error comes from the core and the stream ends exactly as it does on the WebAssembly path. The native path holds a copy of the stream key, which StreamOpener.free wipes.
Example
using opener = StreamOpener.start(pair.secretKey, header);
const plain = opener.open(ciphertext, true); // a single-chunk streamImplements
Disposable
Properties
chunkSize
readonlychunkSize:number
Defined in: stream.ts:219
Plaintext chunk size in bytes, read from the stream header.
Methods
[dispose]()
[dispose]():
void
Defined in: stream.ts:279
Calls StreamOpener.free, so the opener can be declared with using.
Returns
void
Implementation of
Disposable.[dispose]
free()
free():
void
Defined in: stream.ts:274
Wipes the native key copy, if any, and releases the core cipher and its key.
Returns
void
open()
open(
ciphertext,last):Uint8Array
Defined in: stream.ts:260
Opens the next chunk.
last must be true exactly for the final chunk: it is part of the nonce, so a stream cut short fails authentication. A ciphertext of a length the core does not allow ends the stream.
Parameters
ciphertext
Uint8Array
One chunk's ciphertext and tag: exactly chunkSize + 16 bytes, or 16 to chunkSize + 16 bytes for the last chunk.
last
boolean
True when this is the final chunk.
Returns
Uint8Array
The plaintext of the chunk.
Throws
if it was modified, reordered, dropped, truncated, or the key or AAD is wrong.
Throws
if the ciphertext length is not allowed for this chunk.
Throws
if ciphertext is not bytes or the stream has already ended.
start()
staticstart(secretKey,header,options?):StreamOpener
Defined in: stream.ts:239
Starts opening a stream: parses and validates the header, decapsulates, and derives the stream key.
Parameters
secretKey
The recipient's KEM secret key.
header
Uint8Array
The header bytes (the CBOR after the magic and length field), at most 65,536 bytes.
options?
OpenStreamOptions = {}
expectedAad, the associated data the sender used (default none).
Returns
StreamOpener
An opener ready for the first chunk.
Throws
if secretKey is not a SecretKey, or header or expectedAad is not bytes.
Throws
if the header is longer than 65,536 bytes or is not a valid stream header.
Throws
if the header's algorithm differs from the key's.
Throws
if the header names an algorithm that streams do not support.