zeroize/

zeroize.rs

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]

//! Securely zero memory (a.k.a. zeroize) while avoiding compiler
//! optimizations.
//!
//! This crate implements a portable approach to securely zeroing memory using
//! techniques which guarantee they won't be "optimized away" by the compiler.
//!
//! The [`Zeroize`] trait is the crate's primary API.
//!
//! ## About
//!
//! Zeroing memory securely is hard: compilers optimize for performance, and in
//! doing so they love to "optimize away" unnecessary zeroing calls. There are
//! many documented "tricks" to attempt to avoid these optimizations and ensure
//! that a zeroing routine is performed reliably.
//!
//! This crate isn't about tricks: it uses [`core::ptr::write_volatile`] to
//! provide easy-to-use, portable zeroing behavior which works on all of Rust's
//! core number types and slices thereof. On supported architectures a minimal
//! inline-assembly optimization barrier stops the compiler from eliding the
//! writes, with a portable `core::hint::black_box` fallback on every other
//! target.
//!
//! - No insecure fallbacks!
//! - No required dependencies!
//! - No FFI! A minimal optimization barrier uses inline assembly on supported
//!   targets, with a portable fallback that keeps **WASM** working.
//! - `#![no_std]`, i.e. **embedded-friendly**!
//! - No functionality besides securely zeroing memory!
//! - (Optional) Custom derive support for zeroing complex structures
//!
//! ## Example
//!
//! ```
//! 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();
//! ```
//!
//! ## Usage
//!
//! ### Traits
//!
//! The [`Zeroize`] trait is the core API of this crate. It's intended to be impl'd on values that
//! may-or-may-not contain secrets, for example the `zeroize` crate itself defines them on the
//! core integers e.g. `u8`, `u16`, `i8`, `i16`, as well as arrays thereof. Its core API is
//! [`Zeroize::zeroize`], a method which takes `&mut self` and writes over the type's internal
//! memory with some placeholder value, typically some form of `0`.
//!
//! The [`DefaultIsZeroes`] marker trait can be impl'd on types which have a [`Default`] impl that
//! can be used for [`Zeroize`]. Types which implement this trait receive a blanket impl of the
//! [`Zeroize`] trait.
//!
//! We recommend that types which always contain secrets, and especially ones which need to maintain
//! complex invariants, do NOT impl the [`Zeroize`] trait, but instead provide a [`Drop`] impl which
//! takes care of erasing the secret values from memory directly. Such types can mark that they're
//! doing this with the [`ZeroizeOnDrop`] marker trait. Note that [`ZeroizeOnDrop`] is *just* a
//! marker trait, and making it actually work requires actually providing a [`Drop`] impl which
//! takes care of zeroizing secrets.
//!
//! Why not impl [`Zeroize`] for such types, e.g. a `SecretKey` type? The problem is [`Zeroize`]
//! would effectively leave such types in an invalid state, and a sort of use-after-zeroize
//! condition becomes possible. For that reason, we recommend these types automatically handle
//! zeroization in their [`Drop`] handler alone.
//!
//! ### Supported types
//!
//! The [`Zeroize`] trait is impl'd on all of Rust's core scalar types including
//! integers, floats, `bool`, and `char`.
//!
//! Additionally, it's implemented on slices and `IterMut`s of the above types.
//!
//! When the `alloc` feature is enabled (which it is by default), it's also
//! impl'd for `Vec<T>` for the above types as well as `String`, where it provides
//! [`Vec::clear`] / [`String::clear`]-like behavior (truncating to zero-length)
//! but ensures the backing memory is securely zeroed with some caveats.
//!
//! With the `std` feature enabled (which it is **not** by default), [`Zeroize`]
//! is also implemented for [`CString`]. After calling `zeroize()` on a `CString`,
//! its internal buffer will contain exactly one nul byte. The backing
//! memory is zeroed by converting it to a `Vec<u8>` and back into a `CString`.
//! (NOTE: see "Stack/Heap Zeroing Notes" for important `Vec`/`String`/`CString` details)
//!
//! [`CString`]: https://doc.rust-lang.org/std/ffi/struct.CString.html
//!
//! The [`DefaultIsZeroes`] marker trait can be impl'd on types which also
//! impl [`Default`], which implements [`Zeroize`] by overwriting a value with
//! the default value.
//!
//! ### Custom Derive Support
//!
//! This crate has custom derive support for the `Zeroize` trait,
//! gated under the `zeroize` crate's `derive` Cargo feature,
//! which automatically calls `zeroize()` on all members of a struct
//! or tuple struct.
//!
//! Attributes supported for `Zeroize`:
//!
//! On the item level:
//! - `#[zeroize(bound = "T: MyTrait")]`: this replaces any trait bounds
//!   inferred by zeroize
//!
//! On the field level:
//! - `#[zeroize(skip)]`: skips this field or variant when calling `zeroize()`
//!
//! Attributes supported for `ZeroizeOnDrop`:
//!
//! On the field level:
//! - `#[zeroize(skip)]`: skips this field or variant when calling `zeroize()`
//!
//! Note that the `Zeroize` derive infers a `Zeroize` bound for every type parameter used in a
//! field. The `ZeroizeOnDrop` derive does not infer any bounds: its generated `Drop` impl
//! requires each field to implement either `Zeroize` or `ZeroizeOnDrop`, so generic types must
//! carry the necessary bounds themselves.
//!
//! Example which derives `Drop`:
//!
//! ```
//! # #[cfg(feature = "derive")]
//! # {
//! use zeroize::{Zeroize, ZeroizeOnDrop};
//!
//! // This struct will be zeroized on drop
//! #[derive(Zeroize, ZeroizeOnDrop)]
//! struct MyStruct([u8; 32]);
//! # }
//! ```
//!
//! Example which does not derive `Drop` (useful for e.g. `Copy` types)
//!
//! ```
//! #[cfg(feature = "derive")]
//! # {
//! use zeroize::Zeroize;
//!
//! // This struct will *NOT* be zeroized on drop
//! #[derive(Copy, Clone, Zeroize)]
//! struct MyStruct([u8; 32]);
//! # }
//! ```
//!
//! Example which only derives `Drop`:
//!
//! ```
//! # #[cfg(feature = "derive")]
//! # {
//! use zeroize::ZeroizeOnDrop;
//!
//! // This struct will be zeroized on drop
//! #[derive(ZeroizeOnDrop)]
//! struct MyStruct([u8; 32]);
//! # }
//! ```
//!
//! ### `Zeroizing<Z>`: wrapper for zeroizing arbitrary values on drop
//!
//! `Zeroizing<Z: Zeroize>` is a generic wrapper type that impls `Deref`
//! and `DerefMut`, allowing access to an inner value of type `Z`, and also
//! impls a `Drop` handler which calls `zeroize()` on its contents:
//!
//! ```
//! 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
//! }
//!
//! # use_secret()
//! ```
//!
//! ## What guarantees does this crate provide?
//!
//! This crate guarantees the zeroing operation can't be "optimized away" by the compiler, as
//! ensured by LLVM's volatile semantics.
//!
//! Previously there were worries that the approach used by this crate (mixing volatile and
//! non-volatile accesses) was undefined behavior due to language contained
//! in the documentation for `write_volatile`, however after some discussion
//! within the [Unsafe Code Guidelines Working Group], [these remarks have been removed] and the
//! specific usage pattern in this crate is considered to be well-defined.
//!
//! All of that said, there is still potential for microarchitectural attacks
//! (ala Spectre/Meltdown) to leak "zeroized" secrets through covert channels.
//! This crate makes no guarantees that zeroized values cannot be leaked
//! through such channels, as they represent flaws in the underlying hardware.
//!
//! ## Stack/Heap Zeroing Notes
//!
//! This crate can be used to zero values from either the stack or the heap. We recommend storing
//! sensitive data on the heap whenever possible to reduce the potential for making copies in memory
//! via Rust move semantics, however note that stack spilling and other optimizations may leave
//! temporary copies of data from the heap on the stack.
//!
//! This crate deliberately does not provide a portable "zeroize the stack" API: identifying the
//! stack region used by a computation cannot be done reliably from safe Rust, so such an API
//! tends to give a false sense of security.
//!
//! [`Pin`][`core::pin::Pin`] can be leveraged in conjunction with this crate to ensure data kept
//! on the stack isn't moved.
//!
//! The `Zeroize` impls for `Vec`, `String` and `CString` zeroize the entire capacity of their
//! backing buffer, but cannot guarantee copies of the data were not previously made by buffer
//! reallocation. It's therefore important when attempting to zeroize such buffers to initialize
//! them to the correct capacity, and take care to prevent subsequent reallocation.
//!
//! The [`secrecy`] crate provides higher-level abstractions for eliminating
//! usage patterns which can cause reallocations:
//!
//! [`secrecy`]: https://docs.rs/secrecy
//!
//! ## What about: clearing registers, `mlock()`, `mprotect()`, etc?
//!
//! This crate is focused on providing simple, unobtrusive support for reliably
//! zeroing memory using the best approach possible on stable Rust.
//!
//! Clearing registers is a difficult problem that can't easily be solved by
//! something like a crate, and requires either inline ASM or rustc support.
//! See <https://github.com/rust-lang/rust/issues/17046> for background on
//! this particular problem.
//!
//! Other memory protection mechanisms are interesting and useful, but often
//! overkill (e.g. defending against RAM scraping or attackers with swap access).
//! In as much as there may be merit to these approaches, there are also many
//! other crates that already implement more sophisticated memory protections.
//! Such protections are explicitly out-of-scope for this crate.
//!
//! Zeroing memory is [good cryptographic hygiene] and this crate seeks to promote
//! it in the most unobtrusive manner possible. This includes omitting complex
//! `unsafe` memory protection systems and just trying to make the best memory
//! zeroing crate available.
//!
//! [Unsafe Code Guidelines Working Group]: https://github.com/rust-lang/unsafe-code-guidelines
//! [these remarks have been removed]: https://github.com/rust-lang/rust/pull/60972
//! [good cryptographic hygiene]: https://github.com/veorq/cryptocoding#clean-memory-of-secret-data
//! [`Ordering::SeqCst`]: core::sync::atomic::Ordering::SeqCst

