Fossil SCM

Largely rewrote www/ssl.wiki, it being 7 years since the last update, during which time much has changed in TLS land. Added the initial version of www/tls-nginx.md as a companion article to it, since the topic is too deep to get into within ssl.wiki. Finally, added a new script, tools/fslsrv, referred to by tls-nginx.md, since it's too big to put inline within the article.

wyoung 2019-01-20 01:52 trunk

Commit 062d2bf61bdafe9d9b62e31a48bf19ac324162f75e130a43cfca9f12903359c5

Parent 302ce43947d99c4…

3 files changed +55 +245 -36 +51

+ tools/fslsrv ~ www/ssl.wiki + www/tls-nginx.md

A tools/fslsrv

+55

		--- a/tools/fslsrv
		+++ b/tools/fslsrv
		@@ -0,0 +1,55 @@
	1	+#!/bin/bash
	2	+BFOSSIL=fossil
	3	+PGARGS="-P 1"
	4	+OLDPID=`pgrep -P 1 fossil`
	5	+SITE=https://example.com
	6	+PORT=12345
	7	+
	8	+if [ "$1" = "-f" ] ; then PGARGS= ; shift ; fi
	9	+
	10	+if [ -n "$OLDPID" ]
	11	+then
	12	+ echo "Killing running Fossil server first..."
	13	+ pkill $PGARGS fossil
	14	+
	15	+ for i in $(seq 30)
	16	+ do
	17	+ if [ -n "$(pgrep $PGARGS fossil)" ]
	18	+ then
	19	+ if [ $i -eq 1 ]
	20	+ then
	21	+ echo -n "Waiting for it to die..."
	22	+ else
	23	+ echo -n .
	24	+ fi
	25	+ sleep '0.1'
	26	+ else
	27	+ break
	28	+ fi
	29	+ echo
	30	+ done
	31	+
	32	+ killall -9 fossil 2> /dev/null
	33	+fi
	34	+
	35	+if [ -x ./fossil ]
	36	+then
	37	+ # We're running from a build tree, so use that version instead
	38	+ FOSSIL=./fossil
	39	+fi
	40	+
	41	+function start_one() {
	42	+ bn=$1
	43	+ ln="$2"
	44	+
	45	+ $FO\
	46	+ --port $PORT \
	47	+\
	48	+ --baseurl $urlTE}/$bn \
	49	+ --errorlog ~/log/fossil/$bn-errors.log \
	50	+ ~/museum/$bn.fossil > ~/log/fossil/$bn-stdout.log &
	51	+ echo Started $ln Fossil server, port $PORT, PID $!.
	52	+ PORT=$(($PORT + 1))
	53	+}
	54	+
	55	+star https://foo.net

	--- a/tools/fslsrv
	+++ b/tools/fslsrv
	@@ -0,0 +1,55 @@

	--- a/tools/fslsrv
	+++ b/tools/fslsrv
	@@ -0,0 +1,55 @@
1	#!/bin/bash
2	BFOSSIL=fossil
3	PGARGS="-P 1"
4	OLDPID=`pgrep -P 1 fossil`
5	SITE=https://example.com
6	PORT=12345
7
8	if [ "$1" = "-f" ] ; then PGARGS= ; shift ; fi
9
10	if [ -n "$OLDPID" ]
11	then
12	echo "Killing running Fossil server first..."
13	pkill $PGARGS fossil
14
15	for i in $(seq 30)
16	do
17	if [ -n "$(pgrep $PGARGS fossil)" ]
18	then
19	if [ $i -eq 1 ]
20	then
21	echo -n "Waiting for it to die..."
22	else
23	echo -n .
24	fi
25	sleep '0.1'
26	else
27	break
28	fi
29	echo
30	done
31
32	killall -9 fossil 2> /dev/null
33	fi
34
35	if [ -x ./fossil ]
36	then
37	# We're running from a build tree, so use that version instead
38	FOSSIL=./fossil
39	fi
40
41	function start_one() {
42	bn=$1
43	ln="$2"
44
45	$FO\
46	--port $PORT \
47	\
48	--baseurl $urlTE}/$bn \
49	--errorlog ~/log/fossil/$bn-errors.log \
50	~/museum/$bn.fossil > ~/log/fossil/$bn-stdout.log &
51	echo Started $ln Fossil server, port $PORT, PID $!.
52	PORT=$(($PORT + 1))
53	}
54
55	star https://foo.net

M www/ssl.wiki

