Fossil

Check-in [a13820dc]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Expanded the discussion of OpenSSL options in www/ssl.wiki, mainly adding advice on installing it via package managers. The new OpenSSL discussion in build.wiki now points to this, rather than to the next section level up, as in the prior checkin.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: a13820dc042b9e6a27cd9cfca44bf20c15b5d5dbc38fad23230e29e7b0bec1d2
User & Date: wyoung 2019-01-28 18:29:52.103
Context
2019-01-28
19:25
Assorted improvements to www/tls-nginx.md ... (check-in: e629c1b7 user: wyoung tags: trunk)
18:29
Expanded the discussion of OpenSSL options in www/ssl.wiki, mainly adding advice on installing it via package managers. The new OpenSSL discussion in build.wiki now points to this, rather than to the next section level up, as in the prior checkin. ... (check-in: a13820dc user: wyoung tags: trunk)
17:54
Expanded the section on --with-openssl=none in www/build.wiki to explain why adding that option is a bad idea, what to do instead, and to point to the newly expanded OpenSSL discussion in www/ssl.wiki for more information. ... (check-in: 4f810279 user: wyoung tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to www/build.wiki.
︙︙
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111


<p>If you do not have the OpenSSL development libraries on your system,
we recommend that you install them, typically via your OS's package
manager. The Fossil build system goes to a lot of effort to seek these
out wherever they may be found, so that is typically all you need to
do.</p>

<p>For more advanced use cases, see the [./ssl.wiki#client|OpenSSL
discussion in the "TLS and Fossil" document].</p>

<li><p>
To build a statically linked binary (suitable for use inside a chroot
jail) add the <b>--static</b> option.

<li><p>








|








97
98
99
100
101
102
103
104
105
106
107
108
109
110
111


<p>If you do not have the OpenSSL development libraries on your system,
we recommend that you install them, typically via your OS's package
manager. The Fossil build system goes to a lot of effort to seek these
out wherever they may be found, so that is typically all you need to
do.</p>

<p>For more advanced use cases, see the [./ssl.wiki#openssl-bin|OpenSSL
discussion in the "TLS and Fossil" document].</p>

<li><p>
To build a statically linked binary (suitable for use inside a chroot
jail) add the <b>--static</b> option.

<li><p>
︙︙
Changes to www/ssl.wiki.
︙︙
15
16
17
18
19
20
21
22
23
24
25
26
27
28



29



30



























31
32
33
34
35
36

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58



59
60
61
62
63
64
65

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 TLS Configuration</h2>

Fossil itself has built-in support for TLS on the client side only. That
is to say, you can build it against [https://www.openssl.org/|the
OpenSSL library], which will allow it to clone and sync with a remote
Fossil repository via <tt>https</tt> URIs.




The <tt>configure</tt> script will attempt to find OpenSSL on your



system automatically, but if necessary, you can specify the location



























with the <tt>--with-openssl</tt> option. Type <tt>./configure
--help</tt> for details.

Even if the Fossil build system does manage to find a workable version
of OpenSSL, a common situation is that the platform version is outdated
in some key way, enough so that you do not want to use it with Fossil.

For example, the platform version of 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, so that even
though both sides are speaking TLS/SSL, they can't come to an agreement
on the cryptography.
In such cases, you may want to link Fossil to a newer version of OpenSSL
than the one provided with your client operating system. You can do this
like so:

<pre>
    cd compat
    tar xf /path/to/openssl-*.tar.gz
    ln -fs openssl-x.y.z 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.





<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].









|






>
>
>

>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
|


|
|
>
|
|
|
|
|
|
|
|














>
>
>








15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

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">Fossil TLS Configuration: Client Side</h2>

Fossil itself has built-in support for TLS on the client side only. That
is to say, you can build it against [https://www.openssl.org/|the
OpenSSL library], which will allow it to clone and sync with a remote
Fossil repository via <tt>https</tt> URIs.


<h3 id="openssl-bin">Building Against a Binary Version of OpenSSL</h3>

The <tt>configure</tt> script will attempt to find OpenSSL on your
system automatically. 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 yum 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 can also find and use OpenSSL in nonstandard
locations.

If you've installed OpenSSL via a method 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.

Even if the Fossil build system does manage to find a workable version
of OpenSSL, it is possible that the platform version is outdated in some
key way, enough so that you do not want to use it with Fossil. (The
chance of this happening increases as your OS ages.) For example, the
platform version of 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, so that even though
both sides are speaking a variant of TLS/SSL, they can't come to an
agreement on the cryptography.  In such cases, you may want to link
Fossil to a newer version of OpenSSL than the one available in your OS's
package repository. You can do this like so, from the root of the Fossil
source tree:

<pre>
    cd compat
    tar xf /path/to/openssl-*.tar.gz
    ln -fs openssl-x.y.z 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].
︙︙
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

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 TLS Configuration</h2>

Fossil's built-in HTTP server feature does not currently have a built-in
way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked
Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put
it behind some kind of HTTPS proxy.










|








185
186
187
188
189
190
191
192
193
194
195
196
197
198
199

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">Fossil TLS Configuration: Server Side</h2>

Fossil's built-in HTTP server feature does not currently have a built-in
way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked
Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put
it behind some kind of HTTPS proxy.
︙︙