tls_certificate_check

tls_certificate_check is a library for Erlang/OTP and Elixir that tries to make it easier to establish more secure HTTPS connections in ordinary setups.

Other kinds of TLS/SSL connections may also benefit from it.

It blends a CA trust store with ssl_verify_fun to verify remote hostnames, as well as the boilerplate to validate misordered certificate chains.

The OTP-trusted CAs (typically provided by the OS) are used on OTP 25+ unless unavailable or opted-out¹, in which case tls_certificate_check falls back to a hardcoded Mozilla's CA certificate store, as extracted by curl. When on OTP 24 or older, the lib will initialize using only the latter.

The trusted authorities' certificates are loaded when the application starts and made available to the API through persistent_term². After that, they can be explicitly overridden through the API.

How to use

Erlang

1. Import as a dependency

rebar.config

{deps, [
    % [...]
    {tls_certificate_check, "~> 1.24"}
]}.

your_application.app.src

{applications, [
    kernel,
    stdlib,
    % [...]
    tls_certificate_check
]}

2. Make your connections safer

Host = "example.com",
Options = tls_certificate_check:options(Host),
ssl:connect(Host, 443, Options, 5000)

Elixir

1. Import as a dependency

mix.exs

  defp deps do
    [
      # [...]
      {:tls_certificate_check, "~> 1.24"}
    ]
  end

2. Make your connections safer

host = "example.com"
options = :tls_certificate_check.options(host)
host |> String.to_charlist() |> :ssl.connect(443, options, 5000)

Advanced Use

Overriding Trusted CAs

Erlang

Path = certifi:cacertfile(),
tls_certificate_check:override_trusted_authorities({file, Path})

Elixir

path = CAStore.file_path()
:tls_certificate_check.override_trusted_authorities({:file, path})

API Reference

The API reference can be found on HexDocs.

Tested setup

• Erlang/OTP 22 or newer
• rebar3

License

MIT License

Copyright (c) 2020-2024 Guilherme Andrade

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

Footnotes

1. the use of OTP-trusted CAs can be controlled through the use_otp_trusted_CAs boolean option within application env config. ↩

2. the persistent term key is derived from the CA store's own contents and existing keys are not erased until the app terminates gracefully - this minimizes the risk of an impactful global garbage collection. ↩