Confused over version numbering

[pcolmer]

https://doc.biscuitsec.org/reference/specifications says:

bitwiseAnd, defined on integers, returns an integer (v4 only)
bitwiseOr, defined on integers, returns an integer (v4 only)
bitwiseXor, defined on integers, returns an integer (v4 only)

but https://www.biscuitsec.org/blog/biscuit-3-0/ says "Biscuit v3" adds "support for bitwise operators"

So which is it? V3 or V4 ... or is it v3 of the biscuit and v4 of the specifiction ... in which case how do I tell them apart and how do I know what the Go version supports???

[divarvel]

You are right, this is confusing. Long story short, there is a gap between the actual version number present in tokens (current: 4) and which is used in the specification, and the number used for public communication. The reason is that there was an issue with the version 3 blocks, discovered shortly after updating the spec, so we moved directly to the current version (4). From the outside though, we went from 2.0 to 3.0 (to add to the confusion, the spec itself has a losely defined version, but libraries have their own version scheme, and can have major version bumps unrelated to the biscuit version).

This has bothered me for some time, so i think we should do something about that.

To answer your question: trust the spec and the code, current version is 4 (single numbers, no dots). If you see 3.0 (with a dot, about the spec) it refers to 4. As for libraries themselves, their version number alone cannot tell you which version they support. The best way to know is to look at the code and the conformance suite.

[pcolmer]

Thanks, @divarvel

So given the existence of https://github.com/biscuit-auth/biscuit-go/issues/117, does that mean that the Go library currently only supports v2 biscuits, which means I can't use bitwise operators on biscuits because that is only possible on v4 biscuits?

[divarvel]

Indeed, biscuit-go does not support v4 blocks for now:

https://github.com/biscuit-auth/biscuit-go/blob/main/samples/samples_test.go#L144 all the samples containing v4 features are disabled in the test suite.

Adding support for bitwise operators and check all would be rather easy. The huge part is third-party blocks support.

[divarvel]

I'm not sure how I feel about releasing a version with partial support (I really don't know, it could perfectly well be okay). I think that could be part of the discussion about versions.

[tjohnston-cd]

So which repos implement the latest spec with all features? biscuit and by extension biscuit-cli, but not biscuit-rust for example?

Agreed that third-party block support in the go library would be really fantastic ;)

[divarvel]

biscuit is the spec, it does not contain any implementation. biscuit-rust is up-to-date to the spec, and biscuit-cli exposes biscuit-rust features, so is typically up-to-date as well.