ExAcme (ExAcme v0.3.0)
View SourceExAcme is an ACME protocol client for managing SSL certificates.
It provides functionalities to interact with the ACME server, including generating keys, sending ACME requests, and handling directory and nonce information.
Features
- Start and manage the ExAcme client agent.
- Fetch directory information and terms of service.
- Send signed ACME requests.
- Handle nonce refreshing automatically.
Use the client to interact with ACME endpoints.
Summary
Functions
Returns a specification to start this module under a supervisor.
Deactivates an existing ACME account.
Retrieves the directory information from the client.
Checks if an external account is required.
Fetches account information from the specified URL.
Fetches order authorization information from the specified URL.
Fetches certificate chain from the specified URL.
Fetches authorization challenge information from the specified URL.
Fetches order information from the specified URL.
Finalizes an order by sending a Certificate Signing Request (CSR) to the specified URL.
Generates a cryptographic key pair for use with ACME operations.
Retrieves the profiles from the ACME directory.
Registers a new account with the ACME server.
Revokes a previously issued certificate.
Rotates the account key for an ACME account.
Starts the validation process for a challenge by sending a request to the specified challenge URL.
Starts the ExAcme client agent with the given options.
Submits a new order to the ACME server.
Retrieves the terms of service URL from the ACME directory information.
Types
@type client() :: client()
Client process holding directory cache and state
Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
@spec deactivate_account(ExAcme.AccountKey.t(), client()) :: {:ok, ExAcme.Account.t()} | {:error, any()}
Deactivates an existing ACME account.
This function sends a request to the ACME server to change the status of an account to 'deactivated'. Once an account is deactivated, it cannot be used for any further operations and the change is irreversible.
Parameters
account_key
- The account key used for authentication, containing the Key ID (kid).client
- The pid or name of the ExAcme client agent.
Returns
{:ok, account}
- If the account is successfully deactivated, returns the updated account information.{:error, reason}
- If an error occurs during the deactivation process.
Retrieves the directory information from the client.
Parameters
client
- The pid or name of the ExAcme client agent.
Checks if an external account is required.
Parameters
client
- The pid or name of the ExAcme client agent.
@spec fetch_account(String.t(), ExAcme.AccountKey.t(), client()) :: {:ok, ExAcme.Account.t()} | {:error, any()}
Fetches account information from the specified URL.
Parameters
url
- The URL of the account to fetch.account_key
- The account key used for authentication.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, account}
- If the account is successfully fetched.{:error, reason}
- If an error occurs during the fetch operation.
@spec fetch_authorization(String.t(), ExAcme.AccountKey.t(), client()) :: {:ok, ExAcme.Authorization.t()} | {:error, any()}
Fetches order authorization information from the specified URL.
Parameters
url
- The URL of the authorization to fetch.account_key
- The account key used for authentication.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, authorization}
- If the authorization is successfully fetched.{:error, reason}
- If an error occurs during the fetch operation.
@spec fetch_certificates(String.t(), ExAcme.AccountKey.t(), client()) :: {:ok, [X509.Certificate.t()]} | {:error, any()}
Fetches certificate chain from the specified URL.
Parameters
url
- The URL of the certificate to fetch.account_key
- The account key used for authentication.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, certificate_chain}
- If the certificate chain is successfully fetched.{:error, reason}
- If an error occurs during the fetch operation.
@spec fetch_challenge(String.t(), ExAcme.AccountKey.t(), client()) :: {:ok, ExAcme.Challenge.t()} | {:error, any()}
Fetches authorization challenge information from the specified URL.
Parameters
url
- The URL of the challenge to fetch.account_key
- The account key used for authentication.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, challenge}
- If the challenge is successfully fetched.{:error, reason}
- If an error occurs during the fetch operation.
@spec fetch_order(String.t(), ExAcme.AccountKey.t(), client()) :: {:ok, ExAcme.Order.t()} | {:error, any()}
Fetches order information from the specified URL.
Parameters
url
- The URL of the order to fetch.account_key
- The account key used for authentication.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, order}
- If the order is successfully fetched.{:error, reason}
- If an error occurs during the fetch operation.
@spec finalize_order(String.t(), X509.CSR.t(), ExAcme.AccountKey.t(), client()) :: {:ok, ExAcme.Order.t()} | {:error, any()}
Finalizes an order by sending a Certificate Signing Request (CSR) to the specified URL.
Parameters
finalize_url
- The URL to finalize the order.csr
- The Certificate Signing Request (CSR) to send for finalization. You can generate a CSR using theExAcme.Order.to_csr/2
function.account_key
- The account key used for authentication.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, order}
- If the order is successfully finalized.{:error, reason}
- If an error occurs during the finalization process.
Generates a cryptographic key pair for use with ACME operations.
This function creates a new key pair for signing ACME requests. The default algorithm is ES256 (ECDSA using P-256 and SHA-256), which is widely supported by ACME providers.
Parameters
algorithm
- The algorithm to use for key generation. Default is "ES256".
Returns
JOSE.JWK
struct representing the generated key pair.
Retrieves the profiles from the ACME directory.
Parameters
client
- The pid or name of the ExAcme client agent.
@spec register_account( ExAcme.RegistrationBuilder.t() | map(), JOSE.JWK.t(), client(), keyword() ) :: {:ok, ExAcme.Account.t(), ExAcme.AccountKey.t()} | {:error, any()}
Registers a new account with the ACME server.
This function creates a new account on the ACME server using the provided registration information and JSON Web Key (JWK).
Parameters
registration_builder
- AExAcme.RegistrationBuilder
struct containing registration information or a map with details from section 7.3 of RFC 8555.key
- The JSON Web Key (JWK) to use for the account.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, account, account_key}
- If the registration is successful, returns the account information and the corresponding account key. An account key is the provided JSON Web Key (JWK) and the Key Identifier (kid) returned by the server.{:error, reason}
- If an error occurs during registration.
@spec revoke_certificate( ExAcme.RevocationBuilder.t() | map(), ExAcme.AccountKey.t(), client() ) :: :ok | {:error, any()}
Revokes a previously issued certificate.
This function sends a request to the ACME server to revoke the specified certificate. Once a certificate is revoked, it is no longer valid and cannot be reinstated.
Parameters
revocation_builder
- AnExAcme.RevocationBuilder
struct or a map containing revocation details such as the certificate data and optional reason code.account_key
- The account key used for authentication.client
- The pid or name of the ExAcme client agent.
Returns
:ok
- If the certificate is successfully revoked.{:error, reason}
- If an error occurs during the revocation process.
@spec rotate_account_key(ExAcme.AccountKey.t(), JOSE.JWK.t(), client()) :: {:ok, ExAcme.AccountKey.t()} | {:error, any()}
Rotates the account key for an ACME account.
This function replaces the current account key with a new one. The server will authorize the key change based on a request signed by both the old and new keys.
Parameters
old_account_key
- The current account key to be replaced.new_key
- The new JSON Web Key (JWK) to use for the account.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, account_key}
- If the key rotation is successful, returns the new account key, which is the provided JSON Web Key (JWK) and the Key ID (kid).{:error, reason}
- If an error occurs during key rotation.
@spec start_challenge_validation(String.t(), ExAcme.AccountKey.t(), client()) :: {:ok, ExAcme.Challenge.t()} | {:error, any()}
Starts the validation process for a challenge by sending a request to the specified challenge URL.
This function notifies the ACME server that the client is ready for the server to attempt validation of the challenge. The server will then verify that the requirements of the challenge have been fulfilled.
Parameters
url
- The URL of the challenge to validate.account_key
- The account key used for authentication.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, challenge}
- If the challenge validation request is successfully sent, returns the updated challenge information.{:error, reason}
- If an error occurs during the validation request.
Starts the ExAcme client agent with the given options.
Options
:directory_url
- The URL of the ACME directory. The value can be:lets_encrypt
or:lets_encrypt_staging
to use the Let's Encrypt production or staging directory URL or a custom directory URL.:finch
- The module name or pid of the Finch HTTP client to use.- Other options to pass to
Agent
like:name
.
@spec submit_order(ExAcme.OrderBuilder.t() | map(), ExAcme.AccountKey.t(), client()) :: {:ok, ExAcme.Order.t()} | {:error, any()}
Submits a new order to the ACME server.
This function creates a new certificate order using the provided order information.
It can accept either an ExAcme.OrderBuilder
struct or a map with order details from section 7.4
of RFC 8555.
Parameters
order_builder
- AnExAcme.OrderBuilder
struct or a map containing order details such as identifiers, not_before, and not_after.account_key
- The account key used for authentication.client
- The pid or name of the ExAcme client agent.
Returns
{:ok, order}
- If the order submission is successful, returns the order information.{:error, reason}
- If an error occurs during order submission.
Retrieves the terms of service URL from the ACME directory information.
Parameters
client
- The pid or name of the ExAcme client agent.