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)