xjwt

README

xjwt: small extensions for implementing JWT-based systems

Methods

JWT Verification

xjwt.Verify and xjwt.VerifyRaw are strict verifying methods for validating a JWT is valid and well formed.

Remote JWK Keysets

xkeyset.RemoteKeyset wraps a remote JWKs URL, caching and refreshing a list of JWKs in the background.

jose.v2 shortcuts

RandomNonce

xjwt.RandomNonce provides a basic, random value, conforming to the jose.NonceSource interface.

Converting PEM encoding to JOSE types

xjwt.ParsePrivateKey converts a private key from a PEM encoding to a *jose.JSONWebKey.

License

xjwt is licensed under the Apache License Version 2.0. See the LICENSE file for details.

Documentation

Index

• Variables
• func ParsePrivateKey(privateKey []byte, passphrase []byte) (*jose.JSONWebKey, jose.SignatureAlgorithm, error)
• func Verify(input []byte, vc VerifyConfig) (map[string]interface{}, error)
• func VerifyRaw(input []byte, vc VerifyConfig) ([]byte, error)
• type AuthzErrWithReason
• type RandomNonce
  • func (rn *RandomNonce) Nonce() (string, error)
• type VerifyConfig
• type VerifyErr
  • func NewVerifyErr(msg string, reason VerifyReasons) *VerifyErr
  • func (e *VerifyErr) Error() string
  • func (e *VerifyErr) XJWTVerifyReason() VerifyReasons
• type VerifyReasons

Variables

var ErrIncorrectPassword = x509.IncorrectPasswordError

ErrIncorrectPassword means when attempting to parse an encrypted PEM file, the password was likely incorrect

Functions

func ParsePrivateKey

func ParsePrivateKey(privateKey []byte, passphrase []byte) (*jose.JSONWebKey, jose.SignatureAlgorithm, error)

ParsePrivateKey converts a private key from a PEM encoding to a *jose.JSONWebKey.

Optionally, a passphrase for an encrypted X.509 document can be passed in. If the contents of the PEM is not encrypted, passphrase is ignored.

func Verify

func Verify(input []byte, vc VerifyConfig) (map[string]interface{}, error)

Verify verifies a JWT, and returns a map containing the payload claims

It is paranoid. It has default settings for "real world" JWT usage as an HTTP Header. It will reject potentially valid JWTs nd related specifications.

If an error is encountered, the error returned may implement the xjwt.AuthzErrWithReason interface. This interface can be used to find the reason a JWT did not validate, enumerated by the VerifyReasons type. This is because some errors (like an expired JWT), might be a good reason to refresh from a JWT source, but others like a parse error might be best handled as a hard error.

func VerifyRaw

func VerifyRaw(input []byte, vc VerifyConfig) ([]byte, error)

VerifyRaw verifies a JWT with the same constaints as xjwt.Verify, but returns the payload as a byte slice

Types

type AuthzErrWithReason

type AuthzErrWithReason interface {
	XJWTVerifyReason() VerifyReasons
}

AuthzErrWithReason is used to extract additional reasons a verification failed from an error interface.

type RandomNonce

type RandomNonce struct {
	Size int
}

RandomNonce provides a basic, random value, conforming to the jose.NonceSource interface.

func (*RandomNonce) Nonce

func (rn *RandomNonce) Nonce() (string, error)

Nonce returns a random string or an error

type VerifyConfig

type VerifyConfig struct {
	// ExpectedIssuer validates the iss claim of a JWT matches this value
	ExpectedIssuer string
	// ExpectedSubject validates the sub claim of a JWT matches this value
	ExpectedSubject string
	// ExpectedAudience validates that the aud claim of a JWT contains this value
	ExpectedAudience string
	// ExpectedNonce validates that the nonce claim of a JWT matches this value
	ExpectedNonce string
	// Now is a callback to the current time, if not provided time.Now is used
	Now func() time.Time
	// MaxExpirationFromNow is how far into the future to allow a JWT to be valid for.
	// This can be used to mitigate against some types of  "golden ticket attacks".
	MaxExpirationFromNow time.Duration
	// KeySet is a set of JWKs that are trusted by the verifier, and used to validate the JWT.
	KeySet *jose.JSONWebKeySet
}

VerifyConfig expreses the possible options for validating a JWT

type VerifyErr

type VerifyErr struct {
	// contains filtered or unexported fields
}

VerifyErr repersents an error from Verify meets the error and AuthzErrWithReason interfaces.

func NewVerifyErr

func NewVerifyErr(msg string, reason VerifyReasons) *VerifyErr

NewVerifyErr creates a new VerifyErr

func (*VerifyErr) Error

func (e *VerifyErr) Error() string

Error returns a human readable description of an error

func (*VerifyErr) XJWTVerifyReason

func (e *VerifyErr) XJWTVerifyReason() VerifyReasons

XJWTVerifyReason returns the reason verification failed

type VerifyReasons

type VerifyReasons int32

VerifyReasons expresses why a JWT was not valid.

const (
	// JWT_UNKNOWN means the JWT could not be verified for unknown reasons.
	JWT_UNKNOWN VerifyReasons = 0
	// JWT_NOT_PRESENT means the JWT was empty or otherwise not present.
	JWT_NOT_PRESENT VerifyReasons = 1
	// JWT_EXPIRED means the JWT has expired, and a refresh might be needed.
	JWT_EXPIRED VerifyReasons = 2
	// JWT_INVALID_SIGNATURE means the JWT's signature is invalid.
	JWT_INVALID_SIGNATURE VerifyReasons = 3
	// JWT_NO_VALIDATORS means no matching JWK could be found to validate the JWT.
	// This could be caused by JWKs expiring or not being rotated correctly.
	JWT_NO_VALIDATORS VerifyReasons = 4
	// JWT_MALFORMED means the JWT contained unexpected fields or data.
	JWT_MALFORMED VerifyReasons = 5
	// JWT_EXPECT_MISMATCH means the JWT did not contain the expected claims, such as Audience or Subject.
	JWT_EXPECT_MISMATCH VerifyReasons = 6
)