site_encrypt v0.3.0 SiteEncrypt behaviour View Source

Functions for interacting with sites managed by SiteEncrypt.

Link to this section Summary

Types

Uniquely identifies the site certified via site_encrypt.

Functions

Invoke this macro from certification/0 to return the fully shaped configuration.

Generates a new throwaway certificate for the given site.

Unconditionally obtains the new certificate for the site.

Returns the paths to the certificates and the key for the given site.

Sets the new site certificate.

Callbacks

Invoked during startup to obtain certification info.

Invoked after the new certificate has been obtained.

Link to this section Types

Link to this opaque

certification()

View Source (opaque)

Specs

certification()

Specs

id() :: any()

Uniquely identifies the site certified via site_encrypt.

The actual value is determined by the adapter used to start the site. For example, if SiteEncrypt.Phoenix is used, the site id is the endpoint module.

Specs

pems() :: %{privkey: String.t(), cert: String.t(), chain: String.t()}

Link to this section Functions

Link to this macro

configure(opts)

View Source (macro)

Invoke this macro from certification/0 to return the fully shaped configuration.

The minimal implementation of certification/0 looks as follows:

@impl SiteEncrypt
def certification do
  SiteEncrypt.configure(
    client: :native,
    domains: ["mysite.com", "www.mysite.com"],
    emails: ["contact@abc.org", "another_contact@abc.org"],
    db_folder: Application.app_dir(:phoenix_demo, Path.join(~w/priv site_encrypt/))

    # set OS env var MODE to "staging" or "production" on staging/production hosts
    directory_url:
      case System.get_env("MODE", "local") do
        "local" -> {:internal, port: 4002}
        "staging" -> "https://acme-staging-v02.api.letsencrypt.org/directory"
        "production" -> "https://acme-v02.api.letsencrypt.org/directory"
      end
  )
end

Options

  • :client - Required. Can be either :native or :certbot.

    The native client requires no extra OS-level dependencies, and it runs faster, which is especially useful in a local development and tests. However, this client is very immature, possibly buggy, and incomplete.

    The certbot client is a wrapper around the certbot tool, which has to be installed on the host machine. This client is much more reliable than the native client, but it is also significantly slower.

    As a compromise between these two choices, you can consider running certbot client in production and during CI tests, while using the native client for local development and local tests.

  • :domains - Required. The list of domains for which the certificate will be obtained. Must contain at least one element.

  • :emails - Required. The list of email addresses which will be passed to the CA when creating the new account.

  • :db_folder - Required. The folder where site_encrypt stores its data, such as certificates and account keys.

  • :directory_url - Required. The URL to CA directory resource. It can be either a string (e.g. "https://acme-v02.api.letsencrypt.org/directory") or a tuple in the shape of {:internal, port: local_acme_server_port}. In the latter case, an internal ACME server will be started at the given port. This is useful for local development and testing.

  • :backup - Path to the backup file. If this option is provided, site_encrypt will backup the entire content of the :db_folder to the given path after every successful certification. When the system is being started, if the backup file exists while the :db_folder is empty, the system will perform a restore. The generated file will be a zipped tarball. If this option is not provided no backup will be generated.

  • :days_to_renew - A positive integer which determines the next renewal attempt. For example, if this value is 30, the certificate will be renewed if it expires in 30 days or less. The default value is 30.

  • :log_level - Logger level for info messages. The default value is :info.

  • :key_size - The size used for generating private keys. The default value is 4096.

  • :mode - When set to :auto, the certificate will be automatically created or renewed when needed.

When set to :manual, you need to start the certification manually, using functions such as SiteEncrypt.force_certify/1 or SiteEncrypt.dry_certify/2. This can be useful for the first deploy, where you want to manually test the certification. In :test mix environment the mode is always :manual. The default value is :auto.

Link to this function

dry_certify(id, opts \\ [])

View Source

Specs

dry_certify(id(), [{:directory_url, String.t()}]) :: {:ok, pems()} | :error

Generates a new throwaway certificate for the given site.

This function will perform the full certification at the given CA server. The new certificate won't be used by the site, nor stored on disk. This is mostly useful to test the certification through the staging CA server from the production server, which can be done as follows:

SiteEncrypt.dry_certify(
  MySystemWeb.Endpoint,
  directory_url: "https://acme-staging-v02.api.letsencrypt.org/directory"
)

If for some reasons you want to apply the certificate to the site, you can pass the returned pems to set_certificate/2.

Specs

force_certify(id()) :: :ok | :error

Unconditionally obtains the new certificate for the site.

Be very careful when invoking this function in production, because you might trip some rate limit at the CA server (see here for Let's Encrypt limits).

Specs

https_keys(id()) :: [
  keyfile: Path.t(),
  certfile: Path.t(),
  cacertfile: Path.t()
]

Returns the paths to the certificates and the key for the given site.

Link to this function

set_certificate(id, pems)

View Source

Specs

set_certificate(id(), pems()) :: :ok

Sets the new site certificate.

This operation doesn't persist the certificate in the client storage. As a result, if the client previously obtained and stored a valid certificate, that certificate will be used after the endpoint is restarted.

Link to this section Callbacks

Specs

certification() :: certification()

Invoked during startup to obtain certification info.

See configure/1 for details.

Specs

handle_new_cert() :: any()

Invoked after the new certificate has been obtained.