Biscuit web key sets

[divarvel]

Similar to JWKs, it would be good to have a standard way of exposing biscuit public keys. Thanks to conservative choices made in the biscuit specification, there is less room for footguns than with JWTs, but still there are a few things we need to get right.

A refresher on biscuit keys and signature algorithms

• for now, biscuits only support one signature algorithm: ed25519
• the token format itself allows for multiple signature algorithms (even if only ed25519 is supported)
• the signature itself is an opaque string, only the key itself carries information about the signature algorithm
• the authority block can carry an optional u32 id field, as a hint for which public key should be used (it is primarily intended to aid with key rotation: the hint is there to help select the verifying key from a set of trusted keys)
• datalog code can reference a public key via its algorithm + the serialized key

Goals

The main goal is to help a verifying party select a suitable key when they wish to verify a token, using DNS and TLS as a way to discover and trust the public key.

An extra goal would be to allow a token emitter (or attenuator) select a suitable key for use in a trusting annotation requiring the addition of a third-party block.

Proposed solutions

The biscuit spec could define:

• a well-known URI (eg: /.well-known/biscuit-web-keys)
• a JSON schema for the associated resource representation
• a canonical way to verbalize the bwk acronym (I suggest "bivouac")

JSON representation

The representation could be an array of objects (one object per key) containing the following fields:

• required the key algorithm (for now, only ed25519)
• required the serialized key itself
• required/unique for the domain a key id (intended to be consistent with the optional field in the biscuit token)
• optional an expiration date for the key

A few remarks:

• Making the key id required and unique in the bwks would make things more robust, but it's optional in the tokens themselves.
• Currently a biscuit does not carry any information about its issuer, and the key id is optional and intended only as a hint do choose a key from within an already trusted set.

[divarvel]

Here is a possible JSON schema:

 {
  "$schema": "http://json-schema.org/draft-2020-12/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "algorithm": {
        "type": "string",
        "enum": [
          "ed25519"
        ]
      },
      "keyBytes": {
        "type": "string",
        "pattern": "^([0-9a-fA-F]{2})*$"
      },
      "keyId": {
        "type": "integer"
      },
      "expiresAt": {
        "type": "string",
        "format": "date-time"
      }
    },
    "issuer": { "type": "string" },
    "required": [
      "algorithm",
      "keyBytes",
      "keyId"
    ]
  }
}

And an example value:

[ { "algorithm": "ed25519", "keyBytes": "cb998b406b6bfc4bcc87592c4cfcd55c574262c23694978fd4e5304830ee9fc4", "keyId": 1230, "expiresAt": "2022-01-01T00:00:00Z" },
  { "algorithm": "ed25519", "keyBytes": "bbe548523d48832d4bf0e967f0913803692e5b6dde1ddd6388d35455f56edb8b", "keyId": 1231, "expiresAt": "2022-01-01T00:00:00Z" , "issuer": "issuer#1" },
  { "algorithm": "ed25519", "keyBytes": "3d60a072d7ebd431f9cd266dd2b50ce3ed1f9fca2f4a1d1c698fc012d6051edc", "keyId": 1232 }
]

Please note:

• for now there is only one possible algorithm value: ed25519
• keyBytes are required to be hex-encoded, but no specific length is enforced because different algorithms will have different key lengths
• keyId is required and encoded as a JSON number. This is okay because keyId is an u32, which can be losslessly represented as an f64 value (this type is commonly used in JSON libraries to encode numbers). This would not have been possible with an u64 which cannot be exactly represented by an f64 value
• expiresAt is represented by a RFC3339 datetime value, and not a timestamp, since an f64 value can cause precision loss. This is also easier to read

[Geal]

This sounds good. Maybe there should be an issuer field, like in JWKS, because the case will appear where key sets come from different issuers

[divarvel]

my initial reasoning was the issuer was tied to the domain name under which the key set is published. An optional issuer field would allow finer-grained grouping indeed. In any case, the value of the issuer field would have to be logically scoped to the domain name under which the BWK is published.

As long as the issuer information is determined out-of-band and not derived from the token itself 👍

I have updated the schema and example accordingly.

[woile]

I think it looks good. I would prefer snake_case for key names, similar to oauth or oidc well-known endpoints (e.g: expires_at).

A bit off-topic, biscuit could be one algorithm used by oauth/oidc, right? how would the workflow be between these 2? Read /.well-known/openid-configuration, get token_endpoint_auth_methods_supported where one would be private_key_biscuit and then your app has to be aware that because there's a biscuit, it can fetch the public keys from /.well-known/biscuit-web-keys?

[divarvel]

i have opened a PR, and switched the fields to snake case indeed.

[woile]

Just checking, are you also gonna submit it to the well-known` URI's?

[divarvel]

Just checking, are you also gonna submit it to the well-known` URI's?

Not for now, since the biscuit spec is not airtight (currently, the spec is more of a guidance document / documentation on how the rust implementation works, the actual reference is the rust implementation). We'd like things to be stabler before committing ourselves to stability more officially.

You might be interested in https://github.com/biscuit-auth/biscuit-rust/pull/173