@spec get(String.t() | {String.t(), list()}, options :: Keyword.t()) ::
  {:ok, binary()} | {:not_modified, any()} | {:error, any()}

Securely download https content from a URL.

This function uses the built-in :httpc client but enables certificate verification which is not enabled by :httc by default.

See also https://erlef.github.io/security-wg/secure_coding_and_deployment_hardening/ssl

Arguments

• url is a binary URL or a {url, list_of_headers} tuple. If provided the headers are a list of {'header_name', 'header_value'} tuples. Note that the name and value are both charlists, not strings.

• options is a keyword list of options.

Options

• :verify_peer is a boolean value indicating if peer verification should be done for this request. The default is true in which case the default :ssl options follow the erlef guidelines noted above.

• :timeout is the number of milliseconds available for the request to complete. The default is "120000". This option may also be set with the CLDR_HTTP_TIMEOUT environment variable.

• :connection_timeout is the number of milliseconds available for the a connection to be estabklished to the remote host. The default is "60000". This option may also be set with the CLDR_HTTP_CONNECTION_TIMEOUT environment variable.

Returns

• {:ok, body} if the return is successful.

• {:not_modified, headers} if the request would result in returning the same results as one matching an etag.

• {:error, error} if the download is unsuccessful. An error will also be logged in these cases.

Unsafe HTTPS

If the environment variable CLDR_UNSAFE_HTTPS is set to anything other than FALSE, false, nil or NIL then no peer verification of certificates is performed. Setting this variable is not recommended but may be required is where peer verification for unidentified reasons. Please open an issue if this occurs.

Certificate stores

In order to keep dependencies to a minimum, get/1 attempts to locate an already installed certificate store. It will try to locate a store in the following order which is intended to satisfy most host systems. The certificate store is expected to be a path name on the host system.

# A certificate store configured by the
# developer
Application.get_env(:ex_cldr, :cacertfile)

# Populated if hex package `CAStore` is configured
CAStore.file_path()

# Populated if hex package `certfi` is configured
:certifi.cacertfile()

# Debian/Ubuntu/Gentoo etc.
"/etc/ssl/certs/ca-certificates.crt",

# Fedora/RHEL 6
"/etc/pki/tls/certs/ca-bundle.crt",

# OpenSUSE
"/etc/ssl/ca-bundle.pem",

# OpenELEC
"/etc/pki/tls/cacert.pem",

# CentOS/RHEL 7
"/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem",

# Open SSL on MacOS
"/usr/local/etc/openssl/cert.pem",

# MacOS & Alpine Linux
"/etc/ssl/cert.pem"

@spec get_with_headers(String.t() | {String.t(), list()}, options :: Keyword.t()) ::
  {:ok, list(), binary()} | {:not_modified, any()} | {:error, any()}

Securely download https content from a URL.

This function uses the built-in :httpc client but enables certificate verification which is not enabled by :httc by default.

See also https://erlef.github.io/security-wg/secure_coding_and_deployment_hardening/ssl

Arguments

• url is a binary URL or a {url, list_of_headers} tuple. If provided the headers are a list of {'header_name', 'header_value'} tuples. Note that the name and value are both charlists, not strings.

• options is a keyword list of options.

Options

• :verify_peer is a boolean value indicating if peer verification should be done for this request. The default is true in which case the default :ssl options follow the erlef guidelines noted above.

• :timeout is the number of milliseconds available for the request to complete. The default is "120000". This option may also be set with the CLDR_HTTP_TIMEOUT environment variable.

• :connection_timeout is the number of milliseconds available for the a connection to be estabklished to the remote host. The default is "60000". This option may also be set with the CLDR_HTTP_CONNECTION_TIMEOUT environment variable.

• :https_proxy is the URL of an https proxy to be used. The default is nil.

Returns

• {:ok, body, headers} if the return is successful.

• {:not_modified, headers} if the request would result in returning the same results as one matching an etag.

• {:error, error} if the download is unsuccessful. An error will also be logged in these cases.

Unsafe HTTPS

If the environment variable CLDR_UNSAFE_HTTPS is set to anything other than FALSE, false, nil or NIL then no peer verification of certificates is performed. Setting this variable is not recommended but may be required is where peer verification for unidentified reasons. Please open an issue if this occurs.

Https Proxy

Cldr.Http.get/2 will look for a proxy URL in the following locales in the order presented:

• options[:https_proxy]
• ex_cldr compile-time configuration under the key :ex_cldr[:https_proxy]
• The environment variable HTTPS_PROXY
• The environment variable https_proxy

Certificate stores

In order to keep dependencies to a minimum, get/1 attempts to locate an already installed certificate store. It will try to locate a store in the following order which is intended to satisfy most host systems. The certificate store is expected to be a path name on the host system.

# A certificate store configured by the
# developer
Application.get_env(:ex_cldr, :cacertfile)

# Populated if hex package `CAStore` is configured
CAStore.file_path()

# Populated if hex package `certfi` is configured
:certifi.cacertfile()

# Debian/Ubuntu/Gentoo etc.
"/etc/ssl/certs/ca-certificates.crt",

# Fedora/RHEL 6
"/etc/pki/tls/certs/ca-bundle.crt",

# OpenSUSE
"/etc/ssl/ca-bundle.pem",

# OpenELEC
"/etc/pki/tls/cacert.pem",

# CentOS/RHEL 7
"/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem",

# Open SSL on MacOS
"/usr/local/etc/openssl/cert.pem",

# MacOS & Alpine Linux
"/etc/ssl/cert.pem"