Apache 模块 mod_md

Summary

此模块 Management 一个或多个虚拟主机的域的通用属性。它有两个主要目的：一是通过 ACME 协议(RFC 8555)监督/更新 https：证书。证书将在过期之前由模块进行更新，以解决互联网服务中断的问题。有一些方法可以监视以这种方式 Management 的所有证书的状态，以及可以在续订，到期和错误时运行您自己的通知命令的配置。

其次，mod_md 提供了备用的 OCSP 装订实现。这适用于托管证书以及您自己配置的证书。 OCSP 装订对于任何 https：站点都是必不可少的组件，它会影响页面加载时间，并根据其他设置影响页面可用性。在下面的装订部分中有更多内容。

默认的 ACME Management 证书的机构是Let's Encrypt，但是可以配置另一个支持该协议的 CA。

简单的配置示例：

MDomain example.org

<VirtualHost *:443>
ServerName example.org
DocumentRoot htdocs/a

SSLEngine on
# no certificates specification
</VirtualHost>

Protocols h2 http/1.1 acme-tls/1

MDChallengeDns01 /usr/bin/acme-setup-dns

/usr/bin/acme-setup-dns setup mydomain.com challenge-data
# this needs to remove all existing DNS TXT records for 
# _acme-challenge.mydomain.com and create a new one with 
# content "challenge-data"

/usr/bin/acme-setup-dns teardown mydomain.com
# this needs to remove all existing DNS TXT records for 
# _acme-challenge.mydomain.com

<Location "/md-status">
SetHandler md-status
</Location>

