ssh, public_key: random selection of diffie-hellman moduli

Also tool (public_key:gen_moduli_hrl) to convert an openssh moduli file to erlang format.

1 files changed, 31 insertions, 0 deletions

diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index b247618efc..7f68138497 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -299,6 +299,37 @@
   </desc> 
   </func>
 
+  <func>
+    <name>dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) -> {ok, {Size,Group}} | {error,Error}</name>
+    <fsummary>Selects a group for Diffie-Hellman key exchange</fsummary>
+    <type>
+      <v>MinSize = positive_integer()</v>
+      <v>SuggestedSize = positive_integer()</v>
+      <v>MaxSize = positive_integer()</v>
+      <v>Groups = undefined | [{Size,[{G,P}]}]</v>
+      <v>Size = positive_integer()</v>
+      <v>Group = {G,P}</v>
+      <v>G = positive_integer()</v>
+      <v>P = positive_integer()</v>
+    </type>
+    <desc>
+      <p>Selects a group for Diffie-Hellman key exchange with the key size in the range <c>MinSize...MaxSize</c>
+      and as close to <c>SuggestedSize</c> as possible. If <c>Groups == undefined</c> a default set will be
+      used, otherwise the group is selected from <c>Groups</c>.</p>
+      <p>First is a size as close as possible to <c>SuggestedSize</c> selected. Then is one group with that key size
+      randomly selected from the list. If no size within the limits of <c>MinSize</c> and <c>MaxSize</c> is
+      available, <c>{error,no_group_found}</c> is returned.</p>
+      <p>The default list is in <c>lib/public_key/priv/ssh_moduli</c>. The format is as produced by the openssh tool
+      <c>ssh-keygen -G</c> followed by <c>ssh-keygen -T</c>. When that list is changed, <c>make</c> should be run in
+      <c>lib/public_key</c> to make it available for <c>dh_gex_group/4</c>.</p>
+	    <note>
+	      <p>If you change the default ssh_moduli file, be sure to run <c>ssh-keygen -T</c> as described
+	      in the ssh-keygen manual. Failure to do so correctly will compromise the security of applications
+	      relying on this function.</p>
+	    </note>
+    </desc>
+  </func>
+
     <func>
     <name>encrypt_private(PlainText, Key) -> binary()</name>
     <fsummary>Public-key encryption using the private key.</fsummary>