Documentation.

Author: ncruces

vfs/adiantum/api.go

@@ -1,19 +1,29 @@
 // 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.
+// Adiantum tweakable, length-preserving encryption.
 //
-// Importing package adiantum registers that VFS.
+// 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.
-// This is done through [URI] parameters:
+//
+// 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, use any of the following PRAGMAs:
+//
+//	PRAGMA key='D41d8cD98f00b204e9800998eCf8427e';
+//	PRAGMA hexkey='e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+//	PRAGMA textkey='your-secret-key';
+//
 // [URI]: https://sqlite.org/uri.html
 package adiantum
 

vfs/adiantum/hbsh.go

@@ -87,9 +87,9 @@ func (h *hbshFile) Pragma(name string, value string) (string, error) {
 
 func (h *hbshFile) ReadAt(p []byte, off int64) (n int, err error) {
 	if h.hbsh == nil {
-		// If it's trying to read the header, pretend the file is empty,
-		// so the key can be specified later.
 		if off == 0 && len(p) == 100 {
+			// SQLite is trying to read the header of a database.
+			// Pretend the file is empty so the key can be specified later.
 			return 0, io.EOF
 		}
 		return 0, sqlite3.CANTOPEN

vfs/memdb/api.go

@@ -4,7 +4,7 @@
 // among multiple database connections in the same process,
 // as long as the database name begins with "/".
 //
-// Importing package memdb registers the VFS.
+// Importing package memdb registers the VFS:
 //
 //	import _ "github.com/ncruces/go-sqlite3/vfs/memdb"
 package memdb

vfs/readervfs/api.go

@@ -3,7 +3,7 @@
 // The "reader" [vfs.VFS] permits accessing any [io.ReaderAt]
 // as an immutable SQLite database.
 //
-// Importing package readervfs registers the VFS.
+// Importing package readervfs registers the VFS:
 //
 //	import _ "github.com/ncruces/go-sqlite3/vfs/readervfs"
 package readervfs