#[cfg(feature = "alloc")]
extern crate alloc;
#[cfg(feature = "std")]
extern crate std;

#[cfg(feature = "derive")]
pub use zeroize_derive::{Zeroize, ZeroizeOnDrop};

#[cfg(target_arch = "aarch64")]
mod aarch64;
#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
mod x86;

mod barrier;
#[cfg(feature = "alloc")]
use alloc::{boxed::Box, string::String, vec::Vec};
use core::{
    marker::{PhantomData, PhantomPinned},
    mem::{MaybeUninit, size_of},
    num::{
        self, NonZeroI8, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI128, NonZeroIsize, NonZeroU8, NonZeroU16,
        NonZeroU32, NonZeroU64, NonZeroU128, NonZeroUsize,
    },
    ops, ptr,
    slice::IterMut,
};
#[cfg(feature = "std")]
use std::ffi::CString;

pub use barrier::optimization_barrier;

/// Trait for securely erasing values from memory.
pub trait Zeroize {
    /// Zero out this object from memory using Rust intrinsics which ensure the
    /// zeroization operation is not "optimized away" by the compiler.
    fn zeroize(&mut self);

    /// Zeroize every element of `slice`.
    ///
    /// This is an implementation detail used by the container impls (`[Z; N]`, `Vec<Z>`,
    /// `Box<[Z]>`) so they can select the most efficient strategy for the element type: the
    /// blanket impl for [`DefaultIsZeroes`] types overrides it with a single bulk volatile
    /// write, while other element types fall back to calling [`zeroize`][Zeroize::zeroize] on
    /// each element.
    #[doc(hidden)]
    fn zeroize_slice(slice: &mut [Self])
    where
        Self: Sized,
    {
        for elem in slice {
            elem.zeroize();
        }
    }
}

