Merge branch 'maint'

Conflicts:
	lib/ssl/doc/src/ssl.xml
	lib/ssl/src/ssl.erl
	lib/ssl/src/ssl_cipher_format.erl
	lib/ssl/src/tls_handshake.erl

41 files changed, 1704 insertions, 1215 deletions

diff --git a/lib/crypto/doc/src/engine_keys.xml b/lib/crypto/doc/src/engine_keys.xml
index b28606fb4e..f78bb81bba 100644
--- a/lib/crypto/doc/src/engine_keys.xml
+++ b/lib/crypto/doc/src/engine_keys.xml
@@ -51,7 +51,7 @@
     <p>
       OTP/Crypto requires that the user provides two or three items of information about the key. The application used
       by the user is usually on a higher level, for example in
-      <seealso marker="ssl:ssl#key_option_def">SSL</seealso>. If using
+      <seealso marker="ssl:ssl#type-key">SSL</seealso>. If using
       the crypto application directly, it is required that:
     </p>
     <list>
diff --git a/lib/ftp/doc/src/ftp.xml b/lib/ftp/doc/src/ftp.xml
index ead2367925..9645b03364 100644
--- a/lib/ftp/doc/src/ftp.xml
+++ b/lib/ftp/doc/src/ftp.xml
@@ -550,7 +550,7 @@
 	<v>ipfamily() = inet | inet6 | inet6fb4 (default is inet)</v>
 	<v>port() = integer() > 0 (default is 21)</v>
 	<v>mode() = active | passive (default is passive)</v>
-	<v>tls_options() = [<seealso marker="ssl:ssl#type-ssloption">ssl:ssloption()</seealso>]</v>
+	<v>tls_options() = [<seealso marker="ssl:ssl#type-tls_option">ssl:tls_option()</seealso>]</v>
 	<v>sock_opts() = [<seealso marker="kernel:gen_tcp#type-option">gen_tcp:option()</seealso> except for ipv6_v6only, active, packet, mode, packet_size and header</v>
 	<v>timeout() = integer() > 0 (default is 60000 milliseconds)</v>
 	<v>dtimeout() = integer() > 0 | infinity (default is infinity)</v>
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index 4c61139197..9fcedf6ef9 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -644,7 +644,7 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
       <v>conf_opt() = {cert, der_encoded()} | {key, PrivateKey} |{cacerts, [der_encoded()]}</v>
       <d>
 	This is a subset of the type
-	<seealso marker="ssl:ssl#type-ssloption"> ssl:ssl_option()</seealso>.
+	<seealso marker="ssl:ssl#type-tls_option"> ssl:tls_option()</seealso>.
 	<c>PrivateKey</c> is what
 	<seealso marker="#generate_key-1">generate_key/1</seealso>
 	returns.
diff --git a/lib/public_key/src/public_key.erl b/lib/public_key/src/public_key.erl
index 75d40d2e8a..fd85d3722d 100644
--- a/lib/public_key/src/public_key.erl
+++ b/lib/public_key/src/public_key.erl
@@ -66,7 +66,7 @@
 
 -export_type([public_key/0, private_key/0, pem_entry/0,
 	      pki_asn1_type/0, asn1_type/0, ssh_file/0, der_encoded/0,
-              key_params/0, digest_type/0]).
+              key_params/0, digest_type/0, issuer_name/0]).
 
 -type public_key()           ::  rsa_public_key() | dsa_public_key() | ec_public_key() | ed_public_key() .
 -type private_key()          ::  rsa_private_key() | dsa_private_key() | ec_private_key() | ed_private_key() .
diff --git a/lib/ssl/doc/specs/.gitignore b/lib/ssl/doc/specs/.gitignore
new file mode 100644
index 0000000000..322eebcb06
--- /dev/null
+++ b/lib/ssl/doc/specs/.gitignore
@@ -0,0 +1 @@
+specs_*.xml
diff --git a/lib/ssl/doc/src/Makefile b/lib/ssl/doc/src/Makefile
index c72b6d6cc4..7cf251d8f9 100644
--- a/lib/ssl/doc/src/Makefile
+++ b/lib/ssl/doc/src/Makefile
@@ -80,11 +80,16 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
 
 TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
 
+SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml)
+
+TOP_SPECS_FILE = specs.xml
+
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
 XML_FLAGS +=
 DVIPS_FLAGS +=
+SPECS_FLAGS = -I../../../public_key/include -I../../../public_key/src -I../../..
 
 # ----------------------------------------------------
 # Targets
@@ -92,7 +97,7 @@ DVIPS_FLAGS +=
 $(HTMLDIR)/%.gif: %.gif
 	$(INSTALL_DATA) $< $@
 
-docs: pdf html man
+docs: html pdf man
 
 $(TOP_PDF_FILE): $(XML_FILES)
 
