Remove buf bits which moved to mLib. Fix email addresses.

[u/mdw/catacomb] / key.1

diff --git a/key.1 b/key.1
index cab0d41..6aa3520 100644 (file)
--- a/key.1
+++ b/key.1
@@ -16,6 +16,18 @@
 .  ds ue
 .  ds *b \fIbeta\fP
 .\}
 .  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
 .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
 .I command
 is one of:
 .PP

+.B help
+.RI [ command ...]
+.br
+.B show
+.RI [ item ...]
+.br

 .B add
 .RB [ \-lqrLS ]
 .RB [ \-a
 .B add
 .RB [ \-lqrLS ]
 .RB [ \-a


@@ -41,6 +59,14 @@ is one of:
 .IR tag ]
 .br
 \h'8n'
 .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
 .RB [ \-e
 .IR expire ]
 .RB [ \-t


@@ -87,8 +113,18 @@ is one of:
 .B fingerprint
 .RB [ \-f
 .IR filter ]
 .B fingerprint
 .RB [ \-f
 .IR filter ]

+.RB [ \-a
+.IR hash ]

 .RI [ tag ...]
 .br
 .RI [ tag ...]
 .br

+.B verify
+.RB [ \-f
+.IR filter ]
+.RB [ \-a
+.IR hash ]
+.I tag
+.I fingerprint
+.br

 .B tidy
 .br
 .B extract
 .B tidy
 .br
 .B extract


@@ -110,12 +146,12 @@ Before the command name,
 .I "global options"
 may be given.  The following global options are supported:
 .TP
 .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
 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
 .TP
 .B "\-v, \-\-version"
 Writes the program's version number to standard output, and returns a


@@ -244,6 +280,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"
 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
 .SS add
 The
 .B add


@@ -253,7 +345,9 @@ accepts the following options:
 .BI "\-a, \-\-algorithm " alg
 Selects a key generation algorithm.  The default algorithm is
 .BR binary ;
 .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
 .TP
 .BI "\-b, \-\-bits " bits
 The length of the key to generate, in bits.  The default, if this option


@@ -265,7 +359,53 @@ key-generation algorithms have a subsidiary key size.
 .TP
 .BI "\-p, \-\-parameters " tag
 Selects a key containing parameter values to copy.  Not all
 .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
 .TP
 .BI "\-e, \-\-expire " expire
 The expiry date for the generated key.  This may be the string


@@ -483,7 +623,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
 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
 for a list) or a triple
 .RI ( p ,\  q ,\  g ).
 separated by commas.  No random generation is done in this case: the


@@ -585,7 +725,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
 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
 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


@@ -738,16 +878,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.
 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 "\-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
 .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.
 .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 +941,5 @@ you want them to be replaced during the merge.
 .SH "SEE ALSO"
 .BR keyring (5).
 .SH AUTHOR
 .SH "SEE ALSO"
 .BR keyring (5).
 .SH AUTHOR

-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>