1 files changed, 72 insertions, 0 deletions
diff --git a/net/alcoholic_jwt/README.md b/net/alcoholic_jwt/README.md
new file mode 100644
index 000000000000..c6da0ab8da89
--- /dev/null
+++ b/net/alcoholic_jwt/README.md
@@ -0,0 +1,72 @@
+alcoholic_jwt
+=============
+
+This is a library for **validation** of **RS256** JWTs using keys from
+a JWKS. Nothing more, nothing less.
+
+RS256 is the most commonly used asymmetric signature mechanism for
+JWTs, encountered in for example [Google][]'s or [Aprila][]'s APIs.
+
+The name of the library stems from the potential side-effects of
+trying to use the other Rust libraries that are made for similar
+purposes.
+
+## Usage overview
+
+You are retrieving JWTs from some authentication provider that uses
+`RS256` signatures and provides its public keys in [JWKS][] format.
+
+Example for a token that provides the key ID used for signing in the
+[`kid` claim][]:
+
+```rust
+extern crate alcoholic_jwt;
+
+use alcoholic_jwt::{JWKS, Validation, validate, token_kid};
+
+// The function implied here would usually perform an HTTP-GET
+// on the JWKS-URL for an authentication provider and deserialize
+// the result into the `alcoholic_jwt::JWKS`-struct.
+let jwks: JWKS = jwks_fetching_function();
+
+let token: String = some_token_fetching_function();
+
+// Several types of built-in validations are provided:
+let validations = vec![
+  Validation::Issuer("auth.test.aprila.no".into()),
+  Validation::SubjectPresent,
+];
+
+// If a JWKS contains multiple keys, the correct KID first
+// needs to be fetched from the token headers.
+let kid = token_kid(&token)
+    .expect("Failed to decode token headers")
+    .expect("No 'kid' claim present in token");
+
+let jwk = jwks.find(&kid).expect("Specified key not found in set");
+
+validate(token, jwk, validations).expect("Token validation has failed!");
+```
+
+## Under the hood
+
+This library aims to only use trustworthy off-the-shelf components to
+do the work. Cryptographic operations are provided by the `openssl`
+crate, JSON-serialisation is provided by `serde_json`.
+
+## Contributing
+
+This project is developed in the [TVL monorepo][depot]. To work on it,
+you can either use a local clone of the entire repository or clone
+just the `alcoholic_jwt` subtree:
+
+    https://code.tvl.fyi/depot.git:/net/alcoholic_jwt.git
+
+Please follow the TVL [contribution guidelines][contributing].
+
+[Google]: https://www.google.com/
+[Aprila]: https://www.aprila.no/
+[JWKS]: https://tools.ietf.org/html/rfc7517
+[`kid` claim]: https://tools.ietf.org/html/rfc7515#section-4.1.4
+[depot]: https://code.tvl.fyi/
+[contributing]: https://code.tvl.fyi/about/docs/CONTRIBUTING.md