Skip to main content

Module encryption

faucet_stream

Module encryption 

Source
Available on crate feature encryption only.
Expand description

Encryption at rest for faucet-managed local files (#207).

Seals FileStateStore bookmark files and (via the jsonl sink’s encryption feature) per-line JSONL / DLQ output with authenticated encryption, so resume positions and dead-lettered records — which can embed sensitive values — are not stored in plaintext.

§On-disk format (v1)

+---------+--------+-----------+----------------------+
| "FCT1"  | format | nonce     | ciphertext ‖ GCM tag |
| 4 bytes | 1 byte | 12 bytes  | len(plaintext) + 16  |
+---------+--------+-----------+----------------------+
  • Magic FCT1 (“faucet ciphertext v1”) marks a sealed payload; plaintext JSON can never start with these bytes, so is_encrypted is unambiguous.
  • format byte 0x01 = AES-256-GCM. Unknown values are a typed error (never a panic), leaving room for future algorithms.
  • The nonce is random per encryption (never reused across writes).
  • The GCM tag authenticates the payload: any tampering — a flipped bit, truncation, a swapped nonce — fails decryption loudly.

§Keys

The 32-byte AES key is derived as SHA-256(key string) — a derivation, not a stretching KDF: it accepts arbitrary passphrases and hex/base64 strings uniformly, but offers no brute-force hardening, so the key string should be high-entropy material from a secrets manager (${vault:…} / ${aws-sm:…} / ${env:…}), not a human password.

Rotation: writes always seal with key; decryption tries key first and then each entry of previous_keys in order, so a store can be rotated by moving the old key into previous_keys — old files stay readable and are re-sealed with the new key on their next write.

Structs§

CompiledEncryption
A compiled, validated encryption policy: the derived write key plus every derived read key (write key first).
EncryptionSpec
The user-facing encryption: config block (state store / jsonl sink).

Enums§

EncryptionAlgorithm
Supported AEAD algorithms. A single variant today; the format byte in the on-disk header leaves room for more without breaking old files.

Constants§

MAGIC
Magic prefix marking a faucet-sealed payload.

Functions§

is_encrypted
true when data carries the sealed-payload magic. Free function so callers can detect ciphertext without holding a key.