/// Marker trait signifying that this type will [`Zeroize::zeroize`] itself on [`Drop`].
pub trait ZeroizeOnDrop {}

/// Marker trait for types whose [`Default`] is the desired zeroization result
pub trait DefaultIsZeroes: Copy + Default + Sized {}

/// Fallible trait for representing cases where zeroization may or may not be
/// possible.
///
/// This is primarily useful for scenarios like reference counted data, where
/// zeroization is only possible when the last reference is dropped.
pub trait TryZeroize {
    /// Try to zero out this object from memory using Rust intrinsics which
    /// ensure the zeroization operation is not "optimized away" by the
    /// compiler.
    #[must_use]
    fn try_zeroize(&mut self) -> bool;
}

impl<Z> Zeroize for Z
where
    Z: DefaultIsZeroes,
{
    fn zeroize(&mut self) {
        volatile_write(self, Z::default());
    }

    fn zeroize_slice(slice: &mut [Z]) {
        zeroize_slice_default(slice);
    }
}

/// Bulk zeroization of a mutable slice of [`DefaultIsZeroes`] elements.
///
/// This performs a single volatile set over the whole slice, which is considerably faster than
/// calling [`Zeroize::zeroize`] once per element.
#[inline(always)]
fn zeroize_slice_default<Z: DefaultIsZeroes>(slice: &mut [Z]) {
    let size = slice.len().checked_mul(size_of::<Z>()).expect("overflow");
    assert!(isize::try_from(size).is_ok());

    // Safety:
    //
    // The slice is well aligned and backed by a single allocation of at least `slice.len()`
    // elements of type `Z`. `slice.len() * size_of::<Z>()` is at most `isize::MAX` because of the
    // assertion above, so the memory does not wrap around the address space.
    unsafe { volatile_set(slice.as_mut_ptr(), Z::default(), slice.len()) };
}

