keybroker

README

Key Broker

The package core/workers/keybroker implements a background broker conmtinous retrieval of public keys from multiple different type of sources.

Configuration

The key broker will by default try to retrieve keys from sources specified in the environment. These are the available environment variables:

• JWT_PUBLIC_KEY the key as a string
• JWT_PUBLIC_KEY_URL the http url where the key can be retrieved
• JWT_PUBLIC_KEY_PATH the file path on disk where the key can be read

You can also put your key on the location /usr/local/var/jwt.pub and it will by default attempt to read it.

Examples

broker := keybroker.NewPublicRSA(&keybroker.Config{
    Source:   keybroker.JWTPublicKeySources,
    Interval: 5 * time.Second,
})

// Run the broker
go broker.Run(ctx)

// Queue retrieval of new key
broker.Renew()

// Copy the current public key held by the broker
broker.Copy()

Documentation

Overview

Package keybroker implements a background broker conmtinous retrieval of public keys from multiple different type of sources.

Example

package main

import (
	"context"
	"time"

	"github.com/LUSHDigital/core/workers/keybroker"
)

var ctx context.Context

func main() {
	broker := keybroker.NewPublicRSA(&keybroker.Config{
		Source:   keybroker.JWTPublicKeySources,
		Interval: 5 * time.Second,
	})

	// Run the broker
	go broker.Run(ctx)

	// Queue retrieval of new key
	broker.Renew()

	// Copy the current public key held by the broker
	broker.Copy()
}

Index

• Variables
• type Closer
• type Config
• type EnvFileSource
  • func (source EnvFileSource) Get(ctx context.Context) ([]byte, error)
• type EnvHTTPSource
  • func (source EnvHTTPSource) Get(ctx context.Context) ([]byte, error)
• type EnvStringSource
  • func (source EnvStringSource) Get(ctx context.Context) ([]byte, error)
• type ErrGetKeySource
  • func (e ErrGetKeySource) Error() string
• type ErrNoSourcesResolved
  • func (e ErrNoSourcesResolved) Error() string
• type ErrReadResponse
  • func (e ErrReadResponse) Error() string
• type FileSource
  • func (source FileSource) Get(_ context.Context) ([]byte, error)
• type HTTPSource
  • func (source HTTPSource) Get(ctx context.Context) ([]byte, error)
• type RSAPrivateKeyBroker
  • func NewPrivateRSA(config *Config) *RSAPrivateKeyBroker
  • func (b *RSAPrivateKeyBroker) Check() ([]string, bool)
  • func (b *RSAPrivateKeyBroker) Close()
  • func (b *RSAPrivateKeyBroker) Copy() rsa.PrivateKey
  • func (b *RSAPrivateKeyBroker) Halt(ctx context.Context) error
  • func (b *RSAPrivateKeyBroker) Renew()
  • func (b *RSAPrivateKeyBroker) Run(ctx context.Context) error
• type RSAPrivateKeyCopier
• type RSAPublicKeyBroker
  • func NewPublicRSA(config *Config) *RSAPublicKeyBroker
  • func NewRSA(config *Config) *RSAPublicKeyBroker
  • func (b *RSAPublicKeyBroker) Check() ([]string, bool)
  • func (b *RSAPublicKeyBroker) Close()
  • func (b *RSAPublicKeyBroker) Copy() rsa.PublicKey
  • func (b *RSAPublicKeyBroker) Halt(ctx context.Context) error
  • func (b *RSAPublicKeyBroker) Renew()
  • func (b *RSAPublicKeyBroker) Run(ctx context.Context) error
• type RSAPublicKeyCopier
• type Renewer
• type Source
• type Sources
  • func (sources Sources) Get(ctx context.Context) ([]byte, error)
• type StringSource
  • func (source StringSource) Get(_ context.Context) ([]byte, error)

Examples

• Package

Variables

var (
	// ErrEmptyURL represents an error for when an expected url is an empty string
	ErrEmptyURL = ErrGetKeySource{"url cannot be empty"}

	// ErrEmptyFilePath represents an error for when an expected file path is an empty string
	ErrEmptyFilePath = ErrGetKeySource{"file path cannot be empty"}

	// ErrEmptyString represents an error for when an expected string should contain a public key
	ErrEmptyString = ErrGetKeySource{"string cannot be empty"}
)

