jwt/jwt.go

// Copyright (C) 2018 Marius Schellenberger

// Package jwt provides a easy to use JSON Web Token and blacklisting library
package jwt

import (
	"crypto/hmac"
	"crypto/rand"
	"encoding/base64"
	"encoding/json"
	"errors"
	"io"
	"strings"
	"sync"
	"time"
)

const (
	// HTTPHeader is the default HTTP Authorization header name
	HTTPHeader = "Authorization"
	// DefaultExpiry is the default token expiration time
	DefaultExpiry = time.Hour * 12
	// KeySize is the secret key size
	KeySize = 64

	typ = "JWT"
)

// DefaultSecretReader is the default secret key generator
var DefaultSecretReader = rand.Reader

var (
	ErrNoJWT               = errors.New("not a json web token")
	ErrEmptyToken          = errors.New("token is empty")
	ErrUnsupportedAlg      = errors.New("unsupported algorithm")
	ErrInvalid             = errors.New("token validation failed")
	ErrBlacklisted         = errors.New("token blacklisted")
	ErrBlacklistNotEnabled = errors.New("blacklisting is not enabled")
	ErrNBF                 = errors.New("token not valid yet")
	ErrEXP                 = errors.New("token expired")
	ErrMissingNBF          = errors.New("missing nbf claim")
	ErrMissingEXP          = errors.New("missing exp claim")
	ErrMissingTokenParts   = errors.New("missing token parts")
	ErrEmptySignature      = errors.New("token signature is empty")
	ErrTokenIsNil          = errors.New("token is nil")
	ErrInvalidKeySize      = errors.New("invalid secret key size")
)

// JWT represents the JSON Web Token signing and blacklisting infrastructure
type JWT struct {
	key    []byte
	expiry time.Duration

	blacklist Blacklist
	stopOnce  sync.Once
	done      chan struct{}
}

// New returns a new JWT object with the given expiry timeout.
// If the timeout is less or equal to zero the default expiry (12 hours) is used.
// If blacklisting is enabled, the JWT object leaks a goroutine to garbage-collect expired blacklisted tokens.
// Call the Stop() method to exit the goroutine.
func New(expiry time.Duration, blacklist Blacklist, secret io.Reader) (*JWT, error) {
	if expiry <= 0 {
		expiry = DefaultExpiry
	}
	if secret == nil {
		secret = DefaultSecretReader
	}
	secret = io.LimitReader(secret, KeySize)
	key := make([]byte, KeySize)
	i, err := secret.Read(key)
	if err != nil {
		return nil, errors.New("secret reader error: " + err.Error())
	}
	if i < KeySize {
		return nil, ErrInvalidKeySize
	}
	jwt := &JWT{
		key:       key,
		expiry:    expiry,
		blacklist: blacklist,
	}
	if blacklist != nil {
		jwt.done = make(chan struct{})
		go jwt.clean()
	}
	return jwt, nil
}

// sum calculates the HMAC hash sum of the token
func (jwt *JWT) sum(token string, h Hash) []byte {
	mac := hmac.New(h.Hash, jwt.key)
	mac.Write([]byte(token))
	return mac.Sum(nil)
}

// Invalidate checks if a token is already blacklisted
// If the token is not blacklisted, it will get blacklisted
func (jwt *JWT) Invalidate(t *Token) error {
	if jwt.blacklist == nil {
		return ErrBlacklistNotEnabled
	}
	if t == nil {
		return ErrTokenIsNil
	}
	if err := jwt.blacklisted(t.Sig()); err != nil {
		return err
	}
	header := t.Header()
	if header.GetString("typ") != typ {
		return ErrNoJWT
	}
	h := ParseHash(header.GetString("alg"))
	if h == nil {
		return ErrUnsupportedAlg
	}
	exp := t.Claims.GetInt64("exp")
	switch {
	case exp == 0:
		return ErrMissingEXP
	case time.Now().UTC().Unix() > exp:
		return ErrEXP
	}
	if !hmac.Equal(jwt.sum(t.Data(), h), t.RawSig()) {
		return ErrInvalid
	}
	jwt.blacklist.Add(t.Sig(), exp)
	return nil
}

// blacklisted checks if a token is blacklisted
func (jwt *JWT) blacklisted(sig string) error {
	if sig == "" {
		return ErrEmptySignature
	}
	if jwt.blacklist.Check(sig) {
		return ErrBlacklisted
	}
	return nil
}

// clean looks for expired blacklisted tokens and removes them
func (jwt *JWT) clean() {
	for {
		t := time.NewTimer(time.Hour)
		select {
		case <-t.C:
		case <-jwt.done:
			t.Stop()
			return
		}
		now := time.Now().UTC().Unix()
		for k, v := range jwt.blacklist.Map() {
			if now > v {
				jwt.blacklist.Remove(k)
			}
		}
	}
}

// Sign will sign the provided token using the secret key
// This will overwrite existing 'exp' and 'nbf' claims
func (jwt *JWT) Sign(t *Token) (err error) {
	if t == nil {
		return ErrTokenIsNil
	}
	header := t.Header()
	if header.GetString("typ") != typ {
		return ErrNoJWT
	}
	h := ParseHash(header.GetString("alg"))
	if h == nil {
		return ErrUnsupportedAlg
	}
	now := time.Now().UTC()
	t.Claims.Set("exp", now.Add(jwt.expiry).Unix())
	t.Claims.Set("nbf", now.Unix())
	head, err := json.Marshal(header)
	if err != nil {
		return
	}
	claims, err := json.Marshal(t.Claims)
	if err != nil {
		return
	}
	t.data = strings.Join([]string{base64.URLEncoding.EncodeToString(head), base64.URLEncoding.EncodeToString(claims)}, ".")
	t.rawSignature = jwt.sum(t.data, h)
	t.signature = base64.URLEncoding.EncodeToString(t.rawSignature)
	t.raw = strings.Join([]string{t.data, t.signature}, ".")
	return
}

// Verify will verify the provided token using the secret key
func (jwt *JWT) Verify(t *Token) error {
	if t == nil {
		return ErrTokenIsNil
	}
	if jwt.blacklist != nil {
		if err := jwt.blacklisted(t.Sig()); err != nil {
			return err
		}
	}
	now := time.Now().UTC().Unix()
	header := t.Header()
	if header.GetString("typ") != typ {
		return ErrNoJWT
	}
	h := ParseHash(header.GetString("alg"))
	if h == nil {
		return ErrUnsupportedAlg
	}
	exp := t.Claims.GetInt64("exp")
	switch {
	case exp == 0:
		return ErrMissingEXP
	case now > exp:
		return ErrEXP
	}
	nbf := t.Claims.GetInt64("nbf")
	switch {
	case nbf == 0:
		return ErrMissingNBF
	case now < nbf:
		return ErrNBF
	}
	if !hmac.Equal(jwt.sum(t.Data(), h), t.RawSig()) {
		return ErrInvalid
	}
	return nil
}

// Stop will end the cleaner goroutinge execution
func (jwt *JWT) Stop() error {
	if jwt.blacklist == nil {
		return ErrBlacklistNotEnabled
	}
	jwt.stopOnce.Do(func() {
		close(jwt.done)
	})
	return nil
}