diff options
| -rw-r--r-- | manual/ranch_ssl.md | 80 | ||||
| -rw-r--r-- | manual/ranch_tcp.md | 65 | ||||
| -rw-r--r-- | src/ranch.erl | 6 | ||||
| -rw-r--r-- | src/ranch_ssl.erl | 61 | ||||
| -rw-r--r-- | src/ranch_tcp.erl | 45 |
5 files changed, 183 insertions, 74 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 ------- diff --git a/src/ranch.erl b/src/ranch.erl index fc9bad3..3fbb9a2 100644 --- a/src/ranch.erl +++ b/src/ranch.erl @@ -131,11 +131,17 @@ filter_options(UserOptions, AllowedKeys, DefaultOptions) -> AllowedOptions = filter_user_options(UserOptions, AllowedKeys), lists:foldl(fun merge_options/2, DefaultOptions, AllowedOptions). +%% 2-tuple options. filter_user_options([Opt = {Key, _}|Tail], AllowedKeys) -> case lists:member(Key, AllowedKeys) of true -> [Opt|filter_user_options(Tail, AllowedKeys)]; false -> filter_user_options(Tail, AllowedKeys) end; +%% Special option forms. +filter_user_options([inet|Tail], AllowedKeys) -> + [inet|filter_user_options(Tail, AllowedKeys)]; +filter_user_options([inet6|Tail], AllowedKeys) -> + [inet6|filter_user_options(Tail, AllowedKeys)]; filter_user_options([Opt = {raw, _, _, _}|Tail], AllowedKeys) -> case lists:member(raw, AllowedKeys) of true -> [Opt|filter_user_options(Tail, AllowedKeys)]; diff --git a/src/ranch_ssl.erl b/src/ranch_ssl.erl index acfe38d..305fbb8 100644 --- a/src/ranch_ssl.erl +++ b/src/ranch_ssl.erl @@ -19,6 +19,7 @@ -export([secure/0]). -export([messages/0]). -export([listen/1]). +-export([listen_options/0]). -export([accept/2]). -export([accept_ack/2]). -export([connect/3]). @@ -35,36 +36,40 @@ -export([shutdown/2]). -export([close/1]). --type opt() :: {backlog, non_neg_integer()} +-type 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(([Der::binary()]) -> - {trusted_ca, Der::binary()} | unknown_ca)} + | {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()}} + | {verify_fun, {fun(), any()}} | {versions, [atom()]}. +-export_type([ssl_opt/0]). + +-type opt() :: ranch_tcp:opt() | ssl_opt(). -export_type([opt/0]). -type opts() :: [opt()]. @@ -84,24 +89,26 @@ listen(Opts) -> true = lists:keymember(cert, 1, Opts) orelse lists:keymember(certfile, 1, Opts), Opts2 = ranch:set_option_default(Opts, backlog, 1024), - Opts3 = ranch:set_option_default(Opts2, send_timeout, 30000), - Opts4 = ranch:set_option_default(Opts3, send_timeout_close, true), - Opts5 = ranch:set_option_default(Opts4, ciphers, unbroken_cipher_suites()), + Opts3 = ranch:set_option_default(Opts2, ciphers, unbroken_cipher_suites()), + Opts4 = ranch:set_option_default(Opts3, nodelay, true), + Opts5 = ranch:set_option_default(Opts4, send_timeout, 30000), + Opts6 = ranch:set_option_default(Opts5, send_timeout_close, true), %% We set the port to 0 because it is given in the Opts directly. %% The port in the options takes precedence over the one in the %% first argument. - ssl:listen(0, ranch:filter_options(Opts5, - [backlog, cacertfile, cacerts, cert, certfile, ciphers, - fail_if_no_peer_cert, hibernate_after, - honor_cipher_order, ip, key, keyfile, linger, - next_protocols_advertised, nodelay, - log_alert, partial_chain, password, port, raw, - reuse_session, reuse_sessions, secure_renegotiate, - send_timeout, send_timeout_close, verify, verify_fun, - versions], + ssl:listen(0, ranch:filter_options(Opts6, listen_options(), [binary, {active, false}, {packet, raw}, {reuseaddr, true}, {nodelay, true}])). +listen_options() -> + [alpn_preferred_protocols, cacertfile, cacerts, cert, certfile, + ciphers, client_renegotiation, crl_cache, crl_check, depth, + dh, dhfile, fail_if_no_peer_cert, hibernate_after, honor_cipher_order, + key, keyfile, log_alert, next_protocols_advertised, partial_chain, + password, psk_identity, reuse_session, reuse_sessions, secure_renegotiate, + sni_fun, sni_hosts, user_lookup_fun, verify, verify_fun, versions + |ranch_tcp:listen_options()]. + -spec accept(ssl:sslsocket(), timeout()) -> {ok, ssl:sslsocket()} | {error, closed | timeout | atom()}. accept(LSocket, Timeout) -> diff --git a/src/ranch_tcp.erl b/src/ranch_tcp.erl index 51b10ba..797dec1 100644 --- a/src/ranch_tcp.erl +++ b/src/ranch_tcp.erl @@ -19,6 +19,7 @@ -export([secure/0]). -export([messages/0]). -export([listen/1]). +-export([listen_options/0]). -export([accept/2]). -export([accept_ack/2]). -export([connect/3]). @@ -36,14 +37,29 @@ -export([close/1]). -type 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()}. + | {send_timeout_close, boolean()} + | {sndbuf, non_neg_integer()} + | {tos, integer()}. -export_type([opt/0]). -type opts() :: [opt()]. @@ -60,16 +76,25 @@ messages() -> {tcp, tcp_closed, tcp_error}. -spec listen(opts()) -> {ok, inet:socket()} | {error, atom()}. listen(Opts) -> Opts2 = ranch:set_option_default(Opts, backlog, 1024), - Opts3 = ranch:set_option_default(Opts2, send_timeout, 30000), - Opts4 = ranch:set_option_default(Opts3, send_timeout_close, true), + Opts3 = ranch:set_option_default(Opts2, nodelay, true), + Opts4 = ranch:set_option_default(Opts3, send_timeout, 30000), + Opts5 = ranch:set_option_default(Opts4, send_timeout_close, true), %% We set the port to 0 because it is given in the Opts directly. %% The port in the options takes precedence over the one in the %% first argument. - gen_tcp:listen(0, ranch:filter_options(Opts4, - [backlog, ip, linger, nodelay, port, raw, - send_timeout, send_timeout_close], - [binary, {active, false}, {packet, raw}, - {reuseaddr, true}, {nodelay, true}])). + gen_tcp:listen(0, ranch:filter_options(Opts5, listen_options(), + [binary, {active, false}, {packet, raw}, {reuseaddr, true}])). + +%% 'inet' and 'inet6' are also allowed but they are handled +%% specifically as they do not have 2-tuple equivalents. +%% +%% The 4-tuple 'raw' option is also handled specifically. +listen_options() -> + [backlog, buffer, delay_send, dontroute, exit_on_close, fd, + high_msgq_watermark, high_watermark, ip, + keepalive, linger, low_msgq_watermark, + low_watermark, nodelay, port, priority, recbuf, + send_timeout, send_timeout_close, sndbuf, tos]. -spec accept(inet:socket(), timeout()) -> {ok, inet:socket()} | {error, closed | timeout | atom()}. |