jwkset

package module
v0.5.20 Latest Latest
Warning

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

 Go to latest Published: Sep 18, 2024 License: Apache-2.0 Imports: 26 Imported by: 24

README

Go Reference

JWK Set (JSON Web Key Set)

This is a JWK Set (JSON Web Key Set) implementation written in Golang.

The goal of this project is to provide a complete implementation of JWK and JWK Sets within the constraints of the Golang standard library, without implementing any cryptographic algorithms. For example, Ed25519 is supported, but Ed448 is not, because the Go standard library does not have a high level implementation of Ed448.

If you would like to generate or validate a JWK without writing any Golang code, please visit the Generate a JWK Set section.

If you would like to have a JWK Set client to help verify JWTs without writing any Golang code, you can use the JWK Set Client Proxy (JCP) project perform JWK Set client operations in the language of your choice using an OpenAPI interface.

Generate a JWK Set

If you would like to generate a JWK Set without writing Golang code, this project publishes utilities to generate a JWK Set from:

  • PEM encoded X.509 Certificates
  • PEM encoded public keys
  • PEM encoded private keys

The PEM block type is used to infer which key type to decode. Reference the Supported keys section for a list of supported cryptographic key types.

Website

Visit https://jwkset.com to use the web interface for this project. You can self-host this website by following the instructions in the README.md in the website directory.

Command line

Gather your PEM encoded keys or certificates and use the cmd/jwksetinfer command line tool to generate a JWK Set.

Install

go install github.com/MicahParks/jwkset/cmd/jwksetinfer@latest

Usage

jwksetinfer mykey.pem mycert.crt

Custom server

This project can be used in creating a custom JWK Set server. A good place to start is examples/http_server/main.go.

Golang JWK Set client

If you are using github.com/golang-jwt/jwt/v5 take a look at github.com/MicahParks/keyfunc/v3.

This project can be used to create JWK Set clients. An HTTP client is provided. See a snippet of the usage from examples/default_http_client/main.go below.

Create a JWK Set client from the server's HTTP URL.

jwks, err := jwkset.NewDefaultHTTPClient([]string{server.URL})
if err != nil {
	log.Fatalf("Failed to create client JWK set. Error: %s", err)
}

Read a key from the client.

jwk, err = jwks.KeyRead(ctx, myKeyID)
if err != nil {
	log.Fatalf("Failed to read key from client JWK set. Error: %s", err)
}

Supported keys

This project supports the following key types:

Cryptographic keys can be added, deleted, and read from the JWK Set. A JSON representation of the JWK Set can be created for hosting via HTTPS. This project includes an in-memory storage implementation, but an interface is provided for more advanced use cases.

Notes

This project aims to implement the relevant RFCs to the fullest extent possible using the Go standard library, but does not implement any cryptographic algorithms itself.

  • RFC 8037 adds support for Ed448, X448, and secp256k1, but there is no Golang standard library support for these key types.
  • In order to be compatible with non-RFC compliant JWK Set providers, this project does not strictly enforce JWK parameters that are integers and have extra or missing leading padding. See the release notes of v0.5.15 for details.
  • Base64url Encoding requires that all trailing = characters be removed. This project automatically strips any trailing = characters in an attempt to be compatible with improper implementations of JWK.
  • This project does not currently support JWK Set encryption using JWE. This would involve implementing the relevant JWE specifications. It may be implemented in the future if there is interest. Open a GitHub issue to express interest.

github.com/MicahParks/keyfunc

A JWK Set client for the github.com/golang-jwt/jwt/v5 project.

github.com/MicahParks/jcp

A JWK Set client proxy. JCP for short. This project is a standalone service that uses keyfunc under the hood. It primarily exists for these use cases:

The language or shell a program is written in does not have an adequate JWK Set client. Validate JWTs with curl? Why not? Restrictive networking policies prevent a program from accessing the remote JWK Set directly. Many co-located services need to validate JWTs that were signed by a key that lives in a remote JWK Set. If you can integrate keyfunc directly into your program, you likely don't need JCP.

Documentation

Index

Constants

