From 3e3c752974b0ce8d2c1960ab2bed611404d9ee0f Mon Sep 17 00:00:00 2001
From: Vincent Prouillet <vincent@wearewizards.io>
Date: Thu, 13 Apr 2017 10:29:30 +0900
Subject: [PATCH] Update README

---
 README.md                             | 54 ++++++++++++++++++++-------
 examples/{claims.rs => validation.rs} | 20 +++-------
 2 files changed, 45 insertions(+), 29 deletions(-)
 rename examples/{claims.rs => validation.rs} (72%)

diff --git a/README.md b/README.md
index 93da2a6..edcf517 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,8 @@
 Add the following to Cargo.toml:
 
 ```toml
-jsonwebtoken = "1"
-rustc-serialize = "0.3"
+jsonwebtoken = "2"
+serde_derive = "0.9"
 ```
 
 ## How to use
@@ -16,9 +16,10 @@ There is a complete example in `examples/claims.rs` but here's a quick one.
 In terms of imports:
 ```rust
 extern crate jsonwebtoken as jwt;
-extern crate rustc_serialize;
+#[macro_use]
+extern crate serde_derive;
 
-use jwt::{encode, decode, Header, Algorithm};
+use jwt::{encode, decode, Header, Algorithm, Validation};
 ```
 
 Look at the examples directory for 2 examples: a basic one and one with a custom
@@ -28,24 +29,43 @@ header.
 ```rust
 let token = encode(&Header::default(), &my_claims, "secret".as_ref()).unwrap();
 ```
-In that example, `my_claims` is an instance of a Claims struct that derives `RustcEncodable` and `RustcDecodable`.
+In that example, `my_claims` is an instance of a Claims struct that derives `Serialize` and `Deserialize`.
 The default algorithm is HS256.
 Look at custom headers section to see how to change that.
 
 ### Decoding
 ```rust
-let token = decode::<Claims>(&token, "secret", Algorithm::HS256).unwrap();
+let token = decode::<Claims>(&token, "secret", Algorithm::HS256, &Validation::default()).unwrap();
 // token is a struct with 2 params: header and claims
 ```
-In addition to the normal base64/json decoding errors, `decode` can return two custom errors:
+`decode` can error for a variety of reasons:
 
-- **InvalidToken**: if the token is not a valid JWT
-- **InvalidSignature**: if the signature doesn't match
-- **WrongAlgorithmHeader**: if the alg in the header doesn't match the one given to decode
+- the token or its signature is invalid
+- error while decoding base64 or the result of decoding base64 is not valid UTF-8
+- validation failed
 
 ### Validation
-The library only validates the algorithm type used but does not verify claims such as expiration.
-Feel free to add a `validate` method to your claims struct to handle that: there is an example of that in `examples/claims.rs`.
+This library validates automatically the `iat`, `exp` and `nbf` claims if found. You can also validate the `sub`, `iss` and `aud` but
+those require setting the expected value.
+You can add some leeway to the `iat`, `exp` and `nbf` validation by setting the `leeway` parameter as shown in the example below.
+
+```rust
+use jsonwebtoken::Validation;
+
+// Default valuation
+let validation = Validation::default();
+// Adding some leeway
+let mut validation = Validation {leeway: 1000 * 60, ..Default::default()};
+// Checking issuer
+let mut validation = Validation {iss: Some("issuer".to_string()), ..Default::default()};
+// Setting audience
+let mut validation = Validation::default();
+validation.set_audience(&"Me"); // string
+validation.set_audience(&["Me", "You"]); // array of strings
+```
+
+It's also possible to disable verifying the signature of a token by setting the `validate_signature` to `false`. This should
+only be done if you know what you are doing.
 
 ### Custom headers
 All the parameters from the RFC are supported but the default header only has `typ` and `alg` set: all the other fields are optional.
@@ -60,5 +80,11 @@ let token = encode(&header, &my_claims, "secret".as_ref()).unwrap();
 Look at `examples/custom_header.rs` for a full working example.
 
 ## Algorithms
-The HMAC SHA family is supported: HMAC SHA256, HMAC SHA384 and HMAC SHA512 as well as the RSA PKCS1: RSA_PKCS1_SHA256,
-RSA_PKCS1_SHA384 and RSA_PKCS1_SHA512.
+This library currently supports the following:
+
+- HS256
+- HS384
+- HS512
+- RS256
+- RS384
+- RS512
diff --git a/examples/claims.rs b/examples/validation.rs
similarity index 72%
rename from examples/claims.rs
rename to examples/validation.rs
index 4f75626..7ca0507 100644
--- a/examples/claims.rs
+++ b/examples/validation.rs
@@ -1,5 +1,6 @@
 extern crate jsonwebtoken as jwt;
-#[macro_use] extern crate serde_derive;
+#[macro_use]
+extern crate serde_derive;
 
 use jwt::{encode, decode, Header, Algorithm, Validation};
 use jwt::errors::{ErrorKind};
@@ -11,18 +12,6 @@ struct Claims {
     company: String
 }
 
-// Example validation implementation
-impl Claims {
-    fn is_valid(&self) -> bool {
-        if self.company != "ACME" {
-            return false;
-        }
-        // expiration etc
-
-        true
-    }
-}
-
 fn main() {
     let my_claims = Claims {
         sub: "b@b.com".to_owned(),
@@ -35,15 +24,16 @@ fn main() {
     };
 
     println!("{:?}", token);
+    let validation = Validation {sub: Some("b@b.com".to_string()), ..Validation::default()};
 
-    let token_data = match decode::<Claims>(&token, key.as_ref(), Algorithm::HS256, Validation::default()) {
+    let token_data = match decode::<Claims>(&token, key.as_ref(), Algorithm::HS256, validation) {
         Ok(c) => c,
         Err(err) => match *err.kind() {
             ErrorKind::InvalidToken => panic!(), // Example on how to handle a specific error
+            ErrorKind::InvalidIssuer => panic!(), // Example on how to handle a specific error
             _ => panic!()
         }
     };
     println!("{:?}", token_data.claims);
     println!("{:?}", token_data.header);
-    println!("{:?}", token_data.claims.is_valid());
 }