From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001
From: cashmere <cashmere@autistici.org>
Date: Fri, 4 Sep 2026 09:05:24 +0200
Subject: initial commit

---
 www/encryptedrepos.wiki | 82 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 www/encryptedrepos.wiki

(limited to 'www/encryptedrepos.wiki')

diff --git a/www/encryptedrepos.wiki b/www/encryptedrepos.wiki
new file mode 100644
index 0000000..c9eb923
--- /dev/null
+++ b/www/encryptedrepos.wiki
@@ -0,0 +1,82 @@
+<title>How To Use Encrypted Repositories</title>
+
+<h2>Introduction</h2>
+
+Fossil can be compiled so that it works with encrypted repositories using
+the [https://www.sqlite.org/see/doc/trunk/www/readme.wiki|SQLite Encryption Extension].
+This technical note explains the process.
+
+<h2>Building An Encryption-Enabled Fossil</h2>
+
+The SQLite Encryption Extension (SEE) is proprietary software and requires
+[https://sqlite.org/purchase/see|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 extsrc/ 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 extsrc/ 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.
+
+<pre>
+./configure --with-see; make
+</pre>
+
+To build for Windows using MSVC, add
+the "USE_SEE=1" argument to the "nmake" command line.
+
+<pre>
+nmake -f makefile.msc USE_SEE=1
+</pre>
+
+<h2>Using Encrypted Repositories</h2>
+
+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.
+
+<h2>Additional Security</h2>
+
+Use the FOSSIL_SECURITY_LEVEL environment for additional protection.
+
+<pre>
+export FOSSIL_SECURITY_LEVEL=1
+</pre>
+
+A setting of 1 or greater
+prevents fossil from trying to remember the previous sync password.
+
+<pre>
+export FOSSIL_SECURITY_LEVEL=2
+</pre>
+
+A setting of 2 or greater
+causes all password prompts to be preceded by a random translation matrix similar
+to the following:
+
+<pre>
+abcde fghij klmno pqrst uvwyz
+qresw gjymu dpcoa fhkzv inlbt
+</pre>
+
+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.
-- 
cgit v1.3.1