macro_rules! impl_zeroize_with_default {
    ($($type:ty),+) => {
        $(impl DefaultIsZeroes for $type {})+
    };
}

#[rustfmt::skip]
impl_zeroize_with_default! {
    PhantomPinned, (), bool, char,
    f32, f64,
    i8, i16, i32, i64, i128, isize,
    u8, u16, u32, u64, u128, usize
}

/// `PhantomPinned` is zero sized so provide a `ZeroizeOnDrop` implementation.
impl ZeroizeOnDrop for PhantomPinned {}

/// `()` is zero sized so provide a `ZeroizeOnDrop` implementation.
impl ZeroizeOnDrop for () {}

macro_rules! impl_zeroize_for_non_zero {
    ($($type:ty),+) => {
        $(
            impl Zeroize for $type {
                fn zeroize(&mut self) {
                    const ONE: $type = match <$type>::new(1) {
                        Some(one) => one,
                        None => unreachable!(),
                    };
                    volatile_write(self, ONE);
                }
            }
        )+
    };
}

impl_zeroize_for_non_zero!(
    NonZeroI8,
    NonZeroI16,
    NonZeroI32,
    NonZeroI64,
    NonZeroI128,
    NonZeroIsize,
    NonZeroU8,
    NonZeroU16,
    NonZeroU32,
    NonZeroU64,
    NonZeroU128,
    NonZeroUsize
);

impl<Z> Zeroize for num::Wrapping<Z>
where
    Z: Zeroize,
{
    fn zeroize(&mut self) {
        self.0.zeroize();
    }
}

/// Impl [`Zeroize`] on arrays of types that impl [`Zeroize`].
impl<Z, const N: usize> Zeroize for [Z; N]
where
    Z: Zeroize,
{
    fn zeroize(&mut self) {
        Z::zeroize_slice(self);
    }
}

/// Impl [`ZeroizeOnDrop`] on arrays of types that impl [`ZeroizeOnDrop`].
impl<Z, const N: usize> ZeroizeOnDrop for [Z; N] where Z: ZeroizeOnDrop {}

impl<Z> Zeroize for IterMut<'_, Z>
where
    Z: Zeroize,
{
    fn zeroize(&mut self) {
        for elem in self {
            elem.zeroize();
        }
    }
}

