store

Documentation

Overview

Package store contains two types of secure stores: a store that contains secrets, such as might be used by a password manager, and a store that contains public keys, such as might be used by a PGP-like system.

Index

• Constants
• func DumpKeyStore(store *KeyStore) []byte
• func MarshalSecretStore(s *SecretStore, m secret.ScryptMode) ([]byte, bool)
• type KeyStore
  • func LoadKeyStore(path string, orNew bool) (*KeyStore, bool)
  • func NewPrivateKeyStore(priv *public.PrivateKey) (*KeyStore, bool)
  • func (s *KeyStore) AddKey(label string, peer []byte, metadata map[string]string) bool
  • func (s *KeyStore) Decrypt(message []byte) ([]byte, bool)
  • func (s *KeyStore) DecryptAndVerify(label string, message []byte) ([]byte, bool)
  • func (s *KeyStore) Dump() ([]byte, error)
  • func (s *KeyStore) EncryptAndSignTo(label string, message []byte) ([]byte, bool)
  • func (s *KeyStore) EncryptTo(label string, message []byte) ([]byte, bool)
  • func (s *KeyStore) ExportVerified(label string) ([]byte, bool)
  • func (s *KeyStore) FindPublic(pub []byte) (string, bool)
  • func (s *KeyStore) Has(label string) bool
  • func (s *KeyStore) ImportVerified(label string, signedKey []byte) bool
  • func (s *KeyStore) ImportVerifiedKey(label string, signedKey []byte) bool
  • func (s *KeyStore) KeyAudit() bool
  • func (s *KeyStore) Lock() bool
  • func (s *KeyStore) LockWith(passphrase []byte) bool
  • func (s *KeyStore) Locked() bool
  • func (s *KeyStore) Sign(message []byte) ([]byte, bool)
  • func (s *KeyStore) Unlock(passphrase []byte) bool
  • func (s *KeyStore) Valid(quick bool) bool
  • func (s *KeyStore) Verify(label string, message, sig []byte) bool
  • func (s *KeyStore) VerifyChain(label string) bool
  • func (s *KeyStore) VerifyKeySignature(label string) (string, bool)
• type PublicKeyRecord
• type SecretRecord
  • func (r *SecretRecord) Merge(other *SecretRecord) (*SecretRecord, bool)
  • func (r *SecretRecord) Zero()
• type SecretStore
  • func NewSecretStore(passphrase []byte) *SecretStore
  • func UnmarshalSecretStore(in, passphrase []byte, m secret.ScryptMode) (*SecretStore, bool)
  • func (s *SecretStore) AddRecord(name string, secret []byte, md map[string][]byte) bool
  • func (s *SecretStore) ChangePassword(newPass []byte)
  • func (s *SecretStore) Has(name string) bool
  • func (s *SecretStore) Merge(other *SecretStore) []string
  • func (s *SecretStore) UpdateSecret(name string, secret []byte) bool
  • func (s *SecretStore) Valid() bool
  • func (s *SecretStore) Zero()
• type VerifiedKey
  • func ParseVerifiedKey(in []byte) (*VerifiedKey, error)
  • func (vkey *VerifiedKey) IsSelfSigned() bool
  • func (vkey *VerifiedKey) Serialise() ([]byte, error)
  • func (vkey *VerifiedKey) SignatureData() []byte

Constants

const KeyStoreVersion = 1

KeyStoreVersion is the current version of the keystore format.

const SecretStoreVersion = 1

SecretStoreVersion is the current version of the secret store format.

const SecretType = "CRYPTUTIL SECRET STORE"

SecretType is the PEM type used when exporting the store.

const VerifiedKeyType = "CRYPTUTIL VERIFIED KEY"

VerifiedKeyType is the PEM type used when exporting a verified key.

Functions

func DumpKeyStore

func DumpKeyStore(store *KeyStore) []byte

DumpKeyStore locks the keystore and serialises it to a byte slice, i.e. in preparation for writing to file.

func MarshalSecretStore

func MarshalSecretStore(s *SecretStore, m secret.ScryptMode) ([]byte, bool)

MarshalSecretStore serialises and encrypts the data store to a byte slice suitable for writing to disk.

Types

type KeyStore

type KeyStore struct {
	// Version should reflect the version of the keystore format
	// in use.
	Version int

	// Timestamp is a Unix timestamp pointing to the last time the
	// keystore was updated.
	Timestamp int64

	// Keys is a hash map of the public key records, indexed by
	// label.
	Keys map[string]*PublicKeyRecord

	// PrivateKey contains the locked private key. The private key
	// is encrypted with a passphrase using Scrypt and the NaCl
	// secretbox format.
	PrivateKey []byte

	// PublicKey contains the owner's public key.
	PublicKey []byte

	// ExportKey contains a signed version of the public key as a
	// PEM-encoded VerifiedKey.
	ExportKey []byte
	// contains filtered or unexported fields
}

