jws

Documentation

Overview

This file is auto-generated. DO NOT EDIT

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
• Variables
• func Sign(payload []byte, alg jwa.SignatureAlgorithm, key interface{}, options ...Option) ([]byte, error)
• func SignLiteral(payload []byte, alg jwa.SignatureAlgorithm, key interface{}, headers []byte) ([]byte, error)
• func SignMulti(payload []byte, options ...Option) ([]byte, error)
• func SplitCompact(rdr io.Reader) ([]byte, []byte, []byte, error)
• func Verify(buf []byte, alg jwa.SignatureAlgorithm, key interface{}) (ret []byte, err error)
• func VerifyWithJKU(buf []byte, jwkurl string) ([]byte, error)
• func VerifyWithJWK(buf []byte, key jwk.Key) (payload []byte, err error)
• func VerifyWithJWKSet(buf []byte, keyset *jwk.Set, keyaccept JWKAcceptFunc) (payload []byte, err error)
• type EncodedMessage
• type EncodedMessageUnmarshalProxy
• type EncodedSignature
• type EncodedSignatureUnmarshalProxy
• type FullEncodedMessage
• type FullEncodedMessageUnmarshalProxy
• type Headers
• type JWKAcceptFunc
  • func (f JWKAcceptFunc) Accept(key jwk.Key) bool
• type JWKAcceptor
• type Message
  • func Parse(src io.Reader) (m *Message, err error)
  • func ParseString(s string) (*Message, error)
  • func (m Message) LookupSignature(kid string) []*Signature
  • func (m Message) Payload() []byte
  • func (m Message) Signatures() []*Signature
• type Option
  • func WithHeaders(h Headers) Option
  • func WithSigner(signer sign.Signer, key interface{}, public, protected Headers) Option
• type PayloadSigner
• type Signature
  • func (s Signature) ProtectedHeaders() Headers
  • func (s Signature) PublicHeaders() Headers
  • func (s Signature) Signature() []byte
• type StandardHeaders
  • func (h *StandardHeaders) Algorithm() jwa.SignatureAlgorithm
  • func (h *StandardHeaders) Get(name string) (interface{}, bool)
  • func (h *StandardHeaders) Set(name string, value interface{}) error

Constants

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

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 SignLiteral

func SignLiteral(payload []byte, alg jwa.SignatureAlgorithm, key interface{}, headers []byte) ([]byte, error)

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

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 splits a JWT and returns its three parts separately: protected headers, payload and signature.

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
}

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 programmatically 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 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 {
	JWSalgorithm              jwa.SignatureAlgorithm `json:"alg,omitempty"`      // https://tools.ietf.org/html/rfc7515#section-4.1.1
	JWScontentType            string                 `json:"cty,omitempty"`      // https://tools.ietf.org/html/rfc7515#section-4.1.10
	JWScritical               []string               `json:"crit,omitempty"`     // https://tools.ietf.org/html/rfc7515#section-4.1.11
	JWSjwk                    *jwk.Set               `json:"jwk,omitempty"`      // https://tools.ietf.org/html/rfc7515#section-4.1.3
	JWSjwkSetURL              string                 `json:"jku,omitempty"`      // https://tools.ietf.org/html/rfc7515#section-4.1.2
	JWSkeyID                  string                 `json:"kid,omitempty"`      // https://tools.ietf.org/html/rfc7515#section-4.1.4
	JWStyp                    string                 `json:"typ,omitempty"`      // https://tools.ietf.org/html/rfc7515#section-4.1.9
	JWSx509CertChain          []string               `json:"x5c,omitempty"`      // https://tools.ietf.org/html/rfc7515#section-4.1.6
	JWSx509CertThumbprint     string                 `json:"x5t,omitempty"`      // https://tools.ietf.org/html/rfc7515#section-4.1.7
	JWSx509CertThumbprintS256 string                 `json:"x5t#S256,omitempty"` // https://tools.ietf.org/html/rfc7515#section-4.1.8
	JWSx509URL                string                 `json:"x5u,omitempty"`      // https://tools.ietf.org/html/rfc7515#section-4.1.5
	// contains filtered or unexported fields
}

func (*StandardHeaders) Algorithm

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

func (*StandardHeaders) Get

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

func (*StandardHeaders) Set

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