jose

package
v0.0.9 Latest Latest
Warning

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

 Go to latest Published: Jan 11, 2024 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ED25519            = KeyAlgorithm("ED25519")
	RSA1_5             = KeyAlgorithm("RSA1_5")             // RSA-PKCS1v1.5
	RSA_OAEP           = KeyAlgorithm("RSA-OAEP")           // RSA-OAEP-SHA1
	RSA_OAEP_256       = KeyAlgorithm("RSA-OAEP-256")       // RSA-OAEP-SHA256
	A128KW             = KeyAlgorithm("A128KW")             // AES key wrap (128)
	A192KW             = KeyAlgorithm("A192KW")             // AES key wrap (192)
	A256KW             = KeyAlgorithm("A256KW")             // AES key wrap (256)
	DIRECT             = KeyAlgorithm("dir")                // Direct encryption
	ECDH_ES            = KeyAlgorithm("ECDH-ES")            // ECDH-ES
	ECDH_ES_A128KW     = KeyAlgorithm("ECDH-ES+A128KW")     // ECDH-ES + AES key wrap (128)
	ECDH_ES_A192KW     = KeyAlgorithm("ECDH-ES+A192KW")     // ECDH-ES + AES key wrap (192)
	ECDH_ES_A256KW     = KeyAlgorithm("ECDH-ES+A256KW")     // ECDH-ES + AES key wrap (256)
	A128GCMKW          = KeyAlgorithm("A128GCMKW")          // AES-GCM key wrap (128)
	A192GCMKW          = KeyAlgorithm("A192GCMKW")          // AES-GCM key wrap (192)
	A256GCMKW          = KeyAlgorithm("A256GCMKW")          // AES-GCM key wrap (256)
	PBES2_HS256_A128KW = KeyAlgorithm("PBES2-HS256+A128KW") // PBES2 + HMAC-SHA256 + AES key wrap (128)
	PBES2_HS384_A192KW = KeyAlgorithm("PBES2-HS384+A192KW") // PBES2 + HMAC-SHA384 + AES key wrap (192)
	PBES2_HS512_A256KW = KeyAlgorithm("PBES2-HS512+A256KW") // PBES2 + HMAC-SHA512 + AES key wrap (256)
	ECDH_SM2_S128KW    = KeyAlgorithm("ECDH-SM2+S128KW")
)

Key management algorithms

View Source 
const (
	EdDSA  = SignatureAlgorithm("EdDSA")
	HS256  = SignatureAlgorithm("HS256") // HMAC using SHA-256
	HS384  = SignatureAlgorithm("HS384") // HMAC using SHA-384
	HS512  = SignatureAlgorithm("HS512") // HMAC using SHA-512
	RS256  = SignatureAlgorithm("RS256") // RSASSA-PKCS-v1.5 using SHA-256
	RS384  = SignatureAlgorithm("RS384") // RSASSA-PKCS-v1.5 using SHA-384
	RS512  = SignatureAlgorithm("RS512") // RSASSA-PKCS-v1.5 using SHA-512
	ES256  = SignatureAlgorithm("ES256") // ECDSA using P-256 and SHA-256
	ES384  = SignatureAlgorithm("ES384") // ECDSA using P-384 and SHA-384
	ES512  = SignatureAlgorithm("ES512") // ECDSA using P-521 and SHA-512
	PS256  = SignatureAlgorithm("PS256") // RSASSA-PSS using SHA256 and MGF1-SHA256
	PS384  = SignatureAlgorithm("PS384") // RSASSA-PSS using SHA384 and MGF1-SHA384
	PS512  = SignatureAlgorithm("PS512") // RSASSA-PSS using SHA512 and MGF1-SHA512
	SM3128 = SignatureAlgorithm("SM3")
)

Signature algorithms

View Source 
const (
	A128CBC_HS256  = ContentEncryption("A128CBC-HS256") // AES-CBC + HMAC-SHA256 (128)
	A192CBC_HS384  = ContentEncryption("A192CBC-HS384") // AES-CBC + HMAC-SHA384 (192)
	A256CBC_HS512  = ContentEncryption("A256CBC-HS512") // AES-CBC + HMAC-SHA512 (256)
	A128GCM        = ContentEncryption("A128GCM")       // AES-GCM (128)
	A192GCM        = ContentEncryption("A192GCM")       // AES-GCM (192)
	A256GCM        = ContentEncryption("A256GCM")       // AES-GCM (256)
	S128GCM        = ContentEncryption("S128GCM")
	S128CBC_SM3128 = ContentEncryption("S128CBC-128")
)

