docs: rewrite of the HTTPS and TLS section

Co-authored-by: Ludovic Fernandez <ldez@users.noreply.github.com>

docs/content/https-tls/acme.md → docs/content/https/acme.md

@@ -1,4 +1,4 @@
-# ACME
+# Let's Encrypt
 
 Automatic HTTPS
 {: .subtitle }
@@ -54,7 +54,7 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom
     There are many available options for ACME. For a quick glance at what's possible, browse the configuration reference:
 
     ```toml
-    --8<-- "content/https-tls/ref-acme.toml"
+    --8<-- "content/https/ref-acme.toml"
     ```
 
 ## Automatic Renewals

docs/content/https/overview.md

@@ -0,0 +1,16 @@
+# HTTPS & TLS
+
+Overview
+{: .subtitle }
+
+Traefik supports HTTPS & TLS, which concerns roughly two parts of the configuration:
+routers, and the TLS connection (and its underlying certificates).
+
+When a router has to handle HTTPS traffic,
+it should be specified with a `tls` field of the router definition.
+See the TLS section of the [routers documentation](../routing/routers/index.md#tls).
+
+The next sections of this documentation explain how to configure the TLS connection itself.
+That is to say, how to obtain [TLS certificates](./tls.md#certificates-definition):
+either through a definition in the dynamic configuration, or through [Let's Encrypt](./acme.md) (ACME).
+And how to configure [TLS options](./tls.md#tls-options), and [certificates stores](./tls.md#certificates-stores).

docs/content/https/tls.md

@@ -0,0 +1,140 @@
+# TLS
+
+Transport Layer Security
+{: .subtitle }
+
+## Certificates Definition
+
+### Automated
+
+See the [Let's Encrypt](./acme.md) page.
+
+### User defined
+
+To add / remove TLS certificates, even when Traefik is already running, their definition can be added to the [dynamic configuration](../getting-started/configuration-overview.md), in the `[[tls]]` section:
+
+```toml
+[[tls]]
+  [tls.certificate]
+    certFile = "/path/to/domain.cert"
+    keyFile = "/path/to/domain.key"
+
+[[tls]]
+  [tls.certificate]
+    certFile = "/path/to/other-domain.cert"
+    keyFile = "/path/to/other-domain.key"
+```
+
+!!! important "File Provider Only"
+
+    In the above example, we've used the [file provider](../providers/file.md) to handle these definitions.
+    In its current alpha version, it is the only available method to configure the certificates (as well as the options and the stores).
+
+## Certificates Stores
+
+In Traefik, certificates are grouped together in certificates stores, which are defined as such:
+
+```toml
+[tlsStores]
+  [tlsStores.default]
+```
+
+!!! important "Alpha restriction"
+
+    During the alpha version, any store definition other than the default one (named `default`) will be ignored,
+    and there is thefore only one globally available TLS store.
+
+In the `[[tls]]` section, a list of stores can then be specified to indicate where the certificates should be stored:
+
+```toml
+[[tls]]
+  stores = ["default"]
+  [tls.certificate]
+    certFile = "/path/to/domain.cert"
+    keyFile = "/path/to/domain.key"
+
+[[tls]]
+  # Note that since no store is defined,
+  # the certificate below will be stored in the `default` store.
+  [tls.certificate]
+    certFile = "/path/to/other-domain.cert"
+    keyFile = "/path/to/other-domain.key"
+```
+
+!!! important "Alpha restriction"
+
+    During the alpha version, the `stores` list will actually be ignored and automatically set to `["default"]`.
+
+### Default Certificate
+
+Traefik can use a default certificate for connections without a SNI, or without a matching domain.
+This default certificate should be defined in a TLS store:
+
+```toml
+[tlsStores]
+  [tlsStores.default]
+    [tlsStores.default.defaultCertificate]
+      certFile = "path/to/cert.crt"
+      keyFile  = "path/to/cert.key"
+```
+
+If no default certificate is provided, Traefik generates and uses a self-signed certificate.
+
+## TLS Options
+
+The TLS options allow one to configure some parameters of the TLS connection.
+
+### Minimum TLS Version
+
+```toml
+[tlsOptions]
+
+  [tlsOptions.default]
+    minVersion = "VersionTLS12"
+
+  [tlsOptions.mintls13]
+    minVersion = "VersionTLS13"
+```
+
+### Mutual Authentication
+
+Traefik supports both optional and strict (which is the default) mutual authentication, though the `ClientCA.files` section.
+If present, connections from clients without a certificate will be rejected.
+
+For clients with a certificate, the `optional` option governs the behaviour as follows:
+
+- When `optional = false`, Traefik accepts connections only from clients presenting a certificate signed by a CA listed in `ClientCA.files`.
+- When `optional = true`, Traefik authorizes connections from clients presenting a certificate signed by an unknown CA.
+
+```toml
+[tlsOptions]
+  [tlsOptions.default]
+    [tlsOptions.default.ClientCA]
+      # in PEM format. each file can contain multiple CAs.
+      files = ["tests/clientca1.crt", "tests/clientca2.crt"]
+      optional = false
+```
+
+### Cipher Suites
+
+See [cipherSuites](https://godoc.org/crypto/tls#pkg-constants) for more information.
+
+```toml
+[tlsOptions]
+  [tlsOptions.default]
+    cipherSuites = [
+      "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
+      "TLS_RSA_WITH_AES_256_GCM_SHA384"
+    ]
+```
+
+### Strict SNI Checking
+
+With strict SNI checking, Traefik won't allow connections from clients connections
+that do not specify a server_name extension.
+
+```toml
+[tlsOptions]
+  [tlsOptions.default]
+    sniStrict = true
+```