key

package
v1.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 8, 2023 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package key provides a simple API for loading public and private keys from resources.

Index

Constants

View Source
const (
	// KeyIdParameterName is the template parameter that must be present in URI templates
	// if there are any parameters.  URI templates accepted by this package have either no parameters
	// or exactly one (1) parameter with this name.
	KeyIdParameterName = "keyId"
)

Variables

View Source
var (
	ErrorPEMRequired                 = errors.New("Keys must be PEM-encoded")
	ErrorUnsupportedPrivateKeyFormat = errors.New("Private keys must be in PKCS1 or PKCS8 format")
	ErrorNotRSAPrivateKey            = errors.New("Only RSA private keys are supported")
	ErrorNotRSAPublicKey             = errors.New("Only RSA public keys or certificates are suppored")
)
View Source
var (
	// ErrorInvalidTemplate is the error returned when a URI template is invalid for a key resource
	ErrorInvalidTemplate = fmt.Errorf(
		"Key resource template must support either no parameters are the %s parameter",
		KeyIdParameterName,
	)
)

Functions

func NewUpdater

func NewUpdater(updateInterval time.Duration, resolver Resolver) (updater concurrent.Runnable)

NewUpdater conditionally creates a Runnable which will update the keys in the given resolver on the configured updateInterval. If both (1) the updateInterval is positive, and (2) resolver implements Cache, then this method returns a non-nil function that will spawn a goroutine to update the cache in the background. Otherwise, this method returns nil.

Types

type Cache

type Cache interface {
	Resolver

	// UpdateKeys updates all keys known to this cache.  This method makes
	// a best-effort to avoid blocking other goroutines which use ResolveKey,
	// which may mean copy-on-write semantics.
	//
	// The first return value is the count of keys for which attempts were
	// made to update.
	//
	// UpdateKeys may run multiple I/O operations.  The second return value is a slice of
	// errors that occurred while it attempted to update each key.  Exactly one (1)
	// attempt will be made to update each key present in the cache, regardless
	// of any update errors for each individual key.  This slice may be nil if no
	// errors occurred.
	UpdateKeys() (int, []error)
}

Cache is a Resolver type which provides caching for keys based on keyID.

All implementations will block the first time a particular key is accessed and will initialize the value for that key. Thereafter, all updates happen in a separate goroutine. This allows HTTP transactions to avoid paying the cost of loading a key after the initial fetch.

type MockCache

type MockCache struct {
	mock.Mock
}

MockCache is a stretchr mock for Cache. It's exposed for other package tests.

func (*MockCache) ResolveKey

func (cache *MockCache) ResolveKey(keyId string) (Pair, error)

func (*MockCache) UpdateKeys

func (cache *MockCache) UpdateKeys() (int, []error)

type MockPair

type MockPair struct {
	mock.Mock
}

MockPair is a stretchr mock for Pair. It's exposed for other package tests.

func (*MockPair) HasPrivate

func (pair *MockPair) HasPrivate() bool

func (*MockPair) Private

func (pair *MockPair) Private() interface{}

func (*MockPair) Public

func (pair *MockPair) Public() interface{}

func (*MockPair) Purpose

func (pair *MockPair) Purpose() Purpose

type MockParser

type MockParser struct {
	mock.Mock
}

func (*MockParser) ParseKey

func (parser *MockParser) ParseKey(purpose Purpose, data []byte) (Pair, error)

type MockResolver

type MockResolver struct {
	mock.Mock
}

MockResolver is a stretchr mock for Resolver. It's exposed for other package tests.

func (*MockResolver) ResolveKey

func (resolver *MockResolver) ResolveKey(keyId string) (Pair, error)

type Pair

type Pair interface {
	// Purpose returns the configured intended usage of this key pair
	Purpose() Purpose

	// Public returns the public key associated with this pair.  It will never be nil
	Public() interface{}

	// HasPrivate tests whether this key Pair has a private key
	HasPrivate() bool

	// Private returns the optional private key associated with this Pair.  If there
	// is no private key, this method returns nil.
	Private() interface{}
}

