Merge pull request #1698 from IngelaAndin/ingela/ssl/add-ciphers-to-default/OTP-14760

Ingela/ssl/add ciphers to default/otp 14760

2 files changed, 129 insertions, 12 deletions

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 8fcda78ed5..3db5aa19ac 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -138,17 +138,20 @@
       <tag><c>sslsocket() =</c></tag>
       <item><p>opaque()</p></item>
 
-      <tag><marker id="type-protocol"/><c>protocol() =</c></tag>
+      <tag><marker id="type-protocol"/><c>protocol_version() =</c></tag>
       <item><p><c>sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'</c></p></item>
 
       <tag><c>ciphers() =</c></tag>
-      <item><p><c>= [ciphersuite()] | string()</c></p>
-      <p>According to old API.</p></item>
+      <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(), cipher(), MAC::hash()} |
-      {key_exchange(), cipher(), MAC::hash(), PRF::hash()}</c></p></item>
+      <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
@@ -165,6 +168,12 @@
       <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>
@@ -456,7 +465,7 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
       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>
 
-      <tag><c>{versions, [protocol()]}</c></tag>
+      <tag><c>{versions, [protocol_version()]}</c></tag>
       <item><p>TLS protocol versions supported by started clients and servers.
       This option overrides the application environment option
       <c>protocol_version</c>. If the environment option is not set, it defaults
@@ -829,14 +838,34 @@ fun(srp, Username :: string(), UserState :: term()) ->
   </section>
   
   <funcs>
+
+    <func>
+      <name>append_cipher_suites(Deferred, Suites) -> ciphers() </name>
+      <fsummary></fsummary>
+      <type>
+           <v>Deferred = ciphers() | cipher_filters() </v>
+	   <v>Suites  = ciphers() </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
+      <c>Suites</c> after removing them from <c>Suites</c> if
+      present. <c>Deferred</c> may be a list of cipher suits or a
+      list of filters in which case the filters are use on  <c>Suites</c> to
+      extract the Deferred cipher list.</p> 
+      </desc>
+    </func>
+    
     <func>
       <name>cipher_suites() -></name>
-      <name>cipher_suites(Type) -> ciphers()</name>
+      <name>cipher_suites(Type) -> old_ciphers()</name>
       <fsummary>Returns a list of supported cipher suites.</fsummary>
       <type>
         <v>Type = erlang | openssl | all</v>
       </type>
-      <desc><p>Returns a list of supported cipher suites.
+      <desc>
+	<p>Returns a list of supported cipher suites.
+	This function will become deprecated in OTP 21, and replaced
+	by <seealso marker="#cipher_suites-2">ssl:cipher-suites/2</seealso>
 	<c>cipher_suites()</c> is equivalent to <c>cipher_suites(erlang).</c>
 	Type <c>openssl</c> is provided for backwards compatibility with the
 	old SSL, which used OpenSSL. <c>cipher_suites(all)</c> returns
@@ -844,12 +873,25 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	in <c>cipher_suites(erlang)</c> but included in
 	<c>cipher_suites(all)</c> are not used unless explicitly configured
 	by the user.</p>
+      </desc>
+    </func>
+    
+   <func>
+      <name>cipher_suites(Supported, Version) ->  ciphers()</name>
+      <fsummary>Returns a list of all default or
+      all supported cipher suites.</fsummary>
+      <type>
+        <v> Supported = default | all | anonymous </v>
+	<v> Version = protocol_version() </v>
+      </type>
+      <desc><p>Returns all default or all supported (except anonymous), or all anonymous cipher suites for a
+      TLS version</p>
     </desc>
     </func>
 
     <func>
       <name>eccs() -></name>
-      <name>eccs(protocol()) -> [named_curve()]</name>
+      <name>eccs(protocol_version()) -> [named_curve()]</name>
       <fsummary>Returns a list of supported ECCs.</fsummary>
 
       <desc><p>Returns a list of supported ECCs. <c>eccs()</c>
@@ -1008,6 +1050,21 @@ fun(srp, Username :: string(), UserState :: term()) ->
       </desc>
     </func>
 
