jwk

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Jan 28, 2025 License: MIT Imports: 21 Imported by: 6

Documentation

Index

Constants

View Source 
const (
	SHASizeStr = "256"
	AESSizeStr = "128"
	// SHA-1 is probably safe with OAEP, even if collisions become very easy to compute,
	// but let's throw it away to be on the safe side.
	// Using bloated RSA for encryption is a waste anyway.
	RSAPadding        = "-OAEP-256"
	UseKeyWrapForECDH = true

	// Default Signature Algorithms:
	DefaultECSignAlg   = "ES" + SHASizeStr
	DefaultRSASignAlg  = "RS" + SHASizeStr
	DefaultHMACSignAlg = "HS" + SHASizeStr

	// Default Content Encryption Algorithms:
	DefaultContentEncryptionAlgorithm = "A" + AESSizeStr + "GCM"

	// Default Key Management Algorithms:
	DefaultAESKeyAlg           = "A" + AESSizeStr + "KW"
	DefaultRSAKeyAlg           = "RSA" + RSAPadding
	DefaultECKeyAlg            = "ECDH-ES"
	DefaultECKeyAlgWithKeyWrap = "ECDH-ES+" + DefaultAESKeyAlg
)

This package contains some default security settings that determine encryption strength

Variables

This section is empty.

Functions

This section is empty.

Types

type JWK 

type JWK struct {
	Kid string `json:"kid,omitempty"`
	Kty string `json:"kty,omitempty"`
	Alg string `json:"alg,omitempty"`
	Crv string `json:"crv,omitempty"`
	Use string `json:"use,omitempty"`

	// Public Fields
	X *keyBytes `json:"x,omitempty"`
	Y *keyBytes `json:"y,omitempty"`
	N *keyBytes `json:"n,omitempty"`
	E *keyBytes `json:"e,omitempty"`

	// Private Fields
	D  *keyBytes `json:"d,omitempty"`
	P  *keyBytes `json:"p,omitempty"`
	Q  *keyBytes `json:"q,omitempty"`
	Dp *keyBytes `json:"dp,omitempty"`
	Dq *keyBytes `json:"dq,omitempty"`
	Qi *keyBytes `json:"qi,omitempty"`

	// Symmetric Keys
	K *keyBytes `json:"k,omitempty"`

	// Non-standard (but absolutely necessary!) fields
	Exp int64 `json:"exp"`
}

JWK represents an unparsed JSON Web Key (JWK) in its wire format.

func (*JWK) MarshalJSON 

func (jwk *JWK) MarshalJSON() ([]byte, error)

func (*JWK) ParseKeySpec 

func (jwk *JWK) ParseKeySpec() (*KeySpec, error)

ParseKeySpec parses JWK fields into a key that can be used by Go crypto libraries. The following key type conversions are supported:

kty = "oct" -> []byte kty = "OKP" -> okp.OctetKeyPair (Ed25519 or X25519 keys for x/crypto libraries) kty = "RSA" -> rsa.PrivateKey / rsa.PublicKey kty = "EC" -> ecdsa.PrivateKey / ecdsa.PublicKey

type KeySpec 

type KeySpec struct {
	Key       interface{}
	KeyID     string
	Algorithm string
	Use       string
	ExpiresAt time.Time
}

KeySpec contains a cryptographic key accompanied by JWK metadata. This structure is used to contain information from parsed JSON Web Keys.

func MustParse 

func MustParse(jwkStr string) *KeySpec

MustParse parses a JWK string into a KeySpec, panicking on error

func MustParseBytes 

func MustParseBytes(data []byte) *KeySpec

MustParseBytes parses JWK bytes into a KeySpec, panicking on error

func NewSpec 

func NewSpec(key interface{}) *KeySpec

NewSpec directly creates a KeySpec from a concrete key object.

Key object types supported: rsa.PrivateKey, rsa.PublicKey, ecdsa.PrivateKey, ecdsa.PublicKey, okp.OctetKeyPair, []byte

func NewSpecWithID 

