opt() :: ranch_tcp:opt() | ssl_opt()
ranch_ssl - SSL transport
The module ranch_ssl implements an SSL Ranch transport.
The module ranch_ssl implements the interface defined by ranch_transport(3).
opt() :: ranch_tcp:opt() | ssl_opt()
Listen options.
The TCP options are defined in ranch_tcp(3).
opts() :: [opt()]
List of listen options.
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:
Perform Application-Layer Protocol Negotiation with the given list of preferred protocols.
Configures the server's built-in anti replay feature based on Bloom filters.
Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software.
Path to PEM encoded trusted certificates file used to verify peer certificates.
List of DER encoded trusted certificates.
DER encoded user certificate.
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.
Path to the PEM encoded user certificate file. May also contain the private key.
List of ciphers that clients are allowed to use.
Whether to allow client-initiated renegotiation.
Customize the module used to cache Certificate Revocation Lists.
Whether to perform CRL check on all certificates in the chain during validation.
Maximum of intermediate certificates allowed in the certification path.
DER encoded Diffie-Hellman parameters.
Path to the PEM encoded Diffie-Hellman parameters file.
List of named ECC curves.
Whether to refuse the connection if the client sends an empty certificate.
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.
Time in ms after which SSL socket processes go into hibernation to reduce memory usage.
If true, use the server's preference for cipher selection. If false, use the client's preference.
If true, use the server's preference for ECC curve selection. If false, use the client's preference.
DER encoded user private key.
Configures the maximum amount of bytes that can be sent on a TLS 1.3 connection before an automatic key update is performed.
Path to the PEM encoded private key file, if different from the certfile.
If false, error reports will not be displayed.
Specifies the log level for TLS/DTLS.
Used to limit the size of valid TLS handshake packets to avoid DoS attacks.
Configures the middlebox compatibility mode on a TLS 1.3 connection.
List of protocols to send to the client if it supports the Next Protocol extension.
Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software.
Claim an intermediate CA in the chain as trusted.
Password to the private key file, if password protected.
Choose TLS or DTLS protocol for the transport layer security.
Provide the given PSK identity hint to the client during the handshake.
Custom policy to decide whether a session should be reused.
Whether to allow session reuse.
Whether to reject renegotiation attempts that do not conform to RFC5746.
Configures the session ticket functionality.
The TLS signature algorithm extension may be used, from TLS 1.2, to negotiate which signature algorithm to use during the TLS handshake.
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.
Function called when the client requests a host using Server Name Indication. Returns options to apply.
Options to apply for the host that matches what the client requested with Server Name Indication.
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.
Function called to determine the shared secret when using PSK, or provide parameters when using SRP.
Use verify_peer to request a certificate from the client.
Custom policy to decide whether a client certificate is valid.
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.
ssl_opt() type was updated for OTP-23.0.
ranch(7), ranch_transport(3), ranch_tcp(3), ssl(3)
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.