14 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
16 key \- simple key management system
100 command performs useful operations on Catacomb keyring files. It
101 provides a number of subcommands, by which the various operations may be
104 Before the command name,
106 may be given. The following global options are supported:
108 .BR "\-h, \-\-help " [ \fIcommand ]
109 Writes a brief summary of
111 various options to standard output, and
112 returns a successful exit status. With a command name, gives help on
115 .B "\-v, \-\-version"
116 Writes the program's version number to standard output, and returns a
117 successful exit status.
120 Writes a very terse command line summary to standard output, and returns
121 a successful exit status.
123 .BI "\-k, \-\-keyring " file
124 Names the keyring file which
126 is to process. The default keyring, used if this option doesn't specify
127 one, is the file named
129 in the current directory. The keyring must be stored in a regular file:
130 pipes, sockets, devices etc. are not allowed.
133 program attempts to lock the keyring before accessing it, using
135 locking. It will however time out after a short while (10 seconds) and
138 In addition to the actual key data itself, a Catacomb key has a number
139 of other pieces of information attached to it:
142 Every key has a 32-bit identifying number, written in hexadecimal.
143 Keyids are not actually related to the key contents: they're generated
144 randomly. Applications use keyids to refer to specific keys; users are
145 probably better off with tags and types. A
147 key cannot be looked up by keyid.
150 A key's tag is a unique string which can be used by users and
151 applications to identify the key. Tag strings may not contain spaces,
154 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
155 keyid or key type string can be given instead.
158 A key's type string describes what the key may be used for. The type
159 string is arbitrary, except that it may not contain whitespace
160 characters, dots or colons. Applications use key types to obtain an
161 arbitrary but suitable key for some purpose. An
163 key cannot be looked up by type, but may be looked up by keyid or tag.
166 There are a number of different ways in which keys can be represented,
167 according to the uses to which the key will be put. Most symmetric
170 keys. Keys used with number-theoretic systems (like most common
171 public-key systems) use
172 .I "multiprecision integer"
173 keys. Algorithms which require several key constituents (again, like
174 most public-key systems) use
176 keys, which consist of a collection of named parts. Finally, keys
177 (including structured keys) can be encrypted.
180 Keys and key components may be selected by a filter expression, a
181 sequence of flag names separated by commas. Flags are:
187 (describing the key encoding);
193 (describing the category of key);
197 (whether the key should be erased from memory after use); and
201 (whether the key is safe to divulge).
204 A key component may be identified by the key's tag (or keyid, or type).
205 Subcomponents of structured keys are identified by following the tag by
206 a dot and the name of the subcomponent.
209 Most keys expire after a certain amount of time. Once a key has
210 expired, it will no longer be chosen as a result of a lookup by key
211 type. However, it is not deleted until its deletion time is also
215 A key's deletion time is the latest expiry time of any of the objects
216 which require that key. For example, a key used for authenticating
217 cryptographic cookies should have its deletion time set to the longest
218 expiry time of any of the cookies it can authenticate. Once a key's
219 deletion time is passed, it can no longer be referred to by
220 applications, and will be removed from the keyring next time it's
224 A key may be given a comment when it's created. The comment is for the
225 benefit of users, and isn't interpreted by applications at all.
229 A key as zero or more name/value pairs. The names and values are
230 arbitrary strings, except they may not contain null bytes. Some
231 attributes may have meaning for particular applications or key types;
232 others may be assigned global meanings in future.
233 .SH "COMMAND REFERENCE"
237 command creates a new key and adds it to the keyring. The command
238 accepts the following options:
240 .BI "\-a, \-\-algorithm " alg
241 Selects a key generation algorithm. The default algorithm is
243 the different algorithms are described below.
245 .BI "\-b, \-\-bits " bits
246 The length of the key to generate, in bits. The default, if this option
247 is not supplied, depends on the key-generation algorithm.
249 .BI "\-B, \-\-qbits " bits
250 The length of the subsidiary key or parameter, in bits. Not all
251 key-generation algorithms have a subsidiary key size.
253 .BI "\-p, \-\-parameters " tag
254 Selects a key containing parameter values to copy. Not all
255 key-generation algorithms allow the use of shared parameters.
257 .BI "\-e, \-\-expire " expire
258 The expiry date for the generated key. This may be the string
260 if the key should never expire automatically, or any date acceptable to
263 library function. Briefly,
265 understands absolute dates such as
268 .RB ` "August 2nd, 1999" ',
269 and (perhaps more usefully) relative dates such as
271 The default is to allow a 2 week expiry, which isn't useful.
273 .BI "\-c, \-\-comment " comment
274 Sets a comment for the key. The default is not to attach a comment.
276 .BI "\-C, \-\-curve " curve-spec
277 Use the elliptic curve described by
279 when generating elliptic curve parameters.
281 .BI "\-t, \-\-tag " tag
282 Selects a tag string for the key. The default is not to set a tag. It
283 is an error to select a tag which already exists.
288 option is given, remove this tag from any key which already has it.
290 .BI "\-R, \-\-rand-id " tag
291 Selects the key to use for the random number generator. Catacomb's
292 random number generator can be
294 so that, even if the inputs to the generator are compromised, knowledge
295 of the key is also necessary to be able to predict the output. By
296 default, the latest-expiring key with type
298 is used, if present; if not, no key is used.
301 Requests that the secret parts of the newly-generated key be encrypted
305 Suppresses the progress indication which is usually generated while
306 time-consuming key generation tasks are being performed.
309 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
310 rather than a random (or safe) prime. See the details on Diffie-Hellman
311 key generation below.
313 .BI "\-S, --subgroup"
314 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
315 generator of a prime-order subgroup rather than a subgroup of order
318 The key's type is given by the required
320 argument. Following the type are zero or more attributes, which are
321 attached to the key in the same way as for the
325 The key-generation algorithms supported are as follows:
328 Generates a plain binary key of the requested length. If the requested
329 key length is not a multiple of eight, the high-order bits of the first
330 octet of the key are zeroed. The default key length is 128 bits.
333 Generates a DES key, with parity bits. The key length must be 56, 112
334 or 168; the default is 56. The low-order bit of each octet is ignored by
335 the DES algorithm; it is used to give each octet odd parity.
338 Generates a public/private key pair for use with the RSA algorithm.
340 The key components are
344 a pair of prime numbers;
353 the private exponent, chosen such that
356 .RI ( p \ \-\ 1)( q \ \-\ 1));
357 and some other values useful for optimizing private-key operations:
358 .IR q \*(ss\-1\*(se\ mod\ p ,
359 .IR d \ mod\ p \ \-\ 1,
361 .IR d \ mod\ q \ \-\ 1.
366 constitute the public key; the rest must be kept secret. The key size
369 option determines the size of the modulus
371 the default is 1024 bits.
373 The key generation algorithm chooses
383 have large prime factors \- call them
389 also has a large prime factor;
391 has similar properties.
395 cannot be sensibly used as a shared parameter, since knowledge of
396 corrssponding public and private exponents is sufficient to be able to
397 factor the modulus and recover other users' private keys.
400 Generates parameters for use with the Diffie-Hellman key exchange
401 protocol, and many related systems, such as ElGamal encryption and
402 signatures, and even DSA. (The separate DSA algorithm uses the
403 generator described in FIPS186-1.)
405 The Diffie-Hellman parameters are a prime modulus
416 option controls the size of the modulus
418 the default size is 1024 bits.
422 size is selected using the
424 option and the Lim-Lee prime option is disabled, then
426 is chosen to be a `safe' prime (i.e.,
427 .IR p \ =\ 2 q \ +\ 1,
430 prime). In this case, the value of
434 If a size is chosen for
436 and Lim-Lee primes are not selected then the prime
447 option was given Lim-Lee primes are selected: the parameters are chosen
449 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
452 are primes at least as large as the setting given by the
454 option (or 256 bits, if no setting was given).
458 option was given, the generator
460 is chosen to generate the subgroup of order
464 will generate the group of order
465 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
468 Generates a public/private key pair for use with offline Diffie-Hellman,
469 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
472 and computes the public key
473 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
476 Generates parameters for the DSA algorithm. DSA parameters are also
477 suitable for use with Diffie-Hellman and ElGamal system.
479 The main difference between DSA and Diffie-Hellman parameter generation
480 is thatthe DSA parameter generation
483 from which the parameters are derived, and, assuming that the SHA-1 hash
484 function is strong, it's not feasible to construct a seed from which
485 deliberately weak parameters are derived. The algorithm used is the one
486 described in the DSA standard, FIPS\ 186, extended only to allow
487 sequential search for a prime
489 and to allow arbitrary parameter sizes. The seed is stored,
490 Base64-encoded, as the value of the attribute
493 The default lengths for
497 are 768 and 160 bits respectively, since the DSA standard specifies that
499 be 160 bits, and the choice of 768 bits for
501 gives commensurate security.
504 Generates a public/private key pair for DSA. As for Diffie-Hellman
508 and computes the public key
509 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
512 Generates a public/private key pair for the Blum-Blum-Shub random-number
513 generator, and the Blum-Goldwasser semantically-secure public-key
516 The key components are prime numbers
520 both congruent to 3 (mod\ 4), and their product
522 The public key is simply the modulus
530 The key-generation algorithm ensures that the two primes
536 (see the discussion of strong primes above, in the section on RSA keys),
541 are relatively prime, giving a maximum possible period length.
543 The key size requested by the
545 option determines the length of the modulus
547 the default length is 1024 bits.
550 Store an elliptic curve specification. If no explicit
554 option) then a curve is chosen whose order is about the size given by the
556 option (default is 256 bits).
560 can be given explicitly (in which case
562 is ignored). It can either be the name of a built-in curve (say
563 .B "key add \-C list"
564 for a list of curve names) or a full specification. The curve is
565 checked for correctness and security according to the SEC1
566 specification: failed checks cause a warning to be issued to standard
567 error (though the program continues anyway). The check can be
572 A curve specification consists of the following elements optionally
573 separated by whitespace: a
594 (the `proj' types currently have much better performance);
597 the two field-element parameters
601 which define the elliptic curve
603 separated by an optional
611 of the generator point
613 separated by an optional
619 of the group generated by
630 Generate a private scalar and a corresponding public point on an
633 above for how to specify elliptic curve parameter sets. The scalar
635 is chosen unformly between 0 and the curve order
637 the public point is then
642 Forces keys to immediately expire. An expired key is not chosen when a
643 program requests a key by its type. The keys to expire are listed by
647 Deletes keys immediately. The keys to delete are listed by their
649 Be careful when deleting keys. It might be a better idea
650 to expire keys rather than deleting them.
652 Sets, deletes or changes the tag attached to a key. The first tag or
653 keyid names the key to be modified; the second, if present specifies the
654 new tag to be set. If no second argument is given, the existing tag, if
655 any, is removed and no new tag is set. It is an error to set a tag
656 which already exists on another key, unless you give the
658 option, which removes the tag first.
660 Attaches attributes to a key. The key to which the attributes should be
661 attached is given by its
663 Each attribute has the form
665 An attribute can be deleted by assigning it an empty value. Although
666 the keyring file format is capable of representing an attribute with an
667 empty value as distinct from a nonexistant attribute, this interface
668 does not allow empty attributes to be set.
670 Sets, deletes or changes the comment attached to a key. The first
671 argument is a key tag or keyid which names the key to be modified; the
672 second, if present, is the new comment. If no second argument is given,
673 the existing comment, if any, is removed, and no new comment is set.
675 Locks a key or key component using a passphrase. If the key is already
676 locked, the existing passphrase is requested, and a new passphrase is
679 Unlocks a passphrase-locked key or key component. If the key is not
680 locked, an error is reported.
682 Lists the keys in the keyring. A couple of options are supported:
684 .B "\-v, \-\-verbose"
685 Increases the amount of information displayed for each key. Repeat for
689 Decreases the amount of information displayed for each key. Each use
695 Display key expiry times as UTC rather than using the local time zone.
697 .BI "\-f, \-\-filter " filter
698 Specifies a filter. Only keys and key components which match the filter
701 By default, a single line of output is generated for each, showing
702 keyids, types, expiry and deletion dates, and comments. Additional
704 options show more information, such as the exact time of day for expiry
705 and deletion, key attributes, and a dump of the actual key data. If the
706 verbosity level is sufficiently high, passphrases are requested to
707 decrypt locked keys. Make sure nobody is looking over your shoulder
710 Reports a fingerprint (secure hash) on components of requested keys.
711 The following option is supported:
713 .BI "\-f, \-\-filter " filter
714 Specifies a filter. Only keys and key components which match the filter
715 are fingerprinted. The default is to only fingerprint nonsecret
718 The keys to be fingerprinted are named by their tags or keyids given as
719 command line arguments. If no key tags are given, all keys which match
720 the filter are fingerprinted.
722 Simply reads the keyring from file and writes it back again. This has
723 the effect of removing any deleted keys from the file.
725 Writes a selection of keys to a file. An option is supported:
727 .BI "\-f, \-\-filter " filter
728 Specifies a filter. Only keys and key components which match the filter
731 Keys extracted are written to the file named by the first argument,
734 to designate standard output. The keys to extract are listed by their
735 tags; if no tags are given, all keys which match the filter are
736 extracted. The output is a valid keyring file.
738 Merges the keys from the named
742 to designate standard input, with the keyring. Keys already in the
743 keyring are not overwritten: you must explicitly remove them first if
744 you want them to be replaced during the merge.
748 Mark Wooding, <mdw@nsict.org>