From 1476eebc51ffeec4964f3f42691b52685876cab5 Mon Sep 17 00:00:00 2001
From: mdw <mdw>
Date: Sat, 29 Jul 2000 17:02:58 +0000
Subject: [PATCH] Describe the Lim-Lee prime stuff.

---
 key.1 | 97 +++++++++++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 71 insertions(+), 26 deletions(-)

diff --git a/key.1 b/key.1
index 2f47eff..9b0a843 100644
--- a/key.1
+++ b/key.1
@@ -2,10 +2,14 @@
 .ie t \{\
 .  ds ss \s8\u
 .  ds se \d\s0
+.  ds us \s8\d
+.  ds ue \u\s0
 .\}
 .el \{\
 .  ds ss ^
 .  ds se
+.  ds us _
+.  ds se
 .\}
 .TH key 1 "5 June 1999" Catacomb
 .SH NAME
@@ -21,7 +25,7 @@ where
 is one of:
 .PP
 .B add
-.RB [ \-lq ]
+.RB [ \-lqLS ]
 .RB [ \-a
 .IR alg ]
 .RB [ \-b | \-B
@@ -285,6 +289,16 @@ using a passphrase.
 .BI "\-q, \-\-quiet"
 Suppresses the progress indication which is usually generated while
 time-consuming key generation tasks are being performed.
+.TP
+.BI "\-L, --lim-lee"
+When generating Diffie-Hellman parameters, generate a Lim-Lee prime
+rather than a random (or safe) prime.  See the details on Diffie-Hellman
+key generation below.
+.TP
+.BI "\-S, --subgroup"
+When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
+generator of a prime-order subgroup rather than a subgroup of order
+.RI ( p "- 1)/2."
 .PP
 The key's type is given by the required
 .I type
@@ -370,39 +384,70 @@ factor the modulus and recover other users' private keys.
 .B "dh-params"
 Generates parameters for use with the Diffie-Hellman key exchange
 protocol, and many related systems, such as ElGamal encryption and
-signatures, and even DSA (although the DSA algorithm is probably better
-for this).  The parameters are a prime number
-.IR q ,
-a larger prime number
-.IR p ,
+signatures, and even DSA.  (The separate DSA algorithm uses the
+generator described in FIPS186-1.)
+.IP
+The Diffie-Hellman parameters are a prime modulus
+.I p
 and a generator
 .I g
-of the
-.RI order- q
-subgroup of the integers
-.RI mod\  p .
-.IP
-The key size set by the
+of a subgroup of
+.BR Z / \c
+.IB p Z
+of order
+.IR q .
+The
 .B \-b
-option determines the size of the modulus
+option controls the size of the modulus
 .IR p ;
-the size of the generator order
+the default size is 1024 bits.
+.IP
+If no 
 .I q
-is set by the
+size is selected using the
 .B \-B
-option.  The default modulus size is 1024 bits; if no size is specified
-for
-.IR q ,
-the parameters are chosen such that
+option and the Lim-Lee prime option is disabled, then 
+.I p
+is chosen to be a `safe' prime (i.e.,
 .IR p \ =\ 2 q \ +\ 1,
-and
-.I
-g
-is assigned the value 4.  This takes much longer.
+with
+.I q
+prime).  In this case, the value of
+.I g
+is fixed as 4.
+.IP
+If a size is chosen for
+.I q
+and Lim-Lee primes are not selected then the prime
+.I q
+is generated and
+.I p
+is chosen so that
+.IR p \ \-\ 1
+is a multiple of
+.IR q .
+.IP
+If the
+.B \-L
+option was given Lim-Lee primes are selected: the parameters are chosen
+such that
+.IR p \ =\ 2\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
+where the
+.IR q \*(us i\*(ue
+are primes at least as large as the setting given by the
+.B \-B
+option (or 256 bits, if no setting was given).
 .IP
-If used with the
-.B \-p
-option, the algorithm simply copies the parameters from an existing key.
+If the
+.B \-S
+option was given, the generator
+.I g
+is chosen to generate the subgroup of order
+.IR q \*(us0\*(ue;
+otherwise,
+.I g
+will generate the group of order
+.RI ( p \ \-\ 1)/2\ =\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
 .TP
 .B "dh"
 Generates a public/private key pair for use with offline Diffie-Hellman,
-- 
2.11.0