keyloader

Documentation

Index

• Constants
• Variables
• func LoadKey(identifier string) (symmecrypt.Key, error)
• func LoadKeyFromStore(identifier string, store *configstore.Store) (symmecrypt.Key, error)
• func LoadSingleKey() (symmecrypt.Key, error)
• func LoadSingleKeyFromStore(store *configstore.Store) (symmecrypt.Key, error)
• func NewKey(cfgs ...*KeyConfig) (symmecrypt.Key, error)
• func WatchKey(identifier string) (symmecrypt.Key, error)
• func WatchKeyFromStore(identifier string, store *configstore.Store) (symmecrypt.Key, error)
• func WatchSingleKey() (symmecrypt.Key, error)
• func WatchSingleKeyFromStore(store *configstore.Store) (symmecrypt.Key, error)
• type KeyConfig
  • func ConfiguredKeys() ([]*KeyConfig, error)
  • func ConfiguredKeysFromStore(store *configstore.Store) ([]*KeyConfig, error)
  • func GenerateKey(cipher string, identifier string, sealed bool, timestamp time.Time) (*KeyConfig, error)
  • func SealKey(k *KeyConfig, s *seal.Seal) (*KeyConfig, error)
  • func UnsealKey(k *KeyConfig, s *seal.Seal) (*KeyConfig, error)
  • func (k KeyConfig) String() string

Constants

const (
	// EncryptionKeyConfigName is the name of the config items representing encryption keys in configstore.
	EncryptionKeyConfigName = "encryption-key"

	// DefaultCipher is the cipher used by default if an empty ciper name is passed to GenerateKey().
	DefaultCipher = xchacha20poly1305.CipherName
)

Variables

var (
	// ConfigFilter is the configstore manipulation filter used to retrieve the encryption keys
	ConfigFilter = configstore.Filter().Slice(EncryptionKeyConfigName).Unmarshal(configFactory).Rekey(rekeyConfigByIdentifier).Reorder(reorderTimestamp)

	// ErrKeySealed is returned when attempting to use a key that is still in a sealed state
	ErrKeySealed = errors.New("encryption key is sealed!")
)

Functions

func LoadKey

func LoadKey(identifier string) (symmecrypt.Key, error)

LoadKey instantiates a new encryption key for a given identifier from the default store in configstore. It retrieves all the necessary data from configstore then calls NewKey().

If several keys are found for the identifier, they are sorted by timestamp, and a composite key is returned. The most recent key will be used for encryption, and decryption will be done by any of them. There needs to be _only one_ key with the highest priority for the identifier.

If the key configuration specifies it is sealed, the key returned will be wrapped by an unseal mechanism. When the symmecrypt/seal global singleton gets unsealed, the key will become usable instantly. It will return errors in the meantime.

The key cipher name is expected to match a KeyFactory that got registered through RegisterCipher(). Either use a built-in cipher, or make sure to register a proper factory for this cipher. This KeyFactory will be called, either directly or when the symmecrypt/seal global singleton gets unsealed, if applicable.

func LoadKeyFromStore

func LoadKeyFromStore(identifier string, store *configstore.Store) (symmecrypt.Key, error)

LoadKeyFromStore instantiates a new encryption key for a given identifier from a specific store instance. It retrieves all the necessary data from configstore then calls NewKey().

If several keys are found for the identifier, they are sorted by timestamp, and a composite key is returned. The most recent key will be used for encryption, and decryption will be done by any of them. There needs to be _only one_ key with the highest priority for the identifier.

If the key configuration specifies it is sealed, the key returned will be wrapped by an unseal mechanism. When the symmecrypt/seal global singleton gets unsealed, the key will become usable instantly. It will return errors in the meantime.

The key cipher name is expected to match a KeyFactory that got registered through RegisterCipher(). Either use a built-in cipher, or make sure to register a proper factory for this cipher. This KeyFactory will be called, either directly or when the symmecrypt/seal global singleton gets unsealed, if applicable.

func LoadSingleKey

func LoadSingleKey() (symmecrypt.Key, error)

