jws

Documentation

Overview

Package jws implements JWSs per RFC 7515

Index

• Constants
• Variables
• func GetSigningMethod(alg string) crypto.SigningMethod
• func NewJWT(claims Claims, method crypto.SigningMethod) jwt.JWT
• func ParseJWT(encoded []byte) (jwt.JWT, error)
• func RegisterSigningMethod(sm crypto.SigningMethod)
• func RemoveSigningMethod(sm crypto.SigningMethod)
• type Claims
• type JWS
  • func New(content interface{}, methods ...crypto.SigningMethod) *JWS
  • func Parse(encoded []byte, u ...json.Unmarshaler) (*JWS, error)
  • func ParseCompact(encoded []byte, u ...json.Unmarshaler) (*JWS, error)
  • func ParseFlat(encoded []byte, u ...json.Unmarshaler) (*JWS, error)
  • func ParseGeneral(encoded []byte, u ...json.Unmarshaler) (*JWS, error)
  • func (j *JWS) Claims() jwt.Claims
  • func (j *JWS) Compact(key interface{}) ([]byte, error)
  • func (j *JWS) Flat(key interface{}) ([]byte, error)
  • func (j *JWS) General(keys ...interface{}) ([]byte, error)
  • func (j *JWS) GetProtected(key string, i ...int) interface{}
  • func (j *JWS) GetUnprotected(key string, i ...int) interface{}
  • func (j *JWS) IsJWT() bool
  • func (j *JWS) Payload() interface{}
  • func (j *JWS) RemoveProtected(key string, i ...int)
  • func (j *JWS) RemoveUnprotected(key string, i ...int)
  • func (j *JWS) Serialize(key interface{}) ([]byte, error)
  • func (j *JWS) SetPayload(val interface{})
  • func (j *JWS) SetProtected(key string, val interface{}, i ...int)
  • func (j *JWS) SetUnprotected(key string, val interface{}, i ...int)
  • func (j *JWS) Validate(key interface{}, method crypto.SigningMethod) error
  • func (j *JWS) ValidateMulti(keys []interface{}, methods []crypto.SigningMethod, idx ...int) error
  • func (j *JWS) Verify(key interface{}, m crypto.SigningMethod, o ...jwt.Opts) error
• type Opts
  • func (o Opts) C() jwt.Opts
  • func (o Opts) Convert() jwt.Opts

Constants

const Any int = -1

Any means any of the JWS signatures need to validate. Refer to ValidateMulti for more information.

Variables

var (

	// ErrNotEnoughMethods is returned if New was called _or_ the Flat/Compact
	// methods were called with 0 SigningMethods.
	ErrNotEnoughMethods = errors.New("not enough methods provided")

	// ErrCouldNotUnmarshal is returned when Parse's json.Unmarshaler
	// parameter returns an error.
	ErrCouldNotUnmarshal = errors.New("custom unmarshal failed")

	// ErrNotCompact signals that the provided potential JWS is not
	// in its compact representation.
	ErrNotCompact = errors.New("not a compact JWS")

	// ErrDuplicateHeaderParameter signals that there are duplicate parameters
	// in the provided Headers.
	ErrDuplicateHeaderParameter = errors.New("duplicate parameters in the JOSE Header")

	// ErrTwoEmptyHeaders is returned if both Headers are empty.
	ErrTwoEmptyHeaders = errors.New("both headers cannot be empty")

	// ErrNotEnoughKeys is returned when not enough keys are provided for
	// the given SigningMethods.
	ErrNotEnoughKeys = errors.New("not enough keys (for given methods)")

	// ErrDidNotValidate means the given JWT did not properly validate
	ErrDidNotValidate = errors.New("did not validate")

	// ErrNoAlgorithm means no algorithm ("alg") was found in the Protected
	// Header.
	ErrNoAlgorithm = errors.New("no algorithm found")

	// ErrAlgorithmDoesntExist means the algorithm asked for cannot be
	// found inside the signingMethod cache.
	ErrAlgorithmDoesntExist = errors.New("algorithm doesn't exist")

	// ErrMismatchedAlgorithms means the algorithm inside the JWT was
	// different than the algorithm the caller wanted to use.
	ErrMismatchedAlgorithms = errors.New("mismatched algorithms")

	// ErrCannotValidate means the JWS cannot be validated for various
	// reasons. For example, if there aren't any signatures/payloads/headers
	// to actually validate.
	ErrCannotValidate = errors.New("cannot validate")

	// ErrIsNotJWT means the given JWS is not a JWT.
	ErrIsNotJWT = errors.New("JWS is not a JWT")

	// ErrHoldsJWE means the given JWS holds a JWE inside its payload.
	ErrHoldsJWE = errors.New("JWS holds JWE")
)

