ssl: Enhance documentation after "use-spec-rewrite"

6 files changed, 235 insertions, 237 deletions

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 21ea1be4b4..67ec93809f 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -55,7 +55,7 @@
     <datatype>
       <name name="sslsocket"/>
       <desc>
-	<p>An opaque reference to the TLS/DTLS connection.</p>
+	<p>An opaque reference to the TLS/DTLS connection, may be used for equality matching.</p>
 	</desc>
     </datatype>
 
@@ -87,14 +87,6 @@
     </datatype>
 
     <datatype>
-      <name name="socket_connect_option"/>
-    </datatype>
-    
-     <datatype>
-      <name name="socket_listen_option"/>
-    </datatype>
-
-    <datatype>
       <name name="active_msgs"/>
       <desc>
       <p>When an TLS/DTLS socket is in active mode (the default), data from the
@@ -119,11 +111,7 @@
 	</p>
       </desc>
     </datatype>
-   
-      <datatype>
-      <name name="path"/>
-     </datatype>
-
+  
      <datatype>
       <name name="host"/>
      </datatype>
@@ -147,12 +135,14 @@
      <datatype>
        <name name="dtls_version"/>
      </datatype>
-
-
-   <datatype>
+     
+     <datatype>
        <name name="legacy_version"/>
      </datatype>
      
+       <datatype>
+       <name name="prf_random"/>
+     </datatype>
      
       <datatype>
        <name name="verify_type"/>
@@ -190,7 +180,10 @@
        <name name="legacy_hash"/>
      </datatype>
 
-  
+    <datatype>
+       <name name="old_cipher_suite"/>
+     </datatype>
+     
      <datatype>
       <name name="signature_algs"/>
      </datatype>
@@ -200,7 +193,7 @@
      </datatype>
 
      <datatype>
-      <name name="key_algo"/>
+      <name name="kex_algo"/>
      </datatype>
 
      <datatype>
@@ -232,6 +225,10 @@
      </datatype>
 
      <datatype>
+      <name name="protocol_extensions"/>
+     </datatype>
+
+     <datatype>
       <name name="error_alert"/>
      </datatype>
 
@@ -366,8 +363,8 @@
 	<p>The verification fun is to be defined as follows:</p>
 
 	<code>
-fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revoked,
-atom()}} |
+fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() |
+             {revoked, atom()}} |
 	     {extension, #'Extension'{}}, InitialUserState :: term()) ->
 	{valid, UserState :: term()} | {valid_peer, UserState :: term()} |
 	{fail, Reason :: term()} | {unknown, UserState :: term()}.
@@ -580,7 +577,8 @@ fun(Chain::[public_key:der_encoded()]) ->
 fun(psk, PSKIdentity ::string(), UserState :: term()) ->
 	{ok, SharedSecret :: binary()} | error;
 fun(srp, Username :: string(), UserState :: term()) ->
-	{ok, {SRPParams :: srp_param_type(), Salt :: binary(), DerivedKey :: binary()}} | error.
+	{ok, {SRPParams :: srp_param_type(), Salt :: binary(),
+	      DerivedKey :: binary()}} | error.
 	</code>
 
 	<p>For Pre-Shared Key (PSK) cipher suites, the lookup fun is
@@ -658,7 +656,11 @@ fun(srp, Username :: string(), UserState :: term()) ->
       </desc>
     </datatype>
     
-
+    <datatype>
+      <name name="ssl_imp"/>
+        <desc><p>Deprecated since OTP-17, has no affect.</p></desc>
+    </datatype>
+    
     <datatype_title>TLS/DTLS OPTION DESCRIPTIONS - CLIENT</datatype_title>
     
     <datatype>
@@ -1079,7 +1081,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
     
     <func>
       <name since="OTP R14B">cipher_suites() -></name>
-      <name since="OTP R14B">cipher_suites(Type) -> old_ciphers()</name>
+      <name since="OTP R14B">cipher_suites(Type) -> [old_cipher_suite()]</name>
       <fsummary>Returns a list of supported cipher suites.</fsummary>
       <type>
         <v>Type = erlang | openssl | all</v>
@@ -1140,10 +1142,10 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	equivalent, connected socket to an TLS socket.</fsummary>
       <type>
 	<v>Socket = <seealso marker="#type-socket"> socket() </seealso></v>
-	<v>Options = <seealso marker="#type-client_option"> [client_option()] </seealso></v>
+	<v>Options = <seealso marker="#type-tls_client_option"> [tls_client_option()] </seealso></v>
 	<v>Timeout = timeout()</v>
 	<v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
-	<v>Ext = hello_extensions()</v>
+	<v>Ext = <seealso marker="#type-protocol_extensions">protocol_extensions()</seealso></v>
 	<v>Reason = closed | timeout | <seealso marker="#type-error_alert"> error_alert() </seealso></v>
       </type>
       <desc><p>Upgrades a <c>gen_tcp</c>, or equivalent,
@@ -1184,7 +1186,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <type>
 	  <v>Host =<seealso marker="#type-host"> host() </seealso> </v>
 	  <v>Port = <seealso marker="kernel:inet#type-port_number">inet:port_number()</seealso></v>
-	  <v>Options = <seealso marker="#type-client_option"> [client_option()]</seealso></v>
+	  <v>Options = <seealso marker="#type-tls_client_option"> [tls_client_option()]</seealso></v>
 	  <v>Timeout = timeout()</v>
 	  <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
 	  <v>Reason = closed | timeout | <seealso marker="#type-error_alert"> error_alert() </seealso></v>
@@ -1393,8 +1395,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <type>
         <v>Socket = socket() |  <seealso marker="#type-sslsocket"> socket() </seealso> </v>
 	<v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso> </v>
-	<v>Ext = hello_extensions()</v>
-	<v>Options = <seealso marker="#type-server_option"> [server_option()] </seealso>  </v>
+	<v>Ext =  <seealso marker="#type-protocol_extensions">protocol_extensions()</seealso></v>
+	<v>Options = <seealso marker="#type-tls_server_option"> [server_option()] </seealso>  </v>
         <v>Timeout = timeout()</v>
         <v>Reason = closed | timeout | <seealso marker="#type-error_alert"> error_alert() </seealso></v>
       </type>
@@ -1464,7 +1466,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <fsummary>Creates an SSL listen socket.</fsummary>
       <type>
 	<v>Port = <seealso marker="kernel:inet#type-port_number">inet:port_number()</seealso></v>
-	<v>Options = <seealso marker="#type-server_option"> [server_option()] </seealso></v>
+	<v>Options = <seealso marker="#type-tls_server_option"> [server_option()] </seealso></v>
 	<v>ListenSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
       </type>
       <desc>
@@ -1539,7 +1541,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	<v>Socket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
 	<v>Secret = binary() | master_secret</v>
 	<v>Label = binary()</v>
-	<v>Seed = [binary() | prf_random()]</v>
+	<v>Seed = [binary() | <seealso marker="#type-prf_random"> prf_random()</seealso>]</v>
 	<v>WantedLength = non_neg_integer()</v>
       </type>
       <desc>
@@ -1658,7 +1660,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <fsummary>Performs server-side SSL/TLS/DTLS handshake.</fsummary>
       <type>
         <v>Socket = socket() |  <seealso marker="#type-sslsocket"> sslsocket() </seealso> </v>
-	<v>Options =  <seealso marker="#type-server_option"> [server_option()] </seealso> </v>
+	<v>Options =  <seealso marker="#type-tls_server_option"> [server_option()] </seealso> </v>
         <v>Timeout = timeout()</v>
         <v>Reason = closed | timeout | <seealso marker="#type-error_alert"> error_alert() </seealso></v>
       </type>
diff --git a/lib/ssl/src/ssl.erl b/lib/ssl/src/ssl.erl
index c39a6f1603..3a8a068d5a 100644
--- a/lib/ssl/src/ssl.erl
+++ b/lib/ssl/src/ssl.erl
@@ -64,159 +64,153 @@
 -export_type([socket/0,
               sslsocket/0,
               socket_option/0,
-              tls_client_option/0,
-              tls_option/0,
-              tls_server_option/0,
               active_msgs/0,
-              erl_cipher_suite/0,
-              protocol_version/0,
-              dtls_version/0,
-              tls_version/0,
-              prf_random/0, 
-              hello_extensions/0,
-              error_alert/0,
-              session_id/0, 
-              path/0, 
-              hostname/0,
               host/0,
-              prf/0, 
-              srp_param_type/0,
-              cipher_filters/0,
-              ssl_imp/0,
-              private_key_type/0,
+              tls_option/0,              
+              tls_client_option/0,
+              tls_server_option/0,                            
+              erl_cipher_suite/0,
+              old_cipher_suite/0,
+              ciphers/0,             
               cipher/0,
               hash/0,
-              key_algo/0,
-              sign_algo/0
-             ]).
+              kex_algo/0,
+              prf_random/0, 
+              cipher_filters/0,
+              sign_algo/0,
+              protocol_version/0,
+              protocol_extensions/0,
+              session_id/0,
+              error_alert/0,
+              srp_param_type/0]).
+
 %% -------------------------------------------------------------------------------------------------------
 -type socket()                   :: gen_tcp:socket().
