keychain

Documentation

Index

• Constants
• type Cache
  • func (c *Cache) Cache(commonName string, pubkey keys.Key, ttl time.Duration) (err error)
  • func (c *Cache) ClearCache() error
  • func (c *Cache) ExchangeKey(commonName string) (pubkey keys.PublicKey, err error)
  • func (c *Cache) ExternalStore() KeyStore
  • func (c *Cache) InternalStore() KeyStore
  • func (c *Cache) Lookup(commonName string, source Source) (signature string, err error)
  • func (c *Cache) SealingKey(commonName string) (pubkey keys.PublicKey, err error)
  • func (c *Cache) StorageKey(signature, commonName string) (pubkey keys.PublicKey, err error)
  • func (c *Cache) Store(keypair keys.Key, opts *KeyOptions) (err error)
  • func (c *Cache) UnsealingKey(signature, commonName string) (privkey keys.PrivateKey, err error)
• type CacheOption
  • func WithCacheDuration(ttl time.Duration) CacheOption
  • func WithDefaultKey(key keys.Key) CacheOption
  • func WithExternalStore(store KeyStore) CacheOption
  • func WithInternalStore(store KeyStore) CacheOption
  • func WithSealingKeys(keys ...keys.Key) CacheOption
• type KeyChain
  • func New(opts ...CacheOption) (_ KeyChain, err error)
• type KeyOptions
• type KeyStore
• type Source
  • func (s Source) String() string
• type SourceMap
  • func NewSourceMap() SourceMap

Constants

const (
	DefaultCacheDuration = 24 * time.Hour
)

Types

type Cache

type Cache struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Cache implements the KeyChain interface and manages both the storage of private keys for unsealing envelopes and responding to key exchange requests as well as cacheing public keys from remote counterparties for sealing secure envelopes. By default the cache keeps keys from remote counter parties for 10 minutes before requiring another key exchange from the peer.

The Cache stores public and private keys in separate key stores, by default using memks.MemStore as the default storage backend, but can be configured to use other key stores where necessary.

func (*Cache) Cache

func (c *Cache) Cache(commonName string, pubkey keys.Key, ttl time.Duration) (err error)

Cache a public key received from the remote Peer during a key exchange. If ttl is less than or equal to 0 the default cache time is used. This method operates on the external source (e.g. keys from external counterparties).

func (*Cache) ClearCache

func (c *Cache) ClearCache() error

func (*Cache) ExchangeKey

func (c *Cache) ExchangeKey(commonName string) (pubkey keys.PublicKey, err error)

Get the local public seal key to send to the remote in a key exchange so that the remote Peer can seal envelopes being sent to this node. If there is no keys specified for the common name, the default keys are returned. This method operates on the internal source (e.g. keys loaded for the local node).

func (*Cache) ExternalStore

func (c *Cache) ExternalStore() KeyStore

func (*Cache) InternalStore

func (c *Cache) InternalStore() KeyStore

func (*Cache) Lookup

func (c *Cache) Lookup(commonName string, source Source) (signature string, err error)

Lookup the signature for the specified common name. If the source is internal and there is a default key, then the default key signature is returned. Returns an error if no signature and no default key is available.

func (*Cache) SealingKey

func (c *Cache) SealingKey(commonName string) (pubkey keys.PublicKey, err error)

Get the public key (or other asymmetric public key) associated with the remote Peer via a key exchange using mTLS certificates with the given common name. An error is returned if no sealing key is available (or the cache has expired), requiring a KeyExchange or a key lookup from the GDS. This method operates on the external source (e.g. keys from external counterparties).

func (*Cache) StorageKey

func (c *Cache) StorageKey(signature, commonName string) (pubkey keys.PublicKey, err error)

func (*Cache) Store

func (c *Cache) Store(keypair keys.Key, opts *KeyOptions) (err error)

Store a private key pair for use in unsealing incoming envelopes and to send public keys in key exchange request with remote peers. Options deals with how the sealing key is used during key exchanges. This method operates on the internal source (e.g. keys loaded for the local node).

func (*Cache) UnsealingKey

func (c *Cache) UnsealingKey(signature, commonName string) (privkey keys.PrivateKey, err error)

Get the private unsealing key either by public key signature on the envelope or by common name from the mTLS certificates in the RPC to unseal an incoming secure envelope sealed by the remote. If both a signature and a commonName are supplied, the commonName is ignored. If neither the signature nor the commonName are supplied then the default keys are returned if they are set on the cache. This method operates on the internal source (e.g. keys loaded for the local node).

type CacheOption

type CacheOption func(*Cache) error

func WithCacheDuration

func WithCacheDuration(ttl time.Duration) CacheOption