A KeyStore represents a collection of keys with an owner. A KeyStore with a private key should be locked before serialisation.

func LoadKeyStore

func LoadKeyStore(path string, orNew bool) (*KeyStore, bool)

LoadKeyStore attempts to load a keystore from the given path. If the keystore doesn't exist, a new one is created with a freshly-generated keys if the orNew argument is true.

func NewPrivateKeyStore

func NewPrivateKeyStore(priv *public.PrivateKey) (*KeyStore, bool)

NewPrivateKeyStore builds a keystore from a private key.

func (*KeyStore) AddKey

func (s *KeyStore) AddKey(label string, peer []byte, metadata map[string]string) bool

AddKey adds the new peer key to the keystore, signing it with the owner's key. If the keystore is locked, this will fail.

func (*KeyStore) Decrypt

func (s *KeyStore) Decrypt(message []byte) ([]byte, bool)

Decrypt decrypts the message using the keystore's private key.

func (*KeyStore) DecryptAndVerify

func (s *KeyStore) DecryptAndVerify(label string, message []byte) ([]byte, bool)

DecryptAndVerify decrypts the message and verifies the message was signed by the named key.

func (*KeyStore) Dump

func (s *KeyStore) Dump() ([]byte, error)

func (*KeyStore) EncryptAndSignTo

func (s *KeyStore) EncryptAndSignTo(label string, message []byte) ([]byte, bool)

EncryptAndSignTo signs the message and encrypts to the named key.

func (*KeyStore) EncryptTo

func (s *KeyStore) EncryptTo(label string, message []byte) ([]byte, bool)

EncryptTo encrypts the message to the named public key.

func (*KeyStore) ExportVerified

func (s *KeyStore) ExportVerified(label string) ([]byte, bool)

ExportVerified returns a verified key from the label. The verified key will be signed by the keystore owner; the key's signature chain is first checked before exporting.

func (*KeyStore) FindPublic

func (s *KeyStore) FindPublic(pub []byte) (string, bool)

FindPublic looks up the public key in the key store, returning its label.

func (*KeyStore) Has

func (s *KeyStore) Has(label string) bool

Has returns true if the label is present in the keystore.

func (*KeyStore) ImportVerified

func (s *KeyStore) ImportVerified(label string, signedKey []byte) bool

ImportVerified imports a verified key under the label. The original signature data is preserved in the keystore.

func (*KeyStore) ImportVerifiedKey

func (s *KeyStore) ImportVerifiedKey(label string, signedKey []byte) bool

ImportVerifiedKey imports a PEM-encoded verified key.

func (*KeyStore) KeyAudit

func (s *KeyStore) KeyAudit() bool

KeyAudit verifies the signature chain on all keys in the keystore. This operation may be slow, and it is recommended that it be run at most once per hour. For large keystores, once per day might be more suitable.

func (*KeyStore) Lock

func (s *KeyStore) Lock() bool

Lock clears out the unlocked private key, if the keystore is locked. This should always return true, and if it doesn't, a serious error has occurred.

func (*KeyStore) LockWith

func (s *KeyStore) LockWith(passphrase []byte) bool

LockWith locks the key store with the given passphrase. This can be used with a new keystore to set the passphrase.

func (*KeyStore) Locked

func (s *KeyStore) Locked() bool

Locked indicates whether the keystore is locked. When unlocked, it may perform signature and decryption operations.

func (*KeyStore) Sign

func (s *KeyStore) Sign(message []byte) ([]byte, bool)

Sign signs the message using the keystore's private key.

func (*KeyStore) Unlock

func (s *KeyStore) Unlock(passphrase []byte) bool

Unlock decrypts the private key stored in the keystore.

func (*KeyStore) Valid

func (s *KeyStore) Valid(quick bool) bool

Valid performs sanity checks on the keystore to make sure it is valid. If quick is false, the public key and private key (if unlocked) will be checked as well.

func (*KeyStore) Verify

func (s *KeyStore) Verify(label string, message, sig []byte) bool

Verify validates that the message was signed by the named public key.

func (*KeyStore) VerifyChain

func (s *KeyStore) VerifyChain(label string) bool

VerifyChain verifies the signature chain on the key pointed to by label. First, the signature on the key pointed to by the label is verified. Then, the signature key is validated; this is continued until the keystore's public key ends up at the keystore's public key.

func (*KeyStore) VerifyKeySignature

func (s *KeyStore) VerifyKeySignature(label string) (string, bool)

VerifyKeySignature authenticates the signature on the key indicated by label. If the label is self, Verify returns true as that label is assumed always valid.

type PublicKeyRecord

