Struct Macaroon 

pub struct Macaroon { /* private fields */ }

A Macaroon has a location, identifier, signature, and caveats.

Implementations

impl Macaroon

pub fn new( location: impl Into<String>, identifier: impl Into<String>, secret: Secret, ) -> Result<Self, Error>

Mint a new macaroon for the location, identifier, and root secret.

pub fn location(&self) -> &str

The location of the macaroon. This will be provided to the loader. Intentionally not protected by the signature; it should be a hint to where the macaroon came from.

pub fn identifier(&self) -> &str

The identifier for the macaroon. This is how the server will translate the macaroon to its root secret.

pub fn signature(&self) -> &Secret

The signature of the macaroon. Keep it secret or any derived macaroons can be leaked.

pub fn to_bytes(&self) -> Vec<u8>

Encode this macaroon to its prototk byte representation.

pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error>

Decode exactly one macaroon from its prototk byte representation.

Trailing bytes are rejected.

pub fn caveat_count(&self) -> usize

The number of caveats attached to the macaroon.

pub fn caveats( &self, ) -> impl ExactSizeIterator<Item = CaveatRef<'_>> + DoubleEndedIterator + '_

Iterate over read-only caveat views.

pub fn has_caveats(&self) -> bool

Returns true if this macaroon has any caveats.

pub fn add_exact_string(&mut self, what: impl Into<String>) -> Result<(), Error>

Add a caveat that must match exactly.

pub fn add_fact( &mut self, name: &'static str, value: impl Display, ) -> Result<(), Error>

Add a canonical exact-string fact caveat.

The fact name is static so application code controls the vocabulary. The caveat string is formatted as "{name} = {value}".

pub fn add_expires(&mut self, when: u64) -> Result<(), Error>

Add a caveat that expires the macaroon after when.

pub fn add_expires_at(&mut self, when: SystemTime) -> Result<(), Error>

Add an expiration caveat from a SystemTime.

pub fn add_not_before(&mut self, when: u64) -> Result<(), Error>

Add a caveat that rejects verifier times before when.

pub fn add_not_before_at(&mut self, when: SystemTime) -> Result<(), Error>

Add a not-before caveat from a SystemTime.

pub fn add_ttl(&mut self, ttl: Duration) -> Result<(), Error>

Add a fresh expiration caveat for ttl after the current system time.

This appends a new caveat. It does not replace earlier expiration caveats, so the effective expiration remains the minimum of all expiration caveats.

pub fn add_ttl_from( &mut self, now: SystemTime, ttl: Duration, ) -> Result<(), Error>

Add a fresh expiration caveat for ttl after now.

This is useful for deterministic tests and for applications that already captured request time.

pub fn add_third_party_caveat( &mut self, location: impl Into<String>, identifier: impl Into<String>, secret: ThirdPartySecret, ) -> Result<(), Error>

Add a third party caveat. Provide signature() to ask the third party to generate the identifier and secret.

The location is an unsigned routing hint. Verification depends on the identifier, encrypted verification-key material, and signature chain.

pub fn bind_discharge(&self, discharge: &mut Macaroon) -> Result<(), Error>

Bind a macaroon to the request to make sure discharge macaroons cannot be used in other contexts.

pub fn bind_discharge_owned( &self, discharge: Macaroon, ) -> Result<Macaroon, Error>

Bind and return a single discharge macaroon.

This is the owned-value form of Macaroon::bind_discharge.

pub fn bind_discharges(&self, discharges: &mut [Macaroon]) -> Result<(), Error>

Bind every discharge macaroon in place.

pub fn bind_discharges_owned<I>( &self, discharges: I, ) -> Result<Vec<Macaroon>, Error>

where I: IntoIterator<Item = Macaroon>,

Bind owned discharge macaroons and return them as a vector.

pub fn covering_set( &self, candidates: &[Macaroon], ) -> Result<Vec<Macaroon>, Error>

Assemble the transitive discharge cover from candidates.

The returned set contains discharge macaroons only, not self. Selection is based only on public macaroon data: locations, identifiers, and third-party caveat references. This does not verify signatures, decrypt third-party secrets, or prove that the selected macaroons satisfy their caveats; pass the returned set to Verifier::verify for that.

If more than one candidate has the same public location and identifier, the first candidate is selected because public data cannot distinguish which proof is valid.

pub fn covering_set_refs<'a>( &self, candidates: &'a [Macaroon], ) -> Result<Vec<&'a Macaroon>, Error>

Assemble the transitive discharge cover from candidates, returning references into the candidate slice.

See Macaroon::covering_set for selection semantics.

Trait Implementations

impl Clone for Macaroon

fn clone(&self) -> Macaroon

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Macaroon

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Macaroon

fn default() -> Macaroon

Returns the “default value” for a type.

impl Eq for Macaroon

impl<'prototk> FieldPackHelper<'prototk, message<Macaroon>> for Macaroon

fn field_pack_sz(&self, tag: &Tag) -> usize

The size of encoding self with tag.

fn field_pack(&self, tag: &Tag, out: &mut [u8])

Pack the tag into the output buffer.

impl<'prototk> FieldUnpackHelper<'prototk, message<Macaroon>> for Macaroon

fn merge_field(&mut self, proto: message<Macaroon>)

Merge the proto into self.

impl From<message<Macaroon>> for Macaroon

fn from(proto: message<Self>) -> Self

Converts to this type from the input type.

impl<'prototk> Message<'prototk> for Macaroon

impl Packable for Macaroon

fn pack_sz(&self) -> usize

pack_sz returns the number of bytes required to serialize the Packable object.

fn pack(&self, buf: &mut [u8])

pack fills in the buffer out with the packed binary representation of the Packable object. The implementor is responsible to ensure that out is exactly pack_sz() bytes and implementations are encouraged to assert this.

fn stream<W: Write>(&self, writer: &mut W) -> Result<usize, Error>

stream writes the object to the provided writer using the same representation that would be used in a call to pack. The implementor is responsible for making sure that the number of bytes written is exactly equal to the number of required bytes.

impl PartialEq for Macaroon

fn eq(&self, other: &Macaroon) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Macaroon

impl<'prototk> Unpackable<'prototk> for Macaroon

type Error = SError

Type of error this unpackable returns.

fn unpack<'b>(buf: &'b [u8]) -> Result<(Self, &'b [u8]), SError>

where 'b: 'prototk,

unpack attempts to return an Unpackable object stored in a prefix of buf. The method returns the result and remaining unused buffer.