Introduction

Fossil can be compiled so that it works with encrypted repositories using the SQLite Encryption Extension. This technical note explains the process.

Building An Encryption-Enabled Fossil

The SQLite Encryption Extension (SEE) is proprietary software and requires purchasing a license.

Assuming you have an SEE license, the first step of compiling Fossil to use SEE is to create an SEE-enabled version of the SQLite database source code. This alternative SQLite database source file should be called "sqlite3-see.c" and should be placed in the src/ subfolder of the Fossil sources, right beside the public-domain "sqlite3.c" source file. Also make a copy of the SEE-enabled "shell.c" file, renamed as "shell-see.c", and place it in the src/ subfolder beside the original "shell.c".

Add the --with-see command-line option to the configuration script to enable the use of SEE on unix-like systems.

./configure --with-see; make

To build for Windows using MSVC, add the "USE_SEE=1" argument to the "nmake" command line.

nmake -f makefile.msc USE_SEE=1

Using Encrypted Repositories

Any Fossil repositories whose filename ends with ".efossil" is taken to be an encrypted repository. Fossil will prompt for the encryption password and attempt to open the repository database using that password.

Every invocation of fossil on an encrypted repository requires retyping the encryption password. To avoid excess password typing, consider using the "fossil shell" command which prompts for the password just once, then reuses it for each subsequent Fossil command entered at the prompt.

On Windows, the "fossil server", "fossil ui", and "fossil shell" commands do not (currently) work on an encrypted repository.

Additional Security

Use the FOSSIL_SECURITY_LEVEL environment for additional protection.

export FOSSIL_SECURITY_LEVEL=1

A setting of 1 or greater prevents fossil from trying to remember the previous sync password.

export FOSSIL_SECURITY_LEVEL=2

A setting of 2 or greater causes all password prompts to be preceeded by a random translation matrix similar to the following:

abcde fghij klmno pqrst uvwyz
qresw gjymu dpcoa fhkzv inlbt

When entering the password, the user must substitute the letter on the second line that corresponds to the letter on the first line. Uppercase substitutes for uppercase inputs, and lowercase substitutes for lowercase inputs. Letters that are not in the translation matrix (digits, punctuation, and "x") are not modified. For example, given the translation matrix above, if the password is "pilot-9crazy-xube", then the user must type "fmpav-9ekqtb-xirw". This simple substitution cypher helps prevent password capture by keyloggers.