Crate zeroize[][src]

Securely zero memory using core or OS intrinsics. This crate wraps facilities specifically designed to securely zero memory in a common, safe API: secure_zero_memory().

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: instead it only invokes intrinsics (either rustc/LLVM or OS) with a documented contract assuring the caller that after the intrinsic is invoked, memory will be zeroed 100% of the time.

No insecure fallbacks. No dependencies. #![no_std]. No functionality besides securely zeroing memory.

This crate has one job and one function: secure_zero_memory(), and it provides the thinnest portable wrapper for secure zeroing intrinsics.

If it can't find a way to securely zero memory, it will refuse to compile. Don't worry about that though: it supports almost every tier 1 and 2 Rust platform (and even most of tier 3!). See below for compatiblity.

Platform Support / Intrinsics

This crate provides wrappers for the following intrinsics:

Notable unsupported platforms at present: Fuchsia, Redox. PRs accepted!

Enable the nightly cargo feature to take advantage of the Rust intrinsic rather than using FFI to invoke OS intrinsics (requires a nightly rustc):

Cargo.toml example:

[dependencies.zeroize]
version = "0"
features = ["nightly"]

‡ NOTE: Linux w\ glibc versions earlier than 2.2.5 (i.e. when the linux-backport cargo feature is enabled) uses cc as a build dependency to link explicit_bzero.c, a backport of the method glibc uses to implement explicit_bzero().

Stack/Heap Zeroing Notes

This crate can be used to zero values from either the stack or the heap.

However, be aware that Rust's current memory semantics (e.g. move) can leave copies of data in memory, and there isn't presently a good solution for ensuring all copies of data on the stack are properly cleared.

The Pin RFC proposes a method for avoiding this. See also: https://github.com/rust-lang/rust/issues/17046.

What about: clearing registers, mlock, mprotect, etc?

This crate is laser focused on being a simple, unobtrusive crate for zeroing memory reliably.

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.

Other memory protection mechanisms are interesting and useful, but often overkill (e.g. defending against RAM scraping or attackers with swap access). There are already many other crates that already implement more sophisticated memory protections.

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.

Functions

secure_zero_memory

Zero out memory using explicit_bzero().