impl<Z> Zeroize for Option<Z>
where
    Z: Zeroize,
{
    fn zeroize(&mut self) {
        if let Some(value) = self {
            value.zeroize();

            // Ensures self is None and that the value was dropped. Without the take, the drop
            // of the (zeroized) value isn't called, which might lead to a leak or other
            // unexpected behavior. For example, if this were Option<Vec<T>>, the above call to
            // zeroize would not free the allocated memory, but the `take` call will.
            self.take();
        }

        // Ensure that if the `Option` were previously `Some` but a value was copied/moved out
        // that the remaining space in the `Option` is zeroized.
        //
        // Safety:
        //
        // The memory pointed to by `self` is valid for `size_of::<Self>()` bytes.
        // It is also properly aligned, because `u8` has an alignment of `1`.
        unsafe {
            volatile_set(ptr::from_mut::<Self>(self).cast::<u8>(), 0, size_of::<Self>());
        }

        // Ensures self is overwritten with the `None` bit pattern. volatile_write can't be
        // used because Option<Z> is not copy.
        //
        // Safety:
        //
        // self is safe to replace with `None`, which the take() call above should have
        // already done semantically. Any value which needed to be dropped will have been
        // done so by take().
        unsafe { ptr::write_volatile(self, None) }
    }
}

impl<Z> ZeroizeOnDrop for Option<Z> where Z: ZeroizeOnDrop {}

/// Impl [`Zeroize`] on [`MaybeUninit`] types.
///
/// This fills the memory with zeroes.
/// Note that this ignore invariants that `Z` might have, because
/// [`MaybeUninit`] removes all invariants.
impl<Z> Zeroize for MaybeUninit<Z> {
    fn zeroize(&mut self) {
        // SAFETY: `MaybeUninit` is valid for any byte pattern, including zeros.
        unsafe { ptr::write_volatile(self, MaybeUninit::zeroed()) }
    }
}

/// Impl [`Zeroize`] on slices of [`MaybeUninit`] types.
///
/// This impl can eventually be optimized using an memset intrinsic,
/// such as [`core::intrinsics::volatile_set_memory`].
///
/// This fills the slice with zeroes.
///
/// Note that this ignore invariants that `Z` might have, because
/// [`MaybeUninit`] removes all invariants.
impl<Z> Zeroize for [MaybeUninit<Z>] {
    fn zeroize(&mut self) {
        let ptr = self.as_mut_ptr().cast::<MaybeUninit<u8>>();
        let size = self.len().checked_mul(size_of::<Z>()).expect("overflow");
        assert!(isize::try_from(size).is_ok());

        // Safety:
        //
        // This is safe, because every valid pointer is well aligned for u8
        // and it is backed by a single allocated object for at least `self.len() * size_of::<Z>()` bytes.
        // and 0 is a valid value for `MaybeUninit<Z>`
        // The memory of the slice should not wrap around the address space.
        unsafe { volatile_set(ptr, MaybeUninit::zeroed(), size) }
    }
}

/// Impl [`Zeroize`] on slices of types that can be zeroized with [`Default`].
///
/// This impl can eventually be optimized using an memset intrinsic,
/// such as [`core::intrinsics::volatile_set_memory`]. For that reason the
/// blanket impl on slices is bounded by [`DefaultIsZeroes`].
///
/// To zeroize a mut slice of `Z: Zeroize` which does not impl
/// [`DefaultIsZeroes`], call `iter_mut().zeroize()`.
impl<Z> Zeroize for [Z]
where
    Z: DefaultIsZeroes,
{
    fn zeroize(&mut self) {
        zeroize_slice_default(self);
    }
}

/// Overwrites the contents of the string slice with NUL (`\0`) bytes.
///
/// Note that, unlike the `String` implementation, this cannot change the length of the string,
/// because `str` is a dynamically sized view whose length is stored in the pointer. The result is
/// therefore a string of the same length whose bytes are all `\0`, which is still valid UTF-8.
impl Zeroize for str {
    fn zeroize(&mut self) {
        // Safety:
        // A zeroized byte slice is a valid UTF-8 string.
        unsafe { self.as_bytes_mut().zeroize() }
    }
}

/// [`PhantomData`] is always zero sized so provide a [`Zeroize`] implementation.
impl<Z> Zeroize for PhantomData<Z> {
    fn zeroize(&mut self) {}
}

/// [`PhantomData`] is always zero sized so provide a [`ZeroizeOnDrop`] implementation.
impl<Z> ZeroizeOnDrop for PhantomData<Z> {}

