Merge branch 'ingela/ssl/backported-ssl-enhancments/ERL-929/ERL-893/PR-2215/OTP-15785' into maint

6 files changed, 298 insertions, 147 deletions

diff --git a/lib/ssl/src/ssl.erl b/lib/ssl/src/ssl.erl
index 7f8f1ec71c..7c1d0a3829 100644
--- a/lib/ssl/src/ssl.erl
+++ b/lib/ssl/src/ssl.erl
@@ -85,19 +85,20 @@
               srp_param_type/0]).
 
 %% -------------------------------------------------------------------------------------------------------
--type socket()                   :: gen_tcp:socket().
--type socket_option()            :: gen_tcp:connect_option() | gen_tcp:listen_option() | gen_udp:option().
--type sslsocket()                :: any().
--type tls_option()               :: tls_client_option() | tls_server_option().
--type tls_client_option()        :: client_option() | common_option() | socket_option() |  transport_option().
--type tls_server_option()        :: server_option() | common_option() | socket_option() | transport_option().
+
+-type socket()                   :: gen_tcp:socket(). % exported
+-type socket_option()            :: gen_tcp:connect_option() | gen_tcp:listen_option() | gen_udp:option(). % exported
+-type sslsocket()                :: any(). % exported
+-type tls_option()               :: tls_client_option() | tls_server_option(). % exported
+-type tls_client_option()        :: client_option() | common_option() | socket_option() |  transport_option(). % exported
+-type tls_server_option()        :: server_option() | common_option() | socket_option() | transport_option(). % exported
 -type active_msgs()              :: {ssl, sslsocket(), Data::binary() | list()} | {ssl_closed, sslsocket()} |
-                                    {ssl_error, sslsocket(), Reason::term()} | {ssl_passive, sslsocket()}.
+                                    {ssl_error, sslsocket(), Reason::any()} | {ssl_passive, sslsocket()}. % exported
 -type transport_option()         :: {cb_info, {CallbackModule::atom(), DataTag::atom(),
                                                ClosedTag::atom(), ErrTag::atom()}} |  
                                     {cb_info, {CallbackModule::atom(), DataTag::atom(),
                                                ClosedTag::atom(), ErrTag::atom(), PassiveTag::atom()}}.
--type host()                     :: hostname() | ip_address().
+-type host()                     :: hostname() | ip_address(). % exported
 -type hostname()                 :: string().
 -type ip_address()               :: inet:ip_address().
 -type session_id()               :: binary().
@@ -111,14 +112,14 @@
                                     aes_128_gcm |
                                     aes_256_gcm |
                                     chacha20_poly1305 |
-                                    legacy_cipher().
+                                    legacy_cipher(). % exported
 -type legacy_cipher()            ::  rc4_128 |
                                      des_cbc |
                                      '3des_ede_cbc'.
 
 -type hash()                     :: sha |
                                     sha2() |
-                                    legacy_hash().
+                                    legacy_hash(). % exported
 
 -type sha2()                    ::  sha224 |
                                     sha256 |
@@ -133,8 +134,8 @@
                                    ecdhe_ecdsa | ecdh_ecdsa | ecdh_rsa |
                                    srp_rsa| srp_dss |
                                    psk | dhe_psk | rsa_psk |
-                                   dh_anon | ecdh_anon | srp_anon |
-                                   any. %% TLS 1.3
+                                   dh_anon | ecdh_anon | srp_anon.
+
 -type erl_cipher_suite()       :: #{key_exchange := kex_algo(),
                                     cipher := cipher(),
                                     mac    := hash() | aead,
@@ -180,9 +181,9 @@
                                  srp_3072 |
                                  srp_4096 |
                                  srp_6144 |
-                                 srp_8192.
+                                 srp_8192. % exported
 
--type error_alert()           :: {tls_alert, {tls_alert(), Description::string()}}.
+-type error_alert()           :: {tls_alert, {tls_alert(), Description::string()}}. % exported
 
 -type tls_alert()             :: close_notify | 
                                  unexpected_message | 
@@ -213,6 +214,7 @@
                                  bad_certificate_hash_value |
                                  unknown_psk_identity |
                                  no_application_protocol.
+
 %% -------------------------------------------------------------------------------------------------------
 -type common_option()        :: {protocol, protocol()} |
                                 {handshake, handshake_completion()} |
@@ -222,7 +224,6 @@
                                 {keyfile, key_pem()} |
                                 {password, key_password()} |
                                 {ciphers, cipher_suites()} |
-                                {eccs, eccs()} |
                                 {secure_renegotiate, secure_renegotiation()} |
                                 {depth, allowed_cert_chain_length()} |
                                 {verify_fun, custom_verify()} |
@@ -247,16 +248,15 @@
                                      #{algorithm := rsa | dss | ecdsa, 
                                        engine := crypto:engine_ref(), 
                                        key_id := crypto:key_id(), 
-                                       password => crypto:password()}.
+                                       password => crypto:password()}. % exported
 -type key_pem()                   :: file:filename().
 -type key_password()              :: string().
 -type cipher_suites()             :: ciphers().    
 -type ciphers()                   :: [erl_cipher_suite()] |
-                                     string(). % (according to old API)
+                                     string(). % (according to old API) exported
 -type cipher_filters()            :: list({key_exchange | cipher | mac | prf,
-                                        algo_filter()}).
+                                        algo_filter()}). % exported
 -type algo_filter()               :: fun((kex_algo()|cipher()|hash()|aead|default_prf) -> true | false).
--type eccs()                      :: [named_curve()].  
 -type secure_renegotiation()      :: boolean(). 
 -type allowed_cert_chain_length() :: integer().
 -type custom_verify()             ::  {Verifyfun :: fun(), InitialUserState :: term()}.
@@ -311,7 +311,6 @@
 -type ssl_imp()                  :: new | old.
 
 %% -------------------------------------------------------------------------------------------------------
-
 -type server_option()        :: {cacerts, server_cacerts()} |
                                 {cacertfile, server_cafile()} |
                                 {dh, dh_der()} |
