.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'
.IR tag ]
.RB [ \-c
.IR comment ]
+.RB [ \-C
+.IR curve ]
+.br
+\h'8n'
.I type
.IR attr ...
.br
.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
.BI "\-c, \-\-comment " comment
Sets a comment for the key. The default is not to attach a comment.
.TP
+.BI "\-C, \-\-curve " curve-spec
+Use the elliptic curve described by
+.I curve-spec
+when generating elliptic curve parameters.
+.TP
.BI "\-t, \-\-tag " tag
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
corrssponding public and private exponents is sufficient to be able to
factor the modulus and recover other users' private keys.
.TP
-.B "dh-params"
+.B "dh-param"
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 used with the
-.B \-p
-option, the algorithm simply copies the parameters from an existing key.
+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 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,
option determines the length of the modulus
.IR n ;
the default length is 1024 bits.
+.TP
+.B "ec-param"
+Store an elliptic curve specification. If no explicit
+.I curve-spec
+is given (the
+.RB ` \-C '
+option) then a curve is chosen whose order is about the size given by the
+.RB ` \-b '
+option (default is 256 bits).
+.IP
+A
+.I curve-spec
+can be given explicitly (in which case
+.RB ` \-b '
+is ignored). It can either be the name of a built-in curve (say
+.B "key add \-C list"
+for a list of curve names) or a full specification. The curve is
+checked for correctness and security according to the SEC1
+specification: failed checks cause a warning to be issued to standard
+error (though the program continues anyway). The check can be
+suppressed using the
+.RB ` \-q '
+option.
+.IP
+A curve specification consists of the following elements optionally
+separated by whitespace: a
+.IR "field type" ,
+which is one of
+.BR "prime" ,
+.BR "niceprime" ,
+or
+.BR "binpoly" ;
+an optional
+.RB ` : ';
+the field modulus
+.IR p ;
+an optional
+.RB ` / ';
+a
+.IR "curve type" ,
+which is one of
+.BR "prime" ,
+.BR "primeproj" ,
+.BR "bin" ,
+and
+.BR "binproj"
+(the `proj' types currently have much better performance);
+an optional
+.RB ` : ';
+the two field-element parameters
+.I a
+and
+.IR b
+which define the elliptic curve
+.IR E ,
+separated by an optional
+.RB ` , ';
+an optional
+.RB ` / ';
+the
+.IR x -
+and
+.IR y -coordinates
+of the generator point
+.IR G ,
+separated by an optional
+.RB ` , ';
+an optional
+.RB ` : ';
+the order
+.I r
+of the group generated by
+.IR G ;
+an optional
+.RB ` * ';
+and the
+.I cofactor
+.I h
+=
+.RI # E / r .
+.TP
+.B "ec"
+Generate a private scalar and a corresponding public point on an
+elliptic curve. See
+.B ec-param
+above for how to specify elliptic curve parameter sets. The scalar
+.I x
+is chosen unformly between 0 and the curve order
+.IR r ;
+the public point is then
+.I x
+\(mu
+.IR G .
.SS "expire"
Forces keys to immediately expire. An expired key is not chosen when a
program requests a key by its type. The keys to expire are listed by
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