|
1
|
<title>How To Use Encrypted Repositories</title> |
|
2
|
|
|
3
|
<h2>Introduction</h2> |
|
4
|
|
|
5
|
Fossil can be compiled so that it works with encrypted repositories using |
|
6
|
the [https://www.sqlite.org/see/doc/trunk/www/readme.wiki|SQLite Encryption Extension]. |
|
7
|
This technical note explains the process. |
|
8
|
|
|
9
|
<h2>Building An Encryption-Enabled Fossil</h2> |
|
10
|
|
|
11
|
The SQLite Encryption Extension (SEE) is proprietary software and requires |
|
12
|
[https://sqlite.org/purchase/see|purchasing a license]. |
|
13
|
|
|
14
|
Assuming you have an SEE license, the first step of compiling Fossil to |
|
15
|
use SEE is to create an SEE-enabled version of the SQLite database source code. |
|
16
|
This alternative SQLite database source file should be called "sqlite3-see.c" |
|
17
|
and should be placed in the extsrc/ subfolder of the Fossil sources, right beside |
|
18
|
the public-domain "sqlite3.c" source file. Also make a copy of the SEE-enabled |
|
19
|
"shell.c" file, renamed as "shell-see.c", and place it in the extsrc/ subfolder |
|
20
|
beside the original "shell.c". |
|
21
|
|
|
22
|
Add the --with-see command-line option to the configuration script to enable |
|
23
|
the use of SEE on unix-like systems. |
|
24
|
|
|
25
|
<pre> |
|
26
|
./configure --with-see; make |
|
27
|
</pre> |
|
28
|
|
|
29
|
To build for Windows using MSVC, add |
|
30
|
the "USE_SEE=1" argument to the "nmake" command line. |
|
31
|
|
|
32
|
<pre> |
|
33
|
nmake -f makefile.msc USE_SEE=1 |
|
34
|
</pre> |
|
35
|
|
|
36
|
<h2>Using Encrypted Repositories</h2> |
|
37
|
|
|
38
|
Any Fossil repositories whose filename ends with ".efossil" is taken to be |
|
39
|
an encrypted repository. Fossil will prompt for the encryption password and |
|
40
|
attempt to open the repository database using that password. |
|
41
|
|
|
42
|
Every invocation of fossil on an encrypted repository requires retyping the |
|
43
|
encryption password. |
|
44
|
To avoid excess password typing, consider using the "fossil shell" |
|
45
|
command which prompts for the password just once, then reuses it for each |
|
46
|
subsequent Fossil command entered at the prompt. |
|
47
|
|
|
48
|
On Windows, the "fossil server", "fossil ui", and "fossil shell" commands do not |
|
49
|
(currently) work on an encrypted repository. |
|
50
|
|
|
51
|
<h2>Additional Security</h2> |
|
52
|
|
|
53
|
Use the FOSSIL_SECURITY_LEVEL environment for additional protection. |
|
54
|
|
|
55
|
<pre> |
|
56
|
export FOSSIL_SECURITY_LEVEL=1 |
|
57
|
</pre> |
|
58
|
|
|
59
|
A setting of 1 or greater |
|
60
|
prevents fossil from trying to remember the previous sync password. |
|
61
|
|
|
62
|
<pre> |
|
63
|
export FOSSIL_SECURITY_LEVEL=2 |
|
64
|
</pre> |
|
65
|
|
|
66
|
A setting of 2 or greater |
|
67
|
causes all password prompts to be preceded by a random translation matrix similar |
|
68
|
to the following: |
|
69
|
|
|
70
|
<pre> |
|
71
|
abcde fghij klmno pqrst uvwyz |
|
72
|
qresw gjymu dpcoa fhkzv inlbt |
|
73
|
</pre> |
|
74
|
|
|
75
|
When entering the password, the user must substitute the letter on the second |
|
76
|
line that corresponds to the letter on the first line. Uppercase substitutes |
|
77
|
for uppercase inputs, and lowercase substitutes for lowercase inputs. Letters |
|
78
|
that are not in the translation matrix (digits, punctuation, and "x") are not |
|
79
|
modified. For example, given the |
|
80
|
translation matrix above, if the password is "pilot-9crazy-xube", then the user |
|
81
|
must type "fmpav-9ekqtb-xirw". This simple substitution cypher helps prevent |
|
82
|
password capture by keyloggers. |
|
83
|
|