### Create New RequestBuilder Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Initializes a new instance of RequestBuilder. Use this to start building a macaroon request. ```rust pub fn new() -> Self ``` -------------------------------- ### Implement Any for T Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Gets the TypeId of the current type. This is part of the Any trait implementation. ```rust fn type_id(&self) -> TypeId ``` -------------------------------- ### Macaroon Introduction and Concepts Source: https://docs.rs/macarunes Provides an overview of the macaroon library, its core concepts, and underlying principles. ```APIDOC ## §macarunes This library provides an implementation of Macaroons. For an introduction to macaroons, check out the paper, or the Python README. ### §Assumptions * We rely upon the type system to provide memory safety. Secrets are scrubbed after use, but there’s no guarantee the linker won’t optimize away such code. Until an end-to-end solution emerges in the Rust compiler, it won’t be possible to guarantee secrets don’t leak in the presence of memory vulnerability. * This library relies upon the determinism of the protocol buffers code. This is guaranteed by prototk. * Intentionally restrictive language compared to the Python implementation. The only cases you need in the core library are to make exact comparisons (which are born out as format strings), to set an expiration, or to use a third-party caveat that enforces some arbitrary predicate before the discharge macaroon is granted. ### §Third-Party Macaroons This is the algorithm for satisfying third-party secrets: 1. Obtain `signature` from the macaroon to which we want to add a third-party caveat. 2. Make an RPC to the third-party that exchanges `signature` for a `ThirdPartySecret`. 3. Call `Macaroon.add_third_party(location, identifier, third_party_secret)`. ### §About Locations A location is a hint that is not part of the macaroons’s signature. The library does this intentionally as the paper suggests that only keys speak. For that reason, locations should be treated as hints that give a plain-text description of how to use the endpoint. The location in the macaroon is not the endpoint for discharge; it’s a opaque identifier that the `RequestBuilder` will iterate over. For each third party, a Loader should be developed that negotiates the protocol to get discharge macaroons. A location that’s not known to a client cannot be trusted. Given that we have to trust servers that give us macaroons, this is not a compromise or limitation. ### §Status Active development. ### §Scope This library should provide a verifier and a client-side library. ### §Warts * This library is under-used and will see active development in the future. ### §Documentation The latest documentation is always available at docs.rs. ``` -------------------------------- ### Clone to Uninit (Experimental) Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Performs copy-assignment from self to an uninitialized destination. This is a nightly-only experimental API. ```rust unsafe fn clone_to_uninit(&self, dest: *mut u8) ``` -------------------------------- ### ThirdPartySecret::new Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Creates a new ThirdPartySecret instance. ```APIDOC ## ThirdPartySecret::new ### Description Create a new ThirdPartySecret with the signature provided by the client and the nonce and discharge_secret provided by the server. ### Method `pub fn new( signature: &Secret, nonce: &Secret, discharge_secret: &Secret, ) -> Self` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) - **Self** (ThirdPartySecret) - A new instance of ThirdPartySecret. #### Response Example None ``` -------------------------------- ### unsafe fn clone_to_uninit Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Macaroon.html Experimental nightly-only API for performing copy-assignment from self to a destination pointer. ```APIDOC ## unsafe fn clone_to_uninit ### Description Performs copy-assignment from self to dest. This is a nightly-only experimental API. ### Parameters #### Path Parameters - **self** (T) - Required - The source value to clone. - **dest** (*mut u8) - Required - The destination pointer to copy into. ``` -------------------------------- ### Create New ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Creates a new ThirdPartySecret. Requires the client-provided signature and the server-provided nonce and discharge_secret. ```rust pub fn new( signature: &Secret, nonce: &Secret, discharge_secret: &Secret, ) -> Self ``` -------------------------------- ### TryFrom Trait Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Secret.html Documentation for the TryFrom trait used for fallible conversions. ```APIDOC ## TryFrom Trait ### Description Defines the interface for fallible conversions from type U to type T. ### Associated Types - **Error** (Infallible) - The type returned in the event of a conversion error. ### Methods - **try_from(value: U) -> Result>::Error>** - Performs the conversion. ``` -------------------------------- ### Implement Default for RequestBuilder Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Provides a default value for RequestBuilder. This allows creating a RequestBuilder with its default settings. ```rust fn default() -> RequestBuilder ``` -------------------------------- ### Trait Conversions (From, Into, TryFrom, TryInto) Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Macaroon.html Standard traits for type conversions and error-handled conversions. ```APIDOC ## Trait Conversions ### Description Standard library traits for converting between types. ### Methods - **From::from(t: T) -> T**: Returns the argument unchanged. - **Into::into(self) -> U**: Calls U::from(self). - **TryFrom::try_from(value: U) -> Result**: Performs a fallible conversion. - **TryInto::try_into(self) -> Result**: Performs a fallible conversion. ``` -------------------------------- ### RequestBuilder API Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Methods for initializing the RequestBuilder, adding loaders for third-party macaroons, and preparing requests. ```APIDOC ## RequestBuilder ### Description RequestBuilder handles the assembly of requests, specifically picking the minimal set of discharge macaroons required for a given operation. ### Methods #### new() Creates a new instance of RequestBuilder. #### add_loader(loader: L) Adds a loader for macaroons. Every type of third party should have its own loader identified by its location. - **loader** (Loader + 'static) - Required - The loader implementation to add. #### prepare_request(location: &str, identifier: &str) Prepares a request with the provided location and identifier. - **location** (&str) - Required - The location of the service. - **identifier** (&str) - Required - The identifier for the macaroon. ### Response - **Result<(Macaroon, Vec), Error>** - Returns a tuple containing the primary Macaroon and a list of discharge Macaroons, or an Error if preparation fails. ``` -------------------------------- ### try_into Method Source: https://docs.rs/macarunes/0.10.0/macarunes/enum.Error.html Provides the method to perform a conversion that may fail, returning a Result. ```APIDOC ## fn try_into ### Description Performs the conversion. Returns a Result which is Ok on success or Err on failure. ### Method Signature ```rust fn try_into(self) -> Result>::Error>; ``` ``` -------------------------------- ### TryInto Trait Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Secret.html Documentation for the TryInto trait used for fallible conversions. ```APIDOC ## TryInto Trait ### Description Defines the interface for fallible conversions into type U from type T. ### Associated Types - **Error** (>::Error) - The type returned in the event of a conversion error. ### Methods - **try_into(self) -> Result>::Error>** - Performs the conversion. ``` -------------------------------- ### Prepare Request with RequestBuilder Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Prepares a macaroon request using the provided location and identifier. This function returns a Result containing the Macaroon and a vector of discharge Macaroons, or an Error. ```rust pub fn prepare_request( &self, location: &str, identifier: &str, ) -> Result<(Macaroon, Vec), Error> ``` -------------------------------- ### Implement From for T Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Returns the argument unchanged. This is the implementation of the From trait. ```rust fn from(t: T) -> T ``` -------------------------------- ### Macaroon Creation Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Macaroon.html Methods for minting new macaroons. ```APIDOC ## POST /macaroon/new ### Description Mint a new macaroon for the location, identifier, and root secret. ### Method POST ### Endpoint /macaroon/new ### Parameters #### Request Body - **location** (String) - Required - The location of the macaroon. - **identifier** (String) - Required - The identifier for the macaroon. - **secret** (Secret) - Required - The root secret for the macaroon. ### Response #### Success Response (200) - **Macaroon** (Macaroon) - The newly created macaroon. ### Request Example ```json { "location": "example.com", "identifier": "user_id_123", "secret": "your_root_secret" } ``` ### Response Example ```json { "macaroon": "{\"location\": \"example.com\", \"identifier\": \"user_id_123\", \"signature\": \"...\", \"caveats\": []}" } ``` ``` -------------------------------- ### Core Structs and Enums Source: https://docs.rs/macarunes Details on the primary data structures and enumerations used within the macaroon library. ```APIDOC ## Structs§ Macaroon A Macaroon has a location, identifier, signature, and caveats. RequestBuilder RequestBuilder handles assembly of requests, picking the minimal set of discharge macaroons. Secret A Secret holds SIGNATURE_BYTES that will be scrubbed at the end of its lifetime. ThirdPartySecret A third party secret. It is intended that this be generated by the server that holds a secret for discharge macaroons. Verifier Verifier implements the servers-side portion of macaroons. Note that the caveats we’ve chosen require very little logic from the server. ## Enums§ Error The error cases macarunes can encounter. ## Constants§ SIGNATURE_BYTES The number of bytes expected in a macaroon signature. ## Traits§ Loader A Loader is a client-side way to get macaroons by identifier. Used by RequestBuilder. ``` -------------------------------- ### Clone Trait Methods Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Methods for managing owned data and cloning operations. ```APIDOC ## fn to_owned(&self) -> T ### Description Creates owned data from borrowed data, usually by cloning. ## fn clone_into(&self, target: &mut T) ### Description Uses borrowed data to replace owned data, usually by cloning. ``` -------------------------------- ### Implement Debug for RequestBuilder Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Provides a debugging representation for the RequestBuilder. This allows the struct to be formatted for debugging purposes. ```rust fn fmt(&self, f: &mut Formatter<'_>) -> Result ``` -------------------------------- ### Secret Methods Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Secret.html Provides details on the methods available for the Secret struct, including generating, representing, and scrubbing secrets. ```APIDOC ## impl Secret ### `fn hexdigest(&self) -> String` #### Description Returns a textual representation of the secret in hexadecimal format. #### Method `hexdigest` #### Parameters - `&self` (Secret) - An immutable reference to the Secret object. #### Returns - `String` - The hexadecimal string representation of the secret. ### `fn scrub(&mut self)` #### Description Attempts to securely erase the secret data from memory. #### Method `scrub` #### Parameters - `&mut self` (Secret) - A mutable reference to the Secret object. #### Returns None. ### `fn random() -> Self` #### Description Generates a new, random secret using a cryptographically secure random number generator. #### Method `random` #### Parameters None. #### Returns - `Self` (Secret) - A newly generated random Secret object. ``` -------------------------------- ### Secret Trait Implementations Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Secret.html Details on the traits implemented for the Secret struct, such as Clone, Default, PartialEq, and various packing/unpacking helpers. ```APIDOC ## Trait Implementations for Secret ### `impl Clone for Secret` #### `fn clone(&self) -> Secret` Returns a duplicate of the `Secret` value. #### `fn clone_from(&mut self, source: &Self)` Performs copy-assignment from `source` to `self`. ### `impl Default for Secret` #### `fn default() -> Secret` Returns the default value for `Secret`. ### `impl Drop for Secret` #### `fn drop(&mut self)` Executes the destructor for `Secret`, ensuring cleanup. ### `impl<'prototk> FieldPackHelper<'prototk, message> for Secret` #### `fn field_pack_sz(&self, tag: &Tag) -> usize` Calculates the size of encoding `self` with the given `tag`. #### `fn field_pack(&self, tag: &Tag, out: &mut [u8])` Packs the `tag` and secret data into the output buffer `out`. ### `impl<'prototk> FieldUnpackHelper<'prototk, message> for Secret` #### `fn merge_field(&mut self, proto: message)` Merges a `message` proto into `self`. ### `impl From> for Secret` #### `fn from(proto: message) -> Self` Converts a `message` into a `Secret`. ### `impl Packable for Secret` #### `fn pack_sz(&self) -> usize` Returns the number of bytes required to serialize the `Secret` object. #### `fn pack(&self, buf: &mut [u8])` Serializes the `Secret` object into the provided buffer `buf`. #### `fn stream(&self, writer: &mut W) -> Result` Writes the `Secret` object to the provided `writer`. ### `impl PartialEq for Secret` #### `fn eq(&self, other: &Secret) -> bool` Tests if `self` is equal to `other`. #### `fn ne(&self, other: &Rhs) -> bool` Tests if `self` is not equal to `other`. ### `impl<'prototk> Unpackable<'prototk> for Secret` #### `type Error = Error` The error type returned during unpacking. #### `fn unpack<'b>(buf: &'b [u8]) -> Result<(Self, &'b [u8]), Error>` Attempts to deserialize a `Secret` object from the buffer `buf`. ``` -------------------------------- ### ThirdPartySecret Trait Implementations Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Details on the various traits implemented for the ThirdPartySecret struct. ```APIDOC ## ThirdPartySecret Trait Implementations ### impl Clone for ThirdPartySecret #### fn clone(&self) -> ThirdPartySecret Returns a duplicate of the value. #### fn clone_from(&mut self, source: &Self) Performs copy-assignment from `source`. ### impl Default for ThirdPartySecret #### fn default() -> ThirdPartySecret Returns the “default value” for a type. ### impl Drop for ThirdPartySecret #### fn drop(&mut self) Executes the destructor for this type. ### impl<'prototk> FieldPackHelper<'prototk, message> for ThirdPartySecret #### 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> for ThirdPartySecret #### fn merge_field(&mut self, proto: message) Merge the proto into self. ### impl From> for ThirdPartySecret #### fn from(proto: message) -> Self Converts to this type from the input type. ### impl Packable for ThirdPartySecret #### 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. #### fn stream(&self, writer: &mut W) -> Result `stream` writes the object to the provided writer using the same representation that would be used in a call to `pack`. ### impl PartialEq for ThirdPartySecret #### fn eq(&self, other: &ThirdPartySecret) -> bool Tests for `self` and `other` values to be equal, and is used by `==`. #### fn ne(&self, other: &Rhs) -> bool Tests for `!=`. ### impl<'prototk> Unpackable<'prototk> for ThirdPartySecret #### type Error = Error Type of error this unpackable returns. #### fn unpack<'b>(buf: &'b [u8]) -> Result<(Self, &'b [u8]), Error> `unpack` attempts to return an Unpackable object stored in a prefix of `buf`. ``` -------------------------------- ### ThirdPartySecret::scrub Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Scrub the memory locations of the nonce and data within the ThirdPartySecret. ```APIDOC ## ThirdPartySecret::scrub ### Description Scrub the memory locations of the nonce and data. ### Method `pub fn scrub(&mut self)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) None (modifies the struct in place) #### Response Example None ``` -------------------------------- ### Struct RequestBuilder Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Defines the structure for building macaroon requests. It handles the assembly of requests and the selection of discharge macaroons. ```rust pub struct RequestBuilder { /* private fields */ } ``` -------------------------------- ### TryFrom Trait Implementation Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Conversion trait for types that can be converted from another type, potentially failing. ```APIDOC ## impl TryFrom for T ### Associated Types - **Error** (Infallible) - The type returned in the event of a conversion error. ### Methods - **try_from(value: U) -> Result>::Error>** - Performs the conversion. ``` -------------------------------- ### Pack ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Fills the provided buffer with the packed binary representation of the Packable ThirdPartySecret object. This is part of the Packable trait. ```rust fn pack(&self, buf: &mut [u8]) ``` -------------------------------- ### Field Pack ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Packs the tag into the output buffer for the ThirdPartySecret. This is part of the FieldPackHelper trait. ```rust fn field_pack(&self, tag: &Tag, out: &mut [u8]) ``` -------------------------------- ### TryInto Trait Implementation Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Conversion trait for types that can be converted into another type, potentially failing. ```APIDOC ## impl TryInto for T ### Associated Types - **Error** (>::Error) - The type returned in the event of a conversion error. ### Methods - **try_into(self) -> Result>::Error>** - Performs the conversion. ``` -------------------------------- ### Macaroon Caveat Management Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Macaroon.html Methods for adding caveats to a macaroon. ```APIDOC ## POST /macaroon/{id}/add_exact ### Description Add a caveat that must match exactly. ### Method POST ### Endpoint /macaroon/{id}/add_exact ### Parameters #### Path Parameters - **id** (String) - Required - The identifier of the macaroon. #### Request Body - **what** (String) - Required - The exact string to match for the caveat. ### Response #### Success Response (200) - **Macaroon** (Macaroon) - The updated macaroon with the added caveat. ### Request Example ```json { "what": "user_id = 123" } ``` ### Response Example ```json { "macaroon": "{\"location\": \"example.com\", \"identifier\": \"user_id_123\", \"signature\": \"...\", \"caveats\": [ { \"type\": \"exact\", \"value\": \"user_id = 123\" } ]}" } ``` ``` ```APIDOC ## POST /macaroon/{id}/add_expires ### Description Add a caveat that expires the macaroon after a specified time. ### Method POST ### Endpoint /macaroon/{id}/add_expires ### Parameters #### Path Parameters - **id** (String) - Required - The identifier of the macaroon. #### Request Body - **when** (u64) - Required - The Unix timestamp (in seconds) after which the macaroon expires. ### Response #### Success Response (200) - **Macaroon** (Macaroon) - The updated macaroon with the added expiration caveat. ### Request Example ```json { "when": 1678886400 } ``` ### Response Example ```json { "macaroon": "{\"location\": \"example.com\", \"identifier\": \"user_id_123\", \"signature\": \"...\", \"caveats\": [ { \"type\": \"expiry\", \"value\": 1678886400 } ]}" } ``` ``` ```APIDOC ## POST /macaroon/{id}/add_third_party ### Description Add a third-party caveat. ### Method POST ### Endpoint /macaroon/{id}/add_third_party ### Parameters #### Path Parameters - **id** (String) - Required - The identifier of the macaroon. #### Request Body - **location** (String) - Required - The location of the third-party service. - **identifier** (String) - Required - The identifier for the third-party caveat. - **secret** (ThirdPartySecret) - Required - The secret for the third-party caveat. ### Response #### Success Response (200) - **Macaroon** (Macaroon) - The updated macaroon with the added third-party caveat. ### Request Example ```json { "location": "thirdparty.example.com", "identifier": "tp_caveat_id", "secret": "tp_secret" } ``` ### Response Example ```json { "macaroon": "{\"location\": \"example.com\", \"identifier\": \"user_id_123\", \"signature\": \"...\", \"caveats\": [ { \"type\": \"third_party\", \"location\": \"thirdparty.example.com\", \"identifier\": \"tp_caveat_id\" } ]}" } ``` ``` -------------------------------- ### Pack Size for ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Returns the number of bytes required to serialize the Packable ThirdPartySecret object. This is part of the Packable trait. ```rust fn pack_sz(&self) -> usize ``` -------------------------------- ### Verifier API Methods Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Verifier.html Methods available on the Verifier struct for managing verification context and performing validation. ```APIDOC ## add_context ### Description Adds a context string to the request. This allows the client to include a contextual caveat that the server will verify. ### Parameters - **context** (String) - Required - The context string to add. ## set_current_time ### Description Sets the current time to be used for the verification process. ### Parameters - **now** (u64) - Required - The timestamp to use for verification. ## verify ### Description Verifies a macaroon. This method is resistant to timing attacks. ### Parameters - **root** (&Macaroon) - Required - The root macaroon to verify. - **key** (&Secret) - Required - The secret key used for verification. - **discharges** (&[Macaroon]) - Required - A slice of discharge macaroons. ### Response - **Result<(), Error>** - Returns Ok(()) if verification succeeds, or an Error if it fails. ``` -------------------------------- ### Equal ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Tests for equality between two ThirdPartySecret values. This is part of the PartialEq trait. ```rust fn eq(&self, other: &ThirdPartySecret) -> bool ``` -------------------------------- ### Implement TryFrom for T Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Performs a fallible conversion from type U into type T. This is part of the TryFrom trait implementation. ```rust fn try_from(value: U) -> Result>::Error> ``` -------------------------------- ### Implement TryInto for T Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Performs a fallible conversion from type T into type U. This is part of the TryInto trait implementation. ```rust fn try_into(self) -> Result>::Error> ``` -------------------------------- ### Field Pack Size for ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Calculates the size of encoding the ThirdPartySecret with a given tag. This is part of the FieldPackHelper trait. ```rust fn field_pack_sz(&self, tag: &Tag) -> usize ``` -------------------------------- ### Add Loader to RequestBuilder Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Adds a loader for macaroons to the RequestBuilder. Each third-party macaroon type requires its own loader, identified by its location. ```rust pub fn add_loader(&mut self, loader: L) ``` -------------------------------- ### Scrub ThirdPartySecret Memory Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Scrub the memory locations of the nonce and data within the ThirdPartySecret. This is a mutable operation. ```rust pub fn scrub(&mut self) ``` -------------------------------- ### Convert From Message to ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Converts a message into a ThirdPartySecret. This is part of the From trait. ```rust fn from(proto: message) -> Self ``` -------------------------------- ### Unpack ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Attempts to unpack a ThirdPartySecret object from a buffer. Returns the object and the remaining buffer, or an error. This is part of the Unpackable trait. ```rust fn unpack<'b>(buf: &'b [u8]) -> Result<(Self, &'b [u8]), Error> ``` -------------------------------- ### Clone From ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Performs copy-assignment from a source ThirdPartySecret to self. This implementation is part of the Clone trait. ```rust fn clone_from(&mut self, source: &Self) ``` -------------------------------- ### Implement Borrow for T Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Immutably borrows from an owned value. This is part of the Borrow trait implementation. ```rust fn borrow(&self) -> &T ``` -------------------------------- ### Macaroon Binding Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Macaroon.html Method for binding a discharge macaroon to the current request context. ```APIDOC ## POST /macaroon/{id}/bind_discharge ### Description Bind a macaroon to the request to make sure discharge macaroons cannot be used in other contexts. ### Method POST ### Endpoint /macaroon/{id}/bind_discharge ### Parameters #### Path Parameters - **id** (String) - Required - The identifier of the macaroon to bind. #### Request Body - **discharge** (Macaroon) - Required - The discharge macaroon to bind. ### Response #### Success Response (200) - **Macaroon** (Macaroon) - The macaroon with the discharge macaroon bound. ### Request Example ```json { "discharge": {"location": "discharge.example.com", "identifier": "discharge_id", "signature": "...", "caveats": []} } ``` ### Response Example ```json { "macaroon": "{\"location\": \"example.com\", \"identifier\": \"user_id_123\", \"signature\": \"...\", \"caveats\": [ { \"type\": \"discharge\", \"cid\": \"discharge_id\" } ]}" } ``` ``` -------------------------------- ### Constant SIGNATURE_BYTES Source: https://docs.rs/macarunes/0.10.0/macarunes/constant.SIGNATURE_BYTES.html The number of bytes expected in a macaroon signature. ```APIDOC ## Constant SIGNATURE_BYTES ### Description The number of bytes expected in a macaroon signature. ### Summary `pub const SIGNATURE_BYTES: usize = 32;` ``` -------------------------------- ### Verifier struct definition Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Verifier.html The internal structure of the Verifier type. ```rust pub struct Verifier { /* private fields */ } ``` -------------------------------- ### Implement Into for T Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Converts the value into the target type U by calling U::from(self). This is part of the Into trait implementation. ```rust fn into(self) -> U ``` -------------------------------- ### Macaroon Struct Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Macaroon.html Represents a macaroon with its location, identifier, signature, and caveats. ```APIDOC ## Struct Macaroon ### Description A Macaroon has a location, identifier, signature, and caveats. ### Fields (Fields are private and not directly accessible via public API) ``` -------------------------------- ### Not Equal ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Tests for inequality between two ThirdPartySecret values. This is part of the PartialEq trait. ```rust fn ne(&self, other: &Rhs) -> bool ``` -------------------------------- ### Stream ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Writes the Packable ThirdPartySecret object to a writer using its packed binary representation. This is part of the Packable trait. ```rust fn stream(&self, writer: &mut W) -> Result ``` -------------------------------- ### Macaroon Struct Definition Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Macaroon.html The primary structure for representing a Macaroon. ```rust pub struct Macaroon { /* private fields */ } ``` -------------------------------- ### Error Type Definition Source: https://docs.rs/macarunes/0.10.0/macarunes/enum.Error.html Defines the generic Error type returned when a TryFrom conversion fails. ```APIDOC ## type Error ### Description The type returned in the event of a conversion error. ### Type Definition ```rust type Error = >::Error; ``` ``` -------------------------------- ### Implement BorrowMut for T Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.RequestBuilder.html Mutably borrows from an owned value. This is part of the BorrowMut trait implementation. ```rust fn borrow_mut(&mut self) -> &mut T ``` -------------------------------- ### Define SIGNATURE_BYTES Constant Source: https://docs.rs/macarunes/0.10.0/macarunes/constant.SIGNATURE_BYTES.html This constant defines the expected number of bytes for a macaroon signature. It is used to ensure the integrity and validity of macaroon signatures. ```rust pub const SIGNATURE_BYTES: usize = 32; ``` -------------------------------- ### Default ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Returns the default value for ThirdPartySecret. This implementation is part of the Default trait. ```rust fn default() -> ThirdPartySecret ``` -------------------------------- ### ThirdPartySecret Struct Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Represents a third-party secret, intended to be generated by a server holding a secret for discharge macaroons. ```APIDOC ## Struct ThirdPartySecret ### Description A third party secret. It is intended that this be generated by the server that holds a secret for discharge macaroons. ### Fields (Private fields, not detailed in the documentation) ``` -------------------------------- ### Macaroon Inspection Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Macaroon.html Methods for retrieving information about a macaroon. ```APIDOC ## GET /macaroon/{id}/location ### Description Retrieves the location of the macaroon. ### Method GET ### Endpoint /macaroon/{id}/location ### Parameters #### Path Parameters - **id** (String) - Required - The identifier of the macaroon. ### Response #### Success Response (200) - **location** (String) - The location of the macaroon. ### Response Example ```json { "location": "example.com" } ``` ``` ```APIDOC ## GET /macaroon/{id}/identifier ### Description Retrieves the identifier of the macaroon. ### Method GET ### Endpoint /macaroon/{id}/identifier ### Parameters #### Path Parameters - **id** (String) - Required - The identifier of the macaroon. ### Response #### Success Response (200) - **identifier** (String) - The identifier of the macaroon. ### Response Example ```json { "identifier": "user_id_123" } ``` ``` ```APIDOC ## GET /macaroon/{id}/signature ### Description Retrieves the signature of the macaroon. ### Method GET ### Endpoint /macaroon/{id}/signature ### Parameters #### Path Parameters - **id** (String) - Required - The identifier of the macaroon. ### Response #### Success Response (200) - **signature** (Secret) - The signature of the macaroon. ### Response Example ```json { "signature": "secret_signature_value" } ``` ``` -------------------------------- ### Clone ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Returns a duplicate of the ThirdPartySecret value. This implementation is part of the Clone trait. ```rust fn clone(&self) -> ThirdPartySecret ``` -------------------------------- ### Loader Trait Source: https://docs.rs/macarunes/0.10.0/macarunes/trait.Loader.html The Loader trait provides an interface for clients to fetch macaroons based on a given identifier. It is utilized by the RequestBuilder. ```APIDOC ## Trait Loader ### Description A Loader is a client-side way to get macaroons by identifier. Used by RequestBuilder. ### Required Methods #### fn location(&self) -> &'static str ##### Description The location this loader serves. #### fn lookup(&self, identifier: &str) -> Result ##### Description Lookup the discharge macaroon with the given identifier. Assumes the caller will verify the macaroon’s location against `self.location()`. ``` -------------------------------- ### Define ThirdPartySecret Struct Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Defines the ThirdPartySecret struct. It is intended to be generated by a server holding a secret for discharge macaroons. The struct has private fields. ```rust pub struct ThirdPartySecret { /* private fields */ } ``` -------------------------------- ### ToOwned Trait Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Macaroon.html Methods for creating owned data from borrowed data. ```APIDOC ## ToOwned Trait ### Description Provides methods for creating owned data from borrowed data, typically via cloning. ### Methods - **to_owned(&self) -> T**: Creates owned data from borrowed data. - **clone_into(&self, target: &mut T)**: Uses borrowed data to replace owned data. ``` -------------------------------- ### Define the Loader trait Source: https://docs.rs/macarunes/0.10.0/macarunes/trait.Loader.html The Loader trait requires implementation of location and lookup methods for retrieving macaroons. ```rust pub trait Loader: Debug { // Required methods fn location(&self) -> &'static str; fn lookup(&self, identifier: &str) -> Result; } ``` -------------------------------- ### Drop ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Executes the destructor for the ThirdPartySecret type. This implementation is part of the Drop trait. ```rust fn drop(&mut self) ``` -------------------------------- ### Merge Field into ThirdPartySecret Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Merges a protocol message into the ThirdPartySecret. This is part of the FieldUnpackHelper trait. ```rust fn merge_field(&mut self, proto: message) ``` -------------------------------- ### Secret Struct Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.Secret.html The Secret struct is used to hold sensitive data that will be scrubbed from memory at the end of its lifetime. ```APIDOC ## Struct Secret ### Description A Secret holds SIGNATURE_BYTES that will be scrubbed at the end of its lifetime. ### Fields (Private fields, not exposed) ### Example ```rust // Example usage of Secret struct // Note: Actual instantiation might involve internal methods due to private fields. ``` ``` -------------------------------- ### Define Error Enum Source: https://docs.rs/macarunes/0.10.0/macarunes/enum.Error.html The Error enum represents potential failure conditions in macarunes operations. ```rust pub enum Error { Success, Cycle, ProofInvalid, MissingLoader { what: String, }, } ``` -------------------------------- ### Macarunes Error Enum Source: https://docs.rs/macarunes/0.10.0/macarunes/enum.Error.html The Error enum represents the different types of errors that can occur within the Macarunes library. Each variant signifies a specific failure condition. ```APIDOC ## Enum Error ### Description The error cases macarunes can encounter. ### Variants #### Success Success is the default error. #### Cycle The macarunes detected a cycle. This is a P(0) event for valid macarunes trees. #### ProofInvalid The proof carried by macarunes does not hold up under scrutiny. #### MissingLoader The client is lacking a loader for the given macarune. ##### Fields - **what** (String) - A textual description of the loader that’s needed. ``` -------------------------------- ### Owned Type Source: https://docs.rs/macarunes/0.10.0/macarunes/struct.ThirdPartySecret.html Defines the 'Owned' type, which is the resulting type after obtaining ownership. This is part of the ToOwned trait. ```rust type Owned = T ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.