keys

Documentation

Overview

Package keys provides a signer implementation that relies on a key ring that can be rotated in a thread / instance safe manner

Index

• type BenchTime
• type DefaultSigner
  • func NewSigner(minKeyBench, keyLifetime, keepKeyFor int64, provider KeyRingProvider) (*DefaultSigner, error)
  • func (m *DefaultSigner) KeyID() (string, error)
  • func (m *DefaultSigner) PublicKeys() ([]PublicKey, int64, error)
  • func (m *DefaultSigner) Sign(keyID string, data []byte) ([]byte, error)
  • func (m *DefaultSigner) TokenLifetime() int64
• type KeepFor
• type KeyRing
  • func NewRing() *KeyRing
  • func (r *KeyRing) Cleanup(t Now, benchtime BenchTime, lifetime LifeTime, keepfor KeepFor) (err error)
  • func (r *KeyRing) Equal(other *KeyRing, ignoreExp bool) bool
  • func (r *KeyRing) IsDirty(t Now, benchtime BenchTime) bool
  • func (r *KeyRing) Key() (string, *ecdsa.PrivateKey)
  • func (r KeyRing) MarshalBinary() (_ []byte, err error)
  • func (r *KeyRing) PublicKeys() (keys []PublicKey, expireAt int64, err error)
  • func (r *KeyRing) UnmarshalBinary(data []byte) (err error)
• type KeyRingProvider
• type LifeTime
• type Now
• type PublicKey
  • func (k *PublicKey) Equal(other *PublicKey) bool
  • func (k PublicKey) MarshalBinary() ([]byte, error)
  • func (k *PublicKey) ShouldExpire(now int64) bool
  • func (k *PublicKey) UnmarshalBinary(data []byte) (err error)

Types

type BenchTime

type BenchTime int64

BenchTime is an int64 alias that represents how a key should exist before it is used

type DefaultSigner

type DefaultSigner struct {

	// MinKeyBench is the min amount of time a key is benched before become active
	MinKeyBench BenchTime
	// KeyLifetime is the delay after which a key is rotated
	KeyLifetime LifeTime
	// KeepKeyFor is the time a key is kept after it expired
	KeepKeyFor KeepFor
	// contains filtered or unexported fields
}

DefaultSigner manages rotating signature keys

Key rotation is evaluated every time the JWKS() function is called. Signing will also not occurred if the manager is not in its nominal state.

Key rotation is done so that: - key rotations operations should be triggered every time keys are retrieved or a token is signed - keys are rotated approximately every `KeyRotation`. Approximately because if a key has not been used for a while, it will be used at least once before the rotation process is triggered. This should not happen since the `JWKS()` function should be called regularly by the gateway - before a key is active, it is benched and returned by `JWKS` for at least MinKeyBench. This is so that the gateway has time to retrieve the key before using it.

func NewSigner

func NewSigner(minKeyBench, keyLifetime, keepKeyFor int64, provider KeyRingProvider) (*DefaultSigner, error)

NewSigner is the default constructor for DefaultSigner

func (*DefaultSigner) KeyID

func (m *DefaultSigner) KeyID() (string, error)

KeyID returns the active key id after ensuring everything is ok

func (*DefaultSigner) PublicKeys

func (m *DefaultSigner) PublicKeys() ([]PublicKey, int64, error)

PublicKeys returns the available public keys, it also rotates the keys if required Also returns the remaining time for which the keys will be valid

func (*DefaultSigner) Sign

func (m *DefaultSigner) Sign(keyID string, data []byte) ([]byte, error)

Sign returns a signature The provided key ID must match the one returned by KeyID()

func (*DefaultSigner) TokenLifetime

func (m *DefaultSigner) TokenLifetime() int64

TokenLifetime returns how long the key is kept after it expired

type KeepFor

type KeepFor int64

KeepFor is an int64 alias that represents how long the key should be kept after it expired

type KeyRing

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

KeyRing manages a set of keys

func NewRing

func NewRing() *KeyRing

NewRing creates a new keyring

func (*KeyRing) Cleanup

func (r *KeyRing) Cleanup(t Now, benchtime BenchTime, lifetime LifeTime, keepfor KeepFor) (err error)

Cleanup makes the keyring not dirty

func (*KeyRing) Equal

func (r *KeyRing) Equal(other *KeyRing, ignoreExp bool) bool

Equal returns true if the 2 keyrings are identical

func (*KeyRing) IsDirty

func (r *KeyRing) IsDirty(t Now, benchtime BenchTime) bool

IsDirty returns true if the key ring needs an operation

func (*KeyRing) Key

func (r *KeyRing) Key() (string, *ecdsa.PrivateKey)

Key returns the active key

func (KeyRing) MarshalBinary

func (r KeyRing) MarshalBinary() (_ []byte, err error)

MarshalBinary implmements the gob protocol

func (*KeyRing) PublicKeys

func (r *KeyRing) PublicKeys() (keys []PublicKey, expireAt int64, err error)

PublicKeys returns the public keys associated with the key ring

func (*KeyRing) UnmarshalBinary

func (r *KeyRing) UnmarshalBinary(data []byte) (err error)

UnmarshalBinary implmements the gob protocol

type KeyRingProvider

type KeyRingProvider interface {
	// Provide returns a clean key ring or an error. It is called every time the current keyring is dirty.
	// This method is called within a mutex lock so it should do its best to return fast
	Provide(*KeyRing, func() Now, BenchTime, LifeTime, KeepFor) (*KeyRing, error)
}

KeyRingProvider is an object that manages a key repository

type LifeTime

type LifeTime int64

LifeTime is an int64 alias that represents the duration for which a key can be use

type Now

type Now int64

Now is an int64 alias that represents the curren time

type PublicKey

type PublicKey struct {
	ID       string
	ExpireAt int64 `json:"-"`
	Key      *ecdsa.PublicKey
}

PublicKey holds data about a public key

func (*PublicKey) Equal

func (k *PublicKey) Equal(other *PublicKey) bool

Equal returns true if the 2 are identical

func (PublicKey) MarshalBinary

func (k PublicKey) MarshalBinary() ([]byte, error)

MarshalBinary implements the gobbing protocol

func (*PublicKey) ShouldExpire

func (k *PublicKey) ShouldExpire(now int64) bool

ShouldExpire returns true if the key should be removed

func (*PublicKey) UnmarshalBinary

func (k *PublicKey) UnmarshalBinary(data []byte) (err error)

UnmarshalBinary implements the gobbing protocol