Module aes256_cbc_hmac_legacy_stream 

AES-256-CBC-HMAC-Legacy-Stream

Aes256CBC-HMAC-Legacy-Stream is a format for streaming encryption of attachments. It consists of a header, an AES-CBC stream, and a hmac over IV + CBC ciphertext. Because there is just one HMAC over the entire stream, it is not permissible to decrypt a partial portion of this stream, as the integrity of that portion cannot be guaranteed.

Format

The stream looks as follows:

(KEY_E, KEY_A) = KEY
IV | HMAC[KEY_A] (over IV + ciphertext) | AES-CBC[KEY_E]() ciphertext

Limitations

Because the HMAC is written to the start, encryption must be buffered in memory fully before emitting out as an encryption stream, since the HMAC can only be calculated after all ciphertext is produced. This is a limitation to the format.

Further, the HMAC covers the entire stream, not chunks of it, so the entire stream must be fully read before the output is used. IMPORTANT: YOU MUST READ THE ENTIRE STREAM BEFORE USING THE DECRYPTED OUTPUT. This contract cannot be enforced by the interface and requires the correct usage of the caller.

NOTE: The attachments, stored on the server contain a header idicating which format they are encrypted with. This header is NOT included in the stream processed by this file, and is expected to be stripped by the caller before passing the ciphertext to this code.

Random access is not possible with this format, both because of the use of CBC chaining, and because of the single HMAC over the entire cipher stream.

Structs

CbcDecryptor 🔒

CbcEncryptor 🔒

CbcPlaintextBlock 🔒

CiphertextBuffer 🔒

HmacStreamValidator 🔒

A higher level interface over the HMAC validation of the attachment ciphertext

StreamHeader 🔒

StreamingAes256CbcHmacDecryptor

Streaming AES-256-CBC + HMAC-SHA256 decryptor. The HMAC is verified only when StreamingDecryptor::update is called with last_block = true; bytes returned from earlier update calls as ChunkDecryptionResult::DecryptedChunk are decrypted but not yet authenticated and must be treated as untrusted until the terminal ChunkDecryptionResult::FinalDecryptedChunk is observed.

StreamingAes256CbcHmacEncryptor

Streaming AES-256-CBC + HMAC-SHA256 encryptor. The IV is generated at construction time and the HMAC is computed over IV || ciphertext, matching the wire format consumed by StreamingAes256CbcHmacDecryptor. Because the MAC depends on the entire ciphertext, the complete wire stream (IV, ciphertext) is only emitted once update is called with last_block = true, as a single ChunkEncryptionResult::FinalEncryptedChunk.

Enums

DecryptorInitializeWithHeaderError 🔒

DecryptorState 🔒

EncryptorState 🔒

Pkcs7ValidationResult 🔒

Constants

AES256_CBC_BLOCK_SIZE 🔒

AES256_CBC_IV_SIZE 🔒

EMISSION_CHUNK_SIZE 🔒

HEADER_LENGTH 🔒

HMAC_SIZE 🔒

Functions

read_block_ciphertext 🔒

Reads and removes the first block from the buffer. The size must be checked by the caller before calling this function, and it may panic otherwise.

read_header 🔒

read_plaintext_block 🔒

Reads and removes the first block from the buffer. The size must be checked by the caller before calling this function, and it may panic otherwise.

Type Aliases

CbcCiphertextBlock 🔒

Iv 🔒

CBC IV

Mac 🔒

HMAC over IV + Ciphertext

StreamHeaderBytes 🔒

Header is IV || HMAC