es

README

ECDSA 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 ECDSA algorithms for JWT / JWS as specified in RFC 7518.

How to initialize

const (
	ES256 = 1
	ES384 = 2
	ES512 = 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 (encoded as PKCS8 or EC private key) and then calling LoadProvider with the settings.

The provider has to be registered using the name ESxxx 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 public key corresponding to the private key used for signing, use provider.CurrentKey.

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 (
	// ES256 is ECDSA using P-256 and SHA-256
	ES256 = 1

	// ES384 is ECDSA using P-384 and SHA-384
	ES384 = 2

	// ES512 is ECDSA using P-521 and SHA-512
	ES512 = 3
)

Types

type Provider

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

Provider provides ECDSA using the NIST curves and SHA2 for JWS signing and verification

func LoadProvider

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

LoadProvider returns a Provider using the supplied settings. The public key will be ignored as the settings include all necessary information.

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

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 signature settings for an EdDSA curve

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