Documentation
¶
Overview ¶
Package aeadstream is the chunked AES-256-GCM framing, in the STREAM construction, of the v2 upload stream in uploads, factored out so that other encrypted formats in the sdk can share it. It frames chunks and nothing else; each format owns its header, writes it before the chunks, and passes it in as the additional data every chunk authenticates.
Chunk i is sealed under the nonce noncePrefix(7) || uint32 BE i || final(1), where final is 1 only on the last chunk. The index stops a chunk moving within a stream and the flag stops a stream being cut short. Index and flag repeat in every stream, so under a DEK that seals more than one stream only the prefix keeps nonces apart: a caller must draw a fresh random prefix per stream (uploads' package doc gives the bound that buys).
The 4-byte index caps a stream at 2^32 chunks, enforced on both the sealing and the opening side.
Index ¶
Constants ¶
const ( // KeySize is the AES-256 DEK length in bytes. KeySize = 32 // NoncePrefixSize is the per-stream random nonce prefix length in // bytes. The remaining 5 bytes of the 12-byte GCM nonce are the chunk // index and the final-chunk flag. NoncePrefixSize = 7 // ChunkOverhead is the bytes each sealed chunk adds to its plaintext: // the AES-GCM tag. ChunkOverhead = 16 // MaxChunks is the most chunks one stream holds, set by the 4-byte // chunk index in the nonce. The last index is a legal home for the // final chunk. MaxChunks = math.MaxUint32 + 1 // MaxChunkSize bounds the chunk size NewReader honors. A format reads // its chunk size from a header that is unauthenticated until a chunk // opens under it, so an unbounded value would let a hostile stream // name a multi-gigabyte frame. This bounds the frame only; the // reader's buffer tracks the bytes that actually arrive (see // chunkBufGrowth). MaxChunkSize = 16 << 20 )
Variables ¶
This section is empty.
Functions ¶
func NewReader ¶
NewReader returns a reader of the plaintext of the chunks in r, sealed as NewWriter seals them under the same dek, aad, noncePrefix and chunkSize. r must be positioned at the first chunk, past any header.
Read the returned reader to EOF to verify the complete stream. Each chunk authenticates before its plaintext is returned, and modification, deletion, reordering, splicing, a missing final chunk, or the wrong dek or aad causes a read error. Buffers grow with the bytes that arrive rather than with chunkSize, so a chunkSize taken from an unauthenticated header costs nothing until a peer sends that much.
noncePrefix is copied, but aad is retained and must not be modified while the reader is in use. The returned reader is not safe for concurrent use.
func NewWriter ¶
NewWriter returns a writer that seals everything written to it into w as AES-256-GCM chunks of chunkSize plaintext bytes, with aad as every chunk's additional data. It writes nothing itself, so the caller writes its header to w first.
The caller must Close the returned writer to emit the final chunk; a stream whose final chunk is missing does not open. An empty stream still emits one. Close does not close w. Writes after Close fail, as does a stream that would need more than 2^32 chunks.
noncePrefix is copied, but aad is retained and must not be modified while the writer is in use. The returned writer is not safe for concurrent use.
Types ¶
This section is empty.
Source Files