TLS Options

TLS 选项支持配置 TLS 连接的部分参数。

'default' TLS 选项

default 选项比较特殊。 TLS 路由器未指定 TLS 选项时，会使用 default 选项。显式指定 default 选项时，请勿指定提供者命名空间，因为 default 选项没有命名空间。相反，进行跨提供者引用时，例如从 Docker 标签引用文件提供者，必须指定提供者命名空间，例如： traefik.http.routers.myrouter.tls.options=myoptions@file

提供者

基于容器标签或标签（tag）的提供者不支持 TLS 选项。不过，使用 KV 提供者时可以定义 TLS 选项。

Kubernetes 中的 TLSOption

使用 TLSOption 资源时，名为 default 的选项适用于所有未显式引用 TLSOption 的路由器，无论该选项定义在哪个命名空间中。提供者选项 defaultTLSResourcesNamespace 限制了可定义此集群范围默认选项的命名空间。

服务器名称关联¶

TLS 选项配置在路由器上，但会在 TLS 握手期间应用，即在路由发生之前，此时唯一可用的信息是服务器名称（SNI）。因此，TLS 选项引用始终映射到路由器规则中 Host 部分的主机名，而非路由器或其规则。一条规则中也可以包含多个 Host 部分，此时 TLS 选项引用会映射到对应的所有主机名。

在域名前置场景中，如果与 Host 请求头关联的 TLS 选项和与 SNI 关联的 TLS 选项不同， Traefik 会返回 421 Misdirected Request 状态码。

TLS 选项冲突¶

由于 TLS 选项引用映射到主机名，当配置导致同一入口点上的同一主机名匹配两个不同的 TLS 选项引用时，就会发生冲突，如下例所示：

结构化 (YAML)

# Dynamic configuration

http:
  routers:
    routerfoo:
      rule: "Host(`example.com`) && Path(`/foo`)"
      tls:
        options: foo

    routerbar:
      rule: "Host(`example.com`) && Path(`/bar`)"
      tls:
        options: bar

结构化 (TOML)

# Dynamic configuration

[http.routers]
  [http.routers.routerfoo]
    rule = "Host(`example.com`) && Path(`/foo`)"
    [http.routers.routerfoo.tls]
      options = "foo"

  [http.routers.routerbar]
    rule = "Host(`example.com`) && Path(`/bar`)"
    [http.routers.routerbar.tls]
      options = "bar"

发生这种情况时，两个映射都会被丢弃，该主机名（本例中为 example.com）将改为关联 default TLS 选项。

冲突检测不限于单个提供者：来自不同提供者的路由器，例如通过容器标签定义的路由器与通过文件提供者定义的另一个路由器，只要它们在同一入口点上处理同一主机名，就会互相冲突。

默认 TLS 选项

default TLS 选项是冲突处理的回退选项，因此其安全性不应低于它可能替代的选项。例如，依赖双向 TLS 认证（clientAuth）的路由器，如果其主机名发生冲突并回退到不要求双向认证的 default TLS 选项，就不再强制执行双向认证。

避免此问题最稳妥的方法，是让同一入口点上处理同一主机名的所有路由器引用相同的 TLS 选项。

严格 TLS 选项¶

安装配置选项 core.strictTLSOptions 会禁用回退到 default TLS 选项的行为。启用后，参与冲突的路由器会标记为错误且完全不会构建，该主机名也不再映射到任何 TLS 选项。

禁用的路由器

启用 strictTLSOptions 后发生故障时会拒绝访问：冲突会禁用相关入口点上处理冲突主机名的所有路由器，直到冲突得到解决。

文件 (YAML)

## Install configuration
core:
  strictTLSOptions: true

文件 (TOML)

## Install configuration
[core]
  strictTLSOptions = true

CLI

## Install configuration
--core.strictTLSOptions=true

最低 TLS 版本¶

结构化 (YAML)

# Dynamic configuration

tls:
  options:
    default:
      minVersion: VersionTLS12

    mintls13:
      minVersion: VersionTLS13

结构化 (TOML)

# Dynamic configuration

[tls.options]

  [tls.options.default]
    minVersion = "VersionTLS12"

  [tls.options.mintls13]
    minVersion = "VersionTLS13"

最高 TLS 版本¶

不建议使用此设置禁用 TLS1.3。

推荐的做法是更新客户端，使其支持 TLS1.3。

结构化 (YAML)

# Dynamic configuration

tls:
  options:
    default:
      maxVersion: VersionTLS13

    maxtls12:
      maxVersion: VersionTLS12

结构化 (TOML)

# Dynamic configuration

