From e91b2afc41716557bad662e346e9f978ee3156ba Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 12 Jun 2018 09:55:50 +0200 Subject: ssl: Add handle_continue/2 and document enhancements * deprecation of ssl:ssl_accept/[1,2,3] * deprecation of ssl:cipher_suites/[0,1] * More consistent naming --- lib/ssl/doc/src/ssl.xml | 142 ++++++++++++++++++------------------------ lib/ssl/doc/src/using_ssl.xml | 6 +- lib/ssl/src/ssl.erl | 12 +++- lib/ssl/test/ssl_test_lib.erl | 2 +- 4 files changed, 75 insertions(+), 87 deletions(-) (limited to 'lib') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 825bf46459..d6e9e949c3 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -896,16 +896,7 @@ fun(srp, Username :: string(), UserState :: term()) -> Type = erlang | openssl | all -

Returns a list of supported cipher suites. - This function will become deprecated in OTP 21, and replaced - by ssl:cipher-suites/2 - cipher_suites() is equivalent to cipher_suites(erlang). - Type openssl is provided for backwards compatibility with the - old SSL, which used OpenSSL. cipher_suites(all) returns - all available cipher suites. The cipher suites not present - in cipher_suites(erlang) but included in - cipher_suites(all) are not used unless explicitly configured - by the user.

+

Deprecated in OTP 21, use ssl:cipher_suites/2 instead.

 @@ -948,7 +939,7 @@ fun(srp, Username :: string(), UserState :: term()) -> connect(Socket, SslOptions) -> - connect(Socket, SslOptions, Timeout) -> {ok, TLSSocket} | {ok, TLSSocket, Ext} + connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} Upgrades a gen_tcp, or equivalent, connected socket to an TLS socket. @@ -956,7 +947,7 @@ fun(srp, Username :: string(), UserState :: term()) -> Socket = socket() SslOptions = [{handshake, hello| full} | ssl_option()] Timeout = integer() | infinity - TLSSocket = sslsocket() + SslSocket = sslsocket() Ext = hello_extensions() Reason = term() @@ -973,8 +964,8 @@ fun(srp, Username :: string(), UserState :: term()) ->

If the option {handshake, hello} is used the handshake is paused after receiving the server hello message - and the success response is {ok, TLSSocket, Ext} - instead of {ok, TLSSocket}. Thereafter the handshake is continued or + and the success response is {ok, SslSocket, Ext} + instead of {ok, SslSocket}. Thereafter the handshake is continued or canceled by calling handshake_continue/3 or handshake_cancel/1. @@ -986,7 +977,7 @@ fun(srp, Username :: string(), UserState :: term()) -> connect(Host, Port, Options) -> connect(Host, Port, Options, Timeout) -> - {ok, SslSocket}| {ok, TLSSocket, Ext} | {error, Reason} + {ok, SslSocket}| {ok, SslSocket, Ext} | {error, Reason} Opens an TLS/DTLS connection to Host, Port. Host = host() @@ -1017,8 +1008,8 @@ fun(srp, Username :: string(), UserState :: term()) ->

If the option {handshake, hello} is used the handshake is paused after receiving the server hello message - and the success response is {ok, TLSSocket, Ext} - instead of {ok, TLSSocket}. Thereafter the handshake is continued or + and the success response is {ok, SslSocket, Ext} + instead of {ok, SslSocket}. Thereafter the handshake is continued or canceled by calling handshake_continue/3 or handshake_cancel/1. @@ -1074,6 +1065,7 @@ fun(srp, Username :: string(), UserState :: term()) -> Returns all the connection information. + SslSocket = sslsocket() Item = protocol | cipher_suite | sni_hostname | ecc | session_id | atom() Meaningful atoms, not specified above, are the ssl option names. Result = [{Item::atom(), Value::term()}] @@ -1091,6 +1083,7 @@ fun(srp, Username :: string(), UserState :: term()) -> Returns the requested connection information. + SslSocket = sslsocket() Items = [Item] Item = protocol | cipher_suite | sni_hostname | ecc | session_id | client_random | server_random | master_secret | atom() @@ -1133,7 +1126,7 @@ fun(srp, Username :: string(), UserState :: term()) -> - getopts(Socket, OptionNames) -> + getopts(SslSocket, OptionNames) -> {ok, [socketoption()]} | {error, Reason} Gets the values of the specified options. @@ -1147,13 +1140,13 @@ fun(srp, Username :: string(), UserState :: term()) -> - getstat(Socket) -> + getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()} - getstat(Socket, OptionNames) -> + getstat(SslSocket, OptionNames) -> {ok, OptionValues} | {error, inet:posix()} Get one or more statistic options for a socket - Socket = sslsocket() + SslSocket = sslsocket() OptionNames = [atom()] OptionValues = [{inet:stat_option(), integer()}] @@ -1164,28 +1157,27 @@ fun(srp, Username :: string(), UserState :: term()) -> - handshake(Socket) -> - handshake(Socket, Timeout) -> {ok, Socket} | {error, Reason} + handshake(HsSocket) -> + handshake(HsSocket, Timeout) -> {ok, SslSocket} | {error, Reason} Performs server-side SSL/TLS handshake. - Socket = sslsocket() + HsSocket = SslSocket = sslsocket() Timeout = integer() Reason = term()

