TLS Hardening Guide

This guide describes how to harden Transport Layer Security (TLS) connections configured with the ssl application. It covers cryptographic algorithm selection, protocol version configuration, certificate verification, and revocation checking.

Erlang's TLS implementation provided by the ssl application strives to have secure defaults. That said, we will avoid changing defaults in non-major releases.

For embedded systems with constrained bandwidth, cipher suites using Advanced Encryption Standard (AES) with counter cipher block chaining message authentication code, that is AES-CCM-8 (8-byte authentication tag) can be configured and provides 64-bit integrity instead of 128-bit.

Cryptographic Algorithms

The available cryptographic algorithms depend on the version of OpenSSL cryptolib that Erlang/OTP is built and linked with.

When you configure algorithm options such as supported_groups, or signature_algs, the ssl application automatically removes any algorithms not supported by the underlying OpenSSL cryptolib. The exception is the ciphers option: user-supplied cipher suites are not automatically filtered against crypto support, this is due to the more complex composition of algorithms in cipher suites pre TLS-1.3. In this case use ssl:filter_cipher_suites/2 to remove suites that are not supported by linked OpenSSL cryptolib.

Algorithms selection

The TLS protocol typically specifies that the client's algorithm preference determines the algorithm selection. The server option honor_cipher_order overrides this for cipher suite selection in all TLS versions. For TLS-1.2 and legacy versions, honor_ecc_order does the same for ECC curve selection.

Signature Algorithms

The signature_algs option configures which signature algorithms are acceptable for TLS protocol messages. The signature_algs_cert, option separately configures acceptable algorithms for certificate chain signatures.

If signature_algs is specified but not signature_algs_cert the value of signature_algs will implicitly be used for signature_algs_cert; however if none of them are explicitly specified certificate signatures are verified against default signature_algs (with additional legacy SHA-1 algorithms — see note below).

Post Quantum Algorithms

Post-Quantum Cryptography (PQC) algorithms are designed to resist attacks from future cryptographically relevant quantum computers (CRQCs), which are expected to break algorithms such as RSA and ECC. PQC is only available in TLS-1.3.

PQC algorithms generally require more computation and network bandwidth than classical algorithms. Key sizes, signatures, and ciphertexts are larger.

For key exchange, several ML-KEM hybrid groups are supported. By default, only x25519mlkem768 is offered — a hybrid that combines classical X25519 with ML-KEM-768 to balance current security with future quantum resistance, as the newer algorithms are less battle-tested.

For authentication, the signature algorithms ML-DSA and SLH-DSA are supported. ML-DSA is preferred due to faster signing and smaller signatures. Using PQC signature algorithms requires appropriate PQC certificates and keys.

Privacy and Integrity

The protocol version TLS-1.3 is a major upgrade of the protocol over previous versions, and supporting both TLS-1.3 and TLS-1.2 will require a configuration including options from both.

TLS 1.3 significantly improves session handling over TLS 1.2 by reducing the handshake from two round-trips (2-RTT) to one (1-RTT). It mandates forward secrecy, encrypts more of the handshake, and introduces 0-RTT resumption for previously visited sites.

The protocol itself will prevent version downgrade when using TLS-1.3 and TLS-1.2, which are the default supported versions. All other TLS versions still configurable are legacy versions. Datagram transport layer security, DTLS-1.2 over User Datagram Protocol (UDP) can also be configured and has functionality similar to TLS-1.2 but will always be less reliable and may lose application data just like plain UDP communication. DTLS over other transports can possibly be achieved but not out of the box. DTLS-1.3 is currently not supported.

Cipher Suites

TLS-1.3 does not share any cipher suites with previous protocol versions. You will need to include at least one cipher suite for both TLS-1.3 and TLS-1.2 to be able to support both versions in the ciphers option.

TLS 1.3 uses only modern Authenticated Encryption with Associated Data (AEAD) cipher suites, so does the ssl application's TLS-1.2 default.

Session Key Renewal

Renegotiation options only apply to versions prior to TLS-1.3. TLS-1.3 replaces renegotiation with the key update mechanism, which only handles session key rotation and does not allow renegotiating cipher suites or certificates mid-connection.

A server can disable client-initiated renegotiation with the client_renegotiation option to avoid possible DoS-attacks.

By default, the server mitigates renegotiation abuse by enforcing a 12-second delay between client initiated renegotiations.

Key Exchange Groups

TLS-1.3 decouples key exchange algorithms from cipher suites. The key exchange algorithms are configured using the supported_groups option. In TLS-1.2 in addition to the cipher suites the options eccs, dh, dhfile, are available for configuring the key exchange.

TLS 1.3 removes static RSA, supporting only ephemeral Diffie-Hellman, which provides mandatory Perfect Forward Secrecy (PFS), so does the ssl application's TLS-1.2 default.

Pre-Shared Keys

In TLS-1.2, PSK is supported by PSK cipher suites, which generally lack forward secrecy unless combined with DHE or ECDHE key exchange. In TLS-1.3, PSK are most commonly used together with a key exchange algorithm, providing forward secrecy, although a PSK only option still exists.

Early Data

Early data (0-RTT) in TLS-1.3 is not forward secret and is vulnerable to replay attacks. The server option early_data is disabled by default.

See Early Data in TLS-1.3 for mitigation strategies and examples.

Authenticity

Certificate verification is essential for establishing trust in TLS connections. The ssl application provides several mechanisms for customizing and strengthening certificate validation.

Certificate and Keys

Use the certs_keys option to be able to configure more than one possible certificate for the client or server. The best one compatible with the peer will be chosen.

Verify Function

The verify_fun option lets you customize certificate path validation for both TLS clients and servers. Use it to add application-specific checks beyond the standard chain verification.

To summarize:

• Always use verify_peer on the client side (default since OTP 26)
• Avoid accepting {bad_cert, _} errors in verify_fun unless there is some edge-case workaround that you have confidence in excluding.
• When enabling client certification on the server, ensure fail_if_no_peer_cert is true (default since OTP 26).

Certificate Revocation Verification

Certificate revocation verification is important for security and needs to be performed. However it requires some application specific knowledge to set it up correctly, hence the option crl_check default to false. Use true to verify the entire certificate chain, or peer to verify only the peer certificate.

The built-in Certificate Revocation List (CRL) cache can be pre-populated via ssl_crl_cache:insert/1 or configured to fetch CRLs from HTTP distribution points in certificates. For custom CRL sources, implement the ssl_crl_cache_api behaviour.

The client can request Online Certificate Status Protocol (OCSP) stapling from the server with the stapling option (disabled by default). In TLS-1.2, only end-entity certificate stapling is supported as opposed to TLS-1.3. If the server does not provide a staple, the connection by default fails with {bad_cert, missing_ocsp_staple}.

A custom verify_fun can intercept this to implement fallback revocation checking (that is, direct CRL fetch).