Encrypted Repositories

Licensees of the SQLite Encryption Extension, a.k.a. SEE, can build libfossil using their preferred SEE variant (which differs for each encryption type) and use that to encrypt their repository and checkout databases.

Building with SEE support depends on how libfossil is being built:

1. In the canonical source tree, simply drop a copy of sqlite3-see-XYZ.c into the extsrc directory, where XYZ is the desired encryption mode (SEE has, as of this writing, 9 variants).

2. When building against the amalgamation (preferred), simply compile the desired sqlite3-see-XYZ.c into the application.

Minor caveat: when linking against a DLL build of SEE, the API will have to be activated by the client using sqlite3_activate_see(), as covered in the SEE documentation. That does not apply when linking in the sqlite3-... object file directly into the application.

libfossil does not actually know whether it's been built against an SEE-capable sqlite3, and uses the SEE-related pragmas to set a database's encryption key. For non-encrypted databases and non-SEE builds, those pragmas will be harmless no-ops.

The f-apps family of applications, via the fcli mini-framework, all support several CLI flags for setting the key:

• --see-key KEY sets the plain-text key KEY as the encryption key.
• --see-hexkey KEY uses the given hex-encoded key.
• --see-textkey KEY works as per the textkey sqlite3 shell option in the SEE documentation.

For example:

$ f-new my.repo --see-key foo -m "My new encrypted repo."

Will create a new repository encrypted with the given password. Opening it requires providing that same password:

$ f-open --see-key foo /path/to/my.repo
# Equivalent:
$ f-open --see-hexkey 666f6f /path/to/my.repo

Library clients can enable this support when initializing their fsl_cx context, using the fsl_cx_config::see member to define a callback and optional state for that callback. If the callback is not NULL then it is invoked when the library opens a checkout or repository database, in order to collect the encryption key from the client. How the client actually fetches that key is up to the client. Note that a checkout and a repository must have the same encryption key. Opening an encrypted repository into a new checkout will encrypt the checkout with the same key automatically.

Only repository and checkout databases are subject to encryption. The global config database is not encrypted, nor are arbitrary databases opened using the fsl_db API (though clients are free to invoke the appropriate pragmas to encrypt or unlock them).