Performs the SSL/TLS/DTLS server-side handshake.

-

Socket is a socket as returned by - ssl:transport_accept/[1,2]. -

+

Returns a new TLS/DTLS socket if the handshake is successful.

 handshake(Socket, SslOptions) -> - handshake(Socket, SslOptions, Timeout) -> {ok, Socket} | {ok, Socket, Ext} | {error, Reason} + handshake(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} Performs server-side SSL/TLS/DTLS handshake. Socket = socket() | sslsocket() + SslSocket = sslsocket() Ext = hello_extensions() SslOptions = [{handshake, hello| full} | ssl_option()] Timeout = integer() @@ -1194,22 +1186,23 @@ fun(srp, Username :: string(), UserState :: term()) ->

If Socket is a ordinary socket(): upgrades a gen_tcp, or equivalent, socket to an SSL socket, that is, performs - the SSL/TLS server-side handshake and returns the SSL socket.

+ the SSL/TLS server-side handshake and returns a TLS socket.

-

The Socket shall be in passive mode ({active, - false}) before calling this function or the handshake can fail - due to a race condition.

 +

The Socket shall be in passive mode ({active, + false}) before calling this function or else the behavior of this function + is undefined. +

If Socket is an sslsocket(): provides extra SSL/TLS/DTLS options to those specified in ssl:listen/2 and then performs - the SSL/TLS/DTLS handshake.

- + the SSL/TLS/DTLS handshake. Returns a new TLS/DTLS socket if the handshake is successful.

+

If option {handshake, hello} is specified the handshake is paused after receiving the client hello message and the - sucess response is {ok, TLSSocket, Ext} instead of {ok, - TLSSocket}. Thereafter the handshake is continued or + success response is {ok, SslSocket, Ext} instead of {ok, + SslSocket}. Thereafter the handshake is continued or canceled by calling handshake_continue/3 or handshake_cancel/1. @@ -1218,10 +1211,10 @@ fun(srp, Username :: string(), UserState :: term()) -> - handshake_cancel(Socket) -> ok + handshake_cancel(SslSocket) -> ok Cancel handshake with a fatal alert - Socket = sslsocket() + SslSocket = sslsocket()

Cancel the handshake with a fatal USER_CANCELED alert.

