Dowser.Client.HTTP.SSL (Dowser.Client v0.3.0)

View Source

Builds the :ssl options Dowser.Client.HTTP hands to :httpc for an https:// URL.

Secure by default: the chain is verified against the OS trust store (:public_key.cacerts_get/0), the certificate's identity is checked against the URL's host, SNI is sent, and TLS is restricted to 1.2+.

Options

http_opts[:ssl] is a keyword list. The keys below are interpreted here; every other key is passed through to :ssl verbatim (so ssl: [reuse_sessions: false] works), and overrides the computed value for that key.

  • :verify — true (default) for :verify_peer, false for :verify_none. The :ssl atoms :verify_peer/:verify_none are also accepted.
  • :insecure — true is shorthand for verify: false: no chain and no hostname verification at all. For a localhost cluster with a self-signed certificate, or a dev box you own.
  • :verify_hostname — true (default) checks the certificate identity against the URL host. false keeps full chain verification but accepts any name in the certificate — the option for an SSH tunnel or a port-forward, where the host you connect to is never the host the certificate was issued for.
  • :cacerts / :cacertfile — an explicit trust store, replacing the OS one. :cacertfile accepts a string path.
  • :sni — the server name to send. :auto (default) sends the URL host, except for an IP address, where SNI is disabled (an IP is not a legal SNI value). :disable never sends it; a string sends that name.
  • :versions — TLS versions; defaults to [:"tlsv1.2", :"tlsv1.3"].
  • :depth — maximum intermediate certificates; defaults to 3.

Examples

# localhost with a self-signed certificate
ssl: [insecure: true]

# SSH tunnel: real CA, but the hostname will never match
ssl: [verify_hostname: false]

# a private CA
ssl: [cacertfile: "/etc/ssl/certs/internal-ca.pem"]

Summary

Types

opts()

Functions

options(url, ssl_opts \\ [])

Returns {:ok, ssl_options} for an https:// URL, {:ok, nil} for any other scheme (:httpc ignores :ssl there), or {:error, reason} when the options cannot be built — e.g. no trust store is available and none was given.

Types

opts()

@type opts() :: keyword()

Functions

options(url, ssl_opts \\ [])

@spec options(String.t(), opts()) :: {:ok, keyword() | nil} | {:error, term()}

Returns {:ok, ssl_options} for an https:// URL, {:ok, nil} for any other scheme (:httpc ignores :ssl there), or {:error, reason} when the options cannot be built — e.g. no trust store is available and none was given.