hs

README

HMAC-SHA2 Signature Provider

Test coverage: Fully tested using unit tests and integration tests. No static tests of signing and verification. Signing and verification manually validated against jwt.io.

This package implements a verification and siging provider using the HMAC-SHA2 algorithms for JWT / JWS as specified in RFC 7518.

How to initialize

const (
	HS256 = 1
	HS384 = 2
	HS512 = 3
)

NewProvider(algorithm int) (Provider, error)
NewProviderWithKeyURL(algorithm int, keyURL string) (Provider, error)

NewSettings(key []byte, keyID string) (Settings, error)
NewSettingsWithKeyURL(key []byte, keyID, keyURL string) (Settings, error)
LoadProvider(settings Settings, algorithm int) (Provider, error)

There are two ways to initialize this package:

• Generate a new key using NewProvider which optionally may also include a key URL. Note that you will need to upload the public key to the key store manually.
• Load an existing key by creating a new Settings struct using NewSettings supplying the key as a byte slice (not encoded) and then calling LoadProvider with the settings.

The provider has to be registered using the name HSxxx to be compliant with RFC 7518. It will be able to sign and verify keys for the specified byte size only.

Managing public keys

provider.CurrentKey() publickey.PublicKey

provider.AddPublicKey(key publickey.PublicKey) error
provider.RemovePublicKey(keyID string)

To retrieve the signing / verification key, use provider.CurrentKey.

Important: Do not publish this key as it is used for both signing and verification.

Adding a public key is done via provider.AddPublicKey while removing works via provider.RemovePublicKey.

Documentation

Index

• Constants
• type Provider
  • func LoadProvider(s Settings, t int) (Provider, error)
  • func NewProvider(t int) (Provider, error)
  • func NewProviderWithKeyURL(t int, keyURL string) (Provider, error)
  • func (p *Provider) AddPublicKey(key publickey.PublicKey) error
  • func (p Provider) CurrentKey() publickey.PublicKey
  • func (p Provider) Header(h *jwt.Header)
  • func (p *Provider) RemovePublicKey(keyid string)
  • func (p Provider) Sign(c []byte) ([]byte, error)
  • func (p Provider) Verify(data, sig []byte, h jwt.Header) error
• type Settings
  • func NewSettings(key []byte, keyID string) (Settings, error)
  • func NewSettingsWithKeyURL(key []byte, keyID, keyURL string) (Settings, error)

Constants

const (
	// HS256 is HMAC-SHA256
	HS256 = 1

	// HS384 is HMAC-SHA384
	HS384 = 2

	// HS512 is HMAC-SHA512
	HS512 = 3
)

Types

type Provider

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

Provider provides HMAC-SHA2 JWS signing and verification

func LoadProvider

func LoadProvider(s Settings, t int) (Provider, error)

LoadProvider returns a Provider using the supplied keypairs

func NewProvider

func NewProvider(t int) (Provider, error)

NewProvider creates a new Provider generating the necessary keypairs

func NewProviderWithKeyURL

func NewProviderWithKeyURL(t int, keyURL string) (Provider, error)

NewProviderWithKeyURL works just like NewProvider but also sets the key URL of the generated keys

func (*Provider) AddPublicKey

func (p *Provider) AddPublicKey(key publickey.PublicKey) error

AddPublicKey adds a public key for verification

func (Provider) CurrentKey

func (p Provider) CurrentKey() publickey.PublicKey

CurrentKey returns the public key belonging to the private key used for signing. CAUTION: The public and private key are the same for this algorithm. Do not share the key you obtain using this function

func (Provider) Header

func (p Provider) Header(h *jwt.Header)

Header sets the necessary JWT header fields

func (*Provider) RemovePublicKey

func (p *Provider) RemovePublicKey(keyid string)

RemovePublicKey removes a public key by it's key ID from the verification set

func (Provider) Sign

func (p Provider) Sign(c []byte) ([]byte, error)

Sign signs the content of a JWT

func (Provider) Verify

func (p Provider) Verify(data, sig []byte, h jwt.Header) error

Verify verifies if the content matches it's signature.

type Settings

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

Settings stores the key for an algorithm

func NewSettings

func NewSettings(key []byte, keyID string) (Settings, error)

NewSettings creates new signature settings for the parameters

func NewSettingsWithKeyURL

func NewSettingsWithKeyURL(key []byte, keyID, keyURL string) (Settings, error)

NewSettingsWithKeyURL creates new signature settings for the parameters