Api reference

biscuit_auth module

Main module for the biscuit_auth lib

exception biscuit_auth.AuthorizationError

class biscuit_auth.Authorizer

The Authorizer verifies a request according to its policies and the provided token

Parameters:

source (str, optional) – a datalog snippet
parameters (dict, optional) – values for the parameters in the datalog snippet
scope_parameters (dict, optional) – public keys for the public key parameters in the datalog snippet

add_check(check)

Add a single check to the authorizer. A single check can be built with the Check class and its constructor

Parameters:: check (Check) – a datalog check

add_code(source, parameters=Ellipsis, scope_parameters=Ellipsis)

Add code to the builder, using the provided parameters.

Parameters:

source (str, optional) – a datalog snippet
parameters (dict, optional) – values for the parameters in the datalog snippet
scope_parameters (dict, optional) – public keys for the public key parameters in the datalog snippet

add_fact(fact)

Add a single fact to the authorizer. A single fact can be built with the Fact class and its constructor

Parameters:: fact (Fact) – a datalog fact

add_policy(policy)

Add a single policy to the authorizer. A single policy can be built with the Policy class and its constructor

Parameters:: policy (Policy) – a datalog policy

add_rule(rule)

Add a single rule to the authorizer. A single rule can be built with the Rule class and its constructor

Parameters:: rule (Rule) – a datalog rule

add_token(token)

Add a Biscuit to this Authorizer

Parameters:: token (Biscuit) – the token to authorize

authorize()

Runs the authorization checks and policies

Returns the index of the matching allow policy, or an error containing the matching deny policy or a list of the failing checks

Returns:: the index of the matched allow rule
Return type:: int

base64_snapshot()

Take a snapshot of the authorizer and return it, base64-encoded

Returns:: a snapshot as a base64-encoded string
Return type:: str

from_base64_snapshot()

Build an authorizer from a base64-encoded snapshot

Parameters:: input (str) – base64-encoded snapshot
Returns:: the authorizer
Return type:: Authorizer

from_raw_snapshot()

Build an authorizer from a snapshot’s raw bytes

Parameters:: input (bytes) – raw snapshot bytes
Returns:: the authorizer
Return type:: Authorizer

merge(builder)

Merge another Authorizer in this Authorizer. The Authorizer argument will not be modified

Parameters:: builder (Authorizer) – an Authorizer

merge_block(builder)

Merge a BlockBuilder in this Authorizer. The BlockBuilder will not be modified

Parameters:: builder (BlockBuilder) – a BlockBuilder

query(rule)

Query the authorizer by returning all the Fact`s generated by the provided `Rule. The generated facts won’t be added to the authorizer world.

This function can be called before authorize, but in that case will only return facts that are directly defined, not the facts generated by rules.

Parameters:: rule (Rule) – a rule that will be ran against the authorizer contents
Returns:: a list of generated facts
Return type:: list

raw_snapshot()

Take a snapshot of the authorizer and return it, as raw bytes

Returns:: a snapshot as raw bytes
Return type:: bytes

class biscuit_auth.Biscuit

Representation of a biscuit token that has been parsed and cryptographically verified.

append(block)

Create a new Biscuit by appending an attenuation block

Parameters:: block (BlockBuilder) – a builder for the new block
Returns:: the attenuated biscuit
Return type:: Biscuit

block_count()

Returns the number of blocks in the token

Returns:: the number of blocks
Return type:: int

block_source(index)

Prints a block’s content as Datalog code

Parameters:: index (int) – the block index
Returns:: the code for the corresponding block
Return type:: str

static builder()

Creates a BiscuitBuilder

Returns:: an empty BiscuitBuilder
Return type:: BiscuitBuilder

from_base64(root)

Deserializes a token from URL safe base 64 data

This will check the signature using the provided root key (or function)

Parameters:

data (str) – a (url-safe) base64-encoded string
root (function,PublicKey) – either a public key or a function taking an integer (or None) and returning an public key

Returns:

the parsed and verified biscuit

Return type:

Biscuit

from_bytes(root)

Deserializes a token from raw data

This will check the signature using the provided root key (or function)

Parameters:

data (bytes) – raw biscuit bytes
root (function,PublicKey) – either a public key or a function taking an integer (or None) and returning an public key

Returns:

the parsed and verified biscuit

Return type:

Biscuit

revocation_ids: The revocation ids of the token, encoded as hexadecimal strings

to_base64()

Serializes to URL safe base 64 data

Returns:: the serialized biscuit
Return type:: str

to_bytes()

Serializes to raw bytes

Returns:: the serialized biscuit
Return type:: list

exception biscuit_auth.BiscuitBlockError

exception biscuit_auth.BiscuitBuildError

class biscuit_auth.BiscuitBuilder

Builder class allowing to create a biscuit from a datalog block

Parameters:

source (str, optional) – a datalog snippet
parameters (dict, optional) – values for the parameters in the datalog snippet
scope_parameters (dict, optional) – public keys for the public key parameters in the datalog snippet

add_check(check)

Add a single check to the builder. A single check can be built with the Check class and its constructor

Parameters:: check (Check) – a datalog check

add_code(source, parameters=Ellipsis, scope_parameters=Ellipsis)

Add code to the builder, using the provided parameters.

Parameters:

source (str, optional) – a datalog snippet
parameters (dict, optional) – values for the parameters in the datalog snippet
scope_parameters (dict, optional) – public keys for the public key parameters in the datalog snippet

add_fact(fact)

Add a single fact to the builder. A single fact can be built with the Fact class and its constructor

Parameters:: fact (Fact) – a datalog fact

add_rule(rule)

Add a single rule to the builder. A single rule can be built with the Rule class and its constructor

Parameters:: rule (Rule) – a datalog rule

build(root)

