10 .TH key 1 "5 June 1999" Catacomb
12 key \- simple key management system
92 command performs useful operations on Catacomb keyring files. It
93 provides a number of subcommands, by which the various operations may be
96 Before the command name,
98 may be given. The following global options are supported:
101 Writes a brief summary of
103 various options to standard output, and
104 returns a successful exit status.
106 .B "\-v, \-\-version"
107 Writes the program's version number to standard output, and returns a
108 successful exit status.
111 Writes a very terse command line summary to standard output, and returns
112 a successful exit status.
114 .BI "\-k, \-\-keyring " file
115 Names the keyring file which
117 is to process. The default keyring, used if this option doesn't specify
118 one, is the file named
120 in the current directory. The keyring must be stored in a regular file:
121 pipes, sockets, devices etc. are not allowed.
124 program attempts to lock the keyring before accessing it, using
126 locking. It will however time out after a short while (10 seconds) and
129 In addition to the actual key data itself, a Catacomb key has a number
130 of other pieces of information attached to it:
133 Every key has a 32-bit identifying number, written in hexadecimal.
134 Keyids are not actually related to the key contents: they're generated
135 randomly. Applications use keyids to refer to specific keys; users are
136 probably better off with tags and types. A
138 key cannot be looked up by keyid.
141 A key's tag is a unique string which can be used by users and
142 applications to identify the key. Tag strings may not contain spaces,
145 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
146 keyid or key type string can be given instead.
149 A key's type string describes what the key may be used for. The type
150 string is arbitrary, except that it may not contain whitespace
151 characters, dots or colons. Applications use key types to obtain an
152 arbitrary but suitable key for some purpose. An
154 key cannot be looked up by type, but may be looked up by keyid or tag.
157 There are a number of different ways in which keys can be represented,
158 according to the uses to which the key will be put. Most symmetric
161 keys. Keys used with number-theoretic systems (like most common
162 public-key systems) use
163 .I "multiprecision integer"
164 keys. Algorithms which require several key constituents (again, like
165 most public-key systems) use
167 keys, which consist of a collection of named parts. Finally, keys
168 (including structured keys) can be encrypted.
171 Keys and key components may be selected by a filter expression, a
172 sequence of flag names separated by commas. Flags are:
178 (describing the key encoding);
184 (describing the category of key);
188 (whether the key should be erased from memory after use); and
192 (whether the key is safe to divulge).
195 A key component may be identified by the key's tag (or keyid, or type).
196 Subcomponents of structured keys are identified by following the tag by
197 a dot and the name of the subcomponent.
200 Most keys expire after a certain amount of time. Once a key has
201 expired, it will no longer be chosen as a result of a lookup by key
202 type. However, it is not deleted until its deletion time is also
206 A key's deletion time is the latest expiry time of any of the objects
207 which require that key. For example, a key used for authenticating
208 cryptographic cookies should have its deletion time set to the longest
209 expiry time of any of the cookies it can authenticate. Once a key's
210 deletion time is passed, it can no longer be referred to by
211 applications, and will be removed from the keyring next time it's
215 A key may be given a comment when it's created. The comment is for the
216 benefit of users, and isn't interpreted by applications at all.
220 A key as zero or more name/value pairs. The names and values are
221 arbitrary strings, except they may not contain null bytes. Some
222 attributes may have meaning for particular applications or key types;
223 others may be assigned global meanings in future.
224 .SH "COMMAND REFERENCE"
228 command creates a new key and adds it to the keyring. The command
229 accepts the following options:
231 .BI "\-a, \-\-algorithm " alg
232 Selects a key generation algorithm. The default algorithm is
234 the different algorithms are described below.
236 .BI "\-b, \-\-bits " bits
237 The length of the key to generate, in bits. The default, if this option
238 is not supplied, depends on the key-generation algorithm.
240 .BI "\-B, \-\-qbits " bits
241 The length of the subsidiary key or parameter, in bits. Not all
242 key-generation algorithms have a subsidiary key size.
244 .BI "\-p, \-\-parameters " tag
245 Selects a key containing parameter values to copy. Not all
246 key-generation algorithms allow the use of shared parameters.
248 .BI "\-e, \-\-expire " expire
249 The expiry date for the generated key. This may be the string
251 if the key should never expire automatically, or any date acceptable to
254 library function. Briefly,
256 understands absolute dates such as
259 .RB ` "August 2nd, 1999" ',
260 and (perhaps more usefully) relative dates such as
262 The default is to allow a 2 week expiry, which isn't useful.
264 .BI "\-c, \-\-comment " comment
265 Sets a comment for the key. The default is not to attach a comment.
267 .BI "\-t, \-\-tag " tag
268 Selects a tag string for the key. The default is not to set a tag. It
269 is an error to select a tag which already exists.
271 .BI "\-r, \-\-rand-id " tag
272 Selects the key to use for the random number generator. Catacomb's
273 random number generator can be
275 so that, even if the inputs to the generator are compromised, knowledge
276 of the key is also necessary to be able to predict the output. By
277 default, the latest-expiring key with type
279 is used, if present; if not, no key is used.
282 Requests that the secret parts of the newly-generated key be encrypted
286 Suppresses the progress indication which is usually generated while
287 time-consuming key generation tasks are being performed.
289 The key's type is given by the required
291 argument. Following the type are zero or more attributes, which are
292 attached to the key in the same way as for the
296 The key-generation algorithms supported are as follows:
299 Generates a plain binary key of the requested length. If the requested
300 key length is not a multiple of eight, the high-order bits of the first
301 octet of the key are zeroed. The default key length is 128 bits.
304 Generates a DES key, with parity bits. The key length must be 56, 112
305 or 168; the default is 56. The low-order bit of each octet is ignored by
306 the DES algorithm; it is used to give each octet odd parity.
309 Generates a public/private key pair for use with the RSA algorithm.
311 The key components are
315 a pair of prime numbers;
324 the private exponent, chosen such that
327 .RI ( p \ \-\ 1)( q \ \-\ 1));
328 and some other values useful for optimizing private-key operations:
329 .IR q \*(ss\-1\*(se\ mod\ p ,
330 .IR d \ mod\ p \ \-\ 1,
332 .IR d \ mod\ q \ \-\ 1.
337 constitute the public key; the rest must be kept secret. The key size
340 option determines the size of the modulus
342 the default is 1024 bits.
344 The key generation algorithm chooses
354 have large prime factors \- call them
360 also has a large prime factor;
362 has similar properties.
366 cannot be sensibly used as a shared parameter, since knowledge of
367 corrssponding public and private exponents is sufficient to be able to
368 factor the modulus and recover other users' private keys.
371 Generates parameters for use with the Diffie-Hellman key exchange
372 protocol, and many related systems, such as ElGamal encryption and
373 signatures, and even DSA (although the DSA algorithm is probably better
374 for this). The parameters are a prime number
376 a larger prime number
382 subgroup of the integers
385 The key size set by the
387 option determines the size of the modulus
389 the size of the generator order
393 option. The default modulus size is 1024 bits; if no size is specified
396 the parameters are chosen such that
397 .IR p \ =\ 2 q \ +\ 1,
401 is assigned the value 4. This takes much longer.
405 option, the algorithm simply copies the parameters from an existing key.
408 Generates a public/private key pair for use with offline Diffie-Hellman,
409 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
412 and computes the public key
413 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
416 Generates parameters for the DSA algorithm. DSA parameters are also
417 suitable for use with Diffie-Hellman and ElGamal system.
419 The main difference between DSA and Diffie-Hellman parameter generation
420 is thatthe DSA parameter generation
423 from which the parameters are derived, and, assuming that the SHA-1 hash
424 function is strong, it's not feasible to construct a seed from which
425 deliberately weak parameters are derived. The algorithm used is the one
426 described in the DSA standard, FIPS\ 186, extended only to allow
427 sequential search for a prime
429 and to allow arbitrary parameter sizes. The seed is stored,
430 Base64-encoded, as the value of the attribute
433 The default lengths for
437 are 768 and 160 bits respectively, since the DSA standard specifies that
439 be 160 bits, and the choice of 768 bits for
441 gives commensurate security.
444 Generates a public/private key pair for DSA. As for Diffie-Hellman
448 and computes the public key
449 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
452 Generates a public/private key pair for the Blum-Blum-Shub random-number
453 generator, and the Blum-Goldwasser semantically-secure public-key
456 The key components are prime numbers
460 both congruent to 3 (mod\ 4), and their product
462 The public key is simply the modulus
470 The key-generation algorithm ensures that the two primes
476 (see the discussion of strong primes above, in the section on RSA keys),
481 are relatively prime, giving a maximum possible period length.
483 The key size requested by the
485 option determines the length of the modulus
487 the default length is 1024 bits.
489 Forces keys to immediately expire. An expired key is not chosen when a
490 program requests a key by its type. The keys to expire are listed by
494 Deletes keys immediately. The keys to delete are listed by their
496 Be careful when deleting keys. It might be a better idea
497 to expire keys rather than deleting them.
499 Sets, deletes or changes the tag attached to a key. The first tag or
500 keyid names the key to be modified; the second, if present specifies the
501 new tag to be set. If no second argument is given, the existing tag, if
502 any, is removed and no new tag is set.
504 Attaches attributes to a key. The key to which the attributes should be
505 attached is given by its
507 Each attribute has the form
509 An attribute can be deleted by assigning it an empty value. Although
510 the keyring file format is capable of representing an attribute with an
511 empty value as distinct from a nonexistant attribute, this interface
512 does not allow empty attributes to be set.
514 Sets, deletes or changes the comment attached to a key. The first
515 argument is a key tag or keyid which names the key to be modified; the
516 second, if present, is the new comment. If no second argument is given,
517 the existing comment, if any, is removed, and no new comment is set.
519 Locks a key or key component using a passphrase. If the key is already
520 locked, the existing passphrase is requested, and a new passphrase is
523 Unlocks a passphrase-locked key or key component. If the key is not
524 locked, an error is reported.
526 Lists the keys in the keyring. A couple of options are supported:
528 .B "\-v, \-\-verbose"
529 Increases the amount of information displayed for each key. Repeat for
533 Decreases the amount of information displayed for each key. Each use
539 Display key expiry times as UTC rather than using the local time zone.
541 .BI "\-f, \-\-filter " filter
542 Specifies a filter. Only keys and key components which match the filter
545 By default, a single line of output is generated for each, showing
546 keyids, types, expiry and deletion dates, and comments. Additional
548 options show more information, such as the exact time of day for expiry
549 and deletion, key attributes, and a dump of the actual key data. If the
550 verbosity level is sufficiently high, passphrases are requested to
551 decrypt locked keys. Make sure nobody is looking over your shoulder
554 Reports a fingerprint (secure hash) on components of requested keys.
555 The following option is supported:
557 .BI "\-f, \-\-filter " filter
558 Specifies a filter. Only keys and key components which match the filter
559 are fingerprinted. The default is to only fingerprint nonsecret
562 The keys to be fingerprinted are named by their tags or keyids given as
563 command line arguments. If no key tags are given, all keys which match
564 the filter are fingerprinted.
566 Simply reads the keyring from file and writes it back again. This has
567 the effect of removing any deleted keys from the file.
569 Writes a selection of keys to a file. An option is supported:
571 .BI "\-f, \-\-filter " filter
572 Specifies a filter. Only keys and key components which match the filter
575 Keys extracted are written to the file named by the first argument,
578 to designate standard output. The keys to extract are listed by their
579 tags; if no tags are given, all keys which match the filter are
580 extracted. The output is a valid keyring file.
582 Merges the keys from the named
586 to designate standard input, with the keyring. Keys already in the
587 keyring are not overwritten: you must explicitly remove them first if
588 you want them to be replaced during the merge.
592 Mark Wooding, <mdw@nsict.org>