acme-v2

acme-v2 是一个用于访问 ACME（自动证书管理环境）服务，如 Let's Encrypt 的库。使用 ACME v2 签发/更新证书。

从 acme-lib 分支

此库是从 acme-lib 分支出来的，同时解决了一些原始库中没有解决的问题。

示例

use acme_v2::{Error, Directory, DirectoryUrl};
use acme_v2::persist::FilePersist;
use acme_v2::create_p384_key;

fn request_cert() -> Result<(), Error> {

// Use DirectoryUrl::LetsEncrypStaging for dev/testing.
let url = DirectoryUrl::LetsEncrypt;

// Save/load keys and certificates to current dir.
let persist = FilePersist::new(".");

// Create a directory entrypoint.
let dir = Directory::from_url(persist, url)?;

// Reads the private account key from persistence, or
// creates a new one before accessing the API to establish
// that it's there.
let acc = dir.account("[email protected]")?;

// Order a new TLS certificate for a domain.
let mut ord_new = acc.new_order("mydomain.io", &[])?;

// If the ownership of the domain(s) have already been
// authorized in a previous order, you might be able to
// skip validation. The ACME API provider decides.
let ord_csr = loop {
    // are we done?
    if let Some(ord_csr) = ord_new.confirm_validations() {
        break ord_csr;
    }

    // Get the possible authorizations (for a single domain
    // this will only be one element).
    let auths = ord_new.authorizations()?;

    // For HTTP, the challenge is a text file that needs to
    // be placed in your web server's root:
    //
    // /var/www/.well-known/acme-challenge/<token>
    //
    // The important thing is that it's accessible over the
    // web for the domain(s) you are trying to get a
    // certificate for:
    //
    // http://mydomain.io/.well-known/acme-challenge/<token>
    let chall = auths[0].http_challenge();

    // The token is the filename.
    let token = chall.http_token();
    let path = format!(".well-known/acme-challenge/{}", token);

    // The proof is the contents of the file
    let proof = chall.http_proof();

    // Here you must do "something" to place
    // the file/contents in the correct place.
    // update_my_web_server(&path, &proof);

    // After the file is accessible from the web, the calls
    // this to tell the ACME API to start checking the
    // existence of the proof.
    //
    // The order at ACME will change status to either
    // confirm ownership of the domain, or fail due to the
    // not finding the proof. To see the change, we poll
    // the API with 5000 milliseconds wait between.
    chall.validate(5000)?;

    // Update the state against the ACME API.
    ord_new.refresh()?;
};

// Ownership is proven. Create a private key for
// the certificate. These are provided for convenience, you
// can provide your own keypair instead if you want.
let pkey_pri = create_p384_key();

// Submit the CSR. This causes the ACME provider to enter a
// state of "processing" that must be polled until the
// certificate is either issued or rejected. Again we poll
// for the status change.
let ord_cert =
    ord_csr.finalize_pkey(pkey_pri, 5000)?;

// Now download the certificate. Also stores the cert in
// the persistence.
let cert = ord_cert.download_and_save_cert()?;

Ok(())
}

域名所有权

大多数网站 TLS 证书都试图证明对它们签发的域的所有权/控制权。对于 ACME，这意味着证明您控制着响应该域名 HTTP 请求的 Web 服务器，或者响应域名名称查找的 DNS 服务器。

要使用此库，在流程中需要修改 Web 服务器或 DNS 服务器才能继续获取证书。

请参阅 http_challenge 和 dns_challenge。

多个域名

在创建新的订单时，可以提供多个 alt-names，这些名称也将成为证书的一部分。ACME API 要求您证明对这些域的所有权。请参阅 authorizations。

速率限制

ACME API 提供商 Let's Encrypt 使用 速率限制 来确保 API 不会被滥用。降低此库中某些轮询调用中的 delay_millis 可能很有吸引力，但请权衡这背后的实际风险，即访问被切断。

使用测试环境进行开发！

特别要注意在开发中使用 Let`s Encrypt 测试环境，那里的速率限制更为宽松。

请参阅 DirectoryUrl::LetsEncryptStaging。

实现细节

该库试图尽可能减少依赖项。目前这意味着使用同步 I/O 和阻塞调用。这并不排除将来有基于 futures 的版本。

本文档遵循ACME草案规范18编写，并且高度依赖于openssl库来生成JWK/JWT并签署API请求。

许可协议：MIT