macro_rules! impl_zeroize_tuple {
    ( $( $type_name:ident ),+ ) => {
        impl<$($type_name: Zeroize),+> Zeroize for ($($type_name,)+) {
            fn zeroize(&mut self) {
                #[allow(non_snake_case)]
                let ($($type_name,)+) = self;
                $($type_name.zeroize());+
            }
        }

        impl<$($type_name: ZeroizeOnDrop),+> ZeroizeOnDrop for ($($type_name,)+) { }
    }
}

// Generic implementations for tuples up to 10 parameters.
impl_zeroize_tuple!(A);
impl_zeroize_tuple!(A, B);
impl_zeroize_tuple!(A, B, C);
impl_zeroize_tuple!(A, B, C, D);
impl_zeroize_tuple!(A, B, C, D, E);
impl_zeroize_tuple!(A, B, C, D, E, F);
impl_zeroize_tuple!(A, B, C, D, E, F, G);
impl_zeroize_tuple!(A, B, C, D, E, F, G, H);
impl_zeroize_tuple!(A, B, C, D, E, F, G, H, I);
impl_zeroize_tuple!(A, B, C, D, E, F, G, H, I, J);

#[cfg(feature = "alloc")]
impl<Z> Zeroize for Vec<Z>
where
    Z: Zeroize,
{
    /// "Best effort" zeroization for `Vec`.
    ///
    /// Call `Zeroize` on all `Vec` elements and spare capacity. Cannot ensure that
    /// previous reallocations did not leave values on the heap.
    fn zeroize(&mut self) {
        // Zero the spare (uninitialized) capacity first, i.e. everything
        // beyond `len`. This must happen before `clear()` resets `len` to 0,
        // otherwise `spare_capacity_mut()` would cover the whole allocation
        // and re-zero the initialized elements a second time below.
        self.spare_capacity_mut().zeroize();

        // Zeroize all the initialized elements.
        Z::zeroize_slice(self);

        // Set the Vec's length to 0 and drop all the (already-zeroized) elements.
        self.clear();
    }
}

#[cfg(feature = "alloc")]
impl<Z> ZeroizeOnDrop for Vec<Z> where Z: ZeroizeOnDrop {}

#[cfg(feature = "alloc")]
impl<Z> Zeroize for Box<[Z]>
where
    Z: Zeroize,
{
    /// Unlike `Vec`, `Box<[Z]>` cannot reallocate, so we can be sure that we are not leaving
    /// values on the heap.
    fn zeroize(&mut self) {
        Z::zeroize_slice(self);
    }
}

#[cfg(feature = "alloc")]
impl<Z> ZeroizeOnDrop for Box<[Z]> where Z: ZeroizeOnDrop {}

#[cfg(feature = "alloc")]
impl Zeroize for Box<str> {
    fn zeroize(&mut self) {
        self.as_mut().zeroize();
    }
}

#[cfg(feature = "alloc")]
impl Zeroize for String {
    fn zeroize(&mut self) {
        // Safety:
        //
        // The bytes are immediately zeroized, and a slice of NUL bytes is valid UTF-8, so the
        // `String` remains a valid UTF-8 buffer (with length 0) when the borrow ends.
        unsafe { self.as_mut_vec() }.zeroize();
    }
}

#[cfg(feature = "std")]
impl Zeroize for CString {
    fn zeroize(&mut self) {
        use core::mem;

        // mem::take uses replace internally to swap the pointer
        // Unfortunately this results in an allocation for a Box::new(&[0]) as CString must
        // contain a trailing zero byte
        let this = mem::take(self);

        // - CString::into_bytes_with_nul calls ::into_vec which takes ownership of the heap pointer
        // as a Vec<u8>
        // - Calling .zeroize() on the resulting vector clears out the bytes
        // From: https://github.com/RustCrypto/utils/pull/759#issuecomment-1087976570
        let mut buf = this.into_bytes_with_nul();
        buf.zeroize();

        // expect() should never fail, because zeroize() truncates the Vec
        let zeroed = CString::new(buf).expect("buf not truncated");

        // Replace the (now empty) `self` with the zeroed `CString`. The original buffer has
        // already been zeroed above; it may be reused or shrunk in place here, but its previous
        // contents are gone either way.
        let _ = mem::replace(self, zeroed);
    }
}

