progs/key.c: Support applying parameters in all key-generation algorithms.

[catacomb] / progs / key.1

diff --git a/progs/key.1 b/progs/key.1
index f301391..abd399d 100644 (file)
--- a/progs/key.1
+++ b/progs/key.1
@@ -117,6 +117,8 @@ is one of:
 .B fingerprint
 .RB [ \-f
 .IR filter ]
 .B fingerprint
 .RB [ \-f
 .IR filter ]

+.RB [ \-p
+.IR style ]

 .RB [ \-a
 .IR hash ]
 .RI [ tag ...]
 .RB [ \-a
 .IR hash ]
 .RI [ tag ...]


@@ -124,6 +126,8 @@ is one of:
 .B verify
 .RB [ \-f
 .IR filter ]
 .B verify
 .RB [ \-f
 .IR filter ]

+.RB [ \-p
+.IR style ]

 .RB [ \-a
 .IR hash ]
 .I tag
 .RB [ \-a
 .IR hash ]
 .I tag


@@ -340,6 +344,13 @@ The pseudorandom generators which are acceptable to the
 option of the
 .B add
 command.
 option of the
 .B add
 command.

+.TP
+.B fpres
+Fingerprint presentation styles, as used by the
+.B fingerprint
+and
+.B verify
+commands.

 .SS add
 The
 .B add
 .SS add
 The
 .B add


@@ -362,9 +373,8 @@ The length of the subsidiary key or parameter, in bits.  Not all
 key-generation algorithms have a subsidiary key size.
 .TP
 .BI "\-p, \-\-parameters " tag
 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.  A new key
-also inherits attributes from its parameter key.
+Selects a key containing parameter values to copy.
+A new key also inherits attributes from its parameter key.

 .TP
 .BI "\-A, \-\-seedalg " seed-alg
 Use the deterministic random number generator algorithm
 .TP
 .BI "\-A, \-\-seedalg " seed-alg
 Use the deterministic random number generator algorithm


@@ -835,6 +845,12 @@ the public point is then
 .I x
 \(mu
 .IR G .
 .I x
 \(mu
 .IR G .

+.TP
+.B empty
+Generate an empty key, with trivial contents.
+This is useful as a `parameters' key,
+carrying attributes to be applied to other keys
+if they don't require more detailed parameters.

 .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
 .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


@@ -919,6 +935,11 @@ Specifies a filter.  Only keys and key components which match the filter
 are fingerprinted.  The default is to only fingerprint nonsecret
 components.
 .TP
 are fingerprinted.  The default is to only fingerprint nonsecret
 components.
 .TP

+.BI "\-p, \-\-presentation " style
+Write fingerprints in the given
+.IR style .
+See below for a list of presentation styles.
+.TP

 .BI "\-a, \-\-algorithm " hash
 Names the hashing algorithm.  Run
 .B key show hash
 .BI "\-a, \-\-algorithm " hash
 Names the hashing algorithm.  Run
 .B key show hash


@@ -930,6 +951,18 @@ command line arguments.  If no key tags are given, all keys which match
 the filter are fingerprinted.  See
 .BR keyring (5)
 for a description of how key fingerprints are computed.
 the filter are fingerprinted.  See
 .BR keyring (5)
 for a description of how key fingerprints are computed.

+.PP
+The fingerprint may be shown in the following styles.
+.TP
+.B hex
+Lowercase hexadecimal, with groups of eight digits separated by hyphens
+(`\-').  This is the default presentation style.  (On input, colons are
+also permitted as separators.)
+.TP
+.B base32
+Lowercase Base32 encoding, without `=' padding, with groups of six
+digits separated by colons (`:').  (On input, padding characters are
+ignored.)

 .SS "verify"
 Check a key's fingerprint against a reference copy.  The following
 options are supported:
 .SS "verify"
 Check a key's fingerprint against a reference copy.  The following
 options are supported:


@@ -939,15 +972,29 @@ 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
 hashed.  The default is to only fingerprint nonsecret components.  An
 error is reported if no part of the key matches.
 .TP

+.BI "\-p, \-\-presentation " style
+Expect the
+.I fingerprint
+to be in the given presentation
+.IR style .
+These match the styles produced by the
+.B fingerprint
+command described above.
+.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
 .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.
+The fingerprint should be provided in the form printed by the
+.B fingerprint
+command, using the same presentation
+.IR style .
+A little flexibility is permitted: separators may be placed anywhere (or
+not at all) and are ignored; whitespace is permitted and ignored; and
+case is ignored in presentation styles which don't make use of both
+upper- and lower-case characters.

 .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.