diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/ranch_ssl.md | 80 | ||||
| -rw-r--r-- | manual/ranch_tcp.md | 65 |
2 files changed, 108 insertions, 37 deletions
diff --git a/manual/ranch_ssl.md b/manual/ranch_ssl.md index e8a41ec..13790d6 100644 --- a/manual/ranch_ssl.md +++ b/manual/ranch_ssl.md @@ -6,43 +6,47 @@ The `ranch_ssl` module implements an SSL Ranch transport. Types ----- -### opt() = {backlog, non_neg_integer()} +### ssl_opt() = {alpn_preferred_protocols, [binary()]} | {cacertfile, string()} - | {cacerts, [Der::binary()]} - | {cert, Der::binary()} + | {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()} - | {ip, inet:ip_address()} - | {key, Der::binary()} + | {key, {'RSAPrivateKey' | 'DSAPrivateKey' | 'PrivateKeyInfo', public_key:der_encoded()}} | {keyfile, string()} - | {linger, {boolean(), non_neg_integer()}} | {log_alert, boolean()} | {next_protocols_advertised, [binary()]} - | {nodelay, boolean()} + | {partial_chain, fun(([public_key:der_encoded()]) -> {trusted_ca, public_key:der_encoded()} | unknown_ca)} | {password, string()} - | {port, inet:port_number()} - | {raw, non_neg_integer(), non_neg_integer(), non_neg_integer() | binary()} + | {psk_identity, string()} | {reuse_session, fun()} | {reuse_sessions, boolean()} | {secure_renegotiate, boolean()} - | {send_timeout, timeout()} - | {send_timeout_close, boolean()} + | {sni_fun, fun()} + | {sni_hosts, [{string(), ssl_opt()}]} + | {user_lookup_fun, {fun(), any()}} | {verify, ssl:verify_type()} - | {verify_fun, {fun(), InitialUserState::term()}}, - | {versions, [atom()]} + | {verify_fun, {fun(), any()}} + | {versions, [atom()]}. + +> SSL-specific listen options. + +### opt() = ranch_tcp:opt() | ssl_opt() > Listen options. -> -> This does not represent the entirety of the options that can -> be set on the socket, but only the options that should be -> set independently of protocol implementation. ### opts() = [opt()] -> Listen options. +> List of listen options. Option descriptions ------------------- @@ -52,8 +56,8 @@ or the `certfile` option. None of the other options are required. The default value is given next to the option name. - - backlog (1024) - - Max length of the queue of pending connections. + - 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 @@ -64,40 +68,52 @@ The default value is given next to the option name. - 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 (the default), use the client's preference. - - ip - - Interface to listen on. Listen on all interfaces by default. + - 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. - - linger ({false, 0}) - - Whether to wait and how long to flush data sent before closing the socket. - 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. - - port (0) - - TCP port number to listen on. 0 means a random port will be used. + - 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. - - send_timeout (30000) - - How long the send call may wait for confirmation before returning. - - send_timeout_close (true) - - Whether to close the socket when the confirmation wasn't received. + - 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 @@ -111,7 +127,7 @@ 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 `raw` option is unsupported. +The options `sni_fun` and `sni_hosts` are mutually exclusive. Exports ------- diff --git a/manual/ranch_tcp.md b/manual/ranch_tcp.md index 2967392..c274b0b 100644 --- a/manual/ranch_tcp.md +++ b/manual/ranch_tcp.md @@ -12,47 +12,102 @@ Types ----- ### opt() = {backlog, non_neg_integer()} + | {buffer, non_neg_integer()} + | {delay_send, boolean()} + | {dontroute, boolean()} + | {exit_on_close, boolean()} + | {fd, non_neg_integer()} + | {high_msgq_watermark, non_neg_integer()} + | {high_watermark, non_neg_integer()} + | inet + | inet6 | {ip, inet:ip_address()} + | {keepalive, boolean()} | {linger, {boolean(), non_neg_integer()}} + | {low_msgq_watermark, non_neg_integer()} + | {low_watermark, non_neg_integer()} | {nodelay, boolean()} | {port, inet:port_number()} - | {raw, non_neg_integer(), non_neg_integer(), non_neg_integer() | binary()} + | {priority, integer()} + | {raw, non_neg_integer(), non_neg_integer(), binary()} + | {recbuf, non_neg_integer()} | {send_timeout, timeout()} | {send_timeout_close, boolean()} + | {sndbuf, non_neg_integer()} + | {tos, integer()} > Listen options. > > This does not represent the entirety of the options that can -> be set on the socket, but only the options that should be +> be set on the socket, but only the options that may be > set independently of protocol implementation. ### opts() = [opt()] -> Listen options. +> List of listen options. Option descriptions ------------------- None of the options are required. -The default value is given next to the option name. +Please consult the `gen_tcp` and `inet` manuals for a more +thorough description of these options. This manual only aims +to provide a short description along with what the defaults +are. Defaults may be different in Ranch compared to `gen_tcp`. +Defaults are given next to the option name. - backlog (1024) - Max length of the queue of pending connections. + - buffer + - Size of the buffer used by the Erlang driver. Default is system-dependent. + - delay_send (false) + - Always queue packets before sending, to send fewer, larger packets over the network. + - dontroute (false) + - Don't send via a gateway, only send to directly connected hosts. + - exit_on_close (true) + - Disable to allow sending data after a close has been detected. + - fd + - File descriptor of the socket, if it was opened externally. + - high_msgq_watermark (8192) + - Limit in the amount of data in the socket message queue before the socket queue becomes busy. + - high_watermark (8192) + - Limit in the amount of data in the ERTS socket implementation's queue before the socket becomes busy. + - inet + - Set up the socket for IPv4. + - inet6 + - Set up the socket for IPv6. - ip - Interface to listen on. Listen on all interfaces by default. + - keepalive (false) + - Enable sending of keep-alive messages. - linger ({false, 0}) - Whether to wait and how long to flush data sent before closing the socket. + - low_msgq_watermark (4096) + - Amount of data in the socket message queue before the socket queue leaves busy state. + - low_watermark (4096) + - Amount of data in the ERTS socket implementation's queue before the socket leaves busy state. - nodelay (true) - Whether to enable TCP_NODELAY. - port (0) - TCP port number to listen on. 0 means a random port will be used. + - priority (0) + - Priority value for all packets to be sent by this socket. + - recbuf + - Minimum size of the socket's receive buffer. Default is system-dependent. - send_timeout (30000) - How long the send call may wait for confirmation before returning. - send_timeout_close (true) - Whether to close the socket when the confirmation wasn't received. + - sndbuf + - Minimum size of the socket's send buffer. Default is system-dependent. + - tos + - Value for the IP_TOS IP level option. Use with caution. -The `raw` option is unsupported. +In addition, the `raw` option can be used to set system-specific +options by specifying the protocol level, the option number and +the actual option value specified as a binary. This option is not +portable. Use with caution. Exports ------- |