Fossil SCM
Assorted improvements to the TLS/SSL docs.
Commit
43166dcda39e8f5d39a74924a07ff0f700a3b442ba033bbee16858ad92f7f28a
Parent
9c7fdea89b50654…
2 files changed
+1
-1
+74
-17
+1
-1
| --- www/ssl.wiki | ||
| +++ www/ssl.wiki | ||
| @@ -237,9 +237,9 @@ | ||
| 237 | 237 | |
| 238 | 238 | Some people still use the term "SSL" when they actually mean "TLS," but |
| 239 | 239 | in the Fossil project, we always use "TLS" except when we must preserve |
| 240 | 240 | some sort of historical compatibility, as with this document's name in |
| 241 | 241 | order to avoid broken external URLs. The Fossil TLS-related settings |
| 242 | -also often use "`ssl`" in their names, for the same reason. | |
| 242 | +also often use "<tt>ssl</tt>" in their names, for the same reason. | |
| 243 | 243 | |
| 244 | 244 | This series of protocols is also called "HTTPS" after the URI scheme |
| 245 | 245 | used to specify "HTTP over TLS." |
| 246 | 246 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -237,9 +237,9 @@ | |
| 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 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -237,9 +237,9 @@ | |
| 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 "<tt>ssl</tt>" 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 |
+74
-17
| --- www/tls-nginx.md | ||
| +++ www/tls-nginx.md | ||
| @@ -276,39 +276,71 @@ | ||
| 276 | 276 | ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; |
| 277 | 277 | ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; |
| 278 | 278 | |
| 279 | 279 | ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; |
| 280 | 280 | |
| 281 | + ssl_stapling on; | |
| 282 | + ssl_stapling_verify on; | |
| 283 | + | |
| 281 | 284 | ssl_protocols TLSv1 TLSv1.1 TLSv1.2; |
| 282 | 285 | ssl_ciphers "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SH |
| 283 | 286 | ssl_session_cache shared:le_nginx_SSL:1m; |
| 284 | 287 | ssl_prefer_server_ciphers on; |
| 285 | 288 | ssl_session_timeout 1440m; |
| 286 | 289 | |
| 287 | 290 | These are the common TLS configuration parameters used by all domains |
| 288 | -hosted by this server. Since all of those domains share a single TLS | |
| 289 | -certificate, we reference the same `example.com/*.pem` files written out | |
| 290 | -by Certbot here. We also reference the common server-specific | |
| 291 | -Diffie-Hellman parameter file written by the Let’s Encrypt package when | |
| 292 | -it’s initially installed. | |
| 293 | - | |
| 294 | -The `ssl_protocols` and `ssl_ciphers` lines are prone to bit-rot: as new | |
| 295 | -attacks on TLS and its associated technologies are discovered, this | |
| 296 | -configuration is likely to need to change. Even if we fully succeed in | |
| 297 | -[keeping this document up-to-date](#evolution), the nature of this guide | |
| 298 | -is to recommend static configurations for your server. You will have to | |
| 299 | -keep an eye on this sort of thing and evolve your local configuration as | |
| 300 | -the world changes around it. | |
| 291 | +hosted by this server. | |
| 292 | + | |
| 293 | +The first line tells nginx to accept TLS-encrypted HTTP connections on | |
| 294 | +the standard HTTPS port. It is the same as `listen 443; ssl on;` in | |
| 295 | +older versions of nginx. | |
| 296 | + | |
| 297 | +Since all of those domains share a single TLS certificate, we reference | |
| 298 | +the same `example.com/*.pem` files written out by Certbot with the | |
| 299 | +`ssl_certificate*` lines. | |
| 300 | + | |
| 301 | +The `ssl_dhparam` directive isn’t strictly required, but without it, the | |
| 302 | +server becomes vulnerable to the [Logjam attack][lja] because some of | |
| 303 | +the cryptography steps are precomputed, making the attacker’s job much | |
| 304 | +easier. The parameter file this directive references should be | |
| 305 | +generated automatically by the Let’s Encrypt package upon installation, | |
| 306 | +making those parameters unique to your server and thus unguessable. If | |
| 307 | +the file doesn’t exist on your system, you can create it manually, so: | |
| 308 | + | |
| 309 | + $ sudo openssl dhparam -out /etc/letsencrypt/dhparams.pem 2048 | |
| 310 | + | |
| 311 | +Beware, this will take a few minutes of CPU time. | |
| 312 | + | |
| 313 | +The next section is also optional. It enables [OCSP stapling][ocsp], a | |
| 314 | +protocol that improves the speed and security of the TLS connection | |
| 315 | +negotiation. | |
| 316 | + | |
| 317 | +The next section containing the `ssl_protocols` and `ssl_ciphers` lines | |
| 318 | +restricts the TLS implementation to only those protocols and ciphers | |
| 319 | +that are currently believed to be safe and secure. This section is the | |
| 320 | +one most prone to bit-rot: as new attacks on TLS and its associated | |
| 321 | +technologies are discovered, this configuration is likely to need to | |
| 322 | +change. Even if we fully succeed in [keeping this document | |
| 323 | +up-to-date](#evolution), the nature of this guide is to recommend static | |
| 324 | +configurations for your server. You will have to keep an eye on this | |
| 325 | +sort of thing and evolve your local configuration as the world changes | |
| 326 | +around it. | |
| 301 | 327 | |
| 302 | 328 | Running a TLS certificate checker against your site occasionally is a |
| 303 | 329 | good idea. The most thorough service I’m aware of is the [Qualys SSL |
| 304 | 330 | Labs Test][qslt], which gives the site I’m basing this guide on an “A” |
| 305 | 331 | rating at the time of this writing. |
| 306 | 332 | |
| 307 | -I assume you’re taking my advice to serve only the least amount of stuff | |
| 308 | -over HTTP that you can get away with. Certbot’s ACME HTTP-01 | |
| 309 | -authentication scheme is one of those few things. | |
| 333 | +<a id=”hsts”></a>There are a few things you can do to get an even better | |
| 334 | +grade, such as to enable [HSTS][hsts], which prevents a particular | |
| 335 | +variety of [man in the middle attack][mitm] where our HTTP-to-HTTPS | |
| 336 | +permanent redirect is intercepted, allowing the attacker to prevent the | |
| 337 | +automatic upgrade of the connection to a secure TLS-encrypted one. I | |
| 338 | +didn’t enable that in the configuration above, because it is something a | |
| 339 | +site administrator should enable only after the configuration is tested | |
| 340 | +and stable, and then only after due consideration. There are ways to | |
| 341 | +lock your users out of your site by jumping to HSTS hastily. | |
| 310 | 342 | |
| 311 | 343 | |
| 312 | 344 | ### HTTP-Only Service |
| 313 | 345 | |
| 314 | 346 | While we’d prefer not to offer HTTP service at all, we need to do so for |
| @@ -485,11 +517,32 @@ | ||
| 485 | 517 | is it unnecessary with this HTTPS redirect at the front-end proxy level, |
| 486 | 518 | it would actually [cause an infinite redirect loop if |
| 487 | 519 | enabled](./ssl.wiki#rloop). |
| 488 | 520 | |
| 489 | 521 | |
| 490 | -## Step 6: Renewing Automatically | |
| 522 | + | |
| 523 | +## Step 6: Re-Sync Your Repositories | |
| 524 | + | |
| 525 | +Now that the repositories hosted by this server are available via HTTPS, | |
| 526 | +you need to tell Fossil about it: | |
| 527 | + | |
| 528 | + $ cd ~/path/to/checkout | |
| 529 | + $ fossil sync https://example.com/code | |
| 530 | + | |
| 531 | +Once that’s done per repository file, all checkouts of that repo will | |
| 532 | +from that point on use the HTTPS URI to sync. | |
| 533 | + | |
| 534 | +You might wonder if that’s necessary, since we have the automatic | |
| 535 | +HTTP-to-HTTPS redirect on this site now. If you clone or sync one of | |
| 536 | +these nginx-hosted Fossil repositories over an untrustworthy network | |
| 537 | +that allows [MITM attacks][mitm], that redirect won’t protect you from a | |
| 538 | +sufficiently capable and motivated attacker unless you’ve also gone | |
| 539 | +ahead and [enabled HSTS](#hsts). You can put off the need to enable | |
| 540 | +HSTS by explicitly using HTTPS URIs. | |
| 541 | + | |
| 542 | + | |
| 543 | +## Step 7: Renewing Automatically | |
| 491 | 544 | |
| 492 | 545 | Now that the configuration is solid, you can renew the LE cert and |
| 493 | 546 | restart nginx with two short commands, which are easily automated: |
| 494 | 547 | |
| 495 | 548 | sudo certbot certonly --webroot |
| @@ -526,8 +579,12 @@ | ||
| 526 | 579 | |
| 527 | 580 | [2016]: https://www.mail-archive.com/[email protected]/msg22907.html |
| 528 | 581 | [cb]: https://certbot.eff.org/ |
| 529 | 582 | [cbnu]: https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx |
| 530 | 583 | [fd]: https://fossil-scm.org/forum/forumpost/ae6a4ee157 |
| 584 | +[hsts]: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security | |
| 585 | +[lja]: https://en.wikipedia.org/wiki/Logjam_(computer_security) | |
| 586 | +[mitm]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack | |
| 587 | +[ocsp]: https://en.wikipedia.org/wiki/OCSP_stapling | |
| 531 | 588 | [qslt]: https://www.ssllabs.com/ssltest/ |
| 532 | 589 | [scgi]: https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface |
| 533 | 590 | [vps]: https://en.wikipedia.org/wiki/Virtual_private_server |
| 534 | 591 |
| --- www/tls-nginx.md | |
| +++ www/tls-nginx.md | |
| @@ -276,39 +276,71 @@ | |
| 276 | ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; |
| 277 | ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; |
| 278 | |
| 279 | ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; |
| 280 | |
| 281 | ssl_protocols TLSv1 TLSv1.1 TLSv1.2; |
| 282 | ssl_ciphers "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SH |
| 283 | ssl_session_cache shared:le_nginx_SSL:1m; |
| 284 | ssl_prefer_server_ciphers on; |
| 285 | ssl_session_timeout 1440m; |
| 286 | |
| 287 | These are the common TLS configuration parameters used by all domains |
| 288 | hosted by this server. Since all of those domains share a single TLS |
| 289 | certificate, we reference the same `example.com/*.pem` files written out |
| 290 | by Certbot here. We also reference the common server-specific |
| 291 | Diffie-Hellman parameter file written by the Let’s Encrypt package when |
| 292 | it’s initially installed. |
| 293 | |
| 294 | The `ssl_protocols` and `ssl_ciphers` lines are prone to bit-rot: as new |
| 295 | attacks on TLS and its associated technologies are discovered, this |
| 296 | configuration is likely to need to change. Even if we fully succeed in |
| 297 | [keeping this document up-to-date](#evolution), the nature of this guide |
| 298 | is to recommend static configurations for your server. You will have to |
| 299 | keep an eye on this sort of thing and evolve your local configuration as |
| 300 | the world changes around it. |
| 301 | |
| 302 | Running a TLS certificate checker against your site occasionally is a |
| 303 | good idea. The most thorough service I’m aware of is the [Qualys SSL |
| 304 | Labs Test][qslt], which gives the site I’m basing this guide on an “A” |
| 305 | rating at the time of this writing. |
| 306 | |
| 307 | I assume you’re taking my advice to serve only the least amount of stuff |
| 308 | over HTTP that you can get away with. Certbot’s ACME HTTP-01 |
| 309 | authentication scheme is one of those few things. |
| 310 | |
| 311 | |
| 312 | ### HTTP-Only Service |
| 313 | |
| 314 | While we’d prefer not to offer HTTP service at all, we need to do so for |
| @@ -485,11 +517,32 @@ | |
| 485 | is it unnecessary with this HTTPS redirect at the front-end proxy level, |
| 486 | it would actually [cause an infinite redirect loop if |
| 487 | enabled](./ssl.wiki#rloop). |
| 488 | |
| 489 | |
| 490 | ## Step 6: Renewing Automatically |
| 491 | |
| 492 | Now that the configuration is solid, you can renew the LE cert and |
| 493 | restart nginx with two short commands, which are easily automated: |
| 494 | |
| 495 | sudo certbot certonly --webroot |
| @@ -526,8 +579,12 @@ | |
| 526 | |
| 527 | [2016]: https://www.mail-archive.com/[email protected]/msg22907.html |
| 528 | [cb]: https://certbot.eff.org/ |
| 529 | [cbnu]: https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx |
| 530 | [fd]: https://fossil-scm.org/forum/forumpost/ae6a4ee157 |
| 531 | [qslt]: https://www.ssllabs.com/ssltest/ |
| 532 | [scgi]: https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface |
| 533 | [vps]: https://en.wikipedia.org/wiki/Virtual_private_server |
| 534 |
| --- www/tls-nginx.md | |
| +++ www/tls-nginx.md | |
| @@ -276,39 +276,71 @@ | |
| 276 | ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; |
| 277 | ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; |
| 278 | |
| 279 | ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; |
| 280 | |
| 281 | ssl_stapling on; |
| 282 | ssl_stapling_verify on; |
| 283 | |
| 284 | ssl_protocols TLSv1 TLSv1.1 TLSv1.2; |
| 285 | ssl_ciphers "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SH |
| 286 | ssl_session_cache shared:le_nginx_SSL:1m; |
| 287 | ssl_prefer_server_ciphers on; |
| 288 | ssl_session_timeout 1440m; |
| 289 | |
| 290 | These are the common TLS configuration parameters used by all domains |
| 291 | hosted by this server. |
| 292 | |
| 293 | The first line tells nginx to accept TLS-encrypted HTTP connections on |
| 294 | the standard HTTPS port. It is the same as `listen 443; ssl on;` in |
| 295 | older versions of nginx. |
| 296 | |
| 297 | Since all of those domains share a single TLS certificate, we reference |
| 298 | the same `example.com/*.pem` files written out by Certbot with the |
| 299 | `ssl_certificate*` lines. |
| 300 | |
| 301 | The `ssl_dhparam` directive isn’t strictly required, but without it, the |
| 302 | server becomes vulnerable to the [Logjam attack][lja] because some of |
| 303 | the cryptography steps are precomputed, making the attacker’s job much |
| 304 | easier. The parameter file this directive references should be |
| 305 | generated automatically by the Let’s Encrypt package upon installation, |
| 306 | making those parameters unique to your server and thus unguessable. If |
| 307 | the file doesn’t exist on your system, you can create it manually, so: |
| 308 | |
| 309 | $ sudo openssl dhparam -out /etc/letsencrypt/dhparams.pem 2048 |
| 310 | |
| 311 | Beware, this will take a few minutes of CPU time. |
| 312 | |
| 313 | The next section is also optional. It enables [OCSP stapling][ocsp], a |
| 314 | protocol that improves the speed and security of the TLS connection |
| 315 | negotiation. |
| 316 | |
| 317 | The next section containing the `ssl_protocols` and `ssl_ciphers` lines |
| 318 | restricts the TLS implementation to only those protocols and ciphers |
| 319 | that are currently believed to be safe and secure. This section is the |
| 320 | one most prone to bit-rot: as new attacks on TLS and its associated |
| 321 | technologies are discovered, this configuration is likely to need to |
| 322 | change. Even if we fully succeed in [keeping this document |
| 323 | up-to-date](#evolution), the nature of this guide is to recommend static |
| 324 | configurations for your server. You will have to keep an eye on this |
| 325 | sort of thing and evolve your local configuration as the world changes |
| 326 | around it. |
| 327 | |
| 328 | Running a TLS certificate checker against your site occasionally is a |
| 329 | good idea. The most thorough service I’m aware of is the [Qualys SSL |
| 330 | Labs Test][qslt], which gives the site I’m basing this guide on an “A” |
| 331 | rating at the time of this writing. |
| 332 | |
| 333 | <a id=”hsts”></a>There are a few things you can do to get an even better |
| 334 | grade, such as to enable [HSTS][hsts], which prevents a particular |
| 335 | variety of [man in the middle attack][mitm] where our HTTP-to-HTTPS |
| 336 | permanent redirect is intercepted, allowing the attacker to prevent the |
| 337 | automatic upgrade of the connection to a secure TLS-encrypted one. I |
| 338 | didn’t enable that in the configuration above, because it is something a |
| 339 | site administrator should enable only after the configuration is tested |
| 340 | and stable, and then only after due consideration. There are ways to |
| 341 | lock your users out of your site by jumping to HSTS hastily. |
| 342 | |
| 343 | |
| 344 | ### HTTP-Only Service |
| 345 | |
| 346 | While we’d prefer not to offer HTTP service at all, we need to do so for |
| @@ -485,11 +517,32 @@ | |
| 517 | is it unnecessary with this HTTPS redirect at the front-end proxy level, |
| 518 | it would actually [cause an infinite redirect loop if |
| 519 | enabled](./ssl.wiki#rloop). |
| 520 | |
| 521 | |
| 522 | |
| 523 | ## Step 6: Re-Sync Your Repositories |
| 524 | |
| 525 | Now that the repositories hosted by this server are available via HTTPS, |
| 526 | you need to tell Fossil about it: |
| 527 | |
| 528 | $ cd ~/path/to/checkout |
| 529 | $ fossil sync https://example.com/code |
| 530 | |
| 531 | Once that’s done per repository file, all checkouts of that repo will |
| 532 | from that point on use the HTTPS URI to sync. |
| 533 | |
| 534 | You might wonder if that’s necessary, since we have the automatic |
| 535 | HTTP-to-HTTPS redirect on this site now. If you clone or sync one of |
| 536 | these nginx-hosted Fossil repositories over an untrustworthy network |
| 537 | that allows [MITM attacks][mitm], that redirect won’t protect you from a |
| 538 | sufficiently capable and motivated attacker unless you’ve also gone |
| 539 | ahead and [enabled HSTS](#hsts). You can put off the need to enable |
| 540 | HSTS by explicitly using HTTPS URIs. |
| 541 | |
| 542 | |
| 543 | ## Step 7: Renewing Automatically |
| 544 | |
| 545 | Now that the configuration is solid, you can renew the LE cert and |
| 546 | restart nginx with two short commands, which are easily automated: |
| 547 | |
| 548 | sudo certbot certonly --webroot |
| @@ -526,8 +579,12 @@ | |
| 579 | |
| 580 | [2016]: https://www.mail-archive.com/[email protected]/msg22907.html |
| 581 | [cb]: https://certbot.eff.org/ |
| 582 | [cbnu]: https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx |
| 583 | [fd]: https://fossil-scm.org/forum/forumpost/ae6a4ee157 |
| 584 | [hsts]: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security |
| 585 | [lja]: https://en.wikipedia.org/wiki/Logjam_(computer_security) |
| 586 | [mitm]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack |
| 587 | [ocsp]: https://en.wikipedia.org/wiki/OCSP_stapling |
| 588 | [qslt]: https://www.ssllabs.com/ssltest/ |
| 589 | [scgi]: https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface |
| 590 | [vps]: https://en.wikipedia.org/wiki/Virtual_private_server |
| 591 |