+245 -36

		--- www/ssl.wiki
		+++ www/ssl.wiki
		@@ -1,36 +1,245 @@
1		-<title>SSL and Fossil</title>
2		-
3		-<h2>Using SSL with Fossil</h2>
4		-
5		-If you are storing sensitive information in your repository, you should use SSL to encrypt all communications. This will protect the credentials used to access the server, as well preventing eavesdropping of the contents of your repository.
6		-
7		-To host a repository with SSL, you need to use an web server which supports SSL in front of the Fossil server. You can host it using the CGI option or by proxying Fossil's built in HTTP server.
8		-
9		-Your fossil client must be built with SSL support. The <tt>configure</tt> script will attempt to find OpenSSL on your system, but if necessary, you can specify the location with the <tt>--with-openssl</tt> option. Type <tt>./configure --help</tt> for details.
10		-
11		-Make sure the URL you clone from uses the <tt>https:</tt> scheme to ensure you're using SSL. If your server is configured to serve the repository from http as well as https, it's easy to accidentally use unencrypted HTTP if you forget the all important 's'.
12		-
13		-
14		-<h2>Certificates</h2>
15		-
16		-To verify the identify of a server, SSL uses certificates. Fossil needs to know which certificates you trust.
17		-
18		-If you are using a self-signed certificate, 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" to remember your decision.
19		-
20		-If you are using a certificate signed by a certificate authority, you need to specify the certificates you trust with the <tt>ssl-ca-location</tt> setting. Set this globally with the <tt>-global</tt> option for convenience.
21		-
22		-This should be set to the location of a file containing all the PEM encoded certificates you trust. You can obtain a certificate using a web browser, for example, Firefox, or just refer to your system's trusted CA roots which are usually stored somewhere in <tt>/etc</tt>.
23		-
24		-
25		-<h2>Client side certificates</h2>
26		-
27		-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.
28		-
29		-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.
30		-
31		-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.
32		-
33		-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.
34		-
35		-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.
36		-
	1	+<title>TLS and Fossil</title>
	2	+
	3	+<h2>Using TLS-Encrypted Communications with Fossil</h2>
	4	+
	5	+If you are storing sensitive information in a repository accessible over
	6	+a network whose integrity you do not fully trust, you should use TLS to
	7	+encrypt all communications with it. This is most true for repositories
	8	+accessed over the Internet, especially if they will be accessed from
	9	+edge networks you do not control, since that admits of various forms of
	10	+[https://en.wikipedia.org/wiki/Man-in-the-middle_attack\|man in the
	11	+middle attack].
	12	+
	13	+TLS protects the credentials used to access the server, prevents
	14	+eavesdropping, prevents in-flight data modification, prevents server
	15	+identify spoofing, and more.
	16	+
	17	+There are two major aspects to this, both of which have to be addressed
	18	+in different ways. Those are the subjects of the next two major
	19	+sections.
	20	+
	21	+
	22	+<h2 id="client">Client-Side TLS Configuration</h2>
	23	+
	24	+Fossil itself has built-in support for TLS on the client side only. That
	25	+is to say, you can build it against [https://www.openssl.org/\|the
	26	+OpenSSL library], which will allow it to clone and sync with a remote
	27	+Fossil repository via <tt>https</tt> URIs.
	28	+
	29	+The <tt>configure</tt> script will attempt to find OpenSSL on your
	30	+system automatically, but if necessary, you can specify the location
	31	+with the <tt>--with-openssl</tt> option. Type <tt>./configure
	32	+--help</tt> for details.
	33	+
	34	+Even if the Fossil build system does manage to find a workable version
	35	+of OpenSSL, a common situation is that the platform version is outdated
	36	+in some key way, enough so that you do not want to use it with Fossil.
	37	+For example, the platform version of OpenSSL might not support any of
	38	+the [https://en.wikipedia.org/wiki/Cipher_suite\|cipher suites] the
	39	+remote Fossil repository's HTTPS proxy is willing to offer, so that even
	40	+though both sides are speaking TLS/SSL, they can't come to an agreement
	41	+on the cryptography.
	42	+In such cases, you may want to link Fossil to a newer version of OpenSSL
	43	+than the one provided with your client operating system. You can do this
	44	+like so:
	45	+
	46	+<pre>
	47	+ cd compat
	48	+ tar xf /path/to/openssl-*.tar.gz
	49	+ ln -fs openssl-x.y.z openssl
	50	+ ./config # or, e.g. ./Configure darwin64-x86_64-cc
	51	+ make -j11
	52	+ cd ../..
	53	+ ./configure --with-openssl=tree
	54	+ make -j11
	55	+</pre>
	56	+
	57	+That will get you a Fossil binary statically linked to this in-tree
	58	+version of OpenSSL.
	59	+
	60	+
	61	+<h3 id="certs">Certificates</h3>
	62	+
	63	+To verify the identify of a server, TLS uses
	64	+[https://en.wikipedia.org/wiki/X.509#Certificates\|X.509 certificates].
	65	+
	66	+If you are using a self-signed certificate, you'll be asked if you want
	67	+to accept the certificate the first time you communicate with the
	68	+server. Verify the certificate fingerprint is correct, then answer
	69	+"always" to remember your decision.
	70	+
	71	+If you are cloning from or syncing to Fossil servers that use a
	72	+certificate signed by a
	73	+[https://en.wikipedia.org/wiki/Certificate_authority\|certificate
	74	+authority] (CA), Fossil needs to know which CAs you trust to sign those
	75	+certificates. Fossil relies on the OpenSSL library to have some way to
	76	+check a trusted list of CA signing keys.
	77	+
	78	+There are two common ways this fails:
	79	+
	80	+ # <p>The OpenSSL library Fossil is linked to doesn't have a CA
	81	+ signing key set at all, so that it initially trusts no certificates
	82	+ at all.</p>
	83	+ # <p>The OpenSSL library does have a CA cert set, but your Fossil server's
	84	+ TLS certificate was signed by a CA that isn't in that set.</p>
	85	+
	86	+A common reason to fall into the second trap is that you're using
	87	+certificates signed by a local private CA, as often happens in large
	88	+enterprises. You can solve this sort of problem by getting your local
	89	+CA's signing certificate in PEM format and pointing OpenSSL at it:
	90	+
	91	+<pre>
	92	+ fossil set --global ssl-ca-location /path/to/local-ca.pem
	93	+</pre>
	94	+
	95	+The use of <tt>--global</tt> with this option is common, since you may
	96	+have multiple reposotories served under certificates signed by that same
	97	+CA.
	98	+
	99	+A common way to run into the broader first problem is that you're on
	100	+FreeBSD, which does not install a CA certificate set by default, even as
	101	+a dependency of the OpenSSL library. If you're using a certificate
	102	+signed by one of the major public CAs, you can solve this by installing
	103	+the <tt>ca_root_nss</tt> package. That package contains the Mozilla NSS
	104	+certificate bundle, which gets installed in a location that OpenSSL
	105	+checks by default, so you don't need to change any Fossil settings.
	106	+(This is the same certificate set that ships with Firefox, by the way.)
	107	+
	108	+The same sort of thing happens with the Windows build of OpenSSL, but
	109	+for a different core reason: Windows does ship with a stock CA
	110	+certificate set, but it's not in a format that OpenSSL understands how
	111	+to use. Rather than try to find a way to convert the data format, you
	112	+may find it acceptable to use the same Mozilla NSS cert set. I do not
	113	+know of a way to easily get this from Mozilla themselves, but I did find
	114	+a [https://curl.haxx.se/docs/caextract.html\|third party source] for the
	115	+<tt>cacert.pem</tt> file. Install it somewhere on your system, then
	116	+point Fossil at it like so:
	117	+
	118	+<pre>
	119	+ fossil set --global ssl-ca-location /path/to/cacert.pem
	120	+</pre>
	121	+
	122	+Linux platforms tend to provide such a root cert store along with the
	123	+platform OpenSSL package, either built-in or as a hard dependency.
	124	+
	125	+
	126	+<h4>Client-Side Certificates</h4>
	127	+
	128	+You can also use client side certificates to add an extra layer of
	129	+authentication, over and above Fossil's built in user management. If you
	130	+are particularly paranoid, you'll want to use this to remove the ability
	131	+of anyone on the internet from making any request to Fossil. Without
	132	+presenting a valid client side certificate, the web server won't invoke
	133	+the Fossil CGI handler.
	134	+
	135	+Configure your server to request a client side certificate, and set up a
	136	+certificate authority to sign your client certificates. For each person
	137	+who needs to access the repository, create a private key and certificate
	138	+signed with that CA.
	139	+
	140	+The PEM encoded private key and certificate should be stored in a single
	141	+file, simply by concatenating the key and certificate files. Specify the
	142	+location of this file with the <tt>ssl-identity</tt> setting, or the
	143	+<tt>--ssl-identity</tt> option to the <tt>clone</tt> command.
	144	+
	145	+If you've password protected the private key, the password will be
	146	+requested every time you connect to the server. This password is not
	147	+stored by fossil, as doing so would defeat the purpose of having a
	148	+password.
	149	+
	150	+If you attempt to connect to a server which requests a client
	151	+certificate, but don't provide one, fossil will show an error message
	152	+which explains what to do to authenticate with the server.
	153	+
	154	+
	155	+<h2 id="server">Server-Side TLS Configuration</h2>
	156	+
	157	+Fossil's built-in HTTP server feature does not currently have a built-in
	158	+way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked
	159	+Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put
	160	+it behind some kind of HTTPS proxy.
	161	+
	162	+
	163	+<h3 id="stunnel">stunnel Alone</h3>
	164	+
	165	+Conceptually, the simplest option is to [https://www.stunnel.org/\|set up
	166	+stunnel]. A typical configuration is to run Fossil as an HTTP server
	167	+bound to localhost only, then export access to it via HTTPS with stunnel
	168	+encrypting access to Fossil instance hiding behind it.
	169	+
	170	+The difficulty comes in configuring it, which really wants a guide that
	171	+no one has written for us yet. Until that appears, you'll have to read
	172	+the stunnel documentation and that of your TLS certificate provider to
	173	+work out how to set this up.
	174	+
	175	+
	176	+<h3 id="althttpd">stunnel + althttpd</h3>
	177	+
	178	+The public SQLite and Fossil web sites can't just use stunnel + Fossil
	179	+because parts of the web site are static, served by
	180	+[https://www.sqlite.org/docsrc/file/misc/althttpd.c\|a separate web
	181	+server called <tt>althttpd</tt>], written by the primary author of both
	182	+SQLite and Fossil. It is a lightweight HTTP-only web server. It handles
	183	+the static HTTP hits on <tt>sqlite.org</tt> and <tt>fossil-scm.org</tt>,
	184	+delegating HTTPS and dynamic Fossil content hits to stunnel and Fossil.
	185	+
	186	+The only documentation for althttpd currently is in its header comment.
	187	+As is typical for drh software, althttpd is a single-file C program, so
	188	+that at worst, you just have to read its code to understand it.
	189	+
	190	+
	191	+<h3 id="nginx">nginx</h3>
	192	+
	193	+If your needs are more complex than althttpd can handle or you'd prefer
	194	+to use only software available in your server operating system's package
	195	+repository, we recommend that you step up to [http://nginx.org/\|nginx].
	196	+Setting this up is complex enough that we cover it [./tls-nginx.md\|in a
	197	+separate document].
	198	+
	199	+
	200	+<h2 id="enforcing">Enforcing TLS Access</h2>
	201	+
	202	+To use TLS encryption in cloning and syncing to a remote Fossil
	203	+repository, be sure to use the <tt>https:</tt> URI scheme in
	204	+<tt>clone</tt> and <tt>sync</tt> commands. If your server is configured
	205	+to serve the repository via both HTTP and HTTPS, it's easy to
	206	+accidentally use unencrypted HTTP if you forget the all-important 's'.
	207	+
	208	+There is a setting in the Fossil UI under Admin → Access called
	209	+"Redirect to HTTPS on the Login page." This setting is not enabled by
	210	+default. This setting does not automatically upgrade clones and syncs
	211	+done via the <tt>http</tt> URI scheme. It only affects web UI access to
	212	+the Fossil repository.
	213	+
	214	+<b id="rloop">WARNING:</b> Never enable this setting when running Fossil
	215	+behind an HTTPS proxy with Fossil running underneath it via HTTP or
	216	+SCGI. This will cause an infinite redirect loop any time someone tries
	217	+to log into the web UI. Fossil sees that it's being accessed via HTTP,
	218	+so it redirects the browser to an HTTPS equivalent URL, which causes the
	219	+client to hit the HTTPS front end proxy up again for access, which
	220	+causes Fossil to see that it's being accessed via HTTP, so it redirects
	221	+the client to...'round and 'round it goes until the web browser detects
	222	+it's in a redirect loop and gives up.
	223	+
	224	+If you wish to enforce TLS-only access to a Fossil web server, it is
	225	+best done at the HTTPS front-end proxy layer, not by use of Fossil-level
	226	+settings like this one. The [./tls-nginx.md\|nginx TLS proxy guide]
	227	+shows one way to achieve this, for example.
	228	+
	229	+
	230	+<h2>Terminology Note</h2>
	231	+
	232	+This document is called <tt>ssl.wiki</tt> for historical reasons. The
	233	+TLS protocol was originally called SSL, and it went through several
	234	+revisions before being replaced by TLS. Years before this writing, SSL
	235	+finally became entirely obsolete due to weaknesses in the protocol fixed
	236	+in the later TLS series of protocols.
	237	+
	238	+Some people still use the term "SSL" when they actually mean "TLS," but
	239	+in the Fossil project, we always use "TLS" except when we must preserve
	240	+some sort of historical compatibility, as with this document's name in
	241	+order to avoid broken external URLs. The Fossil TLS-related settings
	242	+also often use "`ssl`" in their names, for the same reason.
	243	+
	244	+This series of protocols is also called "HTTPS" after the URI scheme
	245	+used to specify "HTTP over TLS."
37	246
38	247	ADDED www/tls-nginx.md

	--- www/ssl.wiki
	+++ www/ssl.wiki
	@@ -1,36 +1,245 @@
1	<title>SSL and Fossil</title>
2
3	<h2>Using SSL with Fossil</h2>
4
5	If you are storing sensitive information in your repository, you should use SSL to encrypt all communications. This will protect the credentials used to access the server, as well preventing eavesdropping of the contents of your repository.
6
7	To host a repository with SSL, you need to use an web server which supports SSL in front of the Fossil server. You can host it using the CGI option or by proxying Fossil's built in HTTP server.
8
9	Your fossil client must be built with SSL support. The <tt>configure</tt> script will attempt to find OpenSSL on your system, but if necessary, you can specify the location with the <tt>--with-openssl</tt> option. Type <tt>./configure --help</tt> for details.
10
11	Make sure the URL you clone from uses the <tt>https:</tt> scheme to ensure you're using SSL. If your server is configured to serve the repository from http as well as https, it's easy to accidentally use unencrypted HTTP if you forget the all important 's'.
12
13
14	<h2>Certificates</h2>
15
16	To verify the identify of a server, SSL uses certificates. Fossil needs to know which certificates you trust.
17
18	If you are using a self-signed certificate, 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" to remember your decision.
19
20	If you are using a certificate signed by a certificate authority, you need to specify the certificates you trust with the <tt>ssl-ca-location</tt> setting. Set this globally with the <tt>-global</tt> option for convenience.
21
22	This should be set to the location of a file containing all the PEM encoded certificates you trust. You can obtain a certificate using a web browser, for example, Firefox, or just refer to your system's trusted CA roots which are usually stored somewhere in <tt>/etc</tt>.
23
24
25	<h2>Client side certificates</h2>
26
27	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.
28
29	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.
30
31	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.
32
33	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.
34
35	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.
36

















































































































































































































37
38	DDED www/tls-nginx.md

	--- www/ssl.wiki
	+++ www/ssl.wiki
	@@ -1,36 +1,245 @@
1	<title>TLS and Fossil</title>
2
3	<h2>Using TLS-Encrypted Communications with Fossil</h2>
4
5	If you are storing sensitive information in a repository accessible over
6	a network whose integrity you do not fully trust, you should use TLS to
7	encrypt all communications with it. This is most true for repositories
8	accessed over the Internet, especially if they will be accessed from
9	edge networks you do not control, since that admits of various forms of
10	[https://en.wikipedia.org/wiki/Man-in-the-middle_attack\|man in the
11	middle attack].
12
13	TLS protects the credentials used to access the server, prevents
14	eavesdropping, prevents in-flight data modification, prevents server
15	identify spoofing, and more.
16
17	There are two major aspects to this, both of which have to be addressed
18	in different ways. Those are the subjects of the next two major
19	sections.
20
21
22	<h2 id="client">Client-Side TLS Configuration</h2>
23
24	Fossil itself has built-in support for TLS on the client side only. That
25	is to say, you can build it against [https://www.openssl.org/\|the
26	OpenSSL library], which will allow it to clone and sync with a remote
27	Fossil repository via <tt>https</tt> URIs.
28
29	The <tt>configure</tt> script will attempt to find OpenSSL on your
30	system automatically, but if necessary, you can specify the location
31	with the <tt>--with-openssl</tt> option. Type <tt>./configure
32	--help</tt> for details.
33
34	Even if the Fossil build system does manage to find a workable version
35	of OpenSSL, a common situation is that the platform version is outdated
36	in some key way, enough so that you do not want to use it with Fossil.
37	For example, the platform version of OpenSSL might not support any of
38	the [https://en.wikipedia.org/wiki/Cipher_suite\|cipher suites] the
39	remote Fossil repository's HTTPS proxy is willing to offer, so that even
40	though both sides are speaking TLS/SSL, they can't come to an agreement
41	on the cryptography.
42	In such cases, you may want to link Fossil to a newer version of OpenSSL
43	than the one provided with your client operating system. You can do this
44	like so:
45
46	<pre>
47	cd compat
48	tar xf /path/to/openssl-*.tar.gz
49	ln -fs openssl-x.y.z openssl
50	./config # or, e.g. ./Configure darwin64-x86_64-cc
51	make -j11
52	cd ../..
53	./configure --with-openssl=tree
54	make -j11
55	</pre>
56
57	That will get you a Fossil binary statically linked to this in-tree
58	version of OpenSSL.
59
60
61	<h3 id="certs">Certificates</h3>
62
63	To verify the identify of a server, TLS uses
64	[https://en.wikipedia.org/wiki/X.509#Certificates\|X.509 certificates].
65
66	If you are using a self-signed certificate, you'll be asked if you want
67	to accept the certificate the first time you communicate with the
68	server. Verify the certificate fingerprint is correct, then answer
69	"always" to remember your decision.
70
71	If you are cloning from or syncing to Fossil servers that use a
72	certificate signed by a
73	[https://en.wikipedia.org/wiki/Certificate_authority\|certificate
74	authority] (CA), Fossil needs to know which CAs you trust to sign those
75	certificates. Fossil relies on the OpenSSL library to have some way to
76	check a trusted list of CA signing keys.
77
78	There are two common ways this fails:
79
80	# <p>The OpenSSL library Fossil is linked to doesn't have a CA
81	signing key set at all, so that it initially trusts no certificates
82	at all.</p>
83	# <p>The OpenSSL library does have a CA cert set, but your Fossil server's
84	TLS certificate was signed by a CA that isn't in that set.</p>
85
86	A common reason to fall into the second trap is that you're using
87	certificates signed by a local private CA, as often happens in large
88	enterprises. You can solve this sort of problem by getting your local
89	CA's signing certificate in PEM format and pointing OpenSSL at it:
90
91	<pre>
92	fossil set --global ssl-ca-location /path/to/local-ca.pem
93	</pre>
94
95	The use of <tt>--global</tt> with this option is common, since you may
96	have multiple reposotories served under certificates signed by that same
97	CA.
98
99	A common way to run into the broader first problem is that you're on
100	FreeBSD, which does not install a CA certificate set by default, even as
101	a dependency of the OpenSSL library. If you're using a certificate
102	signed by one of the major public CAs, you can solve this by installing
103	the <tt>ca_root_nss</tt> package. That package contains the Mozilla NSS
104	certificate bundle, which gets installed in a location that OpenSSL
105	checks by default, so you don't need to change any Fossil settings.
106	(This is the same certificate set that ships with Firefox, by the way.)
107
108	The same sort of thing happens with the Windows build of OpenSSL, but
109	for a different core reason: Windows does ship with a stock CA
110	certificate set, but it's not in a format that OpenSSL understands how
111	to use. Rather than try to find a way to convert the data format, you
112	may find it acceptable to use the same Mozilla NSS cert set. I do not
113	know of a way to easily get this from Mozilla themselves, but I did find
114	a [https://curl.haxx.se/docs/caextract.html\|third party source] for the
115	<tt>cacert.pem</tt> file. Install it somewhere on your system, then
116	point Fossil at it like so:
117
118	<pre>
119	fossil set --global ssl-ca-location /path/to/cacert.pem
120	</pre>
121
122	Linux platforms tend to provide such a root cert store along with the
123	platform OpenSSL package, either built-in or as a hard dependency.
124
125
126	<h4>Client-Side Certificates</h4>
127
128	You can also use client side certificates to add an extra layer of
129	authentication, over and above Fossil's built in user management. If you
130	are particularly paranoid, you'll want to use this to remove the ability
131	of anyone on the internet from making any request to Fossil. Without
132	presenting a valid client side certificate, the web server won't invoke
133	the Fossil CGI handler.
134
135	Configure your server to request a client side certificate, and set up a
136	certificate authority to sign your client certificates. For each person
137	who needs to access the repository, create a private key and certificate
138	signed with that CA.
139
140	The PEM encoded private key and certificate should be stored in a single
141	file, simply by concatenating the key and certificate files. Specify the
142	location of this file with the <tt>ssl-identity</tt> setting, or the
143	<tt>--ssl-identity</tt> option to the <tt>clone</tt> command.
144
145	If you've password protected the private key, the password will be
146	requested every time you connect to the server. This password is not
147	stored by fossil, as doing so would defeat the purpose of having a
148	password.
149
150	If you attempt to connect to a server which requests a client
151	certificate, but don't provide one, fossil will show an error message
152	which explains what to do to authenticate with the server.
153
154
155	<h2 id="server">Server-Side TLS Configuration</h2>
156
157	Fossil's built-in HTTP server feature does not currently have a built-in
158	way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked
159	Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put
160	it behind some kind of HTTPS proxy.
161
162
163	<h3 id="stunnel">stunnel Alone</h3>
164
165	Conceptually, the simplest option is to [https://www.stunnel.org/\|set up
166	stunnel]. A typical configuration is to run Fossil as an HTTP server
167	bound to localhost only, then export access to it via HTTPS with stunnel
168	encrypting access to Fossil instance hiding behind it.
169
170	The difficulty comes in configuring it, which really wants a guide that
171	no one has written for us yet. Until that appears, you'll have to read
172	the stunnel documentation and that of your TLS certificate provider to
173	work out how to set this up.
174
175
176	<h3 id="althttpd">stunnel + althttpd</h3>
177
178	The public SQLite and Fossil web sites can't just use stunnel + Fossil
179	because parts of the web site are static, served by
180	[https://www.sqlite.org/docsrc/file/misc/althttpd.c\|a separate web
181	server called <tt>althttpd</tt>], written by the primary author of both
182	SQLite and Fossil. It is a lightweight HTTP-only web server. It handles
183	the static HTTP hits on <tt>sqlite.org</tt> and <tt>fossil-scm.org</tt>,
184	delegating HTTPS and dynamic Fossil content hits to stunnel and Fossil.
185
186	The only documentation for althttpd currently is in its header comment.
187	As is typical for drh software, althttpd is a single-file C program, so
188	that at worst, you just have to read its code to understand it.
189
190
191	<h3 id="nginx">nginx</h3>
192
193	If your needs are more complex than althttpd can handle or you'd prefer
194	to use only software available in your server operating system's package
195	repository, we recommend that you step up to [http://nginx.org/\|nginx].
196	Setting this up is complex enough that we cover it [./tls-nginx.md\|in a
197	separate document].
198
199
200	<h2 id="enforcing">Enforcing TLS Access</h2>
201
202	To use TLS encryption in cloning and syncing to a remote Fossil
203	repository, be sure to use the <tt>https:</tt> URI scheme in
204	<tt>clone</tt> and <tt>sync</tt> commands. If your server is configured
205	to serve the repository via both HTTP and HTTPS, it's easy to
206	accidentally use unencrypted HTTP if you forget the all-important 's'.
207
208	There is a setting in the Fossil UI under Admin → Access called
209	"Redirect to HTTPS on the Login page." This setting is not enabled by
210	default. This setting does not automatically upgrade clones and syncs
211	done via the <tt>http</tt> URI scheme. It only affects web UI access to
212	the Fossil repository.
213
214	<b id="rloop">WARNING:</b> Never enable this setting when running Fossil
215	behind an HTTPS proxy with Fossil running underneath it via HTTP or
216	SCGI. This will cause an infinite redirect loop any time someone tries
217	to log into the web UI. Fossil sees that it's being accessed via HTTP,
218	so it redirects the browser to an HTTPS equivalent URL, which causes the
219	client to hit the HTTPS front end proxy up again for access, which
220	causes Fossil to see that it's being accessed via HTTP, so it redirects
221	the client to...'round and 'round it goes until the web browser detects
222	it's in a redirect loop and gives up.
223
224	If you wish to enforce TLS-only access to a Fossil web server, it is
225	best done at the HTTPS front-end proxy layer, not by use of Fossil-level
226	settings like this one. The [./tls-nginx.md\|nginx TLS proxy guide]
227	shows one way to achieve this, for example.
228
229
230	<h2>Terminology Note</h2>
231
232	This document is called <tt>ssl.wiki</tt> for historical reasons. The
233	TLS protocol was originally called SSL, and it went through several
234	revisions before being replaced by TLS. Years before this writing, SSL
235	finally became entirely obsolete due to weaknesses in the protocol fixed
236	in the later TLS series of protocols.
237
238	Some people still use the term "SSL" when they actually mean "TLS," but
239	in the Fossil project, we always use "TLS" except when we must preserve
240	some sort of historical compatibility, as with this document's name in
241	order to avoid broken external URLs. The Fossil TLS-related settings
242	also often use "`ssl`" in their names, for the same reason.
243
244	This series of protocols is also called "HTTPS" after the URI scheme
245	used to specify "HTTP over TLS."
246
247	DDED www/tls-nginx.md

A www/tls-nginx.md

+51

		--- a/www/tls-nginx.md
		+++ b/www/tls-nginx.md
		@@ -0,0 +1,51 @@
	1	+and
	2	+restart nginx with two short commands, which are easily automated
	3	+;
	4	+ you canThis script’s automatic restart feature makes Fossil upgrades easy:
	5	+
	6	+ $ cd ~/src/fossil/trunk ; fossil up ; make ; killall fossil ;
	7	+sudo make install ; fslsrv
	8	+
	9	+I’ve written that as a single long command because I keep it in the
	10	+history for my Fossil servers, so I can just run it again from history.
	11	+You could put it in a shell script instead.n’t be difficult to port to very different systems, like macOS
	12	+ The details are preuse the
	13	+s, we’ve found that the ones that come with
	14	+Ubuntu work just fineACME verification steps can fail., one temporary and the other going forward indefinitely.
	15	+
	16	+First, minted and configured
	17	+Second, the Certbot ACME HTTP-01
	18	+service only runs over HTTP,
	19	+working, or. This
	20	+is the protocol o determinnd
	21	+restart nginx with tinx with two shorjust `google.com`
	22	+and `paypal.com`!You need to do much the same sort of thing as above for each domain name
	23	+hosted by your nginx server.
	24	+
	25	+You might being to wonder, then, why I haven’t
	26	+directives . For example, why caabove just be these two lines:
	27	+
	28	+, we’d like toany of theseACME directory
	29	+restart nginx with two short coo short command domains
	30	+ being
	31	+ you
	32	+ is
	33	+ Since
	34	+ need to
	35	+ single
	36	+and’re looking for that
	37	+here. If
	38	+your web , if the test domain
	39	+is one of the secondary names, as in the example above, `foo.net`cb]: CHACHA20-POLY1305:GCM-SHiocsp
	40	+ when
	41	+it’s initially installed.
	42	+
	43	+T are
	44	+
	45	+
	46	+
	47	+is to recommend static
	48	+
	49	+I assume you’re taking my advice to serve only the least amount of stuff
	50	+over HTTP that you can get away with. Certbot’s ACME HTTP-01
	51	+authentication scheme## Step 6XXXXXXXX

	--- a/www/tls-nginx.md
	+++ b/www/tls-nginx.md
	@@ -0,0 +1,51 @@

	--- a/www/tls-nginx.md
	+++ b/www/tls-nginx.md
	@@ -0,0 +1,51 @@
1	and
2	restart nginx with two short commands, which are easily automated
3	;
4	you canThis script’s automatic restart feature makes Fossil upgrades easy:
5
6	$ cd ~/src/fossil/trunk ; fossil up ; make ; killall fossil ;
7	sudo make install ; fslsrv
8
9	I’ve written that as a single long command because I keep it in the
10	history for my Fossil servers, so I can just run it again from history.
11	You could put it in a shell script instead.n’t be difficult to port to very different systems, like macOS
12	The details are preuse the
13	s, we’ve found that the ones that come with
14	Ubuntu work just fineACME verification steps can fail., one temporary and the other going forward indefinitely.
15
16	First, minted and configured
17	Second, the Certbot ACME HTTP-01
18	service only runs over HTTP,
19	working, or. This
20	is the protocol o determinnd
21	restart nginx with tinx with two shorjust `google.com`
22	and `paypal.com`!You need to do much the same sort of thing as above for each domain name
23	hosted by your nginx server.
24
25	You might being to wonder, then, why I haven’t
26	directives . For example, why caabove just be these two lines:
27
28	, we’d like toany of theseACME directory
29	restart nginx with two short coo short command domains
30	being
31	you
32	is
33	Since
34	need to
35	single
36	and’re looking for that
37	here. If
38	your web , if the test domain
39	is one of the secondary names, as in the example above, `foo.net`cb]: CHACHA20-POLY1305:GCM-SHiocsp
40	when
41	it’s initially installed.
42
43	T are
44
45
46
47	is to recommend static
48
49	I assume you’re taking my advice to serve only the least amount of stuff
50	over HTTP that you can get away with. Certbot’s ACME HTTP-01
51	authentication scheme## Step 6XXXXXXXX

Fossil SCM

Keyboard Shortcuts