[tls.options]

  [tls.options.default]
    maxVersion = "VersionTLS13"

  [tls.options.maxtls12]
    maxVersion = "VersionTLS12"

密码套件¶

更多信息见 cipherSuites。

结构化 (YAML)

# Dynamic configuration

tls:
  options:
    default:
      cipherSuites:
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

结构化 (TOML)

# Dynamic configuration

[tls.options]
  [tls.options.default]
    cipherSuites = [
      "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
    ]

TLS 1.3

TLS 1.2 及更早版本定义的密码套件不能用于 TLS 1.3，反之亦然。（https://tools.ietf.org/html/rfc8446）对于 TLS 1.3，密码套件不可配置（此时所有受支持的密码套件都是安全的）。 https://golang.org/doc/go1.12#tls_1_3

曲线偏好¶

此选项支持设置首选椭圆曲线。

可以使用 crypto 定义的曲线名称（如 CurveP521），以及 RFC 定义的名称（如 secp521r1）。

更多信息见 CurveID。

结构化 (YAML)

# Dynamic configuration

tls:
  options:
    default:
      curvePreferences:
        - CurveP521
        - CurveP384

结构化 (TOML)

# Dynamic configuration

[tls.options]
  [tls.options.default]
    curvePreferences = ["CurveP521", "CurveP384"]

严格 SNI 检查¶

启用严格 SNI 检查后，Traefik 不允许未指定 server_name 扩展或无法匹配任何已配置证书的客户端建立连接。默认证书与此行为无关。

结构化 (YAML)

# Dynamic configuration

tls:
  options:
    default:
      sniStrict: true

结构化 (TOML)

# Dynamic configuration

[tls.options]
  [tls.options.default]
    sniStrict = true

ALPN 协议¶

可选，默认值="h2, http/1.1, acme-tls/1"

此选项支持按优先顺序指定 TLS 握手所支持的应用层协议列表。如果客户端支持 ALPN，选中的协议将来自此列表，如果双方没有共同支持的协议，连接将失败。

结构化 (YAML)

# Dynamic configuration

tls:
  options:
    default:
      alpnProtocols:
        - http/1.1
        - h2

结构化 (TOML)

# Dynamic configuration

[tls.options]
  [tls.options.default]
    alpnProtocols = ["http/1.1", "h2"]

客户端认证（mTLS）¶

Traefik 通过 clientAuth 段支持双向认证。

对于要求验证客户端证书的认证策略，应在 clientAuth.caFiles 中设置证书的证书颁发机构。

在 Kubernetes 环境中，可以在 clientAuth.secretNames 中设置 CA 证书。更多信息见 TLSOption 资源。

clientAuth.clientAuthType 选项按以下方式控制行为：

选项	操作
`NoClientCert`	忽略所有客户端证书。
`RequestClientCert`	请求证书，但即使没有提供证书也会继续。
`RequireAnyClientCert`	要求提供证书，但不验证它是否由 `clientAuth.caFiles` 或 `clientAuth.secretNames` 中列出的 CA 签名。
`VerifyClientCertIfGiven`	如果提供了证书，则验证它是否由 `clientAuth.caFiles` 或 `clientAuth.secretNames` 中列出的 CA 签名；否则，不使用任何证书并继续。
`RequireAndVerifyClientCert`	要求提供证书，且证书必须由 `clientAuth.caFiles` 或 `clientAuth.secretNames` 中列出的 CA 签名。

结构化 (YAML)

# Dynamic configuration

tls:
  options:
    default:
      clientAuth:
        # in PEM format. each file can contain multiple CAs.
        caFiles:
          - tests/clientca1.crt
          - tests/clientca2.crt
        clientAuthType: RequireAndVerifyClientCert

结构化 (TOML)

# 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"

禁用会话票据¶

可选，默认值="false"

设置为 true 时，Traefik 禁用会话票据，强制每个客户端执行完整的 TLS 握手，而不是恢复会话。

结构化 (YAML)

# routing configuration

tls:
  options:
    default:
      disableSessionTickets: true

结构化 (TOML)

# routing configuration

[tls.options]
  [tls.options.default]
    disableSessionTickets = true

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: TLSOption
metadata:
  name: default
  namespace: default

spec:
  disableSessionTickets: true

在生产环境使用 Traefik OSS？

如果你在工作中使用 Traefik，可以考虑为 Traefik OSS 增加企业级 API 网关能力或商业支持。

为 Traefik OSS 增加 API 网关能力快捷且平滑，无需推倒重来，现有配置也会完整保留。请通过这个简短视频了解实际效果。