X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/5032daf4a16aebc784968e8d052dbe4233f88bfe..c65df27983057ec76ed0e72bb370f9a5ae7dad28:/key.1

diff --git a/key.1 b/key.1
index 5c7bee6..07237a7 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,6 +41,12 @@ where
 .I command
 is one of:
 .PP
+.B help
+.RI [ command ...]
+.br
+.B show
+.RI [ item ...]
+.br
 .B add
 .RB [ \-lqrLS ]
 .RB [ \-a
@@ -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
@@ -112,12 +138,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
@@ -246,6 +272,60 @@ 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
+command.
+.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
@@ -255,7 +335,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
@@ -270,6 +352,51 @@ Selects a key containing parameter values to copy.  Not all
 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
 .RB ` forever '