gojwt

README

gojwt

Another JWT implementation written in Go. The package implements HS256, RS256, PS256 as well as others. The library can be further extended to support additional signing algorithms such as Elliptic Curve ECSDA. Inspired by JWT-GO.

Signing algorithms implemented:

• HMAC-SHA 256 (HS256)
• HMAC-SHA 512 (HS512)
• RSA-SHA256 (RS256)
• RSA-SHA512 (RS512)
• RSA-PSS-SHA256 (PS256)

Algorithms

HS vs RS

The main difference between the HMAC-SHA256 and RSA-SHA256 is that the HMAC-SHA256 requires the secret to be shared on every application in order to sign and verify the JWT. Thus possibly exposing your secret with one or more parties. RSA-SHA256 will use an RSA keypair allowing to verify the JWT without exposing the secret (private key) to all parties.

The PS (RSASSA-PSS) signature algorithm is an improved version of the PKCS#1 v1.5. PSS takes an input with a random number salt.

Basic usage

token := gojwt.NewToken(gojwt.HS256, &IanaClaims{})

Instantiation of the token struct is quite fast:

BenchmarkTokenInst-8   	293792617	         4.10 ns/op	       0 B/op	       0 allocs/op

Custom payloads

Custom payloads / claims must implement the Payload interface

type MyPayload struct {
	CustomField  string `json:"customfield,omitempty"`
}

func (t *MyPayload) Valid() error {
	return nil
}

Key generation using OpenSSL

Private and public keys can be generated using OpenSSL as shown below.

# private key without password
openssl genrsa -out rsa.key 4096

# private key with password
openssl genrsa -des3 -passout pass:mysecret -out rsa.key 4096

# extract public key from private keypair
openssl rsa -in rsa.key -pubout > rsa.pub

More examples

More examples will be added in the future.

Documentation

Overview

Another JWT implementation written in Go. The package implements HS256, RS256, PS256 as well as others. The library can be further extended to support additional signing algorithms such as Elliptic Curve ECSDA. Inspired by JWT-GO.

Index

• Constants
• Variables
• func DecodeSegment(seg string) ([]byte, error)
• func Parse(token *Token, tokenString string, validate bool) error
• func ParseRSAPrivateKey(key []byte, password []byte) (*rsa.PrivateKey, error)
• func ParseRSAPrivateKeyFromFile(filename string, password []byte) (*rsa.PrivateKey, error)
• func ParseRSAPublicKey(key []byte) (*rsa.PublicKey, error)
• func ParseRSAPublicKeyFromFile(filename string) (*rsa.PublicKey, error)
• func VerifyAud(iss string, cmp string) bool
• func VerifyExp(exp int64, now int64) bool
• func VerifyIat(iat int64, now int64) bool
• func VerifyIss(iss string, cmp string) bool
• func VerifyNbf(nbf int64, now int64) bool
• type Claims
• type IanaClaims
  • func (c IanaClaims) Valid() error
  • func (c *IanaClaims) VerifyAudience(cmp string) bool
  • func (c *IanaClaims) VerifyExpiresAt(cmp int64) bool
  • func (c *IanaClaims) VerifyIssuedAt(cmp int64) bool
  • func (c *IanaClaims) VerifyIssuer(cmp string) bool
  • func (c *IanaClaims) VerifyNotBefore(cmp int64) bool
• type SignMethod
• type SignMethodData
• type SignMethodHMAC
  • func (m SignMethodHMAC) Alg() crypto.Hash
  • func (m SignMethodHMAC) Sign(signinString string, key interface{}) (string, error)
  • func (m SignMethodHMAC) Verify(signingString string, signature string, key interface{}) error
• type SignMethodRSA
  • func (m SignMethodRSA) Alg() crypto.Hash
  • func (m SignMethodRSA) Sign(signinString string, key interface{}) (string, error)
  • func (m SignMethodRSA) Verify(signingString string, signature string, key interface{}) error