--type socket_option()    ::  socket_connect_option() | socket_listen_option(). 
--type socket_connect_option()    :: gen_tcp:connect_option() | gen_udp:option().
--type socket_listen_option()     :: gen_tcp:listen_option() | gen_udp:option().
--opaque sslsocket()              :: #sslsocket{}.
--type tls_option()                :: tls_client_option() | tls_server_option().
--type tls_client_option()            :: client_option() | socket_connect_option() |  transport_option().
--type tls_server_option()            :: server_option() | socket_listen_option() | transport_option().
--type active_msgs()  :: {ssl, sslsocket(), Data::binary() | list()} | {ssl_closed, sslsocket()} |
-                        {ssl_error, sslsocket(), Reason::term()}.
--type transport_option() :: {cb_info, {CallbackModule::atom(), DataTag::atom(),
+-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 active_msgs()              :: {ssl, sslsocket(), Data::binary() | list()} | {ssl_closed, sslsocket()} |
+                                    {ssl_error, sslsocket(), Reason::term()}.
+-type transport_option()         :: {cb_info, {CallbackModule::atom(), DataTag::atom(),
 				       ClosedTag::atom(), ErrTag::atom()}}.
--type path()         :: file:filename().
--type host()         :: hostname() | ip_address().
--type hostname()     :: string().
--type ip_address()   :: inet:ip_address().
--type session_id()   :: binary().
--type protocol_version() :: tls_version() | dtls_version().
--type tls_version()  :: tlsv1 | 'tlsv1.1' | 'tlsv1.2' | 'tlsv1.3' | legacy_version().
--type dtls_version() :: 'dtlsv1' | 'dtlsv1.2'.
--type legacy_version() :: sslv3.
--type verify_type()  :: verify_none | verify_peer.
--type cipher()            :: aes_128_cbc |
-                             aes_256_cbc |
-                             aes_128_gcm |
-                             aes_256_gcm |
-                             chacha20_poly1305 |
-                             legacy_cipher().
--type legacy_cipher()     ::  rc4_128 |
-                              des_cbc |
-                             '3des_ede_cbc'.
-
--type hash()              :: sha |
-                             sha2() |
-                             legacy_hash().
-
--type sha2()              ::  sha224 |
-                              sha256 |
-                              sha384 |
-                              sha512.
-
--type legacy_hash()        :: md5.
-
--type sign_algo()         :: rsa | dsa | ecdsa.
--type key_algo()          :: rsa |
-                             dhe_rsa | dhe_dss |
-                             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
--type prf()               :: hash() | default_prf.
--type erl_cipher_suite()  :: #{key_exchange := key_algo(),
-                               cipher := cipher(),
-                               mac    := hash() | aead,
-                               prf    := hash() | default_prf %% Old cipher suites, version dependent
-                              }.  
-
--type named_curve()       :: sect571r1 |
-                             sect571k1 |
-                             secp521r1 |
-                             brainpoolP512r1 |
-                             sect409k1 |
-                             sect409r1 |
-                             brainpoolP384r1 |
-                             secp384r1 |
-                             sect283k1 |
-                             sect283r1 |
-                             brainpoolP256r1 |
-                             secp256k1 |
-                             secp256r1 |
-                             sect239k1 |
-                             sect233k1 |
-                             sect233r1 |
-                             secp224k1 |
-                             secp224r1 |
-                             sect193r1 |
-                             sect193r2 |
-                             secp192k1 |
-                             secp192r1 |
-                             sect163k1 |
-                             sect163r1 |
-                             sect163r2 |
-                             secp160k1 |
-                             secp160r1 |
-                             secp160r2.
-
--type srp_param_type()    :: srp_1024 |
-                             srp_1536 |
-                             srp_2048 |
-                             srp_3072 |
-                             srp_4096 |
-                             srp_6144 |
-                             srp_8192.
-
--type error_alert() :: {tls_alert, {tls_alert(), Description::string()}}.
-
--type tls_alert() :: 
-        close_notify | 
-        unexpected_message | 
-        bad_record_mac | 
-        record_overflow | 
-        handshake_failure |
-        bad_certificate | 
-        unsupported_certificate | 
-        certificate_revoked | 
-        certificate_expired | 
-        certificate_unknown |
-        illegal_parameter | 
-        unknown_ca | 
-        access_denied | 
-        decode_error | 
-        decrypt_error | 
-        export_restriction| 
-        protocol_version |
-        insufficient_security |
-        internal_error |
-        inappropriate_fallback |
-        user_canceled |
-        no_renegotiation |
-        unsupported_extension |
-        certificate_unobtainable |
-        unrecognized_name |
-        bad_certificate_status_response |
-        bad_certificate_hash_value |
-        unknown_psk_identity |
-        no_application_protocol.
+-type host()                     :: hostname() | ip_address().
+-type hostname()                 :: string().
+-type ip_address()               :: inet:ip_address().
+-type session_id()               :: binary().
+-type protocol_version()         :: tls_version() | dtls_version().
+-type tls_version()              :: tlsv1 | 'tlsv1.1' | 'tlsv1.2' | 'tlsv1.3' | legacy_version().
+-type dtls_version()             :: 'dtlsv1' | 'dtlsv1.2'.
+-type legacy_version()           :: sslv3.
+-type verify_type()              :: verify_none | verify_peer.
+-type cipher()                   :: aes_128_cbc |
+                                    aes_256_cbc |
+                                    aes_128_gcm |
+                                    aes_256_gcm |
+                                    chacha20_poly1305 |
+                                    legacy_cipher().
+-type legacy_cipher()            ::  rc4_128 |
+                                     des_cbc |
+                                     '3des_ede_cbc'.
+
+-type hash()                     :: sha |
+                                    sha2() |
+                                    legacy_hash().
+
+-type sha2()                    ::  sha224 |
+                                    sha256 |
+                                    sha384 |
+                                    sha512.
+
+-type legacy_hash()             :: md5.
+
+-type sign_algo()               :: rsa | dsa | ecdsa.
+-type kex_algo()                :: rsa |
+                                   dhe_rsa | dhe_dss |
+                                   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
+-type erl_cipher_suite()       :: #{key_exchange := kex_algo(),
+                                    cipher := cipher(),
+                                    mac    := hash() | aead,
+                                    prf    := hash() | default_prf %% Old cipher suites, version dependent
+                                   }.  
+
+-type old_cipher_suite() :: {kex_algo(), cipher(), hash()} % Pre TLS 1.2 
+                             %% TLS 1.2, internally PRE TLS 1.2 will use default_prf
+                           | {kex_algo(), cipher(), hash() | aead, hash()}. 
+
+-type named_curve()           :: sect571r1 |
+                                 sect571k1 |
+                                 secp521r1 |
+                                 brainpoolP512r1 |
+                                 sect409k1 |
+                                 sect409r1 |
+                                 brainpoolP384r1 |
+                                 secp384r1 |
+                                 sect283k1 |
+                                 sect283r1 |
+                                 brainpoolP256r1 |
+                                 secp256k1 |
+                                 secp256r1 |
+                                 sect239k1 |
+                                 sect233k1 |
+                                 sect233r1 |
+                                 secp224k1 |
+                                 secp224r1 |
+                                 sect193r1 |
+                                 sect193r2 |
+                                 secp192k1 |
+                                 secp192r1 |
+                                 sect163k1 |
+                                 sect163r1 |
+                                 sect163r2 |
+                                 secp160k1 |
+                                 secp160r1 |
+                                 secp160r2.
+
+-type srp_param_type()        :: srp_1024 |
+                                 srp_1536 |
+                                 srp_2048 |
+                                 srp_3072 |
+                                 srp_4096 |
+                                 srp_6144 |
+                                 srp_8192.
+
+-type error_alert()           :: {tls_alert, {tls_alert(), Description::string()}}.
+
+-type tls_alert()             :: close_notify | 
+                                 unexpected_message | 
+                                 bad_record_mac | 
+                                 record_overflow | 
+                                 handshake_failure |
+                                 bad_certificate | 
+                                 unsupported_certificate | 
+                                 certificate_revoked | 
+                                 certificate_expired | 
+                                 certificate_unknown |
+                                 illegal_parameter | 
+                                 unknown_ca | 
+                                 access_denied | 
+                                 decode_error | 
+                                 decrypt_error | 
+                                 export_restriction| 
+                                 protocol_version |
+                                 insufficient_security |
+                                 internal_error |
+                                 inappropriate_fallback |
+                                 user_canceled |
+                                 no_renegotiation |
+                                 unsupported_extension |
+                                 certificate_unobtainable |
+                                 unrecognized_name |
+                                 bad_certificate_status_response |
+                                 bad_certificate_hash_value |
+                                 unknown_psk_identity |
+                                 no_application_protocol.
 %% -------------------------------------------------------------------------------------------------------
 -type common_option()        :: {protocol, protocol()} |
                                 {handshake, handshake_completion()} |
