instant-acme

The Order struct represents a stable identity for an ACME order (RFC 8555). You can create an order from an Account using Account::new_order().

Key workflows:

1. Retrieve Authorizations: Use order.authorizations() to get a stream of authorizations required to validate the identifiers in the order.
2. Complete Challenges: For each authorization, use AuthorizationHandle::challenge(type) to get a ChallengeHandle, then use that handle to complete the specific challenge (e.g., via set_ready() or key_authorization()).
3. Finalize Order: Once challenges are complete, use order.poll_ready(retry_policy) to wait for the order to become ready, then call order.finalize() (which generates a CSR and finalizes) or order.finalize_csr(der_bytes) if you have a custom CSR.
4. Retrieve Certificate: After the order is valid, use order.poll_certificate(retry_policy) to wait for and retrieve the PEM encoded certificate chain.

// Conceptual workflow
let mut order = account.new_order(identifiers).await?;

// 1. Handle Authorizations/Challenges
let mut auths = order.authorizations();
while let Some(Ok(auth_handle)) = auths.next().await {
    let mut challenge = auth_handle.challenge(ChallengeType::Http01)?;
    // ... setup challenge response ...
    challenge.set_ready().await?;
}

// 2. Wait for readiness and finalize
let retry_policy = RetryPolicy::new();
order.poll_ready(&retry_policy).await?;
let private_key_pem = order.finalize().await?;

// 3. Wait for certificate
let cert_pem = order.poll_certificate(&retry_policy).await?;

Use AccountBuilder to initialize an Account instance. There are several ways to instantiate an account:

1. Create a new account: Use .create() with NewAccount details and a directory URL.
2. Restore from credentials: Use .from_credentials() with previously serialized AccountCredentials.
3. Load from an existing private key: Use .from_key() to load an account associated with a specific key, or .create_from_key() to create a new account if one doesn't exist for that key.
4. Restore from individual parts: Use .from_parts() if you have the account ID, a PKCS#8 DER private key, and the directory URL separately.

// Create a new account
let (account, credentials) = builder
    .create(&new_account, directory_url, None)
    .await?;

// Restore an account from stored credentials
let account = builder
    .from_credentials(stored_credentials)
    .await?;

// Load an account using a specific private key
let (account, credentials) = builder
    .from_key(key_tuple, directory_url)
    .await?;

A ChallengeHandle is used to interact with a specific challenge within an authorization.

To complete a challenge:

1. Get Key Authorization: Use handle.key_authorization() to generate the required response value. Depending on the challenge type, use .dns_value() (for DNS-01), .as_str() (for HTTP-01), or .digest() (for TLS-ALPN-01).
2. Setup Infrastructure: Provision the response in your DNS or web server.
3. Notify Server: Call handle.set_ready().await to tell the ACME server that the challenge is ready for validation.

For the experimental device-attest-01 challenge, use handle.send_device_attestation(payload) instead.

// Example: HTTP-01 challenge
let mut challenge = auth_handle.challenge(ChallengeType::Http01)?;
let auth_value = challenge.key_authorization()?.as_str();

// [User logic: Place auth_value in .well-known/acme-challenge/...] 

challenge.set_ready().await?;