jws

Documentation

Overview

Package jws contains a partial implementation of the JWS Standard (RFC7515). The package contains functionality for decoding and encoding JWS from/into the JWS Compact Serialization, functionality for dealing with JOSE Headers and implementations of select JWS signing algorithms.

This is a very low-level implementation of JWS that remains agnostic of concrete use cases such as JWT. If you need to handle authentication tokens in common use cases, the KISStokens/opinionated package might be a better fit. If you do have special requirements exceeding the capabilities of KISStokens/opinionated, you can use the KISStokens/jwt package to deal with JSON Web Token payloads more easily.

Index

• Variables
• func BuildSigningInput(joseHeader, payload []byte) string
• func VerifyHS256(jws *CompactJWS, secret []byte) error
• type CompactJWS
  • func ParseCompactJWSString(s string) (*CompactJWS, error)
  • func SignHS256(joseHeader, payload, secret []byte) (*CompactJWS, error)
  • func (j *CompactJWS) SigningInput() string
  • func (j *CompactJWS) String() string
• type JOSEHeader
  • func ParseJOSEHeader(input []byte) (*JOSEHeader, error)
  • func (c *JOSEHeader) Serialize() ([]byte, error)
• type StandardParameters

Variables

var (
	ErrAlgorithmParameterMissing  = errors.New("the JOSE Header is missing the `alg` (Algorithm) parameter")
	ErrJOSEHeaderMustBeJSONObject = errors.New("the encoded JOSE Header must be a JSON Object")
	ErrMarshallingFailed          = errors.New("could not marshal JOSE Header to JSON")
	ErrParameterNameCollision     = errors.New("the name of a custom parameter collides with the name of a standard parameter")
)

var (
	ErrMalformedJWSString       = errors.New("encountered a malformed JWS string representation")
	ErrSignatureMismatch        = errors.New("encountered a JWS with a signature that did not match its contents")
	ErrUnsupportedAlgorithm     = errors.New("encountered a token with an unsupported signing algorithm specified in its JOSE Header")
	ErrUnsupportedCritParameter = errors.New("encountered a 'crit' parameter that is not supported")
)

Functions

func BuildSigningInput

func BuildSigningInput(joseHeader, payload []byte) string

BuildSigningInput builds the JWS Signing Input, as defined in RFC7515 for the given JOSE Header and payload

func VerifyHS256

func VerifyHS256(jws *CompactJWS, secret []byte) error

VerifyHS256 verifies the given JWS with HMAC-SHA256 using the given secret key Note that this only verifies the signature, not the validity of enclosed claims (if any)

Types

type CompactJWS

type CompactJWS struct {
	JOSEHeader []byte
	Payload    []byte
	Signature  []byte
}

CompactJWS represents the parts of a JWS Compact Serialization as defined in RFC7515

func ParseCompactJWSString

func ParseCompactJWSString(s string) (*CompactJWS, error)

ParseCompactJWSString parses a JWS Compact Serialization string as defined in RFC7515 into its parts *without* verifying the signature or the JOSEHeader. Note that it is in the responsibility of the caller to to check, whether the application supports the JOSE Header fields specified in the "crit" property (if any).

func SignHS256

func SignHS256(joseHeader, payload, secret []byte) (*CompactJWS, error)

SignHS256 signs the given JOSE Header and payload with HMAC-SHA256 using the given secret key. Note that this function does *not* validate the given JOSE Header!

func (*CompactJWS) SigningInput

func (j *CompactJWS) SigningInput() string

SigningInput is a wrapper of BuildSigningInput for the given CompactJWS

func (*CompactJWS) String

func (j *CompactJWS) String() string

String produces the JWS Compact Serialization string, as defined in RFC7515

type JOSEHeader

type JOSEHeader struct {
	StandardParameters
	CustomParameters map[string]interface{}
}

JOSEHeader represents the contents of a JOSE Header as defined in RFC7515.

func ParseJOSEHeader

func ParseJOSEHeader(input []byte) (*JOSEHeader, error)

ParseJOSEHeader parses a JOSE Header from the given JSON input

func (*JOSEHeader) Serialize

func (c *JOSEHeader) Serialize() ([]byte, error)

Serialize serializes the JOSE header to JSON It will not accept JOSE headers that have a custom parameters with the same key as a standard parameter.

type StandardParameters

type StandardParameters struct {
	Algorithm                       *string
	JWKSetURL                       *string
	JSONWebKey                      map[string]interface{}
	KeyID                           *string
	X509URL                         *string
	X509CertificateChain            []string
	X509CertificateSHA1Thumbprint   *string
	X509CertificateSHA256Thumbprint *string
	Type                            *string
	ContentType                     *string
	Critical                        []string
}

StandardParameters represents the registered JWS header parameters as defined in RFC7515. When parsing, parameters that were not present are set to nil.