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

1 files changed, 193 insertions, 197 deletions

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) ->