Strong cryptography depends on more than choosing a secure algorithm. Keys need sufficient randomness, secrets need careful handling, and encrypted data needs to be bound to the context in which it is used. Getting these details wrong can undermine the guarantees of the underlying primitives.
Vitamin C is a suite of Rust crates that makes these details easier to get right. It provides components for protecting secret values, generating cryptographic randomness, handling keys and passwords, encrypting structured values, and encoding cryptographic context unambiguously. It builds on libraries such as Subtle, Zeroize, and RustCrypto, with types and APIs designed to prevent misuse. The goal is to make invalid states and configurations fail to compile wherever possible. This matters even more when code is written by AI.
Developed at CipherStash, Vitamin C is open source and in active development toward 1.0.
Use individual crates for the capabilities you need, or enable them through the top-level vitaminc crate.
Feedback and contributions are welcome.
The top-level crate is a facade: it re-exports most of the other crates, each behind a feature.
- Design goals
- Choose a crate
- Installation and usage
- Examples
- Supporting crates
- Compatibility
vitaminccrate features- Escape hatches - use with care!
- Misuse resistant: make the secure way the easy way. Make types and APIs reject invalid use at compile time wherever they can.
- Verified: test with property tests, mutation tests, and fuzzing. Use formal methods where practical. Prefer dependencies that are verified.
- Vetted: write code that security experts can review. Prefer dependencies that experts have reviewed.
- Minimal: include only what is necessary. Put optional parts behind features.
- Consistent: give the crates interfaces that work together.
- Compatible: support native and WebAssembly applications.
Embedded (
no_std) support is a future goal. Every crate requiresstdtoday. - Fast: keep the code fast, without making it less secure.
Most applications need only these crates.
The "Facade feature" column names the vitaminc feature that enables each crate.
You can also add each crate as its own dependency.
The supporting crates are listed after the examples.
| Crate | Purpose | Facade feature | Links |
|---|---|---|---|
vitaminc |
Use the other crates through one dependency, with a feature for each crate. The facade enables no features by default. | Not applicable | crates.io · docs.rs |
vitaminc-protected |
Wrap secret values. Debug output hides them, code must call a named method to read them, and they are wiped (overwritten with zeros) when dropped. | protected |
crates.io · docs.rs |
vitaminc-password |
Generate passwords with safe default lengths, and keep them protected. | password |
crates.io · docs.rs |
vitaminc-random |
Generate cryptographically secure random values, including random values of your own types. | random |
crates.io · docs.rs |
vitaminc-encrypt |
Encrypt and decrypt Rust values with AES-256-GCM. Keys stay protected, and the crate generates each nonce for you. | encrypt |
crates.io · docs.rs |
You can add Vitamin C in two ways:
- Add the
vitamincfacade, and enable a feature for each crate you need. - Add each crate you need as its own dependency.
Both ways give you the same types and APIs. Only the dependency declarations and the import paths differ. You can use both ways in one project.
The facade enables no features by default. Enable a feature for each crate you need:
cargo add vitaminc --features protectedEach feature adds a module to the facade, such as vitaminc::protected for the protected feature.
Import from that module:
use vitaminc::protected::{Controlled, Protected};
let mut token = Protected::new(String::from("example-token"));
token.update(|value| value.push_str("-updated"));
let debug = format!("{token:?}");
assert!(debug.contains("***"));
assert!(!debug.contains("example-token"));Protected hides its contents in debug output.
Protected also wipes its contents when it is dropped.
To enable more than one crate, separate the features with commas:
cargo add vitaminc --features protected,random,encryptThese features add the modules vitaminc::protected, vitaminc::random, and vitaminc::encrypt.
Add each crate you need:
cargo add vitaminc-protectedIn Rust imports, write the crate name with underscores in place of hyphens. The same example becomes:
use vitaminc_protected::{Controlled, Protected};
let mut token = Protected::new(String::from("example-token"));
token.update(|value| value.push_str("-updated"));
let debug = format!("{token:?}");
assert!(debug.contains("***"));
assert!(!debug.contains("example-token"));Add other crates the same way.
For example, add vitaminc-random and vitaminc-encrypt, and import them as vitaminc_random and vitaminc_encrypt.
Even when you use the facade, you need a direct dependency for these:
- The
vitaminc-aead-frameandvitaminc-aead-napicrates. The facade does not currently include them. - Crate features such as
hlist,jiff, andbitvec. Enable them on the crate that defines them, because the facade does not pass them on. - Some derive macros. A derive macro can need a direct dependency on the crate that re-exports it. Each crate's setup guide says whether its macros need one.
Each example starts with the cargo add commands it needs, and runs on its own.
Most examples import the crates directly.
The password example also shows the facade.
To protect a secret type that you define, derive these traits:
OpaqueDebug, fromvitaminc-protected, hides the contents in debug output.TimingSafeEq, fromvitaminc-protected, compares contents of equal length without stopping at the first byte that differs.ZeroizeandZeroizeOnDrop, from the Zeroize crate, wipe the contents.
cargo add vitaminc-protected
cargo add zeroize --features deriveuse vitaminc_protected::{OpaqueDebug, TimingSafeEq};
use zeroize::{Zeroize, ZeroizeOnDrop};
#[derive(OpaqueDebug, TimingSafeEq, Zeroize, ZeroizeOnDrop)]
struct ApiToken(String);
// These values are fixed for this example. Generate real tokens with SafeRand, as shown below.
let token = ApiToken("sk-ant-api03-M_qo...".to_string());
let same = ApiToken("sk-ant-api03-M_qo...".to_string());
let different = ApiToken("sk-ant-api04-M_an...".to_string());
println!("{token:?}"); // Prints the type name, with "***" in place of the contents.
assert_eq!(token, same);
assert_ne!(token, different);
assert!(bool::from(token.ts_eq(&same)));The Zeroize derive adds a .zeroize() method.
Call .zeroize() to wipe the fields.
The ZeroizeOnDrop derive adds a destructor that wipes the fields when the value is dropped.
The timing protection depends on the field types. Two strings of equal length are compared in constant time, so the time taken does not depend on their contents. A string's length and an enum's variant are not treated as secrets.
To protect a value of an existing type, such as String, wrap it in Protected.
To compare protected values, use Equatable.
Both wrappers hide their contents in debug output, and wipe them when dropped.
cargo add vitaminc-protectedComparing two Protected values with == does not compile.
The compile error stops you from comparing secrets with the inner type's ordinary comparison by mistake:
use vitaminc_protected::Protected;
let expected = Protected::new(*b"demo");
let supplied = Protected::new(*b"demo");
let matches = expected == supplied; // Error: Protected does not implement PartialEq.To compare protected values, wrap them in Equatable.
Equatable uses the constant-time comparison of the inner type.
This version compiles:
use vitaminc_protected::{Controlled, Equatable, Protected};
let mut secret = Protected::new(String::from("example-token"));
secret.update(|text| text.make_ascii_uppercase());
println!("{secret:?}"); // Debug output hides the contents.
let expected: Equatable<Protected<[u8; 4]>> = Equatable::new(*b"demo");
let supplied: Equatable<Protected<[u8; 4]>> = Equatable::new(*b"demo");
assert_eq!(expected, supplied);The wrappers do not implement Deref.
To change a value inside its wrapper, call update.
This example generates a password with a safe default length, from a generator seeded by the operating system. The example then converts the password to a protected string for your application to use:
cargo add vitaminc-passworduse vitaminc_password::{AlphaNumericPassword, Protected};
let password = AlphaNumericPassword::generate().expect("password generation failed");
assert_eq!(password.len(), 22); // The length is not secret. The characters stay protected.
let text: Protected<String> = password.into_protected_string();
println!("{text:?}"); // Debug output does not show the password.Each password type has a default length that gives more than 128 bits of entropy, when the generator is securely seeded:
| Password type | Characters | Default length |
|---|---|---|
Password |
Printable ASCII | 20 |
AlphaNumericPassword |
Letters and digits | 22 |
AlphaPassword |
Letters | 23 |
Each default length is also the minimum length.
If you set a shorter length, the build fails.
To generate longer passwords, or many passwords at once, use Generatable::random.
The password guide explains how, in Longer passwords and batches.
Converting a password to a protected string wipes the original characters. The protected string is wiped when it is dropped.
To use the facade instead, enable its password feature.
The password feature also enables protected and random:
cargo add vitaminc --features passworduse vitaminc::password::AlphaNumericPassword;
let password = AlphaNumericPassword::generate().expect("password generation failed");
let text = password.into_protected_string();
println!("{text:?}");To generate random values of your own structs, derive Generatable.
Every field must implement Generatable.
Protected<[u8; 32]> implements Generatable, so protected fields work too.
You get the derive macro from vitaminc-random:
cargo add vitaminc-random vitaminc-protecteduse vitaminc_protected::Protected;
use vitaminc_random::{Generatable, SafeRand};
#[derive(Generatable)]
struct ApiToken {
bytes: Protected<[u8; 32]>,
}
let mut rng = SafeRand::from_entropy().expect("system entropy unavailable");
let secret: Protected<[u8; 32]> = Generatable::random(&mut rng).expect("generation failed");
// The derived implementation generates each field with the RNG you pass in.
let token = ApiToken::random(&mut rng).expect("generation failed");
println!("{secret:?}");
println!("{:?}", token.bytes); // Debug output hides the contents of protected fields.For real secrets, seed the generator from the operating system, as SafeRand::from_entropy does.
A fixed seed is useful in tests, because a test then generates the same values each time.
Anyone who knows the seed can generate those values too.
This example generates a protected 256-bit key, and encrypts a value with AES-256-GCM.
vitaminc-encrypt generates the nonce for each encryption.
You also supply a context, such as a tenant and a field name.
Decryption fails unless you supply the same context:
cargo add vitaminc-encrypt vitaminc-random vitaminc-protecteduse vitaminc_encrypt::{decrypt, encrypt, Aes256Cipher, Key};
use vitaminc_protected::Protected;
use vitaminc_random::{Generatable, SafeRand};
let mut rng = SafeRand::from_entropy().expect("system entropy unavailable");
let key = Key::random(&mut rng).expect("key generation failed");
let cipher = Aes256Cipher::new(&key).expect("cipher creation failed");
let context = "tenant:42/api-token";
let secret = Protected::new(String::from("example-token"));
let ciphertext = encrypt(&secret, &cipher, context).expect("encryption failed");
let recovered: Protected<String> =
decrypt(&cipher, ciphertext, context).expect("decryption failed");
println!("{recovered:?}"); // The decrypted value is also protected.
let ciphertext = encrypt(&secret, &cipher, context).expect("encryption failed");
let wrong_context: Result<Protected<String>, _> =
decrypt(&cipher, ciphertext, "tenant:99/api-token");
assert!(wrong_context.is_err());The context is used as associated data. Encryption authenticates the context, but does not encrypt it. Use a stable, unambiguous identifier as the context. Supply the same context when you decrypt.
To encrypt a struct, derive Encrypt and Decrypt.
You do not need to serialize the struct first, or take its protected fields out of their wrappers:
cargo add vitaminc-aead vitaminc-encrypt vitaminc-random vitaminc-protecteduse vitaminc_aead::{Decrypt, Encrypt};
use vitaminc_encrypt::{decrypt, encrypt, Aes256Cipher, Key};
use vitaminc_protected::Protected;
use vitaminc_random::{Generatable, SafeRand};
#[derive(Encrypt, Decrypt)]
struct Credential {
label: String,
token: Protected<String>,
}
let mut rng = SafeRand::from_entropy().expect("system entropy unavailable");
let key = Key::random(&mut rng).expect("key generation failed");
let cipher = Aes256Cipher::new(&key).expect("cipher creation failed");
let credential = Credential {
label: String::from("deployment"),
token: Protected::new(String::from("example-token")),
};
let ciphertext = encrypt(&credential, &cipher, "tenant:42/credential")
.expect("encryption failed");
let recovered: Credential = decrypt(&cipher, ciphertext, "tenant:42/credential")
.expect("decryption failed");
assert_eq!(recovered.label, credential.label);
println!("{:?}", recovered.token); // The decrypted token is also protected.Each field is encrypted separately.
A field's ciphertext only decrypts under that field's name.
When you decrypt into Credential, the decryption also checks that the value has the fields Credential expects.
Encryption does not authenticate a container as a whole. That is, it does not authenticate which entries a map has, or the order and length of a sequence. The encryption guide explains what the data model guarantees.
For a secret that lives longer than one call, use Locked.
Locked asks the operating system to protect the memory where the secret is stored.
This example generates the key's bytes directly in that memory.
The example then refuses to use the key unless the memory is locked:
cargo add vitaminc-protected vitaminc-randomuse vitaminc_protected::Locked;
use vitaminc_random::{Rng, SafeRand};
let mut rng = SafeRand::from_entropy().expect("system entropy unavailable");
let key = Locked::<[u8; 32]>::generate(|bytes| rng.fill_bytes(bytes))
.expect("key allocation failed");
match key.require_locked() {
Ok(key) => {
// Borrow the bytes only for the operation that needs them.
key.with(|bytes| assert_eq!(bytes.len(), 32));
}
Err(error) => {
// The key has been dropped and wiped. Do not continue with this key.
eprintln!("locked key storage unavailable: {error}");
}
}On Unix, Locked uses mlock.
mlock stops the operating system writing the memory to swap.
Locked also puts guard pages on each side of the memory.
On Linux, the memory is also left out of core dumps.
The operating system can refuse to lock memory.
Some platforms cannot lock memory at all.
By default, the constructors try to lock the memory.
If they cannot, they still return a value.
Call Locked::require_locked when your code must have locked memory.
Store inline data such as [u8; 32] in Locked.
A Vec or String keeps its contents in a separate buffer, so Locked would only lock the Vec or String header.
The locked storage guide gives the details for each platform.
These crates contain lower-level components, traits for backends, derive macros, and bindings for other languages. Most applications use them only through the main crates. When you extend Vitamin C, or connect it to another language or service, add them as direct dependencies.
| Crate | Purpose | Facade feature | Links |
|---|---|---|---|
vitaminc-aead |
The data model for encrypting structured values, and the traits that an authenticated encryption backend implements. | aead |
crates.io · docs.rs |
vitaminc-aead-derive |
The Encrypt and Decrypt derive macros. vitaminc-aead re-exports them. |
Through vitaminc-aead |
crates.io · docs.rs |
vitaminc-aead-frame |
Encodings for sending values and ciphertexts between programs, and a versioned format for storing them. | Direct dependency | crates.io · docs.rs |
vitaminc-aead-napi |
Converts values between Rust and JavaScript in native Node.js addons, through Node-API. This crate is a Rust library, not an npm package. | Direct dependency | crates.io · docs.rs |
vitaminc-async-traits |
Async traits for hash and message authentication code (MAC) providers that run remotely. | async-traits |
crates.io · docs.rs |
vitaminc-context |
Canonical context encoding for authenticated encryption and pseudorandom functions (PRFs). | context |
crates.io · docs.rs |
vitaminc-hmac |
An HMAC-SHA256 backend that runs in your process, for pseudorandom functions over structured values. | hmac |
crates.io · docs.rs |
vitaminc-kms |
An HMAC backend that uses AWS Key Management Service (KMS). | aws-kms |
crates.io · docs.rs |
vitaminc-normalize |
Encodes structured values in one fixed form, for equality indexes. | normalize |
crates.io · docs.rs |
vitaminc-ore |
Order terms and scheme traits for order-revealing encryption (ORE). You need to supply an ORE backend. | ore |
crates.io · docs.rs |
vitaminc-permutation |
Keyed permutations of arrays and bits. | permutation |
crates.io · docs.rs |
vitaminc-prf |
Traits for deriving pseudorandom values, and terms for equality indexes, from structured data. | prf |
crates.io · docs.rs |
vitaminc-protected-derive |
The OpaqueDebug and TimingSafeEq derive macros. vitaminc-protected re-exports them. |
Through vitaminc-protected |
crates.io · docs.rs |
vitaminc-random-derives |
The Generatable derive macro. vitaminc-random re-exports it. |
Through vitaminc-random |
crates.io · docs.rs |
vitaminc-traits |
Hash and MAC traits that backends implement. | traits |
crates.io · docs.rs |
Before you use these crates, read these notes:
- Use each derive macro through the crate that re-exports it. Follow that crate's setup guide.
- Before you store encoded values, read the storage contract for
vitaminc-aead-frame. - An index reveals information about the values in it.
For example, an equality index shows which values are equal, and an ORE index shows their order.
Before you choose an index, read the
vitaminc-normalizeguide and thevitaminc-oreguide.
The minimum supported Rust version (MSRV) is 1.89.0.
vitaminc-kms requires 1.94.1.
Enabling the facade's aws-kms feature raises its requirement to 1.94.1 too.
An MSRV increase requires a minor release, for example from 0.8 to 0.9. The release notes must state the increase. Patch releases keep the existing MSRV.
All crates require std; there is no no_std configuration yet.
Supported targets include native builds, vitaminc-encrypt on wasm32-unknown-unknown, and the separate encryption guest on wasm32-wasip1.
JavaScript WASM hosts need Web Crypto and the generated bindings described in the encryption setup guide.
The KMS adapter and Node addon bindings target native applications.
License: MIT.
vitaminc-ore also includes Unicode-licensed data and declares MIT AND Unicode-3.0; see its license files.
The facade enables no features by default. Each feature exposes the named crate. Some also enable supporting facade features:
| Feature | Also enables |
|---|---|
context, permutation |
protected |
password |
protected, random |
prf |
context |
hmac |
prf |
async-traits, aws-kms |
traits |
aead |
context |
encrypt |
traits, aead |
normalize |
aead; also PRF normalization if prf is enabled |
ore |
normalize |
These dependencies apply transitively.
normalize alone does not enable prf.
For options such as hlist, jiff, or bitvec, add the relevant crate directly and enable its feature; the facade does not forward them.
Use these methods only as a last resort.
Each one takes the plain value out of the protection that the wrapper gives it.
They exist for the rare APIs that cannot accept a protected value.
For those APIs, the Controlled trait has escape hatches: methods that give you the plain value.
Each method makes you responsible for keeping the value safe:
| Method | What it gives you | What you must do |
|---|---|---|
risky_ref() |
A shared borrow of the plain value. | Stop the code that receives the value from logging, serializing, or copying it by mistake. |
risky_inner_mut() |
A mutable borrow of the plain value. | The same as for risky_ref(). Also, replacing the value can discard the old contents without wiping them. |
risky_unwrap() |
The plain value, which you now own. The wrapper is consumed. | Wipe the value yourself, and make sure it is not disclosed. |
For example, borrow the plain value only in the block of code that needs it:
cargo add vitaminc-protecteduse vitaminc_protected::{Controlled, Protected};
let token = Protected::new(String::from("example-token"));
{
let plaintext: &str = token.risky_ref();
// Pass plaintext only to the API that needs it. Do not log it.
assert!(!plaintext.is_empty());
}
// token is still protected, and is wiped when it is dropped.The wrapper cannot protect a copy that the receiving code makes.
A password's into_unprotected_string() method returns an ordinary String.
You must wipe that String yourself.
The closures you pass to update, map, and Locked::with also receive the plain value.
A closure makes clear which code can use the plain value.
The closure does not stop that code from copying or revealing the value.
Where you can, use APIs that take the protected value directly, as the encryption examples above do.