var IgnoreDupes bool

IgnoreDupes should be set to true if the internal duplicate header key check should ignore duplicate Header keys instead of reporting an error when duplicate Header keys are found.

Note: Duplicate Header keys are defined in https://tools.ietf.org/html/rfc7515#section-5.2 meaning keys that both the protected and unprotected Headers possess.

Functions

func GetSigningMethod

func GetSigningMethod(alg string) crypto.SigningMethod

GetSigningMethod retrieves a crypto.SigningMethod from the global map.

func NewJWT

func NewJWT(claims Claims, method crypto.SigningMethod) jwt.JWT

NewJWT creates a new JWT with the given claims.

func ParseJWT

func ParseJWT(encoded []byte) (jwt.JWT, error)

ParseJWT parses a serialized jwt.JWT into a physical jwt.JWT. If its payload isn't a set of claims (or able to be coerced into a set of claims) it'll return an error stating the JWT isn't a JWT.

func RegisterSigningMethod

func RegisterSigningMethod(sm crypto.SigningMethod)

RegisterSigningMethod registers the crypto.SigningMethod in the global map. This is typically done inside the caller's init function.

func RemoveSigningMethod

func RemoveSigningMethod(sm crypto.SigningMethod)

RemoveSigningMethod removes the crypto.SigningMethod from the global map.

Types

type Claims

type Claims jwt.Claims

Claims represents a set of JOSE Claims.

type JWS

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

JWS represents a specific JWS.

func New

func New(content interface{}, methods ...crypto.SigningMethod) *JWS

New creates a new JWS with the provided crypto.SigningMethods.

func Parse

func Parse(encoded []byte, u ...json.Unmarshaler) (*JWS, error)

Parse parses any of the three serialized JWS forms into a physical JWS per https://tools.ietf.org/html/rfc7515#section-5.2

It accepts a json.Unmarshaler in order to properly parse the payload. In order to keep the caller from having to do extra parsing of the payload, a json.Unmarshaler can be passed which will be then to unmarshal the payload however the caller wishes. Do note that if json.Unmarshal returns an error the original payload will be used as if no json.Unmarshaler was passed.

Internally, Parse applies some heuristics and then calls either ParseGeneral, ParseFlat, or ParseCompact. It should only be called if, for whatever reason, you do not know which form the serialized JWT is in.

func ParseCompact

func ParseCompact(encoded []byte, u ...json.Unmarshaler) (*JWS, error)

ParseCompact parses a JWS serialized into its "compact" form per https://tools.ietf.org/html/rfc7515#section-7.1 into a physical JWS per https://tools.ietf.org/html/rfc7515#section-5.2

For information on the json.Unmarshaler parameter, see Parse.

func ParseFlat

func ParseFlat(encoded []byte, u ...json.Unmarshaler) (*JWS, error)

ParseFlat parses a JWS serialized into its "flat" form per https://tools.ietf.org/html/rfc7515#section-7.2.2 into a physical JWS per https://tools.ietf.org/html/rfc7515#section-5.2

For information on the json.Unmarshaler parameter, see Parse.

func ParseGeneral

func ParseGeneral(encoded []byte, u ...json.Unmarshaler) (*JWS, error)

ParseGeneral parses a JWS serialized into its "general" form per https://tools.ietf.org/html/rfc7515#section-7.2.1 into a physical JWS per https://tools.ietf.org/html/rfc7515#section-5.2

For information on the json.Unmarshaler parameter, see Parse.

func (*JWS) Claims

func (j *JWS) Claims() jwt.Claims

Claims helps implements jwt.JWT.

func (*JWS) Compact

func (j *JWS) Compact(key interface{}) ([]byte, error)

