Macarunes

https://docs.rs/macarunes/0.10.0/macarunes/
Admin
Macarunes is a Rust library that provides an implementation of Macaroons, cryptographic...
Tokens:8,318
Snippets:85
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### 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<T, <T as TryFrom<U>>::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<T>::from(t: T) -> T**: Returns the argument unchanged.
- **Into<U>::into(self) -> U**: Calls U::from(self).
- **TryFrom<U>::try_from(value: U) -> Result<T, Error>**: Performs a fallible conversion.
- **TryInto<U>::try_into(self) -> Result<U, Error>**: 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<Macaroon>), 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<U, <U as TryFrom<T>>::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** (<U as TryFrom<T>>::Error) - The type returned in the event of a conversion error.

### Methods
- **try_into(self) -> Result<U, <U as TryFrom<T>>::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<Macaroon>), Error>
```

--------------------------------

### Implement From<T> 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<Secret>> 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<Secret>> for Secret`

#### `fn merge_field(&mut self, proto: message<Secret>)`

Merges a `message<Secret>` proto into `self`.

### `impl From<message<Secret>> for Secret`

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

Converts a `message<Secret>` 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<W: Write>(&self, writer: &mut W) -> Result<usize, Error>`

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<ThirdPartySecret>> 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<ThirdPartySecret>> for ThirdPartySecret
#### fn merge_field(&mut self, proto: message<ThirdPartySecret>)
Merge the proto into self.

### impl From<message<ThirdPartySecret>> for ThirdPartySecret
#### fn from(proto: message<Self>) -> 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<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`.

### 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<T, U> TryFrom<U> for T

### Associated Types
- **Error** (Infallible) - The type returned in the event of a conversion error.

### Methods
- **try_from(value: U) -> Result<T, <T as TryFrom<U>>::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<T, U> TryInto<U> for T

### Associated Types
- **Error** (<U as TryFrom<T>>::Error) - The type returned in the event of a conversion error.

### Methods
- **try_into(self) -> Result<U, <U as TryFrom<T>>::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<U> 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<T, <T as TryFrom<U>>::Error>
```

--------------------------------

### Implement TryInto<U> 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<U, <U as TryFrom<T>>::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<L: Loader + 'static>(&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<ThirdPartySecret> into a ThirdPartySecret. This is part of the From trait.

```rust
fn from(proto: message<Self>) -> 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<U> 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<W: Write>(&self, writer: &mut W) -> Result<usize, Error>
```

--------------------------------

### 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 = <U as TryFrom<T>>::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<Macaroon, Error>

##### 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<Macaroon, Error>;
}
```

--------------------------------

### 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<ThirdPartySecret>)
```

--------------------------------

### 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
```
Tokens:
Raw