Document elliptic curve support.

diff --git a/key.1 b/key.1
index b4252df..e09ef51 100644 (file)
--- a/key.1
+++ b/key.1
@@ -42,6 +42,10 @@ is one of:
 .IR tag ]
 .RB [ \-c
 .IR comment ]
 .IR tag ]
 .RB [ \-c
 .IR comment ]

+.RB [ \-C
+.IR curve ]
+.br
+\h'8n'

 .I type
 .IR attr ...
 .br
 .I type
 .IR attr ...
 .br


@@ -269,6 +273,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, \-\-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.
 .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 +396,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
 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
 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


@@ -536,6 +545,99 @@ The key size requested by the
 option determines the length of the modulus
 .IR n ;
 the default length is 1024 bits.
 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
 .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