View Source 
const (
	AlgHS256            ALG = "HS256"
	AlgHS384            ALG = "HS384"
	AlgHS512            ALG = "HS512"
	AlgRS256            ALG = "RS256"
	AlgRS384            ALG = "RS384"
	AlgRS512            ALG = "RS512"
	AlgES256            ALG = "ES256"
	AlgES384            ALG = "ES384"
	AlgES512            ALG = "ES512"
	AlgPS256            ALG = "PS256"
	AlgPS384            ALG = "PS384"
	AlgPS512            ALG = "PS512"
	AlgNone             ALG = "none"
	AlgRSA1_5           ALG = "RSA1_5"
	AlgRSAOAEP          ALG = "RSA-OAEP"
	AlgRSAOAEP256       ALG = "RSA-OAEP-256"
	AlgA128KW           ALG = "A128KW"
	AlgA192KW           ALG = "A192KW"
	AlgA256KW           ALG = "A256KW"
	AlgDir              ALG = "dir"
	AlgECDHES           ALG = "ECDH-ES"
	AlgECDHESA128KW     ALG = "ECDH-ES+A128KW"
	AlgECDHESA192KW     ALG = "ECDH-ES+A192KW"
	AlgECDHESA256KW     ALG = "ECDH-ES+A256KW"
	AlgA128GCMKW        ALG = "A128GCMKW"
	AlgA192GCMKW        ALG = "A192GCMKW"
	AlgA256GCMKW        ALG = "A256GCMKW"
	AlgPBES2HS256A128KW ALG = "PBES2-HS256+A128KW"
	AlgPBES2HS384A192KW ALG = "PBES2-HS384+A192KW"
	AlgPBES2HS512A256KW ALG = "PBES2-HS512+A256KW"
	AlgA128CBCHS256     ALG = "A128CBC-HS256"
	AlgA192CBCHS384     ALG = "A192CBC-HS384"
	AlgA256CBCHS512     ALG = "A256CBC-HS512"
	AlgA128GCM          ALG = "A128GCM"
	AlgA192GCM          ALG = "A192GCM"
	AlgA256GCM          ALG = "A256GCM"
	AlgEdDSA            ALG = "EdDSA"
	AlgRS1              ALG = "RS1" // Prohibited.
	AlgRSAOAEP384       ALG = "RSA-OAEP-384"
	AlgRSAOAEP512       ALG = "RSA-OAEP-512"
	AlgA128CBC          ALG = "A128CBC" // Prohibited.
	AlgA192CBC          ALG = "A192CBC" // Prohibited.
	AlgA256CBC          ALG = "A256CBC" // Prohibited.
	AlgA128CTR          ALG = "A128CTR" // Prohibited.
	AlgA192CTR          ALG = "A192CTR" // Prohibited.
	AlgA256CTR          ALG = "A256CTR" // Prohibited.
	AlgHS1              ALG = "HS1"     // Prohibited.
	AlgES256K           ALG = "ES256K"

	CrvP256      CRV = "P-256"
	CrvP384      CRV = "P-384"
	CrvP521      CRV = "P-521"
	CrvEd25519   CRV = "Ed25519"
	CrvEd448     CRV = "Ed448"
	CrvX25519    CRV = "X25519"
	CrvX448      CRV = "X448"
	CrvSECP256K1 CRV = "secp256k1"

	KeyOpsSign       KEYOPS = "sign"
	KeyOpsVerify     KEYOPS = "verify"
	KeyOpsEncrypt    KEYOPS = "encrypt"
	KeyOpsDecrypt    KEYOPS = "decrypt"
	KeyOpsWrapKey    KEYOPS = "wrapKey"
	KeyOpsUnwrapKey  KEYOPS = "unwrapKey"
	KeyOpsDeriveKey  KEYOPS = "deriveKey"
	KeyOpsDeriveBits KEYOPS = "deriveBits"

	KtyEC  KTY = "EC"
	KtyOKP KTY = "OKP"
	KtyRSA KTY = "RSA"
	KtyOct KTY = "oct"

	UseEnc USE = "enc"
	UseSig USE = "sig"
)

These are string constants set in https://www.iana.org/assignments/jose/jose.xhtml See their respective types for more information.

