集成指南

最近更新: | 所有文档

如果您是托管服务提供商或正在大型网站中集成 Let’s Encrypt,或者您正在为 Let’s Encrypt 编写客户端软件,则本文档包含了一些对您有用的建议。

做好更改准备

Let’s Encrypt 和 Web PKI 都将随着时间的推移而不断发展。 您应该确保能够轻松更新所有使用 Let’s Encrypt 的服务。 如果您还要部署依赖于 Let’s Encrypt 证书的客户端,请特别确保这些客户端定期收到更新。

将来,这些事情可能会发生变化:

我们将始终尽可能提前通知此类更改,但如果在某些组件中发现严重的安全漏洞,我们可能需要在短期内或立即进行更改。 特别是对于中间证书改变,你不应该硬编码中间证书,而应该使用 ACME 协议中的 Link: rel="up"标头,因为中间证书很可能会改变。

同样,我们可能会在更新服务条款(ToS)时更改其链接。 请避免硬编码 ToS 链接,而是使用 Link:rel =“terms-of-service” 标头确定要使用的 ToS 链接。

要接收有关上述重要更改的小批量更新,请订阅我们的 API 公告分类。这对客户端开发人员和托管提供商都很有用。

获取更新

要接收有关上述重要更改的小批量更新,请订阅我们的 [API 公告](https://community.letsencrypt.org/t/about-the-api-announcements-category/23836)分类。 这对客户端开发人员和托管提供商都很有用。

有关维护和停机的更高容量更新,请访问我们的[状态页面](https://letsencrypt.status.io/)并点击右上方的"订阅"按钮。 这对托管服务提供商最为有用。

此外,请确保为 ACME 帐户使用有效的电子邮件地址。 我们将使用该电子邮件向您发送过期通知,并就您帐户特有的任何问题进行沟通。

谁是用户

我们的 [CPS 和用户协议](/repository)指明了用户是指拥有证书私钥的人。 对于托管服务提供商而言,订阅者是提供商,而不是提供商的客户。 如果您正在编写允许人们自行部署的软件,那用户就是部署软件的人。

创建帐户(即注册)时提供的联系电子邮件应发送给用户。 我们将向该地址发送电子邮件以警告即将到期的证书,并通知我们[隐私政策](/privacy)的更改。 如果您是托管服务提供商,那些通知应该发送给您而不是客户。 理想情况下,请配置邮件列表或别名,以便在您休假时其他人可以响应通知。

这样做的结果是,如果您是托管服务提供商,您无需向我们发送客户的电子邮件地址或让他们同意我们的用户协议。您只需为您控制的域名颁发证书然后开始使用它们。 您只需为您控制的域名颁发证书然后开始使用它们。

使用一个还是多个账户?

在 ACME 中,可以创建一个帐户并将其用于所有授权和颁发,或者为每个客户创建一个帐户。 这种灵活性可能很有价值。 例如,一些主机提供商可能希望每个客户使用一个帐户,并将帐户密钥存储在不同的地方中,这样即使帐户密钥泄露也不会允许攻击者给所有用户颁发证书。

但是,对于大多数大型托管服务提供商,我们建议使用单个帐户并保护相应的帐户密钥。 这样可以更轻松地识别属于同一实体的证书,更容易保持联系信息处于最新状态,并在需要时更轻松地提供速率限制调整。 如果您使用许多不同的帐户,我们将无法有效调整速率限制。

多域名(SAN)证书

我们的[颁发政策](/docs/rate-limits)允许每个证书最多包含 100 个域名。 无论您是为每个主机名使用单独的证书,还是将许多主机名组合在少量证书上,这都取决于您。

每个主机名使用单独的证书意味着在启用和停用域名时逻辑上进行添加和删除域名所需的更改更少。单独的证书还可以最大限度地减少证书大小,从而加快低带宽网络上的 HTTPS 握手速度。 每个主机名使用单独的证书意味着在启用和停用域名时逻辑上进行添加和删除域名所需的更改更少。单独的证书还可以最大限度地减少证书大小,从而加快低带宽网络上的 HTTPS 握手速度。

另一方面,使用具有许多主机名的大型证书可以让您整体上管理更少的证书。如果您需要支持不支持 TLS 服务器名称指示(SNI)的旧客户端(如 Windows XP),则每个证书都需要一个唯一的 IP 地址 ,因此在每个证书上放置更多域名会减少您需要的 IP 地址数量。 另一方面,使用具有许多主机名的大型证书可以让您整体上管理更少的证书。如果您需要支持不支持 TLS 服务器名称指示(SNI)的旧客户端(如 Windows XP),则每个证书都需要一个唯一的 IP 地址 ,因此在每个证书上放置更多域名会减少您需要的 IP 地址数量。

Let’s Encrypt 的主要价值在于我们允许在创建新网站时自动颁发证书。但是,如果您的基础架构可能会为同一网站重复创建新的前端服务器,那么这些前端应该首先尝试使用来自持久性存储的证书和私钥,并且只在没有可用的证书或者所有现有的证书都已过期的情况下颁发新证书。

存储和重用证书和密钥

Let’s Encrypt 的主要价值在于我们允许在创建新网站时自动颁发证书。 但是,如果您的基础架构可能会为同一网站重复创建新的前端服务器,那么这些前端应该首先尝试使用来自持久性存储的证书和私钥,并且只在没有可用的证书或者所有现有的证书都已过期的情况下颁发新证书。

对于 Let’s Encrypt,这有助于我们为尽可能多的人高效地提供服务。 对您而言,这可以确保您能够随时随地部署您的网站,无论 Let’s Encrypt 的状态如何。

例如,许多站点正在开始使用 Docker 按需配置新的前端实例。 如果您将 Docker 容器设置为在启动时颁发证书,并且您没有持久性地存储证书和密钥,那么您如果一次启动太多实例,就可能会达到速率限制。 在最糟糕的情况下,如果您必须立即销毁并重新创建所有实例,您可能会遇到这样的情况:您的实例都没有能够获得证书,并且您的网站在速率限制结束前会有好几天都无法使用。 而且不仅仅是速率限制会导致这类问题。 如果在需要启动前端时 Let’s Encrypt 出于任何原因不可用,您就会遇到同样的问题。

请注意,某些部署原则指出加密密钥永远不能离开生成它们的物理机器。 只要您确保机器及其数据可以长期使用,并且您仔细管理速率限制,此模型就可以正常使用 Let’s Encrypt。

选择验证方式

您如果正在使用 http-01 ACME 进行验证,则需要先向每个前端提供验证用的回复,然后才能通知 Let’s Encrypt 您已准备好进行验证。 如果您有很多前端服务器,这么做可能非常困难。 在这种情况下,使用 dns-01 进行验证可能会更容易。 当然,您如果有许多地理位置分散的 DNS 响应服务器,则必须确保每个响应服务器上都有验证所需的 TXT 记录。

此外,在使用 dns-01 进行验证时,请务必清理旧的 TXT 记录,以确保对 Let’s Encrypt 的查询的回复不会太大。

如果您想无论如何都要使用 http-01 进行验证,您也许可以利用 HTTP 重定向。 您可以设置每个前端,对于所有“XYZ”,将 /.well-known/acme-validation/XYZ 重定向到 validation-server.example.com/XYZ。 这会将颁发证书的责任委托给验证服务器,因此您需要很好地保护该服务器。

中央验证服务器

与上述两点相关,您如果有很多前端服务器,可能需要使用较小的服务器子集来管理证书颁发。 这样可以更轻松地使用重定向进行 http-01 验证,并提供长期存储证书和密钥的位置。

使用 OCSP 装订

很多浏览器在加载您的网页时会尝试从 Let’s Encrypt 的 OCSP 服务器获取响应。 这会导致一些性能和隐私问题。 理想情况下,连接到网站不应需要等待到 Let’s Encrypt 服务器的辅助连接。 此外,OCSP 请求会向 Let’s Encrypt 泄露用户访问的网站名称。 我们有良好的隐私权政策,所以不会记录 OCSP 请求中能够用于识别个人的信息,如果可以的话我们本不想收到这些数据。 此外我们预计,如果每次浏览器首次访问使用 Let’s Encrypt 证书的站点都会发送 OCSP 请求,为这些请求提供服务的带宽成本将占去我们基础设施支出的一大部分。

通过启用 OCSP 装订,您可以提高网站的性能,为用户提供更好的隐私保护,并帮助 Let’s Encrypt 为尽可能多的人高效地提供服务。

防火墙配置

要使用 Let’s Encrypt,您需要允许来自运行 ACME 客户端的计算机的 443 端口上的出站通信。 我们不会公布我们的 ACME 服务使用的 IP 范围,它们可能在不另行通知的情况下改变。

如果您 “http-01” ACME 验证方法,您需要允许 80 端口上的入站通信。 我们不会公布执行验证的 IP 范围,它们可能在不另行通知的情况下改变。

注意:我们建议始终允许对 Web 服务器进行纯 HTTP 访问,并将其重定向到 HTTPS。 这比拒绝或丢弃 80 端口连接的 Web 服务器提供更好的用户体验,并提供相同级别的安全性。

对于所有验证类型,您都需要允许到您的权威 DNS 服务器的 53 端口上的入站流量(TCP和UDP)。

支持的密钥算法

让我们加密我们接受2048、3072或4096位长的 RSA 密钥和P-256 或 P-384 ECDSA 密钥。 对于帐户密钥和证书密钥来说都是如此。 您不能将帐户密钥重用为证书密钥。

我们建议托管服务提供商自动颁发证书并为其控制的所有主机名配置 HTTPS,并且允许用户选择是否将 HTTP 链接重定向到等效的 HTTPS 链接。我们建议为现有帐户在默认情况下禁用该设置,但为新帐户在默认情况下启用该设置。

默认使用 HTTPS

我们建议托管服务提供商自动颁发证书并为其控制的所有主机名配置 HTTPS,并且允许用户选择是否将 HTTP 链接重定向到等效的 HTTPS 链接。 我们建议为现有帐户在默认情况下禁用该设置,但为新帐户在默认情况下启用该设置。

原因:现有网站可能包含一些 HTTP 子资源(脚本,CSS 和图像)。 如果将这些站点自动重定向到其 HTTPS 版本,则由于混合内容阻断,浏览器将阻止其中一些子资源的加载。 这可能会破坏网站上的功能。 但是,创建新网站并发现 HTTPS 重定向的人基本上一定会只包含 HTTPS 子资源,因为如果他们尝试包含 HTTP 子资源,他们会立即注意到该资源无法正常工作。

我们建议允许客户设置 HTTP 严格传输安全(HSTS)标头,并默认设置有效期为 60 天。 但是,应在此设置旁显示警告:如果客户需要转移到不提供 HTTPS 的托管服务提供商,则浏览器中的缓存 HSTS 设置将使其网站不可用。 此外,客户和托管服务提供商都应该知道 HSTS 标头会将证书错误变为硬故障。 例如,虽然人们通常可以通过点击按钮忽略浏览器关于名称不匹配或证书过期的警告,但浏览器不允许对具有有效的 HSTS 标头的主机名这么做。

续期时间

我们建议在有效期剩余三分之一时自动续期证书。 由于 Let’s Encrypt 当前颁发有效期为 90 天的证书,这意味着在到期前 30 天进行续期。

如果您要为超过 10000 个主机名颁发证书,我们建议进行小批量自动续期,而不是批量进行大量证书的续期。 这样做可以降低风险:如果 Let’s Encrypt 在您需要续期时服务中断,或者您的续期系统出现暂时性故障,那么这些问题只会影响您的一部分而不是所有证书。 它还使我们能够更简单地进行服务器处理能力的规划。

您可以批量颁发所有域名的证书以快速配置服务器,这没什么问题。 然后,您可以在正常续期前一天续期一部分证书,再在第二天再续期一部分,等等,这样可以分散各个证书续期的时间。

如果您的客户端软件会自动配置定期批处理作业,请确保在一天中随机选择确切的时间来运行,而不是始终在特定时间运行。 这可以确保 Let’s Encrypt 不会在每小时的开头遇到过高的流量峰值。 由于 Let’s Encrypt 需要增加服务器处理能力来满足峰值负载,降低流量峰值可以帮助我们降低成本。

重试失败的验证

续期失败不应被视为致命错误。 您应该在颁发服务中使用指数式退避模式来实现优雅的重试逻辑,并将重试等待时间的最大值限制为每天对一张证书进行一次重试。 例如,以下是一个合理的退避时间表:一分钟后第一次重试,十分钟后第二次重试,一百分钟后第三次重试,一天后进行第四次和随后的重试。 当然您也应该允许管理员按域名或对全局提提前进行重试。

重试时使用退避算法意味着您的颁发软件应该同时跟踪失败和成功的尝试,并在尝试重新颁发之前检查最近是否有失败。 每小时尝试数百次颁发是没有意义的,因为重复遇到的失败可能是持久性的。

您应将所有错误发送给负责的管理员,以查看是否有特定问题需要修复。