tls

tls用来配置HTTPS连接。由于HTTPS是自动启用的，这个指令只能用于特意覆盖默认设置。如果用到的话一定要小心。

Caddy支持SNI(服务器名称指示)，因此可以从机器上的同一个端口为多个HTTPS站点提供服务。此外，Caddy为所有合格的证书实施OCSP装订。Caddy还会定期自动旋转所有TLS会话票据密钥。

tls指令将忽略显式定义为http://或在80端口上的站点。这允许您在与HTTP和HTTPS站点共享的服务器块中使用tls指令。

如果启动服务器时不知道所有主机名，则可以使用随需TLS特性，该特性在TLS握手期间而不是启动时发出证书。或者，如果您的子域数量超出了CA速率限制的允许范围，那么您可以启用DNS验证获得一个通配符证书。

Caddy附带了对密码套件、曲线、键类型和协议的sane默认值。它们的精确选择和顺序可能随新版本的发布而随时改变。你可能不需要自己去改变它们。调整TLS配置需要自担风险。

Caddy不会消除与密钥的主机名相同的不同或冲突的TLS配置之间的歧义。如果TLS配置是自定义的，那么由相同主机名键入的任何其他TLS配置都必须匹配，或者至少是兼容的，否则就会导致错误。这包括密码套件，曲线设置，等等。

语法

  1. tls off

禁用网站的TLS。除非你有充分的理由，否则不要推荐。关闭TLS后，自动HTTPS会被禁用，不会更改默认端口(2015)。

  1. tls email
  • email 是用于生成具有可信CA的证书的电子邮件地址。通过在这里提供电子邮件，您将不会在运行Caddy时收到提示。

虽然不需要使用上述语法来启用TLS，但它允许您指定CA帐户使用的电子邮件地址，而不是提示使用一个或使用以前运行时使用的另一个。

用自己的证书和密钥使用Caddy：

  1. tls cert key

  • cert 证书文件。如果证书是由CA签署的，那么这个证书文件应该是一个包：服务器证书后面跟着CA证书(根证书通常不是必须的)。

  • key 与证书文件匹配的服务器私钥文件。 指定您自己的证书和密钥将禁用自动HTTPS，包括更改端口和将HTTP重定向到HTTPS。如果你正在管理自己的证书，那这些需要你自己去做。

你可以多次使用此指令来指定多个证书和密钥对。

或者让Caddy生成并在内存中使用一个不可信的自签名证书，该证书持续7天(足够本地开发)：

  1. tls self_signed

上面的语法将使用Caddy的默认TLS设置，已经你自己的证书和密钥，或者持续7天的自签名证书：它仅用于本地开发。

高级用户可以打开设置块进行更多的控制，可以选择指定自己的证书和密钥:

  1. tls [cert key] {
  2.     ca        uri
  3.     protocols min max
  4.     ciphers   ciphers...
  5.     curves    curves...
  6.     clients   [request|require|verify_if_given] clientcas...
  7.     load      dir
  8.     max_certs limit
  9.     ask       url
  10.     key_type  type
  11.     dns       provider
  12.     alpn      protos...
  13.     must_staple
  14.     wildcard
  15. }
  • ca 指定要从请求证书的证书颁发机构端点，要求与ACME兼容。
  • cert 和key 和前面介绍的是一样的。
  • protocols 指定要支持的最小和最大协议版本。后面会介绍具体的有效值。如果min和max相同，则只需要指定一次。
  • ciphers 将支持的以空格分隔的密码列表，覆盖默认值。如果你列出任何选项，那么只有你指定的选项被允许，并按照给定的顺序排序。后面将会介绍具体的有效值。
  • curves 以指定的顺序支持以空格分隔的曲线列表，覆盖默认值。有效曲线下文介绍。
  • clients 是在TLS客户端身份验证期间用于验证的CA列表，以空格分开。如果使用，客户端将被要求通过其浏览器显示其证书，该浏览器将根据此客户端证书颁发机构列表进行验证。如果客户端证书不是由这些根CA之一签名，则不允许其连接。注意，此设置适用于整个服务，而不仅仅是单个站点。你可以使用下列客户CA列表前的关键字之一来修改客户身份验证的严格性：
    • request 仅仅要求客户端提供一个证书，但是如果没有提供证书，或者提供了无效的证书，也不会失败。
    • require 需要客户端证书，但不会验证它。
    • __verify_if_given 将不会失败，如果没有提交，但拒绝所有不通过验证。
    • 如果只找到一个CA文件而没有设置标志，那么默认情况下这两种方法都可以：要求客户端证书并对其进行验证。
  • load 是用来加载证书和密钥的目录。将遍历整个目录及其子文件夹以搜索.pem文件。每个.pem文件必须包含PEM编码证书(链)和关键块，它们连接在一起。
  • max_certs 启用按需TLS，它在第一次需要它而不是在启动时获得证书。如果在Caddyfile中提供了完整的主机名，并且在启动时知道，则不建议使用按需TLS ！该值限制了该站点的按需(在TLS握手期间)颁发的证书数量。它一定是正整数。这个值在进程退出后将被重置(但是通过重新加载保持)。适用内部速率限制。
  • ask 是启用按需TLS的另一种方法。如果在Caddyfile中给出主机名并在配置时知道主机名，则不建议使用按需TLS！URL将通过GET查询，如果允许向查询字符串中的domain查询值提供证书，则返回200状态码。这个节点不允许重定向。URL只能在内部访问。当使用此选项时，Caddy不执行任何额外的速率限制；你的节点应该代替来做明智的决定。
  • key_type 是在为证书生成密钥时使用的密钥类型(仅适用于托管或TLS或自签名证书)。有效值为rsa2048、rsa4096、rsa8192、p256和p384。当前的默认值是rsa2048。
  • dns DNS提供者的名称；指定它将启用DNS验证(有关详细信息，请参阅该链接)。注意，您需要通过环境变量提供凭证才能使其工作。
  • alpn 是用于应用层协议协商(ALPN)的分隔符列表。对于HTTPS服务器，可以使用此设置启用/禁用HTTP版本。默认是h2 http/1.1。
  • must_staple 启用托管证书的Must-Staple。小心使用。
  • wildcard 将通过将最左边的标签替换为*来获取和管理这个名称的通配符证书，只要启用了带DNS验证的托管TLS。任何配置类似并具有相同通配符名称的站点随后将共享相同的单个证书。这不适用于按需TLS，因为它使用SNI值作为证书名称。注意：不要使用此特性，除非您有许多子域，否则会导致您达到CA速率限制。

协议

支持以下协议，按优先级降序排列:

  • tls1.2 (默认最小和最大值)
  • tls1.1
  • tls1.0

请注意，降低最低协议版本可能允许非常老的客户端连接，但可能会产生错误的安全意识。

支持的协议和默认协议版本可以随时更改。

密码套件

目前支持下列密码套件:

  • ECDHE-ECDSA-AES256-GCM-SHA384
  • ECDHE-RSA-AES256-GCM-SHA384
  • ECDHE-ECDSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES128-GCM-SHA256
  • ECDHE-ECDSA-WITH-CHACHA20-POLY1305
  • ECDHE-RSA-WITH-CHACHA20-POLY1305
  • ECDHE-RSA-AES256-CBC-SHA
  • ECDHE-RSA-AES128-CBC-SHA
  • ECDHE-ECDSA-AES256-CBC-SHA
  • ECDHE-ECDSA-AES128-CBC-SHA
  • RSA-AES256-CBC-SHA
  • RSA-AES128-CBC-SHA
  • ECDHE-RSA-3DES-EDE-CBC-SHA
  • RSA-3DES-EDE-CBC-S*HA

注意：出于安全原因，HTTP/2规范列出了超过275个密码套件。除非您知道自己在做什么，否则最好接受默认密码套件设置。

密码套件可以在任何时候从Caddy添加或删除。同样，默认密码套件也可以随时被更改。

曲线

EC密码套件支持以下曲线：

  • X25519
  • p256
  • p384
  • p521

特征总结

总之，Caddy为您自动实现了这些TLS特性。默认情况下，它是唯一这样做的服务器:

  • 会话标识符
  • 会话票据键轮换
  • OCSP装订
  • 动态记录大小调整
  • 应用层协议协商
  • 向前保密
  • HTTP/2（为HTTP服务器）
  • 证书管理(包括自动续期)
  • MITM检测(针对HTTPS站点)

大多数网站甚至不会使用tls指令。不需要使用这些特性。

示例

记住，TLS是默认启用的，通常不需要这个指令！这些示例适用于手动管理证书或需要自定义设置的高级用户。

使用证书和私钥为HTTPS提供服务：

  1. tls ../cert.pem ../key.pem

根据需要在TLS握手期间获得证书，硬限制为10个新证书:

  1. tls {
  2.     max_certs 10
  3. }

从/www/certificates中找到的.pem文件中加载所有证书和密钥：

  1. tls {
  2.     load /www/certificates
  3. }

在内存中为站点提供自签名证书(浏览器不信任，但便于本地开发)：

  1. tls self_signed