@@ -239,43 +233,44 @@
                                 {log_alert, log_alert()} |
                                 {hibernate_after, hibernate_after()} |
                                 {padding_check, padding_check()} |
-                                {beast_mitigation, beast_mitigation()}. 
-
--type protocol()                 :: tls | dtls.
--type handshake_completion()     ::  hello | full.
--type cert()                     :: public_key:der_encoded().
--type cert_pem()                 :: ssl:path().
--type key()                      :: {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'PrivateKeyInfo', 
+                                {beast_mitigation, beast_mitigation()} |
+                                {ssl_imp, ssl_imp()}.
+
+-type protocol()                  :: tls | dtls.
+-type handshake_completion()      :: hello | full.
+-type cert()                      :: public_key:der_encoded().
+-type cert_pem()                  :: file:filename().
+-type key()                       :: {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'PrivateKeyInfo', 
                                            public_key:der_encoded()} | 
                                      #{algorithm := rsa | dss | ecdsa, 
                                        engine := crypto:engine_ref(), 
                                        key_id := crypto:key_id(), 
                                        password => crypto:password()}.
--type key_pem()                  :: ssl:path().
--type key_password()                 :: string().
--type cipher_suites() :: ciphers().    
--type ciphers()      :: [erl_cipher_suite()] |
-			string(). % (according to old API)
--type cipher_filters()    :: list({key_exchange | cipher | mac | prf,
-                                   algo_filter()}).
--type algo_filter()       :: fun((key_algo()|cipher()|hash()|aead|default_prf) -> true | false).
--type eccs()                     :: [named_curve()].  
--type secure_renegotiation()     :: boolean(). 
+-type key_pem()                   :: file:filename().
+-type key_password()              :: string().
+-type cipher_suites()             :: ciphers().    
+-type ciphers()                   :: [erl_cipher_suite()] |
+                                     string(). % (according to old API)
+-type cipher_filters()            :: list({key_exchange | cipher | mac | prf,
+                                        algo_filter()}).
+-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()}.
--type crl_check()                :: boolean() | peer | best_effort.
--type crl_cache_opts()           :: [term()].
--type handshake_size()           :: integer().
--type hibernate_after()          :: timeout().
--type root_fun()                 ::  fun().
--type protocol_versions()        ::  [protocol_version()].
--type signature_algs()           ::  [{hash(), sign_algo()}].
--type custom_user_lookup()       ::  {Lookupfun :: fun(), UserState :: term()}.
--type padding_check()            :: boolean(). 
--type beast_mitigation()         :: one_n_minus_one | zero_n | disabled.
--type srp_identity()             :: {Username :: string(), Password :: string()}.
--type psk_identity()             :: string().
--type log_alert()                :: boolean().
+-type custom_verify()             ::  {Verifyfun :: fun(), InitialUserState :: term()}.
+-type crl_check()                 :: boolean() | peer | best_effort.
+-type crl_cache_opts()            :: [term()].
+-type handshake_size()            :: integer().
+-type hibernate_after()           :: timeout().
+-type root_fun()                  ::  fun().
+-type protocol_versions()         ::  [protocol_version()].
+-type signature_algs()            ::  [{hash(), sign_algo()}].
+-type custom_user_lookup()        ::  {Lookupfun :: fun(), UserState :: term()}.
+-type padding_check()             :: boolean(). 
+-type beast_mitigation()          :: one_n_minus_one | zero_n | disabled.
+-type srp_identity()              :: {Username :: string(), Password :: string()}.
+-type psk_identity()              :: string().
+-type log_alert()                 :: boolean().
 
 %% -------------------------------------------------------------------------------------------------------
 