func NewSpecWithID(kid string, key interface{}) *KeySpec

NewSpecWithID directly creates a KeySpec from a concrete key object and a Key ID.

Key object types supported: rsa.PrivateKey, rsa.PublicKey, ecdsa.PrivateKey, ecdsa.PublicKey, okp.OctetKeyPair, []byte

func Parse 

func Parse(jwkStr string) (*KeySpec, error)

Parse parses a JWK string into a KeySpec

func ParseBytes 

func ParseBytes(data []byte) (*KeySpec, error)

ParseBytes parses JWK bytes into a KeySpec

func (*KeySpec) Clone 

func (k *KeySpec) Clone() *KeySpec

Clone creates a copy of a KeySpec

func (*KeySpec) CoerceOkpCurve added in v1.1.0 

func (k *KeySpec) CoerceOkpCurve(curve string) okp.CurveOctetKeyPair

func (*KeySpec) IsKeyType 

func (k *KeySpec) IsKeyType(expectedKty string) bool

IsKeyType returns true if KeySpec has expected key type and curve.

If expectedKty contains a slash, then it will be parsed as a pair of key type ('kty') and curve ('crv'), in the following format: 'kty/crv', and the KeySpec will match if both its key type and curve match. Otherwise, only the key type will be checked.

func (*KeySpec) IsPublic 

func (k *KeySpec) IsPublic() bool

IsPublic checks whether the key in KeySpec is a public key or not. In case the key is symmetric, this function returns false.

func (*KeySpec) IsValid added in v1.1.0 

func (k *KeySpec) IsValid() bool

IsValid returns true if the key is valid, i.e. it is not expired yet or has no expiry set

func (*KeySpec) KeyType 

func (k *KeySpec) KeyType() (kty string, curve string, private bool)

KeyType returns the key type based on the key.

func (*KeySpec) MarshalJSON 

func (k *KeySpec) MarshalJSON() ([]byte, error)

MarshalJSON serializes the KeySpec to JSON.

func (*KeySpec) MarshalPublicJSON 

func (k *KeySpec) MarshalPublicJSON() ([]byte, error)

MarshalPublicJSON serializes only the public fields of the KeySpec to JSON. For public keys this gives exactly the same result as MarshalJSON()

func (*KeySpec) Normalize 

func (k *KeySpec) Normalize(settings NormalizationSettings) error

Normalize attempts to put some uniformity on the metadata fields attached to the JSON Web Key The normalization is influenced by the settings parameter.

func (*KeySpec) PublicOnly 

func (k *KeySpec) PublicOnly() (*KeySpec, error)

PublicOnly removes all private components from a KeySpec (if they exists) and returns a key which can be safely published as a public key.

func (*KeySpec) Thumbprint 

func (k *KeySpec) Thumbprint() ([]byte, error)

Thumbprint returns the KeySpec's RFC 7638 thumbprint using SHA-256.

func (*KeySpec) ThumbprintUsing 

func (k *KeySpec) ThumbprintUsing(h hash.Hash) ([]byte, error)

ThumbprintUsing returns the KeySpec's RFC 7638 thumbprint using the specified hash function.

func (*KeySpec) ToJWK 

func (k *KeySpec) ToJWK() (*JWK, error)

ToJWK converts a KeySpec into a JWK struct.

func (*KeySpec) UnmarshalJSON 

func (k *KeySpec) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes a KeySpec from the given JSON.

type KeySpecSet 

type KeySpecSet struct {
	Keys []KeySpec `json:"keys"`
}

KeySpecSet represents a set of parsed JSON Web Keys

func CollectKeySet added in v1.2.0 

func CollectKeySet(seq iter.Seq[KeySpec]) KeySpecSet

CollectKeySet collects all KeySpecs in the sequence and returns a new KeySpecSet.

func (KeySpecSet) ActiveKey added in v1.1.1 

func (ks KeySpecSet) ActiveKey() *KeySpec

ActiveKey returns the middlemost KeySpec in the KeySpecSet.

