Documentation ¶
Overview ¶
Package jws contains implementations of the JSON Web Signatures (jws) defined in RFC 7517 (https://datatracker.ietf.org/doc/html/rfc7517) as well as parts from JSON Web Algorithms (jwa) as defined in RFC 7518 (https://www.rfc-editor.org/rfc/rfc7518.html)
Example ¶
package main import ( "fmt" "github.com/halimath/jose/jws" ) func main() { signatureMethod := jws.HS256([]byte("secret")) sig, err := jws.Sign(signatureMethod, []byte("hello, world"), jws.Header{}) if err != nil { panic(err) } compact := sig.Compact() fmt.Println(compact) sig2, err := jws.ParseCompact(compact) if err != nil { panic(err) } fmt.Println(string(sig2.Payload())) }
Output: eyJhbGciOiJIUzI1NiJ9.aGVsbG8sIHdvcmxk.4BeqMvZFJ1IIIpDSQhXK05lFaJ5k9G39y7CNs8xdfjI hello, world
Index ¶
- Variables
- type HMACSignerVerifier
- type Header
- type JWS
- type SignatureAlgorithm
- type Signer
- func ES256Signer(privateKey *ecdsa.PrivateKey) (Signer, error)
- func ES384Signer(privateKey *ecdsa.PrivateKey) (Signer, error)
- func ES512Signer(privateKey *ecdsa.PrivateKey) (Signer, error)
- func RS256Signer(privateKey *rsa.PrivateKey) Signer
- func RS384Signer(privateKey *rsa.PrivateKey) Signer
- func RS512Signer(privateKey *rsa.PrivateKey) Signer
- type SignerVerifier
- type Verifier
- func ES256Verifier(publicKey *ecdsa.PublicKey) (Verifier, error)
- func ES384Verifier(publicKey *ecdsa.PublicKey) (Verifier, error)
- func ES512Verifier(publicKey *ecdsa.PublicKey) (Verifier, error)
- func RS256Verifier(publicKey *rsa.PublicKey) Verifier
- func RS384Verifier(publicKey *rsa.PublicKey) Verifier
- func RS512Verifier(publicKey *rsa.PublicKey) Verifier
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidCompactJWS is returned when a given string is not a valid JWS in compact serialized form. ErrInvalidCompactJWS = errors.New("invalid compact JWS") ErrInvalidHeader = errors.New("invalid header") )
var ( // ErrInvalidSignature is returned from VerifySignature when the signature is not considered valid. ErrInvalidSignature = errors.New("invalid signature") )
Functions ¶
This section is empty.
Types ¶
type HMACSignerVerifier ¶
type HMACSignerVerifier struct {
// contains filtered or unexported fields
}
HMACSignerVerifier implements a signature method using a HMAC with a pre-shared secret.
func (*HMACSignerVerifier) Alg ¶
func (h *HMACSignerVerifier) Alg() SignatureAlgorithm
type Header ¶
type Header struct { Algorithm SignatureAlgorithm `json:"alg"` Type string `json:"typ,omitempty"` }
Header defines the structure representing a JWS JOSE header as defined in RFC7515 section 4 (https://datatracker.ietf.org/doc/html/rfc7515#section-4). This implementation has no support for private header parameters.
func DecodeHeader ¶
type JWS ¶
type JWS struct {
// contains filtered or unexported fields
}
JWS implements a JSON Web Signature datastructure. The fields of this struct represent the different components of a JWS in multiple ways. Once created a JWS is immutable. A JWS may only be created through functions exposed from this package, i.e.
func Sign(signatureMethod SignatureMethod, payload []byte, header Header) JWS func ParseCompact(compact string) (*JWS, error)
func ParseCompact ¶
ParseCompact parses the given compact representation into a JWS datastructure and returns it. It performs only a syntactically validation of base64 URL encoded data as well as parsing the JOSE header JSON. The signature ist NOT verified. Use Verify to perform the verification.
func Sign ¶
Sign signs the given payload and header with the given signature method. It returns a JWS value containing the raw and encoded parts as well as the signature.
func (*JWS) Compact ¶
Compact returns the JWS in compact serialization as specified in RFC 7515 section 7.1 (https://datatracker.ietf.org/doc/html/rfc7515#section-7.1)
func (*JWS) VerifySignature ¶
Verify verifies that the signature t carries has zero length.
type SignatureAlgorithm ¶
type SignatureAlgorithm string
SignatureAlgorithm defines the type used to name algorithms creating digital signature including MACs.
const ( // ECDSA using P-256 and SHA-256 ALG_ES256 SignatureAlgorithm = "ES256" // ECDSA using P-384 and SHA-384 ALG_ES384 SignatureAlgorithm = "ES384" // ECDSA using P-521 and SHA-512 ALG_ES512 SignatureAlgorithm = "ES512" )
const ( ALG_HS256 SignatureAlgorithm = "HS256" ALG_HS384 SignatureAlgorithm = "HS384" ALG_HS512 SignatureAlgorithm = "HS512" )
const ( // RSASSA-PKCS1-v1_5 using SHA-256 ALG_RS256 SignatureAlgorithm = "RS256" // RSASSA-PKCS1-v1_5 using SHA-384 ALG_RS384 SignatureAlgorithm = "RS384" // RSASSA-PKCS1-v1_5 using SHA-512 ALG_RS512 SignatureAlgorithm = "RS512" )
const (
ALG_NONE SignatureAlgorithm = "none"
)
type Signer ¶
type Signer interface { // Alg returns the name of the signature algorithm as defined in // RFC 7518 section 3.1 // (https://www.rfc-editor.org/rfc/rfc7518.html#section-3.1) Alg() SignatureAlgorithm // Sign calculates the the signature or MAC for the given // byte slice and returns the signature bytes. Sign(data []byte) ([]byte, error) }
Signer defines the interface for types implementing a given signature method for signing byte slices.
func ES256Signer ¶
func ES256Signer(privateKey *ecdsa.PrivateKey) (Signer, error)
ES256Signer creates a Signer providing ECDSA using P-256 and SHA-256 signatures using the given private key which must use ellipctic.P256() as the underlying curve.
func ES384Signer ¶
func ES384Signer(privateKey *ecdsa.PrivateKey) (Signer, error)
ES384Signer creates a Signer providing ECDSA using P-384 and SHA-384 signatures using the given private key which must use ellipctic.P384() as the underlying curve.
func ES512Signer ¶
func ES512Signer(privateKey *ecdsa.PrivateKey) (Signer, error)
ES512Signer creates a Signer providing ECDSA using P-512 and SHA-512 signatures using the given private key which must use ellipctic.P512() as the underlying curve.
func RS256Signer ¶
func RS256Signer(privateKey *rsa.PrivateKey) Signer
RS256Signer creates a new Signer using the RS256 algorithm as specified in RFC 7518 section 3.3
func RS384Signer ¶
func RS384Signer(privateKey *rsa.PrivateKey) Signer
RS384Signer creates a new Signer using the RS384 algorithm as specified in RFC 7518 section 3.3
func RS512Signer ¶
func RS512Signer(privateKey *rsa.PrivateKey) Signer
RS512Signer creates a new Signer using the RS512 algorithm as specified in RFC 7518 section 3.3
type SignerVerifier ¶
SignerVerifier is the combination of both Signer and Verifier. It is used for symmetric signatures (i.e. MACs).
func HS256 ¶
func HS256(secret []byte) SignerVerifier
HS256 creates a signature method implementing the HMAC SHA256 algorithm.
func HS384 ¶
func HS384(secret []byte) SignerVerifier
HS384 creates a signature method implementing the HMAC SHA384 algorithm.
func HS512 ¶
func HS512(secret []byte) SignerVerifier
HS512 creates a signature method implementing the HMAC SHA512 algorithm.
func None ¶
func None() SignerVerifier
None returns a signature method that creates no signature. Use this method to create unsecured JWTs as specified in RFC7519 section 6 (https://datatracker.ietf.org/doc/html/rfc7519#section-6)
func SymmetricSignature ¶
func SymmetricSignature(s Signer) SignerVerifier
SymmetricSignature creates a SignerVerifier
type Verifier ¶
type Verifier interface { // Verify is called to verify the given signature for the given data. // Implementations return nil in case of a valid signature or a non-nil error. // Implementation MUST NOT modify neither data nor signature. Verify(alg SignatureAlgorithm, data []byte, signature []byte) error }
Verifier defines the interface for types verifying signatures.
func ES256Verifier ¶
ES256Verifier creates a Verifier verifying ECDSA using P-256 and SHA-256 signatures using the given public key which must use ellipctic.P256() as the underlying curve.
func ES384Verifier ¶
ES384Verifier creates a Verifier verifying ECDSA using P-384 and SHA-384 signatures using the given public key which must use ellipctic.P384() as the underlying curve.
func ES512Verifier ¶
ES512Verifier creates a Verifier verifying ECDSA using P-512 and SHA-512 signatures using the given public key which must use ellipctic.P512() as the underlying curve.
func RS256Verifier ¶
RS256Verifier creates a Verifier for RS256 as defined in RFC 7518 section 3.3 (https://www.rfc-editor.org/rfc/rfc7518.html#section-3.3)
func RS384Verifier ¶
RS384Verifier creates a Verifier for RS384 as defined in RFC 7518 section 3.3 (https://www.rfc-editor.org/rfc/rfc7518.html#section-3.3)
func RS512Verifier ¶
RS512Verifier creates a Verifier for RS512 as defined in RFC 7518 section 3.3 (https://www.rfc-editor.org/rfc/rfc7518.html#section-3.3)