.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
+.TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
.SH NAME
key \- simple key management system
.SH SYNOPSIS
is one of:
.PP
.B add
-.RB [ \-lq ]
+.RB [ \-lqrLS ]
.RB [ \-a
.IR alg ]
.RB [ \-b | \-B
.IR bits ]
.RB [ \-p
.IR param ]
-.RB [ \-r
+.RB [ \-R
.IR tag ]
.br
\h'8n'
.I "global options"
may be given. The following global options are supported:
.TP
-.B "\-h, \-\-help"
+.BR "\-h, \-\-help " [ \fIcommand ]
Writes a brief summary of
.BR key 's
various options to standard output, and
-returns a successful exit status.
+returns a successful exit status. With a command name, gives help on
+that command.
.TP
.B "\-v, \-\-version"
Writes the program's version number to standard output, and returns a
Selects a tag string for the key. The default is not to set a tag. It
is an error to select a tag which already exists.
.TP
-.BI "\-r, \-\-rand-id " tag
+.BI "\-r, \-\-retag"
+If a
+.B \-t
+option is given, remove this tag from any key which already has it.
+.TP
+.BI "\-R, \-\-rand-id " tag
Selects the key to use for the random number generator. Catacomb's
random number generator can be
.IR keyed ,
.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
.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,
Sets, deletes or changes the tag attached to a key. The first tag or
keyid names the key to be modified; the second, if present specifies the
new tag to be set. If no second argument is given, the existing tag, if
-any, is removed and no new tag is set.
+any, is removed and no new tag is set. It is an error to set a tag
+which already exists on another key, unless you give the
+.B \-r
+option, which removes the tag first.
.SS "setattr"
Attaches attributes to a key. The key to which the attributes should be
attached is given by its
projects / u / mdw / catacomb / blobdiff