ranch_ssl(3)

Name

ranch_ssl - SSL transport

Description

The module ranch_ssl implements an SSL Ranch transport.

Exports

The module ranch_ssl implements the interface defined by ranch_transport(3).

Types

opt()

opt() :: ranch_tcp:opt() | ssl_opt()

Listen options.

The TCP options are defined in ranch_tcp(3).

opts()

opts() :: [opt()]

List of listen options.

ssl_opt()

ssl_opt() = {alpn_preferred_protocols, [binary()]}
          | {anti_replay, '10k' | '100k' | {integer(), integer(), integer()}}
          | {beast_mitigation, one_n_minus_one | zero_n | disabled}
          | {cacertfile, file:filename()}
          | {cacerts, [public_key:der_encoded()]}
          | {cert, public_key:der_encoded()}
          | {certs_keys, [#{cert => public_key:der_encoded(),
                            key => ssl:key(),
                            certfile => file:filename(),
                            keyfile => file:filename(),
                            key_pem_password => iodata() | fun(() -> iodata())}]}
          | {certfile, file:filename()}
          | {ciphers, ssl:ciphers()}
          | {client_renegotiation, boolean()}
          | {crl_cache, [any()]}
          | {crl_check, boolean() | peer | best_effort}
          | {depth, integer()}
          | {dh, binary()}
          | {dhfile, file:filename()}
          | {eccs, [ssl:named_curve()]}
          | {fail_if_no_peer_cert, boolean()}
          | {handshake, hello | full}
          | {hibernate_after, timeout()}
          | {honor_cipher_order, boolean()}
          | {honor_ecc_order, boolean()}
          | {key, ssl:key()}
          | {key_update_at, pos_integer()}
          | {keyfile, file:filename()}
          | {log_alert, boolean()}
          | {log_level, logger:level()}
          | {max_handshake_size, integer()}
          | {middlebox_comp_mode, boolean()}
          | {next_protocols_advertised, [binary()]}
          | {padding_check, boolean()}
          | {partial_chain, fun()}
          | {password, string()}
          | {protocol, tls | dtls}
          | {psk_identity, string()}
          | {reuse_session, fun()}
          | {reuse_sessions, boolean()}
          | {secure_renegotiate, boolean()}
          | {session_tickets, disabled | stateful | stateless}
          | {signature_algs, [{ssl:hash(), ssl:sign_algo()}]}
          | {signature_algs_cert, [ssl:sign_scheme()]}
          | {sni_fun, fun()}
          | {sni_hosts, [{string(), ssl_opt()}]}
          | {supported_groups, [ssl:group()]}
          | {user_lookup_fun, {fun(), any()}}
          | {verify, verify_none | verify_peer}
          | {verify_fun, {fun(), any()}}
          | {versions, [ssl:protocol_version()]}

SSL-specific listen options.

Specifying a certificate is mandatory, either through the cert or certfile option, or by configuring SNI. None of the other options are required.

The default value is given next to the option name:

alpn_preferred_protocols

Perform Application-Layer Protocol Negotiation with the given list of preferred protocols.

anti_replay

Configures the server's built-in anti replay feature based on Bloom filters.

beast_mitigation (one_n_minus_one)

Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software.

cacertfile

Path to PEM encoded trusted certificates file used to verify peer certificates.

cacerts

List of DER encoded trusted certificates.

cert

DER encoded user certificate.

certs_keys

A list of a certificate (or possible a certificate and its chain) and the associated key of the certificate, that may be used to authenticate the client or the server.

certfile

Path to the PEM encoded user certificate file. May also contain the private key.

ciphers

List of ciphers that clients are allowed to use.

client_renegotiation (true)

Whether to allow client-initiated renegotiation.

crl_cache ({ssl_crl_cache, {internal, []}})

Customize the module used to cache Certificate Revocation Lists.

crl_check (false)

Whether to perform CRL check on all certificates in the chain during validation.

depth (1)

Maximum of intermediate certificates allowed in the certification path.

dh

DER encoded Diffie-Hellman parameters.

dhfile

Path to the PEM encoded Diffie-Hellman parameters file.

eccs

List of named ECC curves.

fail_if_no_peer_cert (false)

Whether to refuse the connection if the client sends an empty certificate.

handshake (full)

If hello is specified for this option, the handshake is paused after receiving the client hello message. The handshake can then be resumed via handshake_continue/3, or cancelled via handshake_cancel/1.

This option cannot be given to ranch:handshake/1,2.

hibernate_after (undefined)

Time in ms after which SSL socket processes go into hibernation to reduce memory usage.

honor_cipher_order (false)

If true, use the server's preference for cipher selection. If false, use the client's preference.

honor_ecc_order (false)

If true, use the server's preference for ECC curve selection. If false, use the client's preference.

key

DER encoded user private key.

key_update_at

Configures the maximum amount of bytes that can be sent on a TLS 1.3 connection before an automatic key update is performed.

keyfile

Path to the PEM encoded private key file, if different from the certfile.

log_alert (true)

If false, error reports will not be displayed.

log_level

Specifies the log level for TLS/DTLS.

max_handshake_size (256*1024)

Used to limit the size of valid TLS handshake packets to avoid DoS attacks.

middlebox_comp_mode (true)

Configures the middlebox compatibility mode on a TLS 1.3 connection.

next_protocols_advertised

List of protocols to send to the client if it supports the Next Protocol extension.

padding_check

Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software.

partial_chain

Claim an intermediate CA in the chain as trusted.

password

Password to the private key file, if password protected.

protocol (tls)

Choose TLS or DTLS protocol for the transport layer security.

psk_identity

Provide the given PSK identity hint to the client during the handshake.

reuse_session

Custom policy to decide whether a session should be reused.

reuse_sessions (false)

Whether to allow session reuse.

secure_renegotiate (false)

Whether to reject renegotiation attempts that do not conform to RFC5746.

session_tickets

Configures the session ticket functionality.

signature_algs

The TLS signature algorithm extension may be used, from TLS 1.2, to negotiate which signature algorithm to use during the TLS handshake.

signature_algs_cert

List of signature schemes for the signature_algs_cert extension introduced in TLS 1.3, in order to make special requirements on signatures used in certificates.

sni_fun

Function called when the client requests a host using Server Name Indication. Returns options to apply.

sni_hosts

Options to apply for the host that matches what the client requested with Server Name Indication.

supported_groups([x25519, x448, secp256r1, secp384r1])

TLS 1.3 introduces the supported_groups extension that is used for negotiating the Diffie-Hellman parameters in a TLS 1.3 handshake. Both client and server can specify a list of parameters that they are willing to use.

user_lookup_fun

Function called to determine the shared secret when using PSK, or provide parameters when using SRP.

verify (verify_none)

Use verify_peer to request a certificate from the client.

verify_fun

Custom policy to decide whether a client certificate is valid.

versions

TLS protocol versions that will be supported.

Note that the client will not send a certificate unless the value for the verify option is set to verify_peer. This means that fail_if_no_peer_cert only applies when combined with the verify option. The verify_fun option allows greater control over the client certificate validation.

The options sni_fun and sni_hosts are mutually exclusive.

Changelog

  • 2.0: The ssl_opt() type was updated for OTP-23.0.

See also

ranch(7), ranch_transport(3), ranch_tcp(3), ssl(3)

Ranch 2.1 Function Reference

Navigation

Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.