Biscuit web key sets about biscuit

[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 biscuit-auth/biscuit-rust#173