progs/mkphrase.c: Fix trailing spaces in usage message.

[catacomb] / progs / key.1

diff --git a/progs/key.1 b/progs/key.1
index f301391..f5b6445 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


@@ -462,6 +472,14 @@ using a passphrase.
 Suppresses the progress indication which is usually generated while
 time-consuming key generation tasks are being performed.
 .TP
 Suppresses the progress indication which is usually generated while
 time-consuming key generation tasks are being performed.
 .TP

+.BI "\-E, \-\-public-exponent"
+Set the public exponent for RSA keys.
+The default is 65537,
+because this seems to be the overwhelmingly popular choice
+among practitioners
+and because it was the exponent used before this option was introduced.
+The value 3 is fine unless you use a completely terrible padding scheme.
+.TP

 .BI "\-L, \-\-lim-lee"
 When generating Diffie\(enHellman parameters, generate a Lim\(enLee
 prime rather than a random (or safe) prime.  See the details on
 .BI "\-L, \-\-lim-lee"
 When generating Diffie\(enHellman parameters, generate a Lim\(enLee
 prime rather than a random (or safe) prime.  See the details on


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

+.TP
+.B x25519
+Generate a private scalar and a corresponding public point on the
+(Montgomery-form) Curve25519 elliptic curve.
+The scalar is simply a random 256-bit string;
+the public key is the
+.IR x -coordinate
+of the corresponding point.
+.TP
+.B x448
+Generate a private scalar and a corresponding public point on the
+(Montgomery-form) Ed448-Goldilocks elliptic curve.
+The scalar is simply a random 256-bit string;
+the public key is the
+.IR x -coordinate
+of the corresponding point.
+.TP
+.B ed25519
+Generate a private key and a corresponding public point on the
+(twisted Edwards-form) Curve25519 elliptic curve.
+The private key is simply a random 256-bit string,
+from which a scalar and secret prefix are derived;
+the public key is the compressed form of the corresponding point.
+.TP
+.B ed448
+Generate a private key and a corresponding public point on the
+(Edwards-form) Ed448-Goldilocks elliptic curve.
+The private key is simply a random 456-bit string,
+from which a scalar and secret prefix are derived;
+the public key is the compressed form of the corresponding point.
+.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


@@ -852,7 +906,12 @@ new tag to be set.  If no second argument is given, the existing tag, if
 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
 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.
+option.
+.PP
+The following options are recognized.
+.TP
+.B "\-r, \-\-retag"
+Untag the existing key with the desired new tag, if any.

 .SS "setattr"
 Attaches attributes to a key.  The key to which the attributes should be
 attached is given by its
 .SS "setattr"
 Attaches attributes to a key.  The key to which the attributes should be
 attached is given by its


@@ -907,9 +966,9 @@ keyids, types, expiry and deletion dates, and comments.  Additional
 .RB ` \-v '
 options show more information, such as the exact time of day for expiry
 and deletion, key attributes, and a dump of the actual key data.  If the
 .RB ` \-v '
 options show more information, such as the exact time of day for expiry
 and deletion, key attributes, and a dump of the actual key data.  If the

-verbosity level is sufficiently high, passphrases are requested to
-decrypt locked keys.  Make sure nobody is looking over your shoulder
-when you do this!
+verbosity level is sufficiently high, secret parts of keys are printed,
+and passphrases are requested to 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 options are supported:
 .SS "fingerprint"
 Reports a fingerprint (secure hash) on components of requested keys.
 The following options are supported:


@@ -919,6 +978,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 +994,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 +1015,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.