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.
| Attribute | Applies to | Effect |
|---|---|---|
crate = "path" | container | Name the path to vitaminc_aead in the generated code |
recursive | container | Mark a mutually recursive type, whose depth the derive cannot work out |
rename = "name" | field | Store the field under name instead of its own name |
passthrough | field | Store the field in the clear, unencrypted and unauthenticated |
skip | field | Leave the field out of the ciphertext; rebuild it with Default on decrypt |
take | field | Take 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 valuesA 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
passthroughorskip, 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. passthroughon 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.passthroughwithtake. The field is lent, never taken out ofself, sotakewould 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
Decryptfor 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
Encryptfor a struct or a fieldless enum. See the crate documentation for the wire shape this produces; the attributes it accepts are reproduced below.