Update manuals.

[u/mdw/catacomb] / key.1

diff --git a/key.1 b/key.1
index e09ef51..cab0d41 100644 (file)
--- a/key.1
+++ b/key.1
@@ -1,15 +1,20 @@
 .\" -*-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
@@ -170,24 +175,32 @@ algorithms use
 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);
@@ -427,7 +440,8 @@ is chosen to be a `safe' prime (i.e.,
 .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
@@ -463,6 +477,17 @@ otherwise,
 .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,
@@ -560,7 +585,7 @@ A
 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
@@ -575,13 +600,18 @@ separated by whitespace: a
 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" ,