var (
	// DefaultPublicRSA is an empty RSA public key.
	DefaultPublicRSA = &rsa.PublicKey{E: 0, N: big.NewInt(0)}

	// DefaultPrivateRSA is an empty RSA private key.
	DefaultPrivateRSA = &rsa.PrivateKey{
		D:         big.NewInt(0),
		PublicKey: *DefaultPublicRSA,
		Primes:    []*big.Int{},
	}

	// DefaultRSA is an empty RSA public key.
	// DEPRECATED: DefaultRSA is deprecated in favour of DefaultPublicRSA
	DefaultRSA = DefaultPublicRSA
)

var (
	// JWTPublicKeyEnvStringSource represents the source of an RSA public key as a string
	JWTPublicKeyEnvStringSource = EnvStringSource("JWT_PUBLIC_KEY")

	// JWTPublicKeyEnvHTTPSource represents the source of an RSA public key at a HTTP GET destination
	JWTPublicKeyEnvHTTPSource = EnvHTTPSource("JWT_PUBLIC_KEY_URL")

	// JWTPublicKeyEnvFileSource represents the source of an RSA public key on disk
	JWTPublicKeyEnvFileSource = EnvFileSource("JWT_PUBLIC_KEY_PATH")

	// JWTPublicKeyDefaultFileSource represents the source of an RSA public key on disk
	JWTPublicKeyDefaultFileSource = FileSource("/usr/local/var/jwt.pub.pem")

	// JWTPublicKeySources represents a chain of sources for JWT Public Keys in order of priority
	JWTPublicKeySources = Sources{
		JWTPublicKeyEnvStringSource,
		JWTPublicKeyEnvFileSource,
		JWTPublicKeyEnvHTTPSource,
		JWTPublicKeyDefaultFileSource,
	}

	// JWTPrivateKeyEnvStringSource represents the source of an RSA public key as a string
	JWTPrivateKeyEnvStringSource = EnvStringSource("JWT_PRIVATE_KEY")

	// JWTPrivateKeyEnvHTTPSource represents the source of an RSA public key at a HTTP GET destination
	JWTPrivateKeyEnvHTTPSource = EnvHTTPSource("JWT_PRIVATE_KEY_URL")

	// JWTPrivateKeyEnvFileSource represents the source of an RSA public key on disk
	JWTPrivateKeyEnvFileSource = EnvFileSource("JWT_PRIVATE_KEY_PATH")

	// JWTPrivateKeyDefaultFileSource represents the source of an RSA public key on disk
	JWTPrivateKeyDefaultFileSource = FileSource("/usr/local/var/jwt.pem")

	// JWTPrivateKeySources represents a chain of sources for JWT Public Keys in order of priority
	JWTPrivateKeySources = Sources{
		JWTPrivateKeyEnvStringSource,
		JWTPrivateKeyEnvFileSource,
		JWTPrivateKeyEnvHTTPSource,
		JWTPrivateKeyDefaultFileSource,
	}
)

Types

type Closer

type Closer interface {
	Close()
}

Closer represents behaviour for closing a broker

type Config

type Config struct {
	Interval time.Duration
	Source   Source
}

Config represents broker configuration

type EnvFileSource

type EnvFileSource string

EnvFileSource refers to a source in env

func (EnvFileSource) Get

func (source EnvFileSource) Get(ctx context.Context) ([]byte, error)

Get converts the environment variable to a file path and resolves it

type EnvHTTPSource

type EnvHTTPSource string

EnvHTTPSource refers to a source in env

func (EnvHTTPSource) Get

func (source EnvHTTPSource) Get(ctx context.Context) ([]byte, error)

Get converts the environment variable to a http url and resolves it

type EnvStringSource

type EnvStringSource string

EnvStringSource refers to a source in env

func (EnvStringSource) Get

func (source EnvStringSource) Get(ctx context.Context) ([]byte, error)

Get converts the environment variable value to a byte slice

type ErrGetKeySource

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

ErrGetKeySource represents an error when failing to get the source

func (ErrGetKeySource) Error

func (e ErrGetKeySource) Error() string

type ErrNoSourcesResolved

type ErrNoSourcesResolved struct {
	N int
}

ErrNoSourcesResolved represents an error for when no sources could be resolved at all

func (ErrNoSourcesResolved) Error

func (e ErrNoSourcesResolved) Error() string

type ErrReadResponse

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