Content encryption algorithms

View Source 
const (
	NONE    = CompressionAlgorithm("")    // No compression
	DEFLATE = CompressionAlgorithm("DEF") // DEFLATE (RFC 1951)
)

Compression algorithms

View Source 
const (
	HeaderType        = "typ" // string
	HeaderContentType = "cty" // string

)

Variables

View Source 
var (
	// ErrCryptoFailure represents an error in cryptographic primitive. This
	// occurs when, for example, a message had an invalid authentication tag or
	// could not be decrypted.
	ErrCryptoFailure = errors.New("go-jose/go-jose: error in cryptographic primitive")

	// ErrUnsupportedAlgorithm indicates that a selected algorithm is not
	// supported. This occurs when trying to instantiate an encrypter for an
	// algorithm that is not yet implemented.
	ErrUnsupportedAlgorithm = errors.New("go-jose/go-jose: unknown/unsupported algorithm")

	// ErrUnsupportedKeyType indicates that the given key type/format is not
	// supported. This occurs when trying to instantiate an encrypter and passing
	// it a key of an unrecognized type or with unsupported parameters, such as
	// an RSA private key with more than two primes.
	ErrUnsupportedKeyType = errors.New("go-jose/go-jose: unsupported key type/format")

	// ErrInvalidKeySize indicates that the given key is not the correct size
	// for the selected algorithm. This can occur, for example, when trying to
	// encrypt with AES-256 but passing only a 128-bit key as input.
	ErrInvalidKeySize = errors.New("go-jose/go-jose: invalid key size for algorithm")

	// ErrNotSupported serialization of object is not supported. This occurs when
	// trying to compact-serialize an object which can't be represented in
	// compact form.
	ErrNotSupported = errors.New("go-jose/go-jose: compact serialization not supported for object")

	// ErrUnprotectedNonce indicates that while parsing a JWS or JWE object, a
	// nonce header parameter was included in an unprotected header object.
	ErrUnprotectedNonce = errors.New("go-jose/go-jose: Nonce parameter included in unprotected header")
)
View Source 
var RandReader = rand.Reader

RandReader is a cryptographically secure random number generator (stubbed out in tests).

Functions

This section is empty.

Types

type CompressionAlgorithm 

type CompressionAlgorithm string

CompressionAlgorithm represents an algorithm used for plaintext compression.

type ContentEncryption 

type ContentEncryption string

ContentEncryption represents a content encryption algorithm.

type ContentType 

type ContentType string

ContentType represents type of the contained data.

type Encrypter 

type Encrypter interface {
	Encrypt(plaintext []byte) (*JSONWebEncryption, error)
	EncryptWithAuthData(plaintext []byte, aad []byte) (*JSONWebEncryption, error)
	Options() EncrypterOptions
}

Encrypter represents an encrypter which produces an encrypted JWE object.

func NewEncrypter 

func NewEncrypter(enc ContentEncryption, rcpt Recipient, opts *EncrypterOptions) (Encrypter, error)

NewEncrypter creates an appropriate encrypter based on the key type

func NewMultiEncrypter 

func NewMultiEncrypter(enc ContentEncryption, rcpts []Recipient, opts *EncrypterOptions) (Encrypter, error)

NewMultiEncrypter creates a multi-encrypter based on the given parameters

type EncrypterOptions 

type EncrypterOptions struct {
	Compression CompressionAlgorithm

	// Optional map of additional keys to be inserted into the protected header
	// of a JWS object. Some specifications which make use of JWS like to insert
	// additional values here. All values must be JSON-serializable.
	ExtraHeaders map[HeaderKey]interface{}
}

EncrypterOptions represents options that can be set on new encrypters.

func (*EncrypterOptions) WithContentType 

func (eo *EncrypterOptions) WithContentType(contentType ContentType) *EncrypterOptions

WithContentType adds a content type ("cty") header and returns the updated EncrypterOptions.

func (*EncrypterOptions) WithHeader 

func (eo *EncrypterOptions) WithHeader(k HeaderKey, v interface{}) *EncrypterOptions

WithHeader adds an arbitrary value to the ExtraHeaders map, initializing it if necessary. It returns itself and so can be used in a fluent style.

func (*EncrypterOptions) WithType 

func (eo *EncrypterOptions) WithType(typ ContentType) *EncrypterOptions

