encdb

Documentation

Overview

Package encdb defines an encrypted database used within Mute. Such an encrypted database consists of two files for a given database file with name "dbname":

dbname.db
dbname.key

The file "dbname.db" is an AES-256 encrypted sqlite3 file managed by the package "github.com/mutecomm/go-sqlcipher/v4". The file named "dbname.key" is an AES-256 encrypted text file which contains the (randomly generated) raw encryption key for "dbname.db". To decrypt the key file the key derivation function PBKDF2 is applied to a supplied passphrase (with a configurable number of iterations) and the derived key is used as the AES-256 key for "dbname.key".

This design allows a very cheap rekey of the database, because only the key file needs to be changed and the database file itself doesn't have to be modified for a rekey operation.

Index

• Constants
• func Create(dbname string, passphrase []byte, iter int, createStmts []string) error
• func Incremental(db *sql.DB, pages int64) error
• func Open(dbname string, passphrase []byte) (*sql.DB, error)
• func ReadKeyfile(filename string, passphrase []byte) (key []byte, err error)
• func Rekey(dbname string, oldPassphrase, newPassphrase []byte, newIter int) error
• func Status(db *sql.DB) (autoVacuum string, freelistCount int64, err error)
• func Vacuum(db *sql.DB, autoVacuumMode string) error

Constants

const DBSuffix = ".db"

DBSuffix defines the suffix for database files.

const KDFIterations = 64000

KDFIterations defines a default number of KDF iterations.

const KeySuffix = ".key"

KeySuffix defines the suffix for key files.

Functions

func Create

func Create(dbname string, passphrase []byte, iter int, createStmts []string) error

Create tries to create an encrypted database with the given passphrase and iter many KDF iterations. Thereby, dbname is the prefix of the following two database files which will be created and must not exist already:

dbname.db
dbname.key

The SQL database is initialized with the statements given in createStmts. In case of error (for example, the database files do exist already or cannot be created) an error is returned.

func Incremental

func Incremental(db *sql.DB, pages int64) error

Incremental executes incremental_vacuum to free up to pages many pages. If pages is 0, all pages are freed. If the current auto_vacuum mode is not INCREMENTAL, an error is returned.

func Open

func Open(dbname string, passphrase []byte) (*sql.DB, error)

Open tries to open an encrypted database with the given passphrase. Thereby, dbname is the prefix of the following two database files (which must already exist):

dbname.db
dbname.key

In case of error (for example, the database files do not exist or the passphrase is wrong) an error is returned.

func ReadKeyfile

func ReadKeyfile(filename string, passphrase []byte) (key []byte, err error)

ReadKeyfile reads a randomly generated and encrypted AES-256 key from the file with the given filename and returns it in unencrypted form. The key is protected by a passphrase, which is processed by PBKDF2 to derive the AES-256 key to decrypt the generated key.

func Rekey

func Rekey(dbname string, oldPassphrase, newPassphrase []byte, newIter int) error

Rekey tries to rekey an encrypted database with the given newPassphrase and newIter many KDF iterations. The correct oldPassphrase must be supplied. Thereby, dbname is the prefix of the following two database files (which must already exist):

dbname.db
dbname.key

Rekey replaces the dbname.key file and leaves the dbname.db file unmodified, allowing for very fast rekey operations. In case of error (for example, the database files do not exist or the oldPassphrase is wrong) an error is returned.

func Status

func Status(db *sql.DB) (autoVacuum string, freelistCount int64, err error)

Status returns the autoVacuum and freelistCount of db.

func Vacuum

func Vacuum(db *sql.DB, autoVacuumMode string) error

Vacuum executes VACUUM command in db. If autoVacuumMode is not nil and different from the current one, the auto_vacuum mode is changed before VACUUM is executed.