.B fingerprint
.RB [ \-f
.IR filter ]
+.RB [ \-p
+.IR style ]
.RB [ \-a
.IR hash ]
.RI [ tag ...]
.B verify
.RB [ \-f
.IR filter ]
+.RB [ \-p
+.IR style ]
.RB [ \-a
.IR hash ]
.I tag
(Hopefully.)
.TP
.B "attributes"
-A key as zero or more name/value pairs. The names and values are
-arbitrary strings, except they may not contain null bytes. Some
+A key has zero or more name/value pairs. The names and values are
+arbitrary strings, except that 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"
command.
.TP
.B dh
-The built-in Diffie-Hellman groups which can be used with the
+The built-in Diffie\(enHellman groups which can be used with the
.B add \-a dh
command.
.TP
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
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
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-Hellman parameters, generate a Lim-Lee prime
-rather than a random (or safe) prime. See the details on Diffie-Hellman
-key generation below.
+When generating Diffie\(enHellman parameters, generate a Lim\(enLee
+prime rather than a random (or safe) prime. See the details on
+Diffie\(enHellman key generation below.
.TP
.BI "\-K, \-\-kcdsa"
-When generating Diffie-Hellman parameters, generate a KCDSA-style
-Lim-Lee prime rather than a random (or safe) prime. See the details on
-Diffie-Hellman key generation below.
+When generating Diffie\(enHellman parameters, generate a KCDSA-style
+Lim\(enLee prime rather than a random (or safe) prime. See the details
+on Diffie\(enHellman key generation below.
.TP
.BI "\-S, \-\-subgroup"
-When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
-generator of a prime-order subgroup rather than a subgroup of order
-.RI ( p "- 1)/2."
+When generating Diffie\(enHellman parameters with a Lim\(enLee prime,
+choose a generator of a prime-order subgroup rather than a subgroup of
+order
+.RI ( p "\ \-\ 1)/2."
.PP
The key's type is given by the required
.I type
the public exponent;
.IR d ,
the private exponent, chosen such that
-.IR ed \ \(==\ 1
+.IR ed \~\(==\~1
(mod
-.RI ( p \ \-\ 1)( q \ \-\ 1));
+.RI lcm( p "\~\-\~1, " q \~\-\~1));
and some other values useful for optimizing private-key operations:
-.IR q \*(ss\-1\*(se\ mod\ p ,
-.IR d \ mod\ p \ \-\ 1,
+.IR q "\*(ss\-1\*(se mod " p ,
+.IR d "\~mod " p \~\-\~1,
and
-.IR d \ mod\ q \ \-\ 1.
+.IR d "\~mod " q \~\-\~1.
The values
.I n
and
to be
.I strong
primes: both
-.IR p \ \-\ 1
+.IR p \~\-\~1
and
-.IR p \ +\ 1
-have large prime factors \- call them
+.IR p \~+\~1
+have large prime factors \(en call them
.I r
and
.I s
-respectively \- and
-.IR r \ \-\ 1
+respectively \(en and
+.IR r \~\-\~1
also has a large prime factor;
.I q
has similar properties.
factor the modulus and recover other users' private keys.
.TP
.B "dh-param"
-Generates parameters for use with the Diffie-Hellman key exchange
+Generates parameters for use with the Diffie\(enHellman key exchange
protocol, and many related systems, such as ElGamal encryption and
signatures, and even DSA. (The separate DSA algorithm uses the
generator described in FIPS186-1.)
.IP
-The Diffie-Hellman parameters are a prime modulus
+The Diffie\(enHellman parameters are a prime modulus
.I p
and a generator
.I g
.I q
size is selected using the
.B \-B
-option and the Lim-Lee prime options are disabled, then
+option and the Lim\(enLee prime options are disabled, then
.I p
is chosen to be a `safe' prime (i.e.,
-.IR p \ =\ 2 q \ +\ 1,
+.IR p "\~= 2" q \~+\~1,
with
.I q
prime). Finding safe primes takes a very long time. In this case, the
.IP
If a size is chosen for
.I q
-and Lim-Lee primes are not selected then the prime
+and Lim\(enLee primes are not selected then the prime
.I q
is generated and
.I p
is chosen so that
-.IR p \ \-\ 1
+.IR p \~\-\~1
is a multiple of
.IR q .
.IP
If the
.B \-L
-option was given, Lim-Lee primes are selected: the parameters are chosen
-such that
-.IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
+option was given, Lim\(enLee primes are selected: the parameters are
+chosen such that
+.IR p "\~= 2\~" q \*(us0\*(ue
+.IR q \*(us1\*(ue
+.IR q \*(us2\*(ue\~...\~+\~1,
where the
-.IR q \*(us i\*(ue
+.IR q \*(us i \*(ue
are primes at least as large as the setting given by the
.B \-B
option (or 256 bits, if no setting was given).
.IP
If the
.B \-K
-option was given, KCDSA-style Lim-Lee primes are selected: the
+option was given, KCDSA-style Lim\(enLee primes are selected: the
parameters are chosen such that
-.IR p \ =\ 2\ q\ v \ +\ 1,
+.IR p "\~= 2" qv \~+\~1,
where
.IR p,
.I q
otherwise,
.I g
will generate the group of order
-.RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
+.RI ( p "\~\-\~1)/2\~= " q "\*(us0\*(ue " q \*(us1\*(ue
+.IR q \*(us2\*(ue\~...
.IP
Finally, the
.B \-C
of one of the built-in groups (say
.B "key show dh"
for a list) or a triple
-.RI ( p ,\ q ,\ g ).
+.RI ( p ,\~ q ,\~ g ).
separated by commas. No random generation is done in this case: the
given parameters are simply stored.
.TP
.B "dh"
-Generates a public/private key pair for use with offline Diffie-Hellman,
+Generates a public/private key pair for use with offline Diffie\(enHellman,
ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
private key
-.IR x \ <\ q ,
+.IR x \~<\~ q ,
and computes the public key
-.IR y \ =\ g\*(ssx\*(se \ mod\ p .
+.IR y "\~= " g \*(ss x "\*(se mod\~" p .
.TP
.B "dsa-param"
Generates parameters for the DSA algorithm. DSA parameters are also
-suitable for use with Diffie-Hellman and ElGamal system.
+suitable for use with Diffie\(enHellman and ElGamal system.
.IP
-The main difference between DSA and Diffie-Hellman parameter generation
+The main difference between DSA and Diffie\(enHellman parameter generation
is thatthe DSA parameter generation
algorithm creates a
.I seed
gives commensurate security.
.TP
.B "dsa"
-Generates a public/private key pair for DSA. As for Diffie-Hellman
+Generates a public/private key pair for DSA. As for Diffie\(enHellman
keys, it selects a
private key
-.IR x \ <\ q ,
+.IR x \~<\~ q ,
and computes the public key
-.IR y \ =\ g\*(ssx\*(se \ mod\ p .
+.IR y "\~= " g \*(ss x "\*(se mod\~" p .
.TP
.B "bbs"
Generates a public/private key pair for the Blum-Blum-Shub random-number
.I p
and
.IR q ,
-both congruent to 3 (mod\ 4), and their product
+both congruent to 3 (mod\~4), and their product
.IR n .
The public key is simply the modulus
.IR n ;
.I strong
(see the discussion of strong primes above, in the section on RSA keys),
and that
-.RI ( p \ \-\ 1)/2
+.RI ( p \~\-\~1)/2
and
-.RI ( q \ \-\ 1)/2
+.RI ( q \~\-\~1)/2
are relatively prime, giving a maximum possible period length.
.IP
The key size requested by the
.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
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
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
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:
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.
.BR keyring (5).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
-
~mdw / catacomb / blobdiff