Annotating and Auditing the Safety Properties of Unsafe Rust
For Rust developers, this work provides a systematic approach to reduce undefined behavior risks by standardizing safety documentation, though it is incremental as it formalizes existing practices.
The paper addresses the lack of standardized safety documentation in Rust's unsafe code by proposing a tag-centric methodology for auditing consistency and completeness. Applied to the Rust standard library, it fixed documentation issues on 27 APIs with 61 safety tags and found tags applicable to 96.1% of public unsafe APIs.
In Rust, unsafe code is the sole source of potential undefined behaviors. To avoid misuse, Rust developers should clarify the safety properties for each unsafe API. However, the community currently lacks a key standard for safety documentation: existing safety comments in the source code and safety documentation can be ad hoc and incomplete. This paper presents a tag-centric methodology for auditing the consistency and completeness of safety documentation. We first derive a taxonomy of Safety Tags to formalize natural-language requirements. Second, because API soundness frequently relies on struct invariants, we propose a set of empirical rules to systematically audit the structural consistency of safety documentation. We implemented this methodology in safety-tool, a static linter that automatically enforces structural consistency between local safety annotations and callee requirements. Our approach was applied to the Rust standard library, fixing documentation issues on 27 APIs with 61 safety tags and identifying safety tags that are applicable to 96.1% of the public unsafe APIs in libstd. Furthermore, we have formalized the tagging idea through a Rust RFC to the wider community. We believe that the approach establishes a standardized practice of safety documentation and helps significantly reduce safety perils.