View Source SiteEncrypt.Acme.Client.API (site_encrypt v0.6.0)

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.

Summary

Types

challenge()

directory()

error()

order()

session()

session_opts()

status()

Functions

authorization(session, authorization)

Obtains authorization challenges from the CA.

challenge(session, challenge)

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

fetch_kid(session)

Obtains the key identifier of the existing account.

finalize(session, order, csr)

Finalizes the given order.

get_cert(session, order)

Obtains the certificate and chain from a finalized order.

new_account(session, emails)

Creates the new account at the CA server.

new_order(session, domains)

Creates a new order on the CA server.

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

Creates a new session to the given CA.

order_status(session, order)

Obtains the status of the given order.

Types

challenge()

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

directory()

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

error()

@type error() :: Mint.Types.error() | SiteEncrypt.HttpClient.response()

order()

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

session()

@type 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()
}

session_opts()

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

status()

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

Functions

authorization(session, authorization)

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

Obtains authorization challenges from the CA.

challenge(session, challenge)

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

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

fetch_kid(session)

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

finalize(session, order, csr)

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

Finalizes the given order.

get_cert(session, order)

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

Obtains the certificate and chain from a finalized order.

new_account(session, emails)

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

Creates the new account at the CA server.

new_order(session, domains)

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

Creates a new order on the CA server.

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

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

order_status(session, order)

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

Obtains the status of the given order.