Fossil SCM
Moved the mTLS section of www/ssl.wiki down into the server-side configuration as one motivating example of why you'd still want to run Fossil behind a TLS-aware RP. Clarified how all this works without duplicating the RP-specific details.
Commit
3506473c271d33df08a8ea3304c8d3fcdc5ac71513f1f5844b778bd0565c400c
Parent
df389b91f111193…
1 file changed
+45
-30
+45
-30
| --- www/ssl.wiki | ||
| +++ www/ssl.wiki | ||
| @@ -195,53 +195,68 @@ | ||
| 195 | 195 | When you build Fossil on Linux platforms against the binary OpenSSL |
| 196 | 196 | package provided with the OS, you typically get a root cert store along |
| 197 | 197 | with the platform OpenSSL package, either built-in or as a hard |
| 198 | 198 | dependency. |
| 199 | 199 | |
| 200 | - | |
| 201 | -<h4>Client-Side Certificates</h4> | |
| 202 | - | |
| 203 | -You can also use client side certificates to add an extra layer of | |
| 204 | -authentication, over and above Fossil's built in user management. If you | |
| 205 | -are particularly paranoid, you'll want to use this to remove the ability | |
| 206 | -of anyone on the internet from making any request to Fossil. Without | |
| 207 | -presenting a valid client side certificate, the web server won't invoke | |
| 208 | -the Fossil CGI handler. | |
| 209 | - | |
| 210 | -Configure your server to request a client side certificate, and set up a | |
| 211 | -certificate authority to sign your client certificates. For each person | |
| 212 | -who needs to access the repository, create a private key and certificate | |
| 213 | -signed with that CA. | |
| 214 | - | |
| 215 | -The PEM encoded private key and certificate should be stored in a single | |
| 216 | -file, simply by concatenating the key and certificate files. Specify the | |
| 217 | -location of this file with the <tt>ssl-identity</tt> setting, or the | |
| 218 | -<tt>--ssl-identity</tt> option to the <tt>clone</tt> command. | |
| 219 | - | |
| 220 | -If you've password protected the private key, the password will be | |
| 221 | -requested every time you connect to the server. This password is not | |
| 222 | -stored by fossil, as doing so would defeat the purpose of having a | |
| 223 | -password. | |
| 224 | - | |
| 225 | -If you attempt to connect to a server which requests a client | |
| 226 | -certificate, but don't provide one, fossil will show an error message | |
| 227 | -which explains what to do to authenticate with the server. | |
| 228 | - | |
| 229 | 200 | |
| 230 | 201 | <h2 id="server">Server-Side Configuration</h2> |
| 231 | 202 | |
| 232 | 203 | Before Fossil's built-in HTTP server gained [./ssl-server.md | TLS support], |
| 233 | 204 | system administrators that wanted to add this |
| 234 | -had to put it behind a reverse proxy that would do the translation. | |
| 205 | +had to put it behind a reverse proxy (RP) that would do the translation. | |
| 235 | 206 | Since advantages remain for delegating TLS to another layer in the |
| 236 | 207 | stack, instructions for doing so continue to be included in our |
| 237 | 208 | documentation, such as: |
| 238 | 209 | |
| 239 | 210 | * <a id="stunnel" href="./server/any/stunnel.md">Serving via stunnel</a> |
| 240 | 211 | * <a id="althttpd" href="./server/any/althttpd.md">Serving via stunnel + althttpd</a> |
| 241 | 212 | * <a id="nginx" href="./server/debian/nginx.md#tls">Serving via SCGI with nginx on Debian</a> |
| 242 | 213 | |
| 214 | +One such case is… | |
| 215 | + | |
| 216 | + | |
| 217 | +<h3>Client-Side Certificates</h3> | |
| 218 | + | |
| 219 | +One way to harden a Fossil server is to require the <i>clients</i> to | |
| 220 | +provide their own certificates. This builds on top of the normal TLS | |
| 221 | +scheme of having the <i>server</i> identify itself to the clients, | |
| 222 | +producing an [https://en.wikipedia.org/wiki/Mutual_authentication#mTLS | | |
| 223 | +mTLS] scheme. This prevents random Internet hosts from establishing a | |
| 224 | +connection to the RP fronting your Fossil server. | |
| 225 | + | |
| 226 | +Because Fossil's own built-in TLS serving features do not include mTLS | |
| 227 | +support, this is one of the solid reasons for continuing to run Fossil | |
| 228 | +behind a third-party TLS-aware RP. | |
| 229 | + | |
| 230 | +The method varies by the RP you choose to delegate this to, and because | |
| 231 | +there is no tie-in with the configuration of the proxied Fossil server, | |
| 232 | +we do not include duplicate documentation of it here. The basic idea is | |
| 233 | +simple enough to sketch here, however: set the RP up to require client | |
| 234 | +certificates, generate one per client using a mutually-recognized | |
| 235 | +certificate authority, and register the public half with the RP. Only | |
| 236 | +those clients possessing a matching private half of one of those | |
| 237 | +registered key-pairs will then be able to establish an mTLS connection | |
| 238 | +to the server. | |
| 239 | + | |
| 240 | +The Fossil client side does require special configuration to make this | |
| 241 | +work. First, ensure that the PEM private key file also contains the | |
| 242 | +public certificate; this is common, though not universal. (If not, | |
| 243 | +simply concatenate the two in cert-then-key order.) Second, tell your | |
| 244 | +Fossil client where to find that combined PEM file, either via the | |
| 245 | +<tt>ssl-identity</tt> setting or by giving the <tt>--ssl-identity</tt> | |
| 246 | +global option to each <tt>fossil</tt> command using the sync protocol | |
| 247 | +with a server configured to require mTLS. | |
| 248 | + | |
| 249 | +If you've passphrase-protected that PEM file, Fossil will prompt you for | |
| 250 | +it as part of setting up each of these mTLS-protected sync sessions. | |
| 251 | +Unlike the regular sync password, Fossil will not offer to store this | |
| 252 | +PEM passphrase. | |
| 253 | + | |
| 254 | +If you attempt to connect to a server which requests a client | |
| 255 | +certificate but fail to provide one, Fossil will issue a warning | |
| 256 | +which explains what to do to authenticate with the server. | |
| 257 | + | |
| 243 | 258 | |
| 244 | 259 | <h2 id="enforcing">Enforcing TLS Access</h2> |
| 245 | 260 | |
| 246 | 261 | To use TLS encryption in cloning and syncing to a remote Fossil |
| 247 | 262 | repository, be sure to use the <tt>https:</tt> URI scheme in |
| 248 | 263 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -195,53 +195,68 @@ | |
| 195 | When you build Fossil on Linux platforms against the binary OpenSSL |
| 196 | package provided with the OS, you typically get a root cert store along |
| 197 | with the platform OpenSSL package, either built-in or as a hard |
| 198 | dependency. |
| 199 | |
| 200 | |
| 201 | <h4>Client-Side Certificates</h4> |
| 202 | |
| 203 | You can also use client side certificates to add an extra layer of |
| 204 | authentication, over and above Fossil's built in user management. If you |
| 205 | are particularly paranoid, you'll want to use this to remove the ability |
| 206 | of anyone on the internet from making any request to Fossil. Without |
| 207 | presenting a valid client side certificate, the web server won't invoke |
| 208 | the Fossil CGI handler. |
| 209 | |
| 210 | Configure your server to request a client side certificate, and set up a |
| 211 | certificate authority to sign your client certificates. For each person |
| 212 | who needs to access the repository, create a private key and certificate |
| 213 | signed with that CA. |
| 214 | |
| 215 | The PEM encoded private key and certificate should be stored in a single |
| 216 | file, simply by concatenating the key and certificate files. Specify the |
| 217 | location of this file with the <tt>ssl-identity</tt> setting, or the |
| 218 | <tt>--ssl-identity</tt> option to the <tt>clone</tt> command. |
| 219 | |
| 220 | If you've password protected the private key, the password will be |
| 221 | requested every time you connect to the server. This password is not |
| 222 | stored by fossil, as doing so would defeat the purpose of having a |
| 223 | password. |
| 224 | |
| 225 | If you attempt to connect to a server which requests a client |
| 226 | certificate, but don't provide one, fossil will show an error message |
| 227 | which explains what to do to authenticate with the server. |
| 228 | |
| 229 | |
| 230 | <h2 id="server">Server-Side Configuration</h2> |
| 231 | |
| 232 | Before Fossil's built-in HTTP server gained [./ssl-server.md | TLS support], |
| 233 | system administrators that wanted to add this |
| 234 | had to put it behind a reverse proxy that would do the translation. |
| 235 | Since advantages remain for delegating TLS to another layer in the |
| 236 | stack, instructions for doing so continue to be included in our |
| 237 | documentation, such as: |
| 238 | |
| 239 | * <a id="stunnel" href="./server/any/stunnel.md">Serving via stunnel</a> |
| 240 | * <a id="althttpd" href="./server/any/althttpd.md">Serving via stunnel + althttpd</a> |
| 241 | * <a id="nginx" href="./server/debian/nginx.md#tls">Serving via SCGI with nginx on Debian</a> |
| 242 | |
| 243 | |
| 244 | <h2 id="enforcing">Enforcing TLS Access</h2> |
| 245 | |
| 246 | To use TLS encryption in cloning and syncing to a remote Fossil |
| 247 | repository, be sure to use the <tt>https:</tt> URI scheme in |
| 248 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -195,53 +195,68 @@ | |
| 195 | When you build Fossil on Linux platforms against the binary OpenSSL |
| 196 | package provided with the OS, you typically get a root cert store along |
| 197 | with the platform OpenSSL package, either built-in or as a hard |
| 198 | dependency. |
| 199 | |
| 200 | |
| 201 | <h2 id="server">Server-Side Configuration</h2> |
| 202 | |
| 203 | Before Fossil's built-in HTTP server gained [./ssl-server.md | TLS support], |
| 204 | system administrators that wanted to add this |
| 205 | had to put it behind a reverse proxy (RP) that would do the translation. |
| 206 | Since advantages remain for delegating TLS to another layer in the |
| 207 | stack, instructions for doing so continue to be included in our |
| 208 | documentation, such as: |
| 209 | |
| 210 | * <a id="stunnel" href="./server/any/stunnel.md">Serving via stunnel</a> |
| 211 | * <a id="althttpd" href="./server/any/althttpd.md">Serving via stunnel + althttpd</a> |
| 212 | * <a id="nginx" href="./server/debian/nginx.md#tls">Serving via SCGI with nginx on Debian</a> |
| 213 | |
| 214 | One such case is… |
| 215 | |
| 216 | |
| 217 | <h3>Client-Side Certificates</h3> |
| 218 | |
| 219 | One way to harden a Fossil server is to require the <i>clients</i> to |
| 220 | provide their own certificates. This builds on top of the normal TLS |
| 221 | scheme of having the <i>server</i> identify itself to the clients, |
| 222 | producing an [https://en.wikipedia.org/wiki/Mutual_authentication#mTLS | |
| 223 | mTLS] scheme. This prevents random Internet hosts from establishing a |
| 224 | connection to the RP fronting your Fossil server. |
| 225 | |
| 226 | Because Fossil's own built-in TLS serving features do not include mTLS |
| 227 | support, this is one of the solid reasons for continuing to run Fossil |
| 228 | behind a third-party TLS-aware RP. |
| 229 | |
| 230 | The method varies by the RP you choose to delegate this to, and because |
| 231 | there is no tie-in with the configuration of the proxied Fossil server, |
| 232 | we do not include duplicate documentation of it here. The basic idea is |
| 233 | simple enough to sketch here, however: set the RP up to require client |
| 234 | certificates, generate one per client using a mutually-recognized |
| 235 | certificate authority, and register the public half with the RP. Only |
| 236 | those clients possessing a matching private half of one of those |
| 237 | registered key-pairs will then be able to establish an mTLS connection |
| 238 | to the server. |
| 239 | |
| 240 | The Fossil client side does require special configuration to make this |
| 241 | work. First, ensure that the PEM private key file also contains the |
| 242 | public certificate; this is common, though not universal. (If not, |
| 243 | simply concatenate the two in cert-then-key order.) Second, tell your |
| 244 | Fossil client where to find that combined PEM file, either via the |
| 245 | <tt>ssl-identity</tt> setting or by giving the <tt>--ssl-identity</tt> |
| 246 | global option to each <tt>fossil</tt> command using the sync protocol |
| 247 | with a server configured to require mTLS. |
| 248 | |
| 249 | If you've passphrase-protected that PEM file, Fossil will prompt you for |
| 250 | it as part of setting up each of these mTLS-protected sync sessions. |
| 251 | Unlike the regular sync password, Fossil will not offer to store this |
| 252 | PEM passphrase. |
| 253 | |
| 254 | If you attempt to connect to a server which requests a client |
| 255 | certificate but fail to provide one, Fossil will issue a warning |
| 256 | which explains what to do to authenticate with the server. |
| 257 | |
| 258 | |
| 259 | <h2 id="enforcing">Enforcing TLS Access</h2> |
| 260 | |
| 261 | To use TLS encryption in cloning and syncing to a remote Fossil |
| 262 | repository, be sure to use the <tt>https:</tt> URI scheme in |
| 263 |