0
Files
src/docs/rust-unsafe.md
Lukasz Anforowicz 8174ee0645 [rust] Add more UNSAFE_RUST_OWNERS + tweak related documentation.
Bug: 393410747
Change-Id: I10f8c71f40f001d25a4a1a3c746d112da5ba22b9
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6279505
Reviewed-by: Liza Burakova <liza@chromium.org>
Reviewed-by: Dustin Mitchell <djmitche@chromium.org>
Commit-Queue: Łukasz Anforowicz <lukasza@chromium.org>
Reviewed-by: Jonathan Hao <phao@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1422092}
2025-02-19 11:07:58 -08:00

108 lines
4.6 KiB
Markdown

# `unsafe` Rust Guidelines
## Code Review Policy {#code-review-policy}
All `unsafe` Rust code in Chromium needs to be reviewed and LGTM-ed by a
reviewer from `//third_party/rust/UNSAFE_RUST_OWNERS`.
This policy applies to both third-party code
(e.g. under `//third_party/rust`) and first-party code.
### How to request a review
To facilitate a code review please:
* For each new or modified `unsafe` block, function, `impl`, etc.,
add an unresolved "TODO: `unsafe` review" comment in Gerrit.
You can consider using `tools/crates/create_draft_comments.py` to streamline
creating such comments.
* Add `chrome-unsafe-rust-reviews@google.com` as a reviewer.
### Scope of review
Note that changes _anywhere_ in a crate that uses `unsafe` blocks may violate
the internal invariants on which those `unsafe` blocks rely. It is unrealistic
to require an `unsafe` review to re-audit all the
`unsafe` blocks each time a crate is updated, but the crate `OWNERS` and other
reviewers should be on the lookout for code changes which feel as though they
could affect invariants on which `unsafe` blocks rely.
### `OWNERS` files guidance
To require `unsafe` review for certain `.rs` files
(e.g. ones that use `unsafe` Rust)
you can forward from the file's `OWNERS` to
`//third_party/rust/UNSAFE_RUST_OWNERS`
(see comments in the latter for more details).
### Soft SLA
For incremental changes (including updating a minor version of a crate under
`//third_party/rust/chromium_crates_io`) the usual [Chromium responsiveness
expectations](cl_respect.md#expect-responsiveness) apply. (i.e. You should expect
reviewer input within 1 business day.)
For bulk changes (e.g. importing a new crate and its transitive dependencies)
the turnaround time may be longer. This depends mostly on the amount of
`unsafe` code. To streamline reviews and future maintainability, we ask you
kindly to prefer crates that do *not* use `unsafe` Rust code.
### Other notes
Bugs that track streamlining application of this policy are tracked under
the umbrella of https://crbug.com/393394872/dependencies.
## `cargo vet` Policy {#cargo-vet-policy}
Crates in `//third_party/rust/chromium_crates_io` need to be covered by `cargo
vet` audits. In other words, `tools/crates/run_cargo_vet.py check` should
always succeed (this is enforced by `//third_party/rust/PRESUBMIT.py`).
### Audit criteria required for most crates
Audit criteria required for a given crate depend on how the crate is used. The
criteria are written to
`third_party/rust/chromium_crates_io/supply-chain/config.toml` by
`tools/crates/run_gnrt.py vendor` based on whether
`third_party/rust/chromium_crates_io/gnrt_config.toml` declares that the crate
is meant to be used (maybe transitively) in a `safe`, `sandbox`, or `test`
environment. For example, to declare that a crate is `safe` to be used in the
browser process, it needs to be audited and certified to be `safe-to-deploy`,
`ub-risk-2` or lower, and either `does-not-implement-crypto` or `crypto-safe`.
Note that some audits can be done by any engineer ("ub-risk-0" and
"safe-to-run") while others will require specialists from the
`unsafe-rust-in-chrome@google.com` group (see the ["Code Review Policy"
above](#code-review-policy). More details about audit criteria and the required
expertise are explained in the
[auditing_standards.md](https://github.com/google/rust-crate-audits/blob/main/auditing_standards.md),
which also provides guidance for conducting delta audits.
### Some crates don't require an audit
Chromium implicitly trusts certain crate publishers. Currently
there are two scenarios where such trust relationship may be established:
* Trusting crates authored and maintained under https://github.com/rust-lang/
(e.g. `libc`, `hashbrown`), because they are closely related to the Rust
toolchain (i.e. the same group managed and publishes `rustc`,
`rustfmt`, `cargo`, `rustup`, etc.).
* Trusting crates that are part of an OS SDK (e.g. `windows-...` crates).
Chromium uses both our own audits
(stored in `third_party/rust/chromium_crates_io/supply-chain/audits.toml`)
as well as audits imported from other parts of Google
(e.g. Android, Fuchsia, etc.). This means that adding a new crate does not
necessarily require a new audit if the crate has already been audited by
other projects (in this case, `cargo vet` will record the imported audit
in the `third_party/rust/chromium_crates_io/supply-chain/imports.lock` file).
### How to run `cargo vet` in Chromium
See
[Cargo Vet documentation](https://mozilla.github.io/cargo-vet/recording-audits.html)
for how to record the audit in `audits.toml`.
The `tools/crates/run_cargo_vet.py` may be used to invoke Chromium's copy of
`cargo-vet`.