|
| 1 | +# Zerocopy's Policies |
| 2 | + |
| 3 | +## Soundness |
| 4 | + |
| 5 | +Zerocopy is expressly designed for use in security-critical contexts. It is used |
| 6 | +in hardware security firmware, cryptographic implementations, hypervisors, and |
| 7 | +more. We understand that software in these contexts has a very high bar for |
| 8 | +correctness, and we take our responsibility to meet that bar very seriously. |
| 9 | + |
| 10 | +This section describes policies which are designed to ensure the correctness and |
| 11 | +soundness of our code and prevent regressions. |
| 12 | + |
| 13 | +### Forwards-compatibility |
| 14 | + |
| 15 | +Rust does not currently have a formal memory model. As such, while Rust provides |
| 16 | +guarantees about the semantics of some operations, the semantics of many |
| 17 | +operations is up in the air and subject to change. |
| 18 | + |
| 19 | +Zerocopy strives to ensure that our code - and code emitted by our custom |
| 20 | +derives - is sound under any version of Rust as early as our MSRV, and will |
| 21 | +continue to be sound under any future version of Rust. The policies in this |
| 22 | +section are designed to help ensure that we live up to this goal. |
| 23 | + |
| 24 | +### Safety comments |
| 25 | + |
| 26 | +Each non-test `unsafe` block must be annotated with a "safety comment" which |
| 27 | +provides a rationale for its soundness. In order to ensure that our soundness is |
| 28 | +forwards-compatible, safety comments must satisfy the following criteria: |
| 29 | +- Safety comments must constitute a (possibly informal) proof that all of Rust's |
| 30 | + soundness rules are upheld. |
| 31 | +- Safety comments must only rely for their correctness on statements which |
| 32 | + appear in the stable versions of the [Rust Reference] or standard library |
| 33 | + documentation (ie, the docs for [core], [alloc], and [std]); arguments which |
| 34 | + rely on text from the beta or nightly versions of these documents are not |
| 35 | + considered complete. |
| 36 | +- All statements from the Reference or standard library documentation which are |
| 37 | + relied upon for soundness must be quoted in the safety comment. This ensures |
| 38 | + that there is no ambiguity as to what aspect of the text is being cited. This |
| 39 | + is especially important in cases where the text of these documents changes in |
| 40 | + the future. Such changes are of course required to be backwards-compatible, |
| 41 | + but may change the manner in which a particular guarantee is explained. |
| 42 | + |
| 43 | +We use the [`clippy::undocumented_unsafe_blocks`] lint to ensure that `unsafe` |
| 44 | +blocks cannot be added without a safety comment. Note that there are a few |
| 45 | +outstanding uncommented `unsafe` blocks which are tracked in [#429]. Our goal is |
| 46 | +to reach 100% safety comment coverage and not regress once we've reached it. |
| 47 | + |
| 48 | +[Rust Reference]: https://doc.rust-lang.org/reference/ |
| 49 | +[core]: https://doc.rust-lang.org/stable/core/ |
| 50 | +[alloc]: https://doc.rust-lang.org/stable/alloc/ |
| 51 | +[std]: https://doc.rust-lang.org/stable/std/ |
| 52 | +[`clippy::undocumented_unsafe_blocks`]: https://rust-lang.github.io/rust-clippy/master/index.html#/undocumented_unsafe_blocks |
| 53 | +[#429]: https://github.com/google/zerocopy/issues/429 |
| 54 | + |
| 55 | +#### Exceptions to our safety comment policy |
| 56 | + |
| 57 | +In rare circumstances, the soundness of an `unsafe` block may depend upon |
| 58 | +semantics which are widely agreed upon but not formally guaranteed. In order to |
| 59 | +avoid slowing down zerocopy's development to an unreasonable degree, a safety |
| 60 | +comment may violate our safety comment policy so long as all of the following |
| 61 | +hold: |
| 62 | +- The safety comment's correctness may rely on semantics which are not |
| 63 | + guaranteed in official Rust documentation *so long as* a member of the Rust |
| 64 | + team has articulated in an official communication (e.g. a comment on a Rust |
| 65 | + GitHub repo) that Rust intends to guarantee particular semantics. |
| 66 | +- There exists an active effort to formalize the guarantee in Rust's official |
| 67 | + documentation. |
| 68 | + |
| 69 | +### Target architecture support |
| 70 | + |
| 71 | +Zerocopy bases its soundness on guarantees made about the semantics of Rust |
| 72 | +which appear in the Rust Reference or standard library documentation; zerocopy |
| 73 | +is sound so long as these guarantees hold. There are known cases in which these |
| 74 | +guarantees do not hold on certain target architectures (see |
| 75 | +[rust-lang/unsafe-code-guidelines#461]); on such target architectures, zerocopy |
| 76 | +may be unsound. We consider it outside of zerocopy's scope to reason about these |
| 77 | +cases. Zerocopy makes no effort maintain soundness in cases where Rust's |
| 78 | +documented guarantees do not hold. |
| 79 | + |
| 80 | +[rust-lang/unsafe-code-guidelines#461]: https://github.com/rust-lang/unsafe-code-guidelines/issues/461 |
| 81 | + |
| 82 | +## MSRV |
| 83 | + |
| 84 | +Our minimum supported Rust version (MSRV) is encoded in our `Cargo.toml` file. |
| 85 | +We consider an increase in MSRV to be a semver-breaking change, and will only |
| 86 | +increase our MSRV during semver-breaking version changes (e.g., 0.1 -> 0.2, 1.0 |
| 87 | +-> 2.0, etc). |
0 commit comments