Zeroize

https://docs.rs/zeroize/1.9.0/zeroize/
Admin
Zeroize is a Rust crate designed to securely zero memory while avoiding compiler optimizations,...
Tokens:5,918
Snippets:84
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Incorrect stack zeroization example

Source: https://docs.rs/zeroize/1.9.0/zeroize/fn.zeroize_stack.html

This example demonstrates an incorrect implementation where inlining may prevent the stack from being properly cleared.

```rust
pub fn encrypt_data(key: &[u8; 16], data: &mut [u8]) {
    leaking_encryption(key, data);
    zeroize::zeroize_stack::<65_536>();
}
```

--------------------------------

### Correct stack zeroization pattern

Source: https://docs.rs/zeroize/1.9.0/zeroize/fn.zeroize_stack.html

This example shows the recommended approach using #[inline(never)] to isolate the sensitive computation and ensure the stack is cleared correctly.

```rust
#[inline(never)]
fn encrypt_data_inner(key: &[u8; 16], data: &mut [u8]) {
    leaking_encryption(key, data);
}

pub fn encrypt_data(key: &[u8; 16], data: &mut [u8]) {
    encrypt_data_inner(key, data);
    zeroize::zeroize_stack::<65_536>();
}
```

--------------------------------

### Using optimization_barrier in a Drop implementation

Source: https://docs.rs/zeroize/1.9.0/zeroize/fn.optimization_barrier.html

Demonstrates using optimization_barrier within a custom Drop implementation to ensure memory zeroization is not optimized away.

```rust
use core::num::NonZeroU32;
use zeroize::{ZeroizeOnDrop, zeroize_flat_type};


struct DataToZeroize {
    buf: [u8; 32],
    // `ThirdPartyType` can be a type with private fields
    // defined in a third-party crate and which does not implement
    // `Zeroize` or zeroization on drop.
    data: ThirdPartyType,
    pos: NonZeroU32,
}

struct SomeMoreFlatData(u64);

impl Drop for DataToZeroize {
    fn drop(&mut self) {
        self.buf = [0u8; 32];
        self.data = ThirdPartyType::default();
        self.pos = NonZeroU32::new(32).unwrap();
        zeroize::optimization_barrier(self);
    }
}

impl zeroize::ZeroizeOnDrop for DataToZeroize {}

let mut data = DataToZeroize {
    buf: [3u8; 32],
    data: ThirdPartyType::default(),
    pos: NonZeroU32::new(32).unwrap(),
};

// data gets zeroized when dropped
```

--------------------------------

### Zeroing memory with Zeroize

Source: https://docs.rs/zeroize/1.9.0/zeroize/index.html

Demonstrates the basic usage of the Zeroize trait to securely clear sensitive data from memory.

```rust
use zeroize::Zeroize;

// Protip: don't embed secrets in your source code.
// This is just an example.
let mut secret = b"Air shield password: 1,2,3,4,5".to_vec();
// [ ... ] open the air shield here

// Now that we're done using the secret, zero it out.
secret.zeroize();
```

--------------------------------

### Zeroize a flat struct

Source: https://docs.rs/zeroize/1.9.0/zeroize/fn.zeroize_flat_type.html

Demonstrates implementing ZeroizeOnDrop for a struct containing flat data and using zeroize_flat_type within the Drop implementation.

```rust
use zeroize::{ZeroizeOnDrop, zeroize_flat_type};

struct DataToZeroize {
    flat_data_1: [u8; 32],
    flat_data_2: SomeMoreFlatData,
}

struct SomeMoreFlatData(u64);

impl Drop for DataToZeroize {
    fn drop(&mut self) {
        unsafe { zeroize_flat_type(self as *mut Self) }
    }
}
impl ZeroizeOnDrop for DataToZeroize {}

let mut data = DataToZeroize {
    flat_data_1: [3u8; 32],
    flat_data_2: SomeMoreFlatData(123u64)
};

// data gets zeroized when dropped
```

--------------------------------

### Use Zeroizing wrapper

Source: https://docs.rs/zeroize/1.9.0/zeroize/index.html

Wraps a value in Zeroizing to ensure its contents are automatically zeroed when the wrapper is dropped.

```rust
use zeroize::Zeroizing;

fn use_secret() {
    let mut secret = Zeroizing::new([0u8; 5]);

    // Set the air shield password
    // Protip (again): don't embed secrets in your source code.
    secret.copy_from_slice(&[1, 2, 3, 4, 5]);
    assert_eq!(secret.as_ref(), &[1, 2, 3, 4, 5]);

    // The contents of `secret` will be automatically zeroized on drop
}
```

--------------------------------

### Zeroizing::new

Source: https://docs.rs/zeroize/1.9.0/zeroize/struct.Zeroizing.html

Creates a new Zeroizing wrapper around a value that implements the Zeroize trait. This ensures the value is zeroized when the wrapper is dropped.

```APIDOC
## pub fn new(value: Z) -> Self

### Description
Wraps a value of type Z (where Z implements Zeroize) into a Zeroizing container. The container ensures that the inner value is zeroized when it is dropped.

### Parameters
- **value** (Z) - The value to be wrapped and protected by zeroization.

### Returns
- **Self** - A new instance of the Zeroizing wrapper.
```

