Skip to main content

Crate vitaminc_protected

Crate vitaminc_protected 

Source
Expand description

§Vitamin C Protected

Crates.io Workflow Status

This crate is part of the Vitamin C framework to make cryptography code healthy.

§Installation

cargo add vitaminc-protected

§Safe wrappers for sensitive data

Protected is a set of types that remove some of the sharp edges of working with sensitive data in Rust. Its interface is conceptually similar to Option or Result.

§Sensitive data footguns

Rust is a safe language, but it’s still possible to make mistakes when working with sensitive data. These can include (but are not limited to):

  • Not zeroizing sensitive data when it’s no longer needed
  • Accidentally leaking sensitive data in logs or error messages
  • Performing comparison operations on sensitive data in a way that leaks timing information
  • Serializing sensitive data in a way that leaks information

Protected and the other types in this crate aim to make it easier to avoid these mistakes.

§Usage

The Protected type is the most basic building block in this crate. You can use it to wrap any type that you want to protect so long as it implements the Zeroize trait.

use vitaminc_protected::Protected;

let x = Protected::new([0u8; 32]);

Protected will call zeroize on the inner value when it goes out of scope. Because that wipe is a real Drop, Protected is never Copy, even when the inner type is: unlike a move, a Copy value has no single owner whose drop can wipe it. Duplicating the wrapper is an explicit clone(), and each clone is wiped when it drops. See the Protected type docs for the full rationale. risky_unwrap is the escape hatch: it hands back the plain inner value along with the obligation to wipe it. Combinators such as map show the plain value only to their closure and return the result re-wrapped. It also provides an “opaque” implementation of the Debug trait so you can debug protected values without accidentally leaking their innards.

use vitaminc_protected::{Controlled, Protected};
let x = Protected::new([0u8; 32]);
assert!(format!("{x:?}").contains("Protected<[u8; 32]>"));

The inner value is not accessible directly, but you can use the risky_unwrap method as an escape hatch to get it back. risky_unwrap is defined in the Controlled trait so you’ll need to bring that in scope.

use vitaminc_protected::{Controlled, Protected};

let x = Protected::new([0u8; 32]);
assert_eq!(x.risky_unwrap(), [0; 32]);

Protected does not implement Deref so you cannot access the data directly. This is to prevent accidental leakage of the inner value. It also means comparisons (like PartialEq) are not implemented for Protected.

If you want to safely compare values, you can use Equatable.

§Equatable

The Equatable type is a wrapper around Protected that implements constant-time comparison. It implements PartialEq for any inner type that implements ConstantTimeEq.

use vitaminc_protected::{Equatable, Protected};

let x: Equatable<Protected<u32>> = Equatable::new(100);
let y: Equatable<Protected<u32>> = Equatable::new(100);
assert_eq!(x, y);

§Exportable

The Exportable type is a wrapper around Protected that supports safe serialization via the SafeSerialize and SafeDeserialize traits.

§Usage

The Usage type is a wrapper around Protected that allows you to specify a scope for the data.

This adapter is WIP.

§Working with wrapped values

None of the adapters implement Deref so you can’t access the inner value directly. This is to prevent accidental leakage of the inner value by being explicit about when and how you want to work with the inner value.

You can map over the inner value to transform it, so long as the adapter is the same type. For example, you can map a Protected<T> to a Protected<U>.

use vitaminc_protected::{Controlled, Protected};

// Calculate the sum of values in the array with the result as a `Protected`
let x: Protected<[u8; 4]> = Protected::new([1, 2, 3, 4]);
let result: Protected<u8> = x.map(|arr| arr.as_slice().iter().sum());
assert_eq!(result.risky_unwrap(), 10);

If you have a pair of Protected values, you can zip them together with a function that combines them.

use vitaminc_protected::{Controlled, Protected};

let x: Protected<u8> = Protected::new(1);
let y: Protected<u8> = Protected::new(2);
let z: Protected<u8> = x.zip(y, |a, b| a + b);

If the inner type is an Option you can call transpose to swap the Protected and the Option.

use vitaminc_protected::{Controlled, Protected};

let x = Protected::new(Some([0u8; 32]));
let y = x.transpose();
assert!(y.is_some());

A Protected of Protected can be “flattened” into a single Protected.


let x = Protected::new(Protected::new([0u8; 32]));
let y = x.flatten();
assert_eq!(y.risky_unwrap(), [0u8; 32]);

Use flatten_array to convert a [Protected<T>; N] into a Protected<[T; N]>.

§Protected digests

ProtectedDigest requires a fixed-output implementation that zeroizes its internal state on drop. Enable the digest crate’s zeroization feature, such as sha2 = { version = "0.11", features = ["zeroize"] }.

Unkeyed digests use new; keyed fixed-output functions implementing KeyInit use new_with_key so the key remains in a Controlled container at the API boundary.

