vitaminc_aead_derive/lib.rs
1//! Derive macros for [`vitaminc-aead`](https://docs.rs/vitaminc-aead):
2//! [`Encrypt`] and [`Decrypt`].
3//!
4//! Both are re-exported from `vitaminc_aead`, so depend on that crate
5//! rather than this one:
6//!
7//! ```rust
8//! use vitaminc_aead::{Decrypt, Encrypt};
9//!
10//! #[derive(Encrypt, Decrypt)]
11//! struct User {
12//! name: String,
13//! age: u32,
14//! }
15//! # let user = User { name: "Ada".into(), age: 37 };
16//! # let plan = vitaminc_aead::plan::<_, std::convert::Infallible, _>(user, ()).unwrap();
17//! # assert!(matches!(plan, vitaminc_aead::CipherText::Map(entries) if entries.len() == 2));
18//! ```
19//!
20//! `#[derive(Encrypt)]` walks the struct into a sink as a map with one
21//! entry per field. `#[derive(Decrypt)]` generates the map sink that builds
22//! the struct back, routing each entry to the field's own sink.
23//!
24//! # Installation and compatibility
25//!
26//! Install the parent crate with `cargo add vitaminc-aead`. This macro crate
27//! has no Cargo feature flags and requires Rust <!-- msrv:vitaminc-aead-derive -->**1.89.0**<!-- /msrv -->. The macros run on
28//! the compiler host; the parent crate requires `std`.
29//! MSRV increases require a minor release; patch releases retain the existing
30//! floor. See the [workspace policy](https://github.com/cipherstash/vitaminc#compatibility).
31//!
32//! License: MIT.
33//!
34//! # Wire shape
35//!
36//! A struct is encrypted as a **map**, keyed by field name. This is the
37//! deliberate choice over a sequence: the encrypting sink binds each entry's
38//! key into the AAD its value is sealed against (`Context::for_map_entry`),
39//! so a stored ciphertext cannot have its fields renamed or swapped without
40//! decryption failing. Sequence elements carry no such binding — their AAD
41//! has no positional component — so two same-typed fields encoded as a
42//! sequence would be freely interchangeable.
43//!
44//! The consequences of the map shape:
45//!
46//! - Field **names are part of the ciphertext contract**. Renaming a field is
47//! a wire-breaking change; use `#[aead(rename = "...")]` to keep an old name.
48//! - A derived struct's ciphertext is interchangeable with the equivalent
49//! `HashMap<String, _>` ciphertext, and with a map a host binding wrote.
50//! - Tuple structs of two or more fields use the decimal field index as the
51//! key (`"0"`, `"1"`, …), so they get the same per-field binding.
52//! - A **newtype** struct (exactly one unnamed field) is *transparent*: it
53//! encrypts and decrypts exactly as its inner type, adding nothing to the
54//! ciphertext. This mirrors serde, and matches how `Protected<T>` behaves.
55//! - A unit struct — or a struct with no fields — encrypts to the
56//! authenticated empty-map marker.
57//!
58//! Field values are **not** authenticated in any particular order, so the
59//! derived `Decrypt` reads keys first and matches them to fields. Decoding is
60//! strict: an unknown key, a duplicate key, or a missing field is rejected.
61//!
62//! # Enums
63//!
64//! A **fieldless** enum is one `u32` leaf holding the variant's discriminant:
65//! an explicit `= n`, or one more than the previous variant's, as Rust
66//! assigns them. The leaf is sealed and authenticated like any other, and it
67//! is fixed-width, so the ciphertext's length does not give the variant away
68//! either. Decoding is strict: an int that is no variant's discriminant is
69//! refused. Pin the discriminants with `= n` before storing anything, since
70//! reordering variants otherwise changes them. Variants take no
71//! `#[aead(...)]` attributes.
72//!
73//! Enums with fields are not supported. Their payload has no agreed layout
74//! (internally or externally tagged, per-variant AAD), so model the choice
75//! explicitly, as a struct with a fieldless discriminant and `Option`
76//! fields.
77//!
78// The derive and parent crates release together. Keep parent API links on the
79// version being documented without adding a normal dependency cycle.
80#![deny(missing_docs)]
81#![doc = concat!(
82 "\n[`Encrypt`]: https://docs.rs/vitaminc-aead/", env!("CARGO_PKG_VERSION"),
83 "/vitaminc_aead/trait.Encrypt.html\n",
84 "[`Decrypt`]: https://docs.rs/vitaminc-aead/", env!("CARGO_PKG_VERSION"),
85 "/vitaminc_aead/trait.Decrypt.html\n"
86)]
87#![doc = include_str!("../docs/attributes.md")]
88#![deny(unsafe_code)]
89
90use proc_macro::TokenStream;
91use syn::{parse_macro_input, DeriveInput};
92
93mod attrs;
94mod encrypt;
95mod shape;
96#[cfg(test)]
97mod test_support;
98mod typed_decrypt;
99
100#[doc = concat!("Derive [`Encrypt`](https://docs.rs/vitaminc-aead/",
101 env!("CARGO_PKG_VERSION"), "/vitaminc_aead/trait.Encrypt.html)")]
102/// for a struct or a fieldless enum. See the [crate documentation](crate) for
103/// the wire shape this produces; the attributes it accepts are reproduced
104/// below.
105#[doc = include_str!("../docs/attributes.md")]
106#[proc_macro_derive(Encrypt, attributes(aead))]
107pub fn derive_encrypt(input: TokenStream) -> TokenStream {
108 let input = parse_macro_input!(input as DeriveInput);
109 encrypt::derive(input)
110 .unwrap_or_else(syn::Error::into_compile_error)
111 .into()
112}
113
114#[doc = concat!("Derive [`Decrypt`](https://docs.rs/vitaminc-aead/",
115 env!("CARGO_PKG_VERSION"), "/vitaminc_aead/trait.Decrypt.html)")]
116/// for a struct or a fieldless enum: the sink that builds it. See the
117/// [crate documentation](crate) for the wire shape this consumes; the
118/// attributes it accepts are reproduced below.
119#[doc = include_str!("../docs/attributes.md")]
120#[proc_macro_derive(Decrypt, attributes(aead))]
121pub fn derive_decrypt(input: TokenStream) -> TokenStream {
122 let input = parse_macro_input!(input as DeriveInput);
123 typed_decrypt::derive(input)
124 .unwrap_or_else(syn::Error::into_compile_error)
125 .into()
126}