| 1 |
<!-- Copyright 2023 The Fuchsia Authors |
| 2 |
|
| 3 |
Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0 |
| 4 |
<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT |
| 5 |
license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option. |
| 6 |
This file may not be copied, modified, or distributed except according to |
| 7 |
those terms. --> |
| 8 |
|
| 9 |
# Zerocopy's Policies |
| 10 |
|
| 11 |
## Soundness |
| 12 |
|
| 13 |
Zerocopy is expressly designed for use in security-critical contexts. It is used |
| 14 |
in hardware security firmware, cryptographic implementations, hypervisors, and |
| 15 |
more. We understand that software in these contexts has a very high bar for |
| 16 |
correctness, and we take our responsibility to meet that bar very seriously. |
| 17 |
|
| 18 |
This section describes policies which are designed to ensure the correctness and |
| 19 |
soundness of our code and prevent regressions. |
| 20 |
|
| 21 |
### Forwards-compatibility |
| 22 |
|
| 23 |
Rust does not currently have a formal memory model. As such, while Rust provides |
| 24 |
guarantees about the semantics of some operations, the semantics of many |
| 25 |
operations is up in the air and subject to change. |
| 26 |
|
| 27 |
Zerocopy strives to ensure that our code - and code emitted by our custom |
| 28 |
derives - is sound under any version of Rust as early as our MSRV, and will |
| 29 |
continue to be sound under any future version of Rust. The policies in this |
| 30 |
section are designed to help ensure that we live up to this goal. |
| 31 |
|
| 32 |
### Safety comments |
| 33 |
|
| 34 |
Each non-test `unsafe` block must be annotated with a "safety comment" which |
| 35 |
provides a rationale for its soundness. In order to ensure that our soundness is |
| 36 |
forwards-compatible, safety comments must satisfy the following criteria: |
| 37 |
- Safety comments must constitute a (possibly informal) proof that all of Rust's |
| 38 |
soundness rules are upheld. |
| 39 |
- Safety comments must only rely for their correctness on statements which |
| 40 |
appear in the stable versions of the [Rust Reference] or standard library |
| 41 |
documentation (ie, the docs for [core], [alloc], and [std]); arguments which |
| 42 |
rely on text from the beta or nightly versions of these documents are not |
| 43 |
considered complete. |
| 44 |
- All statements from the Reference or standard library documentation which are |
| 45 |
relied upon for soundness must be quoted in the safety comment. This ensures |
| 46 |
that there is no ambiguity as to what aspect of the text is being cited. This |
| 47 |
is especially important in cases where the text of these documents changes in |
| 48 |
the future. Such changes are of course required to be backwards-compatible, |
| 49 |
but may change the manner in which a particular guarantee is explained. |
| 50 |
|
| 51 |
We use the [`clippy::undocumented_unsafe_blocks`] lint to ensure that `unsafe` |
| 52 |
blocks cannot be added without a safety comment. Note that there are a few |
| 53 |
outstanding uncommented `unsafe` blocks which are tracked in [#429]. Our goal is |
| 54 |
to reach 100% safety comment coverage and not regress once we've reached it. |
| 55 |
|
| 56 |
[Rust Reference]: https://doc.rust-lang.org/reference/ |
| 57 |
[core]: https://doc.rust-lang.org/stable/core/ |
| 58 |
[alloc]: https://doc.rust-lang.org/stable/alloc/ |
| 59 |
[std]: https://doc.rust-lang.org/stable/std/ |
| 60 |
[`clippy::undocumented_unsafe_blocks`]: https://rust-lang.github.io/rust-clippy/master/index.html#/undocumented_unsafe_blocks |
| 61 |
[#429]: https://github.com/google/zerocopy/issues/429 |
| 62 |
|
| 63 |
#### Exceptions to our safety comment policy |
| 64 |
|
| 65 |
In rare circumstances, the soundness of an `unsafe` block may depend upon |
| 66 |
semantics which are widely agreed upon but not formally guaranteed. In order to |
| 67 |
avoid slowing down zerocopy's development to an unreasonable degree, a safety |
| 68 |
comment may violate our safety comment policy so long as all of the following |
| 69 |
hold: |
| 70 |
- The safety comment's correctness may rely on semantics which are not |
| 71 |
guaranteed in official Rust documentation *so long as* a member of the Rust |
| 72 |
team has articulated in an official communication (e.g. a comment on a Rust |
| 73 |
GitHub repo) that Rust intends to guarantee particular semantics. |
| 74 |
- There exists an active effort to formalize the guarantee in Rust's official |
| 75 |
documentation. |
| 76 |
|
| 77 |
### Target architecture support |
| 78 |
|
| 79 |
Zerocopy bases its soundness on guarantees made about the semantics of Rust |
| 80 |
which appear in the Rust Reference or standard library documentation; zerocopy |
| 81 |
is sound so long as these guarantees hold. There are known cases in which these |
| 82 |
guarantees do not hold on certain target architectures (see |
| 83 |
[rust-lang/unsafe-code-guidelines#461]); on such target architectures, zerocopy |
| 84 |
may be unsound. We consider it outside of zerocopy's scope to reason about these |
| 85 |
cases. Zerocopy makes no effort maintain soundness in cases where Rust's |
| 86 |
documented guarantees do not hold. |
| 87 |
|
| 88 |
[rust-lang/unsafe-code-guidelines#461]: https://github.com/rust-lang/unsafe-code-guidelines/issues/461 |
| 89 |
|
| 90 |
## MSRV |
| 91 |
|
| 92 |
<!-- Our policy used to be simply that MSRV was a breaking change in all |
| 93 |
circumstances. This implicitly relied on syn having the same MSRV policy, which |
| 94 |
it does not. See #1085 and #1088. --> |
| 95 |
|
| 96 |
Without the `derive` feature enabled, zerocopy's minimum supported Rust version |
| 97 |
(MSRV) is encoded the `package.rust-version` field in its `Cargo.toml` file. For |
| 98 |
zerocopy, we consider an increase in MSRV to be a semver-breaking change, and |
| 99 |
will only increase our MSRV during semver-breaking version changes (e.g., 0.1 -> |
| 100 |
0.2, 1.0 -> 2.0, etc). |
| 101 |
|
| 102 |
For zerocopy with the `derive` feature enabled, and for the zerocopy-derive |
| 103 |
crate, we inherit the maximum MSRV any of our dependencies. As of this writing |
| 104 |
(2024-10-03), at least one dependency (syn) does *not* consider MSRV increases |
| 105 |
to be semver-breaking changes. Thus, using the `derive` feature may result in |
| 106 |
the effective MSRV increasing within a semver version train. |
| 107 |
|
| 108 |
## Yanking |
| 109 |
|
| 110 |
Whenever a bug or regression is identified, we will yank any affected versions |
| 111 |
which are part of the current version train. For example, if the most recent |
| 112 |
version is 0.10.20 and a bug is uncovered, we will release a fix in 0.10.21 and |
| 113 |
yank all 0.10.X versions which are affected. We *may* also yank versions in |
| 114 |
previous version trains on a case-by-case basis, but we don't guarantee it. |
| 115 |
|
| 116 |
For information about a particular yanked or un-yanked version, see our [yank |
| 117 |
log][yank-log]. |
| 118 |
|
| 119 |
[yank-log]: https://github.com/google/zerocopy/blob/main/CHANGELOG.md#yanks-and-regressions |