site_encrypt v0.3.0 SiteEncrypt.Acme.Client.API View Source

Low level API for interacting with an ACME CA server.

This module is a very incomplete implementation of the ACME client, as described in RFC8555. Internally, the module uses Mint.HTTP to communicate with the server. All functions will internally make a blocking HTTP request to the server. Therefore it's advised to invoke the functions of this module from within a separate process, powered by Task.

To use the client, you first need to create the session with new_session/3. Then you can interact with the server using the remaining functions of this module. The session doesn't hold any resources open, so you can safely use it from multiple processes.

Link to this section Summary

Functions

Obtains authorization challenges from the CA.

Returns the status and the token of the http-01 challenge.

Obtains the key identifier of the existing account.

Finalizes the given order.

Obtains the certificate and chain from a finalized order.

Creates the new account at the CA server.

Creates a new order on the CA server.

Creates a new session to the given CA.

Obtains the status of the given order.

Link to this section Types

Specs

challenge() :: %{
  :status => status(),
  :type => String.t(),
  :url => String.t(),
  optional(:token) => String.t()
}

Specs

directory() :: %{
  url: String.t(),
  key_change: String.t(),
  new_account: String.t(),
  new_nonce: String.t(),
  new_order: String.t(),
  revoke_cert: String.t()
}

Specs

error() :: Mint.Types.error() | HTTP.response()

Specs

order() :: %{
  :status => status(),
  :authorizations => [String.t()],
  :finalize => String.t(),
  :location => String.t(),
  optional(:certificate) => String.t()
}

Specs

session() :: %SiteEncrypt.Acme.Client.API.Session{
  account_key: JOSE.JWK.t(),
  directory: nil | directory(),
  http_opts: Keyword.t(),
  kid: nil | String.t(),
  nonce: nil | String.t()
}

Specs

session_opts() :: [{:verify_server_cert, boolean()}]

Specs

status() :: :invalid | :pending | :ready | :processing | :valid

Link to this section Functions

Link to this function

authorization(session, authorization)

View Source

Specs

authorization(session(), String.t()) :: {:ok, [challenge()], session()}

Obtains authorization challenges from the CA.

Link to this function

challenge(session, challenge)

View Source

Specs

challenge(session(), challenge()) ::
  {:ok, %{status: status(), token: String.t()}, session()} | {:error, error()}

Returns the status and the token of the http-01 challenge.

Specs

fetch_kid(session()) :: {:ok, session()} | {:error, error()}

Obtains the key identifier of the existing account.

You only need to invoke this function if the session is created using the key of the existing account.

Link to this function

finalize(session, order, csr)

View Source

Specs

finalize(session(), order(), binary()) ::
  {:ok, %{status: status()}, session()} | {:error, error()}

Finalizes the given order.

Link to this function

get_cert(session, order)

View Source

Specs

get_cert(session(), order()) ::
  {:ok, String.t(), String.t(), session()} | {:error, error()}

Obtains the certificate and chain from a finalized order.

Link to this function

new_account(session, emails)

View Source

Specs

new_account(session(), [String.t()]) :: {:ok, session()} | {:error, error()}

Creates the new account at the CA server.

Link to this function

new_order(session, domains)

View Source

Specs

new_order(session(), [String.t()]) ::
  {:ok, order(), session()} | {:error, error()}

Creates a new order on the CA server.

Link to this function

new_session(directory_url, account_key, http_opts \\ [])

View Source

Specs

new_session(String.t(), JOSE.JWK.t(), session_opts()) ::
  {:ok, session()} | {:error, error()}

Creates a new session to the given CA.

  • directory_url has to point to the GET directory resource, such as https://acme-v02.api.letsencrypt.org/directory or https://acme-staging-v02.api.letsencrypt.org/directory
  • account_key is the private key of the CA account. If you want to create the new account, you need to generate this key yourself, for example with

    JOSE.JWK.generate_key({:rsa, _key_size = 4096})

    Note that this will not create the account. You need to invoke new_account/2 to do that. It is your responsibility to safely store the private key somewhere.

    If you want to access the existing account, you should pass the same key used for the account creation. In this case you'll usually need to invoke fetch_kid/1 to fetch the key identifier from the CA server.

Note that this function will make an in-process GET HTTP request to the given directory URL.

Link to this function

order_status(session, order)

View Source

Specs

order_status(session(), order()) ::
  {:ok, order(), session()} | {:error, error()}

Obtains the status of the given order.