ISecretFileProtector

Namespace: Meshmakers.Octo.Runtime.Contracts.Secrets

Encrypts and decrypts files (e.g. tenant dumps taken before a secret sweep) with the instance key ring (AB#5559). Implemented in Runtime.Engine and registered by AddRuntimeEngine(); the key material never leaves the engine.

public interface ISecretFileProtector

Remarks:

Format OCTOENC1 (see docs/secret-sweep-dump-storage.md, "Encrypted dump file format"): a random 256-bit file key per file, wrapped with AES-256-GCM under a key derived with HKDF-SHA256 from the ring key of the active key id; the body is a sequence of AES-256-GCM chunks bound to the header, their index and a final flag, so tampering, truncation and reordering are detected. Both directions stream with memory bounded by the chunk size.

ISecretFileProtector.UnprotectAsync(Stream, Stream, SecretFileContext, CancellationToken) writes the plaintext of every verified chunk before it reads the next one. When it throws, the output holds a prefix of the plaintext and must be discarded.

A key id must stay in the key ring until the newest file encrypted with it has expired; without the key the file is unreadable.

Properties

IsConfigured

True when an active key is configured, i.e. ISecretFileProtector.ProtectAsync(Stream, Stream, SecretFileContext, CancellationToken) can work.

public abstract bool IsConfigured { get; }

Property Value

Boolean

Methods

ProtectAsync(Stream, Stream, SecretFileContext, CancellationToken)

Encrypts plaintext (read to its end) into output with the active key id. Neither stream needs to be seekable; neither is disposed.

Task ProtectAsync(Stream plaintext, Stream output, SecretFileContext context, CancellationToken cancellationToken)

Parameters

plaintext Stream
Clear-text input

output Stream
Receives the encrypted file

context SecretFileContext
Caller, for the metrics

cancellationToken CancellationToken
Cancellation

Returns

Task

Exceptions

SecretEncryptionNotConfiguredException
No active key is configured

UnprotectAsync(Stream, Stream, SecretFileContext, CancellationToken)

Decrypts an encrypted file from input (read to its end) into output. Neither stream needs to be seekable; neither is disposed.

Task UnprotectAsync(Stream input, Stream output, SecretFileContext context, CancellationToken cancellationToken)

Parameters

input Stream
Encrypted file, positioned at its first byte

output Stream
Receives the plaintext; discard it when the call throws

context SecretFileContext
Caller, for the metrics

cancellationToken CancellationToken
Cancellation

Returns

Task

Exceptions

InvalidSecretFileException
Not an encrypted secret file, or tampered, truncated or reordered

UnknownSecretKeyIdException
The file's key id is not in the key ring

SecretEncryptionNotConfiguredException
No keys are configured at all

ReadHeader(Stream)

Reads the clear-text header from input, which is left positioned after the header. Needs no key and does not verify the file's integrity.

SecretFileHeader ReadHeader(Stream input)

Parameters

input Stream
Encrypted file, positioned at its first byte

Returns

SecretFileHeader
The header

Exceptions

InvalidSecretFileException
Not an encrypted secret file (or an unsupported version)

CanUnprotect(SecretFileHeader)

True when the key id of header is in the key ring, i.e. the file can be decrypted (unless it was tampered with).

bool CanUnprotect(SecretFileHeader header)

Parameters

header SecretFileHeader
Header from ISecretFileProtector.ReadHeader(Stream)

Returns

Boolean