@@ -294,10 +289,10 @@
                                 {fallback, fallback()}.
 
 -type client_verify_type()       :: verify_type().
--type client_reuse_session()     :: ssl:session_id().
+-type client_reuse_session()     :: session_id().
 -type client_reuse_sessions()    :: boolean() | save.
 -type client_cacerts()           :: [public_key:der_encoded()].
--type client_cafile()            :: ssl:path().
+-type client_cafile()            :: file:filename().
 -type app_level_protocol()       :: binary().
 -type client_alpn()              :: [app_level_protocol()].
 -type client_preferred_next_protocols() :: {Precedence :: server | client, 
@@ -308,9 +303,10 @@
 -type client_psk_identity()             :: psk_identity().
 -type client_srp_identity()             :: srp_identity().
 -type customize_hostname_check() :: list().
--type sni()                      :: HostName :: ssl:hostname() | disable. 
+-type sni()                      :: HostName :: hostname() | disable. 
 -type client_signature_algs()    :: signature_algs().
 -type fallback()                 :: boolean().
+-type ssl_imp()                  :: new | old.
 
 %% -------------------------------------------------------------------------------------------------------
 
@@ -334,38 +330,38 @@
                                 {signature_algs, server_signature_algs()}.
 
 -type server_cacerts()           :: [public_key:der_encoded()].
--type server_cafile()            :: ssl:path().
+-type server_cafile()            :: file:filename().
 -type server_alpn()              :: [app_level_protocol()].
 -type server_next_protocol()     :: [app_level_protocol()].
 -type server_psk_identity()      :: psk_identity().
 -type dh_der()                   :: binary().
--type dh_file()                  :: ssl:path().
+-type dh_file()                  :: file:filename().
 -type server_verify_type()       :: verify_type().
 -type fail_if_no_peer_cert()     :: boolean().
 -type server_signature_algs()    :: signature_algs().
 -type server_reuse_session()     :: fun().
 -type server_reuse_sessions()    :: boolean().
--type sni_hosts()                :: [{ssl:hostname(), [server_option() | common_option()]}].
+-type sni_hosts()                :: [{hostname(), [server_option() | common_option()]}].
 -type sni_fun()                  :: fun().
 -type honor_cipher_order()       :: boolean().
 -type honor_ecc_order()          :: boolean().
 -type client_renegotiation()     :: boolean().
 %% -------------------------------------------------------------------------------------------------------
-
--type ssl_imp()      :: new | old.
-
-
 -type prf_random() :: client_random | server_random.
+-type protocol_extensions()  :: #{renegotiation_info => binary(),
+                                  signature_algs => signature_algs(),
+                                  alpn =>  app_level_protocol(),
+                                  srp  => binary(),
+                                  next_protocol => app_level_protocol(),
+                                  ec_point_formats  => [0..2],
+                                  elliptic_curves => [public_key:oid()],
+                                  sni => hostname()}.
+%% -------------------------------------------------------------------------------------------------------
 