@@ -1229,10 +1222,11 @@ fun(srp, Username :: string(), UserState :: term()) -> - handshake_continue(Socket, SSLOptions, Timeout) -> {ok, Socket} | {error, Reason} + handshake_continue(HsSocket, SSLOptions) -> {ok, SslSocket} | {error, Reason} + handshake_continue(HsSocket, SSLOptions, Timeout) -> {ok, SslSocket} | {error, Reason} Continue the SSL/TLS handshake. - Socket = sslsocket() + HsSocket = SslSocket = sslsocket() SslOptions = [ssl_option()] Timeout = integer() Reason = term() @@ -1257,10 +1251,10 @@ fun(srp, Username :: string(), UserState :: term()) -> - negotiated_protocol(Socket) -> {ok, Protocol} | {error, protocol_not_negotiated} + negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, protocol_not_negotiated} Returns the protocol negotiated through ALPN or NPN extensions. - Socket = sslsocket() + SslSocket = sslsocket() Protocol = binary() @@ -1271,10 +1265,10 @@ fun(srp, Username :: string(), UserState :: term()) -> - peercert(Socket) -> {ok, Cert} | {error, Reason} + peercert(SslSocket) -> {ok, Cert} | {error, Reason} Returns the peer certificate. - Socket = sslsocket() + SslSocket = sslsocket() Cert = binary() @@ -1285,11 +1279,11 @@ fun(srp, Username :: string(), UserState :: term()) -> - peername(Socket) -> {ok, {Address, Port}} | + peername(SslSocket) -> {ok, {Address, Port}} | {error, Reason} Returns the peer address and port. - Socket = sslsocket() + SslSocket = sslsocket() Address = ipaddress() Port = integer() @@ -1335,12 +1329,12 @@ fun(srp, Username :: string(), UserState :: term()) -> - recv(Socket, Length) -> - recv(Socket, Length, Timeout) -> {ok, Data} | {error, + recv(SslSocket, Length) -> + recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, Reason} Receives data on a socket. - Socket = sslsocket() + SslSocket = sslsocket() Length = integer() Timeout = integer() Data = [char()] | binary() @@ -1362,10 +1356,10 @@ fun(srp, Username :: string(), UserState :: term()) -> - renegotiate(Socket) -> ok | {error, Reason} + renegotiate(SslSocket) -> ok | {error, Reason} Initiates a new handshake. - Socket = sslsocket() + SslSocket = sslsocket()

Initiates a new handshake. A notable return value is {error, renegotiation_rejected} indicating that the peer @@ -1375,10 +1369,10 @@ fun(srp, Username :: string(), UserState :: term()) -> - send(Socket, Data) -> ok | {error, Reason} + send(SslSocket, Data) -> ok | {error, Reason} Writes data to a socket. - Socket = sslsocket() + SslSocket = sslsocket() Data = iodata() @@ -1389,10 +1383,10 @@ fun(srp, Username :: string(), UserState :: term()) -> - setopts(Socket, Options) -> ok | {error, Reason} + setopts(SslSocket, Options) -> ok | {error, Reason} Sets socket options. - Socket = sslsocket() + SslSocket = sslsocket() Options = [socketoption]() @@ -1402,10 +1396,10 @@ fun(srp, Username :: string(), UserState :: term()) -> - shutdown(Socket, How) -> ok | {error, Reason} + shutdown(SslSocket, How) -> ok | {error, Reason} Immediately closes a socket. - Socket = sslsocket() + SslSocket = sslsocket() How = read | write | read_write Reason = reason() @@ -1420,19 +1414,16 @@ fun(srp, Username :: string(), UserState :: term()) -> - ssl_accept(Socket) -> - ssl_accept(Socket, Timeout) -> ok | {error, Reason} + ssl_accept(SslSocket) -> + ssl_accept(SslSocket, Timeout) -> ok | {error, Reason} Performs server-side SSL/TLS handshake. - Socket = sslsocket() + SslSocket = sslsocket() Timeout = integer() Reason = term() -

Performs the SSL/TLS/DTLS server-side handshake.

-

Socket is a socket as returned by - ssl:transport_accept/[1,2] -

+

Deprecated in OTP 21, use ssl:handshake[1,2] instead.

 @@ -1447,29 +1438,16 @@ fun(srp, Username :: string(), UserState :: term()) -> Reason = term() -

If Socket is a socket(): upgrades a gen_tcp, - or equivalent, socket to an SSL socket, that is, performs - the SSL/TLS server-side handshake and returns the SSL socket.

- -

The listen socket is to be in mode {active, false} - before telling the client that the server is ready to upgrade - by calling this function, else the upgrade succeeds or does not - succeed depending on timing.

 - -

If Socket is an sslsocket(): provides extra SSL/TLS/DTLS - options to those specified in - ssl:listen/2 and then performs - the SSL/TLS/DTLS handshake. -

+

