Struct biscuit_auth::token::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::{crypto::KeyPair, token::{Biscuit, builder::*}};

fn main() {
  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 mut builder = Biscuit::builder(&root);
  builder.add_authority_fact(fact("right", &[s("authority"), string("/a/file1.txt"), s("read")]));

  // facts and rules can also be parsed from a string
  builder.add_authority_fact("right(#authority, \"/a/file1.txt\", #read)").expect("parse error");

  let token1 = builder.build().unwrap();

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

  let keypair2 = KeyPair::new();
  let token2 = token1.append(&keypair2, builder2).unwrap();
}

Implementations

impl Biscuit

pub fn new(
    root: &KeyPair,
    symbols: SymbolTable,
    authority: Block
) -> Result<Biscuit, Token>

creates a new token

the public part of the root keypair must be used for verification

The block is an authority block: its index must be 0 and all of its facts must have the authority tag

pub fn new_with_rng<T: RngCore + CryptoRng>(
    rng: &mut T,
    root: &KeyPair,
    symbols: SymbolTable,
    authority: Block
) -> Result<Biscuit, Token>

creates a new token, using a provided CSPRNG

the public part of the root keypair must be used for verification

The block is an authority block: its index must be 0 and all of its facts must have the authority tag

pub fn from(slice: &[u8]) -> Result<Self, Token>

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

pub fn from_with_symbols(
    slice: &[u8],
    symbols: SymbolTable
) -> Result<Self, Token>

deserializes a token and validates the signature using the root public key, with a custom symbol table

pub fn from_base64<T: AsRef<[u8]>>(slice: T) -> Result<Self, Token>

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

pub fn from_base64_with_symbols<T: AsRef<[u8]>>(
    slice: T,
    symbols: SymbolTable
) -> Result<Self, Token>

deserializes a token and validates the signature using the root public key, with a custom symbol table

pub fn from_sealed(slice: &[u8], secret: &[u8]) -> Result<Self, Token>

deserializes a sealed token and checks its signature with the secret, using a custom symbol table

pub fn from_sealed_with_symbols(
    slice: &[u8],
    secret: &[u8],
    symbols: SymbolTable
) -> Result<Self, Token>

deserializes a sealed token and checks its signature with the secret

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

serializes the token

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

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

serializes the token

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

serializes the token

pub fn seal(&self, secret: &[u8]) -> Result<Vec<u8>, Token>

serializes a sealed version of the token

pub fn container(&self) -> Option<&SerializedBiscuit>

returns the internal representation of the token

pub fn check_root_key(&self, root: PublicKey) -> Result<(), Token>

tests that the token uses this public key as root

pub fn verify(&self, root: PublicKey) -> Result<Verifier, Token>

creates a verifier from this token

this will also call Biscuit::check_root_key

pub fn verify_sealed(&self) -> Result<Verifier, Token>

creates a verifier from this token

pub fn builder(root: &KeyPair) -> BiscuitBuilder<'_>

create the first block’s builder

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

pub fn builder_with_symbols(
    root: &KeyPair,
    symbols: SymbolTable
) -> BiscuitBuilder<'_>

create the first block’s builder, sing a provided symbol table

pub fn create_block(&self) -> BlockBuilder

creates a new block builder

pub fn append(
    &self,
    keypair: &KeyPair,
    block_builder: BlockBuilder
) -> Result<Self, 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 append_with_rng<T: RngCore + CryptoRng>(
    &self,
    rng: &mut T,
    keypair: &KeyPair,
    block_builder: BlockBuilder
) -> Result<Self, 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 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 revocation_identifiers(&self) -> Vec<Vec<u8>>

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

if a token is generated with the same keys and the same content, those identifiers will stay the same

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

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

those identifiers will be different for every token even if they have the same content and use the same keys

pub fn print(&self) -> String

pretty printer for this token

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

prints the content of a block as Datalog source code

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

Formats the value using the given formatter.