ps

README

RSA-PSS Signature Provider

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

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

How to initialize

const (
	PS256 = 1
	PS384 = 2
	PS512 = 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 PKCS1 private key) and then calling LoadProvider with the settings.

The provider has to be registered using the name PSxxx 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 (
	// PS256 is RSASSA-PSS using SHA-256 and MGF1 with SHA-256
	PS256 = 1

	// PS384 is RSASSA-PSS using SHA-384 and MGF1 with SHA-384
	PS384 = 2

	// PS512 is RSASSA-PSS using SHA-512 and MGF1 with SHA-512
	PS512 = 3
)

Types

type Provider

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

Provider provides RSASSA-PSS using SHA2 and MGF1 with 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.

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