type PublicKeyRecord struct {
	// Label contains a string identifier for this record. It is
	// for organisational use only, and there is nothing
	// cryptographically tying it to the key. The special label
	// "self" always points to the keystore owner's key.
	Label string

	// Version should point to the current keystore format version
	// that this record belongs to. This is used when updating the
	// keystore format.
	Version int

	// Timestamp contains the Unix timestamp of when the record
	// was last modified.
	Timestamp int64

	// Keys contains the serialised public key.
	Keys []byte

	// The KeySignature contains a signature on the key; signatures are
	// done using VerifiedKeys.
	KeySignature []byte

	// KeySigner contains the serialised public key of the key
	// that signed this record.
	KeySigner []byte

	// SignatureTime is the timestamp on the signature.
	SignatureTime int64

	// Metadata contains any additional information about the key
	// that should be stored with the key.
	Metadata map[string]string
}

A PublicKeyRecord contains information about a public key contained in the data store. A keystore should contain, at a minimum, the public key that the keystore belongs to.

type SecretRecord

type SecretRecord struct {
	// The label is used to identify the secret in the store.
	Label string

	// The timestamp stores the Unix timestamp of when the record
	// was modified last.
	Timestamp int64

	// Secret contains the secret being stored.
	Secret []byte

	// Metadata contains any additional information that should be
	// stored alongside the secret.
	Metadata map[string][]byte
}

A SecretRecord stores a secret in the secret store.

func (*SecretRecord) Merge

func (r *SecretRecord) Merge(other *SecretRecord) (*SecretRecord, bool)

Merge compares the timestamp of the record to the other record; the record that was modified most recently is selected.

func (*SecretRecord) Zero

func (r *SecretRecord) Zero()

Zero clears out the secret. The discussion for the util.Zero function contains a more in-depth discussion on the security of this.

type SecretStore

type SecretStore struct {
	// Version should reflect the version of the secret store
	// format in use.
	Version int

	// Timestamp is a Unix timestamp pointing to the last time the
	// secret store was updated.
	Timestamp int64

	// Store is a hash map of secret records, indexed by label.
	Store map[string]*SecretRecord
	// contains filtered or unexported fields
}

A SecretStore contains a collection of secrets protected by a passphrase. The passphrase is kept with the store until it is either marshalled (at which point the store is zeroised), or until the store is zeroised manually.

func NewSecretStore

func NewSecretStore(passphrase []byte) *SecretStore

NewSecretStore initialises a new secret store.

func UnmarshalSecretStore

func UnmarshalSecretStore(in, passphrase []byte, m secret.ScryptMode) (*SecretStore, bool)

UnmarshalSecretStore decrypts and parses the secret store contained in the input byte slice.

func (*SecretStore) AddRecord

func (s *SecretStore) AddRecord(name string, secret []byte, md map[string][]byte) bool

AddRecord adds a new secret to the store. If the secret already exists, it will fail. This is by design to prevent overwriting secrets unintentionally.

func (*SecretStore) ChangePassword

func (s *SecretStore) ChangePassword(newPass []byte)

ChangePassword changes the password for the SecretStore; this will take effect the next time the password store is marshalled.

func (*SecretStore) Has

func (s *SecretStore) Has(name string) bool

Has returns true if the secret store contains the named secret.

func (*SecretStore) Merge

func (s *SecretStore) Merge(other *SecretStore) []string

Merge handles the merging of two password stores. For each record in the other password store, if the entry doesn't exist in the password store it is added. If it does exist, the two records are merged.

func (*SecretStore) UpdateSecret

func (s *SecretStore) UpdateSecret(name string, secret []byte) bool

UpdateSecret updates the named secret in the key store.

func (*SecretStore) Valid

func (s *SecretStore) Valid() bool

Valid performs a sanity check on the secret store, and returns false if any discrepencies are noticed.

func (*SecretStore) Zero

func (s *SecretStore) Zero()

Zero wipes the sensitive data from the store. See the discussion of util.Zero for a more in-depth discussion on the subject.

type VerifiedKey

type VerifiedKey struct {
	// Public is the serialised public key.
	Public []byte

	// Signer is the serialised public key that signed Public.
	Signer []byte

	// Timestamp contains a Unix timestamp that indicates when the
	// key was signed.
	Timestamp int64

	// Signature contains the Ed25519 signature on the key.
	Signature []byte
}

A VerifiedKey is a structure that associates a signature with a public key. The signature is performed on the concatenation of the public key, the signer, and the timestamp.

func ParseVerifiedKey

func ParseVerifiedKey(in []byte) (*VerifiedKey, error)

ParseVerifiedKey parses a verified key from a byte slice.

func (*VerifiedKey) IsSelfSigned

func (vkey *VerifiedKey) IsSelfSigned() bool

IsSelfSigned returns true if the verified key is self-signed.

func (*VerifiedKey) Serialise

func (vkey *VerifiedKey) Serialise() ([]byte, error)

Serialises PEM-encodes the verified key.

func (*VerifiedKey) SignatureData

func (vkey *VerifiedKey) SignatureData() []byte

SignatureData returns the byte slice containing the public key, signer's public key, and the big-endian encoded 64-bit signed integer timestamp.