WithCacheDuration sets the TTL for cached public keys of remote peers.

func WithDefaultKey

func WithDefaultKey(key keys.Key) CacheOption

Store default sealing key in the store. Note that this option must come after WithInternalStore if specifying a different internal store than the default store or it will have no effect (e.g. the sealing keys will not be stored).

func WithExternalStore

func WithExternalStore(store KeyStore) CacheOption

Specify the external store to use with the key cache (which is a MemStore by default)

func WithInternalStore

func WithInternalStore(store KeyStore) CacheOption

Specify the internal store to use with the key cache (which is a MemStore by default) Note that this option must come before WithSealingKeys or WithDefaultKey otherwise the default store will be replaced, overwriting the storage of sealing keys.

func WithSealingKeys

func WithSealingKeys(keys ...keys.Key) CacheOption

Store sealing keys when creating the cache. Note that this option must come after WithInternalStore if specifying a different internal store than the default store or it will have no effect (e.g. the sealing keys will not be stored).

type KeyChain

type KeyChain interface {
	// Get the cached *rsa.PublicKey associated with the remote Peer received during a
	// KeyExchange RPC or GDS lookup. An error is returned if no sealing key is
	// available (or the cache has expired), requiring a new KeyExchange or a key lookup
	// from the GDS.
	SealingKey(commonName string) (pubkey keys.PublicKey, err error)

	// Get the private unsealing key either by public key signature on the envelope or
	// by common name from the mTLS certificates in the RPC to unseal an incoming secure
	// envelope sealed by the remote.
	UnsealingKey(signature, commonName string) (privkey keys.PrivateKey, err error)

	// Get the storage key associated with the UnsealingKey (e.g. the public key
	// component of the private key). This key is typically the same key as the exchange
	// key but earlier versions can be retrieved via the signature.
	StorageKey(signature, commonName string) (pubkey keys.PublicKey, err error)

	// Get the local public seal key to send to the remote in a key exchange so that
	// the remote Peer can seal envelopes being sent to this node.
	ExchangeKey(commonName string) (pubkey keys.PublicKey, err error)

	// Cache a public key received from the remote Peer during a key exchange.
	Cache(commonName string, pubkey keys.Key, ttl time.Duration) error

	// Store a private key pair for use in unsealing incoming envelopes and to send
	// public keys in key exchange request with remote peers. Options deals with how
	// the sealing key is used during key exchanges.
	Store(keypair keys.Key, opts *KeyOptions) error
}

The KeyChain user interface is used to manage sealing and unsealing keys both for the local node and any public key material required for remote nodes. The KeyChain indexes keys based on their key signature and common name. For outgoing messages, the keychain can return the public key of the recipient by common name to seal outgoing envelopes. For incoming messages, the signature of the key and optionally the common name can be used to retrieve the private key to open the envelope.

func New

func New(opts ...CacheOption) (_ KeyChain, err error)

New returns a Cache KeyChain object configured and ready for use by the options.

type KeyOptions

type KeyOptions struct {
	// Specify the key is the default key to use in key exchanges. If a default key
	// already exists on the store this key will replace that key.
	IsDefault bool `json:"is_default"`

	// Associate this key with the common names of specific counterparties. Used to
	// identify specific remote peers to use this key with. If counterparties are
	// specified, this key only be used in key exchanges with incoming mTLS connections
	// that have the specified common names, unless it is already marked as the default.
	Counterparties []string `json:"counterparties"`

	// Do not use the key after the specified expiration date. This is used for time
	// based keys. Note that this field ignores expiration on the certificates and if
	// no keys are available that aren't expired, errors will be returned during key
	// exchanges. If this field is empty then the key will never expire.
	ExpiresOn time.Time `json:"expires_on"`
}

KeyOptions defines how multiple private key pairs are used during key exchanges.

type KeyStore

type KeyStore interface {
	Get(signature string) (keys.Key, time.Time, error)
	Put(key keys.Key) error
	Delete(signature string) error
}

KeyStore maps key signatures to serialized public sealing keys that can be stored in memory or on disk. The KeyStore must also manage the time of storage for cache busting.

type Source

type Source uint8

Source type provides cache directionality information. Internal source refers to keys stored for the local (e.g. internal node) usually containing private key pairs. External source refers to keys stored from incoming key exchanges, usually only public keys that are used to seal envelopes.

const (
	UnknownSource Source = iota
	InternalSource
	ExternalSource
)

func (Source) String

func (s Source) String() string

type SourceMap

type SourceMap map[Source]map[string]string

SourceMap is a dictionary that maps names (e.g. common names or signatures) to a map of source to interface, allowing the tree storage of data from different sources.

func NewSourceMap

func NewSourceMap() SourceMap