jws

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.SignWithOption(Payload, algorithm, key)
jws.Verify(encodedjws, algorithm, key)

To sign, simply use `jws.SignWithOption`. `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.SignWithOption` 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
• func SignLiteral(payload []byte, alg jwa.SignatureAlgorithm, key interface{}, hdrBuf []byte, ...) ([]byte, error)
• func SignWithOption(payload []byte, alg jwa.SignatureAlgorithm, key interface{}) ([]byte, error)
• func SplitCompact(jwsCompact string) ([]string, error)
• func Verify(buf []byte, alg jwa.SignatureAlgorithm, key interface{}) (ret []byte, err error)
• func VerifyWithJWK(buf []byte, key jwk.Key) (payload []byte, err error)
• func VerifyWithJWKSet(buf []byte, keyset *jwk.Set) (payload []byte, err error)
• type Headers
• type Message
  • func ParseByte(jwsCompact []byte) (m *Message, err error)
  • func ParseString(s string) (*Message, error)
  • func (m Message) GetPayload() []byte
  • func (m Message) GetSignatures() []*Signature
• type Signature
  • func (s Signature) GetSignature() []byte
  • func (s Signature) ProtectedHeaders() Headers
  • func (s Signature) PublicHeaders() Headers
• type StandardHeaders
  • func (h *StandardHeaders) Get(name string) (interface{}, bool)
  • func (h *StandardHeaders) GetAlgorithm() jwa.SignatureAlgorithm
  • func (h *StandardHeaders) Set(name string, value interface{}) error

Constants

const (
	AlgorithmKey     = "alg"
	ContentTypeKey   = "cty"
	CriticalKey      = "crit"
	JWKKey           = "jwk"
	JWKSetURLKey     = "jku"
	KeyIDKey         = "kid"
	PrivateParamsKey = "privateParams"
	TypeKey          = "typ"
)

Constants for JWS Common parameters

Functions

func SignLiteral

func SignLiteral(payload []byte, alg jwa.SignatureAlgorithm, key interface{}, hdrBuf []byte, rnd io.Reader) ([]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 SignWithOption

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

SignWithOption 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 SplitCompact

func SplitCompact(jwsCompact string) ([]string, 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 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) (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 Headers

type Headers interface {
	Get(string) (interface{}, bool)
	Set(string, interface{}) error
	GetAlgorithm() jwa.SignatureAlgorithm
}

Headers provides a common interface for common header parameters

type Message

type Message struct {
	Payload    []byte       `json:"payload"`
	Signatures []*Signature `json:"signatures,omitempty"`
}

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 `SignWithOption()` nad `Verify()` functions

func ParseByte

func ParseByte(jwsCompact []byte) (m *Message, err error)

ParseByte parses a JWS value serialized via compact serialization and provided as []byte.

func ParseString

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

ParseString parses a JWS value serialized via compact serialization and provided as string.

func (Message) GetPayload

func (m Message) GetPayload() []byte

GetPayload returns the payload in a JWS

func (Message) GetSignatures

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

GetSignatures returns the all signatures in a JWS

type Signature

type Signature struct {
	Headers   Headers `json:"header,omitempty"`    // Unprotected Headers
	Protected Headers `json:"Protected,omitempty"` // Protected Headers
	Signature []byte  `json:"signature,omitempty"` // GetSignature
}

Signature represents the headers and signature of a JWS message

func (Signature) GetSignature

func (s Signature) GetSignature() []byte

GetSignature returns the signature in a JWS

func (Signature) ProtectedHeaders

func (s Signature) ProtectedHeaders() Headers

ProtectedHeaders returns the protected headers in a JWS

func (Signature) PublicHeaders

func (s Signature) PublicHeaders() Headers

PublicHeaders returns the public headers in a JWS

type StandardHeaders

type StandardHeaders struct {
	Algorithm     jwa.SignatureAlgorithm `json:"alg,omitempty"`           // https://tools.ietf.org/html/rfc7515#section-4.1.1
	ContentType   string                 `json:"cty,omitempty"`           // https://tools.ietf.org/html/rfc7515#section-4.1.10
	Critical      []string               `json:"crit,omitempty"`          // https://tools.ietf.org/html/rfc7515#section-4.1.11
	JWK           string                 `json:"jwk,omitempty"`           // https://tools.ietf.org/html/rfc7515#section-4.1.3
	JWKSetURL     string                 `json:"jku,omitempty"`           // https://tools.ietf.org/html/rfc7515#section-4.1.2
	KeyID         string                 `json:"kid,omitempty"`           // https://tools.ietf.org/html/rfc7515#section-4.1.4
	PrivateParams map[string]interface{} `json:"privateParams,omitempty"` // https://tools.ietf.org/html/rfc7515#section-4.1.9
	Type          string                 `json:"typ,omitempty"`           // https://tools.ietf.org/html/rfc7515#section-4.1.9
}

StandardHeaders contains JWS common parameters.

func (*StandardHeaders) Get

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

Get is a general getter function for StandardHeaders structure

func (*StandardHeaders) GetAlgorithm

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

GetAlgorithm returns algorithm

func (*StandardHeaders) Set

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

Set is a general setter function for StandardHeaders structure