Fossil

Check-in [43166dcd]
Login

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

Overview
Comment:Assorted improvements to the TLS/SSL docs.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:43166dcda39e8f5d39a74924a07ff0f700a3b442ba033bbee16858ad92f7f28a
User & Date: wyoung 2019-01-21 09:38:09
Context
2019-01-21
09:45
Linked the new TLS + nginx guide to an nginx blog on enabling HSTS. check-in: 30d577a7 user: wyoung tags: trunk
09:38
Assorted improvements to the TLS/SSL docs. check-in: 43166dcd user: wyoung tags: trunk
2019-01-20
23:57
Improved rendering of cherrypick merge arrows, especially on the "ardoise" and "eagle" skins. check-in: 9c7fdea8 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/ssl.wiki.

235
236
237
238
239
240
241
242
243
244
245
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 "`ssl`" 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."







|



235
236
237
238
239
240
241
242
243
244
245
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."

Changes to www/tls-nginx.md.

274
275
276
277
278
279
280



281
282
283
284
285
286
287






288
289
290






291
292


293








294


295

296
297
298
299
300
301
302
303
304
305
306
307
308
309









310
311
312
313
314
315
316
...
483
484
485
486
487
488
489





















490
491
492
493
494
495
496
497
...
524
525
526
527
528
529
530




531
532
533
      listen 443 ssl;

      ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
      ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

      ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;




      ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
      ssl_ciphers "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SH
      ssl_session_cache shared:le_nginx_SSL:1m;
      ssl_prefer_server_ciphers on;
      ssl_session_timeout 1440m;

These are the common TLS configuration parameters used by all domains






hosted by this server. Since all of those domains share a single TLS
certificate, we reference the same `example.com/*.pem` files written out
by Certbot here. We also reference the common server-specific






Diffie-Hellman parameter file written by the Let’s Encrypt package when
it’s initially installed.











The `ssl_protocols` and `ssl_ciphers` lines are prone to bit-rot: as new


attacks on TLS and its associated technologies are discovered, this