• type SignMethodRSAPSS
  • func (m SignMethodRSAPSS) Alg() crypto.Hash
  • func (m SignMethodRSAPSS) Sign(signinString string, key interface{}) (string, error)
  • func (m SignMethodRSAPSS) Verify(signingString string, signature string, key interface{}) error
• type Token
  • func NewToken(id uint, claims Claims) *Token
  • func (t *Token) Build() error
  • func (t *Token) Parse(tokenString string, validate bool) error
  • func (t *Token) Sign(key interface{}) error
  • func (t *Token) Validate() error
  • func (t *Token) Verify(key interface{}) error
• type TokenError
  • func (e *TokenError) Error() string

Constants

const (
	ErrorInvalidToken      uint32 = 1 << iota
	ErrorInvalidIssuer            // "iss" (Issuer)
	ErrorInvalidAudience          // "aud" (Audience)
	ErrorInvalidExpiration        // "exp" (Expiration Time)
	ErrorInvalidNotBefore         // "nbf" (Not Before)
	ErrorInvalidIssuedAt          // "iat" (Issued At)
	ErrorInvalidJti               // "jti" (JWT ID)
	ErrorInvalidClaim             // Generic error
	ErrorIvalidSignature          // Invalid signature
)

const (
	HS256 uint = 1 + iota
	HS512
	RS256
	RS512
	PS256
)

Variables

var (
	SignMethodTable = []SignMethodData{
		HS256: SignMethodData{
			Method: SignMethodHMAC{Hash: crypto.SHA256},
			Header: map[string]interface{}{"alg": "HS256", "typ": "JWT"},
		},
		HS512: SignMethodData{
			Method: SignMethodHMAC{Hash: crypto.SHA512},
			Header: map[string]interface{}{"alg": "HS512", "typ": "JWT"},
		},
		RS256: SignMethodData{
			Method: SignMethodRSA{Hash: crypto.SHA256},
			Header: map[string]interface{}{"alg": "RS256", "typ": "JWT"},
		},
		RS512: SignMethodData{
			Method: SignMethodRSA{Hash: crypto.SHA512},
			Header: map[string]interface{}{"alg": "RS512", "typ": "JWT"},
		},
		PS256: SignMethodData{
			Method: SignMethodRSAPSS{Hash: crypto.SHA256},
			Header: map[string]interface{}{"alg": "PS256", "typ": "JWT"},
		},
	}
)

Functions

func DecodeSegment

func DecodeSegment(seg string) ([]byte, error)

func Parse

func Parse(token *Token, tokenString string, validate bool) error

func ParseRSAPrivateKey

func ParseRSAPrivateKey(key []byte, password []byte) (*rsa.PrivateKey, error)

func ParseRSAPrivateKeyFromFile

func ParseRSAPrivateKeyFromFile(filename string, password []byte) (*rsa.PrivateKey, error)

func ParseRSAPublicKey

func ParseRSAPublicKey(key []byte) (*rsa.PublicKey, error)

func ParseRSAPublicKeyFromFile

func ParseRSAPublicKeyFromFile(filename string) (*rsa.PublicKey, error)

func VerifyAud

func VerifyAud(iss string, cmp string) bool

func VerifyExp

func VerifyExp(exp int64, now int64) bool

func VerifyIat

func VerifyIat(iat int64, now int64) bool

func VerifyIss

func VerifyIss(iss string, cmp string) bool

func VerifyNbf

func VerifyNbf(nbf int64, now int64) bool

Types

type Claims

type Claims interface {
	Valid() error
}

type IanaClaims

