adiantum

README

Go adiantum SQLite VFS

This package wraps an SQLite VFS to offer encryption at rest.

The "adiantum" VFS wraps the default SQLite VFS using the Adiantum tweakable and length-preserving encryption.
In general, any HBSH construction can be used to wrap any VFS.

The default Adiantum construction uses XChaCha12 for its stream cipher, AES for its block cipher, and NH and Poly1305 for hashing.
Additionally, we use Argon2id to derive 256-bit keys from plain text where needed. File contents are encrypted in 4K blocks, matching the default SQLite page size.

The VFS encrypts all files except super journals: these never contain database data, only filenames, and padding them to the block size is problematic. Temporary files are encrypted with random keys, as they may contain database data. To avoid the overhead of encrypting temporary files, keep them in memory:

PRAGMA temp_store = memory;

[!IMPORTANT] Adiantum is a cipher composition for disk encryption. The standard threat model for disk encryption considers an adversary that can read multiple snapshots of a disk. The only security property that disk encryption provides is that all information such an adversary can obtain is whether the data in a sector has or has not changed over time.

The encryption offered by this package is fully deterministic.

This means that an adversary who can get ahold of multiple snapshots (e.g. backups) of a database file can learn precisely: which blocks changed, which ones didn't, which got reverted.

This is slightly weaker than other forms of SQLite encryption that include some nondeterminism; with limited nondeterminism, an adversary can't distinguish between blocks that actually changed, and blocks that got reverted.

[!CAUTION] This package does not claim protect databases against tampering or forgery.

The major practical consequence of the above point is that, if you're keeping "adiantum" encrypted backups of your database, and want to protect against forgery, you should sign your backups, and verify signatures before restoring them.

This is slightly weaker than other forms of SQLite encryption that include block-level MACs. Block-level MACs can protect against forging individual blocks, but can't prevent them from being reverted to former versions of themselves.

Documentation

Overview

Package adiantum wraps an SQLite VFS to offer encryption at rest.

The "adiantum" vfs.VFS wraps the default VFS using the Adiantum tweakable, length-preserving encryption.

Importing package adiantum registers that VFS:

import _ "github.com/ncruces/go-sqlite3/vfs/adiantum"

To open an encrypted database you need to provide key material.

The simplest way to do that is to specify the key through an URI parameter:

• key: key material in binary (32 bytes)
• hexkey: key material in hex (64 hex digits)
• textkey: key material in text (any length)

However, this makes your key easily accessible to other parts of your application (e.g. through vfs.Filename.URIParameters).

To avoid this, invoke any of the following PRAGMAs immediately after opening a connection:

PRAGMA key='D41d8cD98f00b204e9800998eCf8427e';
PRAGMA hexkey='e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
PRAGMA textkey='your-secret-key';

For an ATTACH-ed database, you must specify the schema name:

ATTACH DATABASE 'demo.db' AS demo;
PRAGMA demo.textkey='your-secret-key';

Index

• func Register(name string, base vfs.VFS, cipher HBSHCreator)
• type HBSHCreator

Examples

• Register (Hpolyc)

Functions

func Register

func Register(name string, base vfs.VFS, cipher HBSHCreator)

Register registers an encrypting VFS, wrapping a base VFS, and possibly using a custom HBSH cipher construction. To use the default Adiantum construction, set cipher to nil.

Example (Hpolyc)

//go:build (linux || darwin || windows || freebsd || openbsd || netbsd || dragonfly || illumos || sqlite3_flock) && !sqlite3_nosys

package main

import (
	"crypto/rand"
	"log"
	"os"

	"github.com/ncruces/go-sqlite3"
	"github.com/ncruces/go-sqlite3/vfs"
	"github.com/ncruces/go-sqlite3/vfs/adiantum"
	"golang.org/x/crypto/argon2"
	"lukechampine.com/adiantum/hbsh"
	"lukechampine.com/adiantum/hpolyc"
)

func main() {
	adiantum.Register("hpolyc", vfs.Find(""), hpolycCreator{})

	db, err := sqlite3.Open("file:demo.db?vfs=hpolyc" +
		"&textkey=correct+horse+battery+staple")
	if err != nil {
		log.Fatal(err)
	}
	defer os.Remove("./demo.db")
	defer db.Close()
}

type hpolycCreator struct{}

// HBSH creates an HBSH cipher given a key.
func (hpolycCreator) HBSH(key []byte) *hbsh.HBSH {
	if len(key) != 32 {
		// Key is not appropriate, return nil.
		return nil
	}
	return hpolyc.New(key)
}

// KDF gets a key from a secret.
func (hpolycCreator) KDF(secret string) []byte {
	if secret == "" {
		// No secret is given, generate a random key.
		key := make([]byte, 32)
		n, _ := rand.Read(key)
		return key[:n]
	}
	// Hash the secret with a KDF.
	return argon2.IDKey([]byte(secret), []byte("hpolyc"), 3, 64*1024, 4, 32)
}

Types

type HBSHCreator

type HBSHCreator interface {
	// KDF derives an HBSH key from a secret.
	// If no secret is given, a random key is generated.
	KDF(secret string) (key []byte)

	// HBSH creates an HBSH cipher given a key.
	// If key is not appropriate, nil is returned.
	HBSH(key []byte) *hbsh.HBSH
}

HBSHCreator creates an hbsh.HBSH cipher given key material.