103 lines
5.2 KiB
Markdown
103 lines
5.2 KiB
Markdown
<!-- Copyright 2023 The Fuchsia Authors
|
|
|
|
Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
|
|
<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
|
|
license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
|
|
This file may not be copied, modified, or distributed except according to
|
|
those terms. -->
|
|
|
|
# Zerocopy's Policies
|
|
|
|
## Soundness
|
|
|
|
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.
|
|
|
|
### Forwards-compatibility
|
|
|
|
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.
|
|
|
|
### Safety comments
|
|
|
|
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.
|
|
|
|
[Rust Reference]: https://doc.rust-lang.org/reference/
|
|
[core]: https://doc.rust-lang.org/stable/core/
|
|
[alloc]: https://doc.rust-lang.org/stable/alloc/
|
|
[std]: https://doc.rust-lang.org/stable/std/
|
|
[`clippy::undocumented_unsafe_blocks`]: https://rust-lang.github.io/rust-clippy/master/index.html#/undocumented_unsafe_blocks
|
|
[#429]: https://github.com/google/zerocopy/issues/429
|
|
|
|
#### Exceptions to our safety comment policy
|
|
|
|
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.
|
|
|
|
### Target architecture support
|
|
|
|
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.
|
|
|
|
[rust-lang/unsafe-code-guidelines#461]: https://github.com/rust-lang/unsafe-code-guidelines/issues/461
|
|
|
|
## MSRV
|
|
|
|
Our minimum supported Rust version (MSRV) is encoded in our `Cargo.toml` file.
|
|
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).
|
|
|
|
## Yanking
|
|
|
|
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.
|