库

您可以在 docs.rs 中阅读整个 API 文档。您可以通过将以下行添加到您的 Cargo.toml 中来使用 acme-client 库。

[dependencies]
acme-client = "0.5"

默认情况下，acme-client 将构建 CLI。您可以使用以下命令禁用此操作：

[dependencies.acme-client]
version = "0.5"
default-features = false

API 概述

要为域名成功签发 SSL 证书，您需要识别域名的所有权。您还可以为多个域名识别和签署证书，并明确使用您自己的私钥和证书签名请求 (CSR)，否则此库将生成它们。acme-client 的基本用法如下：

use acme_client::Directory;

let directory = Directory::lets_encrypt()?;
let account = directory.account_registration().register()?;

// Create a identifier authorization for example.com
let authorization = account.authorization("example.com")?;

// Validate ownership of example.com with http challenge
let http_challenge = authorization.get_http_challenge().ok_or("HTTP challenge not found")?;
http_challenge.save_key_authorization("/var/www")?;
http_challenge.validate()?;

let cert = account.certificate_signer(&["example.com"]).sign_certificate()?;
cert.save_signed_certificate("certificate.pem")?;
cert.save_private_key("certificate.key")?;

acme-client 支持使用 SAN 为多个域名签署证书。您需要验证每个域名的所有权。

use acme_client::Directory;

let directory = Directory::lets_encrypt()?;
let account = directory.account_registration().register()?;

let domains = ["example.com", "example.org"];

for domain in domains.iter() {
    let authorization = account.authorization(domain)?;
    // ...
}

let cert = account.certificate_signer(&domains).sign_certificate()?;
cert.save_signed_certificate("certificate.pem")?;
cert.save_private_key("certificate.key")?;

账户注册

use acme_client::Directory;

let directory = Directory::lets_encrypt()?;
let account = directory.account_registration()
                       .email("[email protected]")
                       .register()?;

联系电子邮件地址是可选的。您也可以在注册时使用您自己的私钥。有关更多信息，请参阅 AccountRegistration 帮助器。

如果您之前已使用自己的密钥注册，您仍然需要使用 register 方法，在这种情况下，它将识别您的用户账户而不是创建一个新账户。

识别域名所有权

在向 ACME 服务器发送证书签名请求之前，您需要识别您想要为其签署证书的域名的所有权。为此，您需要为域名创建一个授权对象并至少完成一个挑战（对于 Let's Encrypt，是 http 或 dns）。

要为域名创建授权对象

let authorization = account.authorization("example.com")?;

Authorization 对象将包含由 ACME 服务器创建的挑战。您可以创建任意数量的 Authorization 对象来验证域名的所有权。例如，如果您想为 example.com 和 example.org 签署证书

let domains = ["example.com", "example.org"];
for domain in domains.iter() {
    let authorization = account.authorization(domain)?;
    // ...
}

标识符验证挑战

当您向 ACME 服务器发送授权请求时，它将生成标识验证挑战，以提供账户持有者也是控制该标识的实体的保证。

HTTP 挑战

使用 HTTP 验证时，ACME 事务中的客户端通过证明它可以配置一个响应该域名的 HTTP 服务器上的资源来证明其对域名的主控权。

acme-client 有 save_key_authorization 方法来将验证文件保存到公共目录中。此目录必须对外界可访问。

let authorization = account.authorization("example.com")?;
let http_challenge = authorization.get_http_challenge().ok_or("HTTP challenge not found")?;

// This method will save key authorization into
// /var/www/.well-known/acme-challenge/ directory.
http_challenge.save_key_authorization("/var/www")?;

// Validate ownership of example.com with http challenge
http_challenge.validate()?;

在验证过程中，ACME 服务器将检查 http://example.com/.well-known/acme-challenge/{token} 以识别域名的所有权。您需要确保标记是公开可访问的。

DNS 挑战

DNS 挑战要求客户端在特定的验证域名下配置包含指定值的 TXT 记录。

acme-client 可以使用 signature 方法生成此值。

用户通过在待验证的域名前添加标签 "_acme-challenge" 来构建验证域名，然后在那个名称下创建一个带有摘要值的TXT记录。例如，如果待验证的域名是 "example.com"，则客户端会创建以下DNS记录

_acme-challenge.example.com: dns_challenge.signature()

使用DNS挑战的示例验证

let authorization = account.authorization("example.com")?;
let dns_challenge = authorization.get_dns_challenge().ok_or("DNS challenge not found")?;
let signature = dns_challenge.signature()?;

// User creates a TXT record for _acme-challenge.example.com with the value of signature.

// Validate ownership of example.com with DNS challenge
dns_challenge.validate()?;

签署证书

在验证所有域名后，您可以发送签名证书请求。acme-client为此提供了CertificateSigner辅助器。您可以使用自己的密钥和CSR，或者让CertificateSigner为您生成它们。

let domains = ["example.com", "example.org"];

// ... validate ownership of domain names

let certificate_signer = account.certificate_signer(&domains);
let cert = certificate_signer.sign_certificate()?;
cert.save_signed_certificate("certificate.pem")?;
cert.save_private_key("certificate.key")?;

撤销已签署的证书

您可以使用revoke_certificate或revoke_certificate_from_file方法撤销已签名的证书。您需要使用之前注册的相同私钥来成功撤销已签名的证书。您也可以使用生成CSR时使用的私钥。

let account = directory.account_registration()
                       .pkey_from_file("user.key")?
                       .register()?;
account.revoke_certificate_from_file("certificate.pem")?;

参考

• IETF ACME 草案
• Let's Encrypt ACME 差异