Slightly more compact documentation & examples to prevent confusion.

README.md

@@ -7,8 +7,8 @@
 … a JSON Web Token (JWT) library for the Go programming language.
 
 * Feature complete
-* No third-party dependencies
-* Full unit test coverage
+* Full test coverage
+* Dependency free
 
 The API enforces secure use by design. Unsigned tokens are rejected.
 No support for encrypted tokens either—use wire encryption instead.
@@ -20,24 +20,21 @@ This is free and unencumbered software released into the
 ## Introduction
 
 Tokens encapsulate signed statements called claims. A claim is a named JSON
-value. The names in use are application specific. The JWT specification defines
-[7 common claims](https://godoc.org/github.com/pascaldekloe/jwt#Registered)
-plus an IANA registration.
+value. Applications using JWTs should define which specific claims they use and
+when they are required or optional.
 
 ```go
 var claims jwt.Claims
 claims.Subject = "[email protected]"
 claims.Issued  = jwt.NewNumericTime(time.Now().Round(time.Second))
-claims.Set     = map[string]interface{}{
-	"email_verified": true,
-}
+claims.Set     = map[string]interface{}{"email_verified": false}
 // issue a JWT
 token, err := claims.EdDSASign(JWTPrivateKey)
 ```
 
 Tokens consists of printable ASCII characters, e.g.,
 `eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiJha3JpZWdlciIsInByZWZpeCI6IkRyLiJ9.RTOboYsLW7zXFJyXtIypOmXfuRGVT_FpDUTs2TOuK73qZKm56JcESfsl_etnBsl7W80TXE5l5qecrMizh3XYmw`.
-Secured resources can use such tokens to determine permissions.
+Secured resources can use such tokens to determine the respective permissions.
 Note how the verification process is self-contained with just a public key.
 
 ```go
@@ -54,7 +51,6 @@ if !claims.Valid(time.Now()) {
 log.Print("hello ", claims.Subject)
 ```
 
-
 Commonly, agents receive a JWT uppon authentication/login. Then, that token is
 included with requests to the secured resources, as a proof of authority. Token
 access is “eyes only” in such scenario. Include and enforce more context detail
@@ -117,7 +113,7 @@ func Greeting(w http.ResponseWriter, req *http.Request) {
 ```
 
 The validated [Claims](https://godoc.org/github.com/pascaldekloe/jwt#Claims)
-object can also be made available through the
+object may also be exposed through the
 [request context](https://godoc.org/github.com/pascaldekloe/jwt#example-Handler--Context).
 
 

extend_test.go

@@ -2,45 +2,40 @@ package jwt_test
 
 import (
 	"crypto"
-	_ "crypto/sha1" // link into binary
+	_ "crypto/md5" // link into binary
 	"fmt"
 
 	"github.com/pascaldekloe/jwt"
 )
 
-// SHA1 Algorithm Extensions
-const (
-	HS1 = "HS1"
-	RS1 = "RS1"
-)
-
 func init() {
-	// static registration
-	jwt.HMACAlgs[HS1] = crypto.SHA1
-	jwt.RSAAlgs[RS1] = crypto.SHA1
+	// additional algorithm registration
+	jwt.HMACAlgs["MD5"] = crypto.MD5
 }
 
+// Non-Standard Algorithm Use
 func Example_extend() {
 	c := new(jwt.Claims)
 	c.ID = "Me Too!"
 
 	// issue with custom algorithm
-	token, err := c.HMACSign(HS1, []byte("guest"))
+	token, err := c.HMACSign("MD5", []byte("guest"))
 	if err != nil {
 		fmt.Println("sign error:", err)
 		return
 	}
 	fmt.Println("token:", string(token))
+	fmt.Println("header:", string(c.RawHeader))
 
 	// verify custom algorithm
 	got, err := jwt.HMACCheck(token, []byte("guest"))
 	if err != nil {
 		fmt.Println("check error:", err)
 		return
 	}
-	fmt.Println("JSON:", string(got.Raw))
-
+	fmt.Println("payload:", string(got.Raw))
 	// Output:
-	// token: eyJhbGciOiJIUzEifQ.eyJqdGkiOiJNZSBUb28hIn0.hHye7VnslIM4jO-MoBfggMe8MUQ
-	// JSON: {"jti":"Me Too!"}
+	// token: eyJhbGciOiJNRDUifQ.eyJqdGkiOiJNZSBUb28hIn0.W5dsc6-lD0Bgc58TP_YOTg
+	// header: {"alg":"MD5"}
+	// payload: {"jti":"Me Too!"}
 }