In capability-based security contexts, ambient authority means anything a program can do that interacts with the outside world that isn't represented by a handle.
This crate defines an empty function, ambient_authority
, which returns a
value of type AmbientAuthority
. This is an empty type used in function
signatures to declare that they use ambient authority. When an API uses
AmbientAuthority
in all functions that use ambient authority, one can quickly
locate all the calls to such functions by scanning for calls to
ambient_authority
.
To use the AmbientAuthroity
type in an API:
-
Add an
AmbientAuthority
argument at the end of the argument list of any function that uses ambient authroity, and add a# Ambient Authority
section in the documentation comments for such functions explaining their use of ambient authority. -
Re-export the
ambient_authority
function andAmbientAuthority
type from this crate, so that users can easily use the same version. -
Ensure that all other
pub
functions avoid using ambient authority, including mutable static state such as staticAtomic
,Cell
,RefCell
,Mutex
,RwLock
, or similar state, includingonce_cell
orlazy_static
state with initialization that uses ambient authority.
For example, see the cap-std crate's API, which follows these guidelines.
One of the cool things about capability-oriented APIs is that programs don't need to be pure to take advantage of them. That said, for programs which do which to aim for purity, this repository has a clippy configuration which can help. To use it:
-
Manually ensure that all immediate dependencies follow the above convention.
-
Copy the clippy.toml file into the top level source directory, add
#![deny(clippy::disallowed_methods)]
to the root module (main.rs or lib.rs), and runcargo clippy
or equivalent.