Struct Biscuit

pub struct Biscuit { /* private fields */ }

This structure represents a valid Biscuit token

It contains multiple Block elements, the associated symbol table, and a serialized version of this data

extern crate biscuit_auth as biscuit;

use biscuit::{KeyPair, Biscuit, builder::*, builder_ext::*};

fn main() -> Result<(), biscuit::error::Token> {
  let root = KeyPair::new();

  // first we define the authority block for global data,
  // like access rights
  // data from the authority block cannot be created in any other block
  let token1 = Biscuit::builder()
      .fact(fact("right", &[string("/a/file1.txt"), string("read")]))?

      // facts and rules can also be parsed from a string
      .fact("right(\"/a/file1.txt\", \"read\")")?
      .build(&root)?;

  // we can create a new block builder from that token
  let builder2 = BlockBuilder::new()
      .check_operation("read");

  let token2 = token1.append(builder2)?;

  Ok(())
}

Implementations

impl Biscuit

pub fn builder() -> BiscuitBuilder

create the first block’s builder

call builder::BiscuitBuilder::build to create the token

pub fn from<T, KP>(slice: T, key_provider: KP) -> Result<Biscuit, Token>

where T: AsRef<[u8]>, KP: RootKeyProvider,

deserializes a token and validates the signature using the root public key

pub fn from_base64<T, KP>(slice: T, key_provider: KP) -> Result<Biscuit, Token>

where T: AsRef<[u8]>, KP: RootKeyProvider,

deserializes a token and validates the signature using the root public key

pub fn unsafe_deprecated_deserialize<T, KP>( slice: T, key_provider: KP, ) -> Result<Biscuit, Token>

where T: AsRef<[u8]>, KP: RootKeyProvider,

deserializes a token and validates the signature using the root public key

This allows the deprecated 3rd party block format

pub fn to_vec(&self) -> Result<Vec<u8>, Token>

serializes the token

Examples found in repository

examples/token_verification.rs (line 107)

fn generate_example_token(keypair: Arc<KeyPair>) -> Result<String, TokenError> {
    // Create a simple test biscuit with authorization rules
    let biscuit_builder = biscuit!(
        r#"
            // Grant rights to alice for resource1
            right("alice", "resource1", "read");
            right("alice", "resource1", "write");
        "#
    );

    // Build and serialize the token
    let biscuit = biscuit_builder
        .build(&keypair)
        .map_err(TokenError::biscuit_error)?;

    let token_bytes = biscuit.to_vec().map_err(TokenError::biscuit_error)?;

    // Encode to base64 for transmission
    Ok(encode_token(&token_bytes))
}

/// Generate a token with service chain attestations
fn generate_service_chain_token(
    root_keypair: Arc<KeyPair>,
    service1_public_key: String,
    service2_public_key: String,
) -> Result<String, TokenError> {
    // Create a biscuit with service chain authorization
    let biscuit_builder = biscuit!(
        r#"
            // Basic rights
            right("alice", "resource1", "read");
            right("alice", "resource1", "write");
            
            // Service nodes
            node($s, "node1") <- service($s) trusting authority, {node1_public_key};
            node($s, "node2") <- service($s) trusting authority, {node2_public_key};
        "#,
        node1_public_key = biscuit_key_from_string(service1_public_key)?,
        node2_public_key = biscuit_key_from_string(service2_public_key)?,
    );

    // Build and serialize the token
    let biscuit = biscuit_builder
        .build(&root_keypair)
        .map_err(TokenError::biscuit_error)?;

    let token_bytes = biscuit.to_vec().map_err(TokenError::biscuit_error)?;

    // Encode to base64
    Ok(encode_token(&token_bytes))
}

examples/token_attenuation.rs (line 77)

fn generate_example_token() -> Result<(String, KeyPair), TokenError> {
    // Create a test keypair
    let keypair = KeyPair::new();

    // Create a simple test biscuit with authorization rules
    let biscuit_builder = biscuit!(
        r#"
            // Grant rights to alice for resource1
            right("alice", "resource1", "read");
            right("alice", "resource1", "write");
        "#
    );

    // Build and serialize the token
    let biscuit = biscuit_builder
        .build(&keypair)
        .map_err(TokenError::biscuit_error)?;

    let token_bytes = biscuit.to_vec().map_err(TokenError::biscuit_error)?;

    // Encode to base64 for transmission
    Ok((encode_token(&token_bytes), keypair))
}

pub fn to_base64(&self) -> Result<String, Token>

serializes the token and encode it to a (URL safe) base64 string

pub fn serialized_size(&self) -> Result<usize, Token>

serializes the token

pub fn seal(&self) -> Result<Biscuit, Token>

creates a sealed version of the token

sealed tokens cannot be attenuated

pub fn authorizer(&self) -> Result<Authorizer, Token>

creates an authorizer from this token

pub fn append(&self, block_builder: BlockBuilder) -> Result<Biscuit, Token>

adds a new block to the token

since the public key is integrated into the token, the keypair can be discarded right after calling this function

pub fn context(&self) -> Vec<Option<String>>

returns the list of context elements of each block

the context is a free form text field in which application specific data can be stored

pub fn root_key_id(&self) -> Option<u32>

returns an (optional) root key identifier. It provides a hint for public key selection during verification

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

returns a list of revocation identifiers for each block, in order

revocation identifiers are unique: tokens generated separately with the same contents will have different revocation ids

pub fn external_public_keys(&self) -> Vec<Option<PublicKey>>

returns a list of external key for each block, in order

Blocks carrying an external public key are third-party blocks and their contents can be trusted as coming from the holder of the corresponding private key

pub fn print(&self) -> String

pretty printer for this token

pub fn print_block_source(&self, index: usize) -> Result<String, Token>

prints the content of a block as Datalog source code

pub fn block_version(&self, index: usize) -> Result<u32, Token>

gets the datalog version for a given block

pub fn container(&self) -> &SerializedBiscuit

returns the internal representation of the token

pub fn append_with_keypair( &self, keypair: &KeyPair, block_builder: BlockBuilder, ) -> Result<Biscuit, Token>

adds a new block to the token, using the provided CSPRNG

since the public key is integrated into the token, the keypair can be discarded right after calling this function

pub fn third_party_request(&self) -> Result<ThirdPartyRequest, Token>

pub fn append_third_party( &self, external_key: PublicKey, response: ThirdPartyBlock, ) -> Result<Biscuit, Token>

pub fn append_third_party_with_keypair( &self, external_key: PublicKey, response: ThirdPartyBlock, next_keypair: KeyPair, ) -> Result<Biscuit, Token>

pub fn block_symbols(&self, index: usize) -> Result<Vec<String>, Token>

gets the list of symbols from a block

pub fn block_public_keys(&self, index: usize) -> Result<PublicKeys, Token>

gets the list of public keys from a block

pub fn block_external_key( &self, index: usize, ) -> Result<Option<PublicKey>, Token>

gets the list of public keys from a block

pub fn block_count(&self) -> usize

returns the number of blocks (at least 1)

Trait Implementations

impl Clone for Biscuit

fn clone(&self) -> Biscuit

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Biscuit

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

Formats the value using the given formatter.

impl Display for Biscuit

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

Formats the value using the given formatter.