PqStreamingEnvelope class abstract final

Pure framing for the .pqfs streaming envelope.

Everything security-relevant — header serialization, per-frame nonce and AAD derivation, and the AEAD seal/open of a single frame — lives here and is unit-testable without touching the filesystem. The sequential file/stream plumbing (and the KEM, signing, and AAD policy) lives in the dart:io streaming service.

Container layout

"PQFS" | uint32 formatVersion
       | uint32 headerCoreLen | headerCore
       | uint32 signatureLen  | signature        (signatureLen 0 = unsigned)
       | frame*
frame  = uint32 bodyLen | uint64 seq | uint8 isFinal | body(ciphertext‖tag)

• nonce = nonceSalt(4B) ‖ uint64(seq) — unique under the per-file DEM key.
• aad = SHA-256(headerCore) ‖ uint64(seq) ‖ uint8(isFinal) — binds every frame to the header and makes truncation, reordering, duplication, and splicing forgery-proof.

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

buildFrameHeader({required int bodyLen, required int seq, required bool isFinal}) → Uint8List

Builds a frame's bodyLen | seq | isFinal header.

frameAad(Uint8List headerHash, int seq, bool isFinal) → Uint8List

SHA-256(headerCore) ‖ uint64(seq) ‖ uint8(isFinal).

frameNonce(Uint8List nonceSalt, int seq) → Uint8List

nonceSalt ‖ uint64(seq) — a 12-byte AEAD nonce, unique per frame under the per-file DEM key.

openFrameBody({required PqForgeAeadEngine engine, required Uint8List demKey, required Uint8List headerHash, required Uint8List nonceSalt, required int seq, required bool isFinal, required Uint8List body}) → Future<Uint8List>

Opens one frame body back to plaintext, authenticating its position.

parseFrameHeader(Uint8List header) → ({int bodyLen, bool isFinal, int seq})

Parses a frame's bodyLen | seq | isFinal header.

parseHeaderCore(Uint8List bytes) → PqStreamingHeader

Parses canonical headerCore bytes back into a PqStreamingHeader.

sealFrameBody({required PqForgeAeadEngine engine, required Uint8List demKey, required Uint8List headerHash, required Uint8List nonceSalt, required int seq, required bool isFinal, required Uint8List plaintext}) → Future<Uint8List>

Seals one plaintext frame, returning its ciphertext‖tag body.

serializeHeaderCore(PqStreamingHeader header) → Uint8List

Serializes header to its canonical, signed headerCore bytes.

signatureContext() → Uint8List

Domain-separation context for the (optional) header signature.

Constants

defaultFrameSize → const int

Default frame size (1 MiB) — the resident working set is a small multiple of this, independent of total file length.

formatVersion → const int

Container format version.

frameHeaderBytes → const int

uint32 bodyLen + uint64 seq + uint8 isFinal.

magic → const String

Container magic; also distinguishes a streaming file from a one-shot envelope (whose toBinary() begins with the bytes 00 00 00 04).

maxFrameCount → const int

Maximum frames per container: the NIST SP 800-38D guidance of at most 2³² GCM invocations under one key. At the default 1 MiB frame size this caps a single container at 4 PiB.

maxFrameSize → const int

Hard cap on a frame's plaintext size, enforced on read so a malicious header/frame can never force an unbounded allocation.

maxHeaderCoreBytes → const int

Hard cap on the serialized header (KEM ciphertext + metadata JSON), enforced on read before allocating — the same anti-DoS bound as maxFrameSize but for the container header.

nonceSaltBytes → const int

Random per-file nonce-salt length, prefixed to the frame counter.