--------------------------------

### Derive Zeroize Macro Syntax

Source: https://docs.rs/zeroize/1.9.0/zeroize/derive.Zeroize.html

Basic syntax for applying the Zeroize derive macro to a struct or enum.

```rust
#[derive(Zeroize)]
{
    // Attributes available to this derive:
    #[zeroize]
}
```

--------------------------------

### fn try_zeroize(&mut self) -> bool

Source: https://docs.rs/zeroize/1.9.0/zeroize/trait.TryZeroize.html

Attempts to zero out the object from memory using intrinsics that prevent compiler optimization. Returns true if the operation was successful, false otherwise.

```APIDOC
## fn try_zeroize(&mut self) -> bool

### Description
Attempts to zero out the object from memory using Rust intrinsics which ensure the zeroization operation is not optimized away by the compiler. This is useful for types where zeroization is conditional, such as reference-counted data.

### Signature
`fn try_zeroize(&mut self) -> bool`

### Returns
- **bool**: Returns true if the object was successfully zeroed, false if zeroization was not possible.
```

--------------------------------

### Derive ZeroizeOnDrop

Source: https://docs.rs/zeroize/1.9.0/zeroize/derive.ZeroizeOnDrop.html

Basic usage of the ZeroizeOnDrop derive macro, including the available zeroize attribute.

```rust
#[derive(ZeroizeOnDrop)]
{
    // Attributes available to this derive:
    #[zeroize]
}
```

--------------------------------

### #[derive(Zeroize)]

Source: https://docs.rs/zeroize/1.9.0/zeroize/derive.Zeroize.html

The Zeroize derive macro provides a way to automatically implement the Zeroize trait for structs and enums. It supports item-level attributes for trait bounds and field-level attributes to skip specific fields during the zeroization process.

```APIDOC
## #[derive(Zeroize)]

### Description
Derives the `Zeroize` trait for a type. This macro is available when the `zeroize_derive` feature is enabled.

### Item-level Attributes
- `#[zeroize(drop)]`: Deprecated. Use `ZeroizeOnDrop` instead.
- `#[zeroize(bound = "T: MyTrait")]`: Replaces any trait bounds inferred by the derive macro.

### Field-level Attributes
- `#[zeroize(skip)]`: Skips the specific field or variant when `zeroize()` is called.
```

--------------------------------

### pub fn zeroize_stack<const N: usize>()

Source: https://docs.rs/zeroize/1.9.0/zeroize/fn.zeroize_stack.html

Zeroizes N bytes of stack space. This is intended to clear sensitive information like cryptographic keys from the stack after computation.

```APIDOC
## Function: zeroize_stack<const N: usize>()

### Description
Zeroizes `N` bytes of stack space. This function is used to clear sensitive data that may remain on the stack after a computation is finished.

### Usage
- **N** (usize) - The number of bytes to zeroize on the stack.

### Warning
- This function requires an accurate estimate of stack usage, which can be affected by optimization levels and compiler flags.
- Sensitive computations must be wrapped in a function annotated with `#[inline(never)]` to ensure the stack frame is not inlined and bypassed by the zeroization process.
- This should be considered a "best effort" approach; verifying the generated binary is recommended for critical security requirements.
```

--------------------------------

### Zeroize Trait

Source: https://docs.rs/zeroize

The Zeroize trait is the primary API for the crate, providing a method to securely zero out memory for types that implement it.

```APIDOC
## trait Zeroize

### Description
The `Zeroize` trait provides a `zeroize()` method to securely clear the memory of an object. This operation is guaranteed not to be optimized away by the compiler.

### Usage
```rust
use zeroize::Zeroize;

let mut secret = b"secret_data".to_vec();
// Perform operations with secret

// Securely clear the memory
secret.zeroize();
```
```

--------------------------------

### pub fn optimization_barrier<T: ?Sized>(val: &T)

Source: https://docs.rs/zeroize/1.9.0/zeroize/fn.optimization_barrier.html

This function acts as an optimization barrier to prevent the compiler from removing previous writes to the referenced data. It is commonly used to ensure that sensitive data is not optimized away during zeroization processes.

```APIDOC
## optimization_barrier

### Description
Observe the referenced data and prevent the compiler from removing previous writes to it. This function acts like `core::hint::black_box` but takes a reference and does not return the passed value.

### Signature
`pub fn optimization_barrier<T: ?Sized>(val: &T)`

### Parameters
- **val** (&T) - The reference to the data that should be protected from compiler optimization.
```

--------------------------------

### Zeroizing Struct Definition

Source: https://docs.rs/zeroize/1.9.0/zeroize/struct.Zeroizing.html

The definition of the Zeroizing wrapper struct.

```rust
pub struct Zeroizing<Z: Zeroize + ?Sized>(/* private fields */);
```

--------------------------------

### Derive Zeroize and ZeroizeOnDrop

Source: https://docs.rs/zeroize/1.9.0/zeroize/index.html

Implements both Zeroize and ZeroizeOnDrop traits to ensure the struct is zeroized when it goes out of scope.

```rust
use zeroize::{Zeroize, ZeroizeOnDrop};