WithType adds a type ("typ") header and returns the updated EncrypterOptions. 

type Header struct {
	KeyID      string
	JSONWebKey *JSONWebKey
	Algorithm  string
	Nonce      string

	// Any headers not recognised above get unmarshalled
	// from JSON in a generic manner and placed in this map.
	ExtraHeaders map[HeaderKey]interface{}
	// contains filtered or unexported fields
}

Header represents the read-only JOSE header for JWE/JWS objects.

func (Header) Certificates 

func (h Header) Certificates(opts x509.VerifyOptions) ([][]*x509.Certificate, error)

Certificates verifies & returns the certificate chain present in the x5c header field of a message, if one was present. Returns an error if there was no x5c header present or the chain could not be validated with the given verify options.

type HeaderKey 

type HeaderKey string

A key in the protected header of a JWS object. Use of the Header... constants is preferred to enhance type safety.

type JSONWebEncryption 

type JSONWebEncryption struct {
	Header Header
	// contains filtered or unexported fields
}

JSONWebEncryption represents an encrypted JWE object after parsing.

func ParseEncrypted 

func ParseEncrypted(input string) (*JSONWebEncryption, error)

ParseEncrypted parses an encrypted message in compact or JWE JSON Serialization format.

func (JSONWebEncryption) CompactSerialize 

func (obj JSONWebEncryption) CompactSerialize() (string, error)

CompactSerialize serializes an object using the compact serialization format.

func (JSONWebEncryption) Decrypt 

func (obj JSONWebEncryption) Decrypt(decryptionKey interface{}) ([]byte, error)

Decrypt and validate the object and return the plaintext. Note that this function does not support multi-recipient, if you desire multi-recipient decryption use DecryptMulti instead.

func (JSONWebEncryption) DecryptMulti 

func (obj JSONWebEncryption) DecryptMulti(decryptionKey interface{}) (int, Header, []byte, error)

DecryptMulti decrypts and validates the object and returns the plaintexts, with support for multiple recipients. It returns the index of the recipient for which the decryption was successful, the merged headers for that recipient, and the plaintext.

func (JSONWebEncryption) FullSerialize 

func (obj JSONWebEncryption) FullSerialize() string

FullSerialize serializes an object using the full JSON serialization format.

func (JSONWebEncryption) GetAuthData 

func (obj JSONWebEncryption) GetAuthData() []byte

GetAuthData retrieves the (optional) authenticated data attached to the object.

type JSONWebKey 

type JSONWebKey struct {
	// Cryptographic key, can be a symmetric or asymmetric key.
	Key interface{}
	// Key identifier, parsed from `kid` header.
	KeyID string
	// Key algorithm, parsed from `alg` header.
	Algorithm string
	// Key use, parsed from `use` header.
	Use string

	// X.509 certificate chain, parsed from `x5c` header.
	Certificates []*x509.Certificate
	// X.509 certificate URL, parsed from `x5u` header.
	CertificatesURL *url.URL
	// X.509 certificate thumbprint (SHA-1), parsed from `x5t` header.
	CertificateThumbprintSHA1 []byte
	// X.509 certificate thumbprint (SHA-256), parsed from `x5t#S256` header.
	CertificateThumbprintSHA256 []byte
}

JSONWebKey represents a public or private key in JWK format.

func (*JSONWebKey) IsPublic 

func (k *JSONWebKey) IsPublic() bool

IsPublic returns true if the JWK represents a public key (not symmetric, not private).

func (JSONWebKey) MarshalJSON 

func (k JSONWebKey) MarshalJSON() ([]byte, error)

MarshalJSON serializes the given key to its JSON representation.

func (*JSONWebKey) Public 

func (k *JSONWebKey) Public() JSONWebKey

Public creates JSONWebKey with corresponding public key if JWK represents asymmetric private key.

func (*JSONWebKey) Thumbprint 

func (k *JSONWebKey) Thumbprint(hash crypto.Hash) ([]byte, error)

Thumbprint computes the JWK Thumbprint of a key using the indicated hash algorithm.

func (*JSONWebKey) UnmarshalJSON 

func (k *JSONWebKey) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON reads a key from its JSON representation.

func (*JSONWebKey) Valid 

func (k *JSONWebKey) Valid() bool

Valid checks that the key contains the expected parameters.

type JSONWebKeySet 

type JSONWebKeySet struct {
	Keys []JSONWebKey `json:"keys"`
}

