xts

README

Go xts SQLite VFS

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

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

The default AES-XTS construction uses AES-128, AES-192, or AES-256 for its block cipher. Additionally, we use PBKDF2-HMAC-SHA512 to derive AES-128 keys from plain text where needed. File contents are encrypted in 512 byte sectors, matching the minimum SQLite page size.

This VFS uses only NIST and FIPS 140-2 approved cryptographic primitives, which may help you become FIPS compliant.

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

PRAGMA temp_store = memory;

[!IMPORTANT] XTS is a cipher mode typically used 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 sectors changed, which ones didn't, which got reverted.

This is weaker than other forms of SQLite encryption that include some nondeterminism. With limited nondeterminism, an adversary can't distinguish between pages that actually changed, and pages that got reverted; a VACUUM can fully rebuild the database file, preventing this differential analysis.

[!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 "xts" encrypted backups of your database, and want to protect against forgery, you should sign your backups, and verify signatures before restoring them.

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

[!TIP] The "adiantum" VFS also offers encryption at rest. In general Adiantum performs significantly better, and as a "wide-block" cipher, may offer improved security.

Documentation

Overview

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

The "xts" vfs.VFS wraps the default VFS using the AES-XTS tweakable, length-preserving encryption.

Importing package xts registers that VFS:

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

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, 48 or 64 bytes)
• hexkey: key material in hex (64, 96 or 128 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 Wrap(base vfs.VFS, cipher XTSCreator) vfs.VFS
• type XTSCreator

Functions

func Wrap

func Wrap(base vfs.VFS, cipher XTSCreator) vfs.VFS

Wrap wraps a base VFS to create an encrypting VFS, possibly using a custom XTS cipher construction.

To use the default AES-XTS construction, set cipher to nil.

The default construction uses AES-128, AES-192, or AES-256 if the key/hexkey is 32, 48, or 64 bytes, respectively. If a textkey is provided, the default KDF is PBKDF2-HMAC-SHA512 with 10,000 iterations, always producing a 32 byte key.

Types

type XTSCreator

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

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

XTSCreator creates an xts.Cipher given key material.