= ranch_ssl(3)

== Name

ranch_ssl - SSL transport module

== Description

The `ranch_ssl` module implements an SSL Ranch transport.

== Types

=== ssl_opt()

[source,erlang]
----
ssl_opt() = {alpn_preferred_protocols, [binary()]}
	| {beast_mitigation, one_n_minus_one | zero_n | disabled}
	| {cacertfile, string()}
	| {cacerts, [public_key:der_encoded()]}
	| {cert, public_key:der_encoded()}
	| {certfile, string()}
	| {ciphers, [ssl:erl_cipher_suite()] | string()}
	| {client_renegotiation, boolean()}
	| {crl_cache, {module(), {internal | any(), list()}}}
	| {crl_check, boolean() | peer | best_effort}
	| {depth, 0..255}
	| {dh, public_key:der_encoded()}
	| {dhfile, string()}
	| {fail_if_no_peer_cert, boolean()}
	| {hibernate_after, integer() | undefined}
	| {honor_cipher_order, boolean()}
	| {key, {'RSAPrivateKey' | 'DSAPrivateKey' | 'PrivateKeyInfo', public_key:der_encoded()}}
	| {keyfile, string()}
	| {log_alert, boolean()}
	| {next_protocols_advertised, [binary()]}
	| {padding_check, boolean()}
	| {partial_chain, fun(([public_key:der_encoded()]) -> {trusted_ca, public_key:der_encoded()} | unknown_ca)}
	| {password, string()}
	| {psk_identity, string()}
	| {reuse_session, fun()}
	| {reuse_sessions, boolean()}
	| {secure_renegotiate, boolean()}
	| {signature_algs, [{atom(), atom()}]}
	| {sni_fun, fun()}
	| {sni_hosts, [{string(), ssl_opt()}]}
	| {user_lookup_fun, {fun(), any()}}
	| {v2_hello_compatible, boolean()}
	| {verify, ssl:verify_type()}
	| {verify_fun, {fun(), any()}}
	| {versions, [atom()]}.
----

SSL-specific listen options.

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

Listen options.

=== opts() = [opt()]

List of listen options.

== Option descriptions

Specifying a certificate is mandatory, either through the `cert`
or the `certfile` option. 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::
	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.
fail_if_no_peer_cert (false)::
	Whether to refuse the connection if the client sends an empty certificate.
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.
key::
	DER encoded user private key.
keyfile::
	Path to the PEM encoded private key file, if different than the certfile.
log_alert (true)::
	If false, error reports will not be displayed.
next_protocols_advertised::
	List of protocols to send to the client if it supports the Next Protocol extension.
nodelay (true)::
	Whether to enable TCP_NODELAY.
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.
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.
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.
v2_hello_compatible::
	Accept clients that send hello messages in SSL-2.0 format while offering supported SSL/TLS versions.
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 the `fail_if_no_peer_cert` only apply 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.

== Exports

None.