@@ -349,7 +348,7 @@
 -type honor_ecc_order()          :: boolean().
 -type client_renegotiation()     :: boolean().
 %% -------------------------------------------------------------------------------------------------------
--type prf_random() :: client_random | server_random.
+-type prf_random() :: client_random | server_random. % exported
 -type protocol_extensions()  :: #{renegotiation_info => binary(),
                                   signature_algs => signature_algs(),
                                   alpn =>  app_level_protocol(),
@@ -357,7 +356,7 @@
                                   next_protocol => app_level_protocol(),
                                   ec_point_formats  => [0..2],
                                   elliptic_curves => [public_key:oid()],
-                                  sni => hostname()}.
+                                  sni => hostname()}. % exported
 %% -------------------------------------------------------------------------------------------------------
 
 %%%--------------------------------------------------------------------
@@ -393,14 +392,29 @@ stop() ->
 %%
 %% Description: Connect to an ssl server.
 %%--------------------------------------------------------------------
--spec connect(host() | port(), [client_option()]) -> {ok, #sslsocket{}} |
-					      {error, reason()}.
+-spec connect(TCPSocket, TLSOptions) ->
+                     {ok, sslsocket()} |
+                     {error, reason()} |
+                     {option_not_a_key_value_tuple, any()} when
+      TCPSocket :: socket(),
+      TLSOptions :: [tls_client_option()].
+
 connect(Socket, SslOptions) when is_port(Socket) ->
     connect(Socket, SslOptions, infinity).
 
--spec connect(host() | port(), [client_option()] | inet:port_number(),
-	      timeout() | list()) ->
-		     {ok, #sslsocket{}} | {error, reason()}.
+-spec connect(TCPSocket, TLSOptions, Timeout) ->
+                     {ok, sslsocket()} | {error, reason()} when
+      TCPSocket :: socket(),
+      TLSOptions :: [tls_client_option()],
+      Timeout :: timeout();
+             (Host, Port, TLSOptions) ->
+                     {ok, sslsocket()} |
+                     {ok, sslsocket(),Ext :: protocol_extensions()} |
+                     {error, reason()} |
+                     {option_not_a_key_value_tuple, any()} when
+      Host :: host(),
+      Port :: inet:port_number(),
+      TLSOptions :: [tls_client_option()].
 connect(Socket, SslOptions0, Timeout) when is_port(Socket),
                                            (is_integer(Timeout) andalso Timeout >= 0) or (Timeout == infinity) ->
     CbInfo = handle_option(cb_info, SslOptions0, default_cb_info(tls)),
@@ -417,8 +431,16 @@ connect(Socket, SslOptions0, Timeout) when is_port(Socket),
 connect(Host, Port, Options) ->
     connect(Host, Port, Options, infinity).
 
--spec connect(host() | port(), inet:port_number(), [client_option()], timeout()) ->
-		     {ok, #sslsocket{}} | {error, reason()}.
+-spec connect(Host, Port, TLSOptions, Timeout) ->
+                     {ok, sslsocket()} |
+                     {ok, sslsocket(),Ext :: protocol_extensions()} |
+                     {error, reason()} |
+                     {option_not_a_key_value_tuple, any()} when
+      Host :: host(),
+      Port :: inet:port_number(),
+      TLSOptions :: [tls_client_option()],
+      Timeout :: timeout().
+
 connect(Host, Port, Options, Timeout) when (is_integer(Timeout) andalso Timeout >= 0) or (Timeout == infinity) ->
     try
 	{ok, Config} = handle_options(Options, client, Host),
@@ -434,7 +456,10 @@ connect(Host, Port, Options, Timeout) when (is_integer(Timeout) andalso Timeout
     end.
 
 %%--------------------------------------------------------------------
--spec listen(inet:port_number(), [tls_server_option()]) ->{ok, #sslsocket{}} | {error, reason()}.
+-spec listen(Port, Options) -> {ok, ListenSocket} | {error, reason()} when
+      Port::inet:port_number(),
+      Options::[tls_server_option()],
+      ListenSocket :: sslsocket().
 
 %%
 %% Description: Creates an ssl listen socket.
@@ -453,13 +478,20 @@ listen(Port, Options0) ->
 %%
 %% Description: Performs transport accept on an ssl listen socket
 %%--------------------------------------------------------------------
--spec transport_accept(#sslsocket{}) -> {ok, #sslsocket{}} |
-					{error, reason()}.
+-spec transport_accept(ListenSocket) -> {ok, SslSocket} |
+					{error, reason()} when
+      ListenSocket :: sslsocket(),
+      SslSocket :: sslsocket().
+
 transport_accept(ListenSocket) ->
     transport_accept(ListenSocket, infinity).
 
--spec transport_accept(#sslsocket{}, timeout()) -> {ok, #sslsocket{}} |
-						   {error, reason()}.
+-spec transport_accept(ListenSocket, Timeout) -> {ok, SslSocket} |
+					{error, reason()} when
+      ListenSocket :: sslsocket(),
+      Timeout :: timeout(),
+      SslSocket :: sslsocket().
+
 transport_accept(#sslsocket{pid = {ListenSocket,
 				   #config{connection_cb = ConnectionCb} = Config}}, Timeout) 
   when (is_integer(Timeout) andalso Timeout >= 0) or (Timeout == infinity) ->
@@ -475,12 +507,22 @@ transport_accept(#sslsocket{pid = {ListenSocket,
 %% Description: Performs accept on an ssl listen socket. e.i. performs
 %%              ssl handshake.
 %%--------------------------------------------------------------------
--spec ssl_accept(#sslsocket{}) -> ok | {error, timeout | closed | {options, any()}| error_alert()}.
+-spec ssl_accept(SslSocket) ->
+                        ok |
+                        {error, Reason} when
+      SslSocket :: sslsocket(),
+      Reason :: closed | timeout | error_alert().
+
 ssl_accept(ListenSocket) ->
     ssl_accept(ListenSocket, [], infinity).
 
--spec ssl_accept(#sslsocket{} | port(), timeout()| [tls_server_option()]) ->
-			ok | {ok, #sslsocket{}} | {error, timeout | closed | {options, any()}| error_alert()}.
+-spec ssl_accept(Socket, TimeoutOrOptions) ->
+			ok |
+                        {ok, sslsocket()} | {error, Reason} when
+      Socket :: sslsocket() | socket(),
+      TimeoutOrOptions :: timeout() | [tls_server_option()],
+      Reason :: timeout | closed | {options, any()} | error_alert().
+
 ssl_accept(Socket, Timeout)  when  (is_integer(Timeout) andalso Timeout >= 0) or (Timeout == infinity) ->
     ssl_accept(Socket, [], Timeout);
 ssl_accept(ListenSocket, SslOptions) when is_port(ListenSocket) ->
@@ -488,8 +530,13 @@ ssl_accept(ListenSocket, SslOptions) when is_port(ListenSocket) ->
 ssl_accept(Socket, Timeout) ->
     ssl_accept(Socket, [], Timeout).
 
--spec ssl_accept(#sslsocket{} | port(), [tls_server_option()], timeout()) ->
-			ok | {ok, #sslsocket{}} | {error, timeout | closed | {options, any()}| error_alert()}.
+-spec ssl_accept(Socket, Options, Timeout) ->
+			ok | {ok, sslsocket()} | {error, Reason} when
+      Socket :: sslsocket() | socket(),
+      Options :: [tls_server_option()],
+      Timeout :: timeout(),
+      Reason :: timeout | closed | {options, any()} | error_alert().
+
 ssl_accept(Socket, SslOptions, Timeout) when is_port(Socket) ->
     handshake(Socket, SslOptions, Timeout);
 ssl_accept(Socket, SslOptions, Timeout) ->
@@ -506,12 +553,29 @@ ssl_accept(Socket, SslOptions, Timeout) ->
 %%--------------------------------------------------------------------
 
 %% Performs the SSL/TLS/DTLS server-side handshake.
--spec handshake(#sslsocket{}) -> {ok, #sslsocket{}} | {error, timeout | closed | {options, any()} | error_alert()}.
+
+-spec handshake(HsSocket) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} when
+      HsSocket :: sslsocket(),
+      SslSocket :: sslsocket(),
+      Ext :: protocol_extensions(),
+      Reason :: closed | timeout | error_alert().
+
 handshake(ListenSocket) ->
     handshake(ListenSocket, infinity).
 
--spec handshake(#sslsocket{} | port(), timeout()| [tls_server_option()]) ->
-                       {ok, #sslsocket{}} | {error, timeout | closed | {options, any()} | error_alert()}.
+-spec handshake(HsSocket, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} when
+      HsSocket :: sslsocket(),
+      Timeout :: timeout(),
+      SslSocket :: sslsocket(),
+      Ext :: protocol_extensions(),
+      Reason :: closed | timeout | error_alert();
+               (Socket, Options) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} when
+      Socket :: socket() | sslsocket(),
+      SslSocket :: sslsocket(),
+      Options :: [server_option()],
+      Ext :: protocol_extensions(),
+      Reason :: closed | timeout | error_alert().
+
 handshake(#sslsocket{} = Socket, Timeout) when  (is_integer(Timeout) andalso Timeout >= 0) or 
                                                 (Timeout == infinity) ->
     ssl_connection:handshake(Socket, Timeout);
@@ -519,8 +583,17 @@ handshake(#sslsocket{} = Socket, Timeout) when  (is_integer(Timeout) andalso Tim
 handshake(ListenSocket, SslOptions)  when is_port(ListenSocket) ->
     handshake(ListenSocket, SslOptions, infinity).
 
--spec handshake(#sslsocket{} | port(), [tls_server_option()], timeout()) ->
-			{ok, #sslsocket{}} | {error, timeout | closed | {options, any()} | error_alert()}.
+-spec handshake(Socket, Options, Timeout) ->
+                       {ok, SslSocket} |
+                       {ok, SslSocket, Ext} |
+                       {error, Reason} when
+      Socket :: socket() | sslsocket(),
+      SslSocket :: sslsocket(),
+      Options :: [server_option()],
+      Timeout :: timeout(),
+      Ext :: protocol_extensions(),
+      Reason :: closed | timeout | {options, any()} | error_alert().
+
 handshake(#sslsocket{} = Socket, [], Timeout) when (is_integer(Timeout) andalso Timeout >= 0) or 
                                                     (Timeout == infinity)->
     handshake(Socket, Timeout);
@@ -563,8 +636,12 @@ handshake(Socket, SslOptions, Timeout) when is_port(Socket),
 
 
 %%--------------------------------------------------------------------
--spec handshake_continue(#sslsocket{}, [tls_client_option() | tls_server_option()]) -> 
-                                {ok, #sslsocket{}} | {error, reason()}.
+-spec handshake_continue(HsSocket, Options) ->
+                                {ok, SslSocket} | {error, Reason} when
+      HsSocket :: sslsocket(),
+      Options :: [tls_client_option() | tls_server_option()],
+      SslSocket :: sslsocket(),
+      Reason :: closed | timeout | error_alert().
 %%
 %%
 %% Description: Continues the handshke possible with newly supplied options.
@@ -572,8 +649,13 @@ handshake(Socket, SslOptions, Timeout) when is_port(Socket),
 handshake_continue(Socket, SSLOptions) ->
     handshake_continue(Socket, SSLOptions, infinity).
 %%--------------------------------------------------------------------
--spec handshake_continue(#sslsocket{}, [tls_client_option() | tls_server_option()], timeout()) -> 
-                                {ok, #sslsocket{}} | {error, reason()}.
+-spec handshake_continue(HsSocket, Options, Timeout) ->
+                                {ok, SslSocket} | {error, Reason} when
+      HsSocket :: sslsocket(),
+      Options :: [tls_client_option() | tls_server_option()],
+      Timeout :: timeout(),
+      SslSocket :: sslsocket(),
+      Reason :: closed | timeout | error_alert().
 %%
 %%
 %% Description: Continues the handshke possible with newly supplied options.
@@ -581,7 +663,7 @@ handshake_continue(Socket, SSLOptions) ->
 handshake_continue(Socket, SSLOptions, Timeout) ->
     ssl_connection:handshake_continue(Socket, SSLOptions, Timeout).
 %%--------------------------------------------------------------------
--spec  handshake_cancel(#sslsocket{}) -> term().
+-spec  handshake_cancel(#sslsocket{}) -> any().
 %%
 %% Description: Cancels the handshakes sending a close alert.
 %%--------------------------------------------------------------------
@@ -589,7 +671,9 @@ handshake_cancel(Socket) ->
     ssl_connection:handshake_cancel(Socket).
 
 %%--------------------------------------------------------------------
--spec  close(#sslsocket{}) -> term().
+-spec  close(SslSocket) -> ok | {error, Reason} when
+      SslSocket :: sslsocket(),
+      Reason :: any().
 %%
 %% Description: Close an ssl connection
 %%--------------------------------------------------------------------
@@ -601,7 +685,10 @@ close(#sslsocket{pid = {ListenSocket, #config{transport_info={Transport,_,_,_,_}
     Transport:close(ListenSocket).
 
 %%--------------------------------------------------------------------
--spec  close(#sslsocket{}, timeout() | {pid(), integer()}) -> term().
+-spec  close(SslSocket, How) -> ok | {ok, port()} | {error,Reason} when
+      SslSocket :: sslsocket(),
+      How :: timeout() | {NewController::pid(), timeout()},
+      Reason :: any().
 %%
 %% Description: Close an ssl connection
 %%--------------------------------------------------------------------
@@ -617,7 +704,9 @@ close(#sslsocket{pid = {ListenSocket, #config{transport_info={Transport,_,_,_,_}
     Transport:close(ListenSocket).
 
 %%--------------------------------------------------------------------
--spec send(#sslsocket{}, iodata()) -> ok | {error, reason()}.
+-spec send(SslSocket, Data) -> ok | {error, reason()} when
+      SslSocket :: sslsocket(),
+      Data :: iodata().
 %%
 %% Description: Sends data over the ssl connection
 %%--------------------------------------------------------------------
@@ -637,11 +726,22 @@ send(#sslsocket{pid = {ListenSocket, #config{transport_info = Info}}}, Data) ->
 %%
 %% Description: Receives data when active = false
 %%--------------------------------------------------------------------
--spec recv(#sslsocket{}, integer()) -> {ok, binary()| list()} | {error, reason()}.
+-spec recv(SslSocket, Length) -> {ok, Data} | {error, reason()} when
+      SslSocket :: sslsocket(),
+      Length :: integer(),
+      Data :: binary() | list() | HttpPacket,
+      HttpPacket :: any().
+
 recv(Socket, Length) ->
     recv(Socket, Length, infinity).
 
--spec recv(#sslsocket{}, integer(), timeout()) -> {ok, binary()| list()} | {error, reason()}.
+-spec recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()} when
+      SslSocket :: sslsocket(),
+      Length :: integer(),
+      Data :: binary() | list() | HttpPacket,
+      Timeout :: timeout(),
+      HttpPacket :: any().
+
 recv(#sslsocket{pid = [Pid|_]}, Length, Timeout) when is_pid(Pid),
 						  (is_integer(Timeout) andalso Timeout >= 0) or (Timeout == infinity)->
     ssl_connection:recv(Pid, Length, Timeout);
@@ -653,7 +753,10 @@ recv(#sslsocket{pid = {Listen,
     Transport:recv(Listen, 0). %% {error,enotconn}
 
 %%--------------------------------------------------------------------
--spec controlling_process(#sslsocket{}, pid()) -> ok | {error, reason()}.
+-spec controlling_process(SslSocket, NewOwner) -> ok | {error, Reason} when
+      SslSocket :: sslsocket(),
+      NewOwner :: pid(),
+      Reason :: any().
 %%
 %% Description: Changes process that receives the messages when active = true
 %% or once.
@@ -672,7 +775,11 @@ controlling_process(#sslsocket{pid = {Listen,
 
 
 %%--------------------------------------------------------------------
--spec connection_information(#sslsocket{}) -> {ok, list()} | {error, reason()}.
+-spec connection_information(SslSocket) -> {ok, Result} | {error, reason()} when
+      SslSocket :: sslsocket(),
+      Result :: [{OptionName, OptionValue}],
+      OptionName :: atom(),
+      OptionValue :: any().
 %%
 %% Description: Return SSL information for the connection
 %%--------------------------------------------------------------------
@@ -689,7 +796,12 @@ connection_information(#sslsocket{pid = {dtls,_}}) ->
     {error,enotconn}. 
 
 %%--------------------------------------------------------------------
--spec connection_information(#sslsocket{}, [atom()]) -> {ok, list()} | {error, reason()}.
+-spec connection_information(SslSocket, Items) -> {ok, Result} | {error, reason()} when
+      SslSocket :: sslsocket(),
+      Items :: [OptionName],
+      Result :: [{OptionName, OptionValue}],
+      OptionName :: atom(),
+      OptionValue :: any().
 %%
 %% Description: Return SSL information for the connection
 %%--------------------------------------------------------------------
@@ -703,7 +815,11 @@ connection_information(#sslsocket{pid = [Pid|_]}, Items) when is_pid(Pid) ->
     end.
 
 %%--------------------------------------------------------------------
--spec peername(#sslsocket{}) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, reason()}.
+-spec peername(SslSocket) -> {ok, {Address, Port}} |
+                             {error, reason()} when
+      SslSocket :: sslsocket(),
+      Address :: inet:ip_address(),
+      Port :: inet:port_number().
 %%
 %% Description: same as inet:peername/1.
 %%--------------------------------------------------------------------
@@ -719,7 +835,9 @@ peername(#sslsocket{pid = {dtls,_}}) ->
     {error,enotconn}.
 
 %%--------------------------------------------------------------------
--spec peercert(#sslsocket{}) ->{ok, DerCert::binary()} | {error, reason()}.
+-spec peercert(SslSocket) -> {ok, Cert} | {error, reason()} when
+      SslSocket :: sslsocket(),
+      Cert :: binary().
 %%
 %% Description: Returns the peercert.
 %%--------------------------------------------------------------------
@@ -736,7 +854,10 @@ peercert(#sslsocket{pid = {Listen, _}}) when is_port(Listen) ->
     {error, enotconn}.
 
 %%--------------------------------------------------------------------
--spec negotiated_protocol(#sslsocket{}) -> {ok, binary()} | {error, reason()}.
+-spec negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason} when
+      SslSocket :: sslsocket(),
+      Protocol :: binary(),
+      Reason :: protocol_not_negotiated.
 %%
 %% Description: Returns the protocol that has been negotiated. If no
 %% protocol has been negotiated will return {error, protocol_not_negotiated}
@@ -750,8 +871,9 @@ negotiated_protocol(#sslsocket{pid = [Pid|_]}) when is_pid(Pid) ->
 cipher_suites() ->
     cipher_suites(erlang).
 %%--------------------------------------------------------------------
--spec cipher_suites(erlang | openssl | all) -> 
-                           [old_cipher_suite() | string()].
+-spec cipher_suites(Type) -> [old_cipher_suite() | string()] when
+      Type :: erlang | openssl | all.
+
 %% Description: Returns all supported cipher suites.
 %%--------------------------------------------------------------------
 cipher_suites(erlang) ->
@@ -765,9 +887,10 @@ cipher_suites(all) ->
     [ssl_cipher_format:erl_suite_definition(Suite) || Suite <- available_suites(all)].
 
 %%--------------------------------------------------------------------
--spec cipher_suites(default | all | anonymous, ssl_record:ssl_version() |
-                    tls_record:tls_atom_version() |  dtls_record:dtls_atom_version()) -> 
-                           [erl_cipher_suite()].
+-spec cipher_suites(Supported, Version) -> ciphers() when
+      Supported :: default | all | anonymous,
+      Version :: protocol_version().
+
 %% Description: Returns all default and all supported cipher suites for a
 %% TLS/DTLS version
 %%--------------------------------------------------------------------
@@ -783,9 +906,11 @@ cipher_suites(Base, Version) ->
     [ssl_cipher_format:suite_definition(Suite) || Suite <- supported_suites(Base, Version)].
 
 %%--------------------------------------------------------------------
--spec filter_cipher_suites([erl_cipher_suite()], 
-                           [{key_exchange | cipher | mac | prf, fun()}] | []) -> 
-                                  [erl_cipher_suite()].
+-spec filter_cipher_suites(Suites, Filters) -> Ciphers when
+      Suites :: ciphers(),
+      Filters :: cipher_filters(),
+      Ciphers :: ciphers().
+
 %% Description: Removes cipher suites if any of the filter functions returns false
 %% for any part of the cipher suite. This function also calls default filter functions
 %% to make sure the cipher suite are supported by crypto.
@@ -802,10 +927,10 @@ filter_cipher_suites(Suites, Filters0) ->
                 prf_filters => add_filter(proplists:get_value(prf, Filters0), PrfF)},
     ssl_cipher:filter_suites(Suites, Filters).
 %%--------------------------------------------------------------------
--spec prepend_cipher_suites([erl_cipher_suite()] | 
-                            [{key_exchange | cipher | mac | prf, fun()}],
-                            [erl_cipher_suite()]) -> 
-                                   [erl_cipher_suite()].
+-spec prepend_cipher_suites(Preferred, Suites) -> ciphers() when
+      Preferred :: ciphers() | cipher_filters(),
+      Suites :: ciphers().
+
 %% Description: Make <Preferred> suites become the most prefered
 %%      suites that is put them at the head of the cipher suite list
 %%      and remove them from <Suites> if present. <Preferred> may be a
@@ -820,10 +945,10 @@ prepend_cipher_suites(Filters, Suites) ->
     Preferred = filter_cipher_suites(Suites, Filters), 
     Preferred ++ (Suites -- Preferred).
 %%--------------------------------------------------------------------
--spec append_cipher_suites(Deferred :: [erl_cipher_suite()] | 
-                                       [{key_exchange | cipher | mac | prf, fun()}],
-                           [erl_cipher_suite()]) -> 
-                                  [erl_cipher_suite()].
+-spec append_cipher_suites(Deferred, Suites) -> ciphers() when
+      Deferred :: ciphers() | cipher_filters(),
+      Suites :: ciphers().
+
 %% Description: Make <Deferred> suites suites become the 
 %% least prefered suites that is put them at the end of the cipher suite list
 %% and removed them from <Suites> if present.
@@ -837,7 +962,9 @@ append_cipher_suites(Filters, Suites) ->
     (Suites -- Deferred) ++  Deferred.
 
 %%--------------------------------------------------------------------
--spec eccs() -> tls_v1:curves().
+-spec eccs() -> NamedCurves when
+      NamedCurves :: [named_curve()].
+
 %% Description: returns all supported curves across all versions
 %%--------------------------------------------------------------------
 eccs() ->
@@ -845,27 +972,24 @@ eccs() ->
     eccs_filter_supported(Curves).
 
 %%--------------------------------------------------------------------
--spec eccs(tls_record:tls_atom_version() |
-           ssl_record:ssl_version() | dtls_record:dtls_atom_version()) ->
-                  tls_v1:curves().
+-spec eccs(Version) -> NamedCurves when
+      Version :: protocol_version(),
+      NamedCurves :: [named_curve()].
+
 %% Description: returns the curves supported for a given version of
 %% ssl/tls.
 %%--------------------------------------------------------------------
-eccs({3,0}) ->
+eccs(sslv3) ->
     [];
-eccs({3,_}) ->
-    Curves = tls_v1:ecc_curves(all),
-    eccs_filter_supported(Curves);
-eccs({254,_} = Version) ->
-    eccs(dtls_v1:corresponding_tls_version(Version));
+eccs('dtlsv1') ->
+    eccs('tlsv1.1');
+eccs('dtlsv1.2') ->
+    eccs('tlsv1.2');
 eccs(Version) when Version == 'tlsv1.2';
                    Version == 'tlsv1.1';
-                   Version == tlsv1;
-                   Version == sslv3 ->
-    eccs(tls_record:protocol_version(Version));
-eccs(Version) when Version == 'dtlsv1.2';
-                   Version == 'dtlsv1'->
-    eccs(dtls_v1:corresponding_tls_version(dtls_record:protocol_version(Version))).
+                   Version == tlsv1 ->
+    Curves = tls_v1:ecc_curves(all),
+    eccs_filter_supported(Curves).
 
 eccs_filter_supported(Curves) ->
     CryptoCurves = crypto:ec_curves(),
@@ -873,8 +997,10 @@ eccs_filter_supported(Curves) ->
                  Curves).
 
 %%--------------------------------------------------------------------
--spec getopts(#sslsocket{}, [gen_tcp:option_name()]) ->
-		     {ok, [gen_tcp:option()]} | {error, reason()}.
+-spec getopts(SslSocket, OptionNames) ->
+		     {ok, [gen_tcp:option()]} | {error, reason()} when
+      SslSocket :: sslsocket(),
+      OptionNames :: [gen_tcp:option_name()].
 %%
 %% Description: Gets options
 %%--------------------------------------------------------------------
@@ -905,7 +1031,9 @@ getopts(#sslsocket{}, OptionTags) ->
     {error, {options, {socket_options, OptionTags}}}.
 
 %%--------------------------------------------------------------------
--spec setopts(#sslsocket{},  [gen_tcp:option()]) -> ok | {error, reason()}.
+-spec setopts(SslSocket, Options) -> ok | {error, reason()} when
+      SslSocket :: sslsocket(),
+      Options :: [gen_tcp:option()].
 %%
 %% Description: Sets options
 %%--------------------------------------------------------------------
@@ -961,9 +1089,9 @@ setopts(#sslsocket{}, Options) ->
     {error, {options,{not_a_proplist, Options}}}.
 
 %%---------------------------------------------------------------
--spec getstat(Socket) ->
-	{ok, OptionValues} | {error, inet:posix()} when
-      Socket :: #sslsocket{},
+-spec getstat(SslSocket) ->
+                     {ok, OptionValues} | {error, inet:posix()} when
+      SslSocket :: sslsocket(),
       OptionValues :: [{inet:stat_option(), integer()}].
 %%
 %% Description: Get all statistic options for a socket.
@@ -972,9 +1100,9 @@ getstat(Socket) ->
 	getstat(Socket, inet:stats()).
 
 %%---------------------------------------------------------------
--spec getstat(Socket, Options) ->
-	{ok, OptionValues} | {error, inet:posix()} when
-      Socket :: #sslsocket{},
+-spec getstat(SslSocket, Options) ->
+                     {ok, OptionValues} | {error, inet:posix()} when
+      SslSocket :: sslsocket(),
       Options :: [inet:stat_option()],
       OptionValues :: [{inet:stat_option(), integer()}].
 %%
@@ -987,7 +1115,9 @@ getstat(#sslsocket{pid = [Pid|_], fd = {Transport, Socket, _, _}}, Options) when
     tls_socket:getstat(Transport, Socket, Options).
 
 %%---------------------------------------------------------------
--spec shutdown(#sslsocket{}, read | write | read_write) ->  ok | {error, reason()}.
+-spec shutdown(SslSocket, How) ->  ok | {error, reason()} when
+      SslSocket :: sslsocket(),
+      How :: read | write | read_write.
 %%
 %% Description: Same as gen_tcp:shutdown/2
 %%--------------------------------------------------------------------
@@ -1001,7 +1131,11 @@ shutdown(#sslsocket{pid = [Pid|_]}, How) when is_pid(Pid) ->
     ssl_connection:shutdown(Pid, How).
 
 %%--------------------------------------------------------------------
--spec sockname(#sslsocket{}) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, reason()}.
+-spec sockname(SslSocket) ->
+                      {ok, {Address, Port}} | {error, reason()} when
+      SslSocket :: sslsocket(),
+      Address :: inet:ip_address(),
+      Port :: inet:port_number().
 %%
 %% Description: Same as inet:sockname/1
 %%--------------------------------------------------------------------
@@ -1015,10 +1149,10 @@ sockname(#sslsocket{pid = [Pid| _], fd = {Transport, Socket,_,_}}) when is_pid(P
     tls_socket:sockname(Transport, Socket).
 
 %%---------------------------------------------------------------
--spec versions() -> [{ssl_app, string()} | {supported, [tls_record:tls_atom_version()]} |
-                     {supported_dtls, [dtls_record:dtls_atom_version()]} |
-		     {available, [tls_record:tls_atom_version()]} |
-                     {available_dtls, [dtls_record:dtls_atom_version()]}].
+-spec versions() -> [VersionInfo] when
+      VersionInfo :: {ssl_app, string()} |
+                     {supported | available, [tls_version()]} |
+                     {supported_dtls | available_dtls, [dtls_version()]}.
 %%
 %% Description: Returns a list of relevant versions.
 %%--------------------------------------------------------------------
@@ -1036,7 +1170,8 @@ versions() ->
 
 
 %%---------------------------------------------------------------
--spec renegotiate(#sslsocket{}) -> ok | {error, reason()}.
+-spec renegotiate(SslSocket) -> ok | {error, reason()} when
+      SslSocket :: sslsocket().
 %%
 %% Description: Initiates a renegotiation.
 %%--------------------------------------------------------------------
@@ -1056,9 +1191,13 @@ renegotiate(#sslsocket{pid = {Listen,_}}) when is_port(Listen) ->
     {error, enotconn}.
 
 %%--------------------------------------------------------------------
--spec prf(#sslsocket{}, binary() | 'master_secret', binary(),
-	  [binary() | prf_random()], non_neg_integer()) ->
-		 {ok, binary()} | {error, reason()}.
+-spec prf(SslSocket, Secret, Label, Seed, WantedLength) ->
+                 {ok, binary()} | {error, reason()} when
+      SslSocket :: sslsocket(),
+      Secret :: binary() | 'master_secret',
+      Label::binary(),
+      Seed :: [binary() | prf_random()],
+      WantedLength :: non_neg_integer().
 %%
 %% Description: use a ssl sessions TLS PRF to generate key material
 %%--------------------------------------------------------------------
@@ -1079,7 +1218,8 @@ clear_pem_cache() ->
     ssl_pem_cache:clear().
 
 %%---------------------------------------------------------------
--spec format_error({error, term()}) -> list().
+-spec format_error({error, Reason}) -> string() when
+      Reason :: any().
 %%
 %% Description: Creates error string.
 %%--------------------------------------------------------------------
@@ -1119,7 +1259,14 @@ tls_version({254, _} = Version) ->
 
 
 %%--------------------------------------------------------------------
--spec suite_to_str(erl_cipher_suite()) -> string().
+-spec suite_to_str(CipherSuite) -> string() when
+      CipherSuite :: erl_cipher_suite();
+                  (CipherSuite) -> string() when
+      %% For internal use!
+      CipherSuite :: #{key_exchange := null,
+                       cipher := null,
+                       mac := null,
+                       prf := null}.
 %%
 %% Description: Return the string representation of a cipher suite.
 %%--------------------------------------------------------------------
diff --git a/lib/ssl/src/ssl_connection.erl b/lib/ssl/src/ssl_connection.erl
index ad81288f64..fbbe0a49c8 100644
--- a/lib/ssl/src/ssl_connection.erl
+++ b/lib/ssl/src/ssl_connection.erl
@@ -114,7 +114,7 @@ handshake(Connection, Port, Socket, Opts, User, CbInfo, Timeout) ->
 
 %%--------------------------------------------------------------------
 -spec handshake(#sslsocket{}, timeout()) ->  {ok, #sslsocket{}} |
-                                                 {ok,  #sslsocket{}, map()}| {error, reason()}.
+                                             {ok,  #sslsocket{}, map()}| {error, reason()}.
 %%
 %% Description: Starts ssl handshake. 
 %%--------------------------------------------------------------------
@@ -129,8 +129,8 @@ handshake(#sslsocket{pid = [Pid|_]} = Socket, Timeout) ->
     end.
 
 %%--------------------------------------------------------------------
--spec handshake(#sslsocket{}, {#ssl_options{},#socket_options{}},
-		timeout()) ->   {ok, #sslsocket{}} | {error, reason()}.
+-spec handshake(#sslsocket{}, {#ssl_options{},#socket_options{}}, timeout()) ->
+                       {ok, #sslsocket{}} | {ok, #sslsocket{}, map()} | {error, reason()}.
 %%
 %% Description: Starts ssl handshake with some new options 
 %%--------------------------------------------------------------------
diff --git a/lib/ssl/src/ssl_handshake.erl b/lib/ssl/src/ssl_handshake.erl
index 9ba62b3a12..29db1b07c4 100644
--- a/lib/ssl/src/ssl_handshake.erl
+++ b/lib/ssl/src/ssl_handshake.erl
@@ -92,8 +92,8 @@ hello_request() ->
     #hello_request{}.
 
 %%--------------------------------------------------------------------
--spec server_hello(#session{}, ssl_record:ssl_version(), ssl_record:connection_states(),
-		   #hello_extensions{}) -> #server_hello{}.
+-spec server_hello(binary(), ssl_record:ssl_version(), ssl_record:connection_states(),
+		   Extension::map()) -> #server_hello{}.
 %%
 %% Description: Creates a server hello message.
 %%--------------------------------------------------------------------
diff --git a/lib/ssl/src/ssl_internal.hrl b/lib/ssl/src/ssl_internal.hrl
index 57c72aa122..ddd7a8eb7b 100644
--- a/lib/ssl/src/ssl_internal.hrl
+++ b/lib/ssl/src/ssl_internal.hrl
@@ -27,12 +27,12 @@
 
 -define(SECRET_PRINTOUT, "***").
 
--type reason()            :: term().
--type reply()             :: term().
--type msg()               :: term().
--type from()              :: term().
+-type reason()            :: any().
+-type reply()             :: any().
+-type msg()               :: any().
+-type from()              :: any().
 -type certdb_ref()        :: reference().
--type db_handle()         :: term().
+-type db_handle()         :: any().
 -type der_cert()          :: binary().
 -type issuer()            :: tuple().
 -type serialnumber()      :: integer().
@@ -82,25 +82,26 @@
 -define('24H_in_sec', 86400).
 
 -record(ssl_options, {
-	  protocol    :: tls | dtls,
-	  versions    :: [ssl_record:ssl_version()], %% ssl_record:atom_version() in API
-	  verify      :: verify_none | verify_peer,
+	  protocol    :: tls | dtls | 'undefined',
+	  versions    :: [ssl_record:ssl_version()] | 'undefined', %% ssl_record:atom_version() in API
+	  verify      :: verify_none | verify_peer | 'undefined',
 	  verify_fun,  %%:: fun(CertVerifyErrors::term()) -> boolean(),
-	  partial_chain       :: fun(),
-	  fail_if_no_peer_cert ::  boolean(),
-	  verify_client_once   ::  boolean(),
+	  partial_chain       :: fun() | 'undefined',
+	  fail_if_no_peer_cert ::  boolean() | 'undefined',
+	  verify_client_once   ::  boolean() | 'undefined',
 	  %% fun(Extensions, State, Verify, AccError) ->  {Extensions, State, AccError}
 	  validate_extensions_fun, 
-	  depth                :: integer(),
-	  certfile             :: binary(),
+	  depth                :: integer() | 'undefined',
+	  certfile             :: binary() | 'undefined',
 	  cert                 :: public_key:der_encoded() | secret_printout() | 'undefined',
-	  keyfile              :: binary(),
-	  key	               :: {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' | 'PrivateKeyInfo', 
-                                   public_key:der_encoded()} | key_map() | secret_printout() | 'undefined',
+	  keyfile              :: binary() | 'undefined',
+	  key	               :: {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' | 'PrivateKeyInfo' | 'undefined',
+                                   public_key:der_encoded()} | map()  %%map() -> ssl:key() how to handle dialyzer?
+                                | secret_printout() | 'undefined',
 	  password	       :: string() | secret_printout() | 'undefined',
 	  cacerts              :: [public_key:der_encoded()] | secret_printout() | 'undefined',
-	  cacertfile           :: binary(),
-	  dh                   :: public_key:der_encoded() | secret_printout(),
+	  cacertfile           :: binary() | 'undefined',
+	  dh                   :: public_key:der_encoded() | secret_printout() | 'undefined',
 	  dhfile               :: binary() | secret_printout() | 'undefined',
 	  user_lookup_fun,  % server option, fun to lookup the user
 	  psk_identity         :: binary() | secret_printout() | 'undefined',
@@ -112,23 +113,23 @@
 	  reuse_session        :: fun() | binary() | undefined, %% Server side is a fun()
 	  %% If false sessions will never be reused, if true they
 	  %% will be reused if possible.
-	  reuse_sessions       :: boolean() | save,  %% Only client side can use value save
+	  reuse_sessions       :: boolean() | save | 'undefined',  %% Only client side can use value save
 	  renegotiate_at,
 	  secure_renegotiate,
 	  client_renegotiation,
 	  %% undefined if not hibernating, or number of ms of
 	  %% inactivity after which ssl_connection will go into
 	  %% hibernation
-	  hibernate_after      :: timeout(),          
+	  hibernate_after      :: timeout() | 'undefined',
 	  %% This option should only be set to true by inet_tls_dist
 	  erl_dist = false     :: boolean(),
-          alpn_advertised_protocols = undefined :: [binary()] | undefined ,
+          alpn_advertised_protocols = undefined :: [binary()] | undefined,
           alpn_preferred_protocols = undefined  :: [binary()] | undefined,
 	  next_protocols_advertised = undefined :: [binary()] | undefined,
 	  next_protocol_selector = undefined,  %% fun([binary()]) -> binary())
 	  log_alert             :: boolean(),
 	  server_name_indication = undefined,
-	  sni_hosts  :: [{inet:hostname(), [tuple()]}],
+	  sni_hosts  :: [{inet:hostname(), [tuple()]}] | 'undefined',
 	  sni_fun :: function() | undefined,
 	  %% Should the server prefer its own cipher order over the one provided by
 	  %% the client?
@@ -138,7 +139,7 @@
 	  %%mitigation entirely?
 	  beast_mitigation = one_n_minus_one :: one_n_minus_one | zero_n | disabled,
 	  fallback = false           :: boolean(),
-	  crl_check                  :: boolean() | peer | best_effort, 
+	  crl_check                  :: boolean() | peer | best_effort | 'undefined',
 	  crl_cache,
 	  signature_algs,
 	  eccs,
@@ -178,9 +179,12 @@
                                   password => crypto:password()
                                  }.
 -type state_name()           :: hello | abbreviated | certify | cipher | connection.
--type gen_fsm_state_return() :: {next_state, state_name(), term()} |
-				{next_state, state_name(), term(), timeout()} |
-				{stop, term(), term()}.
+
+-type gen_fsm_state_return() :: {next_state, state_name(), any()} |
+				{next_state, state_name(), any(), timeout()} |
+				{stop, any(), any()}.
+-type ssl_options()          :: #ssl_options{}.
+
 -endif. % -ifdef(ssl_internal).
 
 
diff --git a/lib/ssl/src/tls_connection.erl b/lib/ssl/src/tls_connection.erl
index 114710a92e..167a99b418 100644
--- a/lib/ssl/src/tls_connection.erl
+++ b/lib/ssl/src/tls_connection.erl
@@ -760,7 +760,7 @@ downgrade(Type, Event, State) ->
 callback_mode() ->
     state_functions.
 
-terminate({shutdown, sender_died, Reason}, _StateName,
+terminate({shutdown, {sender_died, Reason}}, _StateName,
           #state{static_env = #static_env{socket = Socket, 
                                           transport_cb = Transport}} 
           = State) ->
@@ -939,7 +939,7 @@ handle_info({CloseTag, Socket}, StateName,
     end;
 handle_info({'EXIT', Sender, Reason}, _,
             #state{protocol_specific = #{sender := Sender}} = State) ->
-    {stop, {shutdown, sender_died, Reason}, State};
+    {stop, {shutdown, {sender_died, Reason}}, State};
 handle_info(Msg, StateName, State) ->
     ssl_connection:StateName(info, Msg, State, ?MODULE).
 
diff --git a/lib/ssl/src/tls_handshake.erl b/lib/ssl/src/tls_handshake.erl
index 0f0de5936a..c2b0d8e039 100644
--- a/lib/ssl/src/tls_handshake.erl
+++ b/lib/ssl/src/tls_handshake.erl
@@ -157,7 +157,7 @@ encode_handshake(Package, Version) ->
 %%--------------------------------------------------------------------
 -spec get_tls_handshake(tls_record:tls_version(), binary(), binary() | iolist(), 
                         #ssl_options{}) ->
-     {[tls_handshake()], binary()}.
+     {[{tls_handshake(), binary()}], binary()}.
 %%
 %% Description: Given buffered and new data from ssl_record, collects
 %% and returns it as a list of handshake messages, also returns leftover