--type private_key_type() :: rsa | %% Backwards compatibility
-                            dsa | %% Backwards compatibility
-                            'RSAPrivateKey' |
-                            'DSAPrivateKey' |
-                            'ECPrivateKey' |
-                            'PrivateKeyInfo'.
+%%%--------------------------------------------------------------------
+%%% API
+%%%--------------------------------------------------------------------
 
--type hello_extensions()  :: #{signature_algs => sign_algo()}. %% TODO
-%% -------------------------------------------------------------------------------------------------------
 %%--------------------------------------------------------------------
 %%
 %% Description: Utility function that starts the ssl and applications
@@ -745,13 +741,13 @@ negotiated_protocol(#sslsocket{pid = [Pid|_]}) when is_pid(Pid) ->
     ssl_connection:negotiated_protocol(Pid).
 
 %%--------------------------------------------------------------------
--spec cipher_suites() -> [ssl_cipher_format:old_erl_cipher_suite()] | [string()].
+-spec cipher_suites() -> [old_cipher_suite()] | [string()].
 %%--------------------------------------------------------------------
 cipher_suites() ->
     cipher_suites(erlang).
 %%--------------------------------------------------------------------
 -spec cipher_suites(erlang | openssl | all) -> 
-                           [ssl_cipher_format:old_erl_cipher_suite() | string()].
+                           [old_cipher_suite() | string()].
 %% Description: Returns all supported cipher suites.
 %%--------------------------------------------------------------------
 cipher_suites(erlang) ->
diff --git a/lib/ssl/src/ssl_cipher_format.erl b/lib/ssl/src/ssl_cipher_format.erl
index f7af96583f..1d28e1e3b4 100644
--- a/lib/ssl/src/ssl_cipher_format.erl
+++ b/lib/ssl/src/ssl_cipher_format.erl
@@ -34,15 +34,15 @@
 
 -type internal_cipher()            :: null | ssl:cipher().
 -type internal_hash()              :: null | ssl:hash().
--type internal_key_algo()          :: null | ssl:key_algo().
--type internal_erl_cipher_suite()  :: #{key_exchange := internal_key_algo(),
+-type internal_kex_algo()          :: null | ssl:kex_algo().
+-type internal_erl_cipher_suite()  :: #{key_exchange := internal_kex_algo(),
                                cipher := internal_cipher(),
                                mac    := internal_hash() | aead,
                                prf    := internal_hash() | default_prf %% Old cipher suites, version dependent
                               }.  
