1 unstable release
0.1.0 | Mar 25, 2020 |
---|
#4 in #auditing
11KB
75 lines
Provides annotations for describing and auditing usages of unsafe
code in Rust.
This crate has no effect on the compilation or runtime behavior of Rust code. Its purpose is to allow developers to annotate Rust code with information about why unsafe code is used, and to enable automated tools for auditing code bases that use unsafe code.
Instead of this:
unsafe {
// Scary interop code:
let ptr: *mut libc::c_void = allocate_foreign_object();
use_foreign_object(ptr, 42);
free_foreign_object(ptr);
}
Developers can do this:
use unsafety::{unsafe_because, USES_FOREIGN_CODE};
unsafe_because! {
USES_FOREIGN_CODE => {
// Scary interop code:
let ptr: *mut libc::c_void = allocate_foreign_object();
use_foreign_object(ptr, 42);
free_foreign_object(ptr);
}
}
Type safety and concurrency safety are the key benefits of Rust. Because
these safety properties depend on all components in that system correctly
respecting those properties, even unsafe code, it is crucial that unsafe
code nevertheless be correct code. This crate is intended to help meet
that goal, by allowing developers to describe why code does what it does,
with respect to unsafe code, and to make it easy to audit those
descriptions.
Annotating reasons
The unsafe_because
macro requires you to give a reason, and it allows you
to give additional, optional information. You can add the following to
any invocation of unsafe_because
. (All of these can be repeated.)
reason.owner("foo")
: Identifies an owner or expert in this part of the design.reason.bug("...")
: An identifier in a bug-tracking system. This is typically a URL or a bug number.reason.link("http://...")
: A link to any relevant web page, such as a design document.reason.tag("key", "value")
: Allows you to specify arbitrary key-value pairs.
Reusing reasons
Instead of re-stating the same reason repeatedly, reasons can be defined as constants and reused. This is useful when a reason has annotations, which would be cumbersome to repeat at every usage. Example:
use unsafety::{UnsafeReason, IMPLEMENTS_DEVICE_DRIVER, unsafe_because};
const IMPLEMENTS_FANCY_NETWORK_DRIVER: UnsafeReason = IMPLEMENTS_DEVICE_DRIVER
.bug("some_bug_link")
.owner("foo")
.owner("bar")
.link("https://.../some_design_doc.html");
unsafe_because! {
IMPLEMENTS_FANCY_NETWORK_DRIVER => {
// ...
}
}
unsafe_because! {
IMPLEMENTS_FANCY_NETWORK_DRIVER => {
// ... even more code ...
}
}
Combining reasons
Sometimes a single unsafe
block has more than reason for using unsafe
code.
If possible, developers should split such blocks into separate blocks and use
separate justifications for them. However, at times that is not possible.
unsafe_because!
allows you to provide a list of reasons, within square brackets.
Example:
use unsafety::{PERFORMANCE, IMPLEMENTS_DEVICE_DRIVER, unsafe_because};
// Some code has more than one reason for requiring unsafe code.
unsafe_because! {
[PERFORMANCE, IMPLEMENTS_DEVICE_DRIVER] =>
println!("Super fast and scary (but correct) code goes here.");
}
TODO
- Improve the list of standard reasons.
- Auditing tools.
- Needs macros for defining unsafe traits and unsafe function signatures, not just unsafe code blocks.
Future direction
It is possible that some future version of Rust could verify that a particular
set of usages of unsafe
meet some requirement. For example, it might be
useful to allow unsafe code for the reason of accessing a device driver, but
no other reason, within a given crate. unsafe_because
could allow developers
to encode that knowledge now, rather than trying to re-discover that knowledge
after a large, mature component has been developed.