diff options
Diffstat (limited to 'doc/src/manual/ranch_ssl.asciidoc')
| -rw-r--r-- | doc/src/manual/ranch_ssl.asciidoc | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/doc/src/manual/ranch_ssl.asciidoc b/doc/src/manual/ranch_ssl.asciidoc new file mode 100644 index 0000000..55accad --- /dev/null +++ b/doc/src/manual/ranch_ssl.asciidoc @@ -0,0 +1,142 @@ += 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()]} + | {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()]} + | {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()} + | {sni_fun, fun()} + | {sni_hosts, [{string(), ssl_opt()}]} + | {user_lookup_fun, {fun(), any()}} + | {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. +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. +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. +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 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. |