initial commitHEADmaster

1 files changed, 328 insertions, 0 deletions

diff --git a/www/ssl.wiki b/www/ssl.wiki
new file mode 100644
index 0000000..f9d17cd
--- /dev/null
+++ b/www/ssl.wiki
@@ -0,0 +1,328 @@
+<title>Securing a Repository with TLS</title>
+
+<h2>Using TLS-Encrypted Communications with Fossil</h2>
+
+If you are storing sensitive information in a repository accessible over
+a network whose integrity you do not fully trust, you should use TLS to
+encrypt all communications with it. This is most true for repositories
+accessed over the Internet, especially if they will be accessed from
+edge networks you do not control, since that admits of various forms of
+[https://en.wikipedia.org/wiki/Man-in-the-middle_attack|man in the
+middle attack].
+
+TLS protects the credentials used to access the server, prevents
+eavesdropping, prevents in-flight data modification, prevents server
+identify spoofing, and more.
+
+There are two major aspects to this, both of which have to be addressed
+in different ways. Those are the subjects of the next two major
+sections.
+
+
+<h2 id="client">Client-Side Configuration</h2>
+
+You can build Fossil against [https://www.openssl.org/ |
+OpenSSL] to allow it to clone and sync with a remote
+Fossil repository via <tt>https</tt> URIs.
+
+
+<h3 id="openssl-bin">Building Against OpenSSL Automatically</h3>
+
+The <tt>configure</tt> script will attempt to find OpenSSL on your
+system automatically. It first tries asking the <tt>pkg-config</tt>
+system where the OpenSSL development files are, and if that fails, it
+falls back to looking through a list of likely directories.
+
+If it can't find the files it needs, the most common solution is to
+install the OpenSSL development package on your system via your OS's
+package manager. Examples:
+
+  *  <b>RHEL & Fedora</b>: <tt>sudo dnf install openssl-devel</tt>
+  *  <b>Debian & Ubuntu</b>: <tt>sudo apt install libssl-dev</tt>
+  *  <b>FreeBSD</b>: <tt>su -c 'pkg install openssl'</tt>
+  *  <b>macOS</b>: <tt>sudo brew install openssl</tt>
+  *  <b>Cygwin</b>: Install <tt>openssl-devel</tt> via Cygwin's
+     <tt>setup-*.exe</tt> program
+
+The macOS case requires explanation. Apple last shipped OpenSSL
+develpoment files in OS X 10.6 (Snow Leopard), choosing to deprecate it
+from that point forward. (Apple wants you to use their proprietary
+platform-specific encryption methods instead.) Since macOS has no
+built-in package manager, a number have sprung up out of the FOSS world.
+It is not known to this author whether Fossil's current build system can
+find OpenSSL as installed with any of these other package managers, so
+unless you have a particular reason to avoid it, we recomend that you
+use [https://brew.sh|Homebrew] on macOS to install OpenSSL as above.
+Fossil's build system will seek it out and use it automatically.
+
+
+<h3 id="openssl-src">Building Against a Non-Platform Version of
+OpenSSL</h3>
+
+The Fossil build system has a few other methods for finding OpenSSL when
+the automatic methods fail or when you'd prefer that Fossil use a
+different version of OpenSSL than the one Fossil's build system picks on
+its own.
+
+A good reason to do this is when the Fossil build system finds a
+functioning version of OpenSSL which is nevertheless unsuitable. One
+common case is that your OS is sufficiently outdated that the platform
+version of OpenSSL can no longer communicate with remote systems
+adhering to the latest advice on secure communications. An old OpenSSL
+might not support any of the
+[https://en.wikipedia.org/wiki/Cipher_suite|cipher suites] the remote
+Fossil repository's HTTPS proxy is willing to offer, for example, so
+that even though both sides are speaking a variant of TLS/SSL, the peers
+cannot come to an agreement on the cryptography.
+
+If you've installed the OpenSSL development files somewhere that
+Fossil's build system cannot find on its own, you can clue it in by
+passing the <tt>--with-openssl</tt> option to the <tt>configure</tt>
+script. Type <tt>./configure --help</tt> for details.
+
+Another option is to download the source code to OpenSSL and build
+Fossil against that private version of OpenSSL:
+
+<pre>
+cd compat             # relative to the Fossil source tree root
+tar xf /path/to/openssl-*.tar.gz
+ln -fs openssl-x.y.z openssl
+cd openssl
+./config              # or, e.g. ./Configure darwin64-x86_64-cc
+make -j11
+cd ../..
+./configure --with-openssl=tree
+make -j11
+</pre>
+
+That will get you a Fossil binary statically linked to this in-tree
+version of OpenSSL.
+
+Beware, taking this path typically opens you up to new problems, which
+are conveniently covered in the next section!
+
+
+<h3 id="certs">Certificates</h3>
+
+To verify the identify of a server, TLS uses
+[https://en.wikipedia.org/wiki/X.509#Certificates|X.509 certificates], a
+scheme that depends on a trust hierarchy of so-called
+[https://en.wikipedia.org/wiki/Certificate_authority | Certificate
+Authorities]. The tree of trust relationships ultimately ends in the
+CA roots, which are considered the ultimate arbiters of who to trust in
+this scheme.
+
+The question then is, what CA roots does Fossil trust?
+
+If you are using a self-signed certificate, Fossil will initially not
+know that it can trust your certificate, so you'll be asked if you want
+to accept the certificate the first time you communicate with the
+server. Verify the certificate fingerprint is correct, then answer
+"always" if you want Fossil to remember your decision.
+
+If you are cloning from or syncing to Fossil servers that use a
+certificate signed by a well-known CA or one of its delegates, Fossil
+still has to know which CA roots to trust. When this fails, you get an
+error message that looks like this:
+
+<pre>
+Unable to verify SSL cert from fossil-scm.org
+  subject: CN = sqlite.org
+  issuer:  C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3
+  sha256:  bf26092dd97df6e4f7bf1926072e7e8d200129e1ffb8ef5276c1e5dd9bc95d52
+accept this cert and continue (y/N)?
+</pre>
+
+In older versions, the message was much longer and began with this line:
+
+<pre>
+SSL verification failed: unable to get local issuer certificate
+</pre>
+
+Fossil relies on the OpenSSL library to have some way to check a trusted
+list of CA signing keys. There are two common ways this fails:
+
+  #  The OpenSSL library Fossil is linked to doesn't have a CA
+     signing key set at all, so that it initially trusts no certificates
+     at all.
+
+  #  The OpenSSL library does have a CA cert set, but your Fossil server's
+     TLS certificate was signed by a CA that isn't in that set.
+
+A common reason to fall into the second trap is that you're using
+certificates signed by a local private CA, as often happens in large
+enterprises.  You can solve this sort of problem by getting your local
+CA's signing certificate in PEM format and pointing OpenSSL at it:
+
+<pre>
+fossil set --global ssl-ca-location /path/to/local-ca.pem
+</pre>
+
+The use of <tt>--global</tt> with this option is common, since you may
+have multiple repositories served under certificates signed by that same
+CA. However, if you have a mix of publicly-signed and locally-signed
+certificates, you might want to drop the <tt>--global</tt> flag and set
+this option on a per-repository basis instead.
+
+A common way to run into the broader first problem is that you're on
+FreeBSD, which does not install a CA certificate set by default, even as
+a dependency of the OpenSSL library.  If you're using a certificate
+signed by one of the major public CAs, you can solve this by installing
+the <tt>ca_root_nss</tt> package. That package contains the Mozilla NSS
+certificate bundle, which gets installed in a location that OpenSSL
+checks by default, so you don't need to change any Fossil settings.
+(This is the same certificate set that ships with Firefox, by the way.)
+
+The same sort of thing happens with the Windows build of OpenSSL, but
+for a different core reason: Windows does ship with a stock CA
+certificate set, but it's not in a format that OpenSSL understands how
+to use.  Rather than try to find a way to convert the data format, you
+may find it acceptable to use the same Mozilla NSS cert set.  I do not
+know of a way to easily get this from Mozilla themselves, but I did find
+a [https://curl.se/docs/caextract.html | third party source] for the
+<tt>cacert.pem</tt> file. I suggest placing the file into your Windows
+user home directory so that you can then point Fossil at it like so:
+
+<pre>
+fossil set --global ssl-ca-location %userprofile%\cacert.pem
+</pre>
+
+This can also happen if you've linked Fossil to a version of OpenSSL
+[#openssl-src|built from source]. That same <tt>cacert.pem</tt> fix can
+work in that case, too.
+
+<blockquote>
+OpenSSL 3.2.0 or greater is able to use the stock CA certificates
+managed by Windows, and Fossil 2.25 (still in development as of
+2024-07-15) takes advantage of this feature. This <em>possibly</em>
+eliminates the need to manually install the Mozilla certificate package,
+for example when connecting to Fossil servers secured by the widely-used
+Let's Encrypt certificates. Run the following command to check if the
+feature is supported:
+
+<pre>
+fossil tls-config show -v
+</pre>
+
+(See the "OpenSSL-winstore" section, requires Fossil 2.25 or greater.)
+</blockquote>
+
+When you build Fossil on Linux platforms against the binary OpenSSL
+package provided with the OS, you typically get a root cert store along
+with the platform OpenSSL package, either built-in or as a hard
+dependency.
+
+
+<h4>Client-Side Certificates</h4>
+
+You can also use client side certificates to add an extra layer of
+authentication, over and above Fossil's built in user management. If you
+are particularly paranoid, you'll want to use this to remove the ability
+of anyone on the internet from making any request to Fossil. Without
+presenting a valid client side certificate, the web server won't invoke
+the Fossil CGI handler.
+
+Configure your server to request a client side certificate, and set up a
+certificate authority to sign your client certificates. For each person
+who needs to access the repository, create a private key and certificate
+signed with that CA.
+
+The PEM encoded private key and certificate should be stored in a single
+file, simply by concatenating the key and certificate files. Specify the
+location of this file with the <tt>ssl-identity</tt> setting, or the
+<tt>--ssl-identity</tt> option to the <tt>clone</tt> command.
+
+If you've password protected the private key, the password will be
+requested every time you connect to the server. This password is not
+stored by fossil, as doing so would defeat the purpose of having a
+password.
+
+If you attempt to connect to a server which requests a client
+certificate, but don't provide one, fossil will show an error message
+which explains what to do to authenticate with the server.
+
+
+<h2 id="server">Server-Side Configuration</h2>
+
+Before Fossil's built-in HTTP server gained [./ssl-server.md | TLS support],
+system administrators that wanted to add this
+had to put it behind a reverse proxy that would do the translation.
+Since advantages remain for delegating TLS to another layer in the
+stack, instructions for doing so continue to be included in our
+documentation, such as:
+
+  *  <a id="stunnel"  href="./server/any/stunnel.md">Serving via stunnel</a>
+  *  <a id="althttpd" href="./server/any/althttpd.md">Serving via stunnel + althttpd</a>
+  *  <a id="nginx"    href="./server/debian/nginx.md#tls">Serving via SCGI with nginx on Debian</a>
+
+
+<h2 id="enforcing">Enforcing TLS Access</h2>
+
+To use TLS encryption in cloning and syncing to a remote Fossil
+repository, be sure to use the <tt>https:</tt> URI scheme in
+<tt>clone</tt> and <tt>sync</tt> commands.  If your server is configured
+to serve the repository via both HTTP and HTTPS, it's easy to
+accidentally use unencrypted HTTP if you forget the all-important 's'.
+
+As of Fossil 2.9, using an <tt>http://</tt> URI with <tt>fossil
+clone</tt> or <tt>sync</tt> on a site that forwards to HTTPS will cause
+Fossil to remember the secure URL. However, there's a
+[https://en.wikipedia.org/wiki/Trust_on_first_use | TOFU problem] with
+this: it's still better to use <tt>https://</tt> from the start.
+
+As of Fossil 2.8, there is a setting in the Fossil UI under Admin &rarr;
+Access called "Redirect to HTTPS," which is set to "Off" by default.
+Changing this only affects web UI access to the Fossil repository. It
+doesn't affect clones and syncs done via the <tt>http</tt> URI scheme.
+
+In Fossil 2.7 and earlier, there was a much weaker form of this setting
+affecting the <tt>/login</tt> page only. If you're using this setting,
+you should migrate to the new setting as soon as possible, because the
+old setting allows multiple ways of defeating it.
+
+<b id="rloop">WARNING:</b> Enabling HTTPS redirects at the Fossil repo
+level while running Fossil behind an HTTPS proxy can result in an
+infinite redirect loop.  It happens when the proxy mechanism presents
+"<tt>http</tt>" URIs to Fossil, so Fossil issues a redirect, so the browser
+fetches the page again, causing Fossil to see an "<tt>http</tt>" URI again, so
+it issues a redirect...'round and 'round it goes until the web browser
+detects it's in a redirect loop and gives up. This problem prevents you
+from getting back into the Admin UI to fix it, but there are several
+ways to fix it:
+
+  #  <b>Reset via CLI.</b> You can turn the setting back off from the
+     CLI with the command "<tt>fossil -R /path/to/repo.fossil set
+     redirect-to-https 0</tt>". (Currently doesn't work.)
+
+  #  <b>Backup first.</b> This setting is stored in the Fossil
+     repository, so if you make a backup first <i>on the server</i>, you
+     can restore the repo file if enabling this feature creates a
+     redirect loop.
+
+  #  <b>Download, fix, and restore.</b> You can copy the remote
+     repository file down to a local machine, use <tt>fossil ui</tt> to
+     fix the setting, and then upload it to the repository server
+     again.
+
+It's best to enforce TLS-only access at the front-end proxy level
+anyway. It not only avoids the problem entirely, it can be significantly
+more secure.  The [./server/debian/nginx.md#tls | nginx-on-Debian proxy guide] shows one way
+to achieve this.
+
+
+<h2>Terminology Note</h2>
+
+This document is called <tt>ssl.wiki</tt> for historical reasons. The
+TLS protocol was originally called SSL, and it went through several
+revisions before being replaced by TLS. Years before this writing, SSL
+finally became entirely obsolete due to weaknesses in the protocol fixed
+in the later TLS series of protocols.
+
+Some people still use the term "SSL" when they actually mean "TLS," but
+in the Fossil project, we always use "TLS" except when we must preserve
+some sort of historical compatibility, as with this document's name in
+order to avoid broken external URLs.  The Fossil TLS-related settings
+also often use "<tt>ssl</tt>" in their names for the same reason.
+
+This series of protocols is also called "HTTPS" after the URI scheme
+used to specify "HTTP over TLS."