= 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 link:man:ranch_transport(3)[ranch_transport(3)].
== Types
=== opt()
[source,erlang]
----
opt() :: ranch_tcp:opt() | ssl_opt()
----
Listen options.
The TCP options are defined in link:man:ranch_tcp(3)[ranch_tcp(3)].
=== opts()
[source,erlang]
----
opts() :: [opt()]
----
List of listen options.
=== ssl_opt()
[source,erlang]
----
ssl_opt() = {alpn_preferred_protocols, [binary()]}
| {beast_mitigation, one_n_minus_one | zero_n | disabled}
| {cacertfile, file:filename()}
| {cacerts, [public_key:der_encoded()]}
| {cert, public_key:der_encoded()}
| {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, [atom()]}
| {fail_if_no_peer_cert, boolean()}
| {handshake, hello | full}
| {hibernate_after, timeout()}
| {honor_cipher_order, boolean()}
| {honor_ecc_order, boolean()}
| {key, ssl:key()}
| {keyfile, file:filename()}
| {log_alert, boolean()}
| {log_level, logger:level()}
| {max_handshake_size, integer()}
| {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()}
| {signature_algs, [{ssl:hash(), ssl:sign_algo()}]}
| {signature_algs_cert, [atom()]}
| {sni_fun, fun()}
| {sni_hosts, [{string(), ssl_opt()}]}
| {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.
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.
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.
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.
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.
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.
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-22.0.
== See also
link:man:ranch(7)[ranch(7)],
link:man:ranch_transport(3)[ranch_transport(3)],
link:man:ranch_tcp(3)[ranch_tcp(3)],
ssl(3)
