View Source Cldr.Http (cldr_utils v2.27.0)
Supports securely downloading https content.
Summary
Functions
@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 istrue
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 theCLDR_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 theCLDR_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 istrue
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 theCLDR_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 theCLDR_HTTP_CONNECTION_TIMEOUT
environment variable.:https_proxy
is the URL of an https proxy to be used. The default isnil
.
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"