mirror of
https://github.com/biscuit-auth/biscuit.git
synced 2024-09-11 06:15:30 +03:00
Describe caveats, as discussed with tarcieri and geal
This commit is contained in:
parent
e0e6943196
commit
cd5b1121c4
61
DESIGN.md
61
DESIGN.md
@ -61,8 +61,69 @@ specific authorizations
|
||||
- capabilities: a request carries a token that contains a set of rights
|
||||
that will be used for authorization, instead of deploying ACLs on every node
|
||||
|
||||
|
||||
## Structure and semantics
|
||||
|
||||
A biscuit is structured as a cryptographic, append-only list; its elements are
|
||||
called *caveats*, and describe authorization properties. As with Macaroons,
|
||||
an operation must comply with all caveats in order to be allowed by the biscuit.
|
||||
|
||||
Caveats describe which operations are authorized by providing predicates over
|
||||
the operation's attributes.
|
||||
|
||||
Attributes are data, associated with the operation,
|
||||
that is known when the policy is evaluated, such as an identifier for the
|
||||
ressource being accessed, the type of the operation (read, write, append, ...),
|
||||
the operation's parameters (if any), the client's IP address or a
|
||||
channel-binding value (like the TLS transcript hash).
|
||||
|
||||
Available attributes, and their type, are known ahead of time by the verifier.
|
||||
Some of those attributes are *critical*, and all caveats must provide a *bound*
|
||||
for each critical attribute.
|
||||
|
||||
Bounds are a subset of predicates, that only allow the following:
|
||||
- `any`: all values match;
|
||||
- `in <subset>`: only elements in `subset` match; this can be an explicit
|
||||
enumeration, or a (non-infinite) range in the case of numeric types.
|
||||
|
||||
|
||||
### Rationale
|
||||
|
||||
Some attributes grant authority (such as ressource identifiers, operation type,
|
||||
...), and failing to include a caveat limiting acceptable values is a common
|
||||
failure with Macaroons, resulting in authority being accidentally granted.
|
||||
|
||||
By marking them critical, two things are achieved:
|
||||
- They must be bound by caveats, preventing accidental authority grants when new
|
||||
values are added.
|
||||
- Their presence is required in all caveats for a biscuit to be valid; as such:
|
||||
- if developers accidentally fail to provide a bound, the biscuit is invalid;
|
||||
- biscuits issued before the attribute was defined are implicitely revoked.
|
||||
|
||||
For example, consider a data store, which initially only provides read access.
|
||||
Assume I was granted a biscuit for ressources in it, before a developper
|
||||
implemented read-write access, along with a `type` attribute (which can be
|
||||
`Read` or `Write`). My biscuit suddenly grants me read-write access.
|
||||
|
||||
Marking the `type` attribute as critical means that I must request a new
|
||||
biscuit, that properly specifies whether my access is read and/or write.
|
||||
|
||||
Now, if I was to be issued a biscuit with the caveat `type != Write`, before the
|
||||
types `Append`, `Create`, and `Delete` were added, my the biscuit would again go
|
||||
from granting read-only access to granting write access; this is why critical
|
||||
attributes must use bounds.
|
||||
|
||||
|
||||
By requiring that all caveats provide a bound for each critical attribute, we
|
||||
can guarantee that a biscuit does not gain unintended authority when new
|
||||
attributes, or new values for them, are added in the system. (The use of `any`
|
||||
is considered intentional.)
|
||||
|
||||
|
||||
## Format
|
||||
|
||||
XXXTODO: Update for caveats
|
||||
|
||||
A biscuit token is an ordered list of key and value tuples, stored in HPACK
|
||||
format. HPACK was chosen to avoid specifying yet another serialization format,
|
||||
and reusing its data compression features to make tokens small enough to
|
||||
|
Loading…
Reference in New Issue
Block a user