From 265bc740d0abcddee8e7eef2286980f2db3088b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 31 Jul 2018 15:19:16 +0200 Subject: Revisit the manual pages for the various modules --- doc/src/manual/ranch_ssl.asciidoc | 278 ++++++++++++++++++++++++++------------ 1 file changed, 193 insertions(+), 85 deletions(-) (limited to 'doc/src/manual/ranch_ssl.asciidoc') diff --git a/doc/src/manual/ranch_ssl.asciidoc b/doc/src/manual/ranch_ssl.asciidoc index b809ec1..3a4a146 100644 --- a/doc/src/manual/ranch_ssl.asciidoc +++ b/doc/src/manual/ranch_ssl.asciidoc @@ -2,153 +2,261 @@ == Name -ranch_ssl - SSL transport module +ranch_ssl - SSL transport == Description -The `ranch_ssl` module implements an SSL Ranch transport. +The module `ranch_ssl` implements an SSL Ranch transport. + +== Exports + +The module `ranch_ssl` implements the interface defined +by link:man:ranch_transport(3)[ranch_transport(3)]. == Types -=== ssl_opt() +=== 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()]}. +opt() :: ranch_tcp:opt() | ssl_opt() ---- -SSL-specific listen options. +Listen options. -=== opt() = ranch_tcp:opt() | ssl_opt() +The TCP options are defined in link:man:ranch_tcp(3)[ranch_tcp(3)]. -Listen options. +=== opts() -=== opts() = [opt()] +[source,erlang] +---- +opts() :: [opt()] +---- List of listen options. -== Option descriptions +=== 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. Specifying a certificate is mandatory, either through the `cert` -or the `certfile` option. None of the other options are required. +or `certfile` option, or by configuring SNI. None of the other +options are required. -The default value is given next to the option name. +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. + +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. + +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. + +Path to PEM encoded trusted certificates file used to verify +peer certificates. + cacerts:: - List of DER encoded trusted certificates. + +List of DER encoded trusted certificates. + cert:: - DER encoded user certificate. + +DER encoded user certificate. + certfile:: - Path to the PEM encoded user certificate file. May also contain the private key. + +Path to the PEM encoded user certificate file. May also +contain the private key. + ciphers:: - List of ciphers that clients are allowed to use. + +List of ciphers that clients are allowed to use. + client_renegotiation (true):: - Whether to allow client-initiated renegotiation. + +Whether to allow client-initiated renegotiation. + crl_cache ({ssl_crl_cache, {internal, []}}):: - Customize the module used to cache Certificate Revocation Lists. + +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. + +Whether to perform CRL check on all certificates in the chain +during validation. + depth (1):: - Maximum of intermediate certificates allowed in the certification path. + +Maximum of intermediate certificates allowed in the +certification path. + dh:: - DER encoded Diffie-Hellman parameters. + +DER encoded Diffie-Hellman parameters. + dhfile:: - Path to the PEM encoded Diffie-Hellman parameters file. + +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. + +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. + +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. + +If true, use the server's preference for cipher selection. +If false, use the client's preference. + key:: - DER encoded user private key. + +DER encoded user private key. + keyfile:: - Path to the PEM encoded private key file, if different than the certfile. + +Path to the PEM encoded private key file, if different from +the certfile. + log_alert (true):: - If false, error reports will not be displayed. + +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. + +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. + +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. + +Claim an intermediate CA in the chain as trusted. + password:: - Password to the private key file, if password protected. + +Password to the private key file, if password protected. + psk_identity:: - Provide the given PSK identity hint to the client during the handshake. + +Provide the given PSK identity hint to the client during the +handshake. + reuse_session:: - Custom policy to decide whether a session should be reused. + +Custom policy to decide whether a session should be reused. + reuse_sessions (false):: - Whether to allow session reuse. + +Whether to allow session reuse. + secure_renegotiate (false):: - Whether to reject renegotiation attempts that do not conform to RFC5746. + +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. + +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. + +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. + +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. + +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. + +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. + +Use `verify_peer` to request a certificate from the client. + verify_fun:: - Custom policy to decide whether a client certificate is valid. + +Custom policy to decide whether a client certificate is valid. + versions:: - TLS protocol versions that will be supported. + +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 +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. -== Exports +== See also -None. +link:man:ranch(7)[ranch(7)], +link:man:ranch_transport(3)[ranch_transport(3)], +link:man:ranch_tcp(3)[ranch_tcp(3)], +ssl(3) -- cgit v1.2.3