header

package
v0.0.0-...-7521c7f Latest Latest
Warning

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

 Go to latest Published: Aug 16, 2025 License: MPL-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package header provides a package for JWS and JWE headers as described in RFC 7515 and RFC 7516.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrParameterNotFound is returned when a parameter is not found in the header.
	ErrParameterNotFound = errors.New("header: parameter not found")

	// ErrInvalidParameterType is returned when a parameter is not the expected type.
	ErrInvalidParameterType = errors.New("header: invalid parameter type")

	// ErrFailedToEncodeHeader is returned when the header fails to be encoded.
	ErrFailedToEncodeHeader = errors.New("header: failed to base64 URL encode")

	// ErrCriticalHeaderValidation is returned when critical header validation fails.
	ErrCriticalHeaderValidation = errors.New("header: critical header validation failed")
)

Functions

func Get 

func Get[T any](h Parameters, param ParameterName) (T, error)

func IsStandardParameter 

func IsStandardParameter(name string) bool

IsStandardParameter returns true if the parameter name is defined as a standard parameter by RFC 7515 (JWS) or RFC 7516 (JWE).

func StandardParameters 

func StandardParameters() []string

StandardParameters returns a slice of all standard JOSE header parameter names as defined by RFC 7515 (JWS) and RFC 7516 (JWE).

Per RFC 7515 Section 4.1.11, these parameters MUST NOT be included in the "crit" (Critical) header parameter list.

Types

type ParameterName 

type ParameterName = string

ParameterName is one of three types: registered, public, or private.

https://datatracker.ietf.org/doc/html/rfc7515#section-4

type Parameters 

type Parameters map[ParameterName]any

Parameters is a JSON object containing the parameters describing the cryptographic operations and parameters employed.

The JOSE (JSON Object Signing and Encryption) Header is comprised of a set of Header Parameters.

https://datatracker.ietf.org/doc/html/rfc7515#section-2

func (Parameters) Algorithm 

func (h Parameters) Algorithm() (jwa.Algorithm, error)

Algorithm returns the algorithm intended for use with the JWS or JWE; the algorithm used to digitally sign the JWS or encrypt the JWE.

func (Parameters) AsymmetricAlgorithm 

func (h Parameters) AsymmetricAlgorithm() (bool, error)

AsymmetricAlgorithm returns true if the algorithm used in the header is asymmetric. If the algorithm is not asymmetric, the function returns false.

func (Parameters) Get 

func (h Parameters) Get(param ParameterName) (any, error)

Get returns the value for a given parameter name from the set of JOSE header parameters.

This is a convenience function for accessing the value of a parameter from the JOSE header without having to check if the parameter exists in the header first. This function will return an error if the parameter does not exist in the header.

func (Parameters) Has 

func (h Parameters) Has(param ParameterName) bool

Has returns true if the given parameter name exists in the set of JOSE header parameters.

func (Parameters) SymmetricAlgorithm 

func (h Parameters) SymmetricAlgorithm() (bool, error)

SymmetricAlgorithm returns true if the algorithm used in the header is symmetric. If the algorithm is not symmetric, the function returns false.

func (Parameters) Type 

func (h Parameters) Type() (string, error)

Type returns the media type of this complete JOSE object (JWS or JWE).

func (Parameters) ValidateCriticalHeaders 

func (h Parameters) ValidateCriticalHeaders(supportedCriticalHeaders []string) error

ValidateCriticalHeaders validates critical headers per RFC 7515 section 4.1.11. If a "crit" header is present, it must contain only extension header parameter names that the application understands and can process.

This function implements the complete RFC 7515 critical header validation: 1. Validates "crit" is an array of strings 2. Ensures the array is not empty 3. Checks no standard parameters are marked as critical 4. Verifies all critical parameters are present in the header 5. Validates all critical parameters are supported by the application

type Private 

type Private = ParameterName

Private header parameter names for use in private agreements.

https://datatracker.ietf.org/doc/html/rfc7515#section-4.3

type Public 

type Public = ParameterName

Public header parameter names that are not registered, but should be collision resistant.

https://datatracker.ietf.org/doc/html/rfc7515#section-4.2

type Registered 

type Registered = ParameterName

Registered header parameter names from the IANA registry.

https://datatracker.ietf.org/doc/html/rfc7515#section-4.1 

const (
	// Algorithm "alg" is the algorithm intended for use with the JWS or JWE.
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.1
	Algorithm Registered = "alg"

	// JWKSetURL "jku" is a URL that refers to a resource for a set of JSON-encoded public keys,
	// one of which corresponds to the key used to digitally sign the JWS or encrypt the JWE.
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.2
	JWKSetURL Registered = "jku"

	// JSONWebKey "jwk" is the public key that corresponds to the key used to digitally sign
	// the JWS or encrypt the JWE.
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.3
	JSONWebKey Registered = "jwk"

	// KeyID "kid" is a hint indicating which key was used to secure the JWS or JWE.
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.4
	KeyID Registered = "kid"

	// X509URL "x5u" is a URL that refers to a resource for the X.509 public key certificate
	// or certificate chain corresponding to the key used to digitally sign the JWS or encrypt the JWE.
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.5
	X509URL Registered = "x5u"

	// X509CertificateChain "x5c" is the X.509 public key certificate or certificate chain
	// corresponding to the key used to digitally sign the JWS or encrypt the JWE.
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.6
	X509CertificateChain Registered = "x5c"

	// X509CertificateSHA1Thumbprint "x5t" is the base64url-encoded SHA-1 thumbprint (a.k.a. digest)
	// of the DER encoding of the X.509 certificate corresponding to the key used to digitally sign the JWS or encrypt the JWE.
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.7
	X509CertificateSHA1Thumbprint Registered = "x5t"

	// X509CertificateSHA256Thumbprint "x5t#S256" is the base64url-encoded SHA-256 thumbprint (a.k.a. digest)
	// of the DER encoding of the X.509 certificate corresponding to the key used to digitally sign the JWS or encrypt the JWE.
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.8
	X509CertificateSHA256Thumbprint Registered = "x5t#S256"

	// Type "typ" is the [media type] of this complete JOSE object (JWS or JWE).
	//
	// [media type]: https://www.iana.org/assignments/media-types/media-types.xhtml
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.9
	Type Registered = "typ"

	// ContentType "cty" is the media type of the secured content (the payload).
	//
	// [media type]: https://www.iana.org/assignments/media-types/media-types.xhtml
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.10
	ContentType Registered = "cty"

	// Critical "crit" is a list of header parameter names that have
	// values that MUST be integrity protected by the JWS signer.
	//
	// https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.11
	Critical Registered = "crit"

	// EncryptionAlgorithm "enc" is the encryption algorithm used to encrypt
	// the "plaintext" to produce the "ciphertext".
	//
	// https://www.rfc-editor.org/rfc/rfc7516.html#section-4.1.2
	Encryption Registered = "enc"

	// Zip "zip" is the compression algorithm used to compress the "plaintext"
	// before encryption.
	//
	// https://www.rfc-editor.org/rfc/rfc7516.html#section-4.1.3
	Zip Registered = "zip"
)
  • IANA Registry

Registered header parameter names used in JWS and JWE.

IANA Registry

https://www.iana.org/assignments/jose/jose.xhtml

https://datatracker.ietf.org/doc/html/rfc7515#section-4.1

Source Files

View all Source files

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.