The middlemost KeySpec is the safest to use when you're implementing key rotation and you need to choose the active key for signing or encryption.

func (KeySpecSet) All added in v1.2.0 

func (ks KeySpecSet) All() iter.Seq[KeySpec]

All returns a sequence of all KeySpecs in the KeySpecSet.

func (KeySpecSet) Filter 

func (ks KeySpecSet) Filter(filter func(key *KeySpec) bool) KeySpecSet

Filter filters the specified KeySpecSet with a filter function

filter is a predicate that accepts a KeySpec and returns a boolean value.

func (KeySpecSet) FilterIter added in v1.2.0 

func (ks KeySpecSet) FilterIter(filter func(key *KeySpec) bool) iter.Seq[KeySpec]

FilterIter filters the specified KeySpecSet with a filter function and returns an iter.Seq.

filter is a predicate that accepts a KeySpec and returns a boolean value.

func (*KeySpecSet) MarshalPublicJSON 

func (ks *KeySpecSet) MarshalPublicJSON() ([]byte, error)

MarshalPublicJSON serializes only the public fields of the keys inside the KeySpecSet to JSON (as JWKS). For public keys this gives exactly the same result as MarshalJSON()

func (KeySpecSet) OnlyKeyTypes 

func (ks KeySpecSet) OnlyKeyTypes(keyTypes ...string) KeySpecSet

OnlyKeyTypes filters the KeySpecSet and returns only KeySpecs which match the specified key type and curve.

If keyType contains a slash, then it will be parsed as a pair of key type ('kty') and curve ('crv'), in the following format: 'kty/crv', and the KeySpec will match if both its key type and curve match. Otherwise, only the key type will be checked.

func (KeySpecSet) OnlyKeyTypesIter added in v1.2.0 

func (ks KeySpecSet) OnlyKeyTypesIter(keyTypes ...string) iter.Seq[KeySpec]

OnlyKeyTypesIter filters the KeySpecSet and returns only KeySpecs which match the specified key type and curve.

See KeySpecSet.OnlyKeyTypes for more information.

func (KeySpecSet) PrimaryCurveOKP 

func (ks KeySpecSet) PrimaryCurveOKP(curve string) (*KeySpec, okp.CurveOctetKeyPair)

PrimaryCurveOKP returns the first CurveOctetKeyPair in the KeySpecSet which matches the specified curve name.

If keyType contains a slash, then it will be parsed as a pair of key type ('kty') and curve ('crv'), in the following format: 'kty/crv', and the KeySpec will match if both its key type and curve match. Otherwise, only the key type will be checked.

func (KeySpecSet) PrimaryECDSAPrivate 

func (ks KeySpecSet) PrimaryECDSAPrivate() (*KeySpec, *ecdsa.PrivateKey)

PrimaryECDSAPrivate returns the first ECDSA PrivateKey in the KeySpecSet which matches the specified curve name.

func (KeySpecSet) PrimaryKey 

func (ks KeySpecSet) PrimaryKey(keyType string) *KeySpec

PrimaryKey returns the first KeySpec in the KeySpecSet which matches the specified key type and curve.

If keyType contains a slash, then it will be parsed as a pair of key type ('kty') and curve ('crv'), in the following format: 'kty/crv', and the KeySpec will match if both its key type and curve match. Otherwise, only the key type will be checked.

type NormalizationSettings 

type NormalizationSettings struct {
	// Use tells KeySpec.Normalize() to set the 'use' field to the specified string
	Use string

	// RequireKeyID tells KeySpec.Normalize() to attempt to auto-generate 'kid' if it
	// is missing and fail if it couldn't generate it automatically.
	// Automatic generation is done by creating a SHA-256 thumbprint of the key.
	RequireKeyID bool

	// RequireAlgorithm requires 'alg' to be specified.
	RequireAlgorithm bool

	// ThumbprintHashFunc specifies the hash function to use for the thumbprint
	ThumbprintHashFunc hash.Hash
}

NormalizationSettings contains settings for the normalization preformed by KeySpec.Normalize()

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.