Fossil SCM
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.
Commit
a13820dc042b9e6a27cd9cfca44bf20c15b5d5dbc38fad23230e29e7b0bec1d2
Parent
4f810279ceee617…
2 files changed
+1
-1
+52
-14
+1
-1
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -99,11 +99,11 @@ | ||
| 99 | 99 | we recommend that you install them, typically via your OS's package |
| 100 | 100 | manager. The Fossil build system goes to a lot of effort to seek these |
| 101 | 101 | out wherever they may be found, so that is typically all you need to |
| 102 | 102 | do.</p> |
| 103 | 103 | |
| 104 | -<p>For more advanced use cases, see the [./ssl.wiki#client|OpenSSL | |
| 104 | +<p>For more advanced use cases, see the [./ssl.wiki#openssl-bin|OpenSSL | |
| 105 | 105 | discussion in the "TLS and Fossil" document].</p> |
| 106 | 106 | |
| 107 | 107 | <li><p> |
| 108 | 108 | To build a statically linked binary (suitable for use inside a chroot |
| 109 | 109 | jail) add the <b>--static</b> option. |
| 110 | 110 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -99,11 +99,11 @@ | |
| 99 | we recommend that you install them, typically via your OS's package |
| 100 | manager. The Fossil build system goes to a lot of effort to seek these |
| 101 | out wherever they may be found, so that is typically all you need to |
| 102 | do.</p> |
| 103 | |
| 104 | <p>For more advanced use cases, see the [./ssl.wiki#client|OpenSSL |
| 105 | discussion in the "TLS and Fossil" document].</p> |
| 106 | |
| 107 | <li><p> |
| 108 | To build a statically linked binary (suitable for use inside a chroot |
| 109 | jail) add the <b>--static</b> option. |
| 110 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -99,11 +99,11 @@ | |
| 99 | we recommend that you install them, typically via your OS's package |
| 100 | manager. The Fossil build system goes to a lot of effort to seek these |
| 101 | out wherever they may be found, so that is typically all you need to |
| 102 | do.</p> |
| 103 | |
| 104 | <p>For more advanced use cases, see the [./ssl.wiki#openssl-bin|OpenSSL |
| 105 | discussion in the "TLS and Fossil" document].</p> |
| 106 | |
| 107 | <li><p> |
| 108 | To build a statically linked binary (suitable for use inside a chroot |
| 109 | jail) add the <b>--static</b> option. |
| 110 |
+52
-14
| --- www/ssl.wiki | ||
| +++ www/ssl.wiki | ||
| @@ -17,33 +17,67 @@ | ||
| 17 | 17 | There are two major aspects to this, both of which have to be addressed |
| 18 | 18 | in different ways. Those are the subjects of the next two major |
| 19 | 19 | sections. |
| 20 | 20 | |
| 21 | 21 | |
| 22 | -<h2 id="client">Client-Side TLS Configuration</h2> | |
| 22 | +<h2 id="client">Fossil TLS Configuration: Client Side</h2> | |
| 23 | 23 | |
| 24 | 24 | Fossil itself has built-in support for TLS on the client side only. That |
| 25 | 25 | is to say, you can build it against [https://www.openssl.org/|the |
| 26 | 26 | OpenSSL library], which will allow it to clone and sync with a remote |
| 27 | 27 | Fossil repository via <tt>https</tt> URIs. |
| 28 | 28 | |
| 29 | + | |
| 30 | +<h3 id="openssl-bin">Building Against a Binary Version of OpenSSL</h3> | |
| 31 | + | |
| 29 | 32 | 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 | |
| ---help</tt> for details. | ||
| 33 | +system automatically. If it can't find the files it needs, the most | |
| 34 | +common solution is to install the OpenSSL development package on your | |
| 35 | +system via your OS's package manager. Examples: | |
| 36 | + | |
| 37 | + * <b>RHEL & Fedora</b>: <tt>sudo yum install openssl-devel</tt> | |
| 38 | + * <b>Debian & Ubuntu</b>: <tt>sudo apt install libssl-dev</tt> | |
| 39 | + * <b>FreeBSD</b>: <tt>su -c 'pkg install openssl'</tt> | |
| 40 | + * <b>macOS</b>: <tt>sudo brew install openssl</tt> | |
| 41 | + * <b>Cygwin</b>: Install <tt>openssl-devel</tt> via Cygwin's | |
| 42 | + <tt>setup-*.exe</tt> program | |
| 43 | + | |
| 44 | +The macOS case requires explanation. Apple last shipped OpenSSL | |
| 45 | +develpoment files in OS X 10.6 (Snow Leopard), choosing to deprecate it | |
| 46 | +from that point forward. (Apple wants you to use their proprietary | |
| 47 | +platform-specific encryption methods instead.) Since macOS has no | |
| 48 | +built-in package manager, a number have sprung up out of the FOSS world. | |
| 49 | +It is not known to this author whether Fossil's current build system can | |
| 50 | +find OpenSSL as installed with any of these other package managers, so | |
| 51 | +unless you have a particular reason to avoid it, we recomend that you | |
| 52 | +use [https://brew.sh|Homebrew] on macOS to install OpenSSL as above. | |
| 53 | +Fossil's build system will seek it out and use it automatically. | |
| 54 | + | |
| 55 | + | |
| 56 | +<h3 id="openssl-src">Building Against a Non-Platform Version of | |
| 57 | +OpenSSL</h3> | |
| 58 | + | |
| 59 | +The Fossil build system can also find and use OpenSSL in nonstandard | |
| 60 | +locations. | |
| 61 | + | |
| 62 | +If you've installed OpenSSL via a method that Fossil's build system | |
| 63 | +cannot find on its own, you can clue it in by passing the | |
| 64 | +<tt>--with-openssl</tt> option to the <tt>configure</tt> script. Type | |
| 65 | +<tt>./configure --help</tt> for details. | |
| 32 | 66 | |
| 33 | 67 | Even if the Fossil build system does manage to find a workable version |
| 34 | -of OpenSSL, a common situation is that the platform version is outdated | |
| 35 | -in some key way, enough so that you do not want to use it with Fossil. | |
| 36 | -For example, the platform version of OpenSSL might not support any of | |
| 37 | -the [https://en.wikipedia.org/wiki/Cipher_suite|cipher suites] the | |
| 38 | -remote Fossil repository's HTTPS proxy is willing to offer, so that even | |
| 39 | -though both sides are speaking TLS/SSL, they can't come to an agreement | |
| 40 | -on the cryptography. | |
| 41 | -In such cases, you may want to link Fossil to a newer version of OpenSSL | |
| 42 | -than the one provided with your client operating system. You can do this | |
| 43 | -like so: | |
| 68 | +of OpenSSL, it is possible that the platform version is outdated in some | |
| 69 | +key way, enough so that you do not want to use it with Fossil. (The | |
| 70 | +chance of this happening increases as your OS ages.) For example, the | |
| 71 | +platform version of OpenSSL might not support any of the | |
| 72 | +[https://en.wikipedia.org/wiki/Cipher_suite|cipher suites] the remote | |
| 73 | +Fossil repository's HTTPS proxy is willing to offer, so that even though | |
| 74 | +both sides are speaking a variant of TLS/SSL, they can't come to an | |
| 75 | +agreement on the cryptography. In such cases, you may want to link | |
| 76 | +Fossil to a newer version of OpenSSL than the one available in your OS's | |
| 77 | +package repository. You can do this like so, from the root of the Fossil | |
| 78 | +source tree: | |
| 44 | 79 | |
| 45 | 80 | <pre> |
| 46 | 81 | cd compat |
| 47 | 82 | tar xf /path/to/openssl-*.tar.gz |
| 48 | 83 | ln -fs openssl-x.y.z openssl |
| @@ -54,10 +88,13 @@ | ||
| 54 | 88 | make -j11 |
| 55 | 89 | </pre> |
| 56 | 90 | |
| 57 | 91 | That will get you a Fossil binary statically linked to this in-tree |
| 58 | 92 | version of OpenSSL. |
| 93 | + | |
| 94 | +Beware, taking this path typically opens you up to new problems, which | |
| 95 | +are conveniently covered in the next section! | |
| 59 | 96 | |
| 60 | 97 | |
| 61 | 98 | <h3 id="certs">Certificates</h3> |
| 62 | 99 | |
| 63 | 100 | To verify the identify of a server, TLS uses |
| @@ -150,11 +187,11 @@ | ||
| 150 | 187 | If you attempt to connect to a server which requests a client |
| 151 | 188 | certificate, but don't provide one, fossil will show an error message |
| 152 | 189 | which explains what to do to authenticate with the server. |
| 153 | 190 | |
| 154 | 191 | |
| 155 | -<h2 id="server">Server-Side TLS Configuration</h2> | |
| 192 | +<h2 id="server">Fossil TLS Configuration: Server Side</h2> | |
| 156 | 193 | |
| 157 | 194 | Fossil's built-in HTTP server feature does not currently have a built-in |
| 158 | 195 | way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked |
| 159 | 196 | Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put |
| 160 | 197 | it behind some kind of HTTPS proxy. |
| 161 | 198 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -17,33 +17,67 @@ | |
| 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 |
| ---help</tt> for details. | |
| 32 | |
| 33 | Even if the Fossil build system does manage to find a workable version |
| 34 | of OpenSSL, a common situation is that the platform version is outdated |
| 35 | in some key way, enough so that you do not want to use it with Fossil. |
| 36 | For example, the platform version of OpenSSL might not support any of |
| 37 | the [https://en.wikipedia.org/wiki/Cipher_suite|cipher suites] the |
| 38 | remote Fossil repository's HTTPS proxy is willing to offer, so that even |
| 39 | though both sides are speaking TLS/SSL, they can't come to an agreement |
| 40 | on the cryptography. |
| 41 | In such cases, you may want to link Fossil to a newer version of OpenSSL |
| 42 | than the one provided with your client operating system. You can do this |
| 43 | like so: |
| 44 | |
| 45 | <pre> |
| 46 | cd compat |
| 47 | tar xf /path/to/openssl-*.tar.gz |
| 48 | ln -fs openssl-x.y.z openssl |
| @@ -54,10 +88,13 @@ | |
| 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 |
| @@ -150,11 +187,11 @@ | |
| 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 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -17,33 +17,67 @@ | |
| 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">Fossil TLS Configuration: Client Side</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 | |
| 30 | <h3 id="openssl-bin">Building Against a Binary Version of OpenSSL</h3> |
| 31 | |
| 32 | The <tt>configure</tt> script will attempt to find OpenSSL on your |
| ---help</tt> for details. | |
| 33 | system automatically. If it can't find the files it needs, the most |
| 34 | common solution is to install the OpenSSL development package on your |
| 35 | system via your OS's package manager. Examples: |
| 36 | |
| 37 | * <b>RHEL & Fedora</b>: <tt>sudo yum install openssl-devel</tt> |
| 38 | * <b>Debian & Ubuntu</b>: <tt>sudo apt install libssl-dev</tt> |
| 39 | * <b>FreeBSD</b>: <tt>su -c 'pkg install openssl'</tt> |
| 40 | * <b>macOS</b>: <tt>sudo brew install openssl</tt> |
| 41 | * <b>Cygwin</b>: Install <tt>openssl-devel</tt> via Cygwin's |
| 42 | <tt>setup-*.exe</tt> program |
| 43 | |
| 44 | The macOS case requires explanation. Apple last shipped OpenSSL |
| 45 | develpoment files in OS X 10.6 (Snow Leopard), choosing to deprecate it |
| 46 | from that point forward. (Apple wants you to use their proprietary |
| 47 | platform-specific encryption methods instead.) Since macOS has no |
| 48 | built-in package manager, a number have sprung up out of the FOSS world. |
| 49 | It is not known to this author whether Fossil's current build system can |
| 50 | find OpenSSL as installed with any of these other package managers, so |
| 51 | unless you have a particular reason to avoid it, we recomend that you |
| 52 | use [https://brew.sh|Homebrew] on macOS to install OpenSSL as above. |
| 53 | Fossil's build system will seek it out and use it automatically. |
| 54 | |
| 55 | |
| 56 | <h3 id="openssl-src">Building Against a Non-Platform Version of |
| 57 | OpenSSL</h3> |
| 58 | |
| 59 | The Fossil build system can also find and use OpenSSL in nonstandard |
| 60 | locations. |
| 61 | |
| 62 | If you've installed OpenSSL via a method that Fossil's build system |
| 63 | cannot find on its own, you can clue it in by passing the |
| 64 | <tt>--with-openssl</tt> option to the <tt>configure</tt> script. Type |
| 65 | <tt>./configure --help</tt> for details. |
| 66 | |
| 67 | Even if the Fossil build system does manage to find a workable version |
| 68 | of OpenSSL, it is possible that the platform version is outdated in some |
| 69 | key way, enough so that you do not want to use it with Fossil. (The |
| 70 | chance of this happening increases as your OS ages.) For example, the |
| 71 | platform version of OpenSSL might not support any of the |
| 72 | [https://en.wikipedia.org/wiki/Cipher_suite|cipher suites] the remote |
| 73 | Fossil repository's HTTPS proxy is willing to offer, so that even though |
| 74 | both sides are speaking a variant of TLS/SSL, they can't come to an |
| 75 | agreement on the cryptography. In such cases, you may want to link |
| 76 | Fossil to a newer version of OpenSSL than the one available in your OS's |
| 77 | package repository. You can do this like so, from the root of the Fossil |
| 78 | source tree: |
| 79 | |
| 80 | <pre> |
| 81 | cd compat |
| 82 | tar xf /path/to/openssl-*.tar.gz |
| 83 | ln -fs openssl-x.y.z openssl |
| @@ -54,10 +88,13 @@ | |
| 88 | make -j11 |
| 89 | </pre> |
| 90 | |
| 91 | That will get you a Fossil binary statically linked to this in-tree |
| 92 | version of OpenSSL. |
| 93 | |
| 94 | Beware, taking this path typically opens you up to new problems, which |
| 95 | are conveniently covered in the next section! |
| 96 | |
| 97 | |
| 98 | <h3 id="certs">Certificates</h3> |
| 99 | |
| 100 | To verify the identify of a server, TLS uses |
| @@ -150,11 +187,11 @@ | |
| 187 | If you attempt to connect to a server which requests a client |
| 188 | certificate, but don't provide one, fossil will show an error message |
| 189 | which explains what to do to authenticate with the server. |
| 190 | |
| 191 | |
| 192 | <h2 id="server">Fossil TLS Configuration: Server Side</h2> |
| 193 | |
| 194 | Fossil's built-in HTTP server feature does not currently have a built-in |
| 195 | way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked |
| 196 | Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put |
| 197 | it behind some kind of HTTPS proxy. |
| 198 |