Crate acme2

acme2

A Tokio and OpenSSL based ACMEv2 client.

Features:

• ACME v2 support, tested against Let’s Encrypt and Pebble
• Fully async, using reqwest / Tokio
• Support for DNS01 and HTTP01 validation
• Fully instrumented with tracing

Example

This example demonstrates how to provision a certificate for the domain example.com using http-01 validation.

use acme2::gen_rsa_private_key;
use acme2::AccountBuilder;
use acme2::AuthorizationStatus;
use acme2::ChallengeStatus;
use acme2::DirectoryBuilder;
use acme2::OrderBuilder;
use acme2::OrderStatus;
use acme2::Csr;
use acme2::Error;
use std::time::Duration;

const LETS_ENCRYPT_URL: &'static str =
  "https://acme-v02.api.letsencrypt.org/directory";

#[tokio::main]
async fn main() -> Result<(), Error> {
  // Create a new ACMEv2 directory for Let's Encrypt.
  let dir = DirectoryBuilder::new(LETS_ENCRYPT_URL.to_string())
    .build()
    .await?;

  // Create an ACME account to use for the order. For production
  // purposes, you should keep the account (and private key), so
  // you can renew your certificate easily.
  let mut builder = AccountBuilder::new(dir.clone());
  builder.contact(vec!["mailto:hello@lcas.dev".to_string()]);
  builder.terms_of_service_agreed(true);
  let account = builder.build().await?;

  // Create a new order for a specific domain name.
  let mut builder = OrderBuilder::new(account);
  builder.add_dns_identifier("example.com".to_string());
  let order = builder.build().await?;

  // Get the list of needed authorizations for this order.
  let authorizations = order.authorizations().await?;
  for auth in authorizations {
    // Get an http-01 challenge for this authorization (or panic
    // if it doesn't exist).
    let challenge = auth.get_challenge("http-01").unwrap();

    // At this point in time, you must configure your webserver to serve
    // a file at `https://example.com/.well-known/${challenge.token}`
    // with the content of `challenge.key_authorization()??`.

    // Start the validation of the challenge.
    let challenge = challenge.validate().await?;

    // Poll the challenge every 5 seconds until it is in either the
    // `valid` or `invalid` state.
    let challenge = challenge.wait_done(Duration::from_secs(5), 3).await?;

    assert_eq!(challenge.status, ChallengeStatus::Valid);

    // You can now remove the challenge file hosted on your webserver.

    // Poll the authorization every 5 seconds until it is in either the
    // `valid` or `invalid` state.
    let authorization = auth.wait_done(Duration::from_secs(5), 3).await?;
    assert_eq!(authorization.status, AuthorizationStatus::Valid)
  }

  // Poll the order every 5 seconds until it is in either the
  // `ready` or `invalid` state. Ready means that it is now ready
  // for finalization (certificate creation).
  let order = order.wait_ready(Duration::from_secs(5), 3).await?;

  assert_eq!(order.status, OrderStatus::Ready);

  // Generate an RSA private key for the certificate.
  let pkey = gen_rsa_private_key(4096)?;

  // Create a certificate signing request for the order, and request
  // the certificate.
  let order = order.finalize(Csr::Automatic(pkey)).await?;

  // Poll the order every 5 seconds until it is in either the
  // `valid` or `invalid` state. Valid means that the certificate
  // has been provisioned, and is now ready for download.
  let order = order.wait_done(Duration::from_secs(5), 3).await?;

  assert_eq!(order.status, OrderStatus::Valid);

  // Download the certificate, and panic if it doesn't exist.
  let cert = order.certificate().await?.unwrap();
  assert!(cert.len() > 1);

  Ok(())
}

Re-exports

pub use openssl;

Structs

Account

An ACME account. This is used to identify a subscriber to an ACME server.

AccountBuilder

An builder that is used to create / retrieve an Account from the ACME server.

Authorization

An autorization represents the server’s authorization of a certain domain being represented by an account.

Challenge

A challenge represents a means for the server to validate that an account has control over an identifier (domain).

Directory

A directory is the resource representing how to reach an ACME server.

DirectoryBuilder

An builder that is used create a Directory.

DirectoryMeta

This is some metadata about a directory.

Identifier

This is a identifier for a resource that the ACME server can provision certificates for (a domain).

Order

An order represents a subscribers’s request for a certificate from the ACME server, and is used to track the progress of that order through to issuance.

OrderBuilder

A builder used to create a new Order.

ServerError

This is an error as returned by the ACME server.

TransportError

Enums

AccountStatus

The status of an Account.

AuthorizationStatus

The status of this authorization.

ChallengeStatus

The status of this challenge.

Csr

A certificate signing request.

Error

OrderStatus

The status of this order.

Functions

gen_ec_p256_private_key

Generate a new P256 EC private key using the system random.

gen_rsa_private_key

Generate a new RSA private key using the specified size, using the system random.