/// `Zeroizing` is a wrapper for any `Z: Zeroize` type which implements a
/// `Drop` handler which zeroizes dropped values.
///
/// `Zeroizing<T>` is defined with `repr(transparent)`, which means it is
/// guaranteed to have the same physical representation as the underlying type.
#[derive(Default, Eq, PartialEq)]
#[repr(transparent)]
pub struct Zeroizing<Z: Zeroize + ?Sized>(Z);

impl<Z: Zeroize + ?Sized> core::fmt::Debug for Zeroizing<Z> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("Zeroizing").finish_non_exhaustive()
    }
}

impl<Z> Zeroizing<Z>
where
    Z: Zeroize,
{
    /// Move value inside a `Zeroizing` wrapper which ensures it will be
    /// zeroized when it's dropped.
    #[inline(always)]
    pub fn new(value: Z) -> Self {
        Self(value)
    }
}

impl<Z: Zeroize + Clone> Clone for Zeroizing<Z> {
    #[inline(always)]
    fn clone(&self) -> Self {
        Self(self.0.clone())
    }

    #[inline(always)]
    fn clone_from(&mut self, source: &Self) {
        self.0.zeroize();
        self.0.clone_from(&source.0);
    }
}

impl<Z> From<Z> for Zeroizing<Z>
where
    Z: Zeroize,
{
    #[inline(always)]
    fn from(value: Z) -> Zeroizing<Z> {
        Zeroizing(value)
    }
}

impl<Z> ops::Deref for Zeroizing<Z>
where
    Z: Zeroize + ?Sized,
{
    type Target = Z;

    #[inline(always)]
    fn deref(&self) -> &Z {
        &self.0
    }
}

impl<Z> ops::DerefMut for Zeroizing<Z>
where
    Z: Zeroize + ?Sized,
{
    #[inline(always)]
    fn deref_mut(&mut self) -> &mut Z {
        &mut self.0
    }
}

impl<T, Z> AsRef<T> for Zeroizing<Z>
where
    T: ?Sized,
    Z: AsRef<T> + Zeroize + ?Sized,
{
    #[inline(always)]
    fn as_ref(&self) -> &T {
        self.0.as_ref()
    }
}

impl<T, Z> AsMut<T> for Zeroizing<Z>
where
    T: ?Sized,
    Z: AsMut<T> + Zeroize + ?Sized,
{
    #[inline(always)]
    fn as_mut(&mut self) -> &mut T {
        self.0.as_mut()
    }
}

impl<Z> Zeroize for Zeroizing<Z>
where
    Z: Zeroize + ?Sized,
{
    fn zeroize(&mut self) {
        self.0.zeroize();
    }
}

impl<Z> ZeroizeOnDrop for Zeroizing<Z> where Z: Zeroize + ?Sized {}

impl<Z> Drop for Zeroizing<Z>
where
    Z: Zeroize + ?Sized,
{
    fn drop(&mut self) {
        self.0.zeroize();
    }
}

#[cfg(feature = "serde")]
impl<Z> serde::Serialize for Zeroizing<Z>
where
    Z: Zeroize + serde::Serialize + ?Sized,
{
    #[inline(always)]
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        self.0.serialize(serializer)
    }
}

#[cfg(feature = "serde")]
impl<'de, Z> serde::Deserialize<'de> for Zeroizing<Z>
where
    Z: Zeroize + serde::Deserialize<'de>,
{
    #[inline(always)]
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        Ok(Self(Z::deserialize(deserializer)?))
    }
}

/// Perform a volatile write to the destination
#[inline(always)]
fn volatile_write<T: Copy + Sized>(dst: &mut T, src: T) {
    // Safety:
    //
    // `dst` is a valid, aligned reference, so it is valid for a write of `size_of::<T>()` bytes,
    // and `src` is a valid `T`.
    unsafe { ptr::write_volatile(dst, src) }
}