> curl https://<yourhost>/md-status/another-domain.org
{
"name": "another-domain.org",
"domains": [
"another-domain.org",
"www.another-domain.org"
],
...

{
"when": "Wed, 19 Jun 2019 14:45:58 GMT",
"type": "progress", "detail": "The certificate for the managed domain has been renewed successfully and can be used. A graceful server restart now is recommended."
},{
"when": "Wed, 19 Jun 2019 14:45:58 GMT",
"type": "progress", "detail": "Retrieving certificate chain for test-901-003-1560955549.org"
},{
"when": "Wed, 19 Jun 2019 14:45:58 GMT",
"type": "progress", "detail": "Waiting for finalized order to become valid"
},{
"when": "Wed, 19 Jun 2019 14:45:50 GMT",
"type": "progress", "detail": "Submitting CSR to CA for test-901-003-1560955549.org"
},
...

<MDomain mydomain.net>
MDStapling on
</MDomain>

MDActivationDelay Directive

MDBaseServer Directive

控制基本服务器(所有 VirtualHost 外部的服务器)是否应由 mod_md Management。默认情况下不会。由于它可能具有令人困惑的副作用的原因。建议您为所有受管域都拥有虚拟主机，并且不要依赖于全局备用服务器配置。

MDCAChallenges Directive

在证明域所有权时设置挑战类型(按优先 Sequences)。该模块支持挑战方法“ tls-alpn-01”，“ dns-01”和“ http-01”。该模块将查看服务器的整体配置，以找出可以使用的方法。

例如，如果服务器在端口 80 上侦听，则“ http-01”方法可用。 “ dns-01”的先决条件是已配置的MDChallengeDns01命令。上面的“ https：挑战”中介绍了“ tls-alpn-01”。

此自动选择适用于大多数设置。但是，由于 Apache 是具有许多配置选项的功能非常强大的服务器，因此并非在所有可能的情况下都存在这种情况。例如：它可以侦听多个 IP 地址，其中某些 IP 地址可以在 https：上访问，而有些 IP 地址则无法访问。

如果直接配置MDCAChallenges，则会禁用此自动选择。相反，模块在与 ACME 服务器通话时将使用配置的质询列表(质询类型也必须由服务器提供)。将按照指定的 Sequences 检查这些挑战。

MDCertificateAgreement Directive

当您使用 mod_md 获得证书时，您就成为了 CA 的 Client(例如，让我们加密)。这意味着您需要阅读并同意他们的服务条款，以便您了解他们提供的服务以及他们可能排除或要求您提供的服务。 mod_md 本身不能同意这样的事情。

MDCertificateAuthority Directive

CA 提供服务的 URL。

现在让我们加密提供四个此类 URL。两个用于 ACME 协议自己的旧版本，通常称为 ACMEv1.还有两个用于 RFC 8555 版本的名称为 ACMEv2.

每个版本都有 2 个端点，因为它们是生产端点和用于测试的“登台”端点。测试端点的工作原理相同，但是不会提供浏览器可以识别的证书。但是，它也有非常宽松的速率限制。这样就可以重复测试服务，而不会阻塞自己。

LE 舞台设置

MDCertificateAuthority https://acme-staging-v02.api.letsencrypt.org/directory

MDCertificateCheck Directive

MDCertificateFile Directive

它在MDomainSet内使用，并指定保存受管域的证书链的文件。匹配密钥是通过MDCertificateKeyFile指定的。

Example

<MDomain mydomain.com>
  MDCertificateFile /etc/ssl/my.cert
  MDCertificateKeyFile /etc/ssl/my.key
</MDomain>

这等效于 mod_ssl SSLCertificateFile指令。它有多种用途。

如果要使用静态文件将现有域迁移到一个自动的“我们加密”证书中。您定义MDomainSet，在此处添加文件，然后从 VirtualHosts 中删除SSLCertificateFile。

这将为您提供与以前相同的功能，并且配置中的重复行可能更少。然后，您可以向其中添加MDRenewMode“ always”(始终)，该模块将在文件中的证书过期之前获得新证书。完成此操作后，请删除MDCertificateFile并重新加载服务器。

另一个用例是您与其他 ACME Client 端(例如出色的certbot)续订“加密加密”证书。然后，让您的 MD 指向 certbot 中的文件，并使它们一起工作。

MDCertificateKeyFile Directive

它在MDomainSet内部使用，并指定包含托管域私钥的文件。匹配的证书是通过MDCertificateFile指定的。

这等效于 mod_ssl SSLCertificateKeyFile指令。

MDCertificateMonitor Directive

这是“服务器状态” HTML 用户界面的一部分，与核心功能本身无关。它定义了该页面上提供的链接，用于轻松检查证书监视器。证书的 SHA256 指纹将附加到配置的 URL。

证书监视器提供对证书透明度(CT)日志的监督，以跟踪域证书的使用。您可能至少会看到，Let's Encrypt(或您配置的任何 CA)已经将证书 Importing 到 CTLogs 中。

注意：证书日志更新和监视器对这些更新的接收会受到一些延迟。这在日志和监视器之间有所不同。全新证书不会立即被知晓。

MDCertificateProtocol Directive

指定要使用的协议。当前仅支持ACME。

MDCertificateStatus Directive

启用后，“ https：//domain/.httpd/certificate-status”中的“受管域”中的资源可用，该资源将返回当前证书和续订证书的 JSON 文档列表键属性(如果有)。

Example

{
  "valid-until": "Thu, 29 Aug 2019 16:06:35 GMT",
  "valid-from": "Fri, 31 May 2019 16:06:35 GMT",
  "serial": "03039C464D454EDE79FCD2CAE859F668F269",
  "sha256-fingerprint": "1ff3bfd2c7c199489ed04df6e29a9b4ea6c015fe8a1b0ce3deb88afc751e352d"
  "renewal" : { ...renewed cert information... }
}

MDChallengeDns01 Directive

定义需要设置/销毁“ dns-01”质询时要调用的程序。该程序被赋予参数“ setup”或“ teardown”，后跟域名。对于“设置”，还提供了挑战内容。

只要可以使用'http：'或'https：'质询方法，就无需指定此选项。但是，“让我们加密”使“ dns-01”成为通配符证书可用的唯一挑战。如果您需要其中之一，则需要进行配置。

有关更多详细信息，请参见上面有关通配符证书的部分。

MDContactEmail Directive

ACME 协议要求您在注册时提供联系人网址。目前，Let's Encrypt 需要一个电子邮件地址(它将使用它来通知您有关续订或更改的服务条款)。 mod_md在您的 Apache 配置中使用MDContactEmail指令电子邮件，因此请在此处指定正确的地址。如果MDContactEmail不存在，则mod_md将使用ServerAdmin指令。

MDDriveMode Directive

存在此指令是为了向后兼容，它是MDRenewMode的旧名称。

MDHttpProxy Directive

使用 http 代理连接到MDCertificateAuthority。如果您的 Web Service 器只能通过转发代理访问 Internet，请进行定义。

MDMember Directive

您可以使用MDMember将此类名称添加到托管域中，而不是在同一行上列出所有 DNS 名称。

Example

<MDomain example.org>
    MDMember www.example.org
    MDMember mail.example.org
</MDomain>

如果在特定 MD 之外的全局上下文中使用它，则只能将一个值“ auto”或“ manual”指定为所有其他 MD 的默认值。有关这些特殊值的说明，请参见MDomain。

MDMembers Directive

定义是否将 VirtualHost 的ServerName和ServerAlias值自动添加到托管域的成员。

MDMessageCmd Directive

当受管域发生以下事件之一时，将调用此命令：“更新”，“已安装”，“到期”，“错误”。将来可能会调用更多命令，并忽略不准备处理的事件。

这是MDNotifyCmd的更灵活的伴侣。

Example

MDMessageCmd /etc/apache/md-message

# will be invoked when a new certificate for mydomain.org is available as: /etc/apache/md-message renewed mydomain.com

程序不应阻塞，因为模块将 await 其完成。非 0 的返回码被视为错误。

“错误”并不是引起立即关注的直接原因，因为尽早进行更新以使互联网恢复正常。每小时最多报告一次。

“到期”应当真。到达MDWarnWindow时发出。默认情况下，这是证书生存期的 10％，因此，对于“让我们加密”来说，当前意味着证书到期前 9 天。该警告每天最多重复一次。

“更新”表示已获取新证书，并将其存储在 MD 存储区的“登台”区域中。它将在下次服务器重新启动/重新加载时被激活。

当新证书已从登台转移到 MD 存储区中的域位置时，将触发“已安装”。这在服务器启动/重新加载时发生。与所有其他调用不同，MDMessageCmd以 root 权限运行(在* nix 系统上)，并且可以访问证书文件(和密钥)。可以在此事件上处理其他应用程序或其他格式所需的证书。

MDMustStaple Directive

定义新请求的证书是否应设置“ OCSP 必须装订”标志。如果证书具有此标志，则要求服务器向每个 Client 端发送 OCSP 装订响应。仅当您配置mod_ssl生成此代码(请参阅SSLUseStapling和朋友)时，此方法才有效。

MDNotifyCmd Directive

当受管域注册或更新其证书时，将运行配置的可执行文件。给它作为附加参数的已处理 MD 的名称(在此处指定的参数之后)。它应该返回状态代码 0 以指示它已经成功运行。

MDomain Directive

列表中的所有名称都作为一个受管域(MD)进行 Management。 mod_md 将请求一个对所有这些名称均有效的单个证书。该指令使用全局设置(请参阅下面的其他 MD 指令)。如果您需要一个 MD 的特定设置，请使用<MDomainSet>。

受管域还需要进行 2 个其他设置：联系人电子邮件地址(通过MDContactEmail或ServerAdmin)和MDCertificateAgreement。 ServerAdmin的邮件地址用于在 CA 进行注册(默认情况下为“让我们加密”)。 CA 可能会使用它来通知您有关其服务或证书状态的更改。

第二个设置MDCertificateAgreement的值应为“ accepted”。通过指定此选项，您确认您接受 CA 的服务条款。

Example

MDContactEmail admin@example.org
MDCertificateAgreement accepted
MDomain example.org www.example.org

<VirtualHost *:443>
    ServerName example.org
    DocumentRoot htdocs/root

    SSLEngine on
</VirtualHost>

<VirtualHost *:443>
    ServerName www.example.org
    DocumentRoot htdocs/www

    SSLEngine on
</VirtualHost>

您可以在此指令中使用两个特殊名称：“ manual”和“ auto”。这决定了受管域是否应具有已配置(“手动”)的名称列表，还是提供更多便利。通过“自动”，虚拟主机的所有名称都将添加到 MD。方便地，“自动”也是默认设置。

Example

MDomain example.org

<VirtualHost *:443>
    ServerName example.org
    ServerAlias www.example.org
    DocumentRoot htdocs/root

    SSLEngine on
</VirtualHost>

MDomain example2.org auto

<VirtualHost *:443>
    ServerName example2.org
    ServerAlias www.example2.org
    ...
</VirtualHost>

在此示例中，域“ www.example.org”会自动添加到 MD“ example.org”中。与“ example2.org”类似，其中“ auto”被显式配置。每当您向该虚拟主机添加更多 ServerAlias 名称时，它们也将被添加到托管域中。

如果您希望显式声明所有域名，请使用“手动”模式。如果名称与预期名称不匹配，将记录错误。

Directive

这是指令MDomain，它具有仅为此 MD 添加设置的可能性。实际上，您也可以使用“ <MDomain ..>”作为快捷方式。

这允许您配置使用其他证书颁发机构，具有其他续订要求等的 MD。

Example

<MDomain sandbox.example.org>
    MDCertificateAuthority   https://someotherca.com/ACME
</MDomain>

一个常见的用例是为您的域分别配置 https：要求。

Example

<MDomain example.org>
    MDRequireHttps temporary
</MDomain>

MDPortMap Directive

ACME 协议提供了两种通过 HTTP 验证域所有权的方法：一种使用“ http：” URL(端口 80)，一种使用“ https：” URL(端口 443)。如果您的服务器无法通过两者之一访问，则 ACME 只能通过配置 DNS 服务器来工作，请参阅MDChallengeDns01。

在大多数面向公众的服务器上，“ http：”到达端口 80，“ https：”到达端口 443.该模块检查 Apache 服务器正在侦听的端口，并假定这些端口可用。这意味着，当您的服务器未在端口 80 上侦听时，它将假定来自 Internet 的“ http：”请求将不起作用。

这是一个很好的猜测，但可能是错误的。例如，您的 Apache 可能监听 80 端口，但是您的防火墙可能阻止了它。 “ http：”仅在您的 Intranet 中可用。因此，该模块将错误地认为 Let's Encrypt 可以在服务器上使用“ http：”挑战。然后这将失败，因为您的防火墙将丢弃那些防火墙。

Example

MDPortMap http:- https:8433

上面的示例显示了如何指定来自互联网的“ http：”请求永远不会到达。此外，它还说“ https：”请求将到达本地端口 8433.

如果有适当的端口转发，这是必要的，则可以从 Internet 上的端口 443 访问服务器，但是 httpd 使用的本地端口是另一个。您的服务器可能仅侦听端口 8443 和 8000，但可以侦听端口 443 和 80(来自 Internet)。

MDPrivateKeys Directive

定义为托管域生成哪种私钥以及使用什么参数。现在唯一受支持的类型是“ RSA”，并且它采用的唯一参数是密钥所使用的位数。

当前(2017 年)建议至少为 2048 位，此处不接受较小的数字。较高的数字可提供更长的安全性，但在计算上更昂贵，例如增加服务器上的负载。这可能对您来说不是问题。

其他密钥类型将在以后定义。

Example

MDPrivateKeys RSA 3072

请注意，此设置仅对新键有效。您拥有的任何现有私钥均不会受到影响。同样，这仅影响为证书生成的私钥。 ACME 帐户密钥不受此影响。

MDRenewMode Directive

在默认的“自动”模式下，该模块将执行每个受管域最有意义的操作。对于没有证书的域，它将从证书颁发机构获得证书。

但是，如果您定义的 MD 未被 Apache 的任何 VirtualHost 使用，则它不会打扰。对于具有静态证书文件的 MD(请参阅MDCertificateFile)，它假定您拥有自己的源，并且也不会续订它们。

您可以通过两种方式覆盖此默认设置。如果指定“ always”(始终)，则模块将续签 MD 的证书，而不管域是否正在使用或是否有静态文件。

为了达到相反的效果，请配置“手动”，并且不会尝试进行任何更新。

MDRenewWindow Directive

如果证书的有效性低于持续时间，则 mod_md 将获得新的签名证书。

通常，证书的有效期大约为 90 天，mod_md 会在证书过期之前最早将其续约 33％进行续签(因此，对于 90 天的有效期，证书应在过期 30 天之前进行续签)。如果您认为这不是您所需要的，则可以指定确切的时间，例如：

Example

# 21 days before expiry
MDRenewWindow 21d 
# 30 seconds (might be close)
MDRenewWindow 30s
# 10% of the cert lifetime
MDRenewWindow 10%

在自动驱动模式下，该模块至少每 12 小时检查一次托管域的状态以及是否需要执行某些操作。对于错误(例如，当 CA 无法访问时)，它将在几秒钟后最初重试。如果该操作 continue 失败，它将退回至每小时检查的最大间隔。

MDRequireHttps Directive

这是一个方便的指令，可简化从托管域的 http：到 https：的迁移。带有：

Example

MDRequireHttps temporary

您宣布暂时希望将所有通过 http：URL 的流量重定向到 https:。这是安全的，您可以随时再次将其删除。

以下结果： 如果您希望 Client 端 不再 使用 http：URL，请配置：

永久(至少半年！)

MDRequireHttps permanent

这有两件事：

• 使用301状态代码，使用https:方案将对http:资源的所有请求重定向到相同的 url。这告诉 Client 这将永远存在，并且应该相应地更新他们拥有的所有链接。

• 对https:个请求的所有答案都将带有标题Strict-Transport-Security，其使用期限为半年。这告诉浏览器，与该域名通话时，它**绝(半年)永远不要使用http:。浏览器在看到此信息后将拒绝与您未加密的网站联系。这样可以防止恶意中间件降级连接并监听/操纵流量。哪个好但是您不能简单地再次将其收回。

基本上，您可以使用mod_alias和某些Redirect配置实现相同的目的。如果您自己执行此操作，请确保从重定向中排除路径/.well-known/*，否则 mod_md 可能无法在新证书上签名。

如果全局设置，则它适用于所有托管域。如果只希望将其用于特定域，请使用：

Example

<MDomain xxx.yyy>
  MDRequireHttps temporary
</MDomain>

MDServerStatus Directive

Apache 的“服务器状态”处理程序允许您配置资源以监视正在发生的事情。现在，该部分列出了所有托管域，其中包括 DNS 名称，续订状态，生存期和主要属性。

您可以使用此指令将其关闭。

MDStapleOthers Directive

此设置仅在启用MDStapling时生效。它控制mod_md是否还应为不受其直接控制的证书提供装订信息，例如通过 ACME CA 更新。

MDStapling Directive

mod_md提供了用于提供 OCSP 装订信息的实现。这是mod_ssl提供的替代方法。为了向后兼容，默认情况下禁用此功能。

可以为服务器上的所有证书或单个MDomain打开装订。这将替换这些主机在mod_ssl中的任何装订配置。禁用后，mod_ssl装订将完成工作(当然，如果它本身已启用)。这允许从一种实现逐渐过渡到另一种实现。

mod_md装订也适用于该模块未 Management 证书的域(有关如何控制此证书的信息，请参见MDStapleOthers)。这允许使用新的装订而不使用任何 ACME 证书 Management。

MDStaplingKeepResponse Directive

该时间窗口指定何时应再次从存储中删除用于装订的 OCSP 响应数据。超过 7 天(默认)的响应信息会在服务器重新启动/重新加载时删除。当证书经常更新/重新配置时，这可以防止 Store 增长。

MDStaplingRenewWindow Directive

如果装订中使用的 OCSP 响应的有效性低于持续时间，则mod_md将获得新的 OCSP 响应。

颁发证书的 CA 通常还会操作 OCSP 响应程序服务，并确定其有关证书有效性的已签名响应本身有效的时间。有效的响应时间越长，可以缓存的时间就越长，这意味着每个人的整体性能都更好。生存时间越短，证书吊销越快地传播到 Client 端。此外，服务可靠性也是一个考虑因素。

通过调整装订续订窗口，您可以自己控制部分内容。如果您将续订时间缩短(例如，在当前信息过期之前的很短时间)，则会获得最大的缓存时间。但是服务中断(例如停机维护)会影响您。如果您在到期前很长的时间进行更新，更新将变得更加频繁，这将导致 CA 服务器基础结构上的负载增加，并且服务器的子进程之间的协调也将更多。

默认值选择为 33％，这意味着仅剩余响应寿命的三分之一时便开始更新。对于发出 OCSP 响应且生存期为 3 天的 CA，这意味着 2 天的缓存和 1 天的续订尝试。服务中断必须持续 24 小时才能影响您的域。

也可以设置一个绝对更新窗口，例如“ 2d”(2 天)。

MDStoreDir Directive

定义托管域数据在本地文件系统上的存储位置。这是相对于服务器根目录的绝对路径或相对路径。默认值将在服务器根目录中创建目录“ md”。

如果您进行了移动并且已经有数据，请确保先将数据移动/复制到新位置，重新配置然后重新启动服务器。如果重新配置并首先重新启动，则服务器将尝试获取它认为缺少的新证书。

MDWarnWindow Directive

有关如何指定时间的说明，请参见MDRenewWindow。

模块检查证书的剩余寿命，并在剩余的警告窗口不足时调用MDMessageCmd。默认情况下，这意味着来自 Let's Encrypt 的证书需要 9 天。

它也适用于带有静态证书文件的受管域(请参阅MDCertificateFile)。