X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/d07dfe80efdb7969c7a4c2b3a22629836bd2c87e..a9fcea0e5ef17bab8eaca2236016e109ab62488e:/key.1

diff --git a/key.1 b/key.1
index b4252df..cab0d41 100644
--- 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
@@ -42,6 +47,10 @@ is one of:
 .IR tag ]
 .RB [ \-c
 .IR comment ]
+.RB [ \-C
+.IR curve ]
+.br
+\h'8n'
 .I type
 .IR attr ...
 .br
@@ -166,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);
@@ -269,6 +286,11 @@ The default is to allow a 2 week expiry, which isn't useful.
 .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.
@@ -387,7 +409,7 @@ cannot be sensibly used as a shared parameter, since knowledge of
 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.  (The separate DSA algorithm uses the
@@ -418,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
@@ -454,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,
@@ -536,6 +570,104 @@ The key size requested by the
 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 \-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
+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" ,
+.BR "binpoly" ,
+.or
+.BR "binnorm" ;
+an optional
+.RB ` : ';
+the field modulus
+.IR p ;
+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" ,
+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