View Source 
const (
	// HeaderKID is a JWT header for the key ID.
	HeaderKID = "kid"
)

Variables

View Source 
var (
	// ErrGetX5U indicates there was an error getting the X5U remote resource.
	ErrGetX5U = errors.New("failed to get X5U via given URI")
	// ErrJWKValidation indicates that a JWK failed to validate.
	ErrJWKValidation = errors.New("failed to validate JWK")
	// ErrKeyUnmarshalParameter indicates that a JWK's attributes are invalid and cannot be unmarshaled.
	ErrKeyUnmarshalParameter = errors.New("unable to unmarshal JWK due to invalid attributes")
	// ErrOptions indicates that the given options caused an error.
	ErrOptions = errors.New("the given options caused an error")
	// ErrUnsupportedKey indicates a key is not supported.
	ErrUnsupportedKey = errors.New("unsupported key")
	// ErrX509Mismatch indicates that the X.509 certificate does not match the key.
	ErrX509Mismatch = errors.New("the X.509 certificate does not match Golang key type")
)
View Source 
var (
	// ErrKeyNotFound is returned by a Storage implementation when a key is not found.
	ErrKeyNotFound = errors.New("key not found")
	// ErrInvalidHTTPStatusCode is returned when the HTTP status code is invalid.
	ErrInvalidHTTPStatusCode = errors.New("invalid HTTP status code")
)
View Source 
var (
	// ErrNewClient fails to create a new JWK Set client.
	ErrNewClient = errors.New("failed to create new JWK Set client")
)
View Source 
var (
	// ErrPadding indicates that there is invalid padding.
	ErrPadding = errors.New("padding error")
)
View Source 
var (
	// ErrX509Infer is returned when the key type cannot be inferred from the PEM block type.
	ErrX509Infer = errors.New("failed to infer X509 key type")
)

Functions

func DefaultGetX5U added in v0.4.0 

func DefaultGetX5U(u *url.URL) ([]*x509.Certificate, error)

DefaultGetX5U is the default implementation of the GetX5U field for JWKValidateOptions.

func LoadCertificate added in v0.4.0 

func LoadCertificate(pemBlock []byte) (*x509.Certificate, error)

LoadCertificate loads an X509 certificate from a PEM block.

func LoadCertificates added in v0.4.0 

func LoadCertificates(rawPEM []byte) ([]*x509.Certificate, error)

LoadCertificates loads X509 certificates from raw PEM data. It can be useful in loading X5U remote resources.

func LoadX509KeyInfer added in v0.4.0 

func LoadX509KeyInfer(pemBlock *pem.Block) (key any, err error)

LoadX509KeyInfer loads an X509 key from a PEM block.

Types

type ALG added in v0.1.0 

type ALG string

ALG is a set of "JSON Web Signature and Encryption Algorithms" types from https://www.iana.org/assignments/jose/jose.xhtml as defined in https://www.rfc-editor.org/rfc/rfc7518#section-7.1

func (ALG) IANARegistered added in v0.4.0 

func (alg ALG) IANARegistered() bool

func (ALG) String added in v0.2.1 

func (alg ALG) String() string

type CRV added in v0.1.0 

type CRV string

CRV is a set of "JSON Web Key Elliptic Curve" types from https://www.iana.org/assignments/jose/jose.xhtml as mentioned in https://www.rfc-editor.org/rfc/rfc7518.html#section-6.2.1.1

func (CRV) IANARegistered added in v0.4.0 

func (crv CRV) IANARegistered() bool

func (CRV) String added in v0.1.0 

func (crv CRV) String() string

type HTTPClientOptions added in v0.5.0 

type HTTPClientOptions struct {
	// Given contains keys known from outside HTTP URLs.
	Given Storage
	// HTTPURLs are a mapping of HTTP URLs to JWK Set endpoints to storage implementations for the keys located at the
	// URL. If empty, HTTP will not be used.
	HTTPURLs map[string]Storage
	// PrioritizeHTTP is a flag that indicates whether keys from the HTTP URL should be prioritized over keys from the
	// given storage.
	PrioritizeHTTP bool
	// RateLimitWaitMax is the timeout for waiting for rate limiting to end.
	RateLimitWaitMax time.Duration
	// RefreshUnknownKID is non-nil to indicate that remote HTTP resources should be refreshed if a key with an unknown
	// key ID is trying to be read. This makes reading methods block until the context is over, a key with the matching
	// key ID is found in a refreshed remote resource, or all refreshes complete.
	RefreshUnknownKID *rate.Limiter
}

