Panic when following https://www.biscuitsec.org/docs/Usage/cli/

[Michael Schurter]

I tried following the CLI usage docs at https://www.biscuitsec.org/docs/Usage/cli/ and hit a panic.

Reproducible with the following:

Bad copy and paste

biscuit keypair --only-private-key > private-key-file
biscuit keypair --from-private-key-file private-key-file --only-public-key > public-key-file
echo 'right("file1");' | biscuit generate --private-key-file private-key-file - > biscuit-file.bc

# Note the missing --verify-with; I copied and pasted incorrectly from the docs
biscuit inspect --raw-input biscuit-file.bc --public-key-file public-key-file

Outputs:

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Format(DeserializationError("deserialization error: DecodeError { description: \"unexpected end group tag\", stack: [] }"))', /home/schmichael/.cargo/registry/src/github.com-1ecc6299db9ec823/biscuit-cli-0.2.0/src/main.rs:193:42
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

With RUST_BACKTRACE=1:

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Format(DeserializationError("deserialization error: DecodeError { description: \"invalid wire type value: 7\", stack: [] }"))', /home/schmichael/.cargo/registry/src/github.com-1ecc6299db9ec823/biscuit-cli-0.2.0/src/main.rs:193:42
stack backtrace:
   0: rust_begin_unwind
             at /rustc/7737e0b5c4103216d6fd8cf941b7ab9bdbaace7c/library/std/src/panicking.rs:584:5
   1: core::panicking::panic_fmt
             at /rustc/7737e0b5c4103216d6fd8cf941b7ab9bdbaace7c/library/core/src/panicking.rs:143:14
   2: core::result::unwrap_failed
             at /rustc/7737e0b5c4103216d6fd8cf941b7ab9bdbaace7c/library/core/src/result.rs:1749:5
   3: biscuit::main
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

Correct copy and paste

biscuit inspect --raw-input biscuit-file.bc --public-key acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189 --verify-with 'time(2021-11-01T14:44:44Z); check if false; deny if true;'`
> 

^ awaits user input as the command ends in a backtick.

Copy and paste with backtick removed

biscuit inspect --raw-input biscuit-file.bc --public-key-file public-key-file --verify-with 'time(2021-11-01T14:44:44Z); check if false; deny if true;'

Output:

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Format(DeserializationError("deserialization error: DecodeError { description: \"invalid wire type value: 7\", stack: [] }"))', /home/schmichael/.cargo/registry/src/github.com-1ecc6299db9ec823/biscuit-cli-0.2.0/src/main.rs:193:42
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

With BACKTRACE:

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Format(DeserializationError("deserialization error: DecodeError { description: \"invalid wire type value: 7\", stack: [] }"))', /home/schmichael/.cargo/registry/src/github.com-1ecc6299db9ec823/biscuit-cli-0.2.0/src/main.rs:193:42
stack backtrace:
   0: rust_begin_unwind
             at /rustc/7737e0b5c4103216d6fd8cf941b7ab9bdbaace7c/library/std/src/panicking.rs:584:5
   1: core::panicking::panic_fmt
             at /rustc/7737e0b5c4103216d6fd8cf941b7ab9bdbaace7c/library/core/src/panicking.rs:143:14
   2: core::result::unwrap_failed
             at /rustc/7737e0b5c4103216d6fd8cf941b7ab9bdbaace7c/library/core/src/result.rs:1749:5
   3: biscuit::main
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

[Clément Delafargue]

I've removed the backtick from the example, good catch!

I think the issue is that you save a base64-encoded biscuit to the file and read it as raw bytes. It should be fixed by either adding --raw to biscuit generate or by removing --raw-input from biscuit inspect.

The documentation is not strictly wrong, but misleading: it shows the base64 output in the console, but continues from an unencoded biscuit file.

Of course, the error messages are not friendly, they should be improved as well.

[Michael Schurter]

Removing --raw-input worked!

biscuit inspect biscuit-file.bc --public-key-file public-key-file --verify-with
'time(2021-11-01T14:44:44Z); check if false; deny if true;'
Authority block:
== Datalog ==
right("file1");

== Revocation id ==
97e84fea2118c27ae625bdd954c4419b27cafdd23d8adfb6d52322426a60f3dc7eeddac14c766fa194f258eff7a389e0da7def41912d21daa26a013aae34980a

==========

✅ Public key check succeeded 🔑
❌ Authorizer check failed 🛡️
A deny policy matched: deny if true
The following checks failed:
  Authorizer check: check if false

So I guess this could be re-classified as Improve error message and everything else is just a docs issue. The Verification example also includes 2 Datalog entries whereas the prior Create example only includes 1.

Thanks for the quick response!

[Clément Delafargue]

the error you would have gotten with the latest main would now be:

❯ echo "user(1234);" | biscuit generate --private-key $(biscuit keypair --only-private-key) - | biscuit inspect --raw-input -
[Error] error deserializing or verifying the token

(an extra step would be to try and recognize b64 / raw bytes confusion, but i'm not sure it's worth it)

[Clément Delafargue]

I've updated the doc with self-contained examples

[Clément Delafargue]

if you find it clearer now, i'll close the issue