ErrReadResponse represents an error when failing to read the source data

func (ErrReadResponse) Error

func (e ErrReadResponse) Error() string

type FileSource

type FileSource string

FileSource defines a path to a file on disk

func (FileSource) Get

func (source FileSource) Get(_ context.Context) ([]byte, error)

Get retrieves data from the path to a file on disk

type HTTPSource

type HTTPSource string

HTTPSource defines a source with a URL to resolve over HTTP

func (HTTPSource) Get

func (source HTTPSource) Get(ctx context.Context) ([]byte, error)

Get retrieves data from the URL over HTTP

type RSAPrivateKeyBroker

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

RSAPrivateKeyBroker defines the implementation for brokering an RSA public key

func NewPrivateRSA

func NewPrivateRSA(config *Config) *RSAPrivateKeyBroker

NewPrivateRSA returns a rsa private key broker based on configuration.

func (*RSAPrivateKeyBroker) Check

func (b *RSAPrivateKeyBroker) Check() ([]string, bool)

Check will see if the broker is ready.

func (*RSAPrivateKeyBroker) Close

func (b *RSAPrivateKeyBroker) Close()

Close stops the ticker and releases resources.

func (*RSAPrivateKeyBroker) Copy

func (b *RSAPrivateKeyBroker) Copy() rsa.PrivateKey

Copy returns a shallow copy o the RSA private key.

func (*RSAPrivateKeyBroker) Halt

func (b *RSAPrivateKeyBroker) Halt(ctx context.Context) error

Halt will attempt to gracefully shut down the broker.

func (*RSAPrivateKeyBroker) Renew

func (b *RSAPrivateKeyBroker) Renew()

Renew will inform the broker to force renewal of the key.

func (*RSAPrivateKeyBroker) Run

func (b *RSAPrivateKeyBroker) Run(ctx context.Context) error

Run will periodically try and the private key.

type RSAPrivateKeyCopier

type RSAPrivateKeyCopier interface {
	Copy() rsa.PrivateKey
}

RSAPrivateKeyCopier represents behaviour for distributing copies of private keys

type RSAPublicKeyBroker

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

RSAPublicKeyBroker defines the implementation for brokering an RSA public key.

func NewPublicRSA

func NewPublicRSA(config *Config) *RSAPublicKeyBroker

NewPublicRSA returns a rsa public key broker based on configuration.

func NewRSA

func NewRSA(config *Config) *RSAPublicKeyBroker

NewRSA returns a rsa public key broker based on configuration. DEPRECATED: The function keybroker.NewRSA() has been deprecated in favour of keybroker.NewPublicRSA()

func (*RSAPublicKeyBroker) Check

func (b *RSAPublicKeyBroker) Check() ([]string, bool)

Check will see if the broker is ready.

func (*RSAPublicKeyBroker) Close

func (b *RSAPublicKeyBroker) Close()

Close stops the ticker and releases resources.

func (*RSAPublicKeyBroker) Copy

func (b *RSAPublicKeyBroker) Copy() rsa.PublicKey

Copy returns a shallow copy o the RSA public key.

func (*RSAPublicKeyBroker) Halt

func (b *RSAPublicKeyBroker) Halt(ctx context.Context) error

Halt will attempt to gracefully shut down the broker.

func (*RSAPublicKeyBroker) Renew

func (b *RSAPublicKeyBroker) Renew()

Renew will inform the broker to force renewal of the key.

func (*RSAPublicKeyBroker) Run

func (b *RSAPublicKeyBroker) Run(ctx context.Context) error

Run will periodically try and the public key.

type RSAPublicKeyCopier

type RSAPublicKeyCopier interface {
	Copy() rsa.PublicKey
}

RSAPublicKeyCopier represents behaviour for distributing copies of public keys

type Renewer

type Renewer interface {
	Renew()
}

Renewer represents behaviour for marking a broker for renewal

type Source

type Source interface {
	Get(ctx context.Context) ([]byte, error)
}

Source represents one or a chain of sources

type Sources

type Sources []Source

Sources defines a chain of sources

func (Sources) Get

func (sources Sources) Get(ctx context.Context) ([]byte, error)

Get iterates sources and returns the first successfully resolved

type StringSource

type StringSource string

StringSource defines the source as a string

func (StringSource) Get

func (source StringSource) Get(_ context.Context) ([]byte, error)

Get converts the string to a byte slice