HTTPClientOptions are options for creating a new JWK Set client.

type HTTPClientStorageOptions added in v0.5.0 

type HTTPClientStorageOptions struct {
	// Client is the HTTP client to use for requests.
	//
	// This defaults to http.DefaultClient.
	Client *http.Client

	// Ctx is used when performing HTTP requests. It is also used to end the refresh goroutine when it's no longer
	// needed.
	//
	// This defaults to context.Background().
	Ctx context.Context

	// HTTPExpectedStatus is the expected HTTP status code for the HTTP request.
	//
	// This defaults to http.StatusOK.
	HTTPExpectedStatus int

	// HTTPMethod is the HTTP method to use for the HTTP request.
	//
	// This defaults to http.MethodGet.
	HTTPMethod string

	// HTTPTimeout is the timeout for the HTTP request. When the Ctx option is also provided, this value is used for a
	// child context.
	//
	// This defaults to time.Minute.
	HTTPTimeout time.Duration

	// NoErrorReturnFirstHTTPReq will create the Storage without error if the first HTTP request fails.
	NoErrorReturnFirstHTTPReq bool

	// RefreshErrorHandler is a function that consumes errors that happen during an HTTP refresh. This is only effectual
	// if RefreshInterval is set.
	//
	// If NoErrorReturnFirstHTTPReq is set, this function will be called when if the first HTTP request fails.
	RefreshErrorHandler func(ctx context.Context, err error)

	// RefreshInterval is the interval at which the HTTP URL is refreshed and the JWK Set is processed. This option will
	// launch a "refresh goroutine" to refresh the remote HTTP resource at the given interval.
	//
	// Provide the Ctx option to end the goroutine when it's no longer needed.
	RefreshInterval time.Duration

	// Storage is the underlying storage implementation to use.
	//
	// This defaults to NewMemoryStorage().
	Storage Storage

	// ValidateOptions are the options to use when validating the JWKs.
	ValidateOptions JWKValidateOptions
}

HTTPClientStorageOptions are used to configure the behavior of NewStorageFromHTTP.

type JWK added in v0.4.0 

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

JWK represents a JSON Web Key.

func NewJWKFromKey added in v0.4.0 

func NewJWKFromKey(key any, options JWKOptions) (JWK, error)

NewJWKFromKey uses the given key and options to create a JWK. It is possible to provide a private key with an X.509 certificate, which will be validated to contain the correct public key.

func NewJWKFromMarshal added in v0.4.0 

func NewJWKFromMarshal(marshal JWKMarshal, marshalOptions JWKMarshalOptions, validateOptions JWKValidateOptions) (JWK, error)

NewJWKFromMarshal transforms a JWKMarshal into a JWK.

func NewJWKFromRawJSON added in v0.4.0 

func NewJWKFromRawJSON(j json.RawMessage, marshalOptions JWKMarshalOptions, validateOptions JWKValidateOptions) (JWK, error)

NewJWKFromRawJSON uses the given raw JSON to create a JWK.

func NewJWKFromX5C added in v0.4.0 

func NewJWKFromX5C(options JWKOptions) (JWK, error)

NewJWKFromX5C uses the X.509 X5C information in the options to create a JWK.

func NewJWKFromX5U added in v0.4.0 

func NewJWKFromX5U(options JWKOptions) (JWK, error)

NewJWKFromX5U uses the X.509 X5U information in the options to create a JWK.

func (JWK) Key added in v0.4.0 

func (j JWK) Key() any

Key returns the public or private cryptographic key associated with the JWK.

func (JWK) Marshal added in v0.4.0 

func (j JWK) Marshal() JWKMarshal

Marshal returns Go type that can be marshalled into JSON.

func (JWK) Validate added in v0.4.0 

