Specification fixes and rewriting #181
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Geal
commented
May 10, 2025
| is a Biscuit token, that base 64 string should be prefixed with `biscuit:`. | ||
|
|
||
| ### Cryptography | ||
| ## Cryptography |
Contributor
Author
There was a problem hiding this comment.
Putting the cryptography section at the same level as the format section
Geal
commented
May 10, 2025
| If all signatures are verified, extract pk_n+1 from the last block and | ||
| sig from the proof field, and check `verify(pk_n+1, sig_n+1, data_n+alg_n+1+pk_n+1+sig_n)` | ||
|
|
||
| ### Blocks |
Contributor
Author
There was a problem hiding this comment.
this is already covered in a different part of the spec
Geal
commented
May 10, 2025
| them with its rules list. | ||
|
|
||
| ### Symbol table | ||
| ## Symbol table |
Contributor
Author
There was a problem hiding this comment.
the symbol table section is moving up a level. Maybe it should move under the format section though?
Contributor
There was a problem hiding this comment.
maybe we should rename it to "string interning", since it’s not just a serialization matter
divarvel
reviewed
May 12, 2025
Contributor
divarvel
left a comment
divarvel
left a comment
There was a problem hiding this comment.
a few comments / suggestions / typo fixes
| transmitted over the wire is either the normal Biscuit wrapper: | ||
| The token contains two levels of serialization, each with its own versioning scheme. | ||
|
|
||
| ### Signed blocks |
Contributor
There was a problem hiding this comment.
Suggested change
| ### Signed blocks | |
| ### Signed blocks | |
| } | ||
| ``` | ||
|
|
||
| The `rootKeyId` is a hint to decide which root public key should be used |
Contributor
There was a problem hiding this comment.
Suggested change
| The `rootKeyId` is a hint to decide which root public key should be used | |
| The `rootKeyId` is a hint to help the consumer decide which root public key should be used |
|
|
||
| The `rootKeyId` is a hint to decide which root public key should be used | ||
| for signature verification. | ||
| The `authority` block has a special meaning, as it is signed by the root key, |
Contributor
There was a problem hiding this comment.
these should be bullet points or have a line break after them
| } | ||
| ``` | ||
|
|
||
| The `SignedBlock` structure carries the sigend data and its signatures, representing the |
Contributor
There was a problem hiding this comment.
Suggested change
| The `SignedBlock` structure carries the sigend data and its signatures, representing the | |
| The `SignedBlock` structure carries the signed data and its signatures, representing the |
| - `externalSignature`: if present, it is a signature of the current block by another key | ||
| - `version`: indicates the version of the signed payload format | ||
|
|
||
| The version field is used to vary how the block is signed and verified. |
Contributor
There was a problem hiding this comment.
Suggested change
| The version field is used to vary how the block is signed and verified. | |
| The version field is used to specify how the block was signed and must be verified. |
| The `rootKeyId` is a hint to decide which root public key should be used | ||
| for signature verification. | ||
| Public keys are serialized as a byte array, with the `algorithm` field discriminating between | ||
| algorithms. The algorithm depedent serialization format is described in the [Cryptography section](#Algorithms). |
Contributor
There was a problem hiding this comment.
Suggested change
| algorithms. The algorithm depedent serialization format is described in the [Cryptography section](#Algorithms). | |
| algorithms. The algorithm-dependent serialization format is described in the [Cryptography section](#Algorithms). |
| ``` | ||
|
|
||
| Each `SignedBlock` contains: | ||
| - `block`: a `Block` structure serialized as a byte array |
Contributor
There was a problem hiding this comment.
maybe we should hint that why there are two layers of serialization (unless it’s already done somewhere else)
| was generated. Since a Biscuit implementation at version N can receive a valid | ||
| Each `Block` contains the following fields: | ||
| - `symbols`: the list of new [symbols](#symbol-table) introduced in this block. | ||
| - `context`: a free form field with no particular meaning for Biscuit authorization. It can be used to hold application specific data |
Contributor
There was a problem hiding this comment.
Suggested change
| - `context`: a free form field with no particular meaning for Biscuit authorization. It can be used to hold application specific data | |
| - `context`: a free-form field with no particular meaning for Biscuit authorization. It can be used to hold application specific data |
|
|
||
| When transmitted as text, a Biscuit token should be serialized to a | ||
| URLS safe base 64 string. When the context does not indicate that it | ||
| URL safe base 64 string. When the context does not indicate that it |
Contributor
There was a problem hiding this comment.
Suggested change
| URL safe base 64 string. When the context does not indicate that it | |
| URL-safe base 64 string. When the context does not indicate that it |
| them with its rules list. | ||
|
|
||
| ### Symbol table | ||
| ## Symbol table |
Contributor
There was a problem hiding this comment.
maybe we should rename it to "string interning", since it’s not just a serialization matter
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.