ACME#

提供使用 ACME协议 的自动证书获取功能。

当 从源代码构建 时，默认不会构建此模块；需要使用 --with-http_acme_module 构建选项 启用。

在来自 我们的软件包 中的包和镜像中，模块已包含在构建中。

在配置中启用证书检索的步骤：

  1. 定义一个ACME客户端 在 http 块中，用 acme_client 指令设置一个唯一的客户端名称和其他选项；可以配置多个ACME客户端。

  2. 指定要请求证书的域名：将为所有 server 块中 server_name 指令列出的域名颁发单个证书，前提是这些块的 acme 指令引用了单个ACME客户端。

  3. 确保接受ACME挑战: 通过保持80端口开放；模块将处理其余部分。目前，Angie仅支持通过HTTP进行的域名验证，这需要响应来自证书颁发机构（CA）的特殊请求，称为ACME挑战。

  4. 使用新获取的证书和密钥配置SSL：模块将其证书和密钥作为 内置变量 暴露，您可以在 配置 中使用它们来填充 ssl_certificate 和 ssl_certificate_key。

实现细节#

客户端密钥和证书使用 PEM编码 存储在由 --http-acme-client-path 参数 设置的目录下的相应子目录中：

$ ls /var/lib/angie/acme/example/

  account.key  certificate.pem  private.key

ACME客户端需要与CA服务器的账户。为了创建和管理账户，客户端使用私人密钥(account.key)；如果尚未拥有，将在启动时创建密钥。然后，客户端使用它在服务器上注册一个账户。

备注

如果您已有现有账户密钥，请在启动前放置到客户端的子目录中以重用账户。

ACME客户端还维护一个专用密钥(private.key)用于证书签名请求（CSR）；如果需要，此证书密钥也会在启动时自动创建。

在启动时，客户端请求一个证书（如果尚未获得），为其管理的所有域名签署并发送CSR到CA服务器。服务器通过HTTP验证域名所有权并颁发证书，客户端在本地存储(certificate.pem)。

当证书接近计划的续订或域名列表更改时，客户端会签署并发送另一个CSR到CA服务器。再次，服务器验证所有权并颁发新证书，客户端在本地安装，替换以前的证书。

配置示例#

这里，一个名为 example 的ACME客户端管理 example.com 和 www.example.com 域名。证书及其密钥通过前缀变量 $acme_cert_<name> 和 $acme_cert_key_<name> 暴露。它们存储各自的文件内容，反过来用于 ssl_certificate 和 ssl_certificate_key：

http {

    resolver 127.0.0.53; # 'acme_client'指令需要

    acme_client example https://acme-v02.api.letsencrypt.org/directory;

    server {

        listen               80;      # 可以出现在另一个服务器块中，
                                      # 使用不同的域名列表
                                      # 甚至不使用

        listen               443 ssl;

        server_name          example.com www.example.com;
        acme                 example;

        ssl_certificate      $acme_cert_example;
        ssl_certificate_key  $acme_cert_key_example;
    }
}

如前所述，80端口必须开放以接受通过HTTP的ACME挑战。然而，如上例所示，listen 指令可能出现在单独的 server 块中。如果没有这样的块存在，您甚至可以将新的块限制为仅接收ACME挑战：

server {
    listen 80;
    return 444; # 无响应，连接被关闭
}

为什么这会起作用？ 模块在读取头部后，但在选择虚拟服务器之前或任何 rewrite 和 location 指令被处理之前，拦截请求 /.well-known/acme-challenge/<TOKEN>。如果 TOKEN 与特定挑战的预期匹配，则处理此类拦截请求。没有实际的目录访问发生；请求由模块完全处理。

指令#

acme#

Syntax

acme name;

Default

—

Context

server

对于所有引用 acme_client 名为 name 的 server 块中的 server_name 指令指定的所有域，将获得单个证书；如果 server_name 配置更改，证书将更新以反映更改。

备注

目前，不支持通配符域和使用正则表达式指定的域，将被忽略。

此指令可以多次指定以加载不同类型的证书，例如，RSA和ECDSA：

server {

    listen 443 ssl;
    server_name example.com www.example.com;

    ssl_certificate $acme_cert_rsa;
    ssl_certificate_key $acme_cert_key_rsa;

    ssl_certificate $acme_cert_ecdsa;
    ssl_certificate_key $acme_cert_key_ecdsa;

    acme rsa;
    acme ecdsa;
}

acme_client#

Syntax

acme_client name uri [enabled=on | off] [key_type=type] [key_bits=number] [email=email] [renew_before_expiry=time] [retry_after_error=off|time];

Default

—

Context

http

在全局范围内定义一个唯一的ACME客户端`name`。它必须对文件目录有效，并将被视为不区分大小写。

第二个必填参数是ACME目录的`uri`。例如，让我们加密ACME目录的URI 列出 为 https://acme-v02.api.letsencrypt.org/directory。

为了使此指令生效，必须在相同上下文中配置 resolver。

备注

出于测试目的，证书颁发机构通常提供单独的测试环境。例如，让我们加密测试环境 当前为 https://acme-staging-v02.api.letsencrypt.org/directory。

enabled

启用或禁用客户端；这很有用，例如，暂时禁用客户端而不将其从配置中移除。

默认：on。

key_type

证书的私钥算法类型。有效值：rsa，ecdsa。

默认：ecdsa。

key_bits

证书密钥的位数。默认：ecdsa 为256，rsa 为2048。

email

用于反馈的可选电子邮件地址；在CA服务器上创建账户时使用。

max_cert_size

指定新证书文件的最大允许大小（以字节为单位），以在共享内存中为新证书保留空间。请求的域越多，需要的空间越多。

如果启动时已存在证书但其大小超过 max_cert_size 的值，则 max_cert_size 值会动态增加以匹配现有证书文件的大小。

如果更新的证书大小超过 max_cert_size，则更新将失败并报错。

默认：8192。

renew_before_expiry

证书到期前的 时间，在此时间点应开始证书更新。

默认：30d。

retry_after_error

在无法获取证书时重试的 时间。如果设置为 off，客户端不会在失败后重试获取证书。

默认：2h。

acme_client_path#

Syntax

acme_client_path path;

Default

—

Context

http

覆盖用于存储证书和密钥的目录的 path，在构建时用 --http-acme-client-path 构建选项 指定。

内置变量#

$acme_cert_<name>#

由此 name 的客户端获得的最后一个证书文件（如果有）的内容。

$acme_cert_key_<name>#

此 name 的客户端使用的证书密钥文件的内容。

重要

证书文件仅在ACME客户端获得至少一个证书后可用，而密钥文件在启动后立即可用。

目录