14 .TH key 1 "5 June 1999" Catacomb
16 key \- simple key management system
96 command performs useful operations on Catacomb keyring files. It
97 provides a number of subcommands, by which the various operations may be
100 Before the command name,
102 may be given. The following global options are supported:
105 Writes a brief summary of
107 various options to standard output, and
108 returns a successful exit status.
110 .B "\-v, \-\-version"
111 Writes the program's version number to standard output, and returns a
112 successful exit status.
115 Writes a very terse command line summary to standard output, and returns
116 a successful exit status.
118 .BI "\-k, \-\-keyring " file
119 Names the keyring file which
121 is to process. The default keyring, used if this option doesn't specify
122 one, is the file named
124 in the current directory. The keyring must be stored in a regular file:
125 pipes, sockets, devices etc. are not allowed.
128 program attempts to lock the keyring before accessing it, using
130 locking. It will however time out after a short while (10 seconds) and
133 In addition to the actual key data itself, a Catacomb key has a number
134 of other pieces of information attached to it:
137 Every key has a 32-bit identifying number, written in hexadecimal.
138 Keyids are not actually related to the key contents: they're generated
139 randomly. Applications use keyids to refer to specific keys; users are
140 probably better off with tags and types. A
142 key cannot be looked up by keyid.
145 A key's tag is a unique string which can be used by users and
146 applications to identify the key. Tag strings may not contain spaces,
149 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
150 keyid or key type string can be given instead.
153 A key's type string describes what the key may be used for. The type
154 string is arbitrary, except that it may not contain whitespace
155 characters, dots or colons. Applications use key types to obtain an
156 arbitrary but suitable key for some purpose. An
158 key cannot be looked up by type, but may be looked up by keyid or tag.
161 There are a number of different ways in which keys can be represented,
162 according to the uses to which the key will be put. Most symmetric
165 keys. Keys used with number-theoretic systems (like most common
166 public-key systems) use
167 .I "multiprecision integer"
168 keys. Algorithms which require several key constituents (again, like
169 most public-key systems) use
171 keys, which consist of a collection of named parts. Finally, keys
172 (including structured keys) can be encrypted.
175 Keys and key components may be selected by a filter expression, a
176 sequence of flag names separated by commas. Flags are:
182 (describing the key encoding);
188 (describing the category of key);
192 (whether the key should be erased from memory after use); and
196 (whether the key is safe to divulge).
199 A key component may be identified by the key's tag (or keyid, or type).
200 Subcomponents of structured keys are identified by following the tag by
201 a dot and the name of the subcomponent.
204 Most keys expire after a certain amount of time. Once a key has
205 expired, it will no longer be chosen as a result of a lookup by key
206 type. However, it is not deleted until its deletion time is also
210 A key's deletion time is the latest expiry time of any of the objects
211 which require that key. For example, a key used for authenticating
212 cryptographic cookies should have its deletion time set to the longest
213 expiry time of any of the cookies it can authenticate. Once a key's
214 deletion time is passed, it can no longer be referred to by
215 applications, and will be removed from the keyring next time it's
219 A key may be given a comment when it's created. The comment is for the
220 benefit of users, and isn't interpreted by applications at all.
224 A key as zero or more name/value pairs. The names and values are
225 arbitrary strings, except they may not contain null bytes. Some
226 attributes may have meaning for particular applications or key types;
227 others may be assigned global meanings in future.
228 .SH "COMMAND REFERENCE"
232 command creates a new key and adds it to the keyring. The command
233 accepts the following options:
235 .BI "\-a, \-\-algorithm " alg
236 Selects a key generation algorithm. The default algorithm is
238 the different algorithms are described below.
240 .BI "\-b, \-\-bits " bits
241 The length of the key to generate, in bits. The default, if this option
242 is not supplied, depends on the key-generation algorithm.
244 .BI "\-B, \-\-qbits " bits
245 The length of the subsidiary key or parameter, in bits. Not all
246 key-generation algorithms have a subsidiary key size.
248 .BI "\-p, \-\-parameters " tag
249 Selects a key containing parameter values to copy. Not all
250 key-generation algorithms allow the use of shared parameters.
252 .BI "\-e, \-\-expire " expire
253 The expiry date for the generated key. This may be the string
255 if the key should never expire automatically, or any date acceptable to
258 library function. Briefly,
260 understands absolute dates such as
263 .RB ` "August 2nd, 1999" ',
264 and (perhaps more usefully) relative dates such as
266 The default is to allow a 2 week expiry, which isn't useful.
268 .BI "\-c, \-\-comment " comment
269 Sets a comment for the key. The default is not to attach a comment.
271 .BI "\-t, \-\-tag " tag
272 Selects a tag string for the key. The default is not to set a tag. It
273 is an error to select a tag which already exists.
275 .BI "\-r, \-\-rand-id " tag
276 Selects the key to use for the random number generator. Catacomb's
277 random number generator can be
279 so that, even if the inputs to the generator are compromised, knowledge
280 of the key is also necessary to be able to predict the output. By
281 default, the latest-expiring key with type
283 is used, if present; if not, no key is used.
286 Requests that the secret parts of the newly-generated key be encrypted
290 Suppresses the progress indication which is usually generated while
291 time-consuming key generation tasks are being performed.
294 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
295 rather than a random (or safe) prime. See the details on Diffie-Hellman
296 key generation below.
298 .BI "\-S, --subgroup"
299 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
300 generator of a prime-order subgroup rather than a subgroup of order
303 The key's type is given by the required
305 argument. Following the type are zero or more attributes, which are
306 attached to the key in the same way as for the
310 The key-generation algorithms supported are as follows:
313 Generates a plain binary key of the requested length. If the requested
314 key length is not a multiple of eight, the high-order bits of the first
315 octet of the key are zeroed. The default key length is 128 bits.
318 Generates a DES key, with parity bits. The key length must be 56, 112
319 or 168; the default is 56. The low-order bit of each octet is ignored by
320 the DES algorithm; it is used to give each octet odd parity.
323 Generates a public/private key pair for use with the RSA algorithm.
325 The key components are
329 a pair of prime numbers;
338 the private exponent, chosen such that
341 .RI ( p \ \-\ 1)( q \ \-\ 1));
342 and some other values useful for optimizing private-key operations:
343 .IR q \*(ss\-1\*(se\ mod\ p ,
344 .IR d \ mod\ p \ \-\ 1,
346 .IR d \ mod\ q \ \-\ 1.
351 constitute the public key; the rest must be kept secret. The key size
354 option determines the size of the modulus
356 the default is 1024 bits.
358 The key generation algorithm chooses
368 have large prime factors \- call them
374 also has a large prime factor;
376 has similar properties.
380 cannot be sensibly used as a shared parameter, since knowledge of
381 corrssponding public and private exponents is sufficient to be able to
382 factor the modulus and recover other users' private keys.
385 Generates parameters for use with the Diffie-Hellman key exchange
386 protocol, and many related systems, such as ElGamal encryption and
387 signatures, and even DSA. (The separate DSA algorithm uses the
388 generator described in FIPS186-1.)
390 The Diffie-Hellman parameters are a prime modulus
401 option controls the size of the modulus
403 the default size is 1024 bits.
407 size is selected using the
409 option and the Lim-Lee prime option is disabled, then
411 is chosen to be a `safe' prime (i.e.,
412 .IR p \ =\ 2 q \ +\ 1,
415 prime). In this case, the value of
419 If a size is chosen for
421 and Lim-Lee primes are not selected then the prime
432 option was given Lim-Lee primes are selected: the parameters are chosen
434 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
437 are primes at least as large as the setting given by the
439 option (or 256 bits, if no setting was given).
443 option was given, the generator
445 is chosen to generate the subgroup of order
449 will generate the group of order
450 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
453 Generates a public/private key pair for use with offline Diffie-Hellman,
454 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
457 and computes the public key
458 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
461 Generates parameters for the DSA algorithm. DSA parameters are also
462 suitable for use with Diffie-Hellman and ElGamal system.
464 The main difference between DSA and Diffie-Hellman parameter generation
465 is thatthe DSA parameter generation
468 from which the parameters are derived, and, assuming that the SHA-1 hash
469 function is strong, it's not feasible to construct a seed from which
470 deliberately weak parameters are derived. The algorithm used is the one
471 described in the DSA standard, FIPS\ 186, extended only to allow
472 sequential search for a prime
474 and to allow arbitrary parameter sizes. The seed is stored,
475 Base64-encoded, as the value of the attribute
478 The default lengths for
482 are 768 and 160 bits respectively, since the DSA standard specifies that
484 be 160 bits, and the choice of 768 bits for
486 gives commensurate security.
489 Generates a public/private key pair for DSA. As for Diffie-Hellman
493 and computes the public key
494 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
497 Generates a public/private key pair for the Blum-Blum-Shub random-number
498 generator, and the Blum-Goldwasser semantically-secure public-key
501 The key components are prime numbers
505 both congruent to 3 (mod\ 4), and their product
507 The public key is simply the modulus
515 The key-generation algorithm ensures that the two primes
521 (see the discussion of strong primes above, in the section on RSA keys),
526 are relatively prime, giving a maximum possible period length.
528 The key size requested by the
530 option determines the length of the modulus
532 the default length is 1024 bits.
534 Forces keys to immediately expire. An expired key is not chosen when a
535 program requests a key by its type. The keys to expire are listed by
539 Deletes keys immediately. The keys to delete are listed by their
541 Be careful when deleting keys. It might be a better idea
542 to expire keys rather than deleting them.
544 Sets, deletes or changes the tag attached to a key. The first tag or
545 keyid names the key to be modified; the second, if present specifies the
546 new tag to be set. If no second argument is given, the existing tag, if
547 any, is removed and no new tag is set.
549 Attaches attributes to a key. The key to which the attributes should be
550 attached is given by its
552 Each attribute has the form
554 An attribute can be deleted by assigning it an empty value. Although
555 the keyring file format is capable of representing an attribute with an
556 empty value as distinct from a nonexistant attribute, this interface
557 does not allow empty attributes to be set.
559 Sets, deletes or changes the comment attached to a key. The first
560 argument is a key tag or keyid which names the key to be modified; the
561 second, if present, is the new comment. If no second argument is given,
562 the existing comment, if any, is removed, and no new comment is set.
564 Locks a key or key component using a passphrase. If the key is already
565 locked, the existing passphrase is requested, and a new passphrase is
568 Unlocks a passphrase-locked key or key component. If the key is not
569 locked, an error is reported.
571 Lists the keys in the keyring. A couple of options are supported:
573 .B "\-v, \-\-verbose"
574 Increases the amount of information displayed for each key. Repeat for
578 Decreases the amount of information displayed for each key. Each use
584 Display key expiry times as UTC rather than using the local time zone.
586 .BI "\-f, \-\-filter " filter
587 Specifies a filter. Only keys and key components which match the filter
590 By default, a single line of output is generated for each, showing
591 keyids, types, expiry and deletion dates, and comments. Additional
593 options show more information, such as the exact time of day for expiry
594 and deletion, key attributes, and a dump of the actual key data. If the
595 verbosity level is sufficiently high, passphrases are requested to
596 decrypt locked keys. Make sure nobody is looking over your shoulder
599 Reports a fingerprint (secure hash) on components of requested keys.
600 The following option is supported:
602 .BI "\-f, \-\-filter " filter
603 Specifies a filter. Only keys and key components which match the filter
604 are fingerprinted. The default is to only fingerprint nonsecret
607 The keys to be fingerprinted are named by their tags or keyids given as
608 command line arguments. If no key tags are given, all keys which match
609 the filter are fingerprinted.
611 Simply reads the keyring from file and writes it back again. This has
612 the effect of removing any deleted keys from the file.
614 Writes a selection of keys to a file. An option is supported:
616 .BI "\-f, \-\-filter " filter
617 Specifies a filter. Only keys and key components which match the filter
620 Keys extracted are written to the file named by the first argument,
623 to designate standard output. The keys to extract are listed by their
624 tags; if no tags are given, all keys which match the filter are
625 extracted. The output is a valid keyring file.
627 Merges the keys from the named
631 to designate standard input, with the keyring. Keys already in the
632 keyring are not overwritten: you must explicitly remove them first if
633 you want them to be replaced during the merge.
637 Mark Wooding, <mdw@nsict.org>