X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/052b36d05a622a93733b735acce2de865b14627b..6ec3a4cf4aaa7cd375e1aa18f85861986259b8e5:/key.1

diff --git a/key.1 b/key.1
index 2f47eff..3e7a601 100644
--- a/key.1
+++ b/key.1
@@ -1,13 +1,34 @@
 .\" -*-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 ue
+.  ds *b \fIbeta\fP
 .\}
-.TH key 1 "5 June 1999" Catacomb
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
 .SH NAME
 key \- simple key management system
 .SH SYNOPSIS
@@ -20,24 +41,42 @@ where
 .I command
 is one of:
 .PP
+.B help
+.RI [ command ...]
+.br
+.B show
+.RI [ item ...]
+.br
 .B add
-.RB [ \-lq ]
+.RB [ \-lqrLKS ]
 .RB [ \-a
 .IR alg ]
 .RB [ \-b | \-B
 .IR bits ]
 .RB [ \-p
 .IR param ]
-.RB [ \-r
+.RB [ \-R
 .IR tag ]
 .br
 \h'8n'
+.RB [ \-A
+.IR seed-alg ]
+.RB [ \-s
+.IR seed ]
+.RB [ \-n
+.IR bits ]
+.br
+\h'8n'
 .RB [ \-e
 .IR expire ]
 .RB [ \-t
 .IR tag ]
 .RB [ \-c
 .IR comment ]
+.RB [ \-C
+.IR curve ]
+.br
+\h'8n'
 .I type
 .IR attr ...
 .br
@@ -59,6 +98,10 @@ is one of:
 .I tag
 .IR attr ...
 .br
+.B getattr
+.I tag
+.I attr
+.br
 .B lock
 .I qtag
 .br
@@ -74,8 +117,18 @@ is one of:
 .B fingerprint
 .RB [ \-f
 .IR filter ]
+.RB [ \-a
+.IR hash ]
 .RI [ tag ...]
 .br
+.B verify
+.RB [ \-f
+.IR filter ]
+.RB [ \-a
+.IR hash ]
+.I tag
+.I fingerprint
+.br
 .B tidy
 .br
 .B extract
@@ -97,11 +150,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 command names, gives help on
+those commands.
 .TP
 .B "\-v, \-\-version"
 Writes the program's version number to standard output, and returns a
@@ -161,24 +215,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);
@@ -222,6 +284,62 @@ arbitrary strings, except they may not contain null bytes.  Some
 attributes may have meaning for particular applications or key types;
 others may be assigned global meanings in future.
 .SH "COMMAND REFERENCE"
+.SS help
+The
+.B help
+command behaves exactly as the
+.B \-\-help
+option.  With no arguments, it shows an overview of
+.BR key 's
+options; with arguments, it describes the named subcommands.
+.SS show
+The
+.B show
+command prints various lists of tokens understood by
+.BR key .
+With no arguments, it prints all of the lists; with arguments, it prints
+just the named lists, in order.  The recognized lists can be enumerated
+using the
+.VS
+key show list
+.VE
+command.  The lists are as follows.
+.TP
+.B list
+The lists which can be enumerated by the
+.B show
+command.
+.TP
+.B hash
+The hash functions which can be used with the
+.B fingerprint
+and
+.B verify
+commands.
+.TP
+.B ec
+The built-in elliptic curves which can be used with the
+.B add \-a ec
+command.
+.TP
+.B dh
+The built-in Diffie-Hellman groups which can be used with the
+.B add \-a dh
+command.
+.TP
+.B keygen
+The key-generation algorithms which are acceptable to the
+.B \-a
+option of the
+.B add
+command.
+.TP
+.B seed
+The pseudorandom generators which are acceptable to the
+.B \-s
+option of the
+.B add
+command.
 .SS add
 The
 .B add
@@ -231,7 +349,9 @@ accepts the following options:
 .BI "\-a, \-\-algorithm " alg
 Selects a key generation algorithm.  The default algorithm is
 .BR binary ;
-the different algorithms are described below.
+the different algorithms are described below.  The command
+.B key show keygen
+lists the recognized key-generation algorithms.
 .TP
 .BI "\-b, \-\-bits " bits
 The length of the key to generate, in bits.  The default, if this option
@@ -243,7 +363,53 @@ key-generation algorithms have a subsidiary key size.
 .TP
 .BI "\-p, \-\-parameters " tag
 Selects a key containing parameter values to copy.  Not all
-key-generation algorithms allow the use of shared parameters.
+key-generation algorithms allow the use of shared parameters.  A new key
+also inherits attributes from its parameter key.
+.TP
+.BI "\-A, \-\-seedalg " seed-alg
+Use the deterministic random number generator algorithm
+.I seed-alg
+to generate the key.  Use
+.I before
+the
+.B \-s
+or
+.B \-n
+options; without one of these,
+.B \-A
+has no effect.  The default algorithm is
+.BR rmd160-mgf .
+The command
+.B key show seed
+shows a list of recognized seeding algorithms.  The seeding algorithm
+used to generate a key is recorded as the key's
+.B seedalg
+attribute.
+.TP
+.BI "\-s, \-\-seed " seed
+Generate the key deterministically using the given
+.IR seed ,
+which should be a Base64-encoded binary string.  This is mainly useful
+for parameters keys (types
+.BR dsa-param
+and
+.BR dh-param ),
+to demonstrate that a set of parameters has been generated in an honest
+fashion.  The
+.B dsarand
+generation algorithm can be used to generate
+.B dsa-param
+keys as required by FIPS186.  The requested seed is recorded,
+Base64-encoded, as the new key's
+.B seed
+attribute.
+.TP
+.BI "\-n, \-\-newseed " bits
+Generate a new seed, with the given length in
+.IR bits .
+The generated seed is recorded, Base64-encoded, as the new key's
+.B seed
+attribute.
 .TP
 .BI "\-e, \-\-expire " expire
 The expiry date for the generated key.  This may be the string
@@ -264,11 +430,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 ,
@@ -285,6 +461,21 @@ using a passphrase.
 .BI "\-q, \-\-quiet"
 Suppresses the progress indication which is usually generated while
 time-consuming key generation tasks are being performed.
+.TP
+.BI "\-L, \-\-lim-lee"
+When generating Diffie-Hellman parameters, generate a Lim-Lee prime
+rather than a random (or safe) prime.  See the details on Diffie-Hellman
+key generation below.
+.TP
+.BI "\-K, \-\-kcdsa"
+When generating Diffie-Hellman parameters, generate a KCDSA-style
+Lim-Lee prime rather than a random (or safe) prime.  See the details on
+Diffie-Hellman key generation below.
+.TP
+.BI "\-S, \-\-subgroup"
+When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
+generator of a prime-order subgroup rather than a subgroup of order
+.RI ( p "- 1)/2."
 .PP
 The key's type is given by the required
 .I type
@@ -367,42 +558,99 @@ 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 (although the DSA algorithm is probably better
-for this).  The parameters are a prime number
-.IR q ,
-a larger prime number
-.IR p ,
+signatures, and even DSA.  (The separate DSA algorithm uses the
+generator described in FIPS186-1.)
+.IP
+The Diffie-Hellman parameters are a prime modulus
+.I p
 and a generator
 .I g
-of the
-.RI order- q
-subgroup of the integers
-.RI mod\  p .
-.IP
-The key size set by the
+of a subgroup of
+.BR Z / \c
+.IB p Z
+of order
+.IR q .
+The
 .B \-b
-option determines the size of the modulus
+option controls the size of the modulus
 .IR p ;
-the size of the generator order
+the default size is 1024 bits.
+.IP
+If no
 .I q
-is set by the
+size is selected using the
 .B \-B
-option.  The default modulus size is 1024 bits; if no size is specified
-for
-.IR q ,
-the parameters are chosen such that
+option and the Lim-Lee prime options are disabled, then
+.I p
+is chosen to be a `safe' prime (i.e.,
 .IR p \ =\ 2 q \ +\ 1,
+with
+.I q
+prime).  Finding safe primes takes a very long time.  In this case, the
+value of
+.I g
+is fixed as 4.
+.IP
+If a size is chosen for
+.I q
+and Lim-Lee primes are not selected then the prime
+.I q
+is generated and
+.I p
+is chosen so that
+.IR p \ \-\ 1
+is a multiple of
+.IR q .
+.IP
+If the
+.B \-L
+option was given, Lim-Lee primes are selected: the parameters are chosen
+such that
+.IR p \ =\ 2\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
+where the
+.IR q \*(us i\*(ue
+are primes at least as large as the setting given by the
+.B \-B
+option (or 256 bits, if no setting was given).
+.IP
+If the
+.B \-K
+option was given, KCDSA-style Lim-Lee primes are selected: the
+parameters are chosen such that
+.IR p \ =\ 2\  q\ v \ +\ 1,
+where
+.IR p,
+.I q
 and
-.I
-g
-is assigned the value 4.  This takes much longer.
+.I v
+are primes.
+.IP
+If the
+.B \-S
+or
+.B \-K
+options were given, the generator
+.I g
+is chosen to generate the subgroup of order
+.IR q \*(us0\*(ue;
+otherwise,
+.I g
+will generate the group of order
+.RI ( p \ \-\ 1)/2\ =\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
 .IP
-If used with the
-.B \-p
-option, the algorithm simply copies the parameters from an existing key.
+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 show dh"
+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,
@@ -485,6 +733,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 show ec"
+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
@@ -499,7 +845,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
@@ -510,6 +859,13 @@ An attribute can be deleted by assigning it an empty value.  Although
 the keyring file format is capable of representing an attribute with an
 empty value as distinct from a nonexistant attribute, this interface
 does not allow empty attributes to be set.
+.SS "getattr"
+Fetches a single attribute of a key.  The key whose attribute is to be
+read is given by its
+.IR tag .
+The attribute's value is written to standard output followed by a
+newline.  If the key or attribute is absent, a message is written to
+standard error and the program exits nonzero.
 .SS "comment"
 Sets, deletes or changes the comment attached to a key.  The first
 argument is a key tag or keyid which names the key to be modified; the
@@ -552,16 +908,42 @@ decrypt locked keys.  Make sure nobody is looking over your shoulder
 when you do this!
 .SS "fingerprint"
 Reports a fingerprint (secure hash) on components of requested keys.
-The following option is supported:
+The following options are supported:
 .TP
 .BI "\-f, \-\-filter " filter
 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 key show hash
+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 "verify"
+Check a key's fingerprint against a reference copy.  The following
+options are supported:
+.TP
+.BI "\-f, \-\-filter " filter
+Specifies a filter.  Only key components which match the filter are
+hashed.  The default is to only fingerprint nonsecret components.  An
+error is reported if no part of the key matches.
+.TP
+.BI "\-a, \-\-algorithm " hash
+Names the hashing algorithm.  Run
+.B key show hash
+for a list of hashing algorithms.  The default is
+.BR rmd160 .
+.PP
+The reference fingerprint is given as hex, in upper or lower case.  The
+hash may contain hyphens, colons and whitespace.  Other characters are
+not permitted.
 .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.
@@ -589,5 +971,5 @@ you want them to be replaced during the merge.
 .SH "SEE ALSO"
 .BR keyring (5).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>