Fearless Unsafe. A More User-friendly Document for Unsafe Rust Programming Base on Refined Safety Properties

TL;DR

The paper tackles the challenge of vague and inconsistent safety guidance for Unsafe Rust. It defines a structured set of Safety Properties (13 properties with 22 sub-properties) learned from 438 unsafe standard-library APIs, labels each unsafe API accordingly, and analyzes inter-property correlations. It then reorganizes unsafe API documentation, and integrates revised safety documents into a rust-analyzer plugin to assist developers in writing unsafe code more safely. The study validates practical impact by classifying Rust CVEs up to early 2024 by safety properties and by analyzing crates.io usage, showing substantial real-world relevance of the safety-property framework. Overall, the work advances standardized, developer-friendly Unsafe Rust documentation and provides a concrete path toward broader adoption via tooling support and empirical benchmarks.

Abstract

Rust, a popular systems-level programming language, has garnered widespread attention due to its features of achieving run-time efficiency and memory safety. With an increasing number of real-world projects adopting Rust, understanding how to assist programmers in correctly writing unsafe code poses a significant challenge. Based on our observations, the current standard library has many unsafe APIs, but their descriptions are not uniform, complete, and intuitive, especially in describing safety requirements. Therefore, we advocate establishing a systematic category of safety requirements for revising those documents. In this paper, we extended and refined our study in ICSE 2024. We defined a category of Safety Properties (22 items in total) that learned from the documents of unsafe APIs in the standard library. Then, we labeled all public unsafe APIs (438 in total) and analyzed their correlations. Based on the safety properties, we reorganized all the unsafe documents in the standard library and designed a consultation plugin into rust-analyzer as a complementary tool to assist Rust developers in writing unsafe code. To validate the practical significance, we categorized the root causes of all Rust CVEs up to 2024-01-31 (419 in total) into safety properties and further counted the real-world usage of unsafe APIs in the crates.io ecosystem.

Figures (8)

• Figure 1: Example of an unsafe API in Rust std. Listing \ref{['list:take']} provides the source code of an unsafe method of struct ManuallyDrop<T>. Listing \ref{['list:takedoc']} extracts the document in Rust 1.75. This document introduces the usage, functionality, and safety requirements to comply with by using a section labeled Safety.
• Figure 2: Two instances of non-intuitiveness in the std unsafe documents. These two functions are named read, with identical functionality and signature. The document in List \ref{['list:link1']} requires a jump to List \ref{['list:link2']}. However, List \ref{['list:link2']} contains a hyperlink leading to a secondary jump toward the informal definition of valid pointer.
• Figure 3: Correlation matrices for both the large and small datasets. Each figure only includes the sections with weak correlation and above (correlation greater than 0.20).
• Figure 4: The example of a revised document compared with the native document for unsafe API ptr::read. The safety property document has a unique identifier and matches the safety properties, parameters, and native document slices, providing a more structured format. Additionally, it eliminates the secondary link jumps, making it more intuitive.
• Figure 5: The workflow of the plugin. This tool implants safety property documents into the hover component of the rust-analyzer, providing users with safety prompts when hovering over unsafe functions.