Secret inputs use update and protected outputs use finalize_into. Public protocol framing and intentionally exposed outputs cross separate, explicitly named channels:

use sha2::Sha256;
use vitaminc_protected::{Controlled, Protected, ProtectedDigest};

let secret = Protected::new(*b"secret");
let mut digest = ProtectedDigest::<Sha256>::new();
digest.update_public(b"example/domain/v1");
digest.update(&secret);

let mut output = Protected::new([0u8; 32]);
digest.finalize_into(&mut output);
assert_ne!(output.risky_ref(), &[0u8; 32]);

§Also in this crate

Beyond the adapters above, the crate exports TimingSafeEq and Choice (timing-safe comparison), OpaqueDebug and Redacted (leak-resistant Debug), ProtectedDigest, Zeroed, and AsProtectedRef — see the docs.rs API reference for details.

§Non-empty contexts

An AEAD associated-data value or PRF context can legitimately be empty, but a caller that uses one value to domain-separate fields needs it not to be. NonEmpty<T> carries that invariant in the type, checked once at construction: nonempty!("users/email") is checked at compile time (an empty literal does not compile), and NonEmpty::new(value) checks a dynamic value structurally — "", None, Some("") and ("", "") are all rejected, without parsing any encoding. An API that requires the invariant takes NonEmpty<T> directly; a bare &str argument cannot be value-checked at compile time, so there is deliberately no implicit conversion from a string or byte slice. Integers are never empty and convert with From, and a proven value extends with .with(tail) without a second check.

use vitaminc_protected::{nonempty, EmptyError, NonEmpty};

// Compile-time checked: nonempty!("") does not compile.
assert_eq!(nonempty!("users/email").get(), &"users/email");

// Runtime checked, once, for dynamic values.
assert!(NonEmpty::new(String::from("users/email")).is_ok());
assert_eq!(NonEmpty::new(("", None::<&str>)).unwrap_err(), EmptyError);

§Locked storage for long-lived secrets

Use Locked<T> for a secret that lives as long as the process, such as a long-lived key.

Protected wipes a value when the value is dropped. Wiping on drop is enough for a value that lives for one call. Some values are never dropped:

  • a static;
  • a leaked Arc;
  • every value, when the process ends on SIGTERM, SIGKILL, or process::exit.

A key that lives as long as the process needs protection from the moment it is allocated, not only when it is dropped.

On Unix, Locked<T> stores the value in memory that it gets from the operating system. That memory is:

  • locked, so that it is not swapped to disk (mlock);
  • left out of core dumps, on Linux only (MADV_DONTDUMP);
  • surrounded by guard pages;
  • never moved.

Locked<T> wipes the value when it is dropped, as Protected does. While locked() returns true, the kernel does not write the bytes to swap. On Linux, the kernel also leaves the bytes out of core dumps. Both protections apply even if the value is never dropped.

These protections do not keep the bytes out of a hibernation image. The system writes that image by a different mechanism.

On other targets, Locked<T> stores the value on the ordinary heap. The value is wiped when it is dropped. The heap memory has no lock and no guard pages. On those targets, lock_error() reports Unavailable.

// Built in place: the key bytes are never on the stack.
let key: Locked<[u8; 32]> = Locked::generate(fill_from_csprng)?;

key.with(|k| assert_eq!(k[0], 7));
if !key.locked() {
    // Best-effort by default: the value exists, and says why it is not locked.
    eprintln!("key memory is not locked: {}", key.lock_error().unwrap());
}

The operating system can refuse to lock memory, most often because RLIMIT_MEMLOCK (64 KiB by default on many Linux hosts) is too small; every value costs at least one page of it, whatever its size. A seccomp filter can refuse the core-dump exclusion. By default the value is created anyway and the refusal is readable from lock_error; call require_locked() on a value that must be locked, or set LockPolicy::Strict once at startup to make every constructor fail instead. Locked protects the bytes of T itself, so use it for inline types such as [u8; N]; a Vec<u8> inside it has only its header in the locked region.

§Generators

Protected supports generating new values from functions that return the inner value.

fn array_gen<const N: usize>() -> [u8; N] {
    core::array::from_fn(|i| (i + 1) as u8)
}

let input: Protected<[u8; 8]> = Protected::generate(array_gen);

You can also generate values from functions that return a Result with the inner value.

use std::string::FromUtf8Error;

let input: Result<Protected<String>, FromUtf8Error> = Protected::generate_ok(|| {
  String::from_utf8(vec![1, 2, 3, 4, 5, 6, 7, 8])
});

§Cargo features

No optional features are enabled by default.

FeatureEffect
bitvecExposes bit-slice indexing adapters. Accesses use ordinary indexing, so they do not hide the index.
arbitraryImplements quickcheck::Arbitrary for Protected<T> when T supports it, for property tests.

The bitvec dependency is present even without the feature; the flag exposes the adapters. arbitrary is for test data, not cryptographic randomness.

§Compatibility

Requires Rust 1.89.0 and the Rust standard library (std). MSRV increases require a minor release; patch releases retain the existing floor. See the workspace compatibility policy.

§CipherStash

Vitamin C is brought to you by the team at CipherStash.

License: MIT

Modules§

bitvecbitvec
Indexing bit slices with protected indices (bitvec feature). These adapters perform ordinary indexed accesses; they do not hide the index through a constant-time scan.
slice_index
Array indexing using a protected index. Indexing exposes the selected memory access and panics on an out-of-bounds index, just as ordinary indexing does.

Macros§

nonempty
A NonEmpty<&'static str> checked at compile time.
nonempty_bytes
A NonEmpty<&'static [u8]> checked at compile time.

Structs§

Buffer
Secret bytes on the heap, written a few at a time: a frame, a blob, a serialisation of a value.
Choice
The Choice struct represents a choice for use in conditional assignment.
DefaultScope
Default usage scope, also accepted by ordinary unscoped Protected values.
EmptyError
The error returned when a value that must carry caller-supplied data turned out to be empty.
Equatable
A controlled wrapper type that allows for constant time equality checks of a Controlled type. The immediate inner type must also be Controlled (typically Protected).
Exportable
Exportable is a wrapper type that allows for controlled types to be serialized and deserialized. Serialization has a bias towards efficient byte representation and uses serde_bytes for byte arrays.
InvalidLength
The error type returned when key and/or IV used in the KeyInit, KeyIvInit, and InnerIvInit slice-based methods had an invalid length.
LockPolicyError
The process policy was already set to a different value.
Locked
A secret stored in memory that is locked against swapping, excluded from core dumps where the platform allows, fenced by guard pages, and wiped when dropped.
NonEmpty
A context value proven to carry caller-supplied bytes.
Protected
The most basic controlled type. It ensures inner types are Zeroize and implements Debug and Display safely (i.e. inner sensitive values are redacted).
ProtectedDigest
A fixed-output cryptographic state whose implementation wipes itself on drop.
ProtectedRef
A wrapper around a reference to prevent inner access. Conceptually similar to &T, but it can only be made inside this crate, through AsProtectedRef, and the inner value is reached only through the combinators that take it or through risky_ref.
Redacted
Wrapper type for redacting debug output which implements OpaqueDebug for all types.
Usage
Attach a compile-time usage scope to a controlled value.

Enums§

LockError
Why a Locked value could not be created, or why its memory is not locked.
LockPolicy
What a Locked constructor does when the operating system refuses to lock the memory or, on Linux, to exclude it from core dumps.

Traits§

Acceptable
Marker trait for types accepted by an API that explicitly requires scope S.
AsProtectedRef
Trait for types that can be converted to a ProtectedRef. Conceptually similar to the AsRef trait in std but for Protected types. This prevents the inner value from being accessed directly. ProtectedRef cannot be constructed outside this crate, so downstream implementations must delegate to an existing protected source rather than wrapping an arbitrary reference.
ConstantTimeEq
Sealed equality interface returning an ordinary Boolean result.
Controlled
Common access and transformation operations for this crate’s secret wrappers.
IsEmpty
The name MaybeEmpty had before it was renamed: it read as a marker (“values of this type are empty”) when it is a capability (“this value can be asked whether it is empty”). Bounds and impls written against IsEmpty keep compiling; switch to MaybeEmpty at your convenience. Structural emptiness of a value, decided before any encoding is applied.
MaybeEmpty
Structural emptiness of a value, decided before any encoding is applied.
OpaqueDebug
Opaque Debug for secret-bearing types.
ReplaceT
ReplaceT is a sealed trait that is used to replace the inner value of a type. It is only implemented for types that are Controlled.
SafeDeserialize
Explicit deserialization channel for supported values and controlled wrappers.
SafeSerialize
Explicit serialization channel for supported values and controlled wrappers.
Scope
Marker trait for a type that defines a usage scope
TimingSafeEq
This module defines the TimingSafeEq trait for performing equality checks in constant-time with respect to secret data, and the TimingSafeEq derive macro to automatically implement it for structs and enums.
Zeroed
Construct a zero or empty value for supported primitives, arrays, and wrappers. Unlike Default, the intended initial state is explicitly zero/empty.

Functions§

flatten_array
Convenience function to flatten an array of Protected into a Protected array.

Derive Macros§

OpaqueDebug
Derive redacted Debug and the OpaqueDebug marker trait.
TimingSafeEq
Derive TimingSafeEq, PartialEq, and Eq using field comparisons.