jws

package
v0.9.1 Latest Latest
Warning

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

 Go to latest Published: Dec 6, 2021 License: MIT Imports: 14 Imported by: 19

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

Source Files

View all Source files

Directories

Path Synopsis
internal
cmd/genheader

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.