aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/ranch_ssl.asciidoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/manual/ranch_ssl.asciidoc')
-rw-r--r--doc/src/manual/ranch_ssl.asciidoc142
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.