type IanaClaims struct {

	// The "iss" (issuer) claim identifies the principal that issued the JWT
	Issuer string `json:"iss,omitempty"`

	// The "sub" (subject) claim identifies the principal that is the
	// subject of the JWT
	Subject string `json:"sub,omitempty"`

	// The "aud" (audience) claim identifies the recipients that the
	// JWT is intended for.
	Audience string `json:"aud,omitempty"`

	// The "exp" (expiration time) claim identifies the expiration time on
	// or after which the JWT MUST NOT be accepted for processing.
	ExpiresAt int64 `json:"exp,omitempty"`

	// The "nbf" (not before) claim identifies the time before which the JWT
	// MUST NOT be accepted for processing.
	NotBefore int64 `json:"nbf,omitempty"`

	// The "iat" (issued at) claim identifies the time at which the JWT was
	// issued.
	IssuedAt int64 `json:"iat,omitempty"`

	// The "jti" (JWT ID) claim provides a unique identifier for the JWT.
	Jti string `json:"jti,omitempty"`
}

None of the claims defined below are intended to be mandatory to use or implement in all cases, but rather they provide a starting point for a set of useful, interoperable claims. See ref: https://tools.ietf.org/html/rfc7519

func (IanaClaims) Valid

func (c IanaClaims) Valid() error

func (*IanaClaims) VerifyAudience

func (c *IanaClaims) VerifyAudience(cmp string) bool

func (*IanaClaims) VerifyExpiresAt

func (c *IanaClaims) VerifyExpiresAt(cmp int64) bool

func (*IanaClaims) VerifyIssuedAt

func (c *IanaClaims) VerifyIssuedAt(cmp int64) bool

func (*IanaClaims) VerifyIssuer

func (c *IanaClaims) VerifyIssuer(cmp string) bool

func (*IanaClaims) VerifyNotBefore

func (c *IanaClaims) VerifyNotBefore(cmp int64) bool

type SignMethod

type SignMethod interface {
	Verify(string, string, interface{}) error
	Sign(string, interface{}) (string, error)
	Alg() crypto.Hash
}

type SignMethodData

type SignMethodData struct {
	Method SignMethod
	Header map[string]interface{}
}

type SignMethodHMAC

type SignMethodHMAC struct {
	Hash crypto.Hash
}

func (SignMethodHMAC) Alg

func (m SignMethodHMAC) Alg() crypto.Hash

func (SignMethodHMAC) Sign

func (m SignMethodHMAC) Sign(signinString string, key interface{}) (string, error)

func (SignMethodHMAC) Verify

func (m SignMethodHMAC) Verify(signingString string, signature string, key interface{}) error

type SignMethodRSA

type SignMethodRSA struct {
	Hash crypto.Hash
}

func (SignMethodRSA) Alg

func (m SignMethodRSA) Alg() crypto.Hash

func (SignMethodRSA) Sign

func (m SignMethodRSA) Sign(signinString string, key interface{}) (string, error)

func (SignMethodRSA) Verify

func (m SignMethodRSA) Verify(signingString string, signature string, key interface{}) error

type SignMethodRSAPSS

type SignMethodRSAPSS struct {
	Hash crypto.Hash
}

func (SignMethodRSAPSS) Alg

func (m SignMethodRSAPSS) Alg() crypto.Hash

func (SignMethodRSAPSS) Sign

func (m SignMethodRSAPSS) Sign(signinString string, key interface{}) (string, error)

func (SignMethodRSAPSS) Verify

func (m SignMethodRSAPSS) Verify(signingString string, signature string, key interface{}) error

type Token

type Token struct {
	Value         string
	Method        SignMethod
	Header        map[string]interface{}
	Payload       Claims
	Signature     string
	HeaderPayload string
}

func NewToken

func NewToken(id uint, claims Claims) *Token

func (*Token) Build

func (t *Token) Build() error

func (*Token) Parse

func (t *Token) Parse(tokenString string, validate bool) error

func (*Token) Sign

func (t *Token) Sign(key interface{}) error

func (*Token) Validate

func (t *Token) Validate() error

func (*Token) Verify

func (t *Token) Verify(key interface{}) error

type TokenError

type TokenError struct {
	Text  error
	Flags uint32
}

func (*TokenError) Error

func (e *TokenError) Error() string