.\" -*-nroff-*-
.ie t \{\
+. if \n(.g \{\
+. fam P
+. \}
. ds ss \s8\u
. ds se \d\s0
. ds us \s8\d
. ds ue \u\s0
+. ds *b \(*b
.\}
.el \{\
. ds ss ^
. ds se
. ds us _
-. ds se
+. ds ue
+. ds *b \fIbeta\fP
.\}
.TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
.SH NAME
keys. Keys used with number-theoretic systems (like most common
public-key systems) use
.I "multiprecision integer"
-keys. Algorithms which require several key constituents (again, like
-most public-key systems) use
+keys. Elliptic curve systems use
+.I "curve point"
+keys, which are either a pair of integers representing field elements,
+or a `point at infinity'. Algorithms which require several key
+constituents (again, like most public-key systems) use
.I structured
-keys, which consist of a collection of named parts. Finally, keys
-(including structured keys) can be encrypted.
+keys, which consist of a collection of named parts. It's possible to
+store an
+.I "ASCII string"
+as a key, though this is usually done as a component of a structured
+key. Finally, keys (including structured keys) can be encrypted.
.TP
.B "filter"
Keys and key components may be selected by a filter expression, a
sequence of flag names separated by commas. Flags are:
.BR binary ,
.BR integer ,
-.B struct
+.BR struct ,
+.BR ec ,
+.BR string ,
or
.B encrypt
(describing the key encoding);
.BR symmetric ,
.BR private ,
-.B public
+.BR public ,
or
.B shared
(describing the category of key);
.IR p \ =\ 2 q \ +\ 1,
with
.I q
-prime). In this case, the value of
+prime). Finding safe primes takes a very long time. In this case, the
+value of
.I g
is fixed as 4.
.IP
.I g
will generate the group of order
.RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
+.IP
+Finally, the
+.B \-C
+option can be given, in which case the parameters are taken directly
+from the provided group specification, which may either be the the name
+of one of the built-in groups (say
+.B "key add \-a dh\-param \-C list 42"
+for a list) or a triple
+.RI ( p ,\ q ,\ g ).
+separated by commas. No random generation is done in this case: the
+given parameters are simply stored.
.TP
.B "dh"
Generates a public/private key pair for use with offline Diffie-Hellman,
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"
+.B "key add \-a ec\-param \-C list 42"
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
which is one of
.BR "prime" ,
.BR "niceprime" ,
-or
-.BR "binpoly" ;
+.BR "binpoly" ,
+.or
+.BR "binnorm" ;
an optional
.RB ` : ';
the field modulus
.IR p ;
-an optional
+if the field type is
+.B binnorm
+then an optional
+.RB ` , '
+and the representation of the normal element \*(*b; an optional
.RB ` / ';
a
.IR "curve type" ,