configuration is likely to need to change. Even if we fully succeed in
[keeping this document up-to-date](#evolution), the nature of this guide
is to recommend static configurations for your server. You will have to
keep an eye on this sort of thing and evolve your local configuration as
the world changes around it.

Running a TLS certificate checker against your site occasionally is a
good idea. The most thorough service I’m aware of is the [Qualys SSL
Labs Test][qslt], which gives the site I’m basing this guide on an “A”
rating at the time of this writing.

I assume you’re taking my advice to serve only the least amount of stuff
over HTTP that you can get away with. Certbot’s ACME HTTP-01
authentication scheme is one of those few things.











### HTTP-Only Service

While we’d prefer not to offer HTTP service at all, we need to do so for
two reasons, one temporary and the other going forward indefinitely.

................................................................................
This forced redirect is why we don’t need the Fossil Admin &rarr; Access
"Redirect to HTTPS on the Login page" setting to be enabled.  Not only
is it unnecessary with this HTTPS redirect at the front-end proxy level,
it would actually [cause an infinite redirect loop if
enabled](./ssl.wiki#rloop).























## Step 6: Renewing Automatically

Now that the configuration is solid, you can renew the LE cert and
restart nginx with two short commands, which are easily automated:

      sudo certbot certonly --webroot
      sudo systemctl restart nginx

................................................................................
keeps an eye on the forum and expects to keep this document updated with
ideas that appear in that thread.

[2016]: https://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg22907.html
[cb]:   https://certbot.eff.org/
[cbnu]: https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx
[fd]:   https://fossil-scm.org/forum/forumpost/ae6a4ee157




[qslt]: https://www.ssllabs.com/ssltest/
[scgi]: https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface
[vps]:  https://en.wikipedia.org/wiki/Virtual_private_server







>
>
>







>
>
>
>
>
>
|
|
<
>
>
>
>
>
>
|
<
>
>

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






<
<
<
>
>
>
>
>
>
>
>
>







 







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







 







>
>
>
>



274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298

299
300
301
302
303
304
305

306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332



333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
...
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
...
577
578
579
580
581
582
583
584
585
586
587
588
589
590
      listen 443 ssl;

      ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
      ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

      ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

      ssl_stapling on;
      ssl_stapling_verify on;

      ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
      ssl_ciphers "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SH
      ssl_session_cache shared:le_nginx_SSL:1m;
      ssl_prefer_server_ciphers on;
      ssl_session_timeout 1440m;

These are the common TLS configuration parameters used by all domains
hosted by this server.

The first line tells nginx to accept TLS-encrypted HTTP connections on
the standard HTTPS port. It is the same as `listen 443; ssl on;` in
older versions of nginx.

Since all of those domains share a single TLS certificate, we reference
the same `example.com/*.pem` files written out by Certbot with the

`ssl_certificate*` lines. 

The `ssl_dhparam` directive isn’t strictly required, but without it, the
server becomes vulnerable to the [Logjam attack][lja] because some of
the cryptography steps are precomputed, making the attacker’s job much
easier. The parameter file this directive references should be
generated automatically by the Let’s Encrypt package upon installation,

making those parameters unique to your server and thus unguessable. If
the file doesn’t exist on your system, you can create it manually, so:

      $ sudo openssl dhparam -out /etc/letsencrypt/dhparams.pem 2048

Beware, this will take a few minutes of CPU time.

The next section is also optional. It enables [OCSP stapling][ocsp], a
protocol that improves the speed and security of the TLS connection
negotiation.

The next section containing the `ssl_protocols` and `ssl_ciphers` lines
restricts the TLS implementation to only those protocols and ciphers
that are currently believed to be safe and secure.  This section is the
one most prone to bit-rot: as new attacks on TLS and its associated
technologies are discovered, this configuration is likely to need to
change. Even if we fully succeed in [keeping this document
up-to-date](#evolution), the nature of this guide is to recommend static
configurations for your server. You will have to keep an eye on this
sort of thing and evolve your local configuration as the world changes
around it.

Running a TLS certificate checker against your site occasionally is a
good idea. The most thorough service I’m aware of is the [Qualys SSL
Labs Test][qslt], which gives the site I’m basing this guide on an “A”
rating at the time of this writing.




<a id=”hsts”></a>There are a few things you can do to get an even better
grade, such as to enable [HSTS][hsts], which prevents a particular
variety of [man in the middle attack][mitm] where our HTTP-to-HTTPS
permanent redirect is intercepted, allowing the attacker to prevent the
automatic upgrade of the connection to a secure TLS-encrypted one.  I
didn’t enable that in the configuration above, because it is something a
site administrator should enable only after the configuration is tested
and stable, and then only after due consideration. There are ways to
lock your users out of your site by jumping to HSTS hastily.


### HTTP-Only Service

While we’d prefer not to offer HTTP service at all, we need to do so for
two reasons, one temporary and the other going forward indefinitely.

................................................................................
This forced redirect is why we don’t need the Fossil Admin &rarr; Access
"Redirect to HTTPS on the Login page" setting to be enabled.  Not only
is it unnecessary with this HTTPS redirect at the front-end proxy level,
it would actually [cause an infinite redirect loop if
enabled](./ssl.wiki#rloop).



## Step 6: Re-Sync Your Repositories

Now that the repositories hosted by this server are available via HTTPS,
you need to tell Fossil about it:

      $ cd ~/path/to/checkout
      $ fossil sync https://example.com/code

Once that’s done per repository file, all checkouts of that repo will
from that point on use the HTTPS URI to sync.

You might wonder if that’s necessary, since we have the automatic
HTTP-to-HTTPS redirect on this site now.  If you clone or sync one of
these nginx-hosted Fossil repositories over an untrustworthy network
that allows [MITM attacks][mitm], that redirect won’t protect you from a
sufficiently capable and motivated attacker unless you’ve also gone
ahead and [enabled HSTS](#hsts).  You can put off the need to enable
HSTS by explicitly using HTTPS URIs.


## Step 7: Renewing Automatically

Now that the configuration is solid, you can renew the LE cert and
restart nginx with two short commands, which are easily automated:

      sudo certbot certonly --webroot
      sudo systemctl restart nginx

................................................................................
keeps an eye on the forum and expects to keep this document updated with
ideas that appear in that thread.

[2016]: https://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg22907.html
[cb]:   https://certbot.eff.org/
[cbnu]: https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx
[fd]:   https://fossil-scm.org/forum/forumpost/ae6a4ee157
[hsts]: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
[lja]:  https://en.wikipedia.org/wiki/Logjam_(computer_security)
[mitm]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
[ocsp]: https://en.wikipedia.org/wiki/OCSP_stapling
[qslt]: https://www.ssllabs.com/ssltest/
[scgi]: https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface
[vps]:  https://en.wikipedia.org/wiki/Virtual_private_server