@@ -105,6 +110,7 @@ clean clean_docs:
 	rm -rf $(XMLDIR)
 	rm -f $(MAN3DIR)/*
 	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+	rm -f $(SPECS_FILES)
 	rm -f errs core *~
 
 man: $(MAN3_FILES) $(MAN6_FILES)
diff --git a/lib/ssl/doc/src/specs.xml b/lib/ssl/doc/src/specs.xml
new file mode 100644
index 0000000000..50e9428fec
--- /dev/null
+++ b/lib/ssl/doc/src/specs.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<specs xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="../specs/specs_ssl_crl_cache_api.xml"/>
+  <xi:include href="../specs/specs_ssl_crl_cache.xml"/>
+  <xi:include href="../specs/specs_ssl_session_cache_api.xml"/>
+  <xi:include href="../specs/specs_ssl.xml"/>
+</specs>
+
+ 
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 200fb89a4d..be5abac7bc 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -37,292 +37,333 @@
       <seealso marker="ssl_app">ssl(6)</seealso>.
     </p>
   </description>
-    
-  <section>
-    <title>DATA TYPES</title>
-    <p>The following data types are used in the functions for SSL/TLS/DTLS:</p>
-
-    <taglist>
-
-      <tag><c>boolean() =</c></tag>
-      <item><p><c>true | false</c></p></item>
-
-      <tag><c>option() =</c></tag>
-      <item><p><c>socketoption() | ssl_option() | transport_option()</c></p>
-      </item>
-
-      <tag><c>socketoption() =</c></tag>
-      <item><p><c>proplists:property()</c></p>
-      <p>The default socket options are
-      <c>[{mode,list},{packet, 0},{header, 0},{active, true}]</c>.</p>
-      <p>For valid options, see the
-      <seealso marker="kernel:inet">inet(3)</seealso>,
-      <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> and
-      <seealso marker="kernel:gen_tcp">gen_udp(3)</seealso> 
-      manual pages
-      in Kernel. Note that stream oriented options such as packet are only relevant for SSL/TLS and not DTLS</p></item>
-
-      <tag><marker id="type-ssloption"/><c>ssl_option() =</c></tag>
-      <item>
-	<p><c>{verify, verify_type()}</c></p>
-	<p><c>| {verify_fun, {fun(), term()}}</c></p>
-	<p><c>| {fail_if_no_peer_cert, boolean()}</c></p>
-	<p><c>| {depth, integer()}</c></p>
-	<p><c>| {cert, public_key:der_encoded()}</c></p>
-	<p><c>| {certfile, path()}</c></p>
-	<p><c>| {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()}</c></p>
-	<p><c>| {keyfile, path()}</c></p>
-	<p><c>| {password, string()}</c></p>
-	<p><c>| {cacerts, [public_key:der_encoded()]}</c></p>
-	<p><c>| {cacertfile, path()}</c></p>
-	<p><c>| {dh, public_key:der_encoded()}</c></p>
-	<p><c>| {dhfile, path()}</c></p>
-	<p><c>| {ciphers, ciphers()}</c></p>
-	<p><c>| {user_lookup_fun, {fun(), term()}}, {psk_identity, string()},
-	{srp_identity, {string(), string()}}</c></p>
-	<p><c>| {reuse_sessions, boolean() | save()}</c></p>
-	<p><c>| {reuse_session, fun() | binary()} </c></p>
-	<p><c>| {next_protocols_advertised, [binary()]}</c></p>
-	<p><c>| {client_preferred_next_protocols, {client | server,
-	[binary()]} | {client | server, [binary()], binary()}}</c></p>
-	<p><c>| {log_alert, boolean()}</c></p>
-	<p><c>| {log_level, atom()}</c></p>
-	<p><c>| {server_name_indication, hostname() | disable}</c></p>
-	<p><c>| {customize_hostname_check, list()}</c></p>
-	<p><c>| {sni_hosts, [{hostname(), [ssl_option()]}]}</c></p>
-	<p><c>| {sni_fun, SNIfun::fun()}</c></p>
-      </item>
-      
-      <tag><c>transport_option() =</c></tag>
-      <item><p><c>{cb_info, {CallbackModule::atom(), DataTag::atom(),
-
-      ClosedTag::atom(), ErrTag:atom()}}</c></p>
-      <p>Defaults to <c>{gen_tcp, tcp, tcp_closed, tcp_error}</c> for TLS
-      and <c>{gen_udp, udp, udp_closed, udp_error}</c> for DTLS. Can be used
-      to customize the transport layer. For TLS the callback module must implement a
-      reliable transport protocol, behave as <c>gen_tcp</c>, and have functions
-      corresponding to <c>inet:setopts/2</c>, <c>inet:getopts/2</c>,
-      <c>inet:peername/1</c>, <c>inet:sockname/1</c>, and <c>inet:port/1</c>.
-      The callback <c>gen_tcp</c> is treated specially and calls <c>inet</c>
-      directly. For DTLS this feature must be considered exprimental.</p>
-      <taglist>
-	<tag><c>CallbackModule =</c></tag>
-	<item><p><c>atom()</c></p></item>
-	<tag><c>DataTag =</c></tag>
-	<item><p><c>atom()</c></p>
-	<p>Used in socket data message.</p></item>
-	<tag><c>ClosedTag =</c></tag>
-	<item><p><c>atom()</c></p>
-	<p>Used in socket close message.</p></item>
-      </taglist>
-      </item>
-
-      <tag><c>verify_type() =</c></tag>
-      <item><p><c>verify_none | verify_peer</c></p></item>
-
-      <tag><c>path() =</c></tag>
-      <item><p><c>string()</c></p>
-      <p>Represents a file path.</p></item>
 
-      <tag><c>public_key:der_encoded() =</c></tag>
-      <item><p><c>binary()</c></p>
-      <p>ASN.1 DER-encoded entity as an Erlang binary.</p></item>
+  <!--
+      ================================================================
+      =  Data types                                                  =
+      ================================================================
+  -->
 
-      <tag><c>host() =</c></tag>
-      <item><p><c>hostname() | ipaddress()</c></p></item>
+  <datatypes>
+    <datatype_title>Types used in SSL/TLS/DTLS</datatype_title>
 
-      <tag><c>hostname() =</c></tag>
-      <item><p><c>string() - DNS hostname</c></p></item>
+    
+    <datatype>
+      <name name="socket"/>
+    </datatype>
+    
+    <datatype>
+      <name name="sslsocket"/>
+      <desc>
+	<p>An opaque reference to the TLS/DTLS connection.</p>
+	</desc>
+    </datatype>
+
+    <datatype>
+      <name name="tls_option"/>
+    </datatype>
+        
+    <datatype>
+      <name name="tls_client_option"/>
+    </datatype>
+    
+    <datatype>
+      <name name="tls_server_option"/>
+    </datatype>
+   
+    
+    <datatype>
+      <name name="socket_option"/>
+      <desc>
+	<p>The default socket options are
+	<c>[{mode,list},{packet, 0},{header, 0},{active, true}]</c>.</p>
+	<p>For valid options, see the
+	<seealso marker="kernel:inet">inet(3)</seealso>,
+	<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> and
+	<seealso marker="kernel:gen_tcp">gen_udp(3)</seealso> 
+	manual pages in Kernel. Note that stream oriented options such as packet
+	are only relevant for SSL/TLS and not DTLS</p>
+      </desc>
+    </datatype>
 
-      <tag><c>ip_address() =</c></tag>
-      <item><p><c>{N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6
-      </c></p></item>
+    <datatype>
+      <name name="socket_connect_option"/>
+    </datatype>
+    
+     <datatype>
+      <name name="socket_listen_option"/>
+    </datatype>
 
-      <tag><c>sslsocket() =</c></tag>
-      <item><p>opaque()</p></item>
-      
-      <tag><marker id="type-protocol"/><c> protocol_version() =</c></tag>
-      <item><p><c> ssl_tls_protocol() |  dtls_protocol() </c></p></item>
+    <datatype>
+      <name name="active_msgs"/>
+      <desc>
+      <p>When an TLS/DTLS socket is in active mode (the default), data from the
+      socket is delivered to the owner of the socket in the form of
+      messages as described above.</p>
+      </desc>
+    </datatype>
       
-      <item><p><c>sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'</c></p></item>
-
-      <tag><marker id="type-protocol"/><c> dtls_protocol() =</c></tag>
-      <item><p><c>'dtlsv1' | 'dtlsv1.2'</c></p></item>
-
-      <tag><c>ciphers() =</c></tag>
-      <item><p><c>= [ciphersuite()]</c></p>
-      <p>Tuples and string formats accepted by versions
-      before ssl-8.2.4 will be converted for backwards compatibility</p></item>
-
-      <tag><c>ciphersuite() =</c></tag>
-      <item><p><c>
-      #{key_exchange := key_exchange(),
-        cipher := cipher(),
-        mac := MAC::hash() | aead,
-        prf := PRF::hash() | default_prf} </c></p></item>
-
-      <tag><c>key_exchange()=</c></tag>
-      <item><p><c>rsa | dhe_dss | dhe_rsa | dh_anon | psk | dhe_psk
-      | rsa_psk | srp_anon | srp_dss | srp_rsa | ecdh_anon | ecdh_ecdsa
-      | ecdhe_ecdsa | ecdh_rsa | ecdhe_rsa</c></p></item>
-
-      <tag><c>cipher() =</c></tag>
-      <item><p><c>rc4_128 | des_cbc | '3des_ede_cbc'
-      | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm | chacha20_poly1305</c></p></item>
-
-      <tag><c>hash() =</c></tag>
-      <item><p><c>md5 | sha | sha224 | sha256 | sha348 | sha512</c></p></item>
-
-      <tag><c>prf_random() =</c></tag>
-      <item><p><c>client_random | server_random</c></p></item>
-
-      <tag><c>cipher_filters() =</c></tag>
-      <item><p><c> [{key_exchange | cipher | mac | prf, algo_filter()}])</c></p></item>
-
-      <tag><c>algo_filter() =</c></tag>
-      <item><p>fun(key_exchange() | cipher() | hash() | aead | default_prf) -> true | false </p></item>
-
-      <tag><c>srp_param_type() =</c></tag>
-      <item><p><c>srp_1024 | srp_1536 | srp_2048 | srp_3072
-      | srp_4096 | srp_6144 | srp_8192</c></p></item>
-
-      <tag><c>SNIfun::fun()</c></tag>
-      <item><p><c>= fun(ServerName :: string()) -> [ssl_option()]</c></p></item>
-
-      <tag><c>named_curve() =</c></tag>
-      <item><p><c>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</c></p></item>
-
-       <tag><c>hello_extensions() =</c></tag>
-       <item><p><c>#{renegotiation_info => binary() | undefined,
-                   signature_algs => [{hash(), ecsda| rsa| dsa}] | undefined
-		   alpn => binary() | undefined,
-		   next_protocol_negotiation => binary() | undefined,
-		   srp => string() | undefined,
-		   ec_point_formats => list() | undefined,
-		   elliptic_curves => [oid] | undefined,
-		   sni => string() | undefined}
-       }</c></p></item>
-
-       <tag><c>signature_scheme() =</c></tag>
-       <item>
-	 <p><c>rsa_pkcs1_sha256</c></p>
-	 <p><c>| rsa_pkcs1_sha384</c></p>
-	 <p><c>| rsa_pkcs1_sha512</c></p>
-	 <p><c>| ecdsa_secp256r1_sha256</c></p>
-	 <p><c>| ecdsa_secp384r1_sha384</c></p>
-	 <p><c>| ecdsa_secp521r1_sha512</c></p>
-	 <p><c>| rsa_pss_rsae_sha256</c></p>
-	 <p><c>| rsa_pss_rsae_sha384</c></p>
-	 <p><c>| rsa_pss_rsae_sha512</c></p>
-	 <p><c>| rsa_pss_pss_sha256</c></p>
-	 <p><c>| rsa_pss_pss_sha384</c></p>
-	 <p><c>| rsa_pss_pss_sha512</c></p>
-	 <p><c>| rsa_pkcs1_sha1</c></p>
-	 <p><c>| ecdsa_sha1</c></p>
-       </item>
-
-    </taglist>
-  </section>
+    <datatype>
+      <name name="transport_option"/>
+      <desc>
+	<p>Defaults to <c>{gen_tcp, tcp, tcp_closed, tcp_error}</c>
+	for TLS and <c>{gen_udp, udp, udp_closed, udp_error}</c> for
+	DTLS. Can be used to customize the transport layer. The tag
+	values should be the values used by the underlying transport
+	in its active mode messages. For TLS the callback module must implement a
+	reliable transport protocol, behave as <c>gen_tcp</c>, and have functions
+	corresponding to <c>inet:setopts/2</c>, <c>inet:getopts/2</c>,
+	<c>inet:peername/1</c>, <c>inet:sockname/1</c>, and <c>inet:port/1</c>.
+	The callback <c>gen_tcp</c> is treated specially and calls <c>inet</c>
+	directly. For DTLS this feature must be considered exprimental.
+	</p>
+      </desc>
+    </datatype>
+   
+      <datatype>
+      <name name="path"/>
+     </datatype>
+
+     <datatype>
+      <name name="host"/>
+     </datatype>
+
+     <datatype>
+      <name name="hostname"/>
+     </datatype>
+
+       <datatype>
+      <name name="ip_address"/>
+     </datatype>
+
+     <datatype>
+       <name name="protocol_version"/>
+     </datatype>
+
+       <datatype>
+       <name name="tls_version"/>
+     </datatype>
+     
+     <datatype>
+       <name name="dtls_version"/>
+     </datatype>
+
+
+   <datatype>
+       <name name="legacy_version"/>
+     </datatype>
+     
+     
+      <datatype>
+       <name name="verify_type"/>
+     </datatype>
+       
+     <datatype>
+       <name name="ciphers"/>
+     </datatype>
+     
+      <datatype>
+       <name name="erl_cipher_suite"/>
+     </datatype>
+     
+     <datatype>
+       <name name="cipher"/>
+     </datatype>
+    
+     <datatype>
+       <name name="legacy_cipher"/>
+     </datatype>
+    
+     <datatype>
+       <name name="cipher_filters"/>
+     </datatype>
+ 
+       <datatype>
+       <name name="hash"/>
+     </datatype>
 
-  <section>
-    <title>TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT</title>
+     <datatype>
+       <name name="sha2"/>
+     </datatype>
+
+     <datatype>
+       <name name="legacy_hash"/>
+     </datatype>
 
-    <p>The following options have the same meaning in the client and 
-    the server:</p>
+  
+     <datatype>
+      <name name="signature_algs"/>
+     </datatype>
+     
+     <datatype>
+      <name name="sign_algo"/>
+     </datatype>
+
+     <datatype>
+      <name name="key_algo"/>
+     </datatype>
+
+     <datatype>
+      <name name="algo_filter"/>
+     </datatype>
+
+     <datatype>
+      <name name="eccs"/>
+     </datatype>
+
+     <datatype>
+      <name name="named_curve"/>
+     </datatype>
+
+     <datatype>
+       <name name="psk_identity"/>
+     </datatype>
+
+     <datatype>
+       <name name="srp_identity"/>
+     </datatype>
+
+     <datatype>
+      <name name="srp_param_type"/>
+     </datatype>
+     
+     <datatype>
+       <name name="app_level_protocol"/>
+     </datatype>
+
+     <datatype>
+      <name name="error_alert"/>
+     </datatype>
+
+     <datatype>
+      <name name="tls_alert"/>
+     </datatype>
+
+    <datatype_title>TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT</datatype_title>
     
-    <taglist>
-
-      <tag><c>{protocol, tls | dtls}</c></tag>
-      <item><p>Choose TLS or DTLS protocol for the transport layer security.
-      Defaults to <c>tls</c> Introduced in OTP 20, DTLS support is considered
-      experimental in this release. Other transports than UDP are not yet supported.</p></item>
-
-      <tag><c>{handshake, hello | full}</c></tag>
-      <item><p> Defaults to <c>full</c>. If hello is specified the handshake will
-      pause after the hello message and give the user a possibility make decisions
-      based on hello extensions before continuing or aborting the handshake by calling
-      <seealso marker="#handshake_continue-3"> handshake_continue/3</seealso> or
-      <seealso marker="#handshake_cancel-1"> handshake_cancel/1</seealso>
-      </p></item>
-      
-      <tag><c>{cert, public_key:der_encoded()}</c></tag>
-      <item><p>The DER-encoded users certificate. If this option
-      is supplied, it overrides option <c>certfile</c>.</p></item>
-      
-      <tag><c>{certfile, path()}</c></tag>
-      <item><p>Path to a file containing the user certificate.</p></item>
-      
-      <tag>
-	<marker id="key_option_def"/>
-	<c>{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()}</c></tag>
-      <item><p>The DER-encoded user's private key or a map refering to a crypto
-      engine and its key reference that optionally can be password protected,
-      seealso <seealso marker="crypto:crypto#engine_load-4"> crypto:engine_load/4
-      </seealso> and  <seealso marker="crypto:engine_load"> Crypto's Users Guide</seealso>. If this option 
-      is supplied, it overrides option <c>keyfile</c>.</p></item>
-      
-      <tag><c>{keyfile, path()}</c></tag>
-      <item><p>Path to the file containing the user's
-      private PEM-encoded key. As PEM-files can contain several
-      entries, this option defaults to the same file as given by
-      option <c>certfile</c>.</p></item>
-
-      <tag><c>{password, string()}</c></tag>
-      <item><p>String containing the user's password. Only used if the 
-      private keyfile is password-protected.</p></item>
-
-      <tag><c>{ciphers, ciphers()}</c></tag>
-      <item><p>Supported cipher suites. The function
-      <c>cipher_suites/0</c> can be used to find all ciphers that are
-      supported by default. <c>cipher_suites(all)</c> can be called
-      to find all available cipher suites. Pre-Shared Key 
-      (<url href="http://www.ietf.org/rfc/rfc4279.txt">RFC 4279</url> and
-      <url href="http://www.ietf.org/rfc/rfc5487.txt">RFC 5487</url>), 
-      Secure Remote Password 
-      (<url href="http://www.ietf.org/rfc/rfc5054.txt">RFC 5054</url>), RC4 cipher suites,
-      and anonymous cipher suites only work if explicitly enabled by
-      this option; they are supported/enabled by the peer also.
-      Anonymous cipher suites are supported for testing purposes
-      only and are not be used when security matters.</p></item>
-
-      <tag><c>{eccs, [named_curve()]}</c></tag>
-      <item><p> Allows to specify the order of preference for named curves
-      and to restrict their usage when using a cipher suite supporting them.
-      </p></item>
-
-      <tag><c>{secure_renegotiate, boolean()}</c></tag>
-      <item><p>Specifies if to reject renegotiation attempt that does
-      not live up to 
-      <url href="http://www.ietf.org/rfc/rfc5746.txt">RFC 5746</url>. 
-      By default <c>secure_renegotiate</c> is set to <c>true</c>, 
-      that is, secure renegotiation is enforced. If set to <c>false</c> secure renegotiation
-      will still be used if possible,
-      but it falls back to insecure renegotiation if the peer
-      does not support 
-      <url href="http://www.ietf.org/rfc/rfc5746.txt">RFC 5746</url>.</p>
-      </item>
-
-      <tag><c>{depth, integer()}</c></tag>
-      <item><p>Maximum number of non-self-issued
+    <datatype>
+      <name name="common_option"/>
+    </datatype>
+    
+    <datatype>
+      <name since="OTP 20" name="protocol"/>
+      <desc>
+	<p>Choose TLS or DTLS protocol for the transport layer security.
+	Defaults to <c>tls</c>. For DTLS other transports than UDP are not yet supported.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="handshake_completion"/>
+      <desc>
+	<p>Defaults to <c>full</c>. If hello is specified the handshake will
+	pause after the hello message and give the user a possibility make decisions
+	based on hello extensions before continuing or aborting the handshake by calling
+	<seealso marker="#handshake_continue-3"> handshake_continue/3</seealso> or
+	<seealso marker="#handshake_cancel-1"> handshake_cancel/1</seealso></p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="cert"/>
+      <desc>
+	<p>The DER-encoded users certificate. If this option
+	is supplied, it overrides option <c>certfile</c>.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="cert_pem"/>
+      <desc>
+	<p>Path to a file containing the user certificate on PEM format.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="key"/>
+      <desc>
+	<p>The DER-encoded user's private key or a map refering to a crypto
+	engine and its key reference that optionally can be password protected,
+	seealso <seealso marker="crypto:crypto#engine_load-4"> crypto:engine_load/4
+	</seealso> and  <seealso marker="crypto:engine_load"> Crypto's Users Guide</seealso>. If this option 
+	is supplied, it overrides option <c>keyfile</c>.</p>
+      </desc>
+    </datatype>
+    
+     <datatype>
+       <name name="key_pem"/>
+       <desc>
+	<p>Path to the file containing the user's
+	private PEM-encoded key. As PEM-files can contain several
+	entries, this option defaults to the same file as given by
+	option <c>certfile</c>.</p>
+       </desc>
+     </datatype>
+     
+    <datatype>
+      <name name="key_password"/>
+      <desc>
+	<p>String containing the user's password. Only used if the 
+	private keyfile is password-protected.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="cipher_suites"/>
+      <desc>
+	<p>Supported cipher suites. The function
+	<c>cipher_suites/2</c> can be used to find all ciphers that
+	are supported by default. <c>cipher_suites(all, 'tlsv1.2')</c> can be
+	called to find all available cipher suites. Pre-Shared Key
+	(<url href="http://www.ietf.org/rfc/rfc4279.txt">RFC
+	4279</url> and <url
+	href="http://www.ietf.org/rfc/rfc5487.txt">RFC 5487</url>),
+	Secure Remote Password (<url
+	href="http://www.ietf.org/rfc/rfc5054.txt">RFC 5054</url>),
+	RC4, 3DES, DES cipher suites, and anonymous cipher suites only work if
+	explicitly enabled by this option; they are supported/enabled
+	by the peer also.  Anonymous cipher suites are supported for
+	testing purposes only and are not be used when security
+	matters.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="eccs"/>
+      <desc><p> Allows to specify the order of preference for named curves
+      and to restrict their usage when using a cipher suite supporting them.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="secure_renegotiation"/>
+      <desc><p>Specifies if to reject renegotiation attempt that does
+      not live up to <url
+      href="http://www.ietf.org/rfc/rfc5746.txt">RFC 5746</url>.  By
+      default <c>secure_renegotiate</c> is set to <c>true</c>, that
+      is, secure renegotiation is enforced. If set to <c>false</c>
+      secure renegotiation will still be used if possible, but it
+      falls back to insecure renegotiation if the peer does not
+      support <url href="http://www.ietf.org/rfc/rfc5746.txt">RFC
+      5746</url>.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="allowed_cert_chain_length"/>
+      <desc><p>Maximum number of non-self-issued
       intermediate certificates that can follow the peer certificate 
       in a valid certification path. So, if depth is 0 the PEER must 
       be signed by the trusted ROOT-CA directly; if 1 the path can 
       be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, 
-      ROOT-CA, and so on. The default value is 1.</p></item>
-
-      <tag><marker id="verify_fun"/><c>{verify_fun, {Verifyfun :: fun(), InitialUserState ::
-      term()}}</c></tag>
-      <item><p>The verification fun is to be defined as follows:</p>
+      ROOT-CA, and so on. The default value is 1.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="custom_verify"/>
+      <desc>
+	<p>The verification fun is to be defined as follows:</p>
 
 	<code>
 fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revoked,
@@ -334,20 +375,21 @@ atom()}} |
 
 	<p>The verification fun is called during the X509-path
 	validation when an error or an extension unknown to the SSL
-	application is encountered. It is also called
-	when a certificate is considered valid by the path validation
-	to allow access to each certificate in the path to the user
-	application. It differentiates between the peer
-	certificate and the CA certificates by using <c>valid_peer</c> or
-	<c>valid</c> as second argument to the verification fun. See the
-	<seealso marker="public_key:public_key_records">public_key User's
-	Guide</seealso> for definition of <c>#'OTPCertificate'{}</c> and
-	<c>#'Extension'{}</c>.</p>
+	application is encountered. It is also called when a
+	certificate is considered valid by the path validation to
+	allow access to each certificate in the path to the user
+	application. It differentiates between the peer certificate
+	and the CA certificates by using <c>valid_peer</c> or
+	<c>valid</c> as second argument to the verification fun. See
+	the <seealso marker="public_key:public_key_records">public_key
+	User's Guide</seealso> for definition of
+	<c>#'OTPCertificate'{}</c> and <c>#'Extension'{}</c>.</p>
 
 	<list type="bulleted">
-	  <item><p>If the verify callback fun returns <c>{fail, Reason}</c>,
-	  the verification process is immediately stopped, an alert is
-	  sent to the peer, and the TLS/DTLS handshake terminates.</p></item>
+	  <item><p>If the verify callback fun returns <c>{fail,
+	  Reason}</c>, the verification process is immediately
+	  stopped, an alert is sent to the peer, and the TLS/DTLS
+	  handshake terminates.</p></item>
 	  <item><p>If the verify callback fun returns <c>{valid, UserState}</c>,
 	  the verification process continues.</p></item> 
 	  <item><p>If the verify callback fun always returns
@@ -397,10 +439,12 @@ atom()}} |
 
       <taglist>
 	<tag><c>unknown_ca</c></tag>
-	<item><p>No trusted CA was found in the trusted store. The trusted CA is
-	normally a so called ROOT CA, which is a self-signed certificate. Trust can
-	be claimed for an intermediate CA (trusted anchor does not have to be
-	self-signed according to X-509) by using option <c>partial_chain</c>.</p>
+	<item><p>No trusted CA was found in the trusted store. The
+	trusted CA is normally a so called ROOT CA, which is a
+	self-signed certificate. Trust can be claimed for an
+	intermediate CA (trusted anchor does not have to be
+	self-signed according to X-509) by using option
+	<c>partial_chain</c>.</p>
 	</item>
 
 	<tag><c>selfsigned_peer</c></tag>
@@ -411,15 +455,17 @@ atom()}} |
 marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_validation/3</seealso>
 	</p></item>
       </taglist>
-      </item>
-
-      <tag><c>{crl_check, boolean() | peer | best_effort }</c></tag>
-      <item>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="crl_check"/>
+      <desc>
 	<p>Perform CRL (Certificate Revocation List) verification
 	<seealso marker="public_key:public_key#pkix_crls_validate-3">
-	(public_key:pkix_crls_validate/3)</seealso> on all the certificates during the path validation
-	<seealso
-	    marker="public_key:public_key#pkix_path_validation-3">(public_key:pkix_path_validation/3)
+	(public_key:pkix_crls_validate/3)</seealso> on all the
+	certificates during the path validation <seealso
+	marker="public_key:public_key#pkix_path_validation-3">(public_key:pkix_path_validation/3)
 	</seealso>
 	of the certificate chain. Defaults to <c>false</c>.</p>
 	
@@ -431,106 +477,104 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
 	  <item>if certificate revocation status cannot be determined
 	  it will be accepted as valid.</item>
 	</taglist>
-
+	
 	<p>The CA certificates specified for the connection will be used to 
 	construct the certificate chain validating the CRLs.</p>
  	
 	<p>The CRLs will be fetched from a local or external cache. See
 	<seealso marker="ssl:ssl_crl_cache_api">ssl_crl_cache_api(3)</seealso>.</p>
-      </item>
-
-      <tag><c>{crl_cache, {Module :: atom(), {DbHandle :: internal | term(), Args :: list()}}}</c></tag>
-      <item>
-	<p>Specify how to perform lookup and caching of certificate revocation lists.
-	<c>Module</c> defaults to <seealso marker="ssl:ssl_crl_cache">ssl_crl_cache</seealso>
-	with <c> DbHandle </c> being <c>internal</c> and an
-	empty argument list.</p>
-
-	<p>There are two implementations available:</p>
-
-	<taglist>
-	  <tag><c>ssl_crl_cache</c></tag>
-	  <item>
-	    <p>This module maintains a cache of CRLs.  CRLs can be
-	    added to the cache using the function <seealso
-	    marker="ssl:ssl_crl_cache#insert-1">ssl_crl_cache:insert/1</seealso>,
-	    and optionally automatically fetched through HTTP if the
-	    following argument is specified:</p>
-
-	    <taglist>
-	      <tag><c>{http, timeout()}</c></tag>
-	      <item><p>
-		Enables fetching of CRLs specified as http URIs in<seealso
-		marker="public_key:public_key_records">X509 certificate extensions</seealso>.
-		Requires the OTP inets application.</p>
-	      </item>
-	    </taglist>
-	  </item>
-
-	  <tag><c>ssl_crl_hash_dir</c></tag>
-	  <item>
-	    <p>This module makes use of a directory where CRLs are
-	    stored in files named by the hash of the issuer name.</p>
-
-	    <p>The file names consist of eight hexadecimal digits
-	    followed by <c>.rN</c>, where <c>N</c> is an integer,
-	    e.g. <c>1a2b3c4d.r0</c>.  For the first version of the
-	    CRL, <c>N</c> starts at zero, and for each new version,
-	    <c>N</c> is incremented by one.  The OpenSSL utility
-	    <c>c_rehash</c> creates symlinks according to this
-	    pattern.</p>
-
-	    <p>For a given hash value, this module finds all
-	    consecutive <c>.r*</c> files starting from zero, and those
-	    files taken together make up the revocation list.  CRL
-	    files whose <c>nextUpdate</c> fields are in the past, or
-	    that are issued by a different CA that happens to have the
-	    same name hash, are excluded.</p>
-
-	    <p>The following argument is required:</p>
-
-	    <taglist>
-	      <tag><c>{dir, string()}</c></tag>
-	      <item><p>Specifies the directory in which the CRLs can be found.</p></item>
-	    </taglist>
-
-	  </item>
-
-	  <tag><c>max_handshake_size</c></tag>
-	  <item>
-	    <p>Integer (24 bits unsigned). Used to limit the size of
-	    valid TLS handshake packets to avoid DoS attacks.
-	    Defaults to 256*1024.</p>
-          </item>
-          
-	</taglist>
-
-      </item>
+      </desc>
+    </datatype>
 
-      <tag><c>{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} |
-      unknown_ca }</c></tag>
-      <item><p>Claim an intermediate CA in the chain as trusted. TLS then
-      performs <seealso
-      marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_validation/3</seealso>
-      with the selected CA as trusted anchor and the rest of the chain.</p></item>
+    <datatype>
+      <name name="crl_cache_opts"/>
+      <desc>
+    	<p>Specify how to perform lookup and caching of certificate revocation lists.
+    	<c>Module</c> defaults to <seealso marker="ssl:ssl_crl_cache">ssl_crl_cache</seealso>
+    	with <c> DbHandle </c> being <c>internal</c> and an
+    	empty argument list.</p>
+	
+    	<p>There are two implementations available:</p>
+	
+    	<taglist>
+    	  <tag><c>ssl_crl_cache</c></tag>
+    	  <item>
+    	    <p>This module maintains a cache of CRLs.  CRLs can be
+    	    added to the cache using the function <seealso
+    	    marker="ssl:ssl_crl_cache#insert-1">ssl_crl_cache:insert/1</seealso>,
+    	    and optionally automatically fetched through HTTP if the
+    	    following argument is specified:</p>
+	    
+    	    <taglist>
+    	      <tag><c>{http, timeout()}</c></tag>
+    	      <item><p>
+    		Enables fetching of CRLs specified as http URIs in<seealso
+    		marker="public_key:public_key_records">X509 certificate extensions</seealso>.
+    		Requires the OTP inets application.</p>
+    	      </item>
+    	    </taglist>
+    	  </item>
+	  
+    	  <tag><c>ssl_crl_hash_dir</c></tag>
+    	  <item>
+    	    <p>This module makes use of a directory where CRLs are
+    	    stored in files named by the hash of the issuer name.</p>
+
+    	    <p>The file names consist of eight hexadecimal digits
+    	    followed by <c>.rN</c>, where <c>N</c> is an integer,
+    	    e.g. <c>1a2b3c4d.r0</c>.  For the first version of the
+    	    CRL, <c>N</c> starts at zero, and for each new version,
+    	    <c>N</c> is incremented by one.  The OpenSSL utility
+    	    <c>c_rehash</c> creates symlinks according to this
+    	    pattern.</p>
+
+    	    <p>For a given hash value, this module finds all
+    	    consecutive <c>.r*</c> files starting from zero, and those
+    	    files taken together make up the revocation list.  CRL
+    	    files whose <c>nextUpdate</c> fields are in the past, or
+    	    that are issued by a different CA that happens to have the
+    	    same name hash, are excluded.</p>
+	    
+    	    <p>The following argument is required:</p>
+
+    	    <taglist>
+    	      <tag><c>{dir, string()}</c></tag>
+    	      <item><p>Specifies the directory in which the CRLs can be found.</p></item>
+    	    </taglist>
+    	  </item>
+	  </taglist>
+	</desc>
+    </datatype>
+
+    <datatype>
+      <name name="root_fun"/>
+      <desc>
+	<code>
+fun(Chain::[public_key:der_encoded()]) ->
+	{trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca}
+	</code>
+	<p>Claim an intermediate CA in the chain as trusted. TLS then
+	performs <seealso
+	marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_validation/3</seealso>
+	with the selected CA as trusted anchor and the rest of the chain.</p>
+      </desc>
+    </datatype>
 
-      <tag><c>{versions, [protocol_version()]}</c></tag>
 
-      <item><p>TLS protocol versions supported by started clients and servers.
+    <datatype>
+      <name name="protocol_versions"/>
+      <desc><p>TLS protocol versions supported by started clients and servers.
       This option overrides the application environment option
       <c>protocol_version</c> and  <c>dtls_protocol_version</c>. If the environment option is not set, it defaults
       to all versions, except SSL-3.0, supported by the SSL application.
-      See also <seealso marker="ssl:ssl_app">ssl(6).</seealso></p></item>
+      See also <seealso marker="ssl:ssl_app">ssl(6).</seealso></p>
+      </desc>
+    </datatype>
 
-      <tag><c>{hibernate_after, integer()|undefined}</c></tag>
-      <item><p>When an integer-value is specified, <c>TLS/DTLS-connection</c>
-      goes into hibernation after the specified number of milliseconds
-      of inactivity, thus reducing its memory footprint. When
-      <c>undefined</c> is specified (this is the default), the process
-      never goes into hibernation.</p></item>
 
-      <tag><c>{user_lookup_fun, {Lookupfun :: fun(), UserState :: term()}}</c></tag>
-      <item><p>The lookup fun is to defined as follows:</p>
+      <datatype>
+      <name name="custom_user_lookup"/>
+      <desc><p>The lookup fun is to defined as follows:</p>
 
 	<code>
 fun(psk, PSKIdentity ::string(), UserState :: term()) ->
@@ -552,20 +596,54 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	<url href="http://tools.ietf.org/html/rfc5054#section-2.4"> RFC 5054</url>:
 	<c>crypto:sha([Salt, crypto:sha([Username, &lt;&lt;$:&gt;&gt;, Password])])</c>
 	</p>
-      </item>
+      </desc>
+    </datatype>
 
-      <tag><c>{padding_check, boolean()}</c></tag>
-      <item><p>Affects TLS-1.0 connections only.
+    <datatype>
+      <name name="session_id"/>
+      <desc>
+	<p>Identifies a TLS session.</p>
+      </desc>
+    </datatype>
+    
+  <datatype>    
+    <name name="log_alert"/> 
+    <desc><p>If set to <c>false</c>, error reports are not displayed.</p> 
+    </desc> 
+    </datatype> 
+    
+    <datatype>    
+    <name name="hibernate_after"/> 
+    <desc><p>When an integer-value is specified, <c>TLS/DTLS-connection</c> 
+    goes into hibernation after the specified number of milliseconds 
+    of inactivity, thus reducing its memory footprint. When
+    <c>undefined</c> is specified (this is the default), the process 
+    never goes into hibernation.</p> 
+    </desc> 
+    </datatype> 
+
+    <datatype>
+      <name name="handshake_size"/>
+      <desc>
+    	<p>Integer (24 bits unsigned). Used to limit the size of
+    	valid TLS handshake packets to avoid DoS attacks.
+    	Defaults to 256*1024.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="padding_check"/>
+      <desc><p>Affects TLS-1.0 connections only.
       If set to <c>false</c>, it disables the block cipher padding check
       to be able to interoperate with legacy software.</p>
       <warning><p>Using <c>{padding_check, boolean()}</c> makes TLS
 	vulnerable to the Poodle attack.</p></warning>
-      </item>
-
-      
+      </desc>
+    </datatype>
 
-      <tag><c>{beast_mitigation, one_n_minus_one | zero_n | disabled}</c></tag>
-      <item><p>Affects SSL-3.0 and TLS-1.0 connections only. Used to change the BEAST
+    <datatype>
+      <name name="beast_mitigation"/>
+      <desc><p>Affects SSL-3.0 and TLS-1.0 connections only. Used to change the BEAST
        mitigation strategy to interoperate with legacy software.
        Defaults to <c>one_n_minus_one</c>.</p>
 
@@ -575,139 +653,166 @@ fun(srp, Username :: string(), UserState :: term()) ->
 
       <p><c>disabled</c> - Disable BEAST mitigation.</p>
 
-      <warning><p>Using <c>{beast_mitigation, disabled}</c> makes SSL or TLS
+      <warning><p>Using <c>{beast_mitigation, disabled}</c> makes SSL-3.0 or TLS-1.0
         vulnerable to the BEAST attack.</p></warning>
-      </item>
-      </taglist>
-
-  </section>
-  
-  <section>
-    <title>TLS/DTLS OPTION DESCRIPTIONS - CLIENT SIDE</title>
-
-    <p>The following options are client-specific or have a slightly different
-    meaning in the client than in the server:</p>
+      </desc>
+    </datatype>
+    
 
-    <taglist>
+    <datatype_title>TLS/DTLS OPTION DESCRIPTIONS - CLIENT</datatype_title>
+    
+    <datatype>
+      <name name="client_option"/>
+    </datatype>
+   
+     <datatype>
+      <name name="client_verify_type"/>
+      <desc><p>In mode <c>verify_none</c> the default behavior is to allow
+      all x509-path validation errors. See also option  <seealso marker="#type-custom_verify">verify_fun</seealso>.</p>
+      </desc>
+    </datatype>
 
-      <tag><c>{verify, verify_type()}</c></tag>
-      <item><p>In mode <c>verify_none</c> the default behavior is to allow
-      all x509-path validation errors. See also option <c>verify_fun</c>.</p>
-      </item>
-      
-      <tag><marker id="client_reuse_session"/><c>{reuse_session, binary()}</c></tag>
-      <item><p>Reuses a specific session earlier saved with the option
-      <c>{reuse_sessions, save} since ssl-9.2</c>
-      </p></item>
+    <datatype>
+      <name name="client_reuse_session"/>
+      <desc>
+	<p>Reuses a specific session earlier saved with the option
+	<c>{reuse_sessions, save} since OTP-21.3 </c>
+      </p>
+      </desc>
+    </datatype>
 
-      <tag><c>{reuse_sessions, boolean() | save}</c></tag>
-      <item><p>When <c>save</c> is specified a new connection will be negotiated
+    <datatype>
+      <name name="client_reuse_sessions"/>
+      <desc>
+	<p>When <c>save</c> is specified a new connection will be negotiated
       and saved for later reuse. The session ID can be fetched with 
-      <seealso marker="#connection_information">connection_information/2</seealso>
-      and used with the client option <seealso marker="#client_reuse_session">reuse_session</seealso>
+      <seealso marker="#connection_information-2">connection_information/2</seealso>
+      and used with the client option <seealso marker="#type-client_reuse_session">reuse_session</seealso>
       The boolean value true specifies that if possible, automatized session reuse will
       be performed. If a new session is created, and is unique in regard 
-      to previous stored sessions, it will be saved for possible later reuse.
-      Value <c>save</c> since ssl-9.2
-      </p></item>
-      
-      <tag><c>{cacerts, [public_key:der_encoded()]}</c></tag>
-      <item><p>The DER-encoded trusted certificates. If this option
-      is supplied it overrides option <c>cacertfile</c>.</p></item>
-      
-      <tag><c>{cacertfile, path()}</c></tag>
-      <item><p>Path to a file containing PEM-encoded CA certificates. The CA
+      to previous stored sessions, it will be saved for possible later reuse. Since OTP-21.3</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="client_cacerts"/>
+      <desc>
+	<p>The DER-encoded trusted certificates. If this option
+      is supplied it overrides option <c>cacertfile</c>.</p>
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="client_cafile"/>
+      <desc>
+	<p>Path to a file containing PEM-encoded CA certificates. The CA
       certificates are used during server authentication and when building the
       client certificate chain.</p>
-    </item>
-
-      <tag><c>{alpn_advertised_protocols, [binary()]}</c></tag>
-      <item>
-      <p>The list of protocols supported by the client to be sent to the
-      server to be used for an Application-Layer Protocol Negotiation (ALPN).
-      If the server supports ALPN then it will choose a protocol from this
-      list; otherwise it will fail the connection with a "no_application_protocol"
-      alert. A server that does not support ALPN will ignore this value.</p>
-
-      <p>The list of protocols must not contain an empty binary.</p>
-
-      <p>The negotiated protocol can be retrieved using the <c>negotiated_protocol/1</c> function.</p>
-      </item>
-
-      <tag><c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()]}}</c><br/>
-      <c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()], Default :: binary()}}</c></tag>
-	   <item>
-	   <p>Indicates that the client is to try to perform Next Protocol
-	   Negotiation.</p>
-
-	   <p>If precedence is server, the negotiated protocol is the
-	   first protocol to be shown on the server advertised list, which is
-	   also on the client preference list.</p>
-
-	   <p>If precedence is client, the negotiated protocol is the
-	   first protocol to be shown on the client preference list, which is
-	   also on the server advertised list.</p>
-
-	   <p>If the client does not support any of the server advertised
-	   protocols or the server does not advertise any protocols, the
-	   client falls back to the first protocol in its list or to the
-	   default protocol (if a default is supplied). If the
-	   server does not support Next Protocol Negotiation, the
-	   connection terminates if no default protocol is supplied.</p>
-	   </item>
-
-      <tag><c>{psk_identity, string()}</c></tag>
-      <item><p>Specifies the identity the client presents to the server.
-      The matching secret is found by calling <c>user_lookup_fun</c>.</p>
-      </item>
-
-      <tag><c>{srp_identity, {Username :: string(), Password :: string()}
-      </c></tag>
-      <item><p>Specifies the username and password to use to authenticate
-      to the server.</p></item>
-
-      <tag><c>{server_name_indication, HostName :: hostname()}</c></tag>
-      <item><p>Specify the hostname to be used in TLS Server Name Indication extension.
-      If not specified it will default to the <c>Host</c> argument of <seealso marker="#connect-3">connect/[3,4]</seealso>
-      unless it is of type inet:ipaddress().</p>
-      <p>
-	The <c>HostName</c> will also be used in the hostname verification of the peer certificate using
-	<seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso>.
-      </p>
-      </item>
-      <tag><c>{server_name_indication, disable}</c></tag>
-	<item>
-          <p> Prevents the Server Name Indication extension from being sent and
-	  disables the hostname verification check
-	  <seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso> </p>
-	</item>
-
-	<tag><c>{customize_hostname_check, Options::list()}</c></tag>
-	<item>
-          <p> Customizes the hostname verification of the peer certificate, as different protocols that use
+      </desc>
+    </datatype>
+    
+    <datatype>
+      <name name="client_alpn"/>
+      <desc>
+	<p>The list of protocols supported by the client to be sent to the
+	server to be used for an Application-Layer Protocol Negotiation (ALPN).
+	If the server supports ALPN then it will choose a protocol from this
+	list; otherwise it will fail the connection with a "no_application_protocol"
+	alert. A server that does not support ALPN will ignore this value.</p>
+	
+	<p>The list of protocols must not contain an empty binary.</p>
+	
+	<p>The negotiated protocol can be retrieved using the <c>negotiated_protocol/1</c> function.</p>
+      </desc>
+    </datatype>
+    
+   <datatype>
+      <name name="client_preferred_next_protocols"/>
+      <desc>
+	<p>Indicates that the client is to try to perform Next Protocol
+	Negotiation.</p>
+	
+	<p>If precedence is server, the negotiated protocol is the
+	first protocol to be shown on the server advertised list, which is
+	also on the client preference list.</p>
+	
+	<p>If precedence is client, the negotiated protocol is the
+	first protocol to be shown on the client preference list, which is
+	also on the server advertised list.</p>
+	
+	<p>If the client does not support any of the server advertised
+	protocols or the server does not advertise any protocols, the
+	client falls back to the first protocol in its list or to the
+	default protocol (if a default is supplied). If the
+	server does not support Next Protocol Negotiation, the
+	connection terminates if no default protocol is supplied.</p>
+      </desc>
+   </datatype>
+   
+   <datatype>
+      <name name="client_psk_identity"/>
+      <desc>
+	<p>Specifies the identity the client presents to the server.
+	The matching secret is found by calling <c>user_lookup_fun</c></p>
+      </desc>
+      </datatype>
+
+      <datatype>
+	<name name="client_srp_identity"/>
+	<desc>
+	  <p>Specifies the username and password to use to authenticate
+	  to the server.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+      <name name="sni"/>
+      <desc>
+	<p>Specify the hostname to be used in TLS Server Name Indication extension.
+	If not specified it will default to the <c>Host</c> argument of <seealso marker="#connect-3">connect/[3,4]</seealso>
+	unless it is of type inet:ipaddress().</p>
+	<p>
+	  The <c>HostName</c> will also be used in the hostname verification of the peer certificate using
+	  <seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso>.
+	</p>
+	<p> The special value <c>disable</c> prevents the Server Name Indication extension from being sent and
+	disables the hostname verification check
+	<seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso> </p>
+      </desc>
+      </datatype>
+         
+      <datatype>
+	<name name="customize_hostname_check"/>
+	<desc>
+	  <p> Customizes the hostname verification of the peer certificate, as different protocols that use
 	  TLS such as HTTP or LDAP may want to do it differently, for possible options see
 	  <seealso marker="public_key:public_key#pkix_verify_hostname-3">public_key:pkix_verify_hostname/3</seealso> </p>
-	</item>
-
-      <tag><c>{fallback, boolean()}</c></tag>
-      <item>
-	<p> Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired TLS version downgrade.
-	Defaults to false</p>
-	<warning><p>Note this option is not needed in normal TLS usage and should not be used
-	to implement new clients. But legacy clients that retries connections in the following manner</p>
-
-	<p><c> ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1', 'tlsv1', 'sslv3']}])</c></p>
-	<p><c>  ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1', 'sslv3']}, {fallback, true}])</c></p>
-	<p><c>  ssl:connect(Host, Port, [...{versions, ['tlsv1', 'sslv3']}, {fallback, true}]) </c></p>
-	<p><c>  ssl:connect(Host, Port, [...{versions, ['sslv3']}, {fallback, true}]) </c></p>
-	 
-	 <p>may use it to avoid undesired TLS version downgrade. Note that TLS_FALLBACK_SCSV must also
-	 be supported by the server for the prevention to work.
-	</p></warning>
-      </item>
-      <tag><marker id="client_signature_algs"/><c>{signature_algs, [{hash(), ecdsa | rsa | dsa}]}</c></tag>
-	<item>
-	<p>In addition to the algorithms negotiated by the cipher
+	</desc>
+      </datatype>
+      
+      <datatype>
+	<name name="fallback"/>
+	<desc>
+	  <p> Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired TLS version downgrade.
+	  Defaults to false</p>
+	  <warning><p>Note this option is not needed in normal TLS usage and should not be used
+	  to implement new clients. But legacy clients that retries connections in the following manner</p>
+	  
+	  <p><c> ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1', 'tlsv1', 'sslv3']}])</c></p>
+	  <p><c>  ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1', 'sslv3']}, {fallback, true}])</c></p>
+	  <p><c>  ssl:connect(Host, Port, [...{versions, ['tlsv1', 'sslv3']}, {fallback, true}]) </c></p>
+	  <p><c>  ssl:connect(Host, Port, [...{versions, ['sslv3']}, {fallback, true}]) </c></p>
+	  
+	  <p>may use it to avoid undesired TLS version downgrade. Note that TLS_FALLBACK_SCSV must also
+	  be supported by the server for the prevention to work.
+	  </p></warning>
+	</desc>
+      </datatype>
+      
+      <datatype>
+	<name name="client_signature_algs"/>
+	<desc>
+	  <p>In addition to the algorithms negotiated by the cipher
 	suite used for key exchange, payload encryption, message
 	authentication and pseudo random calculation, the TLS signature
 	algorithm extension <url
@@ -738,209 +843,227 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	Selected signature algorithm can restrict which hash functions
 	that may be selected. Default support for {md5, rsa} removed in ssl-8.0
 	</p>
-	</item>
-	<tag><marker id="signature_algs_cert"/><c>{signature_algs_cert, [signature_scheme()]}</c></tag>
-	<item>
-	  <p>
-	    In addition to the signature_algorithms extension from TLS 1.2,
-	    <url href="http://www.ietf.org/rfc/rfc8446.txt#section-4.2.3">TLS 1.3
-	    (RFC 5246 Section 4.2.3)</url>adds the signature_algorithms_cert extension
-	    which enables having special requirements on the signatures used in the
-	    certificates that differs from the requirements on digital signatures as a whole.
-	    If this is not required this extension is not needed.
-	  </p>
-	  <p>
-	    The client will send a signature_algorithms_cert extension (ClientHello),
-	    if TLS version 1.3 or later is used, and the signature_algs_cert option is
-	    explicitly specified. By default, only the signature_algs extension is sent.
-	  </p>
-	  <p>
-	    The signature schemes shall be ordered according to the client's preference
-	    (favorite choice first).
-	  </p>
-	</item>
-      </taglist>
-   </section>
-   
-  <section>
-    <title>TLS/DTLS OPTION DESCRIPTIONS - SERVER SIDE</title>
-
-    <p>The following options are server-specific or have a slightly different
-    meaning in the server than in the client:</p>
-
-    <taglist>
-
-      <tag><c>{cacerts, [public_key:der_encoded()]}</c></tag>
-      <item><p>The DER-encoded trusted certificates. If this option
-      is supplied it overrides option <c>cacertfile</c>.</p></item>
+	</desc>
+      </datatype>
       
-      <tag><c>{cacertfile, path()}</c></tag>
-      <item><p>Path to a file containing PEM-encoded CA
-      certificates. The CA certificates are used to build the server
-      certificate chain and for client authentication. The CAs are
-      also used in the list of acceptable client CAs passed to the
-      client when a certificate is requested. Can be omitted if there
-      is no need to verify the client and if there are no
-      intermediate CAs for the server certificate.</p></item>
-  
-      <tag><c>{dh, public_key:der_encoded()}</c></tag>
-      <item><p>The DER-encoded Diffie-Hellman parameters. If specified,
-      it overrides option <c>dhfile</c>.</p></item>
-
-      <tag><c>{dhfile, path()}</c></tag>
-      <item><p>Path to a file containing PEM-encoded Diffie Hellman parameters
-      to be used by the server if a cipher suite using Diffie Hellman key
-      exchange is negotiated. If not specified, default parameters are used.
-      </p></item>
-
-      <tag><c>{verify, verify_type()}</c></tag>
-      <item><p>A server only does x509-path validation in mode <c>verify_peer</c>,
-      as it then sends a certificate request to the client
-      (this message is not sent if the verify option is <c>verify_none</c>).
-      You can then also want to specify option <c>fail_if_no_peer_cert</c>.
-      </p></item>
-
-      <tag><c>{fail_if_no_peer_cert, boolean()}</c></tag>
-      <item><p>Used together with <c>{verify, verify_peer}</c> by an TLS/DTLS server.
-      If set to <c>true</c>, the server fails if the client does not have
-      a certificate to send, that is, sends an empty certificate. If set to
-      <c>false</c>, it fails only if the client sends an invalid
-      certificate (an empty certificate is considered valid). Defaults to false.</p>
-      </item>
-
-      <tag><c>{reuse_sessions, boolean()}</c></tag>
-      <item><p>The boolean value true specifies that the server will
-      agree to reuse sessions. Setting it to false will result in an empty
-      session table, that is no sessions will be reused. 
-      See also option <seealso marker="#server_reuse_session">reuse_session</seealso>
-      </p></item>
-
-      <tag><marker id="server_reuse_session"/>
-      <c>{reuse_session, fun(SuggestedSessionId,
-      PeerCert, Compression, CipherSuite) -> boolean()}</c></tag>
-      <item><p>Enables the TLS/DTLS server to have a local policy
-      for deciding if a session is to be reused or not.
-      Meaningful only if <c>reuse_sessions</c> is set to <c>true</c>.
-      <c>SuggestedSessionId</c> is a <c>binary()</c>, <c>PeerCert</c> is
-      a DER-encoded certificate, <c>Compression</c> is an enumeration integer,
-      and <c>CipherSuite</c> is of type <c>ciphersuite()</c>.</p></item>
-
-      <tag><c>{alpn_preferred_protocols, [binary()]}</c></tag>
-      <item>
-      <p>Indicates the server will try to perform Application-Layer
-      Protocol Negotiation (ALPN).</p>
-
-      <p>The list of protocols is in order of preference. The protocol
-      negotiated will be the first in the list that matches one of the
-      protocols advertised by the client. If no protocol matches, the
-      server will fail the connection with a "no_application_protocol" alert.</p>
-
-      <p>The negotiated protocol can be retrieved using the <c>negotiated_protocol/1</c> function.</p>
-      </item>
-
-      <tag><c>{next_protocols_advertised, Protocols :: [binary()]}</c></tag>
-      <item><p>List of protocols to send to the client if the client indicates that
-      it supports the Next Protocol extension. The client can select a protocol
-      that is not on this list. The list of protocols must not contain an empty
-      binary. If the server negotiates a Next Protocol, it can be accessed
-      using the <c>negotiated_next_protocol/1</c> method.</p></item>
-
-      <tag><c>{psk_identity, string()}</c></tag>
-      <item><p>Specifies the server identity hint, which the server presents to
-      the client.</p></item>
-
-      <tag><c>{log_alert, boolean()}</c></tag>
-      <item><p>If set to <c>false</c>, error reports are not displayed.</p>
-      <p>Deprecated in OTP 22, use <seealso marker="#log_level">log_level</seealso> instead.</p>
-      </item>
-
-      <tag><marker id="log_level"/><c>{log_level, atom()}</c></tag>
-      <item><p>Specifies the log level for TLS/DTLS. It can take the following
-      values (ordered by increasing verbosity level): <c>emergency, alert, critical, error,
-      warning, notice, info, debug.</c></p>
-      <p>At verbosity level <c>notice</c> and above error reports are
-      displayed in TLS. The level <c>debug</c> triggers verbose logging of TLS protocol
-      messages and logging of ignored alerts in DTLS.</p></item>
-
-      <tag><c>{honor_cipher_order, boolean()}</c></tag>
-      <item><p>If set to <c>true</c>, use the server preference for cipher
-      selection. If set to <c>false</c> (the default), use the client
-      preference.</p></item>
-
-      <tag><c>{sni_hosts, [{hostname(), [ssl_option()]}]}</c></tag>
-      <item><p>If the server receives a SNI (Server Name Indication) from the client
-      matching a host listed in the <c>sni_hosts</c> option, the specific options for
-      that host will override previously specified options.
-
-      The option <c>sni_fun</c>, and <c>sni_hosts</c> are mutually exclusive.</p></item>
-
-      <tag><c>{sni_fun, SNIfun::fun()}</c></tag>
-      <item><p>If the server receives a SNI (Server Name Indication) from the client,
-      the given function will be called to retrieve <c>[ssl_option()]</c> for the indicated server.
-      These options will be merged into predefined <c>[ssl_option()]</c>.
-
-      The function should be defined as:
-        <c>fun(ServerName :: string()) -> [ssl_option()]</c>
-      and can be specified as a fun or as named <c>fun module:function/1</c>
-
-      The option <c>sni_fun</c>, and <c>sni_hosts</c> are mutually exclusive.</p></item>
-
-      <tag><c>{client_renegotiation, boolean()}</c></tag>
-      <item>In protocols that support client-initiated renegotiation, the cost
-      of resources of such an operation is higher for the server than the
-      client. This can act as a vector for denial of service attacks. The SSL
-      application already takes measures to counter-act such attempts,
-      but client-initiated renegotiation can be strictly disabled by setting
-      this option to <c>false</c>. The default value is <c>true</c>.
-      Note that disabling renegotiation can result in long-lived connections
-      becoming unusable due to limits on the number of messages the underlying
-      cipher suite can encipher.
-      </item>
-
-      <tag><c>{honor_cipher_order, boolean()}</c></tag>
-      <item>If true, use the server's preference for cipher selection. If false
-      (the default), use the client's preference.
-      </item>
+      <datatype_title>TLS/DTLS OPTION DESCRIPTIONS - SERVER </datatype_title>
+
+
+      <datatype>
+	<name name="server_option"/>
+      </datatype>
+     
+      <datatype>
+	<name name="server_cacerts"/>
+	<desc><p>The DER-encoded trusted certificates. If this option
+      is supplied it overrides option <c>cacertfile</c>.</p>
+	</desc>
+      </datatype>
+            
+      <datatype>
+	<name name="server_cafile"/>
+	<desc><p>Path to a file containing PEM-encoded CA
+	certificates. The CA certificates are used to build the server
+	certificate chain and for client authentication. The CAs are
+	also used in the list of acceptable client CAs passed to the
+	client when a certificate is requested. Can be omitted if
+	there is no need to verify the client and if there are no
+	intermediate CAs for the server certificate.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="dh_der"/>
+	<desc><p>The DER-encoded Diffie-Hellman parameters. If
+	specified, it overrides option <c>dhfile</c>.</p>
+	</desc>
+      </datatype>
+    
+      <datatype>
+	<name name="dh_file"/>
+	<desc><p>Path to a file containing PEM-encoded Diffie Hellman
+	parameters to be used by the server if a cipher suite using
+	Diffie Hellman key exchange is negotiated. If not specified,
+	default parameters are used.</p>
+	</desc>
+      </datatype>
+
+    <datatype>
+	<name name="server_verify_type"/>
+	<desc><p>A server only does x509-path validation in mode
+	<c>verify_peer</c>, as it then sends a certificate request to
+	the client (this message is not sent if the verify option is
+	<c>verify_none</c>).  You can then also want to specify option
+	<c>fail_if_no_peer_cert</c>. </p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="fail_if_no_peer_cert"/>
+	<desc><p>Used together with <c>{verify, verify_peer}</c> by an
+	TLS/DTLS server.  If set to <c>true</c>, the server fails if
+	the client does not have a certificate to send, that is, sends
+	an empty certificate. If set to <c>false</c>, it fails only if
+	the client sends an invalid certificate (an empty certificate
+	is considered valid). Defaults to false.</p>
+	</desc>
+      </datatype>
       
-      <tag><c>{honor_ecc_order, boolean()}</c></tag>
-      <item>If true, use the server's preference for ECC curve selection. If false
-      (the default), use the client's preference.
-      </item>
-
-      <tag><c>{signature_algs, [{hash(), ecdsa | rsa | dsa}]}</c></tag>
-      <item><p> The algorithms specified by
-      this option will be the ones accepted by the server in a signature algorithm
-      negotiation, introduced in TLS-1.2. The algorithms will also be offered to the client if a
-      client certificate is requested. For more details see the <seealso marker="#client_signature_algs">corresponding client option</seealso>.
-      </p> </item>
-    </taglist>
-  </section>
-  
-  <section>
-    <title>General</title>
+      <datatype>
+	<name name="server_reuse_sessions"/>
+	<desc><p>The boolean value true specifies that the server will
+	agree to reuse sessions. Setting it to false will result in an empty
+	session table, that is no sessions will be reused. 
+	See also option <seealso marker="#type-server_reuse_session">reuse_session</seealso>
+      </p>
+	</desc>
+      </datatype>
       
-    <p>When an TLS/DTLS socket is in active mode (the default), data from the
-      socket is delivered to the owner of the socket in the form of
-      messages:</p>
+      <datatype>
+	<name name="server_reuse_session"/>
+	<desc><p>Enables the TLS/DTLS server to have a local policy
+	for deciding if a session is to be reused or not.  Meaningful
+	only if <c>reuse_sessions</c> is set to <c>true</c>.
+	<c>SuggestedSessionId</c> is a <c>binary()</c>,
+	<c>PeerCert</c> is a DER-encoded certificate,
+	<c>Compression</c> is an enumeration integer, and
+	<c>CipherSuite</c> is of type <c>ciphersuite()</c>.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="server_alpn"/>
+	<desc>  
+	  <p>Indicates the server will try to perform
+	  Application-Layer Protocol Negotiation (ALPN).</p>
+	  
+	  <p>The list of protocols is in order of preference. The
+	  protocol negotiated will be the first in the list that
+	  matches one of the protocols advertised by the client. If no
+	  protocol matches, the server will fail the connection with a
+	  "no_application_protocol" alert.</p>
+	  
+	  <p>The negotiated protocol can be retrieved using the
+	  <c>negotiated_protocol/1</c> function.</p>
+	</desc>
+      </datatype>
+      
+      <datatype>
+	<name name="server_next_protocol"/>
+	<desc><p>List of protocols to send to the client if the client
+	indicates that it supports the Next Protocol extension. The
+	client can select a protocol that is not on this list. The
+	list of protocols must not contain an empty binary. If the
+	server negotiates a Next Protocol, it can be accessed using
+	the <c>negotiated_next_protocol/1</c> method.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="server_psk_identity"/>
+	<desc>
+	  <p>Specifies the server identity hint, which the server presents to
+	  the client.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="honor_cipher_order"/>
+	<desc>
+	  <p>If set to <c>true</c>, use the server preference for cipher
+	  selection. If set to <c>false</c> (the default), use the client
+	  preference.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="sni_hosts"/>
+	<desc><p>If the server receives a SNI (Server Name Indication) from the client
+	matching a host listed in the <c>sni_hosts</c> option, the specific options for
+	that host will override previously specified options.
+	
+	The option <c>sni_fun</c>, and <c>sni_hosts</c> are mutually exclusive.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="sni_fun"/>
+	<desc>
+	  <p>If the server receives a SNI (Server Name Indication)
+	  from the client, the given function will be called to
+	  retrieve <seealso marker="#type-server_option">[server_option()] </seealso> for the indicated server.
+	  These options will be merged into predefined
+	  <seealso marker="#type-server_option">[server_option()] </seealso> list.
+	  
+	  The function should be defined as:
+          fun(ServerName :: string()) -> <seealso marker="#type-server_option">[server_option()] </seealso>
+	  and can be specified as a fun or as named <c>fun module:function/1</c>
+	  
+	  The option <c>sni_fun</c>, and <c>sni_hosts</c> are mutually exclusive.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="client_renegotiation"/>
+	<desc><p>In protocols that support client-initiated
+	renegotiation, the cost of resources of such an operation is
+	higher for the server than the client. This can act as a
+	vector for denial of service attacks. The SSL application
+	already takes measures to counter-act such attempts, but
+	client-initiated renegotiation can be strictly disabled by
+	setting this option to <c>false</c>. The default value is
+	<c>true</c>.  Note that disabling renegotiation can result in
+	long-lived connections becoming unusable due to limits on the
+	number of messages the underlying cipher suite can
+	encipher.</p>
+	</desc>
+      </datatype>
+      
+      <datatype>
+	<name name="honor_cipher_order"/>
+	<desc><p>If true, use the server's preference for cipher
+	selection. If false (the default), use the client's
+	preference.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="honor_ecc_order"/>
+	<desc><p>If true, use the server's preference for ECC curve
+	selection. If false (the default), use the client's
+	preference.</p>
+	</desc>
+      </datatype>
+
+      <datatype>
+	<name name="server_signature_algs"/>
+	<desc><p> The algorithms specified by this option will be the
+	ones accepted by the server in a signature algorithm
+	negotiation, introduced in TLS-1.2. The algorithms will also
+	be offered to the client if a client certificate is
+	requested. For more details see the <seealso
+	marker="#type-client_signature_algs">corresponding client
+	option</seealso>.
+      </p>
+	</desc>
+      </datatype>
+    </datatypes>
 
-    <list type="bulleted">
-      <item><p><c>{ssl, Socket, Data}</c></p></item>
-      <item><p><c>{ssl_closed, Socket}</c></p></item>
-      <item><p><c>{ssl_error, Socket, Reason}</c></p></item>
-    </list>
+<!--
+    ================================================================
+    =  Function definitions                                        =
+    ================================================================
+-->
 
-    <p>A <c>Timeout</c> argument specifies a time-out in milliseconds. The
-      default value for argument <c>Timeout</c> is <c>infinity</c>.</p>
-  </section>
-  
   <funcs>
 
     <func>
       <name since="OTP 20.3">append_cipher_suites(Deferred, Suites) -> ciphers() </name>
       <fsummary></fsummary>
       <type>
-           <v>Deferred = ciphers() | cipher_filters() </v>
-	   <v>Suites  = ciphers() </v>
+        <v>Deferred = <seealso marker="#type-ciphers">ciphers()</seealso> |
+	<seealso marker="#type-cipher_filters">cipher_filters()</seealso></v>
+	<v>Suites  =  <seealso marker="#type-ciphers">ciphers()</seealso></v>
       </type>
       <desc><p>Make <c>Deferred</c> suites become the least preferred
       suites, that is put them at the end of the cipher suite list
@@ -969,7 +1092,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       all supported cipher suites.</fsummary>
       <type>
         <v> Supported = default | all | anonymous </v>
-	<v> Version = protocol_version() </v>
+	<v> Version = <seealso marker="#type-protocol_version">protocol_version() </seealso></v>
       </type>
       <desc><p>Returns all default or all supported (except anonymous),
       or all anonymous cipher suites for a
@@ -979,9 +1102,15 @@ fun(srp, Username :: string(), UserState :: term()) ->
 
     <func>
       <name since="OTP 19.2">eccs() -></name>
-      <name since="OTP 19.2">eccs(protocol_version()) -> [named_curve()]</name>
+      <name since="OTP 19.2">eccs(Version) -> NamedCurves</name>
       <fsummary>Returns a list of supported ECCs.</fsummary>
 
+      <type>
+	<v> Version = <seealso marker="#type-protocol_version">protocol_version() </seealso></v>
+	<v> NamedCurves = <seealso marker="#type-named_curve">[named_curve()] </seealso></v>
+	
+      </type>
+      
       <desc><p>Returns a list of supported ECCs. <c>eccs()</c>
       is equivalent to calling <c>eccs(Protocol)</c> with all
       supported protocols and then deduplicating the output.</p>
@@ -1001,39 +1130,46 @@ fun(srp, Username :: string(), UserState :: term()) ->
     </func>
    
     <func>
-      <name since="OTP R14B">connect(Socket, SslOptions) -> </name>
-      <name since="">connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext}
+      <name since="OTP R14B">connect(Socket, Options) -> </name>
+      <name since="">connect(Socket, Options, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext}
 	| {error, Reason}</name>
       <fsummary>Upgrades a <c>gen_tcp</c>, or
 	equivalent, connected socket to an TLS socket.</fsummary>
       <type>
-	<v>Socket = socket()</v>
-	<v>SslOptions = [{handshake, hello| full} | ssl_option()]</v>
-	<v>Timeout = integer() | infinity</v>
-	<v>SslSocket = sslsocket()</v>
+	<v>Socket = <seealso marker="#type-socket"> socket() </seealso></v>
+	<v>Options = <seealso marker="#type-client_option"> [client_option()] </seealso></v>
+	<v>Timeout = timeout()</v>
+	<v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
 	<v>Ext = hello_extensions()</v>
-	<v>Reason = term()</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,
 	  connected socket to an TLS socket, that is, performs the
 	  client-side TLS handshake.</p>
 	  
-	  <note><p>If the option <c>verify</c> is set to <c>verify_peer</c>
-	  the option <c>server_name_indication</c> shall also be specified,
-	  if it is not no Server Name Indication extension will be sent,
-	  and <seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso>
-	  will be called with the IP-address of the connection as <c>ReferenceID</c>, which is proably not what you want.</p>
+	  <note><p>If the option <c>verify</c> is set to
+	  <c>verify_peer</c> the option <c>server_name_indication</c>
+	  shall also be specified, if it is not no Server Name
+	  Indication extension will be sent, and <seealso
+	  marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso>
+	  will be called with the IP-address of the connection as
+	  <c>ReferenceID</c>, which is proably not what you want.</p>
 	  </note>
 
 	  <p> If the option <c>{handshake, hello}</c> is used the
 	  handshake is paused after receiving the server hello message
 	  and the success response is <c>{ok, SslSocket, Ext}</c>
-	  instead of <c>{ok, SslSocket}</c>. Thereafter the handshake is continued or
-	  canceled by calling <seealso marker="#handshake_continue-3">
+	  instead of <c>{ok, SslSocket}</c>. Thereafter the handshake
+	  is continued or canceled by calling <seealso
+	  marker="#handshake_continue-3">
 	  <c>handshake_continue/3</c></seealso> or <seealso
-	  marker="#handshake_cancel-1"><c>handshake_cancel/1</c></seealso>.	 
+	  marker="#handshake_cancel-1"><c>handshake_cancel/1</c></seealso>.
 	  </p>
 	  
+	  <p> If the option <c>active</c> is set to <c>once</c> or <c>true</c> the
+	  process owning the sslsocket will receive messages of type 
+	  <seealso marker="#type-active_msgs"> active_msgs() </seealso>
+	  </p>
     </desc>
     </func>
 
@@ -1043,19 +1179,19 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	  {ok, SslSocket}| {ok, SslSocket, Ext} | {error, Reason}</name>
       <fsummary>Opens an TLS/DTLS connection to <c>Host</c>, <c>Port</c>.</fsummary>
       <type>
-	  <v>Host = host()</v>
-	  <v>Port = integer()</v>
-	  <v>Options = [option()]</v>
-	  <v>Timeout = integer() | infinity</v>
-	  <v>SslSocket = sslsocket()</v>
-	  <v>Reason = term()</v>
+	  <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>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>
       </type>
       <desc><p>Opens an TLS/DTLS connection to <c>Host</c>, <c>Port</c>.</p>
       
       <p> When the option <c>verify</c> is set to <c>verify_peer</c> the check 
       <seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso> 
       will be performed in addition to the usual x509-path validation checks. If the check fails the error {bad_cert, hostname_check_failed} will
-      be propagated to the path validation fun <seealso marker="#verify_fun">verify_fun</seealso>, where it is possible to do customized
+      be propagated to the path validation fun <seealso marker="#type-custom_verify">verify_fun</seealso>, where it is possible to do customized
       checks by using the full possibilities of the <seealso marker="public_key:public_key#pkix_verify_hostname-3">public_key:pkix_verify_hostname/3</seealso> API.
       
       When the option <c>server_name_indication</c> is provided, its value (the DNS name) will be used as <c>ReferenceID</c>
@@ -1077,6 +1213,11 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	  <c>handshake_continue/3</c></seealso> or <seealso
 	  marker="#handshake_cancel-1"><c>handshake_cancel/1</c></seealso>.
 	  </p>
+
+	  <p> If the option <c>active</c> is set to <c>once</c> or <c>true</c> the
+	  process owning the sslsocket will receive messages of type 
+	  <seealso marker="#type-active_msgs"> active_msgs() </seealso>
+	  </p>
       </desc>
     </func>
 
@@ -1084,7 +1225,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="">close(SslSocket) -> ok | {error, Reason}</name>
       <fsummary>Closes an TLS/DTLS connection.</fsummary>
       <type>
-	  <v>SslSocket = sslsocket()</v>
+	  <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
 	  <v>Reason = term()</v>
       </type>
       <desc><p>Closes an TLS/DTLS connection.</p>
@@ -1095,7 +1236,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP 18.1">close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}</name>
       <fsummary>Closes an TLS connection.</fsummary>
       <type>
-	  <v>SslSocket = sslsocket()</v>
+	  <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
 	  <v>How =  timeout() | {NewController::pid(), timeout()} </v>
 	  <v>Reason = term()</v>
       </type>
@@ -1112,7 +1253,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	<fsummary>Assigns a new controlling process to the
 	TLS/DTLS socket.</fsummary>
 	<type>
-	  <v>SslSocket = sslsocket()</v>
+	  <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
 	  <v>NewOwner = pid()</v>
 	  <v>Reason = term()</v>
 	</type>
@@ -1128,7 +1269,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <fsummary>Returns all the connection information.
       </fsummary>
       <type>
-	<v>SslSocket = sslsocket()</v>
+	<v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
         <v>Item = protocol | selected_cipher_suite | sni_hostname | ecc | session_id | atom()</v>
 	<d>Meaningful atoms, not specified above, are the ssl option names.</d>
 	<v>Result = [{Item::atom(), Value::term()}]</v>
@@ -1149,7 +1290,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <fsummary>Returns the requested connection information.
       </fsummary>
       <type>
-	<v>SslSocket = sslsocket()</v>
+	<v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
 	<v>Items = [Item]</v>
 	<v>Item = protocol | cipher_suite | sni_hostname | ecc | session_id | client_random 
           | server_random  | master_secret | atom()</v>
@@ -1169,8 +1310,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP 20.3">filter_cipher_suites(Suites, Filters) -> ciphers()</name>
       <fsummary></fsummary>
       <type>
-	<v> Suites = ciphers()</v>
-        <v> Filters = cipher_filters()</v>
+	<v> Suites =  <seealso marker="#type-ciphers"> ciphers() </seealso></v>
+        <v> Filters =  <seealso marker="#type-cipher_filters"> cipher_filters() </seealso></v>
       </type>
       <desc><p>Removes cipher suites if any of the filter functions
       returns false for any part of the cipher suite. This function
@@ -1196,7 +1337,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	{ok, [socketoption()]} | {error, Reason}</name>
       <fsummary>Gets the values of the specified options.</fsummary>
       <type>
-	<v>Socket = sslsocket()</v>
+	<v>Socket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
 	<v>OptionNames = [atom()]</v>
       </type>
       <desc>
@@ -1212,7 +1353,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
         {ok, OptionValues} | {error, inet:posix()}</name>
       <fsummary>Get one or more statistic options for a socket</fsummary>
       <type>
-    <v>SslSocket = sslsocket()</v>
+    <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
     <v>OptionNames = [atom()]</v>
         <v>OptionValues = [{inet:stat_option(), integer()}]</v>
       </type>
@@ -1227,27 +1368,32 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP 21.0">handshake(HsSocket, Timeout) -> {ok, SslSocket}  | {error, Reason}</name>
       <fsummary>Performs server-side SSL/TLS handshake.</fsummary>
       <type>
-        <v>HsSocket = SslSocket = sslsocket()</v>
-        <v>Timeout = integer()</v>
-        <v>Reason = term()</v>
+        <v>HsSocket = SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
+        <v>Timeout = timeout()</v>
+        <v>Reason = closed | timeout | <seealso marker="#type-error_alert"> error_alert() </seealso></v>
       </type>
       <desc>
         <p>Performs the SSL/TLS/DTLS server-side handshake.</p>
 	<p>Returns a new TLS/DTLS socket if the handshake is successful.</p>
+
+	<p> If the option <c>active</c> is set to <c>once</c> or <c>true</c> the
+	process owning the sslsocket will receive messages of type 
+	<seealso marker="#type-active_msgs"> active_msgs() </seealso>
+	</p>	
       </desc>
     </func>
 
     <func>
-      <name since="OTP 21.0">handshake(Socket, SslOptions) -> </name>
-      <name since="OTP 21.0">handshake(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason}</name>
+      <name since="OTP 21.0">handshake(Socket, Options) -> </name>
+      <name since="OTP 21.0">handshake(Socket, Options, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason}</name>
       <fsummary>Performs server-side SSL/TLS/DTLS handshake.</fsummary>
       <type>
-        <v>Socket = socket() | sslsocket() </v>
-	<v>SslSocket = sslsocket() </v>
+        <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>SslOptions = [{handshake, hello| full} | ssl_option()]</v>
-        <v>Timeout = integer()</v>
-        <v>Reason = term()</v>
+	<v>Options = <seealso marker="#type-server_option"> [server_option()] </seealso>  </v>
+        <v>Timeout = timeout()</v>
+        <v>Reason = closed | timeout | <seealso marker="#type-error_alert"> error_alert() </seealso></v>
       </type>
       <desc>
         <p>If <c>Socket</c> is a ordinary <c>socket()</c>: upgrades a <c>gen_tcp</c>,
@@ -1259,7 +1405,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	is undefined.
 	</p></warning>
 	
-	<p>If <c>Socket</c> is an <c>sslsocket()</c>: provides extra SSL/TLS/DTLS
+	<p>If <c>Socket</c> is an 
+	<seealso marker="#type-sslsocket"> sslsocket() </seealso>: provides extra SSL/TLS/DTLS
 	options to those specified in
 	<seealso marker="#listen-2">listen/2 </seealso> and then performs
 	the SSL/TLS/DTLS handshake. Returns a new TLS/DTLS socket if the handshake is successful.</p>
@@ -1273,6 +1420,12 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	  <c>handshake_continue/3</c></seealso> or <seealso
 	  marker="#handshake_cancel-1"><c>handshake_cancel/1</c></seealso>.
 	</p>
+	
+	<p> If the option <c>active</c> is set to <c>once</c> or <c>true</c> the
+	process owning the sslsocket will receive messages of type 
+	<seealso marker="#type-active_msgs"> active_msgs() </seealso>
+	</p>
+	
       </desc>
     </func>
 
@@ -1280,7 +1433,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP 21.0">handshake_cancel(SslSocket) -> ok </name>
       <fsummary>Cancel handshake with a fatal alert</fsummary>
       <type>
-        <v>SslSocket = sslsocket()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
       </type>
       <desc>
         <p>Cancel the handshake with a fatal <c>USER_CANCELED</c> alert.</p>
@@ -1288,14 +1441,14 @@ fun(srp, Username :: string(), UserState :: term()) ->
     </func>
 
     <func>
-      <name since="OTP 21.0">handshake_continue(HsSocket, SSLOptions) -> {ok, SslSocket} | {error, Reason}</name>
-      <name since="OTP 21.0">handshake_continue(HsSocket, SSLOptions, Timeout) -> {ok, SslSocket} | {error, Reason}</name>
+      <name since="OTP 21.0">handshake_continue(HsSocket, Options) -> {ok, SslSocket} | {error, Reason}</name>
+      <name since="OTP 21.0">handshake_continue(HsSocket, Options, Timeout) -> {ok, SslSocket} | {error, Reason}</name>
       <fsummary>Continue the SSL/TLS handshake.</fsummary>
       <type>
-	<v>HsSocket = SslSocket = sslsocket()</v>
-	<v>SslOptions = [ssl_option()]</v>
-	<v>Timeout = integer()</v>
-	<v>Reason = term()</v>
+	<v>HsSocket = SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
+	<v>Options = <seealso marker="#type-tls_option"> tls_option() </seealso> </v>
+	<v>Timeout = timeout()</v>
+	<v>Reason = closed | timeout | <seealso marker="#type-error_alert"> error_alert() </seealso></v>
       </type>
       <desc>
         <p>Continue the SSL/TLS handshake possiby with new, additional or changed options.</p>
@@ -1307,9 +1460,9 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	{ok, ListenSocket} | {error, Reason}</name>
       <fsummary>Creates an SSL listen socket.</fsummary>
       <type>
-	<v>Port = integer()</v>
-	<v>Options = options()</v>
-	<v>ListenSocket = sslsocket()</v>
+	<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>ListenSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
       </type>
       <desc>
 	<p>Creates an SSL listen socket.</p>
@@ -1320,7 +1473,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP 18.0">negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, protocol_not_negotiated}</name>
       <fsummary>Returns the protocol negotiated through ALPN or NPN extensions.</fsummary>
       <type>
-        <v>SslSocket = sslsocket()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
         <v>Protocol = binary()</v>
       </type>
       <desc>
@@ -1334,7 +1487,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="">peercert(SslSocket) -> {ok, Cert} | {error, Reason}</name>
       <fsummary>Returns the peer certificate.</fsummary>
      <type>
-        <v>SslSocket = sslsocket()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
         <v>Cert = binary()</v>
       </type>
       <desc>
@@ -1350,9 +1503,9 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	{error, Reason}</name>
       <fsummary>Returns the peer address and port.</fsummary>
       <type>
-        <v>SslSocket = sslsocket()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
         <v>Address = ipaddress()</v>
-        <v>Port = integer()</v>
+	<v>Port = <seealso marker="kernel:inet#type-port_number">inet:port_number()</seealso></v>
       </type>
       <desc>
         <p>Returns the address and port number of the peer.</p>
@@ -1363,8 +1516,9 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP 20.3">prepend_cipher_suites(Preferred, Suites) -> ciphers()</name>
       <fsummary></fsummary>
       <type>
-        <v>Preferred = ciphers() | cipher_filters() </v>
-	<v>Suites = ciphers() </v>
+	<v>Preferred = <seealso marker="#type-ciphers">ciphers()</seealso> |
+	<seealso marker="#type-cipher_filters">cipher_filters()</seealso></v>
+	<v>Suites  =  <seealso marker="#type-ciphers">ciphers()</seealso></v>
       </type>
       <desc><p>Make <c>Preferred</c> suites become the most preferred
       suites that is put them at the head of the cipher suite list
@@ -1379,7 +1533,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP R15B01">prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()}</name>
       <fsummary>Uses a session Pseudo-Random Function to generate key material.</fsummary>
       <type>
-	<v>Socket = sslsocket()</v>
+	<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>
@@ -1401,9 +1555,9 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	Reason}</name>
       <fsummary>Receives data on a socket.</fsummary>
       <type>
-        <v>SslSocket = sslsocket()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
         <v>Length = integer()</v>
-        <v>Timeout = integer()</v>
+        <v>Timeout = timeout()</v>
         <v>Data = [char()] | binary()</v>
       </type>
       <desc>
@@ -1426,7 +1580,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP R14B">renegotiate(SslSocket) -> ok | {error, Reason}</name>
       <fsummary>Initiates a new handshake.</fsummary>
       <type>
-	<v>SslSocket = sslsocket()</v>
+	<v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
       </type>
       <desc><p>Initiates a new handshake. A notable return value is
       <c>{error, renegotiation_rejected}</c> indicating that the peer
@@ -1439,7 +1593,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="">send(SslSocket, Data) -> ok | {error, Reason}</name>
       <fsummary>Writes data to a socket.</fsummary>
       <type>
-        <v>SslSocket = sslsocket()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
         <v>Data = iodata()</v>
       </type>
       <desc>
@@ -1453,8 +1607,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="">setopts(SslSocket, Options) -> ok | {error, Reason}</name>
       <fsummary>Sets socket options.</fsummary>
       <type>
-        <v>SslSocket = sslsocket()</v>
-        <v>Options = [socketoption]()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
+        <v>Options = <seealso marker="#type-socket_option"> [socket_option()] </seealso></v>
       </type>
       <desc>
         <p>Sets options according to <c>Options</c> for socket
@@ -1477,7 +1631,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP R14B">shutdown(SslSocket, How) -> ok | {error, Reason}</name>
       <fsummary>Immediately closes a socket.</fsummary>
       <type>
-        <v>SslSocket = sslsocket()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
         <v>How = read | write | read_write</v>
         <v>Reason = reason()</v>
       </type>
@@ -1496,9 +1650,9 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="">ssl_accept(SslSocket, Timeout) -> ok | {error, Reason}</name>
       <fsummary>Performs server-side SSL/TLS handshake.</fsummary>
       <type>
-        <v>SslSocket = sslsocket()</v>
-        <v>Timeout = integer()</v>
-        <v>Reason = term()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
+        <v>Timeout = timeout()</v>
+        <v>Reason = closed | timeout | <seealso marker="#type-error_alert"> error_alert() </seealso></v>
       </type>
       <desc>
 	<p>Deprecated in OTP 21, use <seealso marker="#handshake-1">handshake/[1,2]</seealso> instead.</p>
@@ -1507,14 +1661,14 @@ fun(srp, Username :: string(), UserState :: term()) ->
     </func>
 
     <func>
-      <name since="">ssl_accept(Socket, SslOptions) -> </name>
-      <name since="OTP R14B">ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason}</name>
+      <name since="">ssl_accept(Socket, Options) -> </name>
+      <name since="OTP R14B">ssl_accept(Socket, Options, Timeout) -> {ok, Socket} | ok | {error, Reason}</name>
       <fsummary>Performs server-side SSL/TLS/DTLS handshake.</fsummary>
       <type>
-        <v>Socket = socket() | sslsocket() </v>
-	<v>SslOptions = [ssl_option()]</v>
-        <v>Timeout = integer()</v>
-        <v>Reason = term()</v>
+        <v>Socket = socket() |  <seealso marker="#type-sslsocket"> sslsocket() </seealso> </v>
+	<v>Options =  <seealso marker="#type-server_option"> [server_option()] </seealso> </v>
+        <v>Timeout = timeout()</v>
+        <v>Reason = closed | timeout | <seealso marker="#type-error_alert"> error_alert() </seealso></v>
       </type>
       <desc>
 	<p>Deprecated in OTP 21, use  <seealso marker="#handshake-3">handshake/[2,3]</seealso> instead.</p>
@@ -1527,9 +1681,9 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	{error, Reason}</name>
       <fsummary>Returns the local address and port.</fsummary>
       <type>
-        <v>SslSocket = sslsocket()</v>
-        <v>Address = ipaddress()</v>
-        <v>Port = integer()</v>
+        <v>SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
+	<v>Address = <seealso marker="#type-ip_address">ip_address()</seealso></v>
+	<v>Port = <seealso marker="kernel:inet#type-port_number">inet:port_number()</seealso></v>
       </type>
       <desc>
         <p>Returns the local address and port number of socket
@@ -1562,7 +1716,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name since="OTP 21.0">suite_to_str(CipherSuite) -> String</name>
       <fsummary>Returns the string representation of a cipher suite.</fsummary>
       <type>
-        <v>CipherSuite = erl_cipher_suite()</v>
+        <v>CipherSuite =  <seealso marker="#type-erl_cipher_suite"> erl_cipher_suite() </seealso></v>
 	<v>String = string()</v>
       </type>
       <desc>
@@ -1577,8 +1731,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <fsummary>Accepts an incoming connection and
 	prepares for <c>ssl_accept</c>.</fsummary>
       <type>
-        <v>ListenSocket = SslSocket = sslsocket()</v>
-        <v>Timeout = integer()</v>
+        <v>ListenSocket = SslSocket =  <seealso marker="#type-sslsocket"> sslsocket() </seealso></v>
+        <v>Timeout = timeout()</v>
         <v>Reason = reason()</v>
       </type>
       <desc>
diff --git a/lib/ssl/doc/src/ssl_crl_cache.xml b/lib/ssl/doc/src/ssl_crl_cache.xml
index b766cfd2d9..a33aec62a7 100644
--- a/lib/ssl/doc/src/ssl_crl_cache.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache.xml
@@ -34,15 +34,27 @@
       the following functions are available.
     </p>
   </description>
+
+    <datatypes>
+    <datatype_title>DATA TYPES</datatype_title>
+
+      <datatype>
+	<name name="crl_src"/>
+      </datatype>
+
+      <datatype>
+	<name name="uri"/>
+      </datatype>
+
+    </datatypes>
   
     <funcs>
       <func>
 	<name since="OTP 18.0">delete(Entries) -> ok |  {error, Reason} </name>
 	<fsummary> </fsummary>
 	<type>
-	  <v> Entries =  <seealso marker="stdlib:uri_string">uri_string:uri_string()</seealso> | {file, string()} | {der, [<seealso
-	  marker="public_key:public_key"> public_key:der_encoded() </seealso>]}</v>
-	  <v> Reason = term()</v>
+	  <v> Entries =  <seealso marker="#type-crl_src">crl_src()</seealso>]}</v>
+	  <v> Reason = crl_reason()</v>
 	</type>
 	<desc>
 	  <p>Delete CRLs from the ssl applications local cache. </p>
@@ -53,13 +65,12 @@
 	<name since="OTP 18.0">insert(URI, CRLSrc) -> ok | {error, Reason}</name>
 	<fsummary> </fsummary>
 	<type>
-	  <v> CRLSrc = {file, string()} | {der, [ <seealso
-	marker="public_key:public_key"> public_key:der_encoded() </seealso> ]}</v>
-	  <v> URI = <seealso marker="stdlib:uri_string">uri_string:uri_string() </seealso> </v>
+	  <v> CRLSrc = <seealso marker="#type-crl_src">crl_src()</seealso>]}</v>
+	  <v> URI = <seealso marker="#type-uri">uri()</seealso> </v>
 	  <v> Reason = term()</v>
 	</type>
 	<desc>
-	 <p>Insert CRLs into the ssl applications local cache. </p>
+	 <p>Insert CRLs, available to fetch on DER format from <c>URI</c>, into the ssl applications local cache. </p>
 	</desc>
       </func>
     </funcs>
diff --git a/lib/ssl/doc/src/ssl_crl_cache_api.xml b/lib/ssl/doc/src/ssl_crl_cache_api.xml
index c7e501867f..4cba4e1de1 100644
--- a/lib/ssl/doc/src/ssl_crl_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache_api.xml
@@ -39,35 +39,44 @@
       a CRL cache.
     </p>
   </description>
-  
-  <section>
-    <title>DATA TYPES</title>
-    
-    <p>The following data types are used in the functions below:
-    </p>
-    
-    <taglist>
-      
-    <tag><c>cache_ref() =</c></tag> 
-    <item>opaque()</item>
-    <tag><c>dist_point() =</c></tag>
-    <item><p>#'DistributionPoint'{} see <seealso
-    marker="public_key:public_key_records"> X509 certificates records</seealso></p></item>
-    
-    </taglist>
+
+
+  <!--
+      ================================================================
+      =  Data types                                                  =
+      ================================================================
+  -->
+
+  <datatypes>
     
-  </section>
+     <datatype>
+	<name name="crl_cache_ref"/>
+	<desc>
+	  <p>Reference to the CRL cache.</p>
+	</desc>
+      </datatype>
+
+
+     <datatype>
+	<name name="dist_point"/>
+	<desc>
+	  <p>For description see <seealso 
+	  marker="public_key:public_key_records"> X509 certificates records</seealso></p>
+	</desc>
+     </datatype>      
+   </datatypes>
+  
   <funcs>
       <func>
       <name since="OTP 18.0">fresh_crl(DistributionPoint, CRL) -> FreshCRL</name>
       <fsummary> <c>fun fresh_crl/2 </c> will be used as input option <c>update_crl</c> to
       public_key:pkix_crls_validate/3 </fsummary>
       <type>
-	<v> DistributionPoint = dist_point() </v>
+	<v> DistributionPoint = <seealso marker="#type-dist_point"> dist_point() </seealso> </v>
 	<v> CRL = [<seealso
-	marker="public_key:public_key">public_key:der_encoded()</seealso>] </v>
+	marker="public_key:public_key#type-der_encoded">public_key:der_encoded()</seealso>] </v>
 	<v> FreshCRL = [<seealso
-	marker="public_key:public_key">public_key:der_encoded()</seealso>] </v>
+	marker="public_key:public_key#type-der_encoded">public_key:der_encoded()</seealso>] </v>
       </type>
       <desc>
 	<p> <c>fun fresh_crl/2 </c> will be used as input option <c>update_crl</c> to
@@ -80,12 +89,12 @@
       <name since="OTP 18.0">lookup(DistributionPoint, DbHandle) -> not_available | CRLs </name>
       <fsummary> </fsummary>
       <type>
-        <v> DistributionPoint = dist_point() </v>
+	<v> DistributionPoint = <seealso marker="#type-dist_point"> dist_point() </seealso> </v>
         <v> Issuer = <seealso
-	marker="public_key:public_key">public_key:issuer_name()</seealso> </v>
-	<v> DbHandle  = cache_ref() </v>
+	marker="public_key:public_key#type-issuer_name">public_key:issuer_name()</seealso> </v>
+	<v> DbHandle = <seealso marker="#type-crl_cache_ref"> crl_cache_ref() </seealso></v>
 	<v> CRLs = [<seealso
-	   marker="public_key:public_key">public_key:der_encoded()</seealso>] </v>
+	   marker="public_key:public_key#type-der_encoded">public_key:der_encoded()</seealso>] </v>
 	</type>
 	<desc> <p>Lookup the CRLs belonging to the distribution point <c> Distributionpoint</c>.
 	This function may choose to only look in the cache or to follow distribution point
@@ -110,8 +119,8 @@
       <fsummary>Select the CRLs in the cache that are issued by <c>Issuer</c></fsummary>
       <type>
 	<v> Issuer = <seealso
-	marker="public_key:public_key">public_key:issuer_name()</seealso></v>
-	<v> DbHandle  = cache_ref() </v>
+	marker="public_key:public_key#type-issuer_name">public_key:issuer_name()</seealso></v>
+	<v> DbHandle = <seealso marker="#type-crl_cache_ref"> cache_ref() </seealso></v>
 	</type>
 	<desc>
 	  <p>Select the CRLs in the cache that are issued by <c>Issuer</c> </p>
diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml
index 463cf15309..e841729e57 100644
--- a/lib/ssl/doc/src/ssl_session_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_session_cache_api.xml
@@ -38,30 +38,41 @@
       defining a new callback module implementing this API.
     </p>
   </description>
-  <section>
-    <title>DATA TYPES</title>
 
-    <p>The following data types are used in the functions for
-    <c>ssl_session_cache_api</c>:</p>
-
-    <taglist>
-      <tag><c>cache_ref() =</c></tag>
-      <item><p><c>opaque()</c></p></item>
-
-      <tag><c>key() =</c></tag>
-      <item><p><c>{partialkey(), session_id()}</c></p></item>
-
-      <tag><c>partialkey() =</c></tag>
-      <item><p><c>opaque()</c></p></item>
-
-      <tag><c>session_id() =</c></tag>
-      <item><p><c>binary()</c></p></item>
-
-      <tag><c>session()</c> =</tag>
-      <item><p><c>opaque()</c></p></item>
-    </taglist>
-
-  </section>
+ <!--
+      ================================================================
+      =  Data types                                                  =
+      ================================================================
+  -->
+
+  <datatypes>
+    
+      <datatype>
+	<name name="session_cache_ref"/>
+      </datatype>
+
+      <datatype>
+	<name name="session_cache_key"/>
+	<desc>
+	  <p>A key to an entry in the session cache.</p>
+	</desc>
+      </datatype>
+
+        <datatype>
+	  <name name="partial_key"/>
+	<desc>
+	   <p>The opaque part of the key. Does not need to be handled
+	  by the callback.</p>
+	</desc>
+      </datatype>
+      
+       <datatype>
+	<name name="session"/>
+	<desc>
+	   <p>The session data that is stored for each session.</p>
+	</desc>
+      </datatype>  
+  </datatypes>
 
   <funcs>
 
@@ -69,8 +80,8 @@
       <name since="OTP R14B">delete(Cache, Key) -> _</name>
       <fsummary>Deletes a cache entry.</fsummary>
       <type>
-	<v>Cache = cache_ref()</v>
-	<v>Key = key()</v>
+	<v>Cache = <seealso marker="#type-session_cache_ref"> session_cache_ref() </seealso></v>
+	<v>Key = <seealso marker="#type-session_cache_key">session_cache_key() </seealso> </v>
       </type>
       <desc>
 	<p>Deletes a cache entry. Is only called from the cache
@@ -83,7 +94,9 @@
       <name since="OTP R14B">foldl(Fun, Acc0, Cache) -> Acc</name>
       <fsummary></fsummary>
       <type>
-	<v></v>
+	<v>Fun = fun()</v>
+	<v>Acc0 = Acc = term()</v>
+	<v>Cache = <seealso marker="#type-session_cache_ref"> session_cache_ref() </seealso></v>
       </type>
       <desc>
 	<p>Calls <c>Fun(Elem, AccIn)</c> on successive elements of the
@@ -96,10 +109,11 @@
     </func>
 
     <func>
-      <name since="OTP 18.0">init(Args) -> opaque() </name>
+      <name since="OTP 18.0">init(Args) -> Cache </name>
       <fsummary>Returns cache reference.</fsummary>
       <type>
-	<v>Args = proplists:proplist()</v>
+	<v>Cache = <seealso marker="#type-session_cache_ref"> session_cache_ref() </seealso></v>
+	<v>Args = <seealso marker="stdlib:proplists#type-proplist">proplists:proplist()</seealso></v>
       </type>
       <desc>
 	<p>Includes property <c>{role, client | server}</c>.
@@ -124,9 +138,9 @@
       <name since="OTP R14B">lookup(Cache, Key) -> Entry</name>
       <fsummary>Looks up a cache entry.</fsummary>
       <type>
-	<v>Cache = cache_ref()</v>
-	<v>Key = key()</v>
-	<v>Entry = session() | undefined</v>
+	<v>Cache = <seealso marker="#type-session_cache_ref"> session_cache_ref() </seealso></v>
+	<v>Key = <seealso marker="#type-session_cache_key">session_cache_key()</seealso> </v>
+	<v>Session = <seealso marker="#type-session">session()</seealso> | undefined</v>
       </type>
       <desc>
 	<p>Looks up a cache entry. Is to be callable from any
@@ -136,12 +150,12 @@
     </func>
 
     <func>
-      <name since="OTP R14B">select_session(Cache, PartialKey) -> [session()]</name>
+      <name since="OTP R14B">select_session(Cache, PartialKey) -> [Session]</name>
       <fsummary>Selects sessions that can be reused.</fsummary>
       <type>
-	<v>Cache = cache_ref()</v>
-	<v>PartialKey = partialkey()</v>
-	<v>Session = session()</v>
+	<v>Cache = <seealso marker="#type-session_cache_ref"> session_cache_ref() </seealso></v>
+	<v>PartialKey = <seealso marker="#type-partial_key"> partial_key() </seealso></v>
+	<v>Session = <seealso marker="#type-session">session()</seealso></v>
       </type>
       <desc>
 	<p>Selects sessions that can be reused. Is to be callable
@@ -154,7 +168,7 @@
       <name since="OTP 19.3">size(Cache) -> integer()</name>
       <fsummary>Returns the number of sessions in the cache.</fsummary>
       <type>
-	<v>Cache = cache_ref()</v>
+	<v>Cache = <seealso marker="#type-session_cache_ref"> session_cache_ref() </seealso></v>
       </type>
       <desc>
 	<p>Returns the number of sessions in the cache. If size
@@ -170,7 +184,8 @@
       <fsummary>Called by the process that handles the cache when it
       is about to terminate.</fsummary>
       <type>
-	<v>Cache = term() - as returned by init/0</v>
+	<v>Cache = <seealso marker="#type-session_cache_ref"> session_cache_ref() </seealso></v>
+	<d>As returned by init/0</d>
       </type>
       <desc>
 	<p>Takes care of possible cleanup that is needed when the
@@ -183,9 +198,9 @@
       <name since="OTP R14B">update(Cache, Key, Session) -> _</name>
       <fsummary>Caches a new session or updates an already cached one.</fsummary>
       <type>
-	<v>Cache = cache_ref()</v>
-	<v>Key = key()</v>
-	<v>Session = session()</v>
+	<v>Cache = <seealso marker="#type-session_cache_ref"> session_cache_ref() </seealso></v>
+	<v>Key = <seealso marker="#type-session_cache_key">session_cache_key()</seealso> </v>
+	<v>Session = <seealso marker="#type-session">session()</seealso></v>
       </type>
       <desc>
 	<p>Caches a new session or updates an already cached one. Is
diff --git a/lib/ssl/src/dtls_connection.erl b/lib/ssl/src/dtls_connection.erl
index cbd5c8e0a9..149ae22052 100644
--- a/lib/ssl/src/dtls_connection.erl
+++ b/lib/ssl/src/dtls_connection.erl
@@ -81,7 +81,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 eb0f742e70..8e749e65b8 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 a16489bbd1..dab4038762 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 ce771343fe..e7fab7ebc5 100644
--- a/lib/ssl/src/inet_tls_dist.erl
+++ b/lib/ssl/src/inet_tls_dist.erl
@@ -481,22 +481,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(),
@@ -521,6 +524,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),
@@ -565,7 +570,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 616e9e26e7..017e06b232 100644
--- a/lib/ssl/src/ssl.erl
+++ b/lib/ssl/src/ssl.erl
@@ -62,16 +62,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, _} ->
@@ -88,21 +393,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(), [tls_client_option()]) -> {ok, #sslsocket{}} |
+                                                      {error, reason()}.
 connect(Socket, SslOptions) when is_port(Socket) ->
     connect(Socket, SslOptions, infinity).
 
+-spec connect(host() | port(), [tls_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,
@@ -119,6 +420,9 @@ connect(Socket, SslOptions0, Timeout) when is_port(Socket),
 connect(Host, Port, Options) ->
     connect(Host, Port, Options, infinity).
 
+-spec connect(host() | port(), inet:port_number(), list(), 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),
@@ -134,7 +438,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.
@@ -150,16 +454,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) ->
@@ -171,25 +475,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) ->
@@ -200,22 +504,19 @@ 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);
@@ -229,6 +530,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);
@@ -271,7 +574,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()}.
 %%
 %%
@@ -280,7 +583,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()}.
 %%
 %%
@@ -341,13 +644,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);
@@ -470,9 +774,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
 %%--------------------------------------------------------------------
@@ -488,9 +792,10 @@ 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()] | [ssl_cipher_format:cipher_suite()], 
+-spec filter_cipher_suites([erl_cipher_suite()] | [ssl_cipher_format:cipher_suite()] , 
                            [{key_exchange | cipher | mac | prf, fun()}] | []) -> 
-                                  [ssl_cipher_format:erl_cipher_suite() ] |  [ssl_cipher_format:cipher_suite()].
+                                  [erl_cipher_suite()] | [ssl_cipher_format: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.
@@ -507,10 +812,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
@@ -525,10 +830,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.
@@ -550,8 +855,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.
@@ -747,7 +1052,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}].
@@ -807,8 +1112,8 @@ format_error(Reason) when is_list(Reason) ->
     Reason;
 format_error(closed) ->
     "TLS connection is closed";
-format_error({tls_alert, Description}) ->
-    "TLS Alert: " ++ Description;
+format_error({tls_alert, {_, Description}}) ->
+    Description;
 format_error({options,{FileType, File, Reason}}) when FileType == cacertfile;
 						      FileType == certfile;
 						      FileType == keyfile;
@@ -837,7 +1142,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.
 %%--------------------------------------------------------------------
@@ -1075,6 +1380,7 @@ handle_options(Opts0, Role, Host) ->
 		  fallback, signature_algs, signature_algs_cert, eccs, honor_ecc_order,
                   beast_mitigation, max_handshake_size, handshake, customize_hostname_check,
                   supported_groups],
+
     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 ed8156e0be..e17476f33b 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
@@ -58,8 +58,10 @@ decode(Bin) ->
 
 reason_code(#alert{description = ?CLOSE_NOTIFY}, _) ->
     closed;
-reason_code(#alert{description = Description}, _) ->
-    {tls_alert, string:casefold(description_txt(Description))}.
+reason_code(#alert{description = Description, role = Role} = Alert, Role) ->
+    {tls_alert, {description_atom(Description), own_alert_txt(Alert)}};
+reason_code(#alert{description = Description} = Alert, Role) ->
+    {tls_alert, {description_atom(Description), alert_txt(Alert#alert{role = Role})}}.
 
 %%--------------------------------------------------------------------
 -spec own_alert_txt(#alert{}) -> string().
@@ -185,3 +187,70 @@ description_txt(?NO_APPLICATION_PROTOCOL) ->
     "No application protocol";
 description_txt(Enum) ->
     lists:flatten(io_lib:format("unsupported/unknown alert: ~p", [Enum])).
+
+description_atom(?CLOSE_NOTIFY) ->
+    close_notify;
+description_atom(?UNEXPECTED_MESSAGE) ->
+    unexpected_message;
+description_atom(?BAD_RECORD_MAC) ->
+    bad_record_mac;
+description_atom(?DECRYPTION_FAILED_RESERVED) ->
+    decryption_failed_reserved;
+description_atom(?RECORD_OVERFLOW) ->
+    record_overflow;
+description_atom(?DECOMPRESSION_FAILURE) ->
+    decompression_failure;
+description_atom(?HANDSHAKE_FAILURE) ->
+    handshake_failure;
+description_atom(?NO_CERTIFICATE_RESERVED) ->
+    no_certificate_reserved;
+description_atom(?BAD_CERTIFICATE) ->
+    bad_certificate;
+description_atom(?UNSUPPORTED_CERTIFICATE) ->
+    unsupported_certificate;
+description_atom(?CERTIFICATE_REVOKED) ->
+    certificate_revoked;
+description_atom(?CERTIFICATE_EXPIRED) ->
+    certificate_expired;
+description_atom(?CERTIFICATE_UNKNOWN) ->
+    certificate_unknown;
+description_atom(?ILLEGAL_PARAMETER) ->
+    illegal_parameter;
+description_atom(?UNKNOWN_CA) ->
+    unknown_ca;
+description_atom(?ACCESS_DENIED) ->
+    access_denied;
+description_atom(?DECODE_ERROR) ->
+    decode_error;
+description_atom(?DECRYPT_ERROR) ->
+    decrypt_error;
+description_atom(?EXPORT_RESTRICTION) ->
+    export_restriction;
+description_atom(?PROTOCOL_VERSION) ->
+    protocol_version;
+description_atom(?INSUFFICIENT_SECURITY) ->
+    insufficient_security;
+description_atom(?INTERNAL_ERROR) ->
+    internal_error;
+description_atom(?USER_CANCELED) ->
+    user_canceled;
+description_atom(?NO_RENEGOTIATION) ->
+    no_renegotiation;
+description_atom(?UNSUPPORTED_EXTENSION) ->
+    unsupported_extension;
+description_atom(?CERTIFICATE_UNOBTAINABLE) ->
+    certificate_unobtainable;
+description_atom(?UNRECOGNISED_NAME) ->
+    unrecognised_name;
+description_atom(?BAD_CERTIFICATE_STATUS_RESPONSE) ->
+    bad_certificate_status_response;
+description_atom(?BAD_CERTIFICATE_HASH_VALUE) ->
+    bad_certificate_hash_value;
+description_atom(?UNKNOWN_PSK_IDENTITY) ->
+    unknown_psk_identity;
+description_atom(?INAPPROPRIATE_FALLBACK) ->
+    inappropriate_fallback;
+description_atom(?NO_APPLICATION_PROTOCOL) ->
+    no_application_protocol;
+description_atom(_) ->
+    'unsupported/unkonwn_alert'.
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 d08b2cc7ad..873572e231 100644
--- a/lib/ssl/src/ssl_cipher.erl
+++ b/lib/ssl/src/ssl_cipher.erl
@@ -501,8 +501,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
 %%-------------------------------------------------------------------	
@@ -528,8 +528,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 6e480eef45..f75daaad22 100644
--- a/lib/ssl/src/ssl_cipher_format.erl
+++ b/lib/ssl/src/ssl_cipher_format.erl
@@ -25,33 +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 |
-                             any. %% TLS 1.3
--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().
 
@@ -60,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.
 %%--------------------------------------------------------------------
@@ -90,7 +82,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.
@@ -845,7 +837,7 @@ suite_definition(?TLS_CHACHA20_POLY1305_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).
@@ -862,7 +854,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.
 %%--------------------------------------------------------------------
@@ -1663,7 +1655,7 @@ openssl_suite("TLS_CHACHA20_POLY1305_SHA256") ->
 
 
 %%--------------------------------------------------------------------
--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 af18ceb322..cd8baf0434 100644
--- a/lib/ssl/src/ssl_connection.erl
+++ b/lib/ssl/src/ssl_connection.erl
@@ -78,7 +78,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
@@ -144,7 +144,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
@@ -2801,10 +2801,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 dd3bdd7478..756418dd75 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 a28f4add1b..16b5b34a3e 100644
--- a/lib/ssl/src/ssl_handshake.erl
+++ b/lib/ssl/src/ssl_handshake.erl
@@ -833,7 +833,7 @@ decode_extensions(Extensions, Version, MessageType) ->
     decode_extensions(Extensions, Version, MessageType, empty_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
@@ -842,7 +842,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 57b72366d3..159b5dad32 100644
--- a/lib/ssl/src/ssl_internal.hrl
+++ b/lib/ssl/src/ssl_internal.hrl
@@ -32,8 +32,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 b1f080b0fe..456a560bf6 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 01e378702c..159250e6d7 100644
--- a/lib/ssl/src/tls_connection.erl
+++ b/lib/ssl/src/tls_connection.erl
@@ -126,7 +126,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 eee2437bfd..a1397047f2 100644
--- a/lib/ssl/src/tls_handshake.erl
+++ b/lib/ssl/src/tls_handshake.erl
@@ -31,6 +31,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").
 -include_lib("kernel/include/logger.hrl").
 
@@ -49,7 +50,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(),
                    #key_share_client_hello{} | undefined) ->
 			  #client_hello{}.
@@ -97,13 +98,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, 
-                    HelloExt::map(), {ssl_cipher_format:hash(), ssl_cipher_format:sign_algo()} | 
+                    HelloExt::map(), {ssl:hash(), ssl:sign_algo()} | 
                     undefined} | #alert{}.
 %%
 %% Description: Handles a received hello message
diff --git a/lib/ssl/test/Makefile b/lib/ssl/test/Makefile
index a4adc7561b..57b74115ed 100644
--- a/lib/ssl/test/Makefile
+++ b/lib/ssl/test/Makefile
@@ -29,7 +29,7 @@ include $(ERL_TOP)/make/$(TARGET)/otp.mk
 # Application version
 # ----------------------------------------------------
 include ../vsn.mk
-VSN=$(GS_VSN)
+VSN=$(SSL_VSN)
 
 # ----------------------------------------------------
 # Target Specs
diff --git a/lib/ssl/test/ssl_alpn_handshake_SUITE.erl b/lib/ssl/test/ssl_alpn_handshake_SUITE.erl
index 7f7c3da5ab..dfc780479e 100644
--- a/lib/ssl/test/ssl_alpn_handshake_SUITE.erl
+++ b/lib/ssl/test/ssl_alpn_handshake_SUITE.erl
@@ -153,41 +153,41 @@ protocols_must_be_a_binary_list(Config) when is_list(Config) ->
 
 empty_client(Config) when is_list(Config) ->
     run_failing_handshake(Config,
-        [{alpn_advertised_protocols, []}],
-        [{alpn_preferred_protocols, [<<"spdy/2">>, <<"spdy/3">>, <<"http/2">>]}],
-        {error,{tls_alert,"no application protocol"}}).
+                          [{alpn_advertised_protocols, []}],
+                          [{alpn_preferred_protocols, [<<"spdy/2">>, <<"spdy/3">>, <<"http/2">>]}],
+                          no_application_protocol).
 
 %--------------------------------------------------------------------------------
 
 empty_server(Config) when is_list(Config) ->
     run_failing_handshake(Config,
-        [{alpn_advertised_protocols, [<<"http/1.0">>, <<"http/1.1">>]}],
-        [{alpn_preferred_protocols, []}],
-        {error,{tls_alert,"no application protocol"}}).
+                          [{alpn_advertised_protocols, [<<"http/1.0">>, <<"http/1.1">>]}],
+                          [{alpn_preferred_protocols, []}],
+                          no_application_protocol).
 
 %--------------------------------------------------------------------------------
 
 empty_client_empty_server(Config) when is_list(Config) ->
     run_failing_handshake(Config,
-        [{alpn_advertised_protocols, []}],
-        [{alpn_preferred_protocols, []}],
-        {error,{tls_alert,"no application protocol"}}).
+                          [{alpn_advertised_protocols, []}],
+                          [{alpn_preferred_protocols, []}],
+                          no_application_protocol).
 
 %--------------------------------------------------------------------------------
 
 no_matching_protocol(Config) when is_list(Config) ->
     run_failing_handshake(Config,
-        [{alpn_advertised_protocols, [<<"http/1.0">>, <<"http/1.1">>]}],
-        [{alpn_preferred_protocols, [<<"spdy/2">>, <<"spdy/3">>, <<"http/2">>]}],
-        {error,{tls_alert,"no application protocol"}}).
+                          [{alpn_advertised_protocols, [<<"http/1.0">>, <<"http/1.1">>]}],
+                          [{alpn_preferred_protocols, [<<"spdy/2">>, <<"spdy/3">>, <<"http/2">>]}],
+                          no_application_protocol).
 
 %--------------------------------------------------------------------------------
 
 client_alpn_and_server_alpn(Config) when is_list(Config) ->
     run_handshake(Config,
-		    [{alpn_advertised_protocols, [<<"http/1.0">>, <<"http/1.1">>]}],
-		    [{alpn_preferred_protocols, [<<"spdy/2">>, <<"http/1.1">>, <<"http/1.0">>]}],
-		    {ok, <<"http/1.1">>}).
+                  [{alpn_advertised_protocols, [<<"http/1.0">>, <<"http/1.1">>]}],
+                  [{alpn_preferred_protocols, [<<"spdy/2">>, <<"http/1.1">>, <<"http/1.0">>]}],
+                  {ok, <<"http/1.1">>}).
 
 %--------------------------------------------------------------------------------
 
@@ -297,7 +297,7 @@ alpn_not_supported_server(Config) when is_list(Config)->
 %% Internal functions ------------------------------------------------
 %%--------------------------------------------------------------------
 
-run_failing_handshake(Config, ClientExtraOpts, ServerExtraOpts, ExpectedResult) ->
+run_failing_handshake(Config, ClientExtraOpts, ServerExtraOpts, ExpectedAlert) ->
     ClientOpts = ClientExtraOpts ++ ssl_test_lib:ssl_options(client_rsa_opts, Config),
     ServerOpts = ServerExtraOpts ++ ssl_test_lib:ssl_options(server_rsa_opts, Config),
 
@@ -313,8 +313,7 @@ run_failing_handshake(Config, ClientExtraOpts, ServerExtraOpts, ExpectedResult)
                                            {from, self()},
                                            {mfa, {?MODULE, placeholder, []}},
                                            {options, ClientOpts}]),
-    ssl_test_lib:check_result(Server, ExpectedResult,
-                              Client, ExpectedResult).
+    ssl_test_lib:check_client_alert(Server, Client, ExpectedAlert).
 
 run_handshake(Config, ClientExtraOpts, ServerExtraOpts, ExpectedProtocol) ->
     Data = "hello world",
diff --git a/lib/ssl/test/ssl_basic_SUITE.erl b/lib/ssl/test/ssl_basic_SUITE.erl
index f4ecc4dc33..0a9a27c109 100644
--- a/lib/ssl/test/ssl_basic_SUITE.erl
+++ b/lib/ssl/test/ssl_basic_SUITE.erl
@@ -29,6 +29,7 @@
 -include_lib("public_key/include/public_key.hrl").
 
 -include("ssl_api.hrl").
+-include("ssl_cipher.hrl").
 -include("ssl_internal.hrl").
 -include("ssl_alert.hrl").
 -include("ssl_internal.hrl").
@@ -713,14 +714,7 @@ hello_client_cancel(Config) when is_list(Config) ->
                                                       {from, self()}, 
                                                       {options, ssl_test_lib:ssl_options([{handshake, hello}], Config)},
                                                       {continue_options, cancel}]),    
-      receive
-          {Server, {error, {tls_alert, "user canceled"}}} ->
-              ok;
-          {Server, {error, closed}} ->
-              ct:pal("Did not receive the ALERT"),
-              ok
-      end.
-
+    ssl_test_lib:check_server_alert(Server, user_canceled).
 %%--------------------------------------------------------------------
 hello_server_cancel() ->
     [{doc, "Test API function ssl:handshake_cancel/1 on the server side"}].
@@ -1194,9 +1188,8 @@ fallback(Config) when is_list(Config) ->
                                                            [{fallback, true},
                                                             {versions, ['tlsv1']}
                                                             | ClientOpts]}]),
-    
-    ssl_test_lib:check_result(Server, {error,{tls_alert,"inappropriate fallback"}},
-                              Client, {error,{tls_alert,"inappropriate fallback"}}).
+    ssl_test_lib:check_server_alert(Server, Client, inappropriate_fallback).
+   
 
 %%--------------------------------------------------------------------
 cipher_format() ->
@@ -2662,8 +2655,7 @@ default_reject_anonymous(Config) when is_list(Config) ->
                                                [{ciphers,[CipherSuite]} |
                                                 ClientOpts]}]),
 
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "insufficient security"}},
-                              Client, {error, {tls_alert, "insufficient security"}}).
+    ssl_test_lib:check_server_alert(Server, Client, insufficient_security).
 
 %%--------------------------------------------------------------------
 ciphers_ecdsa_signed_certs() ->
@@ -3515,8 +3507,7 @@ no_common_signature_algs(Config) when is_list(Config) ->
                                               {options, [{signature_algs, [{sha384, rsa}]}
                                                          | ClientOpts]}]),
     
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "insufficient security"}},
-                              Client, {error, {tls_alert, "insufficient security"}}).
+    ssl_test_lib:check_server_alert(Server, Client, insufficient_security).
 
 %%--------------------------------------------------------------------
 
@@ -4216,8 +4207,7 @@ tls_versions_option(Config) when is_list(Config) ->
 	{Server, _} ->
 	    ok
     end,	    
-   
-    ssl_test_lib:check_result(ErrClient, {error, {tls_alert, "protocol version"}}).
+    ssl_test_lib:check_client_alert(ErrClient, protocol_version).
 
 
 %%--------------------------------------------------------------------
diff --git a/lib/ssl/test/ssl_certificate_verify_SUITE.erl b/lib/ssl/test/ssl_certificate_verify_SUITE.erl
index bddcc2514d..8690faed54 100644
--- a/lib/ssl/test/ssl_certificate_verify_SUITE.erl
+++ b/lib/ssl/test/ssl_certificate_verify_SUITE.erl
@@ -298,15 +298,8 @@ server_require_peer_cert_fail(Config) when is_list(Config) ->
 					      {host, Hostname},
 					      {from, self()},
 					      {options, [{active, Active} | BadClientOpts]}]),
-    receive
-	{Server, {error, {tls_alert, "handshake failure"}}} ->
-	    receive
-		{Client, {error, {tls_alert, "handshake failure"}}} ->
-		    ok;
-		{Client, {error, closed}} ->
-		    ok
-	    end
-    end.
+
+    ssl_test_lib:check_server_alert(Server, Client, handshake_failure).
 
 %%--------------------------------------------------------------------
 server_require_peer_cert_empty_ok() ->
@@ -365,15 +358,8 @@ server_require_peer_cert_partial_chain(Config) when is_list(Config) ->
 					      {options, [{active, Active},
 							 {cacerts, [RootCA]} |
 							 proplists:delete(cacertfile, ClientOpts)]}]),
-    receive
-	{Server, {error, {tls_alert, "unknown ca"}}} ->
-	    receive
-		{Client, {error, {tls_alert, "unknown ca"}}} ->
-		    ok;
-		{Client, {error, closed}} ->
-		    ok
-	    end
-    end.
+    ssl_test_lib:check_server_alert(Server, Client, unknown_ca).
+
 %%--------------------------------------------------------------------
 server_require_peer_cert_allow_partial_chain() ->
     [{doc, "Server trusts intermediat CA and accepts a partial chain. (partial_chain option)"}].
@@ -446,17 +432,7 @@ server_require_peer_cert_do_not_allow_partial_chain(Config) when is_list(Config)
 					      {from, self()},
 					      {mfa, {ssl_test_lib, no_result, []}},
 					      {options, ClientOpts}]),
-
-    receive
-	 {Server, {error, {tls_alert, "unknown ca"}}} ->
-	    receive
-		{Client, {error, {tls_alert, "unknown ca"}}} ->
-		    ok;
-		{Client, {error, closed}} ->
-		    ok
-	    end
-    end.
-
+    ssl_test_lib:check_server_alert(Server, Client, unknown_ca).
  %%--------------------------------------------------------------------
 server_require_peer_cert_partial_chain_fun_fail() ->
     [{doc, "If parial_chain fun crashes, treat it as if it returned unkown_ca"}].
@@ -487,16 +463,7 @@ server_require_peer_cert_partial_chain_fun_fail(Config) when is_list(Config) ->
 					      {from, self()},
 					      {mfa, {ssl_test_lib, no_result, []}},
 					      {options, ClientOpts}]),
-
-    receive
-	 {Server, {error, {tls_alert, "unknown ca"}}} ->
-	    receive
-		{Client, {error, {tls_alert, "unknown ca"}}} ->
-		    ok;
-		{Client, {error, closed}} ->
-		    ok
-	    end
-    end.
+    ssl_test_lib:check_server_alert(Server, Client, unknown_ca).
 
 %%--------------------------------------------------------------------
 verify_fun_always_run_client() ->
@@ -535,14 +502,8 @@ verify_fun_always_run_client(Config) when is_list(Config) ->
 					       [{verify, verify_peer},
 						{verify_fun, FunAndState}
 						| ClientOpts]}]),
-    %% Server error may be {tls_alert,"handshake failure"} or closed depending on timing
-    %% this is not a bug it is a circumstance of how tcp works!
-    receive
-	{Server, ServerError} ->
-	    ct:log("Server Error ~p~n", [ServerError])
-    end,
 
-    ssl_test_lib:check_result(Client, {error, {tls_alert, "handshake failure"}}).
+    ssl_test_lib:check_client_alert(Server, Client, handshake_failure).
 
 %%--------------------------------------------------------------------
 verify_fun_always_run_server() ->
@@ -581,16 +542,8 @@ verify_fun_always_run_server(Config) when is_list(Config) ->
 					      {mfa, {ssl_test_lib,
 						     no_result, []}},
 					      {options, ClientOpts}]),
-
-    %% Client error may be {tls_alert, "handshake failure" } or closed depending on timing
-    %% this is not a bug it is a circumstance of how tcp works!
-    receive
-	{Client, ClientError} ->
-	    ct:log("Client Error ~p~n", [ClientError])
-    end,
-
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "handshake failure"}}).
-
+    
+    ssl_test_lib:check_client_alert(Server, Client, handshake_failure).
 %%--------------------------------------------------------------------
 
 cert_expired() ->
@@ -620,8 +573,7 @@ cert_expired(Config) when is_list(Config) ->
 					      {from, self()},
 					      {options, [{verify, verify_peer}, {active, Active}  | ClientOpts]}]),    
     
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "certificate expired"}},
-                              Client, {error, {tls_alert, "certificate expired"}}).
+    ssl_test_lib:check_client_alert(Server, Client, certificate_expired).
 
 two_digits_str(N) when N < 10 ->
     lists:flatten(io_lib:format("0~p", [N]));
@@ -727,12 +679,8 @@ critical_extension_verify_server(Config) when is_list(Config) ->
                 {options, [{verify, verify_none}, {active, Active} | ClientOpts]}]),
 
     %% This certificate has a critical extension that we don't
-    %% understand.  Therefore, verification should fail.      
-
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "unsupported certificate"}},
-                              Client, {error, {tls_alert, "unsupported certificate"}}),
-    
-    ssl_test_lib:close(Server).
+    %% understand.  Therefore, verification should fail.          
+    ssl_test_lib:check_server_alert(Server, Client, unsupported_certificate).
 %%--------------------------------------------------------------------
 
 critical_extension_verify_client() ->
@@ -763,12 +711,7 @@ critical_extension_verify_client(Config) when is_list(Config) ->
                 {mfa, {ssl_test_lib, ReceiveFunction, []}},
                 {options, [{verify, verify_peer}, {active, Active} | ClientOpts]}]),
 
-    %% This certificate has a critical extension that we don't
-    %% understand.  Therefore, verification should fail.
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "unsupported certificate"}},
-                              Client, {error, {tls_alert, "unsupported certificate"}}),
-
-    ssl_test_lib:close(Server).
+    ssl_test_lib:check_client_alert(Server, Client, unsupported_certificate).
 
 %%--------------------------------------------------------------------
 critical_extension_verify_none() ->
@@ -908,10 +851,7 @@ invalid_signature_server(Config) when is_list(Config) ->
 					      {host, Hostname},
 					      {from, self()},
 					      {options, [{verify, verify_peer} | ClientOpts]}]),
-
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "unknown ca"}},
-                              Client, {error, {tls_alert, "unknown ca"}}).
-
+    ssl_test_lib:check_server_alert(Server, Client, unknown_ca).
 %%--------------------------------------------------------------------
 
 invalid_signature_client() ->
@@ -946,9 +886,7 @@ invalid_signature_client(Config) when is_list(Config) ->
 					      {from, self()},
 					      {options, NewClientOpts}]),
 
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "unknown ca"}},
-                              Client, {error, {tls_alert, "unknown ca"}}).
-
+    ssl_test_lib:check_client_alert(Server, Client, unknown_ca).
 
 %%--------------------------------------------------------------------
 
@@ -1034,16 +972,7 @@ unknown_server_ca_fail(Config) when is_list(Config) ->
 					       [{verify, verify_peer},
 						{verify_fun, FunAndState}
 						| ClientOpts]}]),
-    receive
-	{Client, {error, {tls_alert, "unknown ca"}}} ->
-	    receive
-		{Server, {error, {tls_alert, "unknown ca"}}} ->
-		    ok;
-		{Server, {error, closed}} ->
-		    ok
-	    end
-    end.
-
+    ssl_test_lib:check_client_alert(Server, Client, unknown_ca).
 
 %%--------------------------------------------------------------------
 unknown_server_ca_accept_verify_none() ->
@@ -1193,11 +1122,7 @@ customize_hostname_check(Config) when is_list(Config) ->
                                                {mfa, {ssl_test_lib, no_result, []}},
                                                {options, ClientOpts}
                                               ]),    
-    ssl_test_lib:check_result(Client1, {error, {tls_alert, "handshake failure"}},
-                              Server,  {error, {tls_alert, "handshake failure"}}),
-    
-    ssl_test_lib:close(Server),
-    ssl_test_lib:close(Client).
+    ssl_test_lib:check_client_alert(Server, Client1, handshake_failure).
 
 incomplete_chain() ->
     [{doc,"Test option verify_peer"}].
diff --git a/lib/ssl/test/ssl_crl_SUITE.erl b/lib/ssl/test/ssl_crl_SUITE.erl
index c61039b5da..b2fd3874a8 100644
--- a/lib/ssl/test/ssl_crl_SUITE.erl
+++ b/lib/ssl/test/ssl_crl_SUITE.erl
@@ -238,7 +238,7 @@ crl_verify_revoked(Config)  when is_list(Config) ->
 		  end,	
     
     crl_verify_error(Hostname, ServerNode, ServerOpts, ClientNode, ClientOpts,
-                     "certificate revoked").
+                     certificate_revoked).
 
 crl_verify_no_crl() ->
     [{doc,"Verify a simple CRL chain when the CRL is missing"}].
@@ -277,10 +277,10 @@ crl_verify_no_crl(Config) when is_list(Config) ->
             %% The error "revocation status undetermined" gets turned
             %% into "bad certificate".
             crl_verify_error(Hostname, ServerNode, ServerOpts, ClientNode, ClientOpts,
-                             "bad certificate");
+                             bad_certificate);
         peer ->
             crl_verify_error(Hostname, ServerNode, ServerOpts, ClientNode, ClientOpts,
-                             "bad certificate");
+                             bad_certificate);
         best_effort ->
             %% In "best effort" mode, we consider the certificate not
             %% to be revoked if we can't find the appropriate CRL.
@@ -341,7 +341,7 @@ crl_hash_dir_collision(Config) when is_list(Config) ->
 
     %% First certificate revoked; first fails, second succeeds.
     crl_verify_error(Hostname, ServerNode, ServerOpts1, ClientNode, ClientOpts,
-                     "certificate revoked"),
+                     certificate_revoked),
     crl_verify_valid(Hostname, ServerNode, ServerOpts2, ClientNode, ClientOpts),
 
     make_certs:revoke(PrivDir, CA2, "collision-client-2", CertsConfig),
@@ -352,9 +352,9 @@ crl_hash_dir_collision(Config) when is_list(Config) ->
 
     %% Second certificate revoked; both fail.
     crl_verify_error(Hostname, ServerNode, ServerOpts1, ClientNode, ClientOpts,
-                     "certificate revoked"),
+                     certificate_revoked),
     crl_verify_error(Hostname, ServerNode, ServerOpts2, ClientNode, ClientOpts,
-                     "certificate revoked"),
+                     certificate_revoked),
 
     ok.
 
@@ -400,10 +400,10 @@ crl_hash_dir_expired(Config) when is_list(Config) ->
             %% The error "revocation status undetermined" gets turned
             %% into "bad certificate".
             crl_verify_error(Hostname, ServerNode, ServerOpts, ClientNode, ClientOpts,
-                             "bad certificate");
+                             bad_certificate);
         peer ->
             crl_verify_error(Hostname, ServerNode, ServerOpts, ClientNode, ClientOpts,
-                             "bad certificate");
+                             bad_certificate);
         best_effort ->
             %% In "best effort" mode, we consider the certificate not
             %% to be revoked if we can't find the appropriate CRL.
@@ -451,11 +451,8 @@ crl_verify_error(Hostname, ServerNode, ServerOpts, ClientNode, ClientOpts, Expec
 					      {host, Hostname},
 					      {from, self()},
 					      {options, ClientOpts}]),
-    receive
-	{Server, AlertOrClose} ->
-	    ct:pal("Server Alert or Close ~p", [AlertOrClose])
-    end,
-    ssl_test_lib:check_result(Client, {error, {tls_alert, ExpectedAlert}}).
+
+    ssl_test_lib:check_client_alert(Server, Client, ExpectedAlert).
 
 %%--------------------------------------------------------------------
 %% Internal functions ------------------------------------------------
diff --git a/lib/ssl/test/ssl_sni_SUITE.erl b/lib/ssl/test/ssl_sni_SUITE.erl
index 251b6a2639..7629d75100 100644
--- a/lib/ssl/test/ssl_sni_SUITE.erl
+++ b/lib/ssl/test/ssl_sni_SUITE.erl
@@ -236,8 +236,8 @@ dns_name_reuse(Config) ->
                                          {mfa, {ssl_test_lib, session_info_result, []}},
                                          {from, self()},  {options, [{verify, verify_peer} | ClientConf]}]),
     
-    ssl_test_lib:check_result(Client1, {error, {tls_alert, "handshake failure"}}),
-    ssl_test_lib:close(Client0).
+    ssl_test_lib:check_client_alert(Client1, handshake_failure).
+
 %%--------------------------------------------------------------------
 %% Internal Functions ------------------------------------------------
 %%--------------------------------------------------------------------
@@ -370,8 +370,8 @@ unsuccessfull_connect(ServerOptions, ClientOptions, Hostname0, Config) ->
 					      {from, self()}, 
 					      {options, ClientOptions}]),
     
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "handshake failure"}},
-			      Client, {error, {tls_alert, "handshake failure"}}).
+    ssl_test_lib:check_server_alert(Server, Client, handshake_failure).
+
 host_name(undefined, Hostname) ->
     Hostname;
 host_name(Hostname, _) ->
diff --git a/lib/ssl/test/ssl_test_lib.erl b/lib/ssl/test/ssl_test_lib.erl
index fdbd39d016..f8b60c5edf 100644
--- a/lib/ssl/test/ssl_test_lib.erl
+++ b/lib/ssl/test/ssl_test_lib.erl
@@ -438,6 +438,37 @@ check_result(Pid, Msg) ->
 		      {got, Unexpected}},
 	    ct:fail(Reason)
     end.
+check_server_alert(Pid, Alert) ->
+    receive
+	{Pid, {error, {tls_alert, {Alert, _}}}} ->
+            ok
+    end.
+check_server_alert(Server, Client, Alert) ->
+    receive
+	{Server, {error, {tls_alert, {Alert, _}}}} ->
+	    receive
+		{Client, {error, {tls_alert, {Alert, _}}}} ->
+		    ok;
+		{Client, {error, closed}} ->
+		    ok
+	    end
+    end.
+check_client_alert(Pid, Alert) ->
+    receive
+	{Pid, {error, {tls_alert, {Alert, _}}}} ->
+            ok
+    end.
+check_client_alert(Server, Client, Alert) ->
+    receive
+	{Client, {error, {tls_alert, {Alert, _}}}} ->
+	    receive
+		{Server, {error, {tls_alert, {Alert, _}}}} ->
+		    ok;
+		{Server, {error, closed}} ->
+		    ok
+	    end
+    end.
+
 
 wait_for_result(Server, ServerMsg, Client, ClientMsg) -> 
     receive 
@@ -1072,8 +1103,7 @@ ecc_test(Expect, COpts, SOpts, CECCOpts, SECCOpts, Config) ->
 ecc_test_error(COpts, SOpts, CECCOpts, SECCOpts, Config) ->
     {Server, Port} = start_server_ecc_error(erlang, SOpts, SECCOpts, Config),
     Client = start_client_ecc_error(erlang, Port, COpts, CECCOpts, Config),
-    Error = {error, {tls_alert, "insufficient security"}},
-    check_result(Server, Error, Client, Error).
+    check_server_alert(Server, Client, insufficient_security).
 
 start_client(openssl, Port, ClientOpts, Config) ->
     Cert = proplists:get_value(certfile, ClientOpts),
diff --git a/lib/ssl/test/ssl_to_openssl_SUITE.erl b/lib/ssl/test/ssl_to_openssl_SUITE.erl
index d180021439..87a1edfd96 100644
--- a/lib/ssl/test/ssl_to_openssl_SUITE.erl
+++ b/lib/ssl/test/ssl_to_openssl_SUITE.erl
@@ -1249,7 +1249,7 @@ ssl2_erlang_server_openssl_client(Config) when is_list(Config) ->
 
     ct:log("Ports ~p~n", [[erlang:port_info(P) || P <- erlang:ports()]]), 
     ssl_test_lib:consume_port_exit(OpenSslPort),
-    ssl_test_lib:check_result(Server, {error, {tls_alert, "bad record mac"}}),
+    ssl_test_lib:check_server_alert(Server, bad_record_mac),
     process_flag(trap_exit, false).
 
 %%--------------------------------------------------------------------
diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml
index 9d7eb55a7e..4465103469 100644
--- a/lib/stdlib/doc/src/proplists.xml
+++ b/lib/stdlib/doc/src/proplists.xml
@@ -57,6 +57,11 @@
     <datatype>
       <name name="property"/>
     </datatype>
+
+    <datatype>
+      <name name="proplist"/>
+    </datatype>
+
   </datatypes>
 
   <funcs>