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

diff --git a/key.1 b/key.1
index cab0d41..3e7a601 100644
--- a/key.1
+++ b/key.1
@@ -16,6 +16,18 @@
 .  ds ue
 .  ds *b \fIbeta\fP
 .\}
+.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
@@ -29,8 +41,14 @@ where
 .I command
 is one of:
 .PP
+.B help
+.RI [ command ...]
+.br
+.B show
+.RI [ item ...]
+.br
 .B add
-.RB [ \-lqrLS ]
+.RB [ \-lqrLKS ]
 .RB [ \-a
 .IR alg ]
 .RB [ \-b | \-B
@@ -41,6 +59,14 @@ is one of:
 .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
@@ -72,6 +98,10 @@ is one of:
 .I tag
 .IR attr ...
 .br
+.B getattr
+.I tag
+.I attr
+.br
 .B lock
 .I qtag
 .br
@@ -87,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
@@ -110,12 +150,12 @@ Before the command name,
 .I "global options"
 may be given.  The following global options are supported:
 .TP
-.BR "\-h, \-\-help " [ \fIcommand ]
+.BR "\-h, \-\-help " [ \fIcommand ...]
 Writes a brief summary of
 .BR key 's
 various options to standard output, and
-returns a successful exit status.  With a command name, gives help on
-that command.
+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
@@ -244,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
@@ -253,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
@@ -265,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
@@ -318,12 +462,17 @@ using a passphrase.
 Suppresses the progress indication which is usually generated while
 time-consuming key generation tasks are being performed.
 .TP
-.BI "\-L, --lim-lee"
+.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 "\-S, --subgroup"
+.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."
@@ -430,11 +579,11 @@ option controls the size of the modulus
 .IR p ;
 the default size is 1024 bits.
 .IP
-If no 
+If no
 .I q
 size is selected using the
 .B \-B
-option and the Lim-Lee prime option is disabled, then 
+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,
@@ -458,7 +607,7 @@ is a multiple of
 .IP
 If the
 .B \-L
-option was given Lim-Lee primes are selected: the parameters are chosen
+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
@@ -468,8 +617,22 @@ are primes at least as large as the setting given by the
 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 v
+are primes.
+.IP
+If the
 .B \-S
-option was given, the generator
+or
+.B \-K
+options were given, the generator
 .I g
 is chosen to generate the subgroup of order
 .IR q \*(us0\*(ue;
@@ -483,7 +646,7 @@ Finally, the
 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"
+.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
@@ -585,7 +748,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 \-a ec\-param \-C list 42"
+.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
@@ -612,7 +775,7 @@ if the field type is
 then an optional
 .RB ` , '
 and the representation of the normal element \*(*b; an optional
-.RB ` / ';
+.RB ` ; ';
 a
 .IR "curve type" ,
 which is one of
@@ -627,14 +790,14 @@ an optional
 the two field-element parameters
 .I a
 and
-.IR b 
+.IR b
 which define the elliptic curve
 .IR E ,
 separated by an optional
 .RB ` , ';
 an optional
-.RB ` / ';
-the 
+.RB ` ; ';
+the
 .IR x -
 and
 .IR y -coordinates
@@ -646,11 +809,11 @@ an optional
 .RB ` : ';
 the order
 .I r
-of the group generated by 
+of the group generated by
 .IR G ;
 an optional
 .RB ` * ';
-and the 
+and the
 .I cofactor
 .I h
 =
@@ -696,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
@@ -738,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.
@@ -775,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>