func (j JWK) Validate() error

Validate validates the JWK. The JWK is automatically validated when created from a function in this package.

func (JWK) X509 added in v0.4.0 

func (j JWK) X509() JWKX509Options

X509 returns the X.509 certificate information for the JWK.

type JWKMarshal added in v0.1.0 

type JWKMarshal struct {
	KTY     KTY           `json:"kty,omitempty"`      // https://www.rfc-editor.org/rfc/rfc7517#section-4.1
	USE     USE           `json:"use,omitempty"`      // https://www.rfc-editor.org/rfc/rfc7517#section-4.2
	KEYOPS  []KEYOPS      `json:"key_ops,omitempty"`  // https://www.rfc-editor.org/rfc/rfc7517#section-4.3
	ALG     ALG           `json:"alg,omitempty"`      // https://www.rfc-editor.org/rfc/rfc7517#section-4.4 and https://www.rfc-editor.org/rfc/rfc7518#section-4.1
	KID     string        `json:"kid,omitempty"`      // https://www.rfc-editor.org/rfc/rfc7517#section-4.5
	X5U     string        `json:"x5u,omitempty"`      // https://www.rfc-editor.org/rfc/rfc7517#section-4.6
	X5C     []string      `json:"x5c,omitempty"`      // https://www.rfc-editor.org/rfc/rfc7517#section-4.7
	X5T     string        `json:"x5t,omitempty"`      // https://www.rfc-editor.org/rfc/rfc7517#section-4.8
	X5TS256 string        `json:"x5t#S256,omitempty"` // https://www.rfc-editor.org/rfc/rfc7517#section-4.9
	CRV     CRV           `json:"crv,omitempty"`      // https://www.rfc-editor.org/rfc/rfc7518#section-6.2.1.1 and https://www.rfc-editor.org/rfc/rfc8037.html#section-2
	X       string        `json:"x,omitempty"`        // https://www.rfc-editor.org/rfc/rfc7518#section-6.2.1.2 and https://www.rfc-editor.org/rfc/rfc8037.html#section-2
	Y       string        `json:"y,omitempty"`        // https://www.rfc-editor.org/rfc/rfc7518#section-6.2.1.3
	D       string        `json:"d,omitempty"`        // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.1 and https://www.rfc-editor.org/rfc/rfc7518#section-6.2.2.1 and https://www.rfc-editor.org/rfc/rfc8037.html#section-2
	N       string        `json:"n,omitempty"`        // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.1.1
	E       string        `json:"e,omitempty"`        // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.1.2
	P       string        `json:"p,omitempty"`        // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.2
	Q       string        `json:"q,omitempty"`        // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.3
	DP      string        `json:"dp,omitempty"`       // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.4
	DQ      string        `json:"dq,omitempty"`       // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.5
	QI      string        `json:"qi,omitempty"`       // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.6
	OTH     []OtherPrimes `json:"oth,omitempty"`      // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.7
	K       string        `json:"k,omitempty"`        // https://www.rfc-editor.org/rfc/rfc7518#section-6.4.1
}

JWKMarshal is used to marshal or unmarshal a JSON Web Key. https://www.rfc-editor.org/rfc/rfc7517 https://www.rfc-editor.org/rfc/rfc7518 https://www.rfc-editor.org/rfc/rfc8037

You can find the full list at https://www.iana.org/assignments/jose/jose.xhtml under "JSON Web Key Parameters".

type JWKMarshalOptions added in v0.4.0 

type JWKMarshalOptions struct {
	// Private is used to indicate that the JWK's private key material should be JSON marshaled and unmarshalled. This
	// includes symmetric and asymmetric keys. Setting this to true is the only way to marshal and unmarshal symmetric
	// keys.
	Private bool
}

JWKMarshalOptions are used to specify options for JSON marshaling a JWK.

type JWKMetadataOptions added in v0.4.0 

type JWKMetadataOptions struct {
	// ALG is the algorithm (alg).
	ALG ALG
	// KID is the key ID (kid).
	KID string
	// KEYOPS is the key operations (key_ops).
	KEYOPS []KEYOPS
	// USE is the key use (use).
	USE USE
}