+      <func>
+      <name>filter_cipher_suites(Suites, Filters) -> ciphers()</name>
+      <fsummary></fsummary>
+      <type>
+	<v> Suites = ciphers()</v>
+        <v> Filters = cipher_filters()</v>
+      </type>
+      <desc><p>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
+      suites are supported by crypto. If no filter function is supplied for some
+      part the default behaviour is fun(Algorithm) -> true.</p>
+    </desc>
+    </func>
+    
     <func>
       <name>format_error(Reason) -> string()</name>
       <fsummary>Returns an error string.</fsummary>
@@ -1105,6 +1162,22 @@ fun(srp, Username :: string(), UserState :: term()) ->
         <p>Returns the address and port number of the peer.</p>
       </desc>
     </func>
+    
+      <func>
+      <name>prepend_cipher_suites(Preferred, Suites) -> ciphers()</name>
+      <fsummary></fsummary>
+      <type>
+        <v>Preferred = ciphers() | cipher_filters() </v>
+	<v>Suites = ciphers() </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
+      <c>Suites</c> after removing them from <c>Suites</c> if
+      present. <c>Preferred</c> may be a list of cipher suits or a
+      list of filters in which case the filters are use on <c>Suites</c> to
+      extract the preferred cipher list. </p>
+      </desc>
+    </func>
 
     <func>
       <name>prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()}</name>
@@ -1332,7 +1405,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <fsummary>Returns version information relevant for the
 	SSL application.</fsummary>
       <type>
-	<v>versions_info() = {app_vsn, string()} | {supported | available, [protocol()] </v>
+	<v>versions_info() = {app_vsn, string()} | {supported | available, [protocol_version()] </v>
       </type>
       <desc>
 	<p>Returns version information relevant for the SSL
diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml
index 61918a346d..775066ef7d 100644
--- a/lib/ssl/doc/src/using_ssl.xml
+++ b/lib/ssl/doc/src/using_ssl.xml
@@ -153,7 +153,51 @@ ok</code>
     </section>
   </section>
 
-   <section>
+  <section>
+    <title>Customizing cipher suits</title>
+
+    <p>Fetch default cipher suite list for an TLS/DTLS version. Change default
+    to all to get all possible cipher suites.</p>
+    <code type="erl">1>  Default = ssl:cipher_suites(default, 'tlsv1.2').
+    [#{cipher => aes_256_gcm,key_exchange => ecdhe_ecdsa,
+    mac => aead,prf => sha384}, ....]
+</code>
+
+    <p>In OTP 20 it is desirable to remove all cipher suites
+    that uses rsa kexchange (removed from default in 21) </p>
+    <code type="erl">2> NoRSA =
+    ssl:filter_cipher_suites(Default,
+                            [{key_exchange, fun(rsa) -> false;
+			                       (_) -> true end}]).
+    [...]
+    </code>
+
+    <p> Pick just a few suites </p>
+    <code type="erl"> 3> Suites =
+    ssl:filter_cipher_suites(Default,
+                            [{key_exchange, fun(ecdh_ecdsa) -> true;
+			                       (_) -> false end},
+                             {cipher, fun(aes_128_cbc) ->true;
+			                  (_) ->false end}]).
+    [#{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,
+     mac => sha256,prf => sha256},
+     #{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,mac => sha,
+     prf => default_prf}]
+    </code>
+    
+    <p> Make some particular suites the most preferred, or least
+    preferred by changing prepend to append.</p>
+    <code type="erl"> 4>ssl:prepend_cipher_suites(Suites, Default).
+  [#{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,
+     mac => sha256,prf => sha256},
+   #{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,mac => sha,
+     prf => default_prf},
+   #{cipher => aes_256_cbc,key_exchange => ecdhe_ecdsa,
+     mac => sha384,prf => sha384}, ...]
+    </code>
+  </section>      
+
+  <section>
     <title>Using an Engine Stored Key</title>
     
     <p>Erlang ssl application is able to use private keys provided