docs: Add initial README

1 files changed, 63 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 000000000000..2b1e766d57c4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+alcoholic_jwt
+=============
+
+This is a barebones library for **validation** of **RS256** JWTs using
+keys from a JWKS. Nothing more, nothing less.
+
+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};
+
+fn validate_token() {
+    // serde instances provided
+    let jwks: JWKS = some_http_client(jwks_url).json();
+
+    let token: String = some_token_fetcher();
+
+    // Several types of built-in validations are provided:
+    let validations = vec![
+      Validation::Issuer("some-issuer"),
+      Validation::Audience("some-audience"),
+      Validation::SubjectPresent,
+    ];
+
+    // Extracting a KID is about the only safe operation that can be
+    // done on a JWT before validating it.
+    let kid = token_kid(token).expect("No 'kid' claim present in token");
+
+    let jwk = jwks.find(kid).expect("Specified key not found in set");
+
+    match validate(token, jwk, validations) {
+      Valid => println!("Token is valid!"),
+      InvalidSignature(reason) => println!("Token signature invalid: {}", reason),
+      InvalidClaims(reasons) => {
+          println!("Token claims are totally invalid!");
+          for reason in reasons {
+              println!("Validation failure: {}", reason);
+          }
+      },
+    }
+}
+```
+
+## 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`.
+
+[JWKS]: https://tools.ietf.org/html/rfc7517
+[`kid` claim]: https://tools.ietf.org/html/rfc7515#section-4.1.4