19 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
21 key \- simple key management system
107 command performs useful operations on Catacomb keyring files. It
108 provides a number of subcommands, by which the various operations may be
111 Before the command name,
113 may be given. The following global options are supported:
115 .BR "\-h, \-\-help " [ \fIcommand ]
116 Writes a brief summary of
118 various options to standard output, and
119 returns a successful exit status. With a command name, gives help on
122 .B "\-v, \-\-version"
123 Writes the program's version number to standard output, and returns a
124 successful exit status.
127 Writes a very terse command line summary to standard output, and returns
128 a successful exit status.
130 .BI "\-k, \-\-keyring " file
131 Names the keyring file which
133 is to process. The default keyring, used if this option doesn't specify
134 one, is the file named
136 in the current directory. The keyring must be stored in a regular file:
137 pipes, sockets, devices etc. are not allowed.
140 program attempts to lock the keyring before accessing it, using
142 locking. It will however time out after a short while (10 seconds) and
145 In addition to the actual key data itself, a Catacomb key has a number
146 of other pieces of information attached to it:
149 Every key has a 32-bit identifying number, written in hexadecimal.
150 Keyids are not actually related to the key contents: they're generated
151 randomly. Applications use keyids to refer to specific keys; users are
152 probably better off with tags and types. A
154 key cannot be looked up by keyid.
157 A key's tag is a unique string which can be used by users and
158 applications to identify the key. Tag strings may not contain spaces,
161 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
162 keyid or key type string can be given instead.
165 A key's type string describes what the key may be used for. The type
166 string is arbitrary, except that it may not contain whitespace
167 characters, dots or colons. Applications use key types to obtain an
168 arbitrary but suitable key for some purpose. An
170 key cannot be looked up by type, but may be looked up by keyid or tag.
173 There are a number of different ways in which keys can be represented,
174 according to the uses to which the key will be put. Most symmetric
177 keys. Keys used with number-theoretic systems (like most common
178 public-key systems) use
179 .I "multiprecision integer"
180 keys. Elliptic curve systems use
182 keys, which are either a pair of integers representing field elements,
183 or a `point at infinity'. Algorithms which require several key
184 constituents (again, like most public-key systems) use
186 keys, which consist of a collection of named parts. It's possible to
189 as a key, though this is usually done as a component of a structured
190 key. Finally, keys (including structured keys) can be encrypted.
193 Keys and key components may be selected by a filter expression, a
194 sequence of flag names separated by commas. Flags are:
202 (describing the key encoding);
208 (describing the category of key);
212 (whether the key should be erased from memory after use); and
216 (whether the key is safe to divulge).
219 A key component may be identified by the key's tag (or keyid, or type).
220 Subcomponents of structured keys are identified by following the tag by
221 a dot and the name of the subcomponent.
224 Most keys expire after a certain amount of time. Once a key has
225 expired, it will no longer be chosen as a result of a lookup by key
226 type. However, it is not deleted until its deletion time is also
230 A key's deletion time is the latest expiry time of any of the objects
231 which require that key. For example, a key used for authenticating
232 cryptographic cookies should have its deletion time set to the longest
233 expiry time of any of the cookies it can authenticate. Once a key's
234 deletion time is passed, it can no longer be referred to by
235 applications, and will be removed from the keyring next time it's
239 A key may be given a comment when it's created. The comment is for the
240 benefit of users, and isn't interpreted by applications at all.
244 A key as zero or more name/value pairs. The names and values are
245 arbitrary strings, except they may not contain null bytes. Some
246 attributes may have meaning for particular applications or key types;
247 others may be assigned global meanings in future.
248 .SH "COMMAND REFERENCE"
252 command creates a new key and adds it to the keyring. The command
253 accepts the following options:
255 .BI "\-a, \-\-algorithm " alg
256 Selects a key generation algorithm. The default algorithm is
258 the different algorithms are described below.
260 .BI "\-b, \-\-bits " bits
261 The length of the key to generate, in bits. The default, if this option
262 is not supplied, depends on the key-generation algorithm.
264 .BI "\-B, \-\-qbits " bits
265 The length of the subsidiary key or parameter, in bits. Not all
266 key-generation algorithms have a subsidiary key size.
268 .BI "\-p, \-\-parameters " tag
269 Selects a key containing parameter values to copy. Not all
270 key-generation algorithms allow the use of shared parameters.
272 .BI "\-e, \-\-expire " expire
273 The expiry date for the generated key. This may be the string
275 if the key should never expire automatically, or any date acceptable to
278 library function. Briefly,
280 understands absolute dates such as
283 .RB ` "August 2nd, 1999" ',
284 and (perhaps more usefully) relative dates such as
286 The default is to allow a 2 week expiry, which isn't useful.
288 .BI "\-c, \-\-comment " comment
289 Sets a comment for the key. The default is not to attach a comment.
291 .BI "\-C, \-\-curve " curve-spec
292 Use the elliptic curve described by
294 when generating elliptic curve parameters.
296 .BI "\-t, \-\-tag " tag
297 Selects a tag string for the key. The default is not to set a tag. It
298 is an error to select a tag which already exists.
303 option is given, remove this tag from any key which already has it.
305 .BI "\-R, \-\-rand-id " tag
306 Selects the key to use for the random number generator. Catacomb's
307 random number generator can be
309 so that, even if the inputs to the generator are compromised, knowledge
310 of the key is also necessary to be able to predict the output. By
311 default, the latest-expiring key with type
313 is used, if present; if not, no key is used.
316 Requests that the secret parts of the newly-generated key be encrypted
320 Suppresses the progress indication which is usually generated while
321 time-consuming key generation tasks are being performed.
324 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
325 rather than a random (or safe) prime. See the details on Diffie-Hellman
326 key generation below.
328 .BI "\-S, --subgroup"
329 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
330 generator of a prime-order subgroup rather than a subgroup of order
333 The key's type is given by the required
335 argument. Following the type are zero or more attributes, which are
336 attached to the key in the same way as for the
340 The key-generation algorithms supported are as follows:
343 Generates a plain binary key of the requested length. If the requested
344 key length is not a multiple of eight, the high-order bits of the first
345 octet of the key are zeroed. The default key length is 128 bits.
348 Generates a DES key, with parity bits. The key length must be 56, 112
349 or 168; the default is 56. The low-order bit of each octet is ignored by
350 the DES algorithm; it is used to give each octet odd parity.
353 Generates a public/private key pair for use with the RSA algorithm.
355 The key components are
359 a pair of prime numbers;
368 the private exponent, chosen such that
371 .RI ( p \ \-\ 1)( q \ \-\ 1));
372 and some other values useful for optimizing private-key operations:
373 .IR q \*(ss\-1\*(se\ mod\ p ,
374 .IR d \ mod\ p \ \-\ 1,
376 .IR d \ mod\ q \ \-\ 1.
381 constitute the public key; the rest must be kept secret. The key size
384 option determines the size of the modulus
386 the default is 1024 bits.
388 The key generation algorithm chooses
398 have large prime factors \- call them
404 also has a large prime factor;
406 has similar properties.
410 cannot be sensibly used as a shared parameter, since knowledge of
411 corrssponding public and private exponents is sufficient to be able to
412 factor the modulus and recover other users' private keys.
415 Generates parameters for use with the Diffie-Hellman key exchange
416 protocol, and many related systems, such as ElGamal encryption and
417 signatures, and even DSA. (The separate DSA algorithm uses the
418 generator described in FIPS186-1.)
420 The Diffie-Hellman parameters are a prime modulus
431 option controls the size of the modulus
433 the default size is 1024 bits.
437 size is selected using the
439 option and the Lim-Lee prime option is disabled, then
441 is chosen to be a `safe' prime (i.e.,
442 .IR p \ =\ 2 q \ +\ 1,
445 prime). Finding safe primes takes a very long time. In this case, the
450 If a size is chosen for
452 and Lim-Lee primes are not selected then the prime
463 option was given Lim-Lee primes are selected: the parameters are chosen
465 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
468 are primes at least as large as the setting given by the
470 option (or 256 bits, if no setting was given).
474 option was given, the generator
476 is chosen to generate the subgroup of order
480 will generate the group of order
481 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
485 option can be given, in which case the parameters are taken directly
486 from the provided group specification, which may either be the the name
487 of one of the built-in groups (say
488 .B "key add \-a dh\-param \-C list 42"
489 for a list) or a triple
491 separated by commas. No random generation is done in this case: the
492 given parameters are simply stored.
495 Generates a public/private key pair for use with offline Diffie-Hellman,
496 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
499 and computes the public key
500 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
503 Generates parameters for the DSA algorithm. DSA parameters are also
504 suitable for use with Diffie-Hellman and ElGamal system.
506 The main difference between DSA and Diffie-Hellman parameter generation
507 is thatthe DSA parameter generation
510 from which the parameters are derived, and, assuming that the SHA-1 hash
511 function is strong, it's not feasible to construct a seed from which
512 deliberately weak parameters are derived. The algorithm used is the one
513 described in the DSA standard, FIPS\ 186, extended only to allow
514 sequential search for a prime
516 and to allow arbitrary parameter sizes. The seed is stored,
517 Base64-encoded, as the value of the attribute
520 The default lengths for
524 are 768 and 160 bits respectively, since the DSA standard specifies that
526 be 160 bits, and the choice of 768 bits for
528 gives commensurate security.
531 Generates a public/private key pair for DSA. As for Diffie-Hellman
535 and computes the public key
536 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
539 Generates a public/private key pair for the Blum-Blum-Shub random-number
540 generator, and the Blum-Goldwasser semantically-secure public-key
543 The key components are prime numbers
547 both congruent to 3 (mod\ 4), and their product
549 The public key is simply the modulus
557 The key-generation algorithm ensures that the two primes
563 (see the discussion of strong primes above, in the section on RSA keys),
568 are relatively prime, giving a maximum possible period length.
570 The key size requested by the
572 option determines the length of the modulus
574 the default length is 1024 bits.
577 Store an elliptic curve specification. If no explicit
581 option) then a curve is chosen whose order is about the size given by the
583 option (default is 256 bits).
587 can be given explicitly (in which case
589 is ignored). It can either be the name of a built-in curve (say
590 .B "key add \-a ec\-param \-C list 42"
591 for a list of curve names) or a full specification. The curve is
592 checked for correctness and security according to the SEC1
593 specification: failed checks cause a warning to be issued to standard
594 error (though the program continues anyway). The check can be
599 A curve specification consists of the following elements optionally
600 separated by whitespace: a
616 and the representation of the normal element \*(*b; an optional
626 (the `proj' types currently have much better performance);
629 the two field-element parameters
633 which define the elliptic curve
635 separated by an optional
643 of the generator point
645 separated by an optional
651 of the group generated by
662 Generate a private scalar and a corresponding public point on an
665 above for how to specify elliptic curve parameter sets. The scalar
667 is chosen unformly between 0 and the curve order
669 the public point is then
674 Forces keys to immediately expire. An expired key is not chosen when a
675 program requests a key by its type. The keys to expire are listed by
679 Deletes keys immediately. The keys to delete are listed by their
681 Be careful when deleting keys. It might be a better idea
682 to expire keys rather than deleting them.
684 Sets, deletes or changes the tag attached to a key. The first tag or
685 keyid names the key to be modified; the second, if present specifies the
686 new tag to be set. If no second argument is given, the existing tag, if
687 any, is removed and no new tag is set. It is an error to set a tag
688 which already exists on another key, unless you give the
690 option, which removes the tag first.
692 Attaches attributes to a key. The key to which the attributes should be
693 attached is given by its
695 Each attribute has the form
697 An attribute can be deleted by assigning it an empty value. Although
698 the keyring file format is capable of representing an attribute with an
699 empty value as distinct from a nonexistant attribute, this interface
700 does not allow empty attributes to be set.
702 Sets, deletes or changes the comment attached to a key. The first
703 argument is a key tag or keyid which names the key to be modified; the
704 second, if present, is the new comment. If no second argument is given,
705 the existing comment, if any, is removed, and no new comment is set.
707 Locks a key or key component using a passphrase. If the key is already
708 locked, the existing passphrase is requested, and a new passphrase is
711 Unlocks a passphrase-locked key or key component. If the key is not
712 locked, an error is reported.
714 Lists the keys in the keyring. A couple of options are supported:
716 .B "\-v, \-\-verbose"
717 Increases the amount of information displayed for each key. Repeat for
721 Decreases the amount of information displayed for each key. Each use
727 Display key expiry times as UTC rather than using the local time zone.
729 .BI "\-f, \-\-filter " filter
730 Specifies a filter. Only keys and key components which match the filter
733 By default, a single line of output is generated for each, showing
734 keyids, types, expiry and deletion dates, and comments. Additional
736 options show more information, such as the exact time of day for expiry
737 and deletion, key attributes, and a dump of the actual key data. If the
738 verbosity level is sufficiently high, passphrases are requested to
739 decrypt locked keys. Make sure nobody is looking over your shoulder
742 Reports a fingerprint (secure hash) on components of requested keys.
743 The following option is supported:
745 .BI "\-f, \-\-filter " filter
746 Specifies a filter. Only keys and key components which match the filter
747 are fingerprinted. The default is to only fingerprint nonsecret
750 .BI "\-a, \-\-algorithm " hash
751 Names the hashing algorithm. Run
753 for a list of hashing algorithms. The default is
756 The keys to be fingerprinted are named by their tags or keyids given as
757 command line arguments. If no key tags are given, all keys which match
758 the filter are fingerprinted. See
760 for a description of how key fingerprints are computed.
762 Simply reads the keyring from file and writes it back again. This has
763 the effect of removing any deleted keys from the file.
765 Writes a selection of keys to a file. An option is supported:
767 .BI "\-f, \-\-filter " filter
768 Specifies a filter. Only keys and key components which match the filter
771 Keys extracted are written to the file named by the first argument,
774 to designate standard output. The keys to extract are listed by their
775 tags; if no tags are given, all keys which match the filter are
776 extracted. The output is a valid keyring file.
778 Merges the keys from the named
782 to designate standard input, with the keyring. Keys already in the
783 keyring are not overwritten: you must explicitly remove them first if
784 you want them to be replaced during the merge.
788 Mark Wooding, <mdw@nsict.org>