From 705ce44a5f9b732dca275ceeb0dea1b4f2881172 Mon Sep 17 00:00:00 2001 From: Clement Delafargue Date: Tue, 4 Jul 2023 14:43:42 +0200 Subject: [PATCH] Update readme & remove mentions to caveats --- README.md | 17 +++++++++++------ SPECIFICATIONS.md | 2 +- SUMMARY.md | 2 +- 3 files changed, 13 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a6136ff..4d57587 100644 --- a/README.md +++ b/README.md @@ -16,41 +16,45 @@ architectures with the following properties: - **offline delegation**: a new, valid token can be created from another one by attenuating its rights, by its holder, without communicating with anyone; - **capabilities based**: authorization in microservices should be tied to rights - related to the request, instead of relying to an identity that might not make + related to the request, instead of relying on an identity that might not make sense to the verifier; - **flexible rights managements**: the token uses a logic language to specify attenuation - and add bounds on ambient data, it can model from small rules like expiration dates, + and add bounds on ambient data, what it can model ranges from small rules like expiration dates, to more flexible architectures like hierarchical roles and user delegation; - **small** enough to fit anywhere (cookies, etc). ## Non goals + - This is not a new authentication protocol. Biscuit tokens can be used as opaque tokens delivered by other systems such as OAuth. - Revocation: Biscuit generates unique revocation identifiers for each token, and can provide expiration dates as well, but revocation requires external state management (revocation lists, databases, etc) that is outside of this -specification. +specification. See the [revocation guide](https://www.biscuitsec.org/docs/guides/revocation/) +for more information. ## Roadmap You can follow the next steps on the [roadmap](https://github.com/biscuit-auth/biscuit/issues/12). Current status: + - the credentials language, cryptographic primitives and serialization format are done - we have implementations for biscuits v2 in - [Rust](https://github.com/biscuit-auth/biscuit-rust) - [Web Assembly](https://github.com/biscuit-auth/biscuit-wasm) (based on the Rust version) - - [Haskell](https://github.com/divarvel/biscuit-haskell) + - [Python](https://github.com/biscuit-auth/biscuit-python) (based on the Rust version) + - [Haskell](https://github.com/biscuit-auth/biscuit-haskell) - we have implementations for biscuits v1 in - [Java](https://github.com/clevercloud/biscuit-java) (migration to v2 is in progress) - - [Go](https://github.com/flynn/biscuit-go) + - [Go](https://github.com/biscuit-auth/biscuit-go) - a website with documentation and an interactive playground is live at - Currently deploying to real world use cases such as [Apache Pulsar](https://github.com/clevercloud/biscuit-pulsar) at [Clever Cloud](https://www.clever-cloud.com/) - looking for an audit of the token's design, cryptographic primitives and implementations ## How to help us? -- provide use cases that we can test the token on (some specific kind of caveats, auth delegation, etc) +- provide use cases that we can test the token on (some specific kind of checks, auth delegation, etc) - cryptographic design audit: we need reviews of algorithms, their usage and implementation in various languages - add support for biscuit v2 to java and go implementations @@ -58,6 +62,7 @@ Current status: - `SUMMARY.md`: introduction to Biscuit from a user's perspective - `SPECIFICATIONS.md` is the description of Biscuit, its format and behaviour +- `biscuit-web-key/` is a specification for publishing biscuit public keys - `DESIGN.md` holds the initial ideas about what Biscuit should be - `experimentations/` holds initial code examples for the crypographic schemes and caveat language. `code/biscuit-poc/` contains an experimental version of Biscuit, built to explore API issues diff --git a/SPECIFICATIONS.md b/SPECIFICATIONS.md index b27f12b..385a566 100644 --- a/SPECIFICATIONS.md +++ b/SPECIFICATIONS.md @@ -4,7 +4,7 @@ Biscuit is a bearer token that supports offline attenuation, can be verified by any system that knows the root public key, and provides a flexible -caveat language based on logic programming. It is serialized as +authorization language based on logic programming. It is serialized as Protocol Buffers [^protobuf], and designed to be small enough for storage in HTTP cookies. diff --git a/SUMMARY.md b/SUMMARY.md index cd3230a..1e34949 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -12,7 +12,7 @@ signature, without contacting the server that created the token. Each attenuatio is done by adding a new "block" of logic data and rules. It is not possible to remove or replace a block while keeping a valid signature. -Biscuit uses a logic language called [Datalog](https://en.wikipedia.org/wiki/Datalog), +Biscuit uses a logic language based on [Datalog](https://en.wikipedia.org/wiki/Datalog), to represent its authorization rules. It can model and combine authorization policies like role-based access control or capabilities in a few lines, and even have fine grained rules carried by the token.