Pair represents a resolved key pair. For all Pair instances, the private key is optional, while the public key will always be present.

type Parser

type Parser interface {
	// Parse examines data to produce a Pair.  If the returned error is not nil,
	// the Pair will always be nil.  This method is responsible for dealing with
	// any required decoding, such as PEM or DER.
	ParseKey(Purpose, []byte) (Pair, error)
}

Parser parses a chunk of bytes into a Pair. Parser implementations must always be safe for concurrent access.

var DefaultParser Parser = defaultParser(0)

DefaultParser is the global, singleton default parser. All keys submitted to this parser must be PEM-encoded.

type Purpose

type Purpose int

Purpose is an enumerated type describing the reason a given key is being used. This type implements Parser.

All Purpose values assume PEM-encoded keys. For other formats, a custom Parser decorator can be used. Purpose.RequiresPrivateKey() determines whether to parse the key as a private key.

const (
	// PurposeVerify refers to a key used to verify a signature.  This is the zero-value
	// for Purpose.  These keys must be public keys encoded as PEM blocks.
	PurposeVerify Purpose = Purpose(iota)

	// PurposeSign refers to a key used to create a signature.  These keys must be private,
	// PEM-encoded keys.
	PurposeSign

	// PurposeEncrypt refers to a key used to encrypt data.  These keys must be private,
	// PEM-encoded keys.
	PurposeEncrypt

	// PurposeDecrypt refers to a key used to decrypt data.  These keys must be public,
	// PEM-encoded keys.
	PurposeDecrypt
)

func (Purpose) MarshalJSON

func (p Purpose) MarshalJSON() ([]byte, error)

func (Purpose) RequiresPrivateKey

func (p Purpose) RequiresPrivateKey() bool

RequiresPrivateKey returns true if this purpose requires a private key, false if it requires a public key.

func (Purpose) String

func (p Purpose) String() string

String returns a human-readable, string representation for a Purpose. Unrecognized purpose values are assumed to be PurposeVerify.

func (*Purpose) UnmarshalJSON

func (p *Purpose) UnmarshalJSON(data []byte) error

type Resolver

type Resolver interface {
	// ResolveKey returns a key Pair associated with the given identifier.  The exact mechanics of resolving
	// a keyId into a Pair are implementation-specific.  Implementations are free
	// to ignore the keyId parameter altogether.
	ResolveKey(keyId string) (Pair, error)
}

Resolver loads and parses keys associated with key identifiers.

type ResolverFactory

type ResolverFactory struct {
	resource.Factory

	// All keys resolved by this factory will have this purpose, which affects
	// how keys are parsed.
	Purpose Purpose `json:"purpose"`

	// UpdateInterval specifies how often keys should be refreshed.
	// If negative or zero, keys are never refreshed and are cached forever.
	UpdateInterval types.Duration `json:"updateInterval"`

	// Parser is a custom key parser.  If omitted, DefaultParser is used.
	Parser Parser `json:"-"`
}

ResolverFactory provides a JSON representation of a collection of keys together with a factory interface for creating distinct Resolver instances.

This factory uses resource.NewExpander() to create a resource template used in resolving keys. This template can have no parameters, in which case the same resource is used regardless of the key id. If the template has any parameters, it must have exactly (1) parameter and that parameter's name must be equal to KeyIdParameterName.

func (*ResolverFactory) NewResolver

func (factory *ResolverFactory) NewResolver() (Resolver, error)

NewResolver() creates a Resolver using this factory's configuration. The returned Resolver always caches keys forever once they have been loaded.

func (*ResolverFactory) NewUpdater

func (factory *ResolverFactory) NewUpdater(resolver Resolver) concurrent.Runnable

NewUpdater uses this factory's configuration to conditionally create a Runnable updater for the given resolver. This method delegates to the NewUpdater function, and may return a nil Runnable if no updates are necessary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL