unixcharles/acme-client

# Acme::Client `acme-client` 是 ACME / [RFC 8555](https://tools.ietf.org/html/rfc8555) 协议的 Ruby 客户端实现。 你可以找到 Go 语言的 [服务端](https://github.com/letsencrypt/boulder) 和 Python 语言的 [客户端](https://github.com/certbot/certbot) 的 ACME 参考实现。 ACME 是 [Letsencrypt](https://letsencrypt.org/) 项目的一部分，该项目的目标是通过自动化获取和更新流程来提供免费的 SSL/TLS 证书。 ## 安装 通过 RubyGems： ``` $ gem install acme-client ``` 或者将其添加到 Gemfile 中： ``` gem 'acme-client' ``` ## 用法 - [Acme::Client](#acmeclient) - [安装](#installation) - [用法](#usage) - [设置客户端](#setting-up-a-client) - [账户管理](#account-management) - [获取证书](#obtaining-a-certificate) - [订购证书](#ordering-a-certificate) - [准备 HTTP 验证](#preparing-for-http-challenge) - [准备 DNS 验证](#preparing-for-dns-challenge) - [请求验证核查](#requesting-a-challenge-verification) - [下载证书](#downloading-a-certificate) - [订购备用证书](#ordering-an-alternative-certificate) - [额外](#extra) - [证书吊销](#certificate-revokation) - [证书续期](#certificate-renewal) - [未实现](#not-implemented) - [环境要求](#requirements) - [开发](#development) - [Pull request?](#pull-request) - [许可证](#license) ## 设置客户端 客户端使用私钥和 ACME 提供商的 directory URL 进行初始化。 LetsEncrypt 的 `directory` URL 是 `https://acme-v02.api.letsencrypt.org/directory`。 他们还有一个 staging endpoint，地址为 `https://acme-staging-v02.api.letsencrypt.org/directory`。 `acme-ruby` 接受 `OpenSSL::PKey::RSA` 或 `OpenSSL::PKey::EC`。 你可以使用 OpenSSL 在 Ruby 中生成一个。 ``` require 'openssl' private_key = OpenSSL::PKey::RSA.new(4096) ``` 或者从 PEM 文件加载 ``` require 'openssl' OpenSSL::PKey::RSA.new(File.read('/path/to/private_key.pem')) ``` 有关文档，请参阅 [RSA](https://ruby.github.io/openssl/OpenSSL/PKey/RSA.html) 和 [EC](https://ruby.github.io/openssl/OpenSSL/PKey/EC.html)。 ``` client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory') ``` 如果你的账户已经注册，你可以通过直接传入 key ID 来节省一些 API 调用。这将避免从私钥检索 key ID 的多余 API 调用。 ``` client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory', kid: 'https://example.com/acme/acct/1') ``` ## 账户管理 账户与私钥绑定。在允许创建订单之前，必须注册账户并使用私钥接受服务条款 (ToS)。账户将被分配一个 key ID。 ``` client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory') account = client.new_account(contact: 'mailto:info@example.com', terms_of_service_agreed: true) ``` 注册后，你可以检索账户密钥标识符 (kid)。 ``` client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory') account = client.new_account(contact: 'mailto:info@example.com', terms_of_service_agreed: true) account.kid # => ``` 如果你已经拥有一个现有账户（例如在 ACME v1 中创建的账户），请注意，除非在初始化时提供了 `kid`，否则客户端会在需要 `kid` 时通过向 `newAccount` 发送 `POST` 请求来延迟加载 `kid`。因此，你可以轻松获取现有账户的 `kid`，并（如果需要）将其存储以供复用： ``` client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory') # kid 未设置，因此调用 newAccount 以懒加载初始化 kid client.kid => "https://acme-staging-v02.api.letsencrypt.org/acme/acct/000000" ``` ## 外部账户绑定支持 你可以通过提供带有 `kid` 和 `hmac_key` 的 `external_account_binding` 来使用外部账户绑定。 ``` client = Acme::Client.new(private_key: private_key, directory: 'https://acme.zerossl.com/v2/DV90') account = client.new_account(contact: 'mailto:info@example.com', terms_of_service_agreed: true, external_account_binding: { kid: "your kid", hmac_key: "your hmac key"}) ``` ## 获取证书 ### 订购证书 要订购新证书，客户端必须提供标识符列表。 返回的订单将包含一系列 `Authorization`，为了完成订单，这些授权需要被完成，通常每个标识符对应一个。 每个授权包含多个挑战 (challenge)，通常是 `dns-01`、`dns-account-01` 和 `http-01` 挑战。申请人只需完成其中一项挑战。 `dns-account-01` 挑战在 `_acme-challenge` 之前添加一个特定于账户的标签，生成形式为 `_._acme-challenge` 的记录名称，以便不同的客户端可以同时验证同一个域名。 你可以使用 `#dns`、`#dns_account` 或 `#http` 方法访问你希望完成的挑战。 ``` order = client.new_order(identifiers: ['example.com']) authorization = order.authorizations.first challenge = authorization.http ``` ### 准备 HTTP 验证 要完成 HTTP 验证，你必须通过 HTTP 返回一个文件。 路径遵循以下格式： 文件内容是 key authorization。HTTP01 对象提供了生成它们的实用方法。 ``` > http_challenge.content_type # => 'text/plain' > http_challenge.file_content # => example_token.TO1xJ0UDgfQ8WY5zT3txynup87UU3PhcDEIcuPyw4QU > http_challenge.filename # => '.well-known/acme-challenge/example_token' > http_challenge.token # => 'example_token' ``` 出于测试目的，你可以直接保存验证文件并使用 Ruby 提供服务： ``` ruby -run -e httpd public -p 8080 --bind-address 0.0.0.0 ``` ### 准备 DNS 验证 要完成 DNS 验证，你必须设置一条 DNS 记录以证明你拥有该域名的控制权。 DNS01 对象提供了生成它们的实用方法。 ``` dns_challenge.record_name # => '_acme-challenge' dns_challenge.record_type # => 'TXT' dns_challenge.record_content # => 'HRV3PS5sRDyV-ous4HJk4z24s5JjmUTjcCaUjFt28-8' ``` ### 准备 DNS-Account-01 验证 要完成 DNS-Account-01 验证，你必须使用特定于账户的名称设置一条 DNS TXT 记录。这允许不同的 ACME 客户端同时验证同一个域名而不发生冲突。 DNSAccount01 对象提供了生成所需 DNS 记录的实用方法： ``` dns_account_challenge = authorization.dns_account dns_account_challenge.record_name # => '_ujmmovf2vn55tgye._acme-challenge' dns_account_challenge.record_type # => 'TXT' dns_account_challenge.record_content # => 'HRV3PS5sRDyV-ous4HJk4z24s5JjmUTjcCaUjFt28-8' ``` 记录名称包含一个从你的账户 URL 派生的特定于账户的标签，确保不同的客户端可以同时进行验证： - **DNS-01**: `_acme-challenge.example.com` (共享) - **DNS-Account-01**: `_ujmmovf2vn55tgye._acme-challenge.example.com` (特定于账户) ### 请求验证核查 一旦你准备好完成挑战，就可以请求服务器执行验证。 ``` challenge.request_validation ``` 验证是异步执行的，服务器执行可能需要一些时间。 你可以轮询直到其状态发生变化。 ``` while challenge.status == 'pending' sleep(2) challenge.reload end challenge.status # => 'valid' ``` ### 下载证书 一旦所有必需的授权都通过挑战得到了验证，就可以使用 CSR ([Certificate Signing Request](https://en.wikipedia.org/wiki/Certificate_signing_request)) 完成订单。 使用 Ruby 标准库中的 OpenSSL 生成 CSR 可能稍微有些棘手。`acme-client` 提供了一个实用工具类 `CertificateRequest` 来提供帮助。你需要为证书请求使用与 `Acme::Client` 账户不同的私钥。 证书生成是异步发生的。你可能需要轮询。 ``` csr = Acme::Client::CertificateRequest.new(private_key: a_different_private_key, subject: { common_name: 'example.com' }) order.finalize(csr: csr) while order.status == 'processing' sleep(1) order.reload end order.certificate # => PEM-formatted certificate ``` ### 订购备用证书 提供商可能会提供具有不同证书链的备用证书。你可以指定所需的链，客户端将自动下载备用证书并按名称匹配链。 ``` begin order.certificate(force_chain: 'DST Root CA X3') rescue Acme::Client::Error::ForcedChainNotFound order.certificate end ``` 注意：如果指定的强制链与现有的备用证书不匹配，该方法将引发 `Acme::Client::Error::ForcedChainNotFound` 错误。 在 [此处](https://github.com/unixcharles/acme-client/issues/186) 了解更多关于此客户端的原始 Github issue，来自 Let's Encrypt 的信息在 [此处](https://letsencrypt.org/2019/04/15/transitioning-to-isrg-root.html)，以及关于交叉签名的信息在 [此处](https://letsencrypt.org/certificates/#cross-signing)。 ## 额外 ### 证书吊销 要吊销证书，你可以使用证书调用 `#revoke`。 ``` client.revoke(certificate: certificate) ``` ### 证书续期 没有续期流程，只需创建一个新订单。 ### 账户密钥更换 要更改账户使用的密钥，你可以使用新的私钥或 jwk 调用 `#account_key_change`。 ``` require 'openssl' new_private_key = OpenSSL::PKey::RSA.new(4096) client.account_key_change(new_private_key: new_private_key) ``` ### Profile Extension 在创建新订单时提供 CA profile： ``` order = client.new_order(identifiers: ['example.com'], profile: 'shortlived') ``` ACME 服务器可能会在 directory endpoint 中列出支持的 profile： ``` client.profiles => {"classic": "https://example.com/docs/classic", "shortlived": "https://example.com/docs/shortlived"} ``` 有关更多信息，请参阅 [RFC draft of certificate profiles](https://datatracker.ietf.org/doc/draft-aaron-acme-profiles/)。 ## 环境要求 Ruby >= 3.0 ## 开发 所有测试都使用 VCR 来模拟与服务器的交互。如果你需要记录新的交互，可以使用 `ACME_DIRECTORY_URL` 环境变量指定 directory URL。 ``` ACME_DIRECTORY_URL=https://acme-staging-v02.api.letsencrypt.org/directory rspec ``` ## Pull request? 是的。 ## 许可证 [MIT License](http://opensource.org/licenses/MIT)

标签：ACME协议, DNS验证, Gem包, HTTP验证, Let's Encrypt, OpenSSL, RFC 8555, Ruby, SSL证书, TLS, Web服务器, 加密, 安全测试工具, 客户端库, 密码学, 开源库, 手动系统调用, 搜索引擎爬虫, 漏洞扫描器, 知识库, 网络安全, 网络调试, 自动化, 证书管理, 证书颁发机构, 防御工具, 隐私保护