--type old_erl_cipher_suite() :: {ssl:key_algo(), internal_cipher(), internal_hash()} % Pre TLS 1.2 
+-type old_erl_cipher_suite() :: {ssl:kex_algo(), internal_cipher(), internal_hash()} % Pre TLS 1.2 
                                 %% TLS 1.2, internally PRE TLS 1.2 will use default_prf
-                              | {ssl:key_algo(), internal_cipher(), internal_hash(), 
+                              | {ssl:kex_algo(), internal_cipher(), internal_hash(), 
                                  internal_hash() | default_prf}. 
 -type cipher_suite()      :: binary().
 -type openssl_cipher_suite()  :: string().
diff --git a/lib/ssl/src/ssl_connection.hrl b/lib/ssl/src/ssl_connection.hrl
index 83013e7fba..7bf90fdb2d 100644
--- a/lib/ssl/src/ssl_connection.hrl
+++ b/lib/ssl/src/ssl_connection.hrl
@@ -69,7 +69,7 @@
                         hashsign_algorithm = {undefined, undefined},
                         cert_hashsign_algorithm = {undefined, undefined},
                         %% key exchange
-                        kex_algorithm         :: ssl:key_algo(),  
+                        kex_algorithm         :: ssl:kex_algo(),  
                         kex_keys  :: {PublicKey :: binary(), PrivateKey :: binary()} | #'ECPrivateKey'{} |  undefined |  secret_printout(),        
                         diffie_hellman_params:: #'DHParameter'{} | undefined | secret_printout(),
                         srp_params           :: #srp_user{} | secret_printout() | 'undefined',
diff --git a/lib/ssl/src/ssl_handshake.erl b/lib/ssl/src/ssl_handshake.erl
index 27c071d6dd..9ba62b3a12 100644
--- a/lib/ssl/src/ssl_handshake.erl
+++ b/lib/ssl/src/ssl_handshake.erl
@@ -729,7 +729,7 @@ decode_hello_extensions(Extensions) ->
     dec_hello_extensions(Extensions, #hello_extensions{}).
 
 %%--------------------------------------------------------------------
--spec decode_server_key(binary(), ssl:key_algo(), ssl_record:ssl_version()) ->
+-spec decode_server_key(binary(), ssl:kex_algo(), ssl_record:ssl_version()) ->
 			       #server_key_params{}.
 %%
 %% Description: Decode server_key data and return appropriate type
@@ -738,7 +738,7 @@ decode_server_key(ServerKey, Type, Version) ->
     dec_server_key(ServerKey, key_exchange_alg(Type), Version).
 
 %%--------------------------------------------------------------------
--spec decode_client_key(binary(), ssl:key_algo(), ssl_record:ssl_version()) ->
+-spec decode_client_key(binary(), ssl:kex_algo(), ssl_record:ssl_version()) ->
 			    #encrypted_premaster_secret{}
 			    | #client_diffie_hellman_public{}
 			    | #client_ec_diffie_hellman_public{}
diff --git a/lib/ssl/src/tls_handshake.erl b/lib/ssl/src/tls_handshake.erl
index fbb81f56fe..0f0de5936a 100644
--- a/lib/ssl/src/tls_handshake.erl
+++ b/lib/ssl/src/tls_handshake.erl
@@ -82,7 +82,7 @@ client_hello(Host, Port, ConnectionStates,
 -spec hello(#server_hello{} | #client_hello{}, #ssl_options{},
 	    ssl_record:connection_states() | {inet:port_number(), #session{}, db_handle(),
 				    atom(), ssl_record:connection_states(), 
-				    binary() | undefined, ssl:key_algo()},
+				    binary() | undefined, ssl:kex_algo()},
 	    boolean()) ->
 		   {tls_record:tls_version(), ssl:session_id(), 
 		    ssl_record:connection_states(), alpn | npn, binary() | undefined}|