kfstore

Documentation

Overview

Package kfstore provides a self-contained encrypted data store for sensitive data managed by keyfish. A Store is packaged as a JSON object containing an encrypted database packet.

Storage Format

On disk, the kfstore is a single JSON object in this layout:

{
   "format":  "ks1",
   "dataKey": "<base64-encoded-data-key>",
   "data":    "<base64-encoded-data>",
   "keySalt": "<base64-encoded-key-salt>"
}

The data value is zlib-compressed and encrypted with the data key using the AEAD construction over chacha20poly1305 with the format as extra data.

The data key is a cryptographically randomly generated key, encrypted with a user-provided access key using the AEAD construction over chacha20poly1305.

The key salt is a plaintext salt value provided by the caller for use in access key generation via a KDF. This field is optional and may be empty.

Index

• Constants
• type KeyFunc
  • func AccessKey[S ~string | ~[]byte](key S) KeyFunc
• type Store
  • func New[DB any](accessKey, keySalt []byte, init *DB) (*Store[DB], error)
  • func Open[DB any](r io.Reader, accessKey KeyFunc) (*Store[DB], error)
  • func (s *Store[DB]) DB() *DB
  • func (s *Store[DB]) WriteTo(w io.Writer) (int64, error)

Constants

const AccessKeyLen = chacha20poly1305.KeySize // 32 bytes

AccessKeyLen is the required length in bytes of an access key.

const Format = "ks1"

Format is the storage format label supported by this package.

Types

type KeyFunc

type KeyFunc func(salt []byte) []byte

KeyFunc is a function that takes a salt value as input and returns an encryption key.

func AccessKey

func AccessKey[S ~string | ~[]byte](key S) KeyFunc

AccessKey returns a KeyFunc that ignores its argument and returns the specified string as the key. It is a convenience wrapper for passing pre-generated key.

type Store

type Store[DB any] struct {
	// contains filtered or unexported fields
}

A Store is an encrypted store containing a user-provide DB value. The concrete type of DB must be JSON-marshalable.

The contents of a store are encoded as a JSON object, inside which the database is encrypted with chacha20poly1305 using the AEAD construction and a randomly-generated data key. The data key is itself encrypted (using the same construction) with a caller-provided access key, and stored alongside the data.

func New

func New[DB any](accessKey, keySalt []byte, init *DB) (*Store[DB], error)

New creates a new store using accessKey to encrypt the store key.

If the accessKey was generated using a key-derivation function, the salt value for the KDF may be passed as keySalt, and it will be stored in plain text alongside the data. This value is made available to the caller when the store is reopened. The keySalt is optional and may be left nil or empty.

If init != nil, it is used as the initial database for the store; otherwise an empty DB is created. The concrete type of DB must be JSON-marshalable.

func Open

func Open[DB any](r io.Reader, accessKey KeyFunc) (*Store[DB], error)

Open opens a Store from the contents of r. Open calls accessKey with the stored key derivation salt (which may be empty) to obtain the access key, which is used to decrypt the stored data.

func (*Store[DB]) DB

func (s *Store[DB]) DB() *DB

DB returns the database associated with s. The result is never nil. If s == nil or points to an invalid Store, DB panics.

func (*Store[DB]) WriteTo

func (s *Store[DB]) WriteTo(w io.Writer) (int64, error)

WriteTo encodes and encrypts the current contents of s and writes it to w.