Deprecated in OTP 21, use ssl:handshake[2,3] instead.

 - sockname(Socket) -> {ok, {Address, Port}} | + sockname(SslSocket) -> {ok, {Address, Port}} | {error, Reason} Returns the local address and port. - Socket = sslsocket() + SslSocket = sslsocket() Address = ipaddress() Port = integer() @@ -1503,11 +1481,11 @@ fun(srp, Username :: string(), UserState :: term()) -> transport_accept(ListenSocket) -> transport_accept(ListenSocket, Timeout) -> - {ok, NewSocket} | {error, Reason} + {ok, SslSocket} | {error, Reason} Accepts an incoming connection and prepares for ssl_accept. - ListenSocket = NewSocket = sslsocket() + ListenSocket = SslSocket = sslsocket() Timeout = integer() Reason = reason() diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml index 3ef33df719..b2d649042b 100644 --- a/lib/ssl/doc/src/using_ssl.xml +++ b/lib/ssl/doc/src/using_ssl.xml @@ -66,7 +66,7 @@ ssl:listen(9999, [{certfile, "cert.pem"}, {keyfile, "key.pem"},{reuseaddr, true} {ok,{sslsocket, [...]}}

Step 3: Do a transport accept on the TLS listen socket:

- 3 server> {ok, Socket} = ssl:transport_accept(ListenSocket). + 3 server> {ok, TLSTransportSocket} = ssl:transport_accept(ListenSocket). {ok,{sslsocket, [...]}}

Step 4: Start the client side:

@@ -77,7 +77,7 @@ ok {ok,{sslsocket, [...]}}

Step 5: Do the TLS handshake:

- 4 server> ok = ssl:ssl_accept(Socket). + 4 server> {ok, Socket} = ssl:handshake(TLSTransportSocket). ok

Step 6: Send a message over TLS:

@@ -126,7 +126,7 @@ ok ok

Step 6: Do the TLS handshake:

- 5 server> {ok, TLSSocket} = ssl:ssl_accept(Socket, [{cacertfile, "cacerts.pem"}, + 5 server> {ok, TLSSocket} = ssl:handshake(Socket, [{cacertfile, "cacerts.pem"}, {certfile, "cert.pem"}, {keyfile, "key.pem"}]). {ok,{sslsocket,[...]}} diff --git a/lib/ssl/src/ssl.erl b/lib/ssl/src/ssl.erl index 565cc9e1bc..130276accd 100644 --- a/lib/ssl/src/ssl.erl +++ b/lib/ssl/src/ssl.erl @@ -40,7 +40,7 @@ %% Socket handling -export([connect/3, connect/2, connect/4, listen/2, transport_accept/1, transport_accept/2, - handshake/1, handshake/2, handshake/3, + handshake/1, handshake/2, handshake/3, handshake_continue/2, handshake_continue/3, handshake_cancel/1, ssl_accept/1, ssl_accept/2, ssl_accept/3, controlling_process/2, peername/1, peercert/1, sockname/1, @@ -259,6 +259,16 @@ handshake(Socket, SslOptions, Timeout) when is_port(Socket), Error = {error, _Reason} -> Error end. + +%%-------------------------------------------------------------------- +-spec handshake_continue(#sslsocket{}, [ssl_option()]) -> + {ok, #sslsocket{}} | {error, reason()}. +%% +%% +%% Description: Continues the handshke possible with newly supplied options. +%%-------------------------------------------------------------------- +handshake_continue(Socket, SSLOptions) -> + handshake_continue(Socket, SSLOptions, infinity). %%-------------------------------------------------------------------- -spec handshake_continue(#sslsocket{}, [ssl_option()], timeout()) -> {ok, #sslsocket{}} | {error, reason()}. diff --git a/lib/ssl/test/ssl_test_lib.erl b/lib/ssl/test/ssl_test_lib.erl index 1e88ca15de..596bf3a6e9 100644 --- a/lib/ssl/test/ssl_test_lib.erl +++ b/lib/ssl/test/ssl_test_lib.erl @@ -309,7 +309,7 @@ client_cont_loop(Node, Host, Port, Pid, Transport, Options, ContOpts, Opts) -> case rpc:call(Node, Transport, connect, [Host, Port, Options]) of {ok, Socket0, _} -> ct:log("~p:~p~nClient: handshake_continue(~p, ~p, infinity) ~n", [?MODULE, ?LINE, Socket0, ContOpts]), - case rpc:call(Node, Transport, handshake_continue, [Socket0, ContOpts, infinity]) of + case rpc:call(Node, Transport, handshake_continue, [Socket0, ContOpts]) of {ok, Socket} -> Pid ! {connected, Socket}, {Module, Function, Args} = proplists:get_value(mfa, Opts), -- cgit v1.2.3