19 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
21 key \- simple key management system
105 command performs useful operations on Catacomb keyring files. It
106 provides a number of subcommands, by which the various operations may be
109 Before the command name,
111 may be given. The following global options are supported:
113 .BR "\-h, \-\-help " [ \fIcommand ]
114 Writes a brief summary of
116 various options to standard output, and
117 returns a successful exit status. With a command name, gives help on
120 .B "\-v, \-\-version"
121 Writes the program's version number to standard output, and returns a
122 successful exit status.
125 Writes a very terse command line summary to standard output, and returns
126 a successful exit status.
128 .BI "\-k, \-\-keyring " file
129 Names the keyring file which
131 is to process. The default keyring, used if this option doesn't specify
132 one, is the file named
134 in the current directory. The keyring must be stored in a regular file:
135 pipes, sockets, devices etc. are not allowed.
138 program attempts to lock the keyring before accessing it, using
140 locking. It will however time out after a short while (10 seconds) and
143 In addition to the actual key data itself, a Catacomb key has a number
144 of other pieces of information attached to it:
147 Every key has a 32-bit identifying number, written in hexadecimal.
148 Keyids are not actually related to the key contents: they're generated
149 randomly. Applications use keyids to refer to specific keys; users are
150 probably better off with tags and types. A
152 key cannot be looked up by keyid.
155 A key's tag is a unique string which can be used by users and
156 applications to identify the key. Tag strings may not contain spaces,
159 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
160 keyid or key type string can be given instead.
163 A key's type string describes what the key may be used for. The type
164 string is arbitrary, except that it may not contain whitespace
165 characters, dots or colons. Applications use key types to obtain an
166 arbitrary but suitable key for some purpose. An
168 key cannot be looked up by type, but may be looked up by keyid or tag.
171 There are a number of different ways in which keys can be represented,
172 according to the uses to which the key will be put. Most symmetric
175 keys. Keys used with number-theoretic systems (like most common
176 public-key systems) use
177 .I "multiprecision integer"
178 keys. Elliptic curve systems use
180 keys, which are either a pair of integers representing field elements,
181 or a `point at infinity'. Algorithms which require several key
182 constituents (again, like most public-key systems) use
184 keys, which consist of a collection of named parts. It's possible to
187 as a key, though this is usually done as a component of a structured
188 key. Finally, keys (including structured keys) can be encrypted.
191 Keys and key components may be selected by a filter expression, a
192 sequence of flag names separated by commas. Flags are:
200 (describing the key encoding);
206 (describing the category of key);
210 (whether the key should be erased from memory after use); and
214 (whether the key is safe to divulge).
217 A key component may be identified by the key's tag (or keyid, or type).
218 Subcomponents of structured keys are identified by following the tag by
219 a dot and the name of the subcomponent.
222 Most keys expire after a certain amount of time. Once a key has
223 expired, it will no longer be chosen as a result of a lookup by key
224 type. However, it is not deleted until its deletion time is also
228 A key's deletion time is the latest expiry time of any of the objects
229 which require that key. For example, a key used for authenticating
230 cryptographic cookies should have its deletion time set to the longest
231 expiry time of any of the cookies it can authenticate. Once a key's
232 deletion time is passed, it can no longer be referred to by
233 applications, and will be removed from the keyring next time it's
237 A key may be given a comment when it's created. The comment is for the
238 benefit of users, and isn't interpreted by applications at all.
242 A key as zero or more name/value pairs. The names and values are
243 arbitrary strings, except they may not contain null bytes. Some
244 attributes may have meaning for particular applications or key types;
245 others may be assigned global meanings in future.
246 .SH "COMMAND REFERENCE"
250 command creates a new key and adds it to the keyring. The command
251 accepts the following options:
253 .BI "\-a, \-\-algorithm " alg
254 Selects a key generation algorithm. The default algorithm is
256 the different algorithms are described below.
258 .BI "\-b, \-\-bits " bits
259 The length of the key to generate, in bits. The default, if this option
260 is not supplied, depends on the key-generation algorithm.
262 .BI "\-B, \-\-qbits " bits
263 The length of the subsidiary key or parameter, in bits. Not all
264 key-generation algorithms have a subsidiary key size.
266 .BI "\-p, \-\-parameters " tag
267 Selects a key containing parameter values to copy. Not all
268 key-generation algorithms allow the use of shared parameters.
270 .BI "\-e, \-\-expire " expire
271 The expiry date for the generated key. This may be the string
273 if the key should never expire automatically, or any date acceptable to
276 library function. Briefly,
278 understands absolute dates such as
281 .RB ` "August 2nd, 1999" ',
282 and (perhaps more usefully) relative dates such as
284 The default is to allow a 2 week expiry, which isn't useful.
286 .BI "\-c, \-\-comment " comment
287 Sets a comment for the key. The default is not to attach a comment.
289 .BI "\-C, \-\-curve " curve-spec
290 Use the elliptic curve described by
292 when generating elliptic curve parameters.
294 .BI "\-t, \-\-tag " tag
295 Selects a tag string for the key. The default is not to set a tag. It
296 is an error to select a tag which already exists.
301 option is given, remove this tag from any key which already has it.
303 .BI "\-R, \-\-rand-id " tag
304 Selects the key to use for the random number generator. Catacomb's
305 random number generator can be
307 so that, even if the inputs to the generator are compromised, knowledge
308 of the key is also necessary to be able to predict the output. By
309 default, the latest-expiring key with type
311 is used, if present; if not, no key is used.
314 Requests that the secret parts of the newly-generated key be encrypted
318 Suppresses the progress indication which is usually generated while
319 time-consuming key generation tasks are being performed.
322 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
323 rather than a random (or safe) prime. See the details on Diffie-Hellman
324 key generation below.
326 .BI "\-S, --subgroup"
327 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
328 generator of a prime-order subgroup rather than a subgroup of order
331 The key's type is given by the required
333 argument. Following the type are zero or more attributes, which are
334 attached to the key in the same way as for the
338 The key-generation algorithms supported are as follows:
341 Generates a plain binary key of the requested length. If the requested
342 key length is not a multiple of eight, the high-order bits of the first
343 octet of the key are zeroed. The default key length is 128 bits.
346 Generates a DES key, with parity bits. The key length must be 56, 112
347 or 168; the default is 56. The low-order bit of each octet is ignored by
348 the DES algorithm; it is used to give each octet odd parity.
351 Generates a public/private key pair for use with the RSA algorithm.
353 The key components are
357 a pair of prime numbers;
366 the private exponent, chosen such that
369 .RI ( p \ \-\ 1)( q \ \-\ 1));
370 and some other values useful for optimizing private-key operations:
371 .IR q \*(ss\-1\*(se\ mod\ p ,
372 .IR d \ mod\ p \ \-\ 1,
374 .IR d \ mod\ q \ \-\ 1.
379 constitute the public key; the rest must be kept secret. The key size
382 option determines the size of the modulus
384 the default is 1024 bits.
386 The key generation algorithm chooses
396 have large prime factors \- call them
402 also has a large prime factor;
404 has similar properties.
408 cannot be sensibly used as a shared parameter, since knowledge of
409 corrssponding public and private exponents is sufficient to be able to
410 factor the modulus and recover other users' private keys.
413 Generates parameters for use with the Diffie-Hellman key exchange
414 protocol, and many related systems, such as ElGamal encryption and
415 signatures, and even DSA. (The separate DSA algorithm uses the
416 generator described in FIPS186-1.)
418 The Diffie-Hellman parameters are a prime modulus
429 option controls the size of the modulus
431 the default size is 1024 bits.
435 size is selected using the
437 option and the Lim-Lee prime option is disabled, then
439 is chosen to be a `safe' prime (i.e.,
440 .IR p \ =\ 2 q \ +\ 1,
443 prime). Finding safe primes takes a very long time. In this case, the
448 If a size is chosen for
450 and Lim-Lee primes are not selected then the prime
461 option was given Lim-Lee primes are selected: the parameters are chosen
463 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
466 are primes at least as large as the setting given by the
468 option (or 256 bits, if no setting was given).
472 option was given, the generator
474 is chosen to generate the subgroup of order
478 will generate the group of order
479 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
483 option can be given, in which case the parameters are taken directly
484 from the provided group specification, which may either be the the name
485 of one of the built-in groups (say
486 .B "key add \-a dh\-param \-C list 42"
487 for a list) or a triple
489 separated by commas. No random generation is done in this case: the
490 given parameters are simply stored.
493 Generates a public/private key pair for use with offline Diffie-Hellman,
494 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
497 and computes the public key
498 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
501 Generates parameters for the DSA algorithm. DSA parameters are also
502 suitable for use with Diffie-Hellman and ElGamal system.
504 The main difference between DSA and Diffie-Hellman parameter generation
505 is thatthe DSA parameter generation
508 from which the parameters are derived, and, assuming that the SHA-1 hash
509 function is strong, it's not feasible to construct a seed from which
510 deliberately weak parameters are derived. The algorithm used is the one
511 described in the DSA standard, FIPS\ 186, extended only to allow
512 sequential search for a prime
514 and to allow arbitrary parameter sizes. The seed is stored,
515 Base64-encoded, as the value of the attribute
518 The default lengths for
522 are 768 and 160 bits respectively, since the DSA standard specifies that
524 be 160 bits, and the choice of 768 bits for
526 gives commensurate security.
529 Generates a public/private key pair for DSA. As for Diffie-Hellman
533 and computes the public key
534 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
537 Generates a public/private key pair for the Blum-Blum-Shub random-number
538 generator, and the Blum-Goldwasser semantically-secure public-key
541 The key components are prime numbers
545 both congruent to 3 (mod\ 4), and their product
547 The public key is simply the modulus
555 The key-generation algorithm ensures that the two primes
561 (see the discussion of strong primes above, in the section on RSA keys),
566 are relatively prime, giving a maximum possible period length.
568 The key size requested by the
570 option determines the length of the modulus
572 the default length is 1024 bits.
575 Store an elliptic curve specification. If no explicit
579 option) then a curve is chosen whose order is about the size given by the
581 option (default is 256 bits).
585 can be given explicitly (in which case
587 is ignored). It can either be the name of a built-in curve (say
588 .B "key add \-a ec\-param \-C list 42"
589 for a list of curve names) or a full specification. The curve is
590 checked for correctness and security according to the SEC1
591 specification: failed checks cause a warning to be issued to standard
592 error (though the program continues anyway). The check can be
597 A curve specification consists of the following elements optionally
598 separated by whitespace: a
614 and the representation of the normal element \*(*b; an optional
624 (the `proj' types currently have much better performance);
627 the two field-element parameters
631 which define the elliptic curve
633 separated by an optional
641 of the generator point
643 separated by an optional
649 of the group generated by
660 Generate a private scalar and a corresponding public point on an
663 above for how to specify elliptic curve parameter sets. The scalar
665 is chosen unformly between 0 and the curve order
667 the public point is then
672 Forces keys to immediately expire. An expired key is not chosen when a
673 program requests a key by its type. The keys to expire are listed by
677 Deletes keys immediately. The keys to delete are listed by their
679 Be careful when deleting keys. It might be a better idea
680 to expire keys rather than deleting them.
682 Sets, deletes or changes the tag attached to a key. The first tag or
683 keyid names the key to be modified; the second, if present specifies the
684 new tag to be set. If no second argument is given, the existing tag, if
685 any, is removed and no new tag is set. It is an error to set a tag
686 which already exists on another key, unless you give the
688 option, which removes the tag first.
690 Attaches attributes to a key. The key to which the attributes should be
691 attached is given by its
693 Each attribute has the form
695 An attribute can be deleted by assigning it an empty value. Although
696 the keyring file format is capable of representing an attribute with an
697 empty value as distinct from a nonexistant attribute, this interface
698 does not allow empty attributes to be set.
700 Sets, deletes or changes the comment attached to a key. The first
701 argument is a key tag or keyid which names the key to be modified; the
702 second, if present, is the new comment. If no second argument is given,
703 the existing comment, if any, is removed, and no new comment is set.
705 Locks a key or key component using a passphrase. If the key is already
706 locked, the existing passphrase is requested, and a new passphrase is
709 Unlocks a passphrase-locked key or key component. If the key is not
710 locked, an error is reported.
712 Lists the keys in the keyring. A couple of options are supported:
714 .B "\-v, \-\-verbose"
715 Increases the amount of information displayed for each key. Repeat for
719 Decreases the amount of information displayed for each key. Each use
725 Display key expiry times as UTC rather than using the local time zone.
727 .BI "\-f, \-\-filter " filter
728 Specifies a filter. Only keys and key components which match the filter
731 By default, a single line of output is generated for each, showing
732 keyids, types, expiry and deletion dates, and comments. Additional
734 options show more information, such as the exact time of day for expiry
735 and deletion, key attributes, and a dump of the actual key data. If the
736 verbosity level is sufficiently high, passphrases are requested to
737 decrypt locked keys. Make sure nobody is looking over your shoulder
740 Reports a fingerprint (secure hash) on components of requested keys.
741 The following option is supported:
743 .BI "\-f, \-\-filter " filter
744 Specifies a filter. Only keys and key components which match the filter
745 are fingerprinted. The default is to only fingerprint nonsecret
748 The keys to be fingerprinted are named by their tags or keyids given as
749 command line arguments. If no key tags are given, all keys which match
750 the filter are fingerprinted.
752 Simply reads the keyring from file and writes it back again. This has
753 the effect of removing any deleted keys from the file.
755 Writes a selection of keys to a file. An option is supported:
757 .BI "\-f, \-\-filter " filter
758 Specifies a filter. Only keys and key components which match the filter
761 Keys extracted are written to the file named by the first argument,
764 to designate standard output. The keys to extract are listed by their
765 tags; if no tags are given, all keys which match the filter are
766 extracted. The output is a valid keyring file.
768 Merges the keys from the named
772 to designate standard input, with the keyring. Keys already in the
773 keyring are not overwritten: you must explicitly remove them first if
774 you want them to be replaced during the merge.
778 Mark Wooding, <mdw@nsict.org>