From cbc8e9ce89ce30e3be90d9ad500becd3c26370e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= <peterdmv@erlang.org>
Date: Tue, 23 Jul 2019 15:57:58 +0200
Subject: ssl: Document option supported_groups

---
 lib/ssl/doc/src/ssl.xml | 23 ++++++++++++++++++++++-
 lib/ssl/src/ssl.erl     |  7 +++++--
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 3aa6e09c2c..05590666da 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -207,6 +207,10 @@
      <datatype>
        <name name="sign_scheme"/>
      </datatype>
+
+     <datatype>
+       <name name="group"/>
+     </datatype>
      
      <datatype>
       <name name="kex_algo"/>
@@ -363,7 +367,20 @@
 	  </p>
       </desc>
      </datatype>
-     
+
+     <datatype>
+       <name name="supported_groups"/>
+       <desc>
+	 <p>TLS 1.3 introduces the "supported_groups" extension that is used for negotiating
+	 the Diffie-Hellman parameters in a TLS 1.3 handshake. Both client and server
+	 can specify a list of parameters that they are willing to use.
+	 </p>
+	 <p> If it is not specified it will use a default list ([x25519, x448, secp256r1, secp384r1]) that
+	 is filtered based on the installed crypto library version.
+	 </p>
+      </desc>
+     </datatype>
+
     <datatype>
       <name name="secure_renegotiation"/>
       <desc><p>Specifies if to reject renegotiation attempt that does
@@ -919,6 +936,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	<name name="dh_der"/>
 	<desc><p>The DER-encoded Diffie-Hellman parameters. If
 	specified, it overrides option <c>dhfile</c>.</p>
+	<warning><p>The <c>dh_der</c> option is not supported by TLS 1.3. Use the
+	<c>supported_groups</c> option instead.</p></warning>
 	</desc>
       </datatype>
     
@@ -928,6 +947,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	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>
+	<warning><p>The <c>dh_file</c> option is not supported by TLS 1.3. Use the
+	<c>supported_groups</c> option instead.</p></warning>
 	</desc>
       </datatype>
 
diff --git a/lib/ssl/src/ssl.erl b/lib/ssl/src/ssl.erl
index 20b1e85ceb..ce639e8fde 100644
--- a/lib/ssl/src/ssl.erl
+++ b/lib/ssl/src/ssl.erl
@@ -128,7 +128,8 @@
               tls_alert/0,
               srp_param_type/0,
               named_curve/0,
-              sign_scheme/0]).
+              sign_scheme/0,
+              group/0]).
 
 %% -------------------------------------------------------------------------------------------------------
 
@@ -243,7 +244,7 @@
                                  secp160r2. % exported
 
 -type group() :: secp256r1 | secp384r1 | secp521r1 | ffdhe2048 |
-                 ffdhe3072 | ffdhe4096 | ffdhe6144 | ffdhe8192.
+                 ffdhe3072 | ffdhe4096 | ffdhe6144 | ffdhe8192. % exported
 
 -type srp_param_type()        :: srp_1024 |
                                  srp_1536 |
@@ -296,6 +297,7 @@
                                 {ciphers, cipher_suites()} |
                                 {eccs, [named_curve()]} |
                                 {signature_algs_cert, signature_schemes()} |
+                                {supported_groups, supported_groups()} |
                                 {secure_renegotiate, secure_renegotiation()} |
                                 {depth, allowed_cert_chain_length()} |
                                 {verify_fun, custom_verify()} |
@@ -342,6 +344,7 @@
 -type protocol_versions()        ::  [protocol_version()].
 -type signature_algs()           ::  [{hash(), sign_algo()}].
 -type signature_schemes()        ::  [sign_scheme()].
+-type supported_groups()         ::  [group()].
 -type custom_user_lookup()       ::  {Lookupfun :: fun(), UserState :: any()}.
 -type padding_check()            :: boolean(). 
 -type beast_mitigation()         :: one_n_minus_one | zero_n | disabled.
-- 
cgit v1.2.3