Command Line
Install
From pre-built packages
Pre-built packages are available: https://github.com/biscuit-auth/biscuit-cli/releases/latest
With cargo
cargo install biscuit-cli
From source
git clone https://github.com/biscuit-auth/biscuit-cli.git
cd biscuit-cli
cargo install --path .
Create a key pair
$ # this will output the keypair, you can then copy/paste the components
$ biscuit keypair
> Generating a new random keypair
> Private key: 4aa4bae701c6eb05cfe0bdd68d5fab236fc0d0d3dcb2a9b582a0d87b23e04500
> Public key: 687b536c502f10f5978eee2d0c04f2869d15cf7858983dc50b6729b15e203809
$ # this will save the private key to a file so you can use it later
$ biscuit keypair --only-private-key > private-key-file
$ cat private-key-file
> e4d17ae4fd444ace42ab0a813c242643cf9b4ef96ca07c502e8e72142a3e8a2e
Generate a public key from a private key
$ biscuit keypair --from-private-key-file private-key-file --only-public-key
> 51c20fb821f7d6a3939fba5c80f0915d80087799de6988a3259c6782bea93d7f
$ biscuit keypair --from-private-key-file private-key-file --only-public-key > public-key-file
Create a token
$ # this will open your text editor and let you type in the authority block as datalog
$ biscuit generate --private-key-file private-key-file
> ChcIADgBQhEKDwgEEgIIABIHIgVmaWxlMRoglMviMbBdrIrlVsOaPNw9EhA62e1VAO2mCYxg5mcr-FgiRAogKAZh5JjRh6n3UTQIVlptzWsAhj92UaOjWZQOVYYqaTASIFG7bXx0Y35LjRWcJHs7N6CAEOBJOuuainDg4Rg_S8IG
$ cat << EOF > authority-block
right("file1");
EOF
$ # this will read the authority block from a file
$ biscuit generate --private-key-file private-key-file authority-block
> En4KFAoFZmlsZTEYAyIJCgcIBBIDGIAIEiQIABIgyOeDz8eTDEWRtx5NBlsL_ajPBg2CmhLj_xylsxpyaPQaQNXM41V4wk-NGskgvcV6ygh1xL7CqxE51urXKqC81DvEkBNxYlr-cgq2hr0M13pLFxc0pKontpWYQiESNXIa9AEiIgog5v8ptssVfc3ES9eDArruxmaOBRm0n95SitePxoMzFPk=
$ # this will read the authority block from standard input
$ echo 'right("file1");' | biscuit generate --private-key-file private-key-file -
> En4KFAoFZmlsZTEYAyIJCgcIBBIDGIAIEiQIABIgtuIug-thwbWXD8Kt8UqQJCiqe80n4527AiyOV7drwvgaQCpDRNl7dsjBwGzqJMh2qHz2Az6b15kczqkVhJjuKabvZ0q5h_dhVxjYdxMvTJNrL-AictItXU4aqngpIHyLsAciIgog1YhpZ9b8mLfZRW-Id2qLfwNFK2O5Nd4Xa9t9ffnQGeA=
$ # the biscuit can be generated as raw bytes, with no b64 encoding
$ echo 'right("file1");' | biscuit generate --raw --private-key-file private-key-file - > biscuit-file.bc
Inspect a token
$ biscuit inspect --raw-input biscuit-file.bc --public-key-file public-key-file
> Open biscuit
> Authority block:
> == Datalog ==
> right("file1");
>
> == Revocation id ==
> a1675990f0b23015019a49b6b003c14fcfd2be134c9899b8146f4f702f8089486ca20766e188cd3388eb8ef653327a78e2dc0f6e42d31be8d97b1c5a8488eb0e
==========
â
Public key check succeeded ð
ð Datalog check skipped ðĄïļ
Authorize a token
$ biscuit inspect --raw-input biscuit-file.bc \
--public-key-file public-key-file \
--authorize-with 'allow if right("file1");' \
--include-time
> Open biscuit
> Authority block:
> == Datalog ==
> right("file1");
>
> == Revocation id ==
> a1675990f0b23015019a49b6b003c14fcfd2be134c9899b8146f4f702f8089486ca20766e188cd3388eb8ef653327a78e2dc0f6e42d31be8d97b1c5a8488eb0e
>
> ==========
>
> â
Public key check succeeded ð
> â
Authorizer check succeeded ðĄïļ
> Matched allow policy: allow if right("file1")
Generate a snapshot
Biscuit inspect can store the authorization context to a file, which can be inspected later. The file will contain both the token contents, and the authorizer contents.
$ biscuit inspect --raw-input biscuit-file.bc \
--public-key-file public-key-file \
--authorize-with 'allow if right("file1");' \
--include-time \
--dump-snapshot-to snapshot-file
> Open biscuit
> Authority block:
> == Datalog ==
> right("file1");
>
> == Revocation id ==
> a1675990f0b23015019a49b6b003c14fcfd2be134c9899b8146f4f702f8089486ca20766e188cd3388eb8ef653327a78e2dc0f6e42d31be8d97b1c5a8488eb0e
>
> ==========
>
> â
Public key check succeeded ð
> â
Authorizer check succeeded ðĄïļ
> Matched allow policy: allow if right("file1")
Attenuate a token
# this will create a new biscuit token with the provided block appended
$ biscuit attenuate --raw-input biscuit-file.bc --block 'check if operation("read")'
> En4KFAoFZmlsZTEYAyIJCgcIBBIDGIAIEiQIABIgX9V0q_5ZU5NpVUKRF_Z8BPbLKl_9TL1bFeiqBQ97LFoaQKFnWZDwsjAVAZpJtrADwU_P0r4TTJiZuBRvT3AvgIlIbKIHZuGIzTOI6472UzJ6eOLcD25C0xvo2XscWoSI6w4afAoSGAMyDgoMCgIIGxIGCAMSAhgAEiQIABIgCxzPZaKjKJ6_C9cy39I16dgCLu9I5EqPNHwGiOl_eOMaQFU00BW0iFfxxt1pMp4vO-R26mPxx9XMKEEyx80Fugf1OFAPmTdefYVm_vp6rV02GcODrCF3C0Ua3QGopor7uAsiIgogSfbsyId59q50CqdJhxmBYXhqMYcTMYsB1eVnDNw3MTY=
# this will add a TTL check to an existing biscuit token
$ biscuit attenuate --raw-input biscuit-file.bc --add-ttl "1 day" --block ""
> En4KFAoFZmlsZTEYAyIJCgcIBBIDGIAIEiQIABIgX9V0q_5ZU5NpVUKRF_Z8BPbLKl_9TL1bFeiqBQ97LFoaQKFnWZDwsjAVAZpJtrADwU_P0r4TTJiZuBRvT3AvgIlIbKIHZuGIzTOI6472UzJ6eOLcD25C0xvo2XscWoSI6w4amQEKLwoBdBgDMigKJgoCCBsSBwgFEgMIgQgaFwoFCgMIgQgKCAoGIP7KrpMGCgQaAggAEiQIABIgU2t5XP1OA9VfujCZAZSVbBeE0WMBqMHViXwEhzoTkSAaQN1jHm8uqZVjhfO_J7URfL2NHK4_E7JJD45jvIFFgrgAmcksrhIc5qgyq1U7D0Jbo5tR7H4w3UvMN0sAEJzSjAoiIgogrolYRQ67V5SHiB7ii_YHPU5uwzDuHc1rL2WGKiAvH_c=
Seal a token
# this will prevent a biscuit from being attenuated further
$ biscuit seal --raw-input biscuit-file.bc
Inspect a snapshot
inspect-snapshot
displays the contents of a snapshot (facts, rules, checks, policies), as well as how much time has been spent evaluating datalog.
The authorization process can be resumed with --authorize-interactive
, --authorize-with
, or --authorize-with-file
.
The authorizer can be queried with --query
or --query-all
$ biscuit inspect-snapshot snapshot-file \
--authorize-with "" \
--query 'data($file) <- right($file)'
// Facts:
// origin: 0
right("file1");
// origin: authorizer
time(2023-11-17T13:59:04Z);
// Policies:
allow if right("file1");
âąïļ Execution time: 13Ξs (0 iterations)
â
Authorizer check succeeded ðĄïļ
Matched allow policy: allow if right("file1")
ð Running query: data($file) <- right($file)
data("file1")