JWKMetadataOptions are direct passthroughs into the JWKMarshal.

type JWKOptions added in v0.4.0 

type JWKOptions struct {
	Marshal  JWKMarshalOptions
	Metadata JWKMetadataOptions
	Validate JWKValidateOptions
	X509     JWKX509Options
}

JWKOptions are used to specify options for marshaling a JSON Web Key.

type JWKSMarshal added in v0.1.0 

type JWKSMarshal struct {
	Keys []JWKMarshal `json:"keys"`
}

JWKSMarshal is used to marshal or unmarshal a JSON Web Key Set.

func (JWKSMarshal) JWKSlice added in v0.5.0 

func (j JWKSMarshal) JWKSlice() ([]JWK, error)

JWKSlice converts the JWKSMarshal to a []JWK.

func (JWKSMarshal) ToStorage added in v0.5.0 

func (j JWKSMarshal) ToStorage() (Storage, error)

ToStorage converts the JWKSMarshal to a Storage.

type JWKValidateOptions added in v0.4.0 

type JWKValidateOptions struct {
	/*
		This package intentionally does not confirm if certificate's usage or compare that to the JWK's use parameter.
		Please open a GitHub issue if you think this should be an option.
	*/
	// CheckX509ValidTime is used to indicate that the X.509 certificate's valid time should be checked.
	CheckX509ValidTime bool
	// GetX5U is used to get and validate the X.509 certificate from the X5U URI. Use DefaultGetX5U for the default
	// behavior.
	GetX5U func(x5u *url.URL) ([]*x509.Certificate, error)
	// SkipAll is used to skip all validation.
	SkipAll bool
	// SkipKeyOps is used to skip validation of the key operations (key_ops).
	SkipKeyOps bool
	// SkipMetadata skips checking if the JWKMetadataOptions match the JWKMarshal.
	SkipMetadata bool
	// SkipUse is used to skip validation of the key use (use).
	SkipUse bool
	// SkipX5UScheme is used to skip checking if the X5U URI scheme is https.
	SkipX5UScheme bool
	// StrictPadding is used to indicate that the JWK should be validated with strict padding.
	StrictPadding bool
}

JWKValidateOptions are used to specify options for validating a JWK.

type JWKX509Options added in v0.4.0 

type JWKX509Options struct {
	// X5C contains a chain of one or more PKIX certificates. The PKIX certificate containing the key value MUST be the
	// first certificate.
	X5C []*x509.Certificate // The PKIX certificate containing the key value MUST be the first certificate.

	// X5U Is a URI that refers to a resource for an X.509 public key certificate or certificate chain.
	X5U string // https://www.rfc-editor.org/rfc/rfc7517#section-4.6
}

JWKX509Options holds the X.509 certificate information for a JWK. This data structure is not used for JSON marshaling.

type KEYOPS added in v0.4.0 

type KEYOPS string

KEYOPS is a set of "JSON Web Key Operations" from https://www.iana.org/assignments/jose/jose.xhtml as mentioned in https://www.rfc-editor.org/rfc/rfc7517#section-4.3

func (KEYOPS) IANARegistered added in v0.4.0 

func (keyopts KEYOPS) IANARegistered() bool

func (KEYOPS) String added in v0.4.0 

func (keyopts KEYOPS) String() string

type KTY added in v0.1.0 

type KTY string

KTY is a set of "JSON Web Key Types" from https://www.iana.org/assignments/jose/jose.xhtml as mentioned in https://www.rfc-editor.org/rfc/rfc7517#section-4.1

func (KTY) IANARegistered added in v0.4.0 

func (kty KTY) IANARegistered() bool

func (KTY) String added in v0.1.0 

func (kty KTY) String() string

type OtherPrimes added in v0.1.0 

type OtherPrimes struct {
	R string `json:"r,omitempty"` // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.7.1
	D string `json:"d,omitempty"` // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.7.2
	T string `json:"t,omitempty"` // https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.7.3
}

OtherPrimes is for RSA private keys that have more than 2 primes. https://www.rfc-editor.org/rfc/rfc7518#section-6.3.2.7

type Storage 

