ssl: Use specs to generate type documentation

21 files changed, 466 insertions, 191 deletions

diff --git a/lib/ssl/src/dtls_connection.erl b/lib/ssl/src/dtls_connection.erl
index 855cd0d123..70dae4c677 100644
--- a/lib/ssl/src/dtls_connection.erl
+++ b/lib/ssl/src/dtls_connection.erl
@@ -80,7 +80,7 @@ start_fsm(Role, Host, Port, Socket, {#ssl_options{erl_dist = false},_, Tracker}
     end.
 
 %%--------------------------------------------------------------------
--spec start_link(atom(), host(), inet:port_number(), port(), list(), pid(), tuple()) ->
+-spec start_link(atom(), ssl:host(), inet:port_number(), port(), list(), pid(), tuple()) ->
 			{ok, pid()} | ignore |  {error, reason()}.
 %%
 %% Description: Creates a gen_statem process which calls Module:init/1 to
diff --git a/lib/ssl/src/dtls_handshake.erl b/lib/ssl/src/dtls_handshake.erl
index 1917d51c03..6e9bf99e52 100644
--- a/lib/ssl/src/dtls_handshake.erl
+++ b/lib/ssl/src/dtls_handshake.erl
@@ -46,7 +46,7 @@
 %% Handshake handling
 %%====================================================================
 %%--------------------------------------------------------------------
--spec client_hello(host(), inet:port_number(), ssl_record:connection_states(),
+-spec client_hello(ssl:host(), inet:port_number(), ssl_record:connection_states(),
 		   #ssl_options{}, integer(), atom(), boolean(), der_cert()) ->
 			  #client_hello{}.
 %%
@@ -59,7 +59,7 @@ client_hello(Host, Port, ConnectionStates, SslOpts,
 		 Cache, CacheCb, Renegotiation, OwnCert).
 
 %%--------------------------------------------------------------------
--spec client_hello(host(), inet:port_number(), term(), ssl_record:connection_states(),
+-spec client_hello(ssl:host(), inet:port_number(), term(), ssl_record:connection_states(),
 		   #ssl_options{}, integer(), atom(), boolean(), der_cert()) ->
 			  #client_hello{}.
 %%
@@ -123,7 +123,7 @@ cookie(Key, Address, Port, #client_hello{client_version = {Major, Minor},
 		  Random, SessionId, CipherSuites, CompressionMethods],
     crypto:hmac(sha, Key, CookieData).
 %%--------------------------------------------------------------------
--spec hello_verify_request(binary(),  dtls_record:dtls_version()) -> #hello_verify_request{}.
+-spec hello_verify_request(binary(),  ssl_record:ssl_version()) -> #hello_verify_request{}.
 %%
 %% Description: Creates a hello verify request message sent by server to
 %% verify client
@@ -151,7 +151,7 @@ encode_handshake(Handshake, Version, Seq) ->
 %%--------------------------------------------------------------------
 
 %%--------------------------------------------------------------------
--spec get_dtls_handshake(dtls_record:dtls_version(), binary(), #protocol_buffers{}) ->
+-spec get_dtls_handshake(ssl_record:ssl_version(), binary(), #protocol_buffers{}) ->
                                 {[dtls_handshake()], #protocol_buffers{}}.                
 %%
 %% Description:  Given buffered and new data from dtls_record, collects
diff --git a/lib/ssl/src/dtls_handshake.hrl b/lib/ssl/src/dtls_handshake.hrl
index 50e92027d2..41da8e5c8c 100644
--- a/lib/ssl/src/dtls_handshake.hrl
+++ b/lib/ssl/src/dtls_handshake.hrl
@@ -27,6 +27,7 @@
 -define(dtls_handshake, true).
 
 -include("ssl_handshake.hrl"). %% Common TLS and DTLS records and Constantes
+-include("ssl_api.hrl").
 
 -define(HELLO_VERIFY_REQUEST, 3).
 -define(HELLO_VERIFY_REQUEST_VERSION, {254, 255}).
diff --git a/lib/ssl/src/dtls_record.erl b/lib/ssl/src/dtls_record.erl
index b7346d3ec8..dd33edfd77 100644
--- a/lib/ssl/src/dtls_record.erl
+++ b/lib/ssl/src/dtls_record.erl
@@ -49,9 +49,8 @@
 	 is_acceptable_version/2, hello_version/2]).
 
 
--export_type([dtls_version/0, dtls_atom_version/0]).
+-export_type([dtls_atom_version/0]).
 
--type dtls_version()       :: ssl_record:ssl_version().
 -type dtls_atom_version()  :: dtlsv1 | 'dtlsv1.2'.
 
 -define(REPLAY_WINDOW_SIZE, 64).
@@ -135,7 +134,7 @@ set_connection_state_by_epoch(ReadState, Epoch, #{saved_read := #{epoch := Epoch
     States#{saved_read := ReadState}.
 
 %%--------------------------------------------------------------------
--spec init_connection_state_seq(dtls_version(), ssl_record:connection_states()) ->
+-spec init_connection_state_seq(ssl_record:ssl_version(), ssl_record:connection_states()) ->
 				       ssl_record:connection_state().
 %%
 %% Description: Copy the read sequence number to the write sequence number
@@ -163,7 +162,7 @@ current_connection_state_epoch(#{current_write := #{epoch := Epoch}},
     Epoch.
 
 %%--------------------------------------------------------------------
--spec get_dtls_records(binary(), [dtls_version()], binary()) -> {[binary()], binary()} | #alert{}.
+-spec get_dtls_records(binary(), [ssl_record:ssl_version()], binary()) -> {[binary()], binary()} | #alert{}.
 %%
 %% Description: Given old buffer and new data from UDP/SCTP, packs up a records
 %% and returns it as a list of tls_compressed binaries also returns leftover
@@ -188,7 +187,7 @@ get_dtls_records(Data, Versions, Buffer) ->
 %%====================================================================
 
 %%--------------------------------------------------------------------
--spec encode_handshake(iolist(), dtls_version(), integer(), ssl_record:connection_states()) ->
+-spec encode_handshake(iolist(), ssl_record:ssl_version(), integer(), ssl_record:connection_states()) ->
 			      {iolist(), ssl_record:connection_states()}.
 %
 %% Description: Encodes a handshake message to send on the ssl-socket.
@@ -198,7 +197,7 @@ encode_handshake(Frag, Version, Epoch, ConnectionStates) ->
 
 
 %%--------------------------------------------------------------------
--spec encode_alert_record(#alert{}, dtls_version(), ssl_record:connection_states()) ->
+-spec encode_alert_record(#alert{}, ssl_record:ssl_version(), ssl_record:connection_states()) ->
 				 {iolist(), ssl_record:connection_states()}.
 %%
 %% Description: Encodes an alert message to send on the ssl-socket.
@@ -210,7 +209,7 @@ encode_alert_record(#alert{level = Level, description = Description},
 		      ConnectionStates).
 
 %%--------------------------------------------------------------------
--spec encode_change_cipher_spec(dtls_version(), integer(), ssl_record:connection_states()) ->
+-spec encode_change_cipher_spec(ssl_record:ssl_version(), integer(), ssl_record:connection_states()) ->
 				       {iolist(), ssl_record:connection_states()}.
 %%
 %% Description: Encodes a change_cipher_spec-message to send on the ssl socket.
@@ -219,7 +218,7 @@ encode_change_cipher_spec(Version, Epoch, ConnectionStates) ->
     encode_plain_text(?CHANGE_CIPHER_SPEC, Version, Epoch, ?byte(?CHANGE_CIPHER_SPEC_PROTO), ConnectionStates).
 
 %%--------------------------------------------------------------------
--spec encode_data(binary(), dtls_version(), ssl_record:connection_states()) ->
+-spec encode_data(binary(), ssl_record:ssl_version(), ssl_record:connection_states()) ->
 			 {iolist(),ssl_record:connection_states()}.
 %%
 %% Description: Encodes data to send on the ssl-socket.
@@ -248,8 +247,8 @@ decode_cipher_text(#ssl_tls{epoch = Epoch} = CipherText, ConnnectionStates0) ->
 %%====================================================================
 
 %%--------------------------------------------------------------------
--spec protocol_version(dtls_atom_version() | dtls_version()) ->
-			      dtls_version() | dtls_atom_version().
+-spec protocol_version(dtls_atom_version() | ssl_record:ssl_version()) ->
+			      ssl_record:ssl_version() | dtls_atom_version().
 %%
 %% Description: Creates a protocol version record from a version atom
 %% or vice versa.
@@ -263,7 +262,7 @@ protocol_version({254, 253}) ->
 protocol_version({254, 255}) ->
     dtlsv1.
 %%--------------------------------------------------------------------
--spec lowest_protocol_version(dtls_version(), dtls_version()) -> dtls_version().
+-spec lowest_protocol_version(ssl_record:ssl_version(), ssl_record:ssl_version()) -> ssl_record:ssl_version().
 %%
 %% Description: Lowes protocol version of two given versions
 %%--------------------------------------------------------------------
@@ -277,7 +276,7 @@ lowest_protocol_version(_,Version) ->
     Version.
 
 %%--------------------------------------------------------------------
--spec lowest_protocol_version([dtls_version()]) -> dtls_version().
+-spec lowest_protocol_version([ssl_record:ssl_version()]) -> ssl_record:ssl_version().
 %%     
 %% Description: Lowest protocol version present in a list
 %%--------------------------------------------------------------------
@@ -288,7 +287,7 @@ lowest_protocol_version(Versions) ->
     lowest_list_protocol_version(Ver, Vers).
 
 %%--------------------------------------------------------------------
--spec highest_protocol_version([dtls_version()]) -> dtls_version().
+-spec highest_protocol_version([ssl_record:ssl_version()]) -> ssl_record:ssl_version().
 %%
 %% Description: Highest protocol version present in a list
 %%--------------------------------------------------------------------
@@ -299,7 +298,7 @@ highest_protocol_version(Versions) ->
     highest_list_protocol_version(Ver, Vers).
 
 %%--------------------------------------------------------------------
--spec highest_protocol_version(dtls_version(), dtls_version()) -> dtls_version().
+-spec highest_protocol_version(ssl_record:ssl_version(), ssl_record:ssl_version()) -> ssl_record:ssl_version().
 %%
 %% Description: Highest protocol version of two given versions
 %%--------------------------------------------------------------------
@@ -315,7 +314,7 @@ highest_protocol_version(_,Version) ->
     Version.
 
 %%--------------------------------------------------------------------
--spec is_higher(V1 :: dtls_version(), V2::dtls_version()) -> boolean().
+-spec is_higher(V1 :: ssl_record:ssl_version(), V2::ssl_record:ssl_version()) -> boolean().
 %%
 %% Description: Is V1 > V2
 %%--------------------------------------------------------------------
@@ -327,7 +326,7 @@ is_higher(_, _) ->
     false.
 
 %%--------------------------------------------------------------------
--spec supported_protocol_versions() -> [dtls_version()].
+-spec supported_protocol_versions() -> [ssl_record:ssl_version()].
 %%
 %% Description: Protocol versions supported
 %%--------------------------------------------------------------------
@@ -370,7 +369,7 @@ supported_protocol_versions([_|_] = Vsns) ->
     end.
 
 %%--------------------------------------------------------------------
--spec is_acceptable_version(dtls_version(), Supported :: [dtls_version()]) -> boolean().
+-spec is_acceptable_version(ssl_record:ssl_version(), Supported :: [ssl_record:ssl_version()]) -> boolean().
 %%
 %% Description: ssl version 2 is not acceptable security risks are too big.
 %%
@@ -378,7 +377,7 @@ supported_protocol_versions([_|_] = Vsns) ->
 is_acceptable_version(Version, Versions) ->
     lists:member(Version, Versions).
 
--spec hello_version(dtls_version(), [dtls_version()]) -> dtls_version().
+-spec hello_version(ssl_record:ssl_version(), [ssl_record:ssl_version()]) -> ssl_record:ssl_version().
 hello_version(Version, Versions) ->
     case dtls_v1:corresponding_tls_version(Version) of
         TLSVersion when TLSVersion >= {3, 3} ->
diff --git a/lib/ssl/src/inet_tls_dist.erl b/lib/ssl/src/inet_tls_dist.erl
index a4f8bb7562..5cab35fd4b 100644
--- a/lib/ssl/src/inet_tls_dist.erl
+++ b/lib/ssl/src/inet_tls_dist.erl
@@ -480,22 +480,25 @@ allowed_nodes(PeerCert, Allowed, PeerIP, Node, Host) ->
             allowed_nodes(PeerCert, Allowed, PeerIP)
     end.
 
-
-
 setup(Node, Type, MyNode, LongOrShortNames, SetupTime) ->
     gen_setup(inet_tcp, Node, Type, MyNode, LongOrShortNames, SetupTime).
 
 gen_setup(Driver, Node, Type, MyNode, LongOrShortNames, SetupTime) ->
     Kernel = self(),
     monitor_pid(
-      spawn_opt(
-        fun() ->
-                do_setup(
-                  Driver, Kernel, Node, Type,
-                  MyNode, LongOrShortNames, SetupTime)
-        end,
-        [link, {priority, max}])).
+      spawn_opt(setup_fun(Driver, Kernel, Node, Type, MyNode, LongOrShortNames, SetupTime),
+                [link, {priority, max}])).
+
+-spec setup_fun(_,_,_,_,_,_,_) -> fun(() -> no_return()).
+setup_fun(Driver, Kernel, Node, Type, MyNode, LongOrShortNames, SetupTime) ->
+    fun() ->
+            do_setup(
+              Driver, Kernel, Node, Type,
+              MyNode, LongOrShortNames, SetupTime)
+    end.
 
+
+-spec do_setup(_,_,_,_,_,_,_) -> no_return().
 do_setup(Driver, Kernel, Node, Type, MyNode, LongOrShortNames, SetupTime) ->
     {Name, Address} = split_node(Driver, Node, LongOrShortNames),
     ErlEpmd = net_kernel:epmd_module(),
@@ -520,6 +523,8 @@ do_setup(Driver, Kernel, Node, Type, MyNode, LongOrShortNames, SetupTime) ->
                trace({getaddr_failed, Driver, Address, Other}))
     end.
 
+-spec do_setup_connect(_,_,_,_,_,_,_,_,_,_) -> no_return().
+
 do_setup_connect(Driver, Kernel, Node, Address, Ip, TcpPort, Version, Type, MyNode, Timer) ->
     Opts =  trace(connect_options(get_ssl_options(client))),
     dist_util:reset_timer(Timer),
@@ -564,7 +569,7 @@ gen_close(Driver, Socket) ->
 %% Determine if EPMD module supports address resolving. Default
 %% is to use inet_tcp:getaddr/2.
 %% ------------------------------------------------------------
-get_address_resolver(EpmdModule, Driver) ->
+get_address_resolver(EpmdModule, _Driver) ->
     case erlang:function_exported(EpmdModule, address_please, 3) of
         true -> {EpmdModule, address_please};
         _    -> {erl_epmd, address_please}
diff --git a/lib/ssl/src/ssl.erl b/lib/ssl/src/ssl.erl
index 34261e5d6b..a7d6f28c7a 100644
--- a/lib/ssl/src/ssl.erl
+++ b/lib/ssl/src/ssl.erl
@@ -61,16 +61,321 @@
 -deprecated({ssl_accept, 2, eventually}).
 -deprecated({ssl_accept, 3, eventually}).
 
+-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,
+              cipher/0,
+              hash/0,
+              key_algo/0,
+              sign_algo/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(),
+				       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 common_option()        :: {protocol, protocol()} |
+                                {handshake, handshake_completion()} |
+                                {cert, cert()} |
+                                {certfile, cert_pem()} |
+                                {key, key()} |
+                                {keyfile, key_pem()} |
+                                {password, key_password()} |
+                                {ciphers, cipher_suites()} |
+                                {eccs, eccs()} |
+                                {secure_renegotiate, secure_renegotiation()} |
+                                {depth, allowed_cert_chain_length()} |
+                                {verify_fun, custom_verify()} |
+                                {crl_check, crl_check()} |
+                                {crl_cache, crl_cache_opts()} |
+                                {max_handshake_size, handshake_size()} |
+                                {partial_chain, root_fun()} |
+                                {versions, protocol_versions()} |
+                                {user_lookup_fun, custom_user_lookup()} |
+                                {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', 
+                                           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 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 client_option()        :: {verify, client_verify_type()} |
+                                {reuse_session, client_reuse_session()} |
+                                {reuse_sessions, client_reuse_sessions()} |
+                                {cacerts, client_cacerts()} |
+                                {cacertfile, client_cafile()} |
+                                {alpn_advertised_protocols, client_alpn()} |
+                                {client_preferred_next_protocols, client_preferred_next_protocols()} |
+                                {psk_identity, client_psk_identity()} |
+                                {srp_identity, client_srp_identity()} |
+                                {server_name_indication, sni()} |
+                                {customize_hostname_check, customize_hostname_check()} |
+                                {signature_algs, client_signature_algs()} |                                    
+                                {fallback, fallback()}.
+
+-type client_verify_type()       :: verify_type().
+-type client_reuse_session()     :: ssl:session_id().
+-type client_reuse_sessions()    :: boolean() | save.
+-type client_cacerts()           :: [public_key:der_encoded()].
+-type client_cafile()            :: ssl:path().
+-type app_level_protocol()       :: binary().
+-type client_alpn()              :: [app_level_protocol()].
+-type client_preferred_next_protocols() :: {Precedence :: server | client, 
+                                            ClientPrefs :: [app_level_protocol()]} |
+                                           {Precedence :: server | client, 
+                                            ClientPrefs :: [app_level_protocol()], 
+                                            Default::app_level_protocol()}.
+-type client_psk_identity()             :: psk_identity().
+-type client_srp_identity()             :: srp_identity().
+-type customize_hostname_check() :: list().
+-type sni()                      :: HostName :: ssl:hostname() | disable. 
+-type client_signature_algs()    :: signature_algs().
+-type fallback()                 :: boolean().
+
+%% -------------------------------------------------------------------------------------------------------
+
+-type server_option()        :: {cacerts, server_cacerts()} |
+                                {cacertfile, server_cafile()} |
+                                {dh, dh_der()} |
+                                {dhfile, dh_file()} |
+                                {verify, server_verify_type()} |
+                                {fail_if_no_peer_cert, fail_if_no_peer_cert()} |
+                                {reuse_sessions, server_reuse_sessions()} |
+                                {reuse_session, server_reuse_session()} |
+                                {alpn_preferred_protocols, server_alpn()} |
+                                {next_protocols_advertised, server_next_protocol()} |
+                                {psk_identity, server_psk_identity()} |
+                                {honor_cipher_order, boolean()} |
+                                {sni_hosts, sni_hosts()} |
+                                {sni_fun, sni_fun()} |
+                                {honor_cipher_order, honor_cipher_order()} |
+                                {honor_ecc_order, honor_ecc_order()} |
+                                {client_renegotiation, client_renegotiation()}|
+                                {signature_algs, server_signature_algs()}.
+
+-type server_cacerts()           :: [public_key:der_encoded()].
+-type server_cafile()            :: ssl:path().
+-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 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_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 private_key_type() :: rsa | %% Backwards compatibility
+                            dsa | %% Backwards compatibility
+                            'RSAPrivateKey' |
+                            'DSAPrivateKey' |
+                            'ECPrivateKey' |
+                            'PrivateKeyInfo'.
+
+-type hello_extensions()  :: #{signature_algs => sign_algo()}. %% TODO
+%% -------------------------------------------------------------------------------------------------------
 %%--------------------------------------------------------------------
--spec start() -> ok  | {error, reason()}.
--spec start(permanent | transient | temporary) -> ok | {error, reason()}.
 %%
 %% Description: Utility function that starts the ssl and applications
 %% that it depends on.
 %% see application(3)
 %%--------------------------------------------------------------------
+-spec start() -> ok  | {error, reason()}.
 start() ->
     start(temporary).
+-spec start(permanent | transient | temporary) -> ok | {error, reason()}.
 start(Type) ->
     case application:ensure_all_started(ssl, Type) of
 	{ok, _} ->
@@ -87,20 +392,17 @@ stop() ->
     application:stop(ssl).
 
 %%--------------------------------------------------------------------
--spec connect(host() | port(), [connect_option()]) -> {ok, #sslsocket{}} |
-					      {error, reason()}.
--spec connect(host() | port(), [connect_option()] | inet:port_number(),
-	      timeout() | list()) ->
-		     {ok, #sslsocket{}} | {error, reason()}.
--spec connect(host() | port(), inet:port_number(), list(), timeout()) ->
-		     {ok, #sslsocket{}} | {error, reason()}.
-
 %%
 %% Description: Connect to an ssl server.
 %%--------------------------------------------------------------------
+-spec connect(host() | port(), [client_option()]) -> {ok, #sslsocket{}} |
+					      {error, reason()}.
 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()}.
 connect(Socket, SslOptions0, Timeout) when is_port(Socket),
 					    (is_integer(Timeout) andalso Timeout >= 0) or (Timeout == infinity) ->
     {Transport,_,_,_} = proplists:get_value(cb_info, SslOptions0,
@@ -117,6 +419,8 @@ 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()}.
 connect(Host, Port, Options, Timeout) when (is_integer(Timeout) andalso Timeout >= 0) or (Timeout == infinity) ->
     try
 	{ok, Config} = handle_options(Options, client, Host),
@@ -132,7 +436,7 @@ connect(Host, Port, Options, Timeout) when (is_integer(Timeout) andalso Timeout
     end.
 
 %%--------------------------------------------------------------------
--spec listen(inet:port_number(), [listen_option()]) ->{ok, #sslsocket{}} | {error, reason()}.
+-spec listen(inet:port_number(), [tls_server_option()]) ->{ok, #sslsocket{}} | {error, reason()}.
 
 %%
 %% Description: Creates an ssl listen socket.
@@ -148,16 +452,16 @@ listen(Port, Options0) ->
 	    Error
     end.
 %%--------------------------------------------------------------------
--spec transport_accept(#sslsocket{}) -> {ok, #sslsocket{}} |
-					{error, reason()}.
--spec transport_accept(#sslsocket{}, timeout()) -> {ok, #sslsocket{}} |
-						   {error, reason()}.
 %%
 %% Description: Performs transport accept on an ssl listen socket
 %%--------------------------------------------------------------------
+-spec transport_accept(#sslsocket{}) -> {ok, #sslsocket{}} |
+					{error, reason()}.
 transport_accept(ListenSocket) ->
     transport_accept(ListenSocket, infinity).
 
+-spec transport_accept(#sslsocket{}, timeout()) -> {ok, #sslsocket{}} |
+						   {error, reason()}.
 transport_accept(#sslsocket{pid = {ListenSocket,
 				   #config{connection_cb = ConnectionCb} = Config}}, Timeout) 
   when (is_integer(Timeout) andalso Timeout >= 0) or (Timeout == infinity) ->
@@ -169,25 +473,25 @@ transport_accept(#sslsocket{pid = {ListenSocket,
     end.
   
 %%--------------------------------------------------------------------
--spec ssl_accept(#sslsocket{}) -> ok | {error, reason()}.
--spec ssl_accept(#sslsocket{} | port(), timeout()| [ssl_option()
-						    | transport_option()]) ->
-			ok | {ok, #sslsocket{}} | {error, reason()}.
-
--spec ssl_accept(#sslsocket{} | port(), [ssl_option()] | [ssl_option()| transport_option()], timeout()) ->
-			ok | {ok, #sslsocket{}} | {error, reason()}.
 %%
 %% 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()}.
 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()}.
 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) ->
     ssl_accept(ListenSocket, SslOptions, infinity);
 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()}.
 ssl_accept(Socket, SslOptions, Timeout) when is_port(Socket) ->
     handshake(Socket, SslOptions, Timeout);
 ssl_accept(Socket, SslOptions, Timeout) ->
@@ -198,20 +502,18 @@ ssl_accept(Socket, SslOptions, Timeout) ->
             Error
      end.
 %%--------------------------------------------------------------------
--spec handshake(#sslsocket{}) -> {ok, #sslsocket{}} | {error, reason()}.
--spec handshake(#sslsocket{} | port(), timeout()| [ssl_option()
-						    | transport_option()]) ->
-                       {ok, #sslsocket{}} | {error, reason()}.
-
--spec handshake(#sslsocket{} | port(), [ssl_option()] | [ssl_option()| transport_option()], timeout()) ->
-			{ok, #sslsocket{}} | {error, reason()}.
 %%
 %% Description: Performs accept on an ssl listen socket. e.i. performs
 %%              ssl handshake.
 %%--------------------------------------------------------------------
+
+%% Performs the SSL/TLS/DTLS server-side handshake.
+-spec handshake(#sslsocket{}) -> {ok, #sslsocket{}} | {error, timeout | closed | {options, any()} | error_alert()}.
 handshake(ListenSocket) ->
     handshake(ListenSocket, infinity).
 
+-spec handshake(#sslsocket{} | port(), timeout()| [tls_server_option()]) ->
+                       {ok, #sslsocket{}} | {error, timeout | closed | {options, any()} | error_alert()}.
 handshake(#sslsocket{} = Socket, Timeout) when  (is_integer(Timeout) andalso Timeout >= 0) or 
                                                 (Timeout == infinity) ->
     ssl_connection:handshake(Socket, Timeout);
@@ -219,6 +521,8 @@ 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()}.
 handshake(#sslsocket{} = Socket, [], Timeout) when (is_integer(Timeout) andalso Timeout >= 0) or 
                                                     (Timeout == infinity)->
     handshake(Socket, Timeout);
@@ -261,7 +565,7 @@ handshake(Socket, SslOptions, Timeout) when is_port(Socket),
 
 
 %%--------------------------------------------------------------------
--spec handshake_continue(#sslsocket{}, [ssl_option()]) -> 
+-spec handshake_continue(#sslsocket{}, [tls_client_option() | tls_server_option()]) -> 
                                 {ok, #sslsocket{}} | {error, reason()}.
 %%
 %%
@@ -270,7 +574,7 @@ handshake(Socket, SslOptions, Timeout) when is_port(Socket),
 handshake_continue(Socket, SSLOptions) ->
     handshake_continue(Socket, SSLOptions, infinity).
 %%--------------------------------------------------------------------
--spec handshake_continue(#sslsocket{}, [ssl_option()], timeout()) -> 
+-spec handshake_continue(#sslsocket{}, [tls_client_option() | tls_server_option()], timeout()) -> 
                                 {ok, #sslsocket{}} | {error, reason()}.
 %%
 %%
@@ -331,13 +635,14 @@ send(#sslsocket{pid = {ListenSocket, #config{transport_info={Transport, _, _, _}
     Transport:send(ListenSocket, Data). %% {error,enotconn}
 
 %%--------------------------------------------------------------------
--spec recv(#sslsocket{}, integer()) -> {ok, binary()| list()} | {error, reason()}.
--spec recv(#sslsocket{}, integer(), timeout()) -> {ok, binary()| list()} | {error, reason()}.
 %%
 %% Description: Receives data when active = false
 %%--------------------------------------------------------------------
+-spec recv(#sslsocket{}, integer()) -> {ok, binary()| list()} | {error, reason()}.
 recv(Socket, Length) ->
     recv(Socket, Length, infinity).
+
+-spec recv(#sslsocket{}, integer(), timeout()) -> {ok, binary()| list()} | {error, reason()}.
 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);
@@ -460,9 +765,9 @@ cipher_suites(all) ->
     [ssl_cipher_format:erl_suite_definition(Suite) || Suite <- available_suites(all)].
 
 %%--------------------------------------------------------------------
--spec cipher_suites(default | all | anonymous, tls_record:tls_version() | dtls_record:dtls_version() |
+-spec cipher_suites(default | all | anonymous, ssl_record:ssl_version() |
                     tls_record:tls_atom_version() |  dtls_record:dtls_atom_version()) -> 
-                           [ssl_cipher_format:erl_cipher_suite()].
+                           [erl_cipher_suite()].
 %% Description: Returns all default and all supported cipher suites for a
 %% TLS/DTLS version
 %%--------------------------------------------------------------------
@@ -478,9 +783,9 @@ cipher_suites(Base, Version) ->
     [ssl_cipher_format:suite_definition(Suite) || Suite <- supported_suites(Base, Version)].
 
 %%--------------------------------------------------------------------
--spec filter_cipher_suites([ssl_cipher_format:erl_cipher_suite()], 
+-spec filter_cipher_suites([erl_cipher_suite()], 
                            [{key_exchange | cipher | mac | prf, fun()}] | []) -> 
-                                  [ssl_cipher_format:erl_cipher_suite()].
+                                  [erl_cipher_suite()].
 %% 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.
@@ -497,10 +802,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([ssl_cipher_format:erl_cipher_suite()] | 
+-spec prepend_cipher_suites([erl_cipher_suite()] | 
                             [{key_exchange | cipher | mac | prf, fun()}],
-                            [ssl_cipher_format:erl_cipher_suite()]) -> 
-                                   [ssl_cipher_format:erl_cipher_suite()].
+                            [erl_cipher_suite()]) -> 
+                                   [erl_cipher_suite()].
 %% 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
@@ -515,10 +820,10 @@ prepend_cipher_suites(Filters, Suites) ->
     Preferred = filter_cipher_suites(Suites, Filters), 
     Preferred ++ (Suites -- Preferred).
 %%--------------------------------------------------------------------
--spec append_cipher_suites(Deferred :: [ssl_cipher_format:erl_cipher_suite()] | 
+-spec append_cipher_suites(Deferred :: [erl_cipher_suite()] | 
                                        [{key_exchange | cipher | mac | prf, fun()}],
-                           [ssl_cipher_format:erl_cipher_suite()]) -> 
-                                  [ssl_cipher_format:erl_cipher_suite()].
+                           [erl_cipher_suite()]) -> 
+                                  [erl_cipher_suite()].
 %% 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.
@@ -540,8 +845,8 @@ eccs() ->
     eccs_filter_supported(Curves).
 
 %%--------------------------------------------------------------------
--spec eccs(tls_record:tls_version() | tls_record:tls_atom_version() |
-           dtls_record:dtls_version() | dtls_record:dtls_atom_version()) ->
+-spec eccs(tls_record:tls_atom_version() |
+           ssl_record:ssl_version() | dtls_record:dtls_atom_version()) ->
                   tls_v1:curves().
 %% Description: returns the curves supported for a given version of
 %% ssl/tls.
@@ -723,7 +1028,7 @@ versions() ->
     SupportedDTLSVsns = [dtls_record:protocol_version(Vsn) || Vsn <- DTLSVsns],
     AvailableTLSVsns = ?ALL_AVAILABLE_VERSIONS,
     AvailableDTLSVsns = ?ALL_AVAILABLE_DATAGRAM_VERSIONS,
-    [{ssl_app, ?VSN}, {supported, SupportedTLSVsns}, 
+    [{ssl_app, "9.2"}, {supported, SupportedTLSVsns}, 
      {supported_dtls, SupportedDTLSVsns}, 
      {available, AvailableTLSVsns}, 
      {available_dtls, AvailableDTLSVsns}].
@@ -813,7 +1118,7 @@ tls_version({254, _} = Version) ->
 
 
 %%--------------------------------------------------------------------
--spec suite_to_str(ssl_cipher_format:erl_cipher_suite()) -> string().
+-spec suite_to_str(erl_cipher_suite()) -> string().
 %%
 %% Description: Return the string representation of a cipher suite.
 %%--------------------------------------------------------------------
@@ -1000,8 +1305,8 @@ handle_options(Opts0, Role, Host) ->
 		  alpn_preferred_protocols, next_protocols_advertised,
 		  client_preferred_next_protocols, log_alert,
 		  server_name_indication, honor_cipher_order, padding_check, crl_check, crl_cache,
-		  fallback, signature_algs, eccs, honor_ecc_order, beast_mitigation,
-                  max_handshake_size, handshake, customize_hostname_check],
+		  fallback, signature_algs, eccs, honor_ecc_order,
+                  beast_mitigation, max_handshake_size, handshake, customize_hostname_check],
     SockOpts = lists:foldl(fun(Key, PropList) ->
 				   proplists:delete(Key, PropList)
 			   end, Opts, SslOptions),
diff --git a/lib/ssl/src/ssl_alert.erl b/lib/ssl/src/ssl_alert.erl
index 83e5ea1088..2a20d13cd5 100644
--- a/lib/ssl/src/ssl_alert.erl
+++ b/lib/ssl/src/ssl_alert.erl
@@ -48,8 +48,8 @@ decode(Bin) ->
     decode(Bin, [], 0).
 
 %%--------------------------------------------------------------------
--spec reason_code(#alert{}, client | server) ->
-                         closed | {tls_alert, unicode:chardata()}.
+%% -spec reason_code(#alert{}, client | server) ->
+%%                          {tls_alert, unicode:chardata()} | closed.
 %-spec reason_code(#alert{}, client | server) -> closed | {essl, string()}.
 %%
 %% Description: Returns the error reason that will be returned to the
diff --git a/lib/ssl/src/ssl_api.hrl b/lib/ssl/src/ssl_api.hrl
index 7b7b1cbcd9..f4594912bd 100644
--- a/lib/ssl/src/ssl_api.hrl
+++ b/lib/ssl/src/ssl_api.hrl
@@ -21,56 +21,7 @@
 -ifndef(ssl_api).
 -define(ssl_api, true).
 
--include("ssl_cipher.hrl").
-
-%% Visible in API
--export_type([connect_option/0, listen_option/0, ssl_option/0, transport_option/0,
-	      prf_random/0, sslsocket/0]).
-
-
 %% Looks like it does for backwards compatibility reasons
 -record(sslsocket, {fd = nil, pid = nil}).
 
-
--type sslsocket()                :: #sslsocket{}.
--type connect_option()           :: socket_connect_option() | ssl_option() | transport_option().
--type socket_connect_option()    :: gen_tcp:connect_option().
--type listen_option()            :: socket_listen_option() | ssl_option() | transport_option().
--type socket_listen_option()     :: gen_tcp:listen_option().
-
--type ssl_option()    :: {versions, ssl_record:ssl_atom_version()} |
-			 {verify, verify_type()} |
-			 {verify_fun, {fun(), InitialUserState::term()}} |
-                         {fail_if_no_peer_cert, boolean()} | {depth, integer()} |
-                         {cert, Der::binary()} | {certfile, path()} |
-                         {key, {private_key_type(), Der::binary()}} |
-                         {keyfile, path()} | {password, string()} | {cacerts, [Der::binary()]} |
-                         {cacertfile, path()} | {dh, Der::binary()} | {dhfile, path()} |
-                         {user_lookup_fun, {fun(), InitialUserState::term()}} |
-                         {psk_identity, string()} |
-                         {srp_identity, {string(), string()}} |
-                         {ciphers, ciphers()} | {ssl_imp, ssl_imp()} | {reuse_sessions, boolean()} |
-                         {reuse_session, fun()} | {hibernate_after, integer()|undefined} |
-                         {alpn_advertised_protocols, [binary()]} |
-                         {alpn_preferred_protocols, [binary()]} |
-                         {next_protocols_advertised, list(binary())} |
-                         {client_preferred_next_protocols, binary(), client | server, list(binary())}.
-
--type verify_type()  :: verify_none | verify_peer.
--type path()         :: string().
--type ciphers()      :: [ssl_cipher_format:erl_cipher_suite()] |
-			string(). % (according to old API)
--type ssl_imp()      :: new | old.
-
--type transport_option() :: {cb_info, {CallbackModule::atom(), DataTag::atom(),
-				       ClosedTag::atom(), ErrTag::atom()}}.
--type prf_random() :: client_random | server_random.
-
--type private_key_type() :: rsa | %% Backwards compatibility
-                            dsa | %% Backwards compatibility
-                            'RSAPrivateKey' |
-                            'DSAPrivateKey' |
-                            'ECPrivateKey' |
-                            'PrivateKeyInfo'.
-
 -endif. % -ifdef(ssl_api).
diff --git a/lib/ssl/src/ssl_cipher.erl b/lib/ssl/src/ssl_cipher.erl
index 0416e5c463..cf1bec6332 100644
--- a/lib/ssl/src/ssl_cipher.erl
+++ b/lib/ssl/src/ssl_cipher.erl
@@ -481,8 +481,8 @@ filter(DerCert, Ciphers0, Version) ->
     filter_suites_signature(Sign, Ciphers, Version).
 
 %%--------------------------------------------------------------------
--spec filter_suites([ssl_cipher_format:erl_cipher_suite()] | [ssl_cipher_format:cipher_suite()], map()) ->
-                           [ssl_cipher_format:erl_cipher_suite()] |  [ssl_cipher_format:cipher_suite()].
+-spec filter_suites([ssl:erl_cipher_suite()] | [ssl_cipher_format:cipher_suite()], map()) ->
+                           [ssl:erl_cipher_suite()] |  [ssl_cipher_format:cipher_suite()].
 %%
 %% Description: Filter suites using supplied filter funs
 %%-------------------------------------------------------------------	
@@ -508,8 +508,8 @@ filter_suite(Suite, Filters) ->
     filter_suite(ssl_cipher_format:suite_definition(Suite), Filters).
 
 %%--------------------------------------------------------------------
--spec filter_suites([ssl_cipher_format:erl_cipher_suite()] | [ssl_cipher_format:cipher_suite()]) -> 
-                           [ssl_cipher_format:erl_cipher_suite()] | [ssl_cipher_format:cipher_suite()].
+-spec filter_suites([ssl:erl_cipher_suite()] | [ssl_cipher_format:cipher_suite()]) -> 
+                           [ssl:erl_cipher_suite()] | [ssl_cipher_format:cipher_suite()].
 %%
 %% Description: Filter suites for algorithms supported by crypto.
 %%-------------------------------------------------------------------
diff --git a/lib/ssl/src/ssl_cipher_format.erl b/lib/ssl/src/ssl_cipher_format.erl
index c311c0d097..f7af96583f 100644
--- a/lib/ssl/src/ssl_cipher_format.erl
+++ b/lib/ssl/src/ssl_cipher_format.erl
@@ -25,26 +25,25 @@
 %%----------------------------------------------------------------------
 -module(ssl_cipher_format).
 
+-include("ssl_api.hrl").
 -include("ssl_cipher.hrl").
 -include("ssl_internal.hrl").
 -include_lib("public_key/include/public_key.hrl").
 
--export_type([cipher_suite/0,
-	      erl_cipher_suite/0, old_erl_cipher_suite/0, openssl_cipher_suite/0,
-	      hash/0, key_algo/0, sign_algo/0]).
+-export_type([old_erl_cipher_suite/0, openssl_cipher_suite/0, cipher_suite/0]).
 
--type cipher()            :: null |rc4_128 | des_cbc | '3des_ede_cbc' | aes_128_cbc |  aes_256_cbc | aes_128_gcm | aes_256_gcm | chacha20_poly1305.
--type hash()              :: null | md5 | sha | sha224 | sha256 | sha384 | sha512.
--type sign_algo()         :: rsa | dsa | ecdsa.
--type key_algo()          :: null | 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.
--type erl_cipher_suite()  :: #{key_exchange := key_algo(),
-                               cipher := cipher(),
-                               mac    := hash() | aead,
-                               prf    := hash() | default_prf %% Old cipher suites, version dependent
+-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(),
+                               cipher := internal_cipher(),
+                               mac    := internal_hash() | aead,
+                               prf    := internal_hash() | default_prf %% Old cipher suites, version dependent
                               }.  
--type old_erl_cipher_suite() :: {key_algo(), cipher(), hash()} % Pre TLS 1.2 
+-type old_erl_cipher_suite() :: {ssl:key_algo(), internal_cipher(), internal_hash()} % Pre TLS 1.2 
                                 %% TLS 1.2, internally PRE TLS 1.2 will use default_prf
-                              | {key_algo(), cipher(), hash(), hash() | default_prf}. 
+                              | {ssl:key_algo(), internal_cipher(), internal_hash(), 
+                                 internal_hash() | default_prf}. 
 -type cipher_suite()      :: binary().
 -type openssl_cipher_suite()  :: string().
 
@@ -53,7 +52,7 @@
          openssl_suite/1, openssl_suite_name/1]).
 
 %%--------------------------------------------------------------------
--spec suite_to_str(erl_cipher_suite()) -> string().
+-spec suite_to_str(internal_erl_cipher_suite()) -> string().
 %%
 %% Description: Return the string representation of a cipher suite.
 %%--------------------------------------------------------------------
@@ -77,7 +76,7 @@ suite_to_str(#{key_exchange := Kex,
         "_" ++ string:to_upper(atom_to_list(Mac)).
 
 %%--------------------------------------------------------------------
--spec suite_definition(cipher_suite()) -> erl_cipher_suite().
+-spec suite_definition(cipher_suite()) -> internal_erl_cipher_suite().
 %%
 %% Description: Return erlang cipher suite definition.
 %% Note: Currently not supported suites are commented away.
@@ -805,7 +804,7 @@ suite_definition(?TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256) ->
       prf => sha256}.
 
 %%--------------------------------------------------------------------
--spec erl_suite_definition(cipher_suite() | erl_cipher_suite()) -> old_erl_cipher_suite().
+-spec erl_suite_definition(cipher_suite() | internal_erl_cipher_suite()) -> old_erl_cipher_suite().
 %%
 %% Description: Return erlang cipher suite definition. Filters last value
 %% for now (compatibility reasons).
@@ -822,7 +821,7 @@ erl_suite_definition(#{key_exchange := KeyExchange, cipher := Cipher,
     end.
 
 %%--------------------------------------------------------------------
--spec suite(erl_cipher_suite()) -> cipher_suite().
+-spec suite(internal_erl_cipher_suite()) -> cipher_suite().
 %%
 %% Description: Return TLS cipher suite definition.
 %%--------------------------------------------------------------------
@@ -1585,7 +1584,7 @@ openssl_suite("ECDH-RSA-AES256-GCM-SHA384") ->
     ?TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384.
 
 %%--------------------------------------------------------------------
--spec openssl_suite_name(cipher_suite()) -> openssl_cipher_suite() | erl_cipher_suite().
+-spec openssl_suite_name(cipher_suite()) -> openssl_cipher_suite() | internal_erl_cipher_suite().
 %%
 %% Description: Return openssl cipher suite name if possible
 %%-------------------------------------------------------------------
diff --git a/lib/ssl/src/ssl_connection.erl b/lib/ssl/src/ssl_connection.erl
index 2bfa9a52cd..41a45089d0 100644
--- a/lib/ssl/src/ssl_connection.erl
+++ b/lib/ssl/src/ssl_connection.erl
@@ -77,7 +77,7 @@
 %%====================================================================
 %%--------------------------------------------------------------------
 -spec connect(tls_connection | dtls_connection,
-	      host(), inet:port_number(), 
+	      ssl:host(), inet:port_number(), 
 	      port() | {tuple(), port()}, %% TLS | DTLS  
 	      {#ssl_options{}, #socket_options{},
 	       %% Tracker only needed on server side
@@ -143,7 +143,7 @@ handshake(#sslsocket{pid = [Pid|_]} = Socket, SslOptions, Timeout) ->
     end.
 
 %%--------------------------------------------------------------------
--spec handshake_continue(#sslsocket{}, [ssl_option()],
+-spec handshake_continue(#sslsocket{}, [ssl:tls_server_option()],
                          timeout()) ->  {ok,  #sslsocket{}}| {error, reason()}.
 %%
 %% Description: Continues handshake with new options
@@ -2753,10 +2753,10 @@ handle_sni_extension(#sni{hostname = Hostname}, #state{static_env = #static_env{
                                         session_cache = CacheHandle
                                        },
                private_key = Key,
-	      diffie_hellman_params = DHParams,
-	      ssl_options = NewOptions,
-	      sni_hostname = Hostname
-	     }
+               diffie_hellman_params = DHParams,
+               ssl_options = NewOptions,
+               sni_hostname = Hostname
+              }
     end.
 
 update_ssl_options_from_sni(OrigSSLOptions, SNIHostname) ->
diff --git a/lib/ssl/src/ssl_connection.hrl b/lib/ssl/src/ssl_connection.hrl
index 177fa37b83..a46407b27e 100644
--- a/lib/ssl/src/ssl_connection.hrl
+++ b/lib/ssl/src/ssl_connection.hrl
@@ -82,7 +82,7 @@
                 %% Used only in HS
                 
                 client_certificate_requested = false :: boolean(),
-                key_algorithm         :: ssl_cipher_format:key_algo(),
+                key_algorithm         :: ssl:key_algo(),
                 hashsign_algorithm = {undefined, undefined},
                 cert_hashsign_algorithm = {undefined, undefined},
                 public_key_info      :: ssl_handshake:public_key_info() | 'undefined',
diff --git a/lib/ssl/src/ssl_crl_cache.erl b/lib/ssl/src/ssl_crl_cache.erl
index 9c1af86eeb..841620ce57 100644
--- a/lib/ssl/src/ssl_crl_cache.erl
+++ b/lib/ssl/src/ssl_crl_cache.erl
@@ -28,6 +28,10 @@
 
 -behaviour(ssl_crl_cache_api).
 
+-export_type([crl_src/0, uri/0]).
+-type crl_src() :: {file, file:filename()} | {der,  public_key:der_encoded()}.
+-type uri()     :: uri_string:uri_string().
+
 -export([lookup/3, select/2, fresh_crl/2]).
 -export([insert/1, insert/2, delete/1]).
 
diff --git a/lib/ssl/src/ssl_crl_cache_api.erl b/lib/ssl/src/ssl_crl_cache_api.erl
index d5380583e7..8a750b3929 100644
--- a/lib/ssl/src/ssl_crl_cache_api.erl
+++ b/lib/ssl/src/ssl_crl_cache_api.erl
@@ -21,12 +21,15 @@
 %%
 
 -module(ssl_crl_cache_api).
-
 -include_lib("public_key/include/public_key.hrl"). 
 
--type db_handle() :: term().
--type issuer_name() :: {rdnSequence, [#'AttributeTypeAndValue'{}]}.
+-export_type([dist_point/0, crl_cache_ref/0]).
+
+-type crl_cache_ref() :: any().
+-type issuer_name() ::  {rdnSequence,[#'AttributeTypeAndValue'{}]}.
+-type dist_point()  :: #'DistributionPoint'{}.
 
--callback lookup(#'DistributionPoint'{}, issuer_name(), db_handle()) -> not_available | [public_key:der_encoded()].
--callback select(issuer_name(), db_handle()) ->  [public_key:der_encoded()].
--callback fresh_crl(#'DistributionPoint'{}, public_key:der_encoded()) -> public_key:der_encoded().
+  
+-callback lookup(dist_point(), issuer_name(), crl_cache_ref()) -> not_available | [public_key:der_encoded()].
+-callback select(issuer_name(), crl_cache_ref()) ->  [public_key:der_encoded()].
+-callback fresh_crl(dist_point(), public_key:der_encoded()) -> public_key:der_encoded().
diff --git a/lib/ssl/src/ssl_handshake.erl b/lib/ssl/src/ssl_handshake.erl
index 3da42eb8ac..27c071d6dd 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_cipher_format:key_algo(), ssl_record:ssl_version()) ->
+-spec decode_server_key(binary(), ssl:key_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_cipher_format:key_algo(), ssl_record:ssl_version()) ->
+-spec decode_client_key(binary(), ssl:key_algo(), ssl_record:ssl_version()) ->
 			    #encrypted_premaster_secret{}
 			    | #client_diffie_hellman_public{}
 			    | #client_ec_diffie_hellman_public{}
diff --git a/lib/ssl/src/ssl_internal.hrl b/lib/ssl/src/ssl_internal.hrl
index 91623db79e..57c72aa122 100644
--- a/lib/ssl/src/ssl_internal.hrl
+++ b/lib/ssl/src/ssl_internal.hrl
@@ -31,8 +31,6 @@
 -type reply()             :: term().
 -type msg()               :: term().
 -type from()              :: term().
--type host()		  :: inet:ip_address() | inet:hostname().
--type session_id()        :: 0 | binary().
 -type certdb_ref()        :: reference().
 -type db_handle()         :: term().
 -type der_cert()          :: binary().
diff --git a/lib/ssl/src/ssl_manager.erl b/lib/ssl/src/ssl_manager.erl
index dcd26635c0..c56675b691 100644
--- a/lib/ssl/src/ssl_manager.erl
+++ b/lib/ssl/src/ssl_manager.erl
@@ -42,6 +42,8 @@
 
 -include("ssl_handshake.hrl").
 -include("ssl_internal.hrl").
+-include("ssl_api.hrl").
+
 -include_lib("kernel/include/file.hrl").
 
 -record(state, {
@@ -148,7 +150,7 @@ lookup_trusted_cert(DbHandle, Ref, SerialNumber, Issuer) ->
     ssl_pkix_db:lookup_trusted_cert(DbHandle, Ref, SerialNumber, Issuer).
 
 %%--------------------------------------------------------------------
--spec new_session_id(integer()) -> session_id().
+-spec new_session_id(integer()) -> ssl:session_id().
 %%
 %% Description: Creates a session id for the server.
 %%--------------------------------------------------------------------
@@ -170,7 +172,7 @@ clean_cert_db(Ref, File) ->
 %%
 %% Description: Make the session available for reuse.
 %%--------------------------------------------------------------------
--spec register_session(host(), inet:port_number(), #session{}, unique | true) -> ok.
+-spec register_session(ssl:host(), inet:port_number(), #session{}, unique | true) -> ok.
 register_session(Host, Port, Session, true) ->
     call({register_session, Host, Port, Session});
 register_session(Host, Port, Session, unique = Save) ->
@@ -185,7 +187,7 @@ register_session(Port, Session) ->
 %% a the session has been marked "is_resumable = false" for some while
 %% it will be safe to remove the data from the session database.
 %%--------------------------------------------------------------------
--spec invalidate_session(host(), inet:port_number(), #session{}) -> ok.
+-spec invalidate_session(ssl:host(), inet:port_number(), #session{}) -> ok.
 invalidate_session(Host, Port, Session) ->
     load_mitigation(),
     cast({invalidate_session, Host, Port, Session}).
diff --git a/lib/ssl/src/ssl_session.erl b/lib/ssl/src/ssl_session.erl
index a9759c9b43..44305c65fe 100644
--- a/lib/ssl/src/ssl_session.erl
+++ b/lib/ssl/src/ssl_session.erl
@@ -27,6 +27,7 @@
 
 -include("ssl_handshake.hrl").
 -include("ssl_internal.hrl").
+-include("ssl_api.hrl").
 
 %% Internal application API
 -export([is_new/2, client_id/4, server_id/6, valid_session/2]).
@@ -34,7 +35,7 @@
 -type seconds()   :: integer(). 
 
 %%--------------------------------------------------------------------
--spec is_new(session_id(), session_id()) -> boolean().
+-spec is_new(ssl:session_id(), ssl:session_id()) -> boolean().
 %%
 %% Description: Checks if the session id decided by the server is a
 %%              new or resumed sesion id.
@@ -47,7 +48,7 @@ is_new(_ClientSuggestion, _ServerDecision) ->
     true.
 
 %%--------------------------------------------------------------------
--spec client_id({host(), inet:port_number(), #ssl_options{}}, db_handle(), atom(),
+-spec client_id({ssl:host(), inet:port_number(), #ssl_options{}}, db_handle(), atom(),
 	 undefined | binary()) -> binary().
 %%
 %% Description: Should be called by the client side to get an id
diff --git a/lib/ssl/src/ssl_session_cache_api.erl b/lib/ssl/src/ssl_session_cache_api.erl
index b68c75a09b..5f96f905b1 100644
--- a/lib/ssl/src/ssl_session_cache_api.erl
+++ b/lib/ssl/src/ssl_session_cache_api.erl
@@ -23,14 +23,20 @@
 -module(ssl_session_cache_api).
 -include("ssl_handshake.hrl").
 -include("ssl_internal.hrl").
+-include("ssl_api.hrl").
 
--type key() :: {{host(), inet:port_number()}, session_id()} |  {inet:port_number(), session_id()}.
+-export_type([session_cache_key/0, session/0, partial_key/0, session_cache_ref/0]).
 
--callback init(list()) -> db_handle().
--callback terminate(db_handle()) -> any().
--callback lookup(db_handle(), key()) -> #session{} | undefined.
--callback update(db_handle(), key(), #session{}) -> any().
--callback delete(db_handle(), key()) -> any().
--callback foldl(fun(), term(), db_handle()) -> term().
--callback select_session(db_handle(), {host(), inet:port_number()} | inet:port_number()) -> [#session{}].
--callback size(db_handle()) -> integer().
+-type session_cache_ref() :: any().
+-type session_cache_key() :: {partial_key(), ssl:session_id()}.
+-opaque session()         :: #session{}.
+-opaque partial_key()     :: {ssl:host(), inet:port_number()} | inet:port_number().
+
+-callback init(list()) -> session_cache_ref().
+-callback terminate(session_cache_ref()) -> any().
+-callback lookup(session_cache_ref(), session_cache_key()) -> #session{} | undefined.
+-callback update(session_cache_ref(), session_cache_key(), #session{}) -> any().
+-callback delete(session_cache_ref(), session_cache_key()) -> any().
+-callback foldl(fun(), term(), session_cache_ref()) -> term().
+-callback select_session(session_cache_ref(), {ssl:host(), inet:port_number()} | inet:port_number()) -> [#session{}].
+-callback size(session_cache_ref()) -> integer().
diff --git a/lib/ssl/src/tls_connection.erl b/lib/ssl/src/tls_connection.erl
index 80c1a74ce7..cee69a05a5 100644
--- a/lib/ssl/src/tls_connection.erl
+++ b/lib/ssl/src/tls_connection.erl
@@ -108,7 +108,7 @@ start_fsm(Role, Host, Port, Socket, {#ssl_options{erl_dist = true},_, Tracker} =
     end.
 
 %%--------------------------------------------------------------------
--spec start_link(atom(), pid(), host(), inet:port_number(), port(), list(), pid(), tuple()) ->
+-spec start_link(atom(), pid(), ssl:host(), inet:port_number(), port(), list(), pid(), tuple()) ->
     {ok, pid()} | ignore |  {error, reason()}.
 %%
 %% Description: Creates a gen_statem process which calls Module:init/1 to
diff --git a/lib/ssl/src/tls_handshake.erl b/lib/ssl/src/tls_handshake.erl
index 65217ad68e..fbb81f56fe 100644
--- a/lib/ssl/src/tls_handshake.erl
+++ b/lib/ssl/src/tls_handshake.erl
@@ -30,6 +30,7 @@
 -include("ssl_alert.hrl").
 -include("ssl_internal.hrl").
 -include("ssl_cipher.hrl").
+-include("ssl_api.hrl").
 -include_lib("public_key/include/public_key.hrl").
 
 %% Handshake handling
@@ -47,7 +48,7 @@
 %% Handshake handling
 %%====================================================================
 %%--------------------------------------------------------------------
--spec client_hello(host(), inet:port_number(), ssl_record:connection_states(),
+-spec client_hello(ssl:host(), inet:port_number(), ssl_record:connection_states(),
 		   #ssl_options{}, integer(), atom(), boolean(), der_cert()) ->
 			  #client_hello{}.
 %%
@@ -81,13 +82,13 @@ 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_cipher_format:key_algo()},
+				    binary() | undefined, ssl:key_algo()},
 	    boolean()) ->
-		   {tls_record:tls_version(), session_id(), 
+		   {tls_record:tls_version(), ssl:session_id(), 
 		    ssl_record:connection_states(), alpn | npn, binary() | undefined}|
 		   {tls_record:tls_version(), {resumed | new, #session{}}, 
 		    ssl_record:connection_states(), binary() | undefined, 
-		    #hello_extensions{}, {ssl_cipher_format:hash(), ssl_cipher_format:sign_algo()} | 
+		    #hello_extensions{}, {ssl:hash(), ssl:sign_algo()} | 
                     undefined} | #alert{}.
 %%
 %% Description: Handles a received hello message