TLS¶
Transport Layer Security
Certificates Definition¶
Automated¶
See the Let's Encrypt page.
User defined¶
To add / remove TLS certificates, even when Traefik is already running, their definition can be added to the dynamic configuration, in the [[tls.certificates]]
section:
# Dynamic configuration
[[tls.certificates]]
certFile = "/path/to/domain.cert"
keyFile = "/path/to/domain.key"
[[tls.certificates]]
certFile = "/path/to/other-domain.cert"
keyFile = "/path/to/other-domain.key"
# Dynamic configuration
tls:
certificates:
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
Restriction
In the above example, we've used the file provider to handle these definitions. It is the only available method to configure the certificates (as well as the options and the stores). However, in Kubernetes, the certificates can and must be provided by secrets.
Certificates Stores¶
In Traefik, certificates are grouped together in certificates stores, which are defined as such:
# Dynamic configuration
[tls.stores]
[tls.stores.default]
# Dynamic configuration
tls:
stores:
default: {}
Restriction
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.certificates
section, a list of stores can then be specified to indicate where the certificates should be stored:
# Dynamic configuration
[[tls.certificates]]
certFile = "/path/to/domain.cert"
keyFile = "/path/to/domain.key"
stores = ["default"]
[[tls.certificates]]
# Note that since no store is defined,
# the certificate below will be stored in the `default` store.
certFile = "/path/to/other-domain.cert"
keyFile = "/path/to/other-domain.key"
# Dynamic configuration
tls:
certificates:
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
stores:
- default
# Note that since no store is defined,
# the certificate below will be stored in the `default` store.
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
Restriction
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:
# Dynamic configuration
[tls.stores]
[tls.stores.default]
[tls.stores.default.defaultCertificate]
certFile = "path/to/cert.crt"
keyFile = "path/to/cert.key"
# Dynamic configuration
tls:
stores:
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¶
# Dynamic configuration
[tls.options]
[tls.options.default]
minVersion = "VersionTLS12"
[tls.options.mintls13]
minVersion = "VersionTLS13"
# Dynamic configuration
tls:
options:
default:
minVersion: VersionTLS12
mintls13:
minVersion: VersionTLS13
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
spec:
minVersion: VersionTLS12
---
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: mintls13
namespace: default
spec:
minVersion: VersionTLS13
Maximum TLS Version¶
We discourages the use of this setting to disable TLS1.3.
The right approach is to update the clients to support TLS1.3.
# Dynamic configuration
[tls.options]
[tls.options.default]
maxVersion = "VersionTLS13"
[tls.options.maxtls12]
maxVersion = "VersionTLS12"
# Dynamic configuration
tls:
options:
default:
maxVersion: VersionTLS13
maxtls12:
maxVersion: VersionTLS12
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
spec:
maxVersion: VersionTLS13
---
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: maxtls12
namespace: default
spec:
maxVersion: VersionTLS12
Cipher Suites¶
See cipherSuites for more information.
# Dynamic configuration
[tls.options]
[tls.options.default]
cipherSuites = [
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
]
# Dynamic configuration
tls:
options:
default:
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
spec:
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS 1.3
Cipher suites defined for TLS 1.2 and below cannot be used in TLS 1.3, and vice versa. (https://tools.ietf.org/html/rfc8446)
With TLS 1.3, the cipher suites are not configurable (all supported cipher suites are safe in this case).
https://golang.org/doc/go1.12#tls_1_3
Curve Preferences¶
This option allows to set the preferred elliptic curves in a specific order.
The names of the curves defined by crypto
(e.g. CurveP521
) and the RFC defined names (e. g. secp521r1
) can be used.
See CurveID for more information.
# Dynamic configuration
[tls.options]
[tls.options.default]
curvePreferences = ["CurveP521", "CurveP384"]
# Dynamic configuration
tls:
options:
default:
curvePreferences:
- CurveP521
- CurveP384
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
spec:
curvePreferences:
- CurveP521
- CurveP384
Strict SNI Checking¶
With strict SNI checking, Traefik won't allow connections from clients connections that do not specify a server_name extension.
# Dynamic configuration
[tls.options]
[tls.options.default]
sniStrict = true
# Dynamic configuration
tls:
options:
default:
sniStrict: true
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
spec:
sniStrict: true
Client Authentication (mTLS)¶
Traefik supports mutual authentication, through the clientAuth
section.
For authentication policies that require verification of the client certificate, the certificate authority for the certificate should be set in clientAuth.caFiles
.
The clientAuth.clientAuthType
option governs the behaviour as follows:
NoClientCert
: disregards any client certificate.RequestClientCert
: asks for a certificate but proceeds anyway if none is provided.RequireAnyClientCert
: requires a certificate but does not verify if it is signed by a CA listed inclientAuth.caFiles
.VerifyClientCertIfGiven
: if a certificate is provided, verifies if it is signed by a CA listed inclientAuth.caFiles
. Otherwise proceeds without any certificate.RequireAndVerifyClientCert
: requires a certificate, which must be signed by a CA listed inclientAuth.caFiles
.
# Dynamic configuration
[tls.options]
[tls.options.default]
[tls.options.default.clientAuth]
# in PEM format. each file can contain multiple CAs.
caFiles = ["tests/clientca1.crt", "tests/clientca2.crt"]
clientAuthType = "RequireAndVerifyClientCert"
# Dynamic configuration
tls:
options:
default:
clientAuth:
# in PEM format. each file can contain multiple CAs.
caFiles:
- tests/clientca1.crt
- tests/clientca2.crt
clientAuthType: RequireAndVerifyClientCert
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
spec:
clientAuth:
secretNames:
- secretCA
clientAuthType: RequireAndVerifyClientCert