Compact serializes the JWS into its "compact" form per https://tools.ietf.org/html/rfc7515#section-7.1

func (*JWS) Flat

func (j *JWS) Flat(key interface{}) ([]byte, error)

Flat serializes the JWS to its "flattened" form per https://tools.ietf.org/html/rfc7515#section-7.2.2

func (*JWS) General

func (j *JWS) General(keys ...interface{}) ([]byte, error)

General serializes the JWS into its "general" form per https://tools.ietf.org/html/rfc7515#section-7.2.1

If only one key is passed it's used for all the provided crypto.SigningMethods. Otherwise, len(keys) must equal the number of crypto.SigningMethods added.

func (*JWS) GetProtected

func (j *JWS) GetProtected(key string, i ...int) interface{}

GetProtected retrieves the value inside the protected Header that corresponds with the given key. For information on parameter i, see SetProtected.

func (*JWS) GetUnprotected

func (j *JWS) GetUnprotected(key string, i ...int) interface{}

GetUnprotected retrieves the value inside the protected Header that corresponds with the given key. For information on parameter i, see SetUnprotected.

func (*JWS) IsJWT

func (j *JWS) IsJWT() bool

IsJWT returns true if the JWS is a JWT.

func (*JWS) Payload

func (j *JWS) Payload() interface{}

Payload returns the JWS' payload.

func (*JWS) RemoveProtected

func (j *JWS) RemoveProtected(key string, i ...int)

RemoveProtected removes the value inside the protected Header that corresponds with the given key. For information on parameter i, see SetProtected.

func (*JWS) RemoveUnprotected

func (j *JWS) RemoveUnprotected(key string, i ...int)

RemoveUnprotected removes the value inside the unprotected Header that corresponds with the given key. For information on parameter i, see SetUnprotected.

func (*JWS) Serialize

func (j *JWS) Serialize(key interface{}) ([]byte, error)

Serialize helps implements jwt.JWT.

func (*JWS) SetPayload

func (j *JWS) SetPayload(val interface{})

SetPayload sets the JWS' raw, unexported payload.

func (*JWS) SetProtected

func (j *JWS) SetProtected(key string, val interface{}, i ...int)

SetProtected sets the protected Header with the given value. If i is provided, it'll assume the JWS is in the "general" format, and set the Header at index i (inside the signatures member) with the given value.

func (*JWS) SetUnprotected

func (j *JWS) SetUnprotected(key string, val interface{}, i ...int)

SetUnprotected sets the protected Header with the given value. If i is provided, it'll assume the JWS is in the "general" format, and set the Header at index i (inside the signatures member) with the given value.

func (*JWS) Validate

func (j *JWS) Validate(key interface{}, method crypto.SigningMethod) error

Validate validates the current JWS as-is. Refer to ValidateMulti for more information.

func (*JWS) ValidateMulti

func (j *JWS) ValidateMulti(keys []interface{}, methods []crypto.SigningMethod, idx ...int) error

ValidateMulti validates the current JWS as-is. Since it's meant to be called after parsing a stream of bytes into a JWS, it doesn't do any internal parsing like the Sign, Flat, Compact, or General methods do. idx represents which signatures need to validate in order for the JWS to be considered valid. Use the constant `Any` (-1) if *any* should validate the JWS. Otherwise, use the indexes of the signatures that need to validate in order for the JWS to be considered valid.

Notes:

1.) If idx is omitted it defaults to requiring *all*
    signatures validate
2.) The JWS spec requires *at least* one
    signature to validate in order for the JWS to be considered valid.

func (*JWS) Verify

func (j *JWS) Verify(key interface{}, m crypto.SigningMethod, o ...jwt.Opts) error

Verify helps implement jwt.JWT.

type Opts

type Opts struct {
	EXP int64 // EXPLeeway
	NBF int64 // NBFLeeway
	Fn  func(Claims) error
	// contains filtered or unexported fields
}

Opts represents some of the validation options. It mimics jwt.Opts.

func (Opts) C

func (o Opts) C() jwt.Opts

C is shorthand for Convert(fn).

func (Opts) Convert

func (o Opts) Convert() jwt.Opts

Convert converts Opts into jwt.Opts.