type Storage interface {
	// KeyDelete deletes a key from the storage. It will return ok as true if the key was present for deletion.
	KeyDelete(ctx context.Context, keyID string) (ok bool, err error)
	// KeyRead reads a key from the storage. If the key is not present, it returns ErrKeyNotFound. Any pointers returned
	// should be considered read-only.
	KeyRead(ctx context.Context, keyID string) (JWK, error)
	// KeyReadAll reads a snapshot of all keys from storage. As with ReadKey, any pointers returned should be
	// considered read-only.
	KeyReadAll(ctx context.Context) ([]JWK, error)
	// KeyWrite writes a key to the storage. If the key already exists, it will be overwritten. After writing a key,
	// any pointers written should be considered owned by the underlying storage.
	KeyWrite(ctx context.Context, jwk JWK) error

	// JSON creates the JSON representation of the JWKSet.
	JSON(ctx context.Context) (json.RawMessage, error)
	// JSONPublic creates the JSON representation of the public keys in JWKSet.
	JSONPublic(ctx context.Context) (json.RawMessage, error)
	// JSONPrivate creates the JSON representation of the JWKSet public and private key material.
	JSONPrivate(ctx context.Context) (json.RawMessage, error)
	// JSONWithOptions creates the JSON representation of the JWKSet with the given options. These options override whatever
	// options are set on the individual JWKs.
	JSONWithOptions(ctx context.Context, marshalOptions JWKMarshalOptions, validationOptions JWKValidateOptions) (json.RawMessage, error)
	// Marshal transforms the JWK Set's current state into a Go type that can be marshaled into JSON.
	Marshal(ctx context.Context) (JWKSMarshal, error)
	// MarshalWithOptions transforms the JWK Set's current state into a Go type that can be marshaled into JSON with the
	// given options. These options override whatever options are set on the individual JWKs.
	MarshalWithOptions(ctx context.Context, marshalOptions JWKMarshalOptions, validationOptions JWKValidateOptions) (JWKSMarshal, error)
}

Storage handles storage operations for a JWKSet.

func NewDefaultHTTPClient added in v0.5.0 

func NewDefaultHTTPClient(urls []string) (Storage, error)

NewDefaultHTTPClient creates a new JWK Set client with default options from remote HTTP resources.

The default behavior is to: 1. Refresh remote HTTP resources every hour. 2. Prioritize keys from remote HTTP resources over keys from the given storage. 3. Refresh remote HTTP resources if a key with an unknown key ID is trying to be read, with a rate limit of 5 minutes. 4. Log to slog.Default() if a refresh fails.

func NewDefaultHTTPClientCtx added in v0.5.11 

func NewDefaultHTTPClientCtx(ctx context.Context, urls []string) (Storage, error)

NewDefaultHTTPClientCtx is the same as NewDefaultHTTPClient, but with a context that can end the refresh goroutine.

func NewHTTPClient added in v0.5.0 

func NewHTTPClient(options HTTPClientOptions) (Storage, error)

NewHTTPClient creates a new JWK Set client from remote HTTP resources.

func NewMemoryStorage 

func NewMemoryStorage() Storage

NewMemoryStorage creates a new in-memory Storage implementation.

func NewStorageFromHTTP added in v0.5.0 

func NewStorageFromHTTP(u *url.URL, options HTTPClientStorageOptions) (Storage, error)

NewStorageFromHTTP creates a new Storage implementation that processes a remote HTTP resource for a JWK Set. If the RefreshInterval option is not set, the remote HTTP resource will be requested and processed before returning. If the RefreshInterval option is set, a background goroutine will be launched to refresh the remote HTTP resource and not block the return of this function.

type USE added in v0.4.0 

type USE string

USE is a set of "JSON Web Key Use" types from https://www.iana.org/assignments/jose/jose.xhtml as mentioned in https://www.rfc-editor.org/rfc/rfc7517#section-4.2

func (USE) IANARegistered added in v0.4.0 

func (use USE) IANARegistered() bool

func (USE) String added in v0.4.0 

func (use USE) String() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
gen_ec
gen_pkcs1
jwksetinfer
examples
default_http_client
http_server
individual_keys

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.