ExAcme (ExAcme v0.3.0)

View Source

ExAcme 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

Types

Client process holding directory cache and state

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

client()

@type client() :: client()

Client process holding directory cache and state

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

deactivate_account(account_key, client)

@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.

directory(client)

@spec directory(client()) :: map()

Retrieves the directory information from the client.

Parameters

  • client - The pid or name of the ExAcme client agent.

external_account_required?(client)

@spec external_account_required?(client()) :: boolean()

Checks if an external account is required.

Parameters

  • client - The pid or name of the ExAcme client agent.

fetch_account(url, account_key, client)

@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.

fetch_authorization(url, account_key, client)

@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.

fetch_certificates(url, account_key, client)

@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.

fetch_challenge(url, account_key, client)

@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.

fetch_order(url, account_key, client)

@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.

finalize_order(finalize_url, csr, account_key, client)

@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 the ExAcme.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.

generate_key(algorithm \\ "ES256")

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.

profiles(client)

@spec profiles(client()) :: [map()]

Retrieves the profiles from the ACME directory.

Parameters

  • client - The pid or name of the ExAcme client agent.

register_account(registration_builder, key, client, opts \\ [])

@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 - A ExAcme.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.

revoke_certificate(revocation_builder, account_key, client)

@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 - An ExAcme.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.

rotate_account_key(old_account_key, new_key, client)

@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.

start_challenge_validation(url, account_key, client)

@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.

start_link(options)

@spec start_link(Keyword.t()) :: client()

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.

submit_order(order_builder, account_key, client)

@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 - An ExAcme.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.

terms_of_service(client)

@spec terms_of_service(client()) :: String.t()

Retrieves the terms of service URL from the ACME directory information.

Parameters

  • client - The pid or name of the ExAcme client agent.