Documentation ¶
Overview ¶
Package jose aims to provide an implementation of the Javascript Object Signing and Encryption set of standards. It implements encryption and signing based on the JSON Web Encryption and JSON Web Signature standards, with optional JSON Web Token support available in a sub-package. The library supports both the compact and JWS/JWE JSON Serialization formats, and has optional support for multiple recipients.
Example (JWE) ¶
// Generate a public/private key pair to use for this example. privateKey, err := rsa.GenerateKey(rand.Reader, 2048) if err != nil { panic(err) } // Instantiate an encrypter using RSA-OAEP with AES128-GCM. An error would // indicate that the selected algorithm(s) are not currently supported. publicKey := &privateKey.PublicKey encrypter, err := NewEncrypter(A128GCM, Recipient{Algorithm: RSA_OAEP, Key: publicKey}, nil) if err != nil { panic(err) } // Encrypt a sample plaintext. Calling the encrypter returns an encrypted // JWE object, which can then be serialized for output afterwards. An error // would indicate a problem in an underlying cryptographic primitive. var plaintext = []byte("Lorem ipsum dolor sit amet") object, err := encrypter.Encrypt(plaintext) if err != nil { panic(err) } // Serialize the encrypted object using the JWE JSON Serialization format. // Alternatively you can also use the compact format here by calling // object.CompactSerialize() instead. serialized := object.FullSerialize() // Parse the serialized, encrypted JWE object. An error would indicate that // the given input did not represent a valid message. object, err = ParseEncrypted(serialized, []KeyAlgorithm{RSA_OAEP}, []ContentEncryption{A128GCM}) if err != nil { panic(err) } // Now we can decrypt and get back our original plaintext. An error here // would indicate that the message failed to decrypt, e.g. because the auth // tag was broken or the message was tampered with. decrypted, err := object.Decrypt(privateKey) if err != nil { panic(err) } fmt.Print(string(decrypted))
Output: Lorem ipsum dolor sit amet
Example (JWS) ¶
// Generate a public/private key pair to use for this example. privateKey, err := rsa.GenerateKey(rand.Reader, 2048) if err != nil { panic(err) } // Instantiate a signer using RSASSA-PSS (SHA512) with the given private key. signer, err := NewSigner(SigningKey{Algorithm: PS512, Key: privateKey}, nil) if err != nil { panic(err) } // Sign a sample payload. Calling the signer returns a protected JWS object, // which can then be serialized for output afterwards. An error would // indicate a problem in an underlying cryptographic primitive. var payload = []byte("Lorem ipsum dolor sit amet") object, err := signer.Sign(payload) if err != nil { panic(err) } // Serialize the signed object using the JWS JSON Serialization format. // Alternatively you can also use the compact format here by calling // object.CompactSerialize() instead. serialized := object.FullSerialize() // Parse the serialized, protected JWS object. An error would indicate that // the given input did not represent a valid message. object, err = ParseSigned(serialized, []SignatureAlgorithm{PS512}) if err != nil { panic(err) } // Now we can verify the signature on the payload. An error here would // indicate that the message failed to verify, e.g. because the signature was // broken or the message was tampered with. output, err := object.Verify(&privateKey.PublicKey) if err != nil { panic(err) } fmt.Print(string(output))
Output: Lorem ipsum dolor sit amet
Index ¶
- Constants
- Variables
- type CompressionAlgorithm
- type ContentEncryption
- type ContentType
- type Encrypter
- type EncrypterOptions
- type Header
- type HeaderKey
- type JSONWebEncryption
- func ParseEncrypted(input string, keyEncryptionAlgorithms []KeyAlgorithm, ...) (*JSONWebEncryption, error)
- func ParseEncryptedCompact(input string, keyAlgorithms []KeyAlgorithm, ...) (*JSONWebEncryption, error)
- func ParseEncryptedJSON(input string, keyEncryptionAlgorithms []KeyAlgorithm, ...) (*JSONWebEncryption, error)
- func (obj JSONWebEncryption) CompactSerialize() (string, error)
- func (obj JSONWebEncryption) Decrypt(decryptionKey interface{}) ([]byte, error)
- func (obj JSONWebEncryption) DecryptMulti(decryptionKey interface{}) (int, Header, []byte, error)
- func (obj JSONWebEncryption) FullSerialize() string
- func (obj JSONWebEncryption) GetAuthData() []byte
- type JSONWebKey
- type JSONWebKeySet
- type JSONWebSignature
- func ParseDetached(signature string, payload []byte, signatureAlgorithms []SignatureAlgorithm) (*JSONWebSignature, error)
- func ParseSigned(signature string, signatureAlgorithms []SignatureAlgorithm) (*JSONWebSignature, error)
- func ParseSignedCompact(signature string, signatureAlgorithms []SignatureAlgorithm) (*JSONWebSignature, error)
- func ParseSignedJSON(input string, signatureAlgorithms []SignatureAlgorithm) (*JSONWebSignature, error)
- func (obj JSONWebSignature) CompactSerialize() (string, error)
- func (obj JSONWebSignature) DetachedCompactSerialize() (string, error)
- func (obj JSONWebSignature) DetachedVerify(payload []byte, verificationKey interface{}) error
- func (obj JSONWebSignature) DetachedVerifyMulti(payload []byte, verificationKey interface{}) (int, Signature, error)
- func (obj JSONWebSignature) FullSerialize() string
- func (obj JSONWebSignature) UnsafePayloadWithoutVerification() []byte
- func (obj JSONWebSignature) Verify(verificationKey interface{}) ([]byte, error)
- func (obj JSONWebSignature) VerifyMulti(verificationKey interface{}) (int, Signature, []byte, error)
- type KeyAlgorithm
- type NonceSource
- type OpaqueKeyDecrypter
- type OpaqueKeyEncrypter
- type OpaqueSigner
- type OpaqueVerifier
- type Recipient
- type Signature
- type SignatureAlgorithm
- type Signer
- type SignerOptions
- func (so *SignerOptions) WithBase64(b64 bool) *SignerOptions
- func (so *SignerOptions) WithContentType(contentType ContentType) *SignerOptions
- func (so *SignerOptions) WithCritical(names ...string) *SignerOptions
- func (so *SignerOptions) WithHeader(k HeaderKey, v interface{}) *SignerOptions
- func (so *SignerOptions) WithType(typ ContentType) *SignerOptions
- type SigningKey
Examples ¶
Constants ¶
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) )
Key management algorithms
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 )
Signature algorithms
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) )
Content encryption algorithms
const ( NONE = CompressionAlgorithm("") // No compression DEFLATE = CompressionAlgorithm("DEF") // DEFLATE (RFC 1951) )
Compression algorithms
const ( HeaderType = "typ" // string HeaderContentType = "cty" // string )
Variables ¶
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") // ErrMissingX5cHeader indicates that the JWT header is missing x5c headers. ErrMissingX5cHeader = errors.New("go-jose/go-jose: no x5c header present in message") // ErrUnsupportedEllipticCurve indicates unsupported or unknown elliptic curve has been found. ErrUnsupportedEllipticCurve = errors.New("go-jose/go-jose: unsupported/unknown elliptic curve") )
var ( // ErrJWKSKidNotFound is returned when a JWKS does not contain a JWK with a // key ID which matches one in the provided tokens headers. ErrJWKSKidNotFound = errors.New("go-jose/go-jose: JWK with matching kid not found in JWK Set") )
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 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.
Example (Encrypt) ¶
// Encrypt a plaintext in order to get an encrypted JWE object. var plaintext = []byte("This is a secret message") encrypter.Encrypt(plaintext)
Output:
Example (EncryptWithAuthData) ¶
// Encrypt a plaintext in order to get an encrypted JWE object. Also attach // some additional authenticated data (AAD) to the object. Note that objects // with attached AAD can only be represented using JWE JSON Serialization. var plaintext = []byte("This is a secret message") var aad = []byte("This is authenticated, but public data") encrypter.EncryptWithAuthData(plaintext, aad)
Output:
func NewEncrypter ¶
func NewEncrypter(enc ContentEncryption, rcpt Recipient, opts *EncrypterOptions) (Encrypter, error)
NewEncrypter creates an appropriate encrypter based on the key type
Example (PublicKey) ¶
var publicKey *rsa.PublicKey // Instantiate an encrypter using RSA-OAEP with AES128-GCM. NewEncrypter(A128GCM, Recipient{Algorithm: RSA_OAEP, Key: publicKey}, nil) // Instantiate an encrypter using RSA-PKCS1v1.5 with AES128-CBC+HMAC. NewEncrypter(A128CBC_HS256, Recipient{Algorithm: RSA1_5, Key: publicKey}, nil)
Output:
Example (Symmetric) ¶
var sharedKey []byte // Instantiate an encrypter using AES128-GCM with AES-GCM key wrap. NewEncrypter(A128GCM, Recipient{Algorithm: A128GCMKW, Key: sharedKey}, nil) // Instantiate an encrypter using AES128-GCM directly, w/o key wrapping. NewEncrypter(A128GCM, Recipient{Algorithm: DIRECT, Key: sharedKey}, nil)
Output:
func NewMultiEncrypter ¶
func NewMultiEncrypter(enc ContentEncryption, rcpts []Recipient, opts *EncrypterOptions) (Encrypter, error)
NewMultiEncrypter creates a multi-encrypter based on the given parameters
Example ¶
var publicKey *rsa.PublicKey var sharedKey []byte // Instantiate an encrypter using AES-GCM. NewMultiEncrypter(A128GCM, []Recipient{ {Algorithm: A128GCMKW, Key: sharedKey}, {Algorithm: RSA_OAEP, Key: publicKey}, }, nil)
Output:
type EncrypterOptions ¶
type EncrypterOptions struct { Compression CompressionAlgorithm // Optional map of name/value pairs to be inserted into the protected // header of a JWS object. Some specifications which make use of // JWS require additional values here. // // Values will be serialized by [json.Marshal] and must be valid inputs to // that function. // // [json.Marshal]: https://pkg.go.dev/encoding/json#Marshal 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, and returns the updated EncrypterOptions.
The v parameter will be serialized by json.Marshal and must be a valid input to that function.
func (*EncrypterOptions) WithType ¶
func (eo *EncrypterOptions) WithType(typ ContentType) *EncrypterOptions
WithType adds a type ("typ") header and returns the updated EncrypterOptions.
type Header ¶
type Header struct { KeyID string JSONWebKey *JSONWebKey Algorithm string Nonce string // At parse time, each header parameter with a name other than "kid", // "jwk", "alg", "nonce", or "x5c" will have its value passed to // [json.Unmarshal] to unmarshal it into an interface value. // The resulting value will be stored in this map, with the header // parameter name as the key. // // [json.Unmarshal]: https://pkg.go.dev/encoding/json#Unmarshal 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, keyEncryptionAlgorithms []KeyAlgorithm, contentEncryption []ContentEncryption, ) (*JSONWebEncryption, error)
ParseEncrypted parses an encrypted message in JWE Compact or JWE JSON Serialization.
https://datatracker.ietf.org/doc/html/rfc7516#section-3.1 https://datatracker.ietf.org/doc/html/rfc7516#section-3.2
The keyAlgorithms and contentEncryption parameters are used to validate the "alg" and "enc" header parameters respectively. They must be nonempty, and each "alg" or "enc" header in parsed data must contain a value that is present in the corresponding parameter. That includes the protected and unprotected headers as well as all recipients. To accept multiple algorithms, pass a slice of all the algorithms you want to accept.
func ParseEncryptedCompact ¶
func ParseEncryptedCompact( input string, keyAlgorithms []KeyAlgorithm, contentEncryption []ContentEncryption, ) (*JSONWebEncryption, error)
ParseEncryptedCompact parses a message in JWE Compact Serialization.
func ParseEncryptedJSON ¶
func ParseEncryptedJSON( input string, keyEncryptionAlgorithms []KeyAlgorithm, contentEncryption []ContentEncryption, ) (*JSONWebEncryption, error)
ParseEncryptedJSON parses a message in JWE JSON Serialization.
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. This function does not support multi-recipient. If you desire multi-recipient decryption use DecryptMulti instead.
The decryptionKey argument must contain a private or symmetric key and must have one of these types:
- *ecdsa.PrivateKey
- *rsa.PrivateKey
- *JSONWebKey
- JSONWebKey
- *JSONWebKeySet
- JSONWebKeySet
- []byte (a symmetric key)
- string (a symmetric key)
- Any type that satisfies the OpaqueKeyDecrypter interface.
Note that ed25519 is only available for signatures, not encryption, so is not an option here.
Automatically decompresses plaintext, but returns an error if the decompressed data would be >250kB or >10x the size of the compressed data, whichever is larger.
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.
The decryptionKey argument must have one of the types allowed for the decryptionKey argument of Decrypt().
Automatically decompresses plaintext, but returns an error if the decompressed data would be >250kB or >3x the size of the compressed data, whichever is larger.
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 { // Key is the Go in-memory representation of this key. It must have one // of these types: // - ed25519.PublicKey // - ed25519.PrivateKey // - *ecdsa.PublicKey // - *ecdsa.PrivateKey // - *rsa.PublicKey // - *rsa.PrivateKey // - []byte (a symmetric key) // // When marshaling this JSONWebKey into JSON, the "kty" header parameter // will be automatically set based on the type of this field. 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. It can be marshaled into JSON and unmarshaled from JSON.
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, signatureAlgorithms []SignatureAlgorithm, ) (*JSONWebSignature, error)
ParseDetached parses a signed message in compact serialization format with detached payload.
func ParseSigned ¶
func ParseSigned( signature string, signatureAlgorithms []SignatureAlgorithm, ) (*JSONWebSignature, error)
ParseSigned parses a signed message in JWS Compact or JWS JSON Serialization.
func ParseSignedCompact ¶
func ParseSignedCompact( signature string, signatureAlgorithms []SignatureAlgorithm, ) (*JSONWebSignature, error)
ParseSignedCompact parses a message in JWS Compact Serialization.
func ParseSignedJSON ¶
func ParseSignedJSON( input string, signatureAlgorithms []SignatureAlgorithm, ) (*JSONWebSignature, error)
ParseSignedJSON parses a message in JWS JSON Serialization.
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.
The verificationKey argument must have one of the types allowed for the verificationKey argument of JSONWebSignature.Verify().
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.
The verificationKey argument must have one of the types allowed for the verificationKey argument of JSONWebSignature.Verify().
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-signature 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.
The verificationKey argument must have one of these types:
- ed25519.PublicKey
- *ecdsa.PublicKey
- *rsa.PublicKey
- *JSONWebKey
- JSONWebKey
- *JSONWebKeySet
- JSONWebKeySet
- []byte (an HMAC key)
- Any type that implements the OpaqueVerifier interface.
If the key is an HMAC key, it must have at least as many bytes as the relevant hash output:
- HS256: 32 bytes
- HS384: 48 bytes
- HS512: 64 bytes
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.
The verificationKey argument must have one of the types allowed for the verificationKey argument of JSONWebSignature.Verify().
type NonceSource ¶
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.
Note: this cannot currently be implemented outside this package because of its unexported method.
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 must have one of these types: // - ed25519.PublicKey // - *ecdsa.PublicKey // - *rsa.PublicKey // - *JSONWebKey // - JSONWebKey // - []byte (a symmetric key) // - Any type that satisfies the OpaqueKeyEncrypter interface // // The type of Key must match the value of Algorithm. 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
Example ¶
var privateKey *rsa.PrivateKey var sharedKey []byte // Instantiate a signer for multiple recipients. NewMultiSigner([]SigningKey{ {Algorithm: HS256, Key: sharedKey}, {Algorithm: PS384, Key: privateKey}, }, nil)
Output:
func NewSigner ¶
func NewSigner(sig SigningKey, opts *SignerOptions) (Signer, error)
NewSigner creates an appropriate signer based on the key type
Example (PublicKey) ¶
var rsaPrivateKey *rsa.PrivateKey var ecdsaPrivateKey *ecdsa.PrivateKey // Instantiate a signer using RSA-PKCS#1v1.5 with SHA-256. NewSigner(SigningKey{Algorithm: RS256, Key: rsaPrivateKey}, nil) // Instantiate a signer using ECDSA with SHA-384. NewSigner(SigningKey{Algorithm: ES384, Key: ecdsaPrivateKey}, nil)
Output:
Example (Symmetric) ¶
var sharedKey []byte // Instantiate an signer using HMAC-SHA256. NewSigner(SigningKey{Algorithm: HS256, Key: sharedKey}, nil) // Instantiate an signer using HMAC-SHA512. NewSigner(SigningKey{Algorithm: HS512, Key: sharedKey}, nil)
Output:
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. // // Values will be serialized by [json.Marshal] and must be valid inputs to // that function. // // [json.Marshal]: https://pkg.go.dev/encoding/json#Marshal 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, and returns the updated SignerOptions.
The v argument will be serialized by json.Marshal and must be a valid input to that function.
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.
Key must have one of these types:
- ed25519.PrivateKey
- *ecdsa.PrivateKey
- *rsa.PrivateKey
- *JSONWebKey
- JSONWebKey
- []byte (an HMAC key)
- Any type that satisfies the OpaqueSigner interface
If the key is an HMAC key, it must have at least as many bytes as the relevant hash output:
- HS256: 32 bytes
- HS384: 48 bytes
- HS512: 64 bytes
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package cryptosigner implements an OpaqueSigner that wraps a "crypto".Signer
|
Package cryptosigner implements an OpaqueSigner that wraps a "crypto".Signer |
Package json implements encoding and decoding of JSON objects as defined in RFC 4627.
|
Package json implements encoding and decoding of JSON objects as defined in RFC 4627. |
Package jwt provides an implementation of the JSON Web Token standard.
|
Package jwt provides an implementation of the JSON Web Token standard. |