ranch_ssl(3)

NAME

ranch_ssl - SSL transport module

DESCRIPTION

The ranch_ssl module implements an SSL Ranch transport.

TYPES

  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.

  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.