jose

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package jose signs and verifies JSON Web Signatures (RFC 7515) in compact form, and converts public keys to and from JSON Web Keys (RFC 7517), for the asymmetric algorithms of RFC 7518 and RFC 8037. HMAC algorithms and "none" are refused: a provider never publishes the secret of an HMAC key, so a mock signing with one teaches clients to accept what no real provider sends. It is where vlatte's jwt and jwks template functions and its JWT matchers do their cryptography.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrUnsupportedAlg says an algorithm is not one the package signs or verifies with.
	ErrUnsupportedAlg = errors.New("jose: unsupported algorithm")
	// ErrKeyMismatch says a key is not of the type, size or curve its algorithm takes.
	ErrKeyMismatch = errors.New("jose: key does not fit the algorithm")
	// ErrSignature says a signature does not verify.
	ErrSignature = errors.New("jose: signature does not verify")
)
View Source
var (
	// ErrMalformed says a token is not a compact JWS whose payload is a JSON object.
	ErrMalformed = errors.New("jose: not a JWT")
	// ErrExpired says the exp claim of a token is past.
	ErrExpired = errors.New("jose: token expired")
	// ErrNotYetValid says the nbf claim of a token is future.
	ErrNotYetValid = errors.New("jose: token not yet valid")
)
View Source
var ErrUnknownKid = errors.New("jose: kid not in the key set")

ErrUnknownKid says no key of a key set has the kid of a token.

Functions

func Algorithms

func Algorithms() []string

Algorithms returns the names of the algorithms the package signs and verifies with, sorted.

func CheckAlg

func CheckAlg(alg string) error

CheckAlg returns an error wrapping ErrUnsupportedAlg unless the package signs and verifies with alg.

func CheckKey

func CheckKey(alg string, key crypto.Signer) error

CheckKey returns an error wrapping ErrUnsupportedAlg or ErrKeyMismatch unless key can sign with alg: an RSA key of 2048 bits or more for RS* and PS*, an ECDSA key on the algorithm's curve for ES*, an Ed25519 key for EdDSA.

func CheckPublicKey

func CheckPublicKey(alg string, pub crypto.PublicKey) error

CheckPublicKey is CheckKey for a public key.

func GenerateKey

func GenerateKey(alg string) (crypto.Signer, error)

GenerateKey returns a new key for alg: RSA keys are 2048 bits.

func ParsePrivateKey

func ParsePrivateKey(data []byte) (crypto.Signer, error)

ParsePrivateKey returns the private key of the first PEM block of data: PKCS #1 ("RSA PRIVATE KEY"), PKCS #8 ("PRIVATE KEY") or SEC 1 ("EC PRIVATE KEY"). Errors never hold key material.

func Sign

func Sign(alg, kid string, key crypto.Signer, payload []byte) (string, error)

Sign returns a compact JWS of payload, with the header {"alg":alg,"kid":kid,"typ":"JWT"}, signed with key. An empty kid is left out of the header. RS* signatures are deterministic: the same payload signs the same way.

Types

type JWK

type JWK struct {
	Kty string `json:"kty"`
	Use string `json:"use,omitempty"`
	Alg string `json:"alg,omitempty"`
	Kid string `json:"kid,omitempty"`
	Crv string `json:"crv,omitempty"`
	N   string `json:"n,omitempty"`
	E   string `json:"e,omitempty"`
	X   string `json:"x,omitempty"`
	Y   string `json:"y,omitempty"`
}

JWK is the public part of a key, as a JSON Web Key.

func PublicJWK

func PublicJWK(alg, kid string, pub crypto.PublicKey) (JWK, error)

PublicJWK returns the JWK of pub, the public key of a signing key: use "sig", with alg and kid.

type JWKSet

type JWKSet struct {
	Keys []JWK `json:"keys"`
}

JWKSet is a JSON Web Key Set.

type KeySet

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

KeySet is the public keys a token may be signed with.

func ParseKeySet

func ParseKeySet(text []byte) (*KeySet, error)

ParseKeySet reads the public keys of text: a JWK Set, a single JWK, or PEM blocks of public keys ("PUBLIC KEY", "RSA PUBLIC KEY") and certificates ("CERTIFICATE"). JWKs of a set whose use is "enc", or whose type or curve the package doesn't support, are skipped; a JWK of a supported type that can't be read is an error. A private key, PEM or JWK, is refused, so a mock file can't hold one by mistake. A set with no key is an error.

func (*KeySet) Verify

func (ks *KeySet) Verify(t *Token) error

Verify returns nil when a key of ks signed t. It takes only the algorithms of the package, so never "none" or an HMAC one. A key whose JWK names a kid is not used for a token that names another kid, and one whose JWK names an alg is used only for that alg, so a token can't pick how its key is read. A token without a kid is tried with every key. A token whose kid no key has fails with ErrUnknownKid unless ks has keys without a kid, such as PEM ones, which are tried in turn.

type Token

type Token struct {
	// Header is the decoded protected header.
	Header map[string]any
	// Claims is the decoded payload.
	Claims map[string]any
	// Alg is the alg of the header.
	Alg string
	// Kid is the kid of the header, or "" without one.
	Kid string
	// contains filtered or unexported fields
}

Token is a decoded compact JWS whose payload is a JSON object: a JWT. Decoding doesn't verify it.

func Parse

func Parse(token string) (*Token, error)

Parse decodes a compact JWS. It returns an error wrapping ErrMalformed for anything else, such as a JWE, or a header without alg.

func (*Token) CheckTime

func (t *Token) CheckTime(now time.Time) error

CheckTime returns ErrExpired when the exp claim of t is now or past, and ErrNotYetValid when its nbf claim is future, with no leeway. A token without them passes; one whose exp or nbf is not a number is malformed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL