19 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
21 key \- simple key management system
107 command performs useful operations on Catacomb keyring files. It
108 provides a number of subcommands, by which the various operations may be
111 Before the command name,
113 may be given. The following global options are supported:
115 .BR "\-h, \-\-help " [ \fIcommand ]
116 Writes a brief summary of
118 various options to standard output, and
119 returns a successful exit status. With a command name, gives help on
122 .B "\-v, \-\-version"
123 Writes the program's version number to standard output, and returns a
124 successful exit status.
127 Writes a very terse command line summary to standard output, and returns
128 a successful exit status.
130 .BI "\-k, \-\-keyring " file
131 Names the keyring file which
133 is to process. The default keyring, used if this option doesn't specify
134 one, is the file named
136 in the current directory. The keyring must be stored in a regular file:
137 pipes, sockets, devices etc. are not allowed.
140 program attempts to lock the keyring before accessing it, using
142 locking. It will however time out after a short while (10 seconds) and
145 In addition to the actual key data itself, a Catacomb key has a number
146 of other pieces of information attached to it:
149 Every key has a 32-bit identifying number, written in hexadecimal.
150 Keyids are not actually related to the key contents: they're generated
151 randomly. Applications use keyids to refer to specific keys; users are
152 probably better off with tags and types. A
154 key cannot be looked up by keyid.
157 A key's tag is a unique string which can be used by users and
158 applications to identify the key. Tag strings may not contain spaces,
161 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
162 keyid or key type string can be given instead.
165 A key's type string describes what the key may be used for. The type
166 string is arbitrary, except that it may not contain whitespace
167 characters, dots or colons. Applications use key types to obtain an
168 arbitrary but suitable key for some purpose. An
170 key cannot be looked up by type, but may be looked up by keyid or tag.
173 There are a number of different ways in which keys can be represented,
174 according to the uses to which the key will be put. Most symmetric
177 keys. Keys used with number-theoretic systems (like most common
178 public-key systems) use
179 .I "multiprecision integer"
180 keys. Elliptic curve systems use
182 keys, which are either a pair of integers representing field elements,
183 or a `point at infinity'. Algorithms which require several key
184 constituents (again, like most public-key systems) use
186 keys, which consist of a collection of named parts. It's possible to
189 as a key, though this is usually done as a component of a structured
190 key. Finally, keys (including structured keys) can be encrypted.
193 Keys and key components may be selected by a filter expression, a
194 sequence of flag names separated by commas. Flags are:
202 (describing the key encoding);
208 (describing the category of key);
212 (whether the key should be erased from memory after use); and
216 (whether the key is safe to divulge).
219 A key component may be identified by the key's tag (or keyid, or type).
220 Subcomponents of structured keys are identified by following the tag by
221 a dot and the name of the subcomponent.
224 Most keys expire after a certain amount of time. Once a key has
225 expired, it will no longer be chosen as a result of a lookup by key
226 type. However, it is not deleted until its deletion time is also
230 A key's deletion time is the latest expiry time of any of the objects
231 which require that key. For example, a key used for authenticating
232 cryptographic cookies should have its deletion time set to the longest
233 expiry time of any of the cookies it can authenticate. Once a key's
234 deletion time is passed, it can no longer be referred to by
235 applications, and will be removed from the keyring next time it's
239 A key may be given a comment when it's created. The comment is for the
240 benefit of users, and isn't interpreted by applications at all.
244 A key as zero or more name/value pairs. The names and values are
245 arbitrary strings, except they may not contain null bytes. Some
246 attributes may have meaning for particular applications or key types;
247 others may be assigned global meanings in future.
248 .SH "COMMAND REFERENCE"
252 command creates a new key and adds it to the keyring. The command
253 accepts the following options:
255 .BI "\-a, \-\-algorithm " alg
256 Selects a key generation algorithm. The default algorithm is
258 the different algorithms are described below.
260 .BI "\-b, \-\-bits " bits
261 The length of the key to generate, in bits. The default, if this option
262 is not supplied, depends on the key-generation algorithm.
264 .BI "\-B, \-\-qbits " bits
265 The length of the subsidiary key or parameter, in bits. Not all
266 key-generation algorithms have a subsidiary key size.
268 .BI "\-p, \-\-parameters " tag
269 Selects a key containing parameter values to copy. Not all
270 key-generation algorithms allow the use of shared parameters. A new key
271 also inherits attributes from its parameter key.
273 .BI "\-e, \-\-expire " expire
274 The expiry date for the generated key. This may be the string
276 if the key should never expire automatically, or any date acceptable to
279 library function. Briefly,
281 understands absolute dates such as
284 .RB ` "August 2nd, 1999" ',
285 and (perhaps more usefully) relative dates such as
287 The default is to allow a 2 week expiry, which isn't useful.
289 .BI "\-c, \-\-comment " comment
290 Sets a comment for the key. The default is not to attach a comment.
292 .BI "\-C, \-\-curve " curve-spec
293 Use the elliptic curve described by
295 when generating elliptic curve parameters.
297 .BI "\-t, \-\-tag " tag
298 Selects a tag string for the key. The default is not to set a tag. It
299 is an error to select a tag which already exists.
304 option is given, remove this tag from any key which already has it.
306 .BI "\-R, \-\-rand-id " tag
307 Selects the key to use for the random number generator. Catacomb's
308 random number generator can be
310 so that, even if the inputs to the generator are compromised, knowledge
311 of the key is also necessary to be able to predict the output. By
312 default, the latest-expiring key with type
314 is used, if present; if not, no key is used.
317 Requests that the secret parts of the newly-generated key be encrypted
321 Suppresses the progress indication which is usually generated while
322 time-consuming key generation tasks are being performed.
325 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
326 rather than a random (or safe) prime. See the details on Diffie-Hellman
327 key generation below.
329 .BI "\-S, --subgroup"
330 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
331 generator of a prime-order subgroup rather than a subgroup of order
334 The key's type is given by the required
336 argument. Following the type are zero or more attributes, which are
337 attached to the key in the same way as for the
341 The key-generation algorithms supported are as follows:
344 Generates a plain binary key of the requested length. If the requested
345 key length is not a multiple of eight, the high-order bits of the first
346 octet of the key are zeroed. The default key length is 128 bits.
349 Generates a DES key, with parity bits. The key length must be 56, 112
350 or 168; the default is 56. The low-order bit of each octet is ignored by
351 the DES algorithm; it is used to give each octet odd parity.
354 Generates a public/private key pair for use with the RSA algorithm.
356 The key components are
360 a pair of prime numbers;
369 the private exponent, chosen such that
372 .RI ( p \ \-\ 1)( q \ \-\ 1));
373 and some other values useful for optimizing private-key operations:
374 .IR q \*(ss\-1\*(se\ mod\ p ,
375 .IR d \ mod\ p \ \-\ 1,
377 .IR d \ mod\ q \ \-\ 1.
382 constitute the public key; the rest must be kept secret. The key size
385 option determines the size of the modulus
387 the default is 1024 bits.
389 The key generation algorithm chooses
399 have large prime factors \- call them
405 also has a large prime factor;
407 has similar properties.
411 cannot be sensibly used as a shared parameter, since knowledge of
412 corrssponding public and private exponents is sufficient to be able to
413 factor the modulus and recover other users' private keys.
416 Generates parameters for use with the Diffie-Hellman key exchange
417 protocol, and many related systems, such as ElGamal encryption and
418 signatures, and even DSA. (The separate DSA algorithm uses the
419 generator described in FIPS186-1.)
421 The Diffie-Hellman parameters are a prime modulus
432 option controls the size of the modulus
434 the default size is 1024 bits.
438 size is selected using the
440 option and the Lim-Lee prime option is disabled, then
442 is chosen to be a `safe' prime (i.e.,
443 .IR p \ =\ 2 q \ +\ 1,
446 prime). Finding safe primes takes a very long time. In this case, the
451 If a size is chosen for
453 and Lim-Lee primes are not selected then the prime
464 option was given Lim-Lee primes are selected: the parameters are chosen
466 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
469 are primes at least as large as the setting given by the
471 option (or 256 bits, if no setting was given).
475 option was given, the generator
477 is chosen to generate the subgroup of order
481 will generate the group of order
482 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
486 option can be given, in which case the parameters are taken directly
487 from the provided group specification, which may either be the the name
488 of one of the built-in groups (say
489 .B "key add \-a dh\-param \-C list 42"
490 for a list) or a triple
492 separated by commas. No random generation is done in this case: the
493 given parameters are simply stored.
496 Generates a public/private key pair for use with offline Diffie-Hellman,
497 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
500 and computes the public key
501 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
504 Generates parameters for the DSA algorithm. DSA parameters are also
505 suitable for use with Diffie-Hellman and ElGamal system.
507 The main difference between DSA and Diffie-Hellman parameter generation
508 is thatthe DSA parameter generation
511 from which the parameters are derived, and, assuming that the SHA-1 hash
512 function is strong, it's not feasible to construct a seed from which
513 deliberately weak parameters are derived. The algorithm used is the one
514 described in the DSA standard, FIPS\ 186, extended only to allow
515 sequential search for a prime
517 and to allow arbitrary parameter sizes. The seed is stored,
518 Base64-encoded, as the value of the attribute
521 The default lengths for
525 are 768 and 160 bits respectively, since the DSA standard specifies that
527 be 160 bits, and the choice of 768 bits for
529 gives commensurate security.
532 Generates a public/private key pair for DSA. As for Diffie-Hellman
536 and computes the public key
537 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
540 Generates a public/private key pair for the Blum-Blum-Shub random-number
541 generator, and the Blum-Goldwasser semantically-secure public-key
544 The key components are prime numbers
548 both congruent to 3 (mod\ 4), and their product
550 The public key is simply the modulus
558 The key-generation algorithm ensures that the two primes
564 (see the discussion of strong primes above, in the section on RSA keys),
569 are relatively prime, giving a maximum possible period length.
571 The key size requested by the
573 option determines the length of the modulus
575 the default length is 1024 bits.
578 Store an elliptic curve specification. If no explicit
582 option) then a curve is chosen whose order is about the size given by the
584 option (default is 256 bits).
588 can be given explicitly (in which case
590 is ignored). It can either be the name of a built-in curve (say
591 .B "key add \-a ec\-param \-C list 42"
592 for a list of curve names) or a full specification. The curve is
593 checked for correctness and security according to the SEC1
594 specification: failed checks cause a warning to be issued to standard
595 error (though the program continues anyway). The check can be
600 A curve specification consists of the following elements optionally
601 separated by whitespace: a
617 and the representation of the normal element \*(*b; an optional
627 (the `proj' types currently have much better performance);
630 the two field-element parameters
634 which define the elliptic curve
636 separated by an optional
644 of the generator point
646 separated by an optional
652 of the group generated by
663 Generate a private scalar and a corresponding public point on an
666 above for how to specify elliptic curve parameter sets. The scalar
668 is chosen unformly between 0 and the curve order
670 the public point is then
675 Forces keys to immediately expire. An expired key is not chosen when a
676 program requests a key by its type. The keys to expire are listed by
680 Deletes keys immediately. The keys to delete are listed by their
682 Be careful when deleting keys. It might be a better idea
683 to expire keys rather than deleting them.
685 Sets, deletes or changes the tag attached to a key. The first tag or
686 keyid names the key to be modified; the second, if present specifies the
687 new tag to be set. If no second argument is given, the existing tag, if
688 any, is removed and no new tag is set. It is an error to set a tag
689 which already exists on another key, unless you give the
691 option, which removes the tag first.
693 Attaches attributes to a key. The key to which the attributes should be
694 attached is given by its
696 Each attribute has the form
698 An attribute can be deleted by assigning it an empty value. Although
699 the keyring file format is capable of representing an attribute with an
700 empty value as distinct from a nonexistant attribute, this interface
701 does not allow empty attributes to be set.
703 Sets, deletes or changes the comment attached to a key. The first
704 argument is a key tag or keyid which names the key to be modified; the
705 second, if present, is the new comment. If no second argument is given,
706 the existing comment, if any, is removed, and no new comment is set.
708 Locks a key or key component using a passphrase. If the key is already
709 locked, the existing passphrase is requested, and a new passphrase is
712 Unlocks a passphrase-locked key or key component. If the key is not
713 locked, an error is reported.
715 Lists the keys in the keyring. A couple of options are supported:
717 .B "\-v, \-\-verbose"
718 Increases the amount of information displayed for each key. Repeat for
722 Decreases the amount of information displayed for each key. Each use
728 Display key expiry times as UTC rather than using the local time zone.
730 .BI "\-f, \-\-filter " filter
731 Specifies a filter. Only keys and key components which match the filter
734 By default, a single line of output is generated for each, showing
735 keyids, types, expiry and deletion dates, and comments. Additional
737 options show more information, such as the exact time of day for expiry
738 and deletion, key attributes, and a dump of the actual key data. If the
739 verbosity level is sufficiently high, passphrases are requested to
740 decrypt locked keys. Make sure nobody is looking over your shoulder
743 Reports a fingerprint (secure hash) on components of requested keys.
744 The following option is supported:
746 .BI "\-f, \-\-filter " filter
747 Specifies a filter. Only keys and key components which match the filter
748 are fingerprinted. The default is to only fingerprint nonsecret
751 .BI "\-a, \-\-algorithm " hash
752 Names the hashing algorithm. Run
754 for a list of hashing algorithms. The default is
757 The keys to be fingerprinted are named by their tags or keyids given as
758 command line arguments. If no key tags are given, all keys which match
759 the filter are fingerprinted. See
761 for a description of how key fingerprints are computed.
763 Simply reads the keyring from file and writes it back again. This has
764 the effect of removing any deleted keys from the file.
766 Writes a selection of keys to a file. An option is supported:
768 .BI "\-f, \-\-filter " filter
769 Specifies a filter. Only keys and key components which match the filter
772 Keys extracted are written to the file named by the first argument,
775 to designate standard output. The keys to extract are listed by their
776 tags; if no tags are given, all keys which match the filter are
777 extracted. The output is a valid keyring file.
779 Merges the keys from the named
783 to designate standard input, with the keyring. Keys already in the
784 keyring are not overwritten: you must explicitly remove them first if
785 you want them to be replaced during the merge.
789 Mark Wooding, <mdw@nsict.org>