LoadSingleKey instantiates a new encryption key using LoadKey from the default store in configstore without specifying its identifier. It retrieves all the necessary data from configstore then calls NewKey(). It will error if several different identifiers are found.

func LoadSingleKeyFromStore

func LoadSingleKeyFromStore(store *configstore.Store) (symmecrypt.Key, error)

LoadSingleKey instantiates a new encryption key using LoadKey from a specific store instance without specifying its identifier. It retrieves all the necessary data from configstore then calls NewKey(). It will error if several different identifiers are found.

func NewKey

func NewKey(cfgs ...*KeyConfig) (symmecrypt.Key, error)

NewKey returns a symmecrypt.Key object configured from a number of KeyConfig objects. If several KeyConfigs are supplied, the returned Key will be composite. A composite key encrypts with the latest Key (based on timestamp) and decrypts with any of they keys.

If the key configuration specifies it is sealed, the key returned will be wrapped by an unseal mechanism. When the symmecrypt/seal global singleton gets unsealed, the key will become usable instantly. It will return errors in the meantime.

The key cipher name is expected to match a KeyFactory that got registered through RegisterCipher(). Either use a built-in cipher, or make sure to register a proper factory for this cipher. This KeyFactory will be called, either directly or when the symmecrypt/seal global singleton gets unsealed, if applicable.

func WatchKey

func WatchKey(identifier string) (symmecrypt.Key, error)

WatchKey instantiates a new hot-reloading encryption key from the default store in configstore. It uses LoadKey(), so the underlying implementation can be anything supported (composite, sealed, any cipher, ...)

func WatchKeyFromStore

func WatchKeyFromStore(identifier string, store *configstore.Store) (symmecrypt.Key, error)

WatchKeyFromStore instantiates a new hot-reloading encryption key from a specific store instance. It uses LoadKey(), so the underlying implementation can be anything supported (composite, sealed, any cipher, ...)

func WatchSingleKey

func WatchSingleKey() (symmecrypt.Key, error)

WatchSingleKey instantiates a new hot-reloading encryption key from the default store in configstore without specifying its identifier. It will error if several different identifiers are found.

func WatchSingleKeyFromStore

func WatchSingleKeyFromStore(store *configstore.Store) (symmecrypt.Key, error)

WatchSingleKeyFromStore instantiates a new hot-reloading encryption key from a specific store instance without specifying its identifier. It will error if several different identifiers are found.

Types

type KeyConfig

type KeyConfig struct {
	Identifier string `json:"identifier,omitempty"`
	Cipher     string `json:"cipher"`
	Timestamp  int64  `json:"timestamp,omitempty"`
	Sealed     bool   `json:"sealed,omitempty"`
	Key        string `json:"key"`
}

KeyConfig is the representation of an encryption key in the configuration.

• Identifier is a free name to uniquely reference this key (and its revisions). It is used when loading the key.
• Cipher controls which cipher is used (aes-gcm, ...)
• Timestamp dictates priority between encryption keys, and is useful to identify new versions of a key
• Sealed controls whether the key should be used as-is, or decrypted using symmecrypt/seal See RegisterCipher() to register a factory. The cipher field should be the same as the factory name.

func ConfiguredKeys

func ConfiguredKeys() ([]*KeyConfig, error)

ConfiguredKeys returns a list of all the encryption keys present in the default store in configstore ensuring they are unsealed.

func ConfiguredKeysFromStore

func ConfiguredKeysFromStore(store *configstore.Store) ([]*KeyConfig, error)

ConfiguredKeysFromStore returns a list of all the encryption keys present in a specific store instance ensuring they are unsealed.

func GenerateKey

func GenerateKey(cipher string, identifier string, sealed bool, timestamp time.Time) (*KeyConfig, error)

GenerateKey generates a new random key and returns its configuration object representation.

func SealKey

func SealKey(k *KeyConfig, s *seal.Seal) (*KeyConfig, error)

SealKey returns a copy of the key configuration object, ensuring it is sealed.

func UnsealKey

func UnsealKey(k *KeyConfig, s *seal.Seal) (*KeyConfig, error)

UnsealKey returns a copy of the key configuration object, ensuring it is unsealed.

func (KeyConfig) String

func (k KeyConfig) String() string