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
To use the
AmbientAuthroity type in an API:
AmbientAuthorityargument at the end of the argument list of any function that uses ambient authroity, and add a
# Ambient Authoritysection in the documentation comments for such functions explaining their use of ambient authority.
AmbientAuthoritytype from this crate, so that users can easily use the same version.
Ensure that all other
pubfunctions avoid using ambient authority, including mutable static state such as static
RwLock, or similar state, including
lazy_staticstate 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 run
cargo clippyor equivalent.