// This struct will be zeroized on drop
#[derive(Zeroize, ZeroizeOnDrop)]
struct MyStruct([u8; 32]);
```

--------------------------------

### Zeroize Trait Definition

Source: https://docs.rs/zeroize/1.9.0/zeroize/trait.Zeroize.html

The core trait definition requiring the implementation of the zeroize method.

```rust
pub trait Zeroize {
    // Required method
    fn zeroize(&mut self);
}
```

--------------------------------

### Define DefaultIsZeroes trait

Source: https://docs.rs/zeroize/1.9.0/zeroize/trait.DefaultIsZeroes.html

The trait definition requiring Copy, Default, and Sized bounds.

```rust
pub trait DefaultIsZeroes:
    Copy
    + Default
    + Sized { }
```

--------------------------------

### Derive Zeroize without Drop

Source: https://docs.rs/zeroize/1.9.0/zeroize/index.html

Implements Zeroize for a struct without adding a Drop handler, suitable for Copy types.

```rust
#[cfg(feature = "zeroize_derive")]
use zeroize::Zeroize;

// This struct will *NOT* be zeroized on drop
#[derive(Copy, Clone, Zeroize)]
struct MyStruct([u8; 32]);
```

--------------------------------

### ZeroizeOnDrop Derive Macro

Source: https://docs.rs/zeroize/1.9.0/zeroize/derive.ZeroizeOnDrop.html

The ZeroizeOnDrop derive macro is used to automatically implement the ZeroizeOnDrop trait for a struct or enum. It supports the #[zeroize(skip)] attribute on fields to exclude them from the zeroization process.

```APIDOC
## Derive Macro: ZeroizeOnDrop

### Description
Derives the `ZeroizeOnDrop` trait for a type, ensuring that the data is zeroed out when the instance is dropped. This requires the `zeroize_derive` crate feature.

### Usage
```rust
#[derive(ZeroizeOnDrop)]
struct SensitiveData {
    #[zeroize(skip)]
    public_field: String,
    secret_field: Vec<u8>,
}
```

### Attributes
- **#[zeroize(skip)]**: Applied at the field level to prevent specific fields or variants from being zeroed when the parent object is dropped.
```

--------------------------------

### pub unsafe fn zeroize_flat_type<F: Sized>(data: *mut F)

Source: https://docs.rs/zeroize/1.9.0/zeroize/fn.zeroize_flat_type.html

Zeroizes a flat type or struct by setting its memory to zero. This function is intended for types that do not own heap-allocated data or require custom drop logic.

```APIDOC
## Function: zeroize_flat_type

### Description
Zeroizes a flat type or struct. It only operates on values owned by the type and is not suitable for dynamically sized values or trait objects.

### Signature
`pub unsafe fn zeroize_flat_type<F: Sized>(data: *mut F)`

### Safety Requirements
- The type must not contain references to outside data or dynamically sized data (e.g., `Vec<T>`, `String`).
- Values stored in the type must not have `Drop` implementations.
- The bit pattern of all zeroes must be valid for the data being zeroized.
- This function may invalidate the type; it is recommended to call this only within `impl Drop`.

### Incompatible Types
- References (`&T`, `&mut T`)
- Non-nullable types (`NonNull<T>`, `NonZeroU32`)
- Enums with explicit non-zero tags
- Smart pointers and collections (`Arc<T>`, `Box<T>`, `Vec<T>`, `HashMap<K, V>`, `String`)
```

--------------------------------

### Zeroize::zeroize

Source: https://docs.rs/zeroize/1.9.0/zeroize/trait.Zeroize.html

The zeroize method clears the memory occupied by the object. It uses Rust intrinsics to ensure the operation is not optimized away by the compiler.

```APIDOC
## fn zeroize(&mut self)

### Description
Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.

### Signature
`fn zeroize(&mut self)`
```

--------------------------------

### TryZeroize Trait Definition

Source: https://docs.rs/zeroize/1.9.0/zeroize/trait.TryZeroize.html

The core trait definition requiring the implementation of the try_zeroize method.

```rust
pub trait TryZeroize {
    // Required method
    fn try_zeroize(&mut self) -> bool;
}
```

--------------------------------

### Define ZeroizeOnDrop Trait

Source: https://docs.rs/zeroize/1.9.0/zeroize/trait.ZeroizeOnDrop.html

The definition of the ZeroizeOnDrop marker trait.

```rust
pub trait ZeroizeOnDrop { }
```

--------------------------------

### Derive ZeroizeOnDrop only

Source: https://docs.rs/zeroize/1.9.0/zeroize/index.html

Implements only the ZeroizeOnDrop marker trait for a struct.

```rust
use zeroize::ZeroizeOnDrop;

// This struct will be zeroized on drop
#[derive(ZeroizeOnDrop)]
struct MyStruct([u8; 32]);
```
Tokens:
Raw