From 29dfb6826f8c543f0a0050af8f00d2b316207607 Mon Sep 17 00:00:00 2001
From: Vincent Ambo <mail@tazj.in>
Date: Tue, 4 Sep 2018 12:36:59 +0200
Subject: docs: Update README to match new library API

---
 README.md  | 56 ++++++++++++++++++++++++--------------------------------
 src/lib.rs | 11 +++++++----
 2 files changed, 31 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index 2b1e766d57c4..75f3bb9839ed 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 alcoholic_jwt
 =============
 
-This is a barebones library for **validation** of **RS256** JWTs using
-keys from a JWKS. Nothing more, nothing less.
+This is a 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
@@ -21,36 +21,28 @@ 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);
-          }
-      },
-    }
-}
+// 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
diff --git a/src/lib.rs b/src/lib.rs
index a61e793e2c17..108c60c677ee 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,9 @@
-//! Implements a library for verifying JSON Web Tokens using the
-//! `RS256` signature algorithm.
+//! Implements a library for 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.
 //!
 //! This library is specifically aimed at developers that consume
 //! tokens from services which provide their RSA public keys in
@@ -21,8 +25,7 @@
 //! #   let jwks_json = "{\"keys\":[{\"kty\":\"RSA\",\"alg\":\"RS256\",\"use\":\"sig\",\"kid\":\"8rDq8Pw0FZcaoXWTEVQo7+Tf2YzSL1fBxNKPCebaai4=\",\"n\":\"l4UTgk1zr-8C8utt0E57DtBV6qqAPWzVRrIuQS2j0_hp2CviaNl5XzGRDnB8gwk0Hx95YOhJupAe6RNq5ok3fDdxL7DLvppJNRLz3Ag9CsmDLcbXgNEQys33fBJaPw1v3GcaFC4tisU5p-o1f5RfWwvwdBtdBfGiwT1GRvbc5sFx6M4iYjg9uv1lNKW60PqSJW4iDYrfqzZmB0zF1SJ0BL_rnQZ1Wi_UkFmNe9arM8W9tI9T3Ie59HITFuyVSTCt6qQEtSfa1e5PiBaVuV3qoFI2jPBiVZQ6LPGBWEDyz4QtrHLdECPPoTF30NN6TSVwwlRbCuUUrdNdXdjYe2dMFQ\",\"e\":\"DhaD5zC7mzaDvHO192wKT_9sfsVmdy8w8T8C9VG17_b1jG2srd3cmc6Ycw-0blDf53Wrpi9-KGZXKHX6_uIuJK249WhkP7N1SHrTJxO0sUJ8AhK482PLF09Qtu6cUfJqY1X1y1S2vACJZItU4Vjr3YAfiVGQXeA8frAf7Sm4O1CBStCyg6yCcIbGojII0jfh2vSB-GD9ok1F69Nmk-R-bClyqMCV_Oq-5a0gqClVS8pDyGYMgKTww2RHgZaFSUcG13KeLMQsG2UOB2OjSC8FkOXK00NBlAjU3d0Vv-IamaLIszO7FQBY3Oh0uxNOvIE9ofQyCOpB-xIK6V9CTTphxw\"}]}";
 //! #   serde_json::from_str(jwks_json).unwrap()
 //! # }
-//!
-//!
+//! #
 //! // 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.
-- 
cgit 1.4.1