JSONWebKeySet represents a JWK Set object.

func (*JSONWebKeySet) Key 

func (s *JSONWebKeySet) Key(kid string) []JSONWebKey

Key convenience method returns keys by key ID. Specification states that a JWK Set "SHOULD" use distinct key IDs, but allows for some cases where they are not distinct. Hence method returns a slice of JSONWebKeys.

type JSONWebSignature 

type JSONWebSignature struct {

	// Signatures attached to this object (may be more than one for multi-sig).
	// Be careful about accessing these directly, prefer to use Verify() or
	// VerifyMulti() to ensure that the data you're getting is verified.
	Signatures []Signature
	// contains filtered or unexported fields
}

JSONWebSignature represents a signed JWS object after parsing.

func ParseDetached 

func ParseDetached(signature string, payload []byte) (*JSONWebSignature, error)

ParseDetached parses a signed message in compact serialization format with detached payload.

func ParseSigned 

func ParseSigned(signature string) (*JSONWebSignature, error)

ParseSigned parses a signed message in compact or JWS JSON Serialization format.

func (JSONWebSignature) CompactSerialize 

func (obj JSONWebSignature) CompactSerialize() (string, error)

CompactSerialize serializes an object using the compact serialization format.

func (JSONWebSignature) DetachedCompactSerialize 

func (obj JSONWebSignature) DetachedCompactSerialize() (string, error)

DetachedCompactSerialize serializes an object using the compact serialization format with detached payload.

func (JSONWebSignature) DetachedVerify 

func (obj JSONWebSignature) DetachedVerify(payload []byte, verificationKey interface{}) error

DetachedVerify validates a detached signature on the given payload. In most cases, you will probably want to use Verify instead. DetachedVerify is only useful if you have a payload and signature that are separated from each other.

func (JSONWebSignature) DetachedVerifyMulti 

func (obj JSONWebSignature) DetachedVerifyMulti(payload []byte, verificationKey interface{}) (int, Signature, error)

DetachedVerifyMulti validates a detached signature on the given payload with a signature/object that has potentially multiple signers. This returns the index of the signature that was verified, along with the signature object. We return the signature and index to guarantee that callers are getting the verified value.

In most cases, you will probably want to use Verify or VerifyMulti instead. DetachedVerifyMulti is only useful if you have a payload and signature that are separated from each other, and the signature can have multiple signers at the same time.

func (JSONWebSignature) FullSerialize 

func (obj JSONWebSignature) FullSerialize() string

FullSerialize serializes an object using the full JSON serialization format.

func (JSONWebSignature) UnsafePayloadWithoutVerification 

func (obj JSONWebSignature) UnsafePayloadWithoutVerification() []byte

UnsafePayloadWithoutVerification returns the payload without verifying it. The content returned from this function cannot be trusted.

func (JSONWebSignature) Verify 

func (obj JSONWebSignature) Verify(verificationKey interface{}) ([]byte, error)

Verify validates the signature on the object and returns the payload. This function does not support multi-signature, if you desire multi-sig verification use VerifyMulti instead.

Be careful when verifying signatures based on embedded JWKs inside the payload header. You cannot assume that the key received in a payload is trusted.

func (JSONWebSignature) VerifyMulti 

func (obj JSONWebSignature) VerifyMulti(verificationKey interface{}) (int, Signature, []byte, error)

VerifyMulti validates (one of the multiple) signatures on the object and returns the index of the signature that was verified, along with the signature object and the payload. We return the signature and index to guarantee that callers are getting the verified value.

type KeyAlgorithm 

type KeyAlgorithm string

KeyAlgorithm represents a key management algorithm.

type NonceSource 

type NonceSource interface {
	Nonce() (string, error)
}

NonceSource represents a source of random nonces to go into JWS objects

type OpaqueKeyDecrypter 

type OpaqueKeyDecrypter interface {
	DecryptKey(encryptedKey []byte, header Header) ([]byte, error)
}

OpaqueKeyDecrypter is an interface that supports decrypting keys with an opaque key.

type OpaqueKeyEncrypter 

type OpaqueKeyEncrypter interface {
	// KeyID returns the kid
	KeyID() string
	// Algs returns a list of supported key encryption algorithms.
	Algs() []KeyAlgorithm
	// contains filtered or unexported methods
}

OpaqueKeyEncrypter is an interface that supports encrypting keys with an opaque key.

type OpaqueSigner 