Build a biscuit token, using the provided private key to sign the authority block

Parameters:: root (PrivateKey) – a keypair that will be used to sign the authority block
Returns:: a biscuit token
Return type:: Biscuit

merge(builder)

Merge a BlockBuilder in this BiscuitBuilder. The BlockBuilder parameter will not be modified

Parameters:: builder (BlockBuilder) – a datalog BlockBuilder

set_root_key_id(root_key_id)

Set the root key identifier for this BiscuitBuilder

Parameters:: root_key_id (int) – the root key identifier

exception biscuit_auth.BiscuitSerializationError

exception biscuit_auth.BiscuitValidationError

class biscuit_auth.BlockBuilder

Builder class allowing to create a block meant to be appended to an existing token

Parameters:

source (str, optional) – a datalog snippet
parameters (dict, optional) – values for the parameters in the datalog snippet
scope_parameters (dict, optional) – public keys for the public key parameters in the datalog snippet

add_check(check)

Add a single check to the builder. A single check can be built with the Check class and its constructor

Parameters:: check (Check) – a datalog check

add_code(source, parameters=Ellipsis, scope_parameters=Ellipsis)

Add code to the builder, using the provided parameters.

Parameters:

source (str, optional) – a datalog snippet
parameters (dict, optional) – values for the parameters in the datalog snippet
scope_parameters (dict, optional) – public keys for the public key parameters in the datalog snippet

add_fact(fact)

Add a single fact to the builder. A single fact can be built with the Fact class and its constructor

Parameters:: fact (Fact) – a datalog fact

add_rule(rule)

Add a single rule to the builder. A single rule can be built with the Rule class and its constructor

Parameters:: rule (Rule) – a datalog rule

merge(builder)

Merge a BlockBuilder in this BlockBuilder. The BlockBuilder will not be modified

Parameters:: builder (BlockBuilder) – a datalog BlockBuilder

class biscuit_auth.Check

A single datalog check

Parameters:

source (str) – a datalog check (without the ending semicolon)
parameters (dict, optional) – values for the parameters in the datalog check
scope_parameters (dict, optional) – public keys for the public key parameters in the datalog check

exception biscuit_auth.DataLogError

class biscuit_auth.Fact

A single datalog Fact

Parameters:

source (str) – a datalog fact (without the ending semicolon)
parameters (dict, optional) – values for the parameters in the datalog fact

name: The fact name

terms: The fact terms

class biscuit_auth.KeyPair

ed25519 keypair

from_private_key()

Generate a keypair from a private key

Parameters:: private_key (PrivateKey) – the private key
Returns:: the corresponding keypair
Return type:: KeyPair

from_private_key_der()

Generate a keypair from a DER buffer

Parameters:: bytes – private key bytes in DER format
Returns:: the corresponding keypair
Return type:: KeyPair

from_private_key_pem()

Generate a keypair from a PEM buffer

Parameters:: bytes – private key bytes in PEM format
Returns:: the corresponding keypair
Return type:: KeyPair

private_key: The private key part

public_key: The public key part

class biscuit_auth.Policy

A single datalog policy

Parameters:

source (str) – a datalog policy (without the ending semicolon)
parameters (dict, optional) – values for the parameters in the datalog policy
scope_parameters (dict, optional) – public keys for the public key parameters in the datalog policy

class biscuit_auth.PrivateKey

ed25519 private key

from_bytes()

Deserializes a private key from raw bytes

Parameters:: data (bytes) – the raw bytes
Returns:: the private key
Return type:: PrivateKey

from_hex()

Deserializes a private key from a hexadecimal string

Parameters:: data (str) – the hex-encoded string
Returns:: the private key
Return type:: PrivateKey

to_bytes()

Serializes a public key to raw bytes

Returns:: the public key bytes
Return type:: list

to_hex()

Serializes a private key to a hexadecimal string

Returns:: the private key bytes (hex-encoded)
Return type:: str

class biscuit_auth.PublicKey

ed25519 public key

from_bytes()

Deserializes a public key from raw bytes

Parameters:: data (bytes) – the raw bytes
Returns:: the public key
Return type:: PublicKey

from_hex()

Deserializes a public key from a hexadecimal string

Parameters:: data (str) – the hex-encoded string
Returns:: the public key
Return type:: PublicKey

to_bytes()

Serializes a public key to raw bytes

Returns:: the public key bytes
Return type:: list

to_hex()

Serializes a public key to a hexadecimal string

Returns:: the public key bytes (hex-encoded)
Return type:: str

class biscuit_auth.Rule

A single datalog rule

Parameters:

source (str) – a datalog rule (without the ending semicolon)
parameters (dict, optional) – values for the parameters in the datalog rule
scope_parameters (dict, optional) – public keys for the public key parameters in the datalog rule

class biscuit_auth.UnverifiedBiscuit

Representation of a biscuit token that has been parsed but not cryptographically verified

append(block)

Create a new UnverifiedBiscuit by appending an attenuation block

Parameters:: block (BlockBuilder) – a builder for the new block
Returns:: the attenuated biscuit
Return type:: Biscuit

block_count()

Returns the number of blocks in the token

Returns:: the number of blocks
Return type:: int

block_source(index)

Prints a block’s content as Datalog code

Parameters:: index (int) – the block index
Returns:: the code for the corresponding block
Return type:: str

from_base64()

Deserializes a token from URL safe base 64 data

The signature will NOT be checked

Parameters:: data (str) – a (url-safe) base64-encoded string
Returns:: the parsed, unverified biscuit
Return type:: UnverifiedBiscuit

revocation_ids: The revocation ids of the token, encoded as hexadecimal strings

root_key_id()

Returns the root key identifier for this UnverifiedBiscuit (or None if there is none)

Returns:: the root key identifier
Return type:: int