crates/veilvoice-crypto/src/aead.rs

Authenticated encryption with XChaCha20-Poly1305.

XChaCha20 rather than plain ChaCha20 because its 192-bit nonce can be drawn at random with no practical collision risk. The 96-bit nonce of RFC 8439 ChaCha20-Poly1305 requires a counter and careful state tracking to stay unique across runs; getting that wrong is catastrophic, and a random 192-bit nonce removes the failure mode entirely.

Every call is authenticated over associated data as well as the plaintext, which is how the container header in crate::container is bound to its ciphertext: flipping a bit in the stored KDF parameters produces a decryption failure rather than a silently different key.

In plain words

This is the encryption itself: it turns a recording into something unreadable, and it can tell whether the result was tampered with afterwards.

Those two jobs go together on purpose. Encryption on its own hides what a file says but does not stop somebody changing it, and a changed file that still decrypts into something is a worse outcome than one that refuses to open. Here, any alteration at all means it will not open, and says so.

WHAT THIS FILE CONTAINS

280 lines defining 5 functions (4 public), 0 types and 2 constants. Everything below is read out of the source, so it cannot disagree with the code.

What happens when it runs. These are the ways in: public, and nothing else in this file calls them, so they are what an outside caller reaches first.

• random_nonce line 35 · Draw a fresh random nonce from the OS CSPRNG.
• seal line 55 · Encrypt plaintext, authenticating aad alongside it.
  reaches cipher
• open line 74 · Decrypt and verify.
  reaches cipher
• open_secret line 121 · Decrypt and verify into protected memory, never into an ordinary Vec.
  reaches cipher

WHAT CALLS WHAT

The functions this file defines, and the calls between them. An edge means the callee's name appears, called, inside the caller's body. This is a syntactic reading, not a type-resolved one.

%%{init: {"theme":"base","themeVariables":{"background":"#1a1b26","primaryColor":"#1f2335","primaryTextColor":"#c0caf5","primaryBorderColor":"#7aa2f7","secondaryColor":"#16161e","tertiaryColor":"#16161e","lineColor":"#737aa2","textColor":"#c0caf5","mainBkg":"#1f2335","nodeBorder":"#7aa2f7","clusterBkg":"#16161e","clusterBorder":"#2f3549","fontFamily":"ui-monospace, SFMono-Regular, Consolas, monospace","fontSize":"14px"}}}%%
flowchart TD
    n_random_nonce(["random_nonce<br/>line 35"])
    n_cipher["cipher<br/>line 45"]
    n_seal(["seal<br/>line 55"])
    n_open(["open<br/>line 74"])
    n_open_secret(["open_secret<br/>line 121"])
    n_open --> n_cipher
    n_open_secret --> n_cipher
    n_seal --> n_cipher
    click n_random_nonce href "https://github.com/tilas01/veilvoice/blob/main/crates/veilvoice-crypto/src/aead.rs#L35" "open the source"
    click n_cipher href "https://github.com/tilas01/veilvoice/blob/main/crates/veilvoice-crypto/src/aead.rs#L45" "open the source"
    click n_seal href "https://github.com/tilas01/veilvoice/blob/main/crates/veilvoice-crypto/src/aead.rs#L55" "open the source"
    click n_open href "https://github.com/tilas01/veilvoice/blob/main/crates/veilvoice-crypto/src/aead.rs#L74" "open the source"
    click n_open_secret href "https://github.com/tilas01/veilvoice/blob/main/crates/veilvoice-crypto/src/aead.rs#L121" "open the source"
    classDef entry fill:#1f2335,stroke:#7aa2f7,color:#c0caf5
    class n_random_nonce,n_seal,n_open,n_open_secret entry
    classDef helper fill:#1f2335,stroke:#bb9af7,color:#c0caf5
    class n_cipher helper

ITEMS