Skip to main content

Crate vitaminc_aead_derive

Crate vitaminc_aead_derive 

Source
Expand description

Derive macros for vitaminc-aead: Encrypt and Decrypt.

Both are re-exported from vitaminc_aead, so depend on that crate rather than this one:

use vitaminc_aead::{Decrypt, Encrypt};

#[derive(Encrypt, Decrypt)]
struct User {
    name: String,
    age: u32,
}

#[derive(Encrypt)] walks the struct into a sink as a map with one entry per field. #[derive(Decrypt)] generates the map sink that builds the struct back, routing each entry to the field’s own sink.

§Installation and compatibility

Install the parent crate with cargo add vitaminc-aead. This macro crate has no Cargo feature flags and requires Rust 1.89.0. The macros run on the compiler host; the parent crate requires std. MSRV increases require a minor release; patch releases retain the existing floor. See the workspace policy.

License: MIT.

§Wire shape

A struct is encrypted as a map, keyed by field name. This is the deliberate choice over a sequence: the encrypting sink binds each entry’s key into the AAD its value is sealed against (Context::for_map_entry), so a stored ciphertext cannot have its fields renamed or swapped without decryption failing. Sequence elements carry no such binding — their AAD has no positional component — so two same-typed fields encoded as a sequence would be freely interchangeable.

The consequences of the map shape:

  • Field names are part of the ciphertext contract. Renaming a field is a wire-breaking change; use #[aead(rename = "...")] to keep an old name.
  • A derived struct’s ciphertext is interchangeable with the equivalent HashMap<String, _> ciphertext, and with a map a host binding wrote.
  • Tuple structs of two or more fields use the decimal field index as the key ("0", "1", …), so they get the same per-field binding.
  • A newtype struct (exactly one unnamed field) is transparent: it encrypts and decrypts exactly as its inner type, adding nothing to the ciphertext. This mirrors serde, and matches how Protected<T> behaves.
  • A unit struct — or a struct with no fields — encrypts to the authenticated empty-map marker.

Field values are not authenticated in any particular order, so the derived Decrypt reads keys first and matches them to fields. Decoding is strict: an unknown key, a duplicate key, or a missing field is rejected.

§Enums

A fieldless enum is one u32 leaf holding the variant’s discriminant: an explicit = n, or one more than the previous variant’s, as Rust assigns them. The leaf is sealed and authenticated like any other, and it is fixed-width, so the ciphertext’s length does not give the variant away either. Decoding is strict: an int that is no variant’s discriminant is refused. Pin the discriminants with = n before storing anything, since reordering variants otherwise changes them. Variants take no #[aead(...)] attributes.

Enums with fields are not supported. Their payload has no agreed layout (internally or externally tagged, per-variant AAD), so model the choice explicitly, as a struct with a fieldless discriminant and Option fields.

§Attributes

All options live under #[aead(...)]. Anything else — a misspelling included — is a compile error rather than a silently dropped setting, because a dropped option is one the author believes is in effect.

AttributeApplies toEffect
crate = "path"containerName the path to vitaminc_aead in the generated code
recursivecontainerMark a mutually recursive type, whose depth the derive cannot work out
rename = "name"fieldStore the field under name instead of its own name
passthroughfieldStore the field in the clear, unencrypted and unauthenticated
skipfieldLeave the field out of the ciphertext; rebuild it with Default on decrypt
takefieldTake the value with mem::take instead of moving it, for a type that implements Drop

Enum variants take no attributes.

§#[aead(crate = "...")]

Points the generated code at a re-export of vitaminc_aead, for callers who depend on it through an umbrella crate rather than directly:

use vitaminc::aead::{Decrypt, Encrypt};

#[derive(Encrypt, Decrypt)]
#[aead(crate = "::vitaminc::aead")]
struct User {
    name: String,
}

Every path the expansion emits is redirected, so the deriving crate needs no direct dependency on vitaminc_aead at all.

§#[aead(recursive)]

#[derive(Encrypt)] works out how deeply a type nests, from its fields, and fails to compile a type deeper than MAX_DEPTH, whose fully populated values the encrypting sink would always refuse:

error[E0080]: evaluation panicked: `TooDeep` nests deeper than `MAX_DEPTH` levels, so
              the encrypting sink would refuse its fully populated values

A recursive type has no fixed depth: a tree can be as deep as its data. For a type that names itself in a field, directly or as Self, the derive sees this and leaves the check to the walk, which refuses a value that is too deep when it is encrypted:

use vitaminc_aead::{Decrypt, Encrypt};

#[derive(Encrypt, Decrypt)]
struct Tree {
    label: String,
    children: Vec<Tree>, // detected: no attribute needed
}

This example checks recursive encoding. Decoding this Tree with Frame::visit(Tree::sink()) currently hits a compiler recursion limit.

The derive looks for the type’s bare name. A field that names the type through a path, such as crate::models::Tree, is read as another type with the same name (db::User inside a User is common), so it is not detected.

Recursion through another type, or through a path, cannot be seen from one derive, and fails to compile with error[E0391]: cycle detected when simplifying constant, naming each type’s DEPTH. Mark every type in the cycle recursive:

use vitaminc_aead::{Decrypt, Encrypt};

#[derive(Encrypt, Decrypt)]
#[aead(recursive)]
struct Even {
    next: Vec<Odd>,
}

#[derive(Encrypt, Decrypt)]
#[aead(recursive)]
struct Odd {
    next: Vec<Even>,
}