/// Perform a volatile `memset` operation which fills a slice with a value
///
/// # Safety
/// The memory pointed to by `dst` must be a single allocated object that is valid for `count`
/// contiguous elements of `T`.
/// `count` must not be larger than an `isize`.
/// `dst` being offset by `size_of::<T> * count` bytes must not wrap around the address space.
/// Also `dst` must be properly aligned.
#[inline(always)]
unsafe fn volatile_set<T: Copy + Sized>(dst: *mut T, src: T, count: usize) {
    // TODO(tarcieri): use `volatile_set_memory` when stabilized
    //
    // Zero-sized types have nothing to write.
    if size_of::<T>() == 0 {
        return;
    }

    // Fast path: for 1-byte types (e.g. `u8`, `i8`, `bool` or `MaybeUninit<u8>`) the value's
    // bytes can be replicated across machine words and written with far fewer volatile stores.
    // This is the common case for byte buffers such as `Vec<u8>` and `String`.
    if size_of::<T>() == 1 {
        // Safety:
        //
        // `T` has size 1 and implements `Copy`, so `src` consists of exactly one initialized,
        // valid byte with no padding, and may be read as a `u8`.
        let byte = unsafe { *(&src as *const T).cast::<u8>() };

        // Safety:
        //
        // `dst` and `count` satisfy the requirements of `volatile_set_bytes` (which are the same
        // as this function's), and `byte` is a valid `u8`.
        unsafe { volatile_set_bytes(dst.cast::<u8>(), byte, count) };
        return;
    }

    for i in 0..count {
        // Safety:
        //
        // This is safe because there is room for at least `count` objects of type `T` in the
        // allocation pointed to by `dst`, because `count <= isize::MAX` and because
        // `dst.add(count)` must not wrap around the address space.
        let ptr = unsafe { dst.add(i) };

        // Safety:
        //
        // This is safe, because the pointer is valid and because `dst` is well aligned for `T` and
        // `ptr` is an offset of `dst` by a multiple of `size_of::<T>()` bytes.
        unsafe { ptr::write_volatile(ptr, src) };
    }
}

/// Volatile `memset` of `count` bytes at `dst` with `byte`.
///
/// Writes are performed a machine word at a time once the destination is word-aligned (with
/// leading/trailing single-byte writes to cover any misalignment), which issues substantially
/// fewer volatile stores than a byte-at-a-time loop.
///
/// # Safety
/// Same requirements as [`volatile_set`], for `T = u8`.
#[inline(always)]
unsafe fn volatile_set_bytes(dst: *mut u8, byte: u8, count: usize) {
    let word_size = size_of::<usize>();

    // Write single bytes until the destination is aligned for a `usize` store.
    let head = (word_size - (dst as usize % word_size)) % word_size;
    let head = head.min(count);
    for i in 0..head {
        // Safety:
        //
        // `i < head <= count`, so `dst.add(i)` is within the allocation, and `dst` is a valid
        // (align 1) pointer.
        unsafe { ptr::write_volatile(dst.add(i), byte) };
    }

    let word = usize::from_ne_bytes([byte; size_of::<usize>()]);
    let mut i = head;
    while i + word_size <= count {
        // Safety:
        //
        // `i + word_size <= count`, so `dst.add(i)` covers `word_size` in-bounds bytes, and it is
        // aligned for `usize` because `i` is a multiple of `word_size` past an aligned `head`.
        unsafe { ptr::write_volatile(dst.add(i).cast::<usize>(), word) };
        i += word_size;
    }

    while i < count {
        // Safety:
        //
        // `i < count`, so `dst.add(i)` is within the allocation.
        unsafe { ptr::write_volatile(dst.add(i), byte) };
        i += 1;
    }
}

/// Internal module used as support for `AssertZeroizeOnDrop`.
#[doc(hidden)]
pub mod __internal {
    use super::*;

    /// Auto-deref workaround for deriving `ZeroizeOnDrop`.
    pub trait AssertZeroizeOnDrop {
        fn zeroize_or_on_drop(self);
    }

    impl<T: ZeroizeOnDrop + ?Sized> AssertZeroizeOnDrop for &&mut T {
        fn zeroize_or_on_drop(self) {}
    }

    /// Auto-deref workaround for deriving `ZeroizeOnDrop`.
    pub trait AssertZeroize {
        fn zeroize_or_on_drop(&mut self);
    }

    impl<T: Zeroize + ?Sized> AssertZeroize for T {
        fn zeroize_or_on_drop(&mut self) {
            self.zeroize();
        }
    }
}