.\" -*-nroff-*-
.ie t \{\
+. if \n(.g \{\
+. fam P
+. \}
. ds ss \s8\u
. ds se \d\s0
. ds us \s8\d
. ds ue \u\s0
+. ds *b \(*b
.\}
.el \{\
. ds ss ^
. ds se
. ds us _
-. ds se
+. 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
.I command
is one of:
.PP
+.B help
+.RI [ command ...]
+.br
+.B show
+.RI [ item ...]
+.br
.B add
.RB [ \-lqrLS ]
.RB [ \-a
.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
.IR tag ]
.RB [ \-c
.IR comment ]
+.RB [ \-C
+.IR curve ]
+.br
+\h'8n'
.I type
.IR attr ...
.br
.B fingerprint
.RB [ \-f
.IR filter ]
+.RB [ \-a
+.IR hash ]
.RI [ tag ...]
.br
+.B verify
+.RB [ \-f
+.IR filter ]
+.RB [ \-a
+.IR hash ]
+.I tag
+.I fingerprint
+.br
.B tidy
.br
.B extract
.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
-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
keys. Keys used with number-theoretic systems (like most common
public-key systems) use
.I "multiprecision integer"
-keys. Algorithms which require several key constituents (again, like
-most public-key systems) use
+keys. Elliptic curve systems use
+.I "curve point"
+keys, which are either a pair of integers representing field elements,
+or a `point at infinity'. Algorithms which require several key
+constituents (again, like most public-key systems) use
.I structured
-keys, which consist of a collection of named parts. Finally, keys
-(including structured keys) can be encrypted.
+keys, which consist of a collection of named parts. It's possible to
+store an
+.I "ASCII string"
+as a key, though this is usually done as a component of a structured
+key. Finally, keys (including structured keys) can be encrypted.
.TP
.B "filter"
Keys and key components may be selected by a filter expression, a
sequence of flag names separated by commas. Flags are:
.BR binary ,
.BR integer ,
-.B struct
+.BR struct ,
+.BR ec ,
+.BR string ,
or
.B encrypt
(describing the key encoding);
.BR symmetric ,
.BR private ,
-.B public
+.BR public ,
or
.B shared
(describing the category of key);
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
.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 "\-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
.BI "\-c, \-\-comment " comment
Sets a comment for the key. The default is not to attach a comment.
.TP
+.BI "\-C, \-\-curve " curve-spec
+Use the elliptic curve described by
+.I curve-spec
+when generating elliptic curve parameters.
+.TP
.BI "\-t, \-\-tag " tag
Selects a tag string for the key. The default is not to set a tag. It
is an error to select a tag which already exists.
corrssponding public and private exponents is sufficient to be able to
factor the modulus and recover other users' private keys.
.TP
-.B "dh-params"
+.B "dh-param"
Generates parameters for use with the Diffie-Hellman key exchange
protocol, and many related systems, such as ElGamal encryption and
signatures, and even DSA. (The separate DSA algorithm uses the
.IR p \ =\ 2 q \ +\ 1,
with
.I q
-prime). In this case, the value of
+prime). Finding safe primes takes a very long time. In this case, the
+value of
.I g
is fixed as 4.
.IP
.I g
will generate the group of order
.RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
+.IP
+Finally, the
+.B \-C
+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 show dh"
+for a list) or a triple
+.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,
option determines the length of the modulus
.IR n ;
the default length is 1024 bits.
+.TP
+.B "ec-param"
+Store an elliptic curve specification. If no explicit
+.I curve-spec
+is given (the
+.RB ` \-C '
+option) then a curve is chosen whose order is about the size given by the
+.RB ` \-b '
+option (default is 256 bits).
+.IP
+A
+.I curve-spec
+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 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
+error (though the program continues anyway). The check can be
+suppressed using the
+.RB ` \-q '
+option.
+.IP
+A curve specification consists of the following elements optionally
+separated by whitespace: a
+.IR "field type" ,
+which is one of
+.BR "prime" ,
+.BR "niceprime" ,
+.BR "binpoly" ,
+.or
+.BR "binnorm" ;
+an optional
+.RB ` : ';
+the field modulus
+.IR p ;
+if the field type is
+.B binnorm
+then an optional
+.RB ` , '
+and the representation of the normal element \*(*b; an optional
+.RB ` / ';
+a
+.IR "curve type" ,
+which is one of
+.BR "prime" ,
+.BR "primeproj" ,
+.BR "bin" ,
+and
+.BR "binproj"
+(the `proj' types currently have much better performance);
+an optional
+.RB ` : ';
+the two field-element parameters
+.I a
+and
+.IR b
+which define the elliptic curve
+.IR E ,
+separated by an optional
+.RB ` , ';
+an optional
+.RB ` / ';
+the
+.IR x -
+and
+.IR y -coordinates
+of the generator point
+.IR G ,
+separated by an optional
+.RB ` , ';
+an optional
+.RB ` : ';
+the order
+.I r
+of the group generated by
+.IR G ;
+an optional
+.RB ` * ';
+and the
+.I cofactor
+.I h
+=
+.RI # E / r .
+.TP
+.B "ec"
+Generate a private scalar and a corresponding public point on an
+elliptic curve. See
+.B ec-param
+above for how to specify elliptic curve parameter sets. The scalar
+.I x
+is chosen unformly between 0 and the curve order
+.IR r ;
+the public point is then
+.I x
+\(mu
+.IR G .
.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
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 "\-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
-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.