14 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
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:
104 .BR "\-h, \-\-help " [ \fIcommand ]
105 Writes a brief summary of
107 various options to standard output, and
108 returns a successful exit status. With a command name, gives help on
111 .B "\-v, \-\-version"
112 Writes the program's version number to standard output, and returns a
113 successful exit status.
116 Writes a very terse command line summary to standard output, and returns
117 a successful exit status.
119 .BI "\-k, \-\-keyring " file
120 Names the keyring file which
122 is to process. The default keyring, used if this option doesn't specify
123 one, is the file named
125 in the current directory. The keyring must be stored in a regular file:
126 pipes, sockets, devices etc. are not allowed.
129 program attempts to lock the keyring before accessing it, using
131 locking. It will however time out after a short while (10 seconds) and
134 In addition to the actual key data itself, a Catacomb key has a number
135 of other pieces of information attached to it:
138 Every key has a 32-bit identifying number, written in hexadecimal.
139 Keyids are not actually related to the key contents: they're generated
140 randomly. Applications use keyids to refer to specific keys; users are
141 probably better off with tags and types. A
143 key cannot be looked up by keyid.
146 A key's tag is a unique string which can be used by users and
147 applications to identify the key. Tag strings may not contain spaces,
150 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
151 keyid or key type string can be given instead.
154 A key's type string describes what the key may be used for. The type
155 string is arbitrary, except that it may not contain whitespace
156 characters, dots or colons. Applications use key types to obtain an
157 arbitrary but suitable key for some purpose. An
159 key cannot be looked up by type, but may be looked up by keyid or tag.
162 There are a number of different ways in which keys can be represented,
163 according to the uses to which the key will be put. Most symmetric
166 keys. Keys used with number-theoretic systems (like most common
167 public-key systems) use
168 .I "multiprecision integer"
169 keys. Algorithms which require several key constituents (again, like
170 most public-key systems) use
172 keys, which consist of a collection of named parts. Finally, keys
173 (including structured keys) can be encrypted.
176 Keys and key components may be selected by a filter expression, a
177 sequence of flag names separated by commas. Flags are:
183 (describing the key encoding);
189 (describing the category of key);
193 (whether the key should be erased from memory after use); and
197 (whether the key is safe to divulge).
200 A key component may be identified by the key's tag (or keyid, or type).
201 Subcomponents of structured keys are identified by following the tag by
202 a dot and the name of the subcomponent.
205 Most keys expire after a certain amount of time. Once a key has
206 expired, it will no longer be chosen as a result of a lookup by key
207 type. However, it is not deleted until its deletion time is also
211 A key's deletion time is the latest expiry time of any of the objects
212 which require that key. For example, a key used for authenticating
213 cryptographic cookies should have its deletion time set to the longest
214 expiry time of any of the cookies it can authenticate. Once a key's
215 deletion time is passed, it can no longer be referred to by
216 applications, and will be removed from the keyring next time it's
220 A key may be given a comment when it's created. The comment is for the
221 benefit of users, and isn't interpreted by applications at all.
225 A key as zero or more name/value pairs. The names and values are
226 arbitrary strings, except they may not contain null bytes. Some
227 attributes may have meaning for particular applications or key types;
228 others may be assigned global meanings in future.
229 .SH "COMMAND REFERENCE"
233 command creates a new key and adds it to the keyring. The command
234 accepts the following options:
236 .BI "\-a, \-\-algorithm " alg
237 Selects a key generation algorithm. The default algorithm is
239 the different algorithms are described below.
241 .BI "\-b, \-\-bits " bits
242 The length of the key to generate, in bits. The default, if this option
243 is not supplied, depends on the key-generation algorithm.
245 .BI "\-B, \-\-qbits " bits
246 The length of the subsidiary key or parameter, in bits. Not all
247 key-generation algorithms have a subsidiary key size.
249 .BI "\-p, \-\-parameters " tag
250 Selects a key containing parameter values to copy. Not all
251 key-generation algorithms allow the use of shared parameters.
253 .BI "\-e, \-\-expire " expire
254 The expiry date for the generated key. This may be the string
256 if the key should never expire automatically, or any date acceptable to
259 library function. Briefly,
261 understands absolute dates such as
264 .RB ` "August 2nd, 1999" ',
265 and (perhaps more usefully) relative dates such as
267 The default is to allow a 2 week expiry, which isn't useful.
269 .BI "\-c, \-\-comment " comment
270 Sets a comment for the key. The default is not to attach a comment.
272 .BI "\-t, \-\-tag " tag
273 Selects a tag string for the key. The default is not to set a tag. It
274 is an error to select a tag which already exists.
279 option is given, remove this tag from any key which already has it.
281 .BI "\-R, \-\-rand-id " tag
282 Selects the key to use for the random number generator. Catacomb's
283 random number generator can be
285 so that, even if the inputs to the generator are compromised, knowledge
286 of the key is also necessary to be able to predict the output. By
287 default, the latest-expiring key with type
289 is used, if present; if not, no key is used.
292 Requests that the secret parts of the newly-generated key be encrypted
296 Suppresses the progress indication which is usually generated while
297 time-consuming key generation tasks are being performed.
300 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
301 rather than a random (or safe) prime. See the details on Diffie-Hellman
302 key generation below.
304 .BI "\-S, --subgroup"
305 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
306 generator of a prime-order subgroup rather than a subgroup of order
309 The key's type is given by the required
311 argument. Following the type are zero or more attributes, which are
312 attached to the key in the same way as for the
316 The key-generation algorithms supported are as follows:
319 Generates a plain binary key of the requested length. If the requested
320 key length is not a multiple of eight, the high-order bits of the first
321 octet of the key are zeroed. The default key length is 128 bits.
324 Generates a DES key, with parity bits. The key length must be 56, 112
325 or 168; the default is 56. The low-order bit of each octet is ignored by
326 the DES algorithm; it is used to give each octet odd parity.
329 Generates a public/private key pair for use with the RSA algorithm.
331 The key components are
335 a pair of prime numbers;
344 the private exponent, chosen such that
347 .RI ( p \ \-\ 1)( q \ \-\ 1));
348 and some other values useful for optimizing private-key operations:
349 .IR q \*(ss\-1\*(se\ mod\ p ,
350 .IR d \ mod\ p \ \-\ 1,
352 .IR d \ mod\ q \ \-\ 1.
357 constitute the public key; the rest must be kept secret. The key size
360 option determines the size of the modulus
362 the default is 1024 bits.
364 The key generation algorithm chooses
374 have large prime factors \- call them
380 also has a large prime factor;
382 has similar properties.
386 cannot be sensibly used as a shared parameter, since knowledge of
387 corrssponding public and private exponents is sufficient to be able to
388 factor the modulus and recover other users' private keys.
391 Generates parameters for use with the Diffie-Hellman key exchange
392 protocol, and many related systems, such as ElGamal encryption and
393 signatures, and even DSA. (The separate DSA algorithm uses the
394 generator described in FIPS186-1.)
396 The Diffie-Hellman parameters are a prime modulus
407 option controls the size of the modulus
409 the default size is 1024 bits.
413 size is selected using the
415 option and the Lim-Lee prime option is disabled, then
417 is chosen to be a `safe' prime (i.e.,
418 .IR p \ =\ 2 q \ +\ 1,
421 prime). In this case, the value of
425 If a size is chosen for
427 and Lim-Lee primes are not selected then the prime
438 option was given Lim-Lee primes are selected: the parameters are chosen
440 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
443 are primes at least as large as the setting given by the
445 option (or 256 bits, if no setting was given).
449 option was given, the generator
451 is chosen to generate the subgroup of order
455 will generate the group of order
456 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
459 Generates a public/private key pair for use with offline Diffie-Hellman,
460 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
463 and computes the public key
464 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
467 Generates parameters for the DSA algorithm. DSA parameters are also
468 suitable for use with Diffie-Hellman and ElGamal system.
470 The main difference between DSA and Diffie-Hellman parameter generation
471 is thatthe DSA parameter generation
474 from which the parameters are derived, and, assuming that the SHA-1 hash
475 function is strong, it's not feasible to construct a seed from which
476 deliberately weak parameters are derived. The algorithm used is the one
477 described in the DSA standard, FIPS\ 186, extended only to allow
478 sequential search for a prime
480 and to allow arbitrary parameter sizes. The seed is stored,
481 Base64-encoded, as the value of the attribute
484 The default lengths for
488 are 768 and 160 bits respectively, since the DSA standard specifies that
490 be 160 bits, and the choice of 768 bits for
492 gives commensurate security.
495 Generates a public/private key pair for DSA. As for Diffie-Hellman
499 and computes the public key
500 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
503 Generates a public/private key pair for the Blum-Blum-Shub random-number
504 generator, and the Blum-Goldwasser semantically-secure public-key
507 The key components are prime numbers
511 both congruent to 3 (mod\ 4), and their product
513 The public key is simply the modulus
521 The key-generation algorithm ensures that the two primes
527 (see the discussion of strong primes above, in the section on RSA keys),
532 are relatively prime, giving a maximum possible period length.
534 The key size requested by the
536 option determines the length of the modulus
538 the default length is 1024 bits.
540 Forces keys to immediately expire. An expired key is not chosen when a
541 program requests a key by its type. The keys to expire are listed by
545 Deletes keys immediately. The keys to delete are listed by their
547 Be careful when deleting keys. It might be a better idea
548 to expire keys rather than deleting them.
550 Sets, deletes or changes the tag attached to a key. The first tag or
551 keyid names the key to be modified; the second, if present specifies the
552 new tag to be set. If no second argument is given, the existing tag, if
553 any, is removed and no new tag is set. It is an error to set a tag
554 which already exists on another key, unless you give the
556 option, which removes the tag first.
558 Attaches attributes to a key. The key to which the attributes should be
559 attached is given by its
561 Each attribute has the form
563 An attribute can be deleted by assigning it an empty value. Although
564 the keyring file format is capable of representing an attribute with an
565 empty value as distinct from a nonexistant attribute, this interface
566 does not allow empty attributes to be set.
568 Sets, deletes or changes the comment attached to a key. The first
569 argument is a key tag or keyid which names the key to be modified; the
570 second, if present, is the new comment. If no second argument is given,
571 the existing comment, if any, is removed, and no new comment is set.
573 Locks a key or key component using a passphrase. If the key is already
574 locked, the existing passphrase is requested, and a new passphrase is
577 Unlocks a passphrase-locked key or key component. If the key is not
578 locked, an error is reported.
580 Lists the keys in the keyring. A couple of options are supported:
582 .B "\-v, \-\-verbose"
583 Increases the amount of information displayed for each key. Repeat for
587 Decreases the amount of information displayed for each key. Each use
593 Display key expiry times as UTC rather than using the local time zone.
595 .BI "\-f, \-\-filter " filter
596 Specifies a filter. Only keys and key components which match the filter
599 By default, a single line of output is generated for each, showing
600 keyids, types, expiry and deletion dates, and comments. Additional
602 options show more information, such as the exact time of day for expiry
603 and deletion, key attributes, and a dump of the actual key data. If the
604 verbosity level is sufficiently high, passphrases are requested to
605 decrypt locked keys. Make sure nobody is looking over your shoulder
608 Reports a fingerprint (secure hash) on components of requested keys.
609 The following option is supported:
611 .BI "\-f, \-\-filter " filter
612 Specifies a filter. Only keys and key components which match the filter
613 are fingerprinted. The default is to only fingerprint nonsecret
616 The keys to be fingerprinted are named by their tags or keyids given as
617 command line arguments. If no key tags are given, all keys which match
618 the filter are fingerprinted.
620 Simply reads the keyring from file and writes it back again. This has
621 the effect of removing any deleted keys from the file.
623 Writes a selection of keys to a file. An option is supported:
625 .BI "\-f, \-\-filter " filter
626 Specifies a filter. Only keys and key components which match the filter
629 Keys extracted are written to the file named by the first argument,
632 to designate standard output. The keys to extract are listed by their
633 tags; if no tags are given, all keys which match the filter are
634 extracted. The output is a valid keyring file.
636 Merges the keys from the named
640 to designate standard input, with the keyring. Keys already in the
641 keyring are not overwritten: you must explicitly remove them first if
642 you want them to be replaced during the merge.
646 Mark Wooding, <mdw@nsict.org>