Struct macaroon::Macaroon

source · [−]

pub struct Macaroon { /* private fields */ }

Implementations

source

impl Macaroon

source

pub fn create(
 location: Option<String>,
 key: &MacaroonKey,
 identifier: ByteString
) -> Result<Macaroon>

Construct a macaroon, given a location and identifier, and a key to sign it with. You can use a bare str or &u8 containing arbitrary data with into to automatically generate a suitable key

Errors

Returns MacaroonError::IncompleteMacaroon if the identifier bytestring is empty

source

pub fn identifier(&self) -> ByteString

Returns a clone of the identifier for the macaroon

source

pub fn location(&self) -> Option<String>

Returns a clone the location for the macaroon

source

pub fn signature(&self) -> MacaroonKey

Returns the macaroon’s signature

The MacaroonKey type is used because it is the same size and format a signature, but the signature is not and should be used as a cryptographic key.

source

pub fn caveats(&self) -> Vec<Caveat>

source

pub fn first_party_caveats(&self) -> Vec<Caveat>

Retrieve a list of the first-party caveats for the macaroon

source

pub fn third_party_caveats(&self) -> Vec<Caveat>

Retrieve a list of the third-party caveats for the macaroon

source

pub fn add_first_party_caveat(&mut self, predicate: ByteString)

Add a first-party caveat to the macaroon

A first-party caveat is just a string predicate in some DSL which can be verified either by exact string match, or by using a function to parse the string and validate it (see Verifier for more info).

source

pub fn add_third_party_caveat(
    &mut self,
    location: &str,
    key: &MacaroonKey,
    id: ByteString
)

Add a third-party caveat to the macaroon

A third-party caveat is a caveat which must be verified by a third party using macaroons provided by them (referred to as “discharge macaroons”).

source

pub fn bind(&self, discharge: &mut Macaroon)

Bind a discharge macaroon to the original macaroon

When a macaroon with third-party caveats must be authorized, you send off to the various locations specified in the caveats, sending the caveat ID and key, and receive a set of one or more “discharge macaroons” which are used to verify the caveat. In order to ensure that the discharge macaroons aren’t re-used in some other context, we bind them to the original macaroon so that they can’t be used in a different context.

source

pub fn serialize(&self, format: Format) -> Result<String>

Serialize the macaroon using the serialization Format provided

For V1 and V2, the binary format will be encoded as URL-safe base64 with padding (base64::URL_SAFE). For V2JSON, the output will be JSON.

source

pub fn deserialize<T: AsRef<[u8]>>(token: T) -> Result<Macaroon>

Deserialize an encoded macaroon token, inferring the Format.

For V1 and V2 tokens, this assumes base64 encoding, in either “standard” or URL-safe encoding, with or without padding.

For V2JSON tokens, the token must begin with the { character with no preceeding whitespace.

Usage

use macaroon::Macaroon;

// '&str' gets automatically de-referenced to bytes ('&[u8]').
// 'b"byte-string"' or slice of 'u8' would also work.
let mac = Macaroon::deserialize("MDAxY2xvY2F0aW9uIGh0dHA6Ly9teWJhbmsvCjAwMjZpZGVudGlmaWVyIHdlIHVzZWQgb3VyIHNlY3JldCBrZXkKMDAxNmNpZCB0ZXN0ID0gY2F2ZWF0CjAwMmZzaWduYXR1cmUgGXusegRK8zMyhluSZuJtSTvdZopmDkTYjOGpmMI9vWcK")?;

let mac_v2json = Macaroon::deserialize(r#"{"v":2,"l":"http://example.org/","i":"keyid", "c":[{"i":"account = 3735928559"},{"i":"user = alice"}],"s64": "S-lnzR6gxrJrr2pKlO6bBbFYhtoLqF6MQqk8jQ4SXvw"}"#)?;

// expect this to fail; leading whitespace is not allowed
Macaroon::deserialize(r#"   {"v":2,"l":"http://example.org/","i":"keyid", "c":[{"i":"account = 3735928559"},{"i":"user = alice"}],"s64": "S-lnzR6gxrJrr2pKlO6bBbFYhtoLqF6MQqk8jQ4SXvw"}"#).unwrap_err();