Crate redoubt_zero 

Systematic memory zeroization with compile-time and runtime guarantees.

Overview

redoubt-zero provides RAII guards and derive macros for automatic, verifiable zeroization. Zeroization happens automatically on drop with runtime verification that it actually occurred.

This is a convenience re-export crate combining [redoubt-zero-core] and [redoubt-zero-derive].

Quick Start

use redoubt_zero::{RedoubtZero, ZeroizeOnDropSentinel, AssertZeroizeOnDrop};

#[derive(RedoubtZero)]
#[fast_zeroize(drop)]
struct TempBuffer {
    data: Vec<u8>,
    capacity: usize,
    __sentinel: ZeroizeOnDropSentinel,
}

let mut buffer = TempBuffer {
    data: vec![1, 2, 3, 4],
    capacity: 1024,
    __sentinel: ZeroizeOnDropSentinel::default(),
};

// Use buffer...

// Automatically zeroized on drop
drop(buffer);

How It Works

1. The Sentinel Pattern

Every struct includes a ZeroizeOnDropSentinel field. This sentinel:

• Flips a flag on drop
• Can be cloned to verify the original was zeroized
• Provides runtime proof of zeroization

2. Automatic Trait Implementation

The #[derive(RedoubtZero)] macro generates:

• FastZeroizable: Implements fast_zeroize(&mut self) to zero all fields
• ZeroizationProbe: Implements is_zeroized(&self) to check if data is zeroed
• AssertZeroizeOnDrop: Test helper to verify drop behavior
• Optional Drop impl: With #[fast_zeroize(drop)], generates Drop that calls fast_zeroize()

3. Field Skipping

Fields can be excluded from zeroization with #[fast_zeroize(skip)]:

#[derive(RedoubtZero)]
struct SessionData {
    token: Vec<u8>,        // Zeroized
    #[fast_zeroize(skip)]
    id: u64,               // Not zeroized (just metadata)
    __sentinel: ZeroizeOnDropSentinel,
}

Core Types

• ZeroizeOnDropSentinel: Drop sentinel for verifiable zeroization
• ZeroizingGuard<T>: RAII wrapper that zeroizes on drop (owned)
• ZeroizingMutGuard<'a, T>: RAII wrapper that zeroizes on drop (borrowed)

Traits

• FastZeroizable: Provides fast_zeroize(&mut self) for efficient zeroization
• ZeroizationProbe: Provides is_zeroized(&self) to check if data is zeroed
• AssertZeroizeOnDrop: Test helper to verify drop zeroization
• ZeroizeMetadata: Field count metadata for verification

Testing Zeroization

Use AssertZeroizeOnDrop::assert_zeroize_on_drop() in tests to verify behavior:

#[derive(RedoubtZero)]
#[fast_zeroize(drop)]
struct Workspace {
    buffer: Vec<u8>,
    __sentinel: ZeroizeOnDropSentinel,
}

#[test]
fn test_workspace_zeroizes() {
    let ws = Workspace {
        buffer: vec![1, 2, 3, 4],
        __sentinel: ZeroizeOnDropSentinel::default(),
    };
    ws.assert_zeroize_on_drop();  // Panics if not zeroized
}

Design Rationale

The Sentinel Pattern

The sentinel enables runtime verification without unsafe code:

• Clone the sentinel before drop
• Drop the original
• Check the sentinel’s flag flipped

This proves Drop ran and zeroization occurred.

FastZeroizable Implementation

FastZeroizable uses compiler fences for zeroization:

• Matches LLVM’s optimization model
• Allows vectorization and unrolling
• Prevents dead store elimination

See redoubt-zero-core for implementation details.

Use Cases

Useful for any data that needs guaranteed cleanup:

• Cryptographic material: Keys, nonces, IVs
• Temporary buffers: Workspace memory, intermediate results
• Session data: Tokens, cookies, auth state
• Parser state: Untrusted input, partial parses
• Any heap allocation you want cleaned up reliably

Crate Structure

This crate re-exports:

• redoubt-zero-core: Core types and traits
• redoubt-zero-derive: #[derive(RedoubtZero)] macro

License

GPL-3.0-only

Modules

assert

Test helpers for verifying zeroization behavior in tests.

collections

Trait implementations and helpers for collections (slices, arrays, Vec<T>).

primitives

Wrapper types for primitive scalars with ZeroizeOnDropSentinel support.

Structs

ZeroizeOnDropSentinel

Runtime verification that zeroization happened before drop.

ZeroizingGuard

RAII guard for owned values that automatically zeroizes on drop.

ZeroizingMutGuard

RAII guard for mutable references that automatically zeroizes on drop.

Traits

AssertZeroizeOnDrop

Trait for types that verify zeroization happened before drop.

FastZeroizable

Trait for types that can be zeroized at runtime.

FastZeroize

Combined trait for types with both zeroization metadata and runtime zeroization.

MutGuarded

Trait for mutable guards that auto-zeroize on drop.

StaticFastZeroizable

Trait for static zeroization of global CipherBox instances.

ZeroizationProbe

Trait for verifying that a value has been zeroized.

ZeroizeMetadata

Metadata about zeroization strategy for a type.

Derive Macros

RedoubtZero

Derives FastZeroizable, ZeroizeMetadata, ZeroizationProbe, and optionally AssertZeroizeOnDrop for a struct.