Documentation

Overview

    Package jws implements the digital signature on JSON based data structures as described in https://tools.ietf.org/html/rfc7515

    If you do not care about the details, the only things that you would need to use are the following functions:

    jws.Sign(payload, algorithm, key)
    jws.Verify(encodedjws, algorithm, key)
    

    To sign, simply use `jws.Sign`. `payload` is a []byte buffer that contains whatever data you want to sign. `alg` is one of the jwa.SignatureAlgorithm constants from package jwa. For RSA and ECDSA family of algorithms, you will need to prepare a private key. For HMAC family, you just need a []byte value. The `jws.Sign` function will return the encoded JWS message on success.

    To verify, use `jws.Verify`. It will parse the `encodedjws` buffer and verify the result using `algorithm` and `key`. Upon successful verification, the original payload is returned, so you can work on it.

    Index

    Constants

    View Source
    const (
    	AlgorithmKey              = "alg"
    	ContentTypeKey            = "cty"
    	CriticalKey               = "crit"
    	JWKKey                    = "jwk"
    	JWKSetURLKey              = "jku"
    	KeyIDKey                  = "kid"
    	TypeKey                   = "typ"
    	X509CertChainKey          = "x5c"
    	X509CertThumbprintKey     = "x5t"
    	X509CertThumbprintS256Key = "x5t#S256"
    	X509URLKey                = "x5u"
    )

    Variables

    View Source
    var DefaultJWKAcceptor = JWKAcceptFunc(func(key jwk.Key) bool {
    	if u := key.KeyUsage(); u != "" && u != "enc" && u != "sig" {
    		return false
    	}
    	return true
    })

      DefaultJWKAcceptor is the default acceptor that is used in functions like VerifyWithJWKSet

      Functions

      func Sign

      func Sign(payload []byte, alg jwa.SignatureAlgorithm, key interface{}, options ...Option) ([]byte, error)

        Sign generates a signature for the given payload, and serializes it in compact serialization format. In this format you may NOT use multiple signers.

        If you would like to pass custom headers, use the WithHeaders option.

        func SignMulti

        func SignMulti(payload []byte, options ...Option) ([]byte, error)

          SignMulti accepts multiple signers via the options parameter, and creates a JWS in JSON serialization format that contains signatures from applying aforementioned signers.

          func SplitCompact

          func SplitCompact(rdr io.Reader) ([]byte, []byte, []byte, error)

            splitCompact

            func Verify

            func Verify(buf []byte, alg jwa.SignatureAlgorithm, key interface{}) (ret []byte, err error)

              Verify checks if the given JWS message is verifiable using `alg` and `key`. If the verification is successful, `err` is nil, and the content of the payload that was signed is returned. If you need more fine-grained control of the verification process, manually call `Parse`, generate a verifier, and call `Verify` on the parsed JWS message object.

              func VerifyWithJKU

              func VerifyWithJKU(buf []byte, jwkurl string) ([]byte, error)

                VerifyWithJKU verifies the JWS message using a remote JWK file represented in the url.

                func VerifyWithJWK

                func VerifyWithJWK(buf []byte, key jwk.Key) (payload []byte, err error)

                  VerifyWithJWK verifies the JWS message using the specified JWK

                  func VerifyWithJWKSet

                  func VerifyWithJWKSet(buf []byte, keyset *jwk.Set, keyaccept JWKAcceptFunc) (payload []byte, err error)

                    VerifyWithJWKSet verifies the JWS message using JWK key set. By default it will only pick up keys that have the "use" key set to either "sig" or "enc", but you can override it by providing a keyaccept function.

                    Types

                    type EncodedMessage

                    type EncodedMessage struct {
                    	Payload    string              `json:"payload"`
                    	Signatures []*EncodedSignature `json:"signatures,omitempty"`
                    }

                    type EncodedMessageUnmarshalProxy

                    type EncodedMessageUnmarshalProxy struct {
                    	Payload    string                            `json:"payload"`
                    	Signatures []*EncodedSignatureUnmarshalProxy `json:"signatures,omitempty"`
                    }

                    type EncodedSignature

                    type EncodedSignature struct {
                    	Protected string  `json:"protected,omitempty"`
                    	Headers   Headers `json:"header,omitempty"`
                    	Signature string  `json:"signature,omitempty"`
                    }

                    type EncodedSignatureUnmarshalProxy

                    type EncodedSignatureUnmarshalProxy struct {
                    	Protected string           `json:"protected,omitempty"`
                    	Headers   *StandardHeaders `json:"header,omitempty"`
                    	Signature string           `json:"signature,omitempty"`
                    }

                    type FullEncodedMessage

                    type FullEncodedMessage struct {
                    	*EncodedSignature // embedded to pick up flattened JSON message
                    	*EncodedMessage
                    }

                    type FullEncodedMessageUnmarshalProxy

                    type FullEncodedMessageUnmarshalProxy struct {
                    	*EncodedSignatureUnmarshalProxy // embedded to pick up flattened JSON message
                    	*EncodedMessageUnmarshalProxy
                    }

                    type Headers

                    type Headers interface {
                    	Get(string) (interface{}, bool)
                    	Set(string, interface{}) error
                    	Algorithm() jwa.SignatureAlgorithm
                    	ContentType() string
                    	Critical() []string
                    	JWK() jwk.Key
                    	JWKSetURL() string
                    	KeyID() string
                    	Type() string
                    	X509CertChain() []string
                    	X509CertThumbprint() string
                    	X509CertThumbprintS256() string
                    	X509URL() string
                    }

                    type JWKAcceptFunc

                    type JWKAcceptFunc func(jwk.Key) bool

                      JWKAcceptFunc is an implementation of JWKAcceptor using a plain function

                      func (JWKAcceptFunc) Accept

                      func (f JWKAcceptFunc) Accept(key jwk.Key) bool

                        Accept executes the provided function to determine if the given key can be used

                        type JWKAcceptor

                        type JWKAcceptor interface {
                        	Accept(jwk.Key) bool
                        }

                          JWKAcceptor decides which keys can be accepted by functions that iterate over a JWK key set.

                          type Message

                          type Message struct {
                          	// contains filtered or unexported fields
                          }

                            Message represents a full JWS encoded message. Flattened serialization is not supported as a struct, but rather it's represented as a Message struct with only one `signature` element.

                            Do not expect to use the Message object to verify or construct a signed payloads with. You should only use this when you want to actually want to programatically view the contents for the full JWS payload.

                            To sign and verify, use the appropriate `Sign()` nad `Verify()` functions

                            func Parse

                            func Parse(src io.Reader) (m *Message, err error)

                              Parse parses contents from the given source and creates a jws.Message struct. The input can be in either compact or full JSON serialization.

                              func ParseString

                              func ParseString(s string) (*Message, error)

                                ParseString is the same as Parse, but take in a string

                                func (Message) LookupSignature

                                func (m Message) LookupSignature(kid string) []*Signature

                                  LookupSignature looks up a particular signature entry using the `kid` value

                                  func (Message) Payload

                                  func (m Message) Payload() []byte

                                  func (Message) Signatures

                                  func (m Message) Signatures() []*Signature

                                  type Option

                                  type Option = option.Interface

                                  func WithHeaders

                                  func WithHeaders(h Headers) Option

                                  func WithPretty

                                  func WithPretty(b bool) Option

                                  func WithSigner

                                  func WithSigner(signer sign.Signer, key interface{}, public, protected Headers) Option

                                  type PayloadSigner

                                  type PayloadSigner interface {
                                  	Sign([]byte) ([]byte, error)
                                  	Algorithm() jwa.SignatureAlgorithm
                                  	ProtectedHeader() Headers
                                  	PublicHeader() Headers
                                  }

                                    PayloadSigner generates signature for the given payload

                                    type Signature

                                    type Signature struct {
                                    	// contains filtered or unexported fields
                                    }

                                    func (Signature) ProtectedHeaders

                                    func (s Signature) ProtectedHeaders() Headers

                                    func (Signature) PublicHeaders

                                    func (s Signature) PublicHeaders() Headers

                                    func (Signature) Signature

                                    func (s Signature) Signature() []byte

                                    type StandardHeaders

                                    type StandardHeaders struct {
                                    	// contains filtered or unexported fields
                                    }

                                    func (*StandardHeaders) Algorithm

                                    func (h *StandardHeaders) Algorithm() jwa.SignatureAlgorithm

                                    func (*StandardHeaders) ContentType

                                    func (h *StandardHeaders) ContentType() string

                                    func (*StandardHeaders) Critical

                                    func (h *StandardHeaders) Critical() []string

                                    func (*StandardHeaders) Get

                                    func (h *StandardHeaders) Get(name string) (interface{}, bool)

                                    func (*StandardHeaders) JWK

                                    func (h *StandardHeaders) JWK() jwk.Key

                                    func (*StandardHeaders) JWKSetURL

                                    func (h *StandardHeaders) JWKSetURL() string

                                    func (*StandardHeaders) KeyID

                                    func (h *StandardHeaders) KeyID() string

                                    func (StandardHeaders) MarshalJSON

                                    func (h StandardHeaders) MarshalJSON() ([]byte, error)

                                    func (*StandardHeaders) Set

                                    func (h *StandardHeaders) Set(name string, value interface{}) error

                                    func (*StandardHeaders) Type

                                    func (h *StandardHeaders) Type() string

                                    func (*StandardHeaders) UnmarshalJSON

                                    func (h *StandardHeaders) UnmarshalJSON(buf []byte) error

                                    func (*StandardHeaders) X509CertChain

                                    func (h *StandardHeaders) X509CertChain() []string

                                    func (*StandardHeaders) X509CertThumbprint

                                    func (h *StandardHeaders) X509CertThumbprint() string

                                    func (*StandardHeaders) X509CertThumbprintS256

                                    func (h *StandardHeaders) X509CertThumbprintS256() string

                                    func (*StandardHeaders) X509URL

                                    func (h *StandardHeaders) X509URL() string

                                    Directories

                                    Path Synopsis
                                    internal