eddsa

README

EdDSA Signature Provider

Test coverage: Fully tested using unit tests and integration tests. No static tests of signing and verification.

Important:

• Ed448 is provided by a package that is marked as unstable by it's developers so use it with care.
• Due to the limited number of implementations of RFC 8037 out there, this package is only tested against itself.

This package implements a verification and siging provider using the EdDSA algorithms for JWT / JWS as specified in RFC 8037.

How to initialize

const (
	Ed25519 = 1
	Ed448 = 2
)

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.

Important: Ed448 currently does not support the private key format defined in RFC 8032. It uses a 144 byte private key consisting of the private, public and symmetric key in that order.

The provider has to be registered using the name EdDSA to be compliant with RFC 8037. It will be able to verify signatures generated using both Ed25519 and Ed448 but can only sign using the algorithm selected on initialization.

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(settings Settings, alg int) (Provider, error)
  • func NewProvider(alg int) (Provider, error)
  • func NewProviderWithKeyURL(alg 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 (
	// Ed25519 is a twisted Edwards curve designed by Daniel J. Bernstein et. al. with a 126-bit security level.
	Ed25519 = 1
	// Ed448 is am Edwards curve designed by Mike Hamburg with a 223-bit security level. It's implementation in Go is currently not stable so use with care.
	Ed448 = 2
)

Types

type Provider

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

Provider is a struct that stores all necessary data to sign and verify EdDSA signatures

func LoadProvider

func LoadProvider(settings Settings, alg int) (Provider, error)

LoadProvider returns a Provider using the supplied keypairs

func NewProvider

func NewProvider(alg int) (Provider, error)

NewProvider creates a new Provider generating the necessary keypairs

func NewProviderWithKeyURL

func NewProviderWithKeyURL(alg 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 for the default curve

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 using the default curve

func (Provider) Verify

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

Verify verifies if the content matches it's signature. The curve to use is set by the header.

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