Expunge revision histories in files.
[u/mdw/catacomb] / key.1
diff --git a/key.1 b/key.1
index 9b0a843..1b6c7e5 100644 (file)
--- a/key.1
+++ b/key.1
@@ -1,17 +1,22 @@
 .\" -*-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" Catacomb
+.TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
 .SH NAME
 key \- simple key management system
 .SH SYNOPSIS
@@ -25,14 +30,14 @@ where
 is one of:
 .PP
 .B add
-.RB [ \-lqLS ]
+.RB [ \-lqrLS ]
 .RB [ \-a
 .IR alg ]
 .RB [ \-b | \-B
 .IR bits ]
 .RB [ \-p
 .IR param ]
-.RB [ \-r
+.RB [ \-R
 .IR tag ]
 .br
 \h'8n'
@@ -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
@@ -78,6 +87,8 @@ is one of:
 .B fingerprint
 .RB [ \-f
 .IR filter ]
+.RB [ \-a
+.IR hash ]
 .RI [ tag ...]
 .br
 .B tidy
@@ -101,11 +112,12 @@ Before the command name,
 .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
@@ -165,24 +177,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);
@@ -268,11 +288,21 @@ 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.
 .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 ,
@@ -381,7 +411,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
@@ -412,7 +442,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
@@ -448,6 +479,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,
@@ -530,6 +572,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
@@ -544,7 +684,10 @@ to expire keys rather than deleting them.
 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
@@ -603,10 +746,18 @@ The following option is supported:
 Specifies a filter.  Only keys and key components which match the filter
 are fingerprinted.  The default is to only fingerprint nonsecret
 components.
+.TP
+.BI "\-a, \-\-algorithm " hash
+Names the hashing algorithm.  Run
+.B hashsum -a list
+for a list of hashing algorithms.  The default is
+.BR rmd160 .
 .PP
 The keys to be fingerprinted are named by their tags or keyids given as
 command line arguments.  If no key tags are given, all keys which match
-the filter are fingerprinted.
+the filter are fingerprinted.  See
+.BR keyring (5)
+for a description of how key fingerprints are computed.
 .SS "tidy"
 Simply reads the keyring from file and writes it back again.  This has
 the effect of removing any deleted keys from the file.