Documentation.

Author: ncruces

vfs/adiantum/README.md

@@ -16,14 +16,23 @@ 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.
-It uses Argon2id to derive 256-bit keys from plain text.
+Additionally, we use Argon2id to derive 256-bit keys from plain text.
 
-The VFS encrypts database files, rollback and statement journals, and WAL files.
+The VFS encrypts all files _except_
+[super journals](https://sqlite.org/tempfiles.html#super_journal_files):
+super journals _never_ contain database data, only filenames,
+and padding them to the block size is problematic.
+
+Temporary files _are_ encrypted, as they _will_ contain database data.
+To avoid the overhead of encrypting temporary files,
+keep them in memory:
+
+    PRAGMA temp_store = memory;
 
 > [!IMPORTANT]
 > Adiantum is typically used for disk encryption.
 > The standard threat model for disk encryption considers an adversary
 > that can read multiple snapshots of a disk.
-> The security property that disk encryption provides is that
-> the only information such an adversary can determine is
-> whether the data in a sector has or has not changed over time.
+> The only security property that disk encryption (and this package)
+> provides is that the only information such an adversary can determine
+> is whether the data in a sector has or has not changed over time.

vfs/adiantum/hbsh.go

@@ -22,11 +22,8 @@ func (h *hbshVFS) Open(name string, flags vfs.OpenFlag) (vfs.File, vfs.OpenFlag,
 }
 
 func (h *hbshVFS) OpenParams(name string, flags vfs.OpenFlag, params url.Values) (file vfs.File, _ vfs.OpenFlag, err error) {
-	encrypt := flags&(0|
-		vfs.OPEN_MAIN_DB|
-		vfs.OPEN_MAIN_JOURNAL|
-		vfs.OPEN_SUBJOURNAL|
-		vfs.OPEN_WAL) != 0
+	// Encrypt everything except super journals.
+	encrypt := flags&vfs.OPEN_SUPER_JOURNAL == 0
 
 	var hbsh *hbsh.HBSH
 	if encrypt {

vfs/memdb/memdb.go

@@ -11,12 +11,22 @@ import (
 	"github.com/ncruces/go-sqlite3/vfs"
 )
 
+// Must be a multiple of 64K (the largest page size).
+const sectorSize = 65536
+
 type memVFS struct{}
 
 func (memVFS) Open(name string, flags vfs.OpenFlag) (vfs.File, vfs.OpenFlag, error) {
-	// Allowed file types:
+	// For simplicity, we do not support reading or writing data
+	// across "sector" boundaries.
+	//
+	// This is not a problem for most SQLite file types:
 	// - databases, which only do page aligned reads/writes;
-	// - temp journals, used by the sorter, which does the same.
+	// - temp journals, as used by the sorter, which does the same:
+	//   https://sqlite.org/src/artifact/237840?ln=409-412
+	//
+	// We refuse to open all other file types,
+	// but returning OPEN_MEMORY means SQLite won't ask us to.
 	const types = vfs.OPEN_MAIN_DB |
 		vfs.OPEN_TRANSIENT_DB |
 		vfs.OPEN_TEMP_DB |
@@ -61,9 +71,6 @@ func (memVFS) FullPathname(name string) (string, error) {
 	return name, nil
 }
 
-// Must be a multiple of 64K (the largest page size).
-const sectorSize = 65536
-
 type memDB struct {
 	// +checklocks:lockMtx
 	pending *memFile