A type that contains a recursive type is not checked either, since its depth depends on the recursive part. A generic type is checked once it is used at a concrete type, under cargo build rather than cargo check.

§#[aead(rename = "...")]

Changes the map key a field is stored under:

use vitaminc_aead::{Decrypt, Encrypt};

#[derive(Encrypt, Decrypt)]
struct User {
    #[aead(rename = "n")]
    name: String,
}
// ciphertext: Map { "n": … }

Field names are part of the ciphertext contract — each key is bound into the AAD its value is sealed against — so renaming a field in Rust breaks compatibility with data already stored under the old name. rename is how you keep the old wire key while changing the Rust one.

Two fields cannot share a key; the collision is a compile error rather than a value silently overwriting another. rename on a newtype is a compile error too: a newtype is transparent, so its value is not stored under a key at all and there is nothing to rename.

§#[aead(passthrough)]

Stores a field as a cleartext map entry, so it can be an ordinary database column that other queries select, filter, and update without holding the key:

use vitaminc_aead::{Decrypt, Encrypt};

#[derive(Encrypt, Decrypt)]
struct Row {
    #[aead(passthrough)]
    tenant: String,   // a plain column
    ssn: String,      // encrypted
}

§⚠️ The field gives up all protection

That independence is bought by giving up everything, and the trade is total:

  • The value is not encrypted — anyone who can read the stored ciphertext can read it.
  • The value is not authenticated. No tag covers it, and unlike an encrypted entry’s key, nothing binds its key either. It can be edited, retargeted at another key, added, or removed, and every encrypted field beside it still decrypts. Treat what comes back as untrusted input — it is exactly as trustworthy as the column it was read from.
  • Deleting the entry is caught only by the ordinary missing-field rule, and is not distinguished from a value that was never written.

So: non-sensitive, non-security-deciding data only. Never a field the program then trusts to make an authorization choice.

A cleartext field that must be tamper-evident needs to be bound into the AAD instead of passed through — and note that binding couples the two, so any independent write to that column would break decryption of every encrypted field beside it. That coupling is precisely what passthrough exists to avoid.

§Requirements

A passthrough field’s type is lent on the way in, never copied or moved, even when the struct itself is walked by value: it implements Encrypt for a reference to it (EncryptRef), as every built-in source and derived struct does, and need be neither Clone nor a source by value. A type parameter that only passthrough fields name is bounded on EncryptRef alone. A sink that is really several sinks lends each the same subtree. On the way out it implements Decrypt. Because the field is only lent, it needs no #[aead(take)] on a type that implements Drop.

These are rejected at compile time:

  • Nothing sealed. If every field is passthrough or skip, nothing would be encrypted, so the ciphertext would carry no tag at all — neither the associated data nor the entry keys would be authenticated. The encrypting sink refuses to seal such a container, so the derive refuses to emit one.
  • passthrough on a newtype. A newtype is transparent and opens no map, so there is no entry to store in the clear; honouring the attribute would mean the whole value travelled unencrypted.
  • passthrough with take. The field is lent, never taken out of self, so take would have no effect.

§#[aead(skip)]

Leaves a field out of the ciphertext altogether, for data that lives somewhere else, such as an ordinary column alongside the ciphertext, or a value derived from the others:

use vitaminc_aead::{Decrypt, Encrypt};

#[derive(Encrypt, Decrypt)]
struct User {
    #[aead(skip)]
    id: u64,          // not in the ciphertext at all
    password: String, // encrypted
}

On encrypt the field contributes nothing: no entry, no key binding, and it is not counted in the map’s length. On decrypt it is rebuilt with Default::default(), so its type must implement Default. The strict decode rules treat a skipped field as never present: an entry that does turn up under its key is refused as an unknown key.

Adding skip to a new field is not a wire-breaking change, since the field is simply absent from the map. Changing a field that was sealed to skip is.

skip cannot be combined with passthrough or take, and is a compile error on a newtype, whose only field is the whole value.

§#[aead(take)]

A struct that implements Drop, such as one that derives ZeroizeOnDrop, cannot be destructured, so its fields cannot be moved out to be walked. take swaps the field for its default with core::mem::take instead, and the empty value left behind is dropped, and wiped, with self:

use vitaminc_aead::{Decrypt, Encrypt};
use zeroize::ZeroizeOnDrop;

#[derive(Encrypt, Decrypt, ZeroizeOnDrop)]
struct SecretToken(#[aead(take)] String);

The field’s type must implement Default. Every encrypted field of a Drop type that is not Copy needs it. A passthrough field does not: it is lent to the sink in place, never moved out of self, so take on it is a compile error. A Protected<T> field has no Default and needs no take: it wipes itself, so a struct whose secrets are all Protected does not need ZeroizeOnDrop in the first place. take only affects how the value leaves self; the ciphertext is the same with or without it.

§Field types and visibility

The sink-based Decrypt derive generates a sink type beside the struct, with the struct’s visibility, whose public associated types name each field’s type. A field’s type therefore has to be at least as visible as the struct, or the derive fails with E0446 (“private type in public interface”). A type that should stay unreachable from outside can be declared pub inside a private module; it is then visible enough for the derive and still not nameable by other crates.

Derive Macros§

Decrypt
Derive Decrypt for a struct or a fieldless enum: the sink that builds it. See the crate documentation for the wire shape this consumes; the attributes it accepts are reproduced below.
Encrypt
Derive Encrypt for a struct or a fieldless enum. See the crate documentation for the wire shape this produces; the attributes it accepts are reproduced below.