Zerocopy is expressly designed for use in security-critical contexts. It is used in hardware security firmware, cryptographic implementations, hypervisors, and more. We understand that software in these contexts has a very high bar for correctness, and we take our responsibility to meet that bar very seriously.
This section describes policies which are designed to ensure the correctness and soundness of our code and prevent regressions.
Rust does not currently have a formal memory model. As such, while Rust provides guarantees about the semantics of some operations, the semantics of many operations is up in the air and subject to change.
Zerocopy strives to ensure that our code - and code emitted by our custom derives - is sound under any version of Rust as early as our MSRV, and will continue to be sound under any future version of Rust. The policies in this section are designed to help ensure that we live up to this goal.
Each non-test unsafe block must be annotated with a "safety comment" which
provides a rationale for its soundness. In order to ensure that our soundness is
forwards-compatible, safety comments must satisfy the following criteria:
- Safety comments must constitute a (possibly informal) proof that all of Rust's soundness rules are upheld.
- Safety comments must only rely for their correctness on statements which appear in the stable versions of the Rust Reference or standard library documentation (ie, the docs for core, alloc, and std); arguments which rely on text from the beta or nightly versions of these documents are not considered complete.
- All statements from the Reference or standard library documentation which are relied upon for soundness must be quoted in the safety comment. This ensures that there is no ambiguity as to what aspect of the text is being cited. This is especially important in cases where the text of these documents changes in the future. Such changes are of course required to be backwards-compatible, but may change the manner in which a particular guarantee is explained.
We use the clippy::undocumented_unsafe_blocks lint to ensure that unsafe
blocks cannot be added without a safety comment. Note that there are a few
outstanding uncommented unsafe blocks which are tracked in #429. Our goal is
to reach 100% safety comment coverage and not regress once we've reached it.
In rare circumstances, the soundness of an unsafe block may depend upon
semantics which are widely agreed upon but not formally guaranteed. In order to
avoid slowing down zerocopy's development to an unreasonable degree, a safety
comment may violate our safety comment policy so long as all of the following
hold:
- The safety comment's correctness may rely on semantics which are not guaranteed in official Rust documentation so long as a member of the Rust team has articulated in an official communication (e.g. a comment on a Rust GitHub repo) that Rust intends to guarantee particular semantics.
- There exists an active effort to formalize the guarantee in Rust's official documentation.
Zerocopy bases its soundness on guarantees made about the semantics of Rust which appear in the Rust Reference or standard library documentation; zerocopy is sound so long as these guarantees hold. There are known cases in which these guarantees do not hold on certain target architectures (see rust-lang/unsafe-code-guidelines#461); on such target architectures, zerocopy may be unsound. We consider it outside of zerocopy's scope to reason about these cases. Zerocopy makes no effort maintain soundness in cases where Rust's documented guarantees do not hold.
Without the derive feature enabled, zerocopy's minimum supported Rust version
(MSRV) is encoded the package.rust-version field in its Cargo.toml file. For
zerocopy, we consider an increase in MSRV to be a semver-breaking change, and
will only increase our MSRV during semver-breaking version changes (e.g., 0.1 ->
0.2, 1.0 -> 2.0, etc).
For zerocopy with the derive feature enabled, and for the zerocopy-derive
crate, we inherit the maximum MSRV any of our dependencies. As of this writing
(2024-10-03), at least one dependency (syn) does not consider MSRV increases
to be semver-breaking changes. Thus, using the derive feature may result in
the effective MSRV increasing within a semver version train.
Whenever a bug or regression is identified, we will yank any affected versions which are part of the current version train. For example, if the most recent version is 0.10.20 and a bug is uncovered, we will release a fix in 0.10.21 and yank all 0.10.X versions which are affected. We may also yank versions in previous version trains on a case-by-case basis, but we don't guarantee it.
For information about a particular yanked or un-yanked version, see our yank log.