type OpaqueSigner interface {
	// Public returns the public key of the current signing key.
	Public() *JSONWebKey
	// Algs returns a list of supported signing algorithms.
	Algs() []SignatureAlgorithm
	// SignPayload signs a payload with the current signing key using the given
	// algorithm.
	SignPayload(payload []byte, alg SignatureAlgorithm) ([]byte, error)
}

OpaqueSigner is an interface that supports signing payloads with opaque private key(s). Private key operations performed by implementers may, for example, occur in a hardware module. An OpaqueSigner may rotate signing keys transparently to the user of this interface.

type OpaqueVerifier 

type OpaqueVerifier interface {
	VerifyPayload(payload []byte, signature []byte, alg SignatureAlgorithm) error
}

OpaqueVerifier is an interface that supports verifying payloads with opaque public key(s). An OpaqueSigner may rotate signing keys transparently to the user of this interface.

type Recipient 

type Recipient struct {
	Algorithm  KeyAlgorithm
	Key        interface{}
	KeyID      string
	PBES2Count int
	PBES2Salt  []byte
}

Recipient represents an algorithm/key to encrypt messages to.

PBES2Count and PBES2Salt correspond with the "p2c" and "p2s" headers used on the password-based encryption algorithms PBES2-HS256+A128KW, PBES2-HS384+A192KW, and PBES2-HS512+A256KW. If they are not provided a safe default of 100000 will be used for the count and a 128-bit random salt will be generated.

type Signature 

type Signature struct {
	// Merged header fields. Contains both protected and unprotected header
	// values. Prefer using Protected and Unprotected fields instead of this.
	// Values in this header may or may not have been signed and in general
	// should not be trusted.
	Header Header

	// Protected header. Values in this header were signed and
	// will be verified as part of the signature verification process.
	Protected Header

	// Unprotected header. Values in this header were not signed
	// and in general should not be trusted.
	Unprotected Header

	// The actual signature value
	Signature []byte
	// contains filtered or unexported fields
}

Signature represents a single signature over the JWS payload and protected header.

type SignatureAlgorithm 

type SignatureAlgorithm string

SignatureAlgorithm represents a signature (or MAC) algorithm.

type Signer 

type Signer interface {
	Sign(payload []byte) (*JSONWebSignature, error)
	Options() SignerOptions
}

Signer represents a signer which takes a payload and produces a signed JWS object.

func NewMultiSigner 

func NewMultiSigner(sigs []SigningKey, opts *SignerOptions) (Signer, error)

NewMultiSigner creates a signer for multiple recipients

func NewSigner 

func NewSigner(sig SigningKey, opts *SignerOptions) (Signer, error)

NewSigner creates an appropriate signer based on the key type

type SignerOptions 

type SignerOptions struct {
	NonceSource NonceSource
	EmbedJWK    bool

	// Optional map of additional keys to be inserted into the protected header
	// of a JWS object. Some specifications which make use of JWS like to insert
	// additional values here. All values must be JSON-serializable.
	ExtraHeaders map[HeaderKey]interface{}
}

SignerOptions represents options that can be set when creating signers.

func (*SignerOptions) WithBase64 

func (so *SignerOptions) WithBase64(b64 bool) *SignerOptions

WithBase64 adds a base64url-encode payload ("b64") header and returns the updated SignerOptions. When the "b64" value is "false", the payload is not base64 encoded.

func (*SignerOptions) WithContentType 

func (so *SignerOptions) WithContentType(contentType ContentType) *SignerOptions

WithContentType adds a content type ("cty") header and returns the updated SignerOptions.

func (*SignerOptions) WithCritical 

func (so *SignerOptions) WithCritical(names ...string) *SignerOptions

WithCritical adds the given names to the critical ("crit") header and returns the updated SignerOptions.

func (*SignerOptions) WithHeader 

func (so *SignerOptions) WithHeader(k HeaderKey, v interface{}) *SignerOptions

WithHeader adds an arbitrary value to the ExtraHeaders map, initializing it if necessary. It returns itself and so can be used in a fluent style.

func (*SignerOptions) WithType 

func (so *SignerOptions) WithType(typ ContentType) *SignerOptions

WithType adds a type ("typ") header and returns the updated SignerOptions.

type SigningKey 

type SigningKey struct {
	Algorithm SignatureAlgorithm
	Key       interface{}
}

SigningKey represents an algorithm/key used to sign a message.

Source Files

View all Source files

Directories

Path Synopsis

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.