path: root/doc/src/manual/ranch_ssl.asciidoc

= 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)