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()]}
          | {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.

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

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 from 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.

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 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.

See also

ranch(7), ranch_transport(3), ranch_tcp(3), ssl(3)