Docs.

Author: ncruces

vfs/adiantum/README.md

@@ -53,6 +53,11 @@ 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](https://en.wikipedia.org/wiki/Message_authentication_code).
-Block-level MACs can protect against forging individual blocks,
+that include page-level [MACs](https://en.wikipedia.org/wiki/Message_authentication_code).
+Page-level MACs can protect against forging individual pages,
 but can't prevent them from being reverted to former versions of themselves.
+
+> [!NOTICE]
+> The [`"xts"`](../xts/README.md) package also offers encryption at rest.
+
+AES-XTS uses _only_ NIST and FIPS-140 approved cryptographic primitives.

vfs/xts/README.md

@@ -1,3 +1,64 @@
 # Go `xts` SQLite VFS
 
-This package wraps an SQLite VFS to offer encryption at rest.
+This package wraps an SQLite VFS to offer encryption at rest.
+
+The `"xts"` VFS wraps the default SQLite VFS using the
+[AES-XTS](https://pkg.go.dev/golang.org/x/crypto/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](https://pkg.go.dev/golang.org/x/crypto/pbkdf2)
+to derive AES-128 keys from plain text where needed.
+File contents are encrypted in 512 byte sectors, matching the
+[minimum](https://sqlite.org/fileformat.html#pages) SQLite page size.
+
+The VFS encrypts all files _except_
+[super journals](https://sqlite.org/tempfiles.html#super_journal_files):
+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 slightly weaker than other forms of SQLite encryption
+that include *some* nondeterminism; with limited nondeterminism,
+an adversary can't distinguish between
+sectors that actually changed, and sectors 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 `"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 slightly weaker than other forms of SQLite encryption
+that include page-level [MACs](https://en.wikipedia.org/wiki/Message_authentication_code).
+Page-level MACs can protect against forging individual pages,
+but can't prevent them from being reverted to former versions of themselves.
+
+> [!NOTICE]
+> The [`"adiantum"`](../adiantum/README.md) package also offers encryption at rest.
+
+In general Adiantum performs significantly better,
+and is a "wide-block" cipher which _may_ offer improved security.

vfs/xts/api.go

@@ -1,4 +1,36 @@
 // 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';
+//
+// [URI]: https://sqlite.org/uri.html
 package xts
 
 import (