Crate vitaminc_protected 

Vitamin C Protected

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

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. 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_eq!(format!("{x:?}"), "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 implements constant-time serialization.

This adapter is WIP.

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!(matches!(y, Some(Protected)));

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]>.

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])
});

CipherStash

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

License: MIT

Modules

slice_index

Structs

Choice

The Choice struct represents a choice for use in conditional assignment.

DefaultScope

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.

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

ProtectedRef

A wrapper around a reference to prevent inner access. Conceptually similar to &T but prevents direct access to the inner value outside of this crate.

Redacted

Wrapper type for redacting debug output which implements OpaqueDebug for all types.

Usage

Traits

Acceptable

Marker trait for types that are acceptable in a certain scope.

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. The trait is sealed so it cannot be implemented outside of this crate.

ConstantTimeEq

Controlled

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

SafeSerialize

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

Similar to Default, but doesn’t rely on the standard library, is only implemented for Paranoid types, and covers array sizes up to 1024.

Functions

flatten_array

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

Derive Macros

OpaqueDebug

TimingSafeEq