X-Git-Url: https://git.distorted.org.uk/~mdw/catacomb/blobdiff_plain/16efb197c59c4b4cfaef7b2f23bd39f70176dd9e..bd6d65e32b835551677456bf286d09ced6859882:/progs/key.1

diff --git a/progs/key.1 b/progs/key.1
index f301391f..f5b64455 100644
--- a/progs/key.1
+++ b/progs/key.1
@@ -117,6 +117,8 @@ is one of:
 .B fingerprint
 .RB [ \-f
 .IR filter ]
+.RB [ \-p
+.IR style ]
 .RB [ \-a
 .IR hash ]
 .RI [ tag ...]
@@ -124,6 +126,8 @@ is one of:
 .B verify
 .RB [ \-f
 .IR filter ]
+.RB [ \-p
+.IR style ]
 .RB [ \-a
 .IR hash ]
 .I tag
@@ -340,6 +344,13 @@ The pseudorandom generators which are acceptable to the
 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
@@ -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
-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
@@ -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
+.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
@@ -835,6 +853,42 @@ the public point is then
 .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
@@ -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
-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
@@ -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
-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:
@@ -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
+.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
@@ -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.
+.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:
@@ -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
+.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
-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.