31 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
33 key \- simple key management system
141 command performs useful operations on Catacomb keyring files. It
142 provides a number of subcommands, by which the various operations may be
145 Before the command name,
147 may be given. The following global options are supported:
149 .BR "\-h, \-\-help " [ \fIcommand ...]
150 Writes a brief summary of
152 various options to standard output, and
153 returns a successful exit status. With command names, gives help on
156 .B "\-v, \-\-version"
157 Writes the program's version number to standard output, and returns a
158 successful exit status.
161 Writes a very terse command line summary to standard output, and returns
162 a successful exit status.
164 .BI "\-k, \-\-keyring " file
165 Names the keyring file which
167 is to process. The default keyring, used if this option doesn't specify
168 one, is the file named
170 in the current directory. The keyring must be stored in a regular file:
171 pipes, sockets, devices etc. are not allowed.
174 program attempts to lock the keyring before accessing it, using
176 locking. It will however time out after a short while (10 seconds) and
179 In addition to the actual key data itself, a Catacomb key has a number
180 of other pieces of information attached to it:
183 Every key has a 32-bit identifying number, written in hexadecimal.
184 Keyids are not actually related to the key contents: they're generated
185 randomly. Applications use keyids to refer to specific keys; users are
186 probably better off with tags and types. A
188 key cannot be looked up by keyid.
191 A key's tag is a unique string which can be used by users and
192 applications to identify the key. Tag strings may not contain spaces,
195 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
196 keyid or key type string can be given instead.
199 A key's type string describes what the key may be used for. The type
200 string is arbitrary, except that it may not contain whitespace
201 characters, dots or colons. Applications use key types to obtain an
202 arbitrary but suitable key for some purpose. An
204 key cannot be looked up by type, but may be looked up by keyid or tag.
207 There are a number of different ways in which keys can be represented,
208 according to the uses to which the key will be put. Most symmetric
211 keys. Keys used with number-theoretic systems (like most common
212 public-key systems) use
213 .I "multiprecision integer"
214 keys. Elliptic curve systems use
216 keys, which are either a pair of integers representing field elements,
217 or a `point at infinity'. Algorithms which require several key
218 constituents (again, like most public-key systems) use
220 keys, which consist of a collection of named parts. It's possible to
223 as a key, though this is usually done as a component of a structured
224 key. Finally, keys (including structured keys) can be encrypted.
227 Keys and key components may be selected by a filter expression, a
228 sequence of flag names separated by commas. Flags are:
236 (describing the key encoding);
242 (describing the category of key);
246 (whether the key should be erased from memory after use); and
250 (whether the key is safe to divulge).
253 A key component may be identified by the key's tag (or keyid, or type).
254 Subcomponents of structured keys are identified by following the tag by
255 a dot and the name of the subcomponent.
258 Most keys expire after a certain amount of time. Once a key has
259 expired, it will no longer be chosen as a result of a lookup by key
260 type. However, it is not deleted until its deletion time is also
264 A key's deletion time is the latest expiry time of any of the objects
265 which require that key. For example, a key used for authenticating
266 cryptographic cookies should have its deletion time set to the longest
267 expiry time of any of the cookies it can authenticate. Once a key's
268 deletion time is passed, it can no longer be referred to by
269 applications, and will be removed from the keyring next time it's
273 A key may be given a comment when it's created. The comment is for the
274 benefit of users, and isn't interpreted by applications at all.
278 A key as zero or more name/value pairs. The names and values are
279 arbitrary strings, except they may not contain null bytes. Some
280 attributes may have meaning for particular applications or key types;
281 others may be assigned global meanings in future.
282 .SH "COMMAND REFERENCE"
286 command behaves exactly as the
288 option. With no arguments, it shows an overview of
290 options; with arguments, it describes the named subcommands.
294 command prints various lists of tokens understood by
296 With no arguments, it prints all of the lists; with arguments, it prints
297 just the named lists, in order. The recognized lists can be enumerated
302 command. The lists are as follows.
305 The lists which can be enumerated by the
310 The hash functions which can be used with the
317 The built-in elliptic curves which can be used with the
322 The built-in Diffie-Hellman groups which can be used with the
327 The key-generation algorithms which are acceptable to the
334 The pseudorandom generators which are acceptable to the
342 command creates a new key and adds it to the keyring. The command
343 accepts the following options:
345 .BI "\-a, \-\-algorithm " alg
346 Selects a key generation algorithm. The default algorithm is
348 the different algorithms are described below. The command
350 lists the recognized key-generation algorithms.
352 .BI "\-b, \-\-bits " bits
353 The length of the key to generate, in bits. The default, if this option
354 is not supplied, depends on the key-generation algorithm.
356 .BI "\-B, \-\-qbits " bits
357 The length of the subsidiary key or parameter, in bits. Not all
358 key-generation algorithms have a subsidiary key size.
360 .BI "\-p, \-\-parameters " tag
361 Selects a key containing parameter values to copy. Not all
362 key-generation algorithms allow the use of shared parameters. A new key
363 also inherits attributes from its parameter key.
365 .BI "\-A, \-\-seedalg " seed-alg
366 Use the deterministic random number generator algorithm
368 to generate the key. Use
374 options; without one of these,
376 has no effect. The default algorithm is
380 shows a list of recognized seeding algorithms. The seeding algorithm
381 used to generate a key is recorded as the key's
385 .BI "\-s, \-\-seed " seed
386 Generate the key deterministically using the given
388 which should be a Base64-encoded binary string. This is mainly useful
389 for parameters keys (types
393 to demonstrate that a set of parameters has been generated in an honest
396 generation algorithm can be used to generate
398 keys as required by FIPS186. The requested seed is recorded,
399 Base64-encoded, as the new key's
403 .BI "\-n, \-\-newseed " bits
404 Generate a new seed, with the given length in
406 The generated seed is recorded, Base64-encoded, as the new key's
410 .BI "\-e, \-\-expire " expire
411 The expiry date for the generated key. This may be the string
413 if the key should never expire automatically, or any date acceptable to
416 library function. Briefly,
418 understands absolute dates such as
421 .RB ` "August 2nd, 1999" ',
422 and (perhaps more usefully) relative dates such as
424 The default is to allow a 2 week expiry, which isn't useful.
426 .BI "\-c, \-\-comment " comment
427 Sets a comment for the key. The default is not to attach a comment.
429 .BI "\-C, \-\-curve " curve-spec
430 Use the elliptic curve described by
432 when generating elliptic curve parameters.
434 .BI "\-t, \-\-tag " tag
435 Selects a tag string for the key. The default is not to set a tag. It
436 is an error to select a tag which already exists.
441 option is given, remove this tag from any key which already has it.
443 .BI "\-R, \-\-rand-id " tag
444 Selects the key to use for the random number generator. Catacomb's
445 random number generator can be
447 so that, even if the inputs to the generator are compromised, knowledge
448 of the key is also necessary to be able to predict the output. By
449 default, the latest-expiring key with type
451 is used, if present; if not, no key is used.
454 Requests that the secret parts of the newly-generated key be encrypted
458 Suppresses the progress indication which is usually generated while
459 time-consuming key generation tasks are being performed.
462 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
463 rather than a random (or safe) prime. See the details on Diffie-Hellman
464 key generation below.
466 .BI "\-S, --subgroup"
467 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
468 generator of a prime-order subgroup rather than a subgroup of order
471 The key's type is given by the required
473 argument. Following the type are zero or more attributes, which are
474 attached to the key in the same way as for the
478 The key-generation algorithms supported are as follows:
481 Generates a plain binary key of the requested length. If the requested
482 key length is not a multiple of eight, the high-order bits of the first
483 octet of the key are zeroed. The default key length is 128 bits.
486 Generates a DES key, with parity bits. The key length must be 56, 112
487 or 168; the default is 56. The low-order bit of each octet is ignored by
488 the DES algorithm; it is used to give each octet odd parity.
491 Generates a public/private key pair for use with the RSA algorithm.
493 The key components are
497 a pair of prime numbers;
506 the private exponent, chosen such that
509 .RI ( p \ \-\ 1)( q \ \-\ 1));
510 and some other values useful for optimizing private-key operations:
511 .IR q \*(ss\-1\*(se\ mod\ p ,
512 .IR d \ mod\ p \ \-\ 1,
514 .IR d \ mod\ q \ \-\ 1.
519 constitute the public key; the rest must be kept secret. The key size
522 option determines the size of the modulus
524 the default is 1024 bits.
526 The key generation algorithm chooses
536 have large prime factors \- call them
542 also has a large prime factor;
544 has similar properties.
548 cannot be sensibly used as a shared parameter, since knowledge of
549 corrssponding public and private exponents is sufficient to be able to
550 factor the modulus and recover other users' private keys.
553 Generates parameters for use with the Diffie-Hellman key exchange
554 protocol, and many related systems, such as ElGamal encryption and
555 signatures, and even DSA. (The separate DSA algorithm uses the
556 generator described in FIPS186-1.)
558 The Diffie-Hellman parameters are a prime modulus
569 option controls the size of the modulus
571 the default size is 1024 bits.
575 size is selected using the
577 option and the Lim-Lee prime option is disabled, then
579 is chosen to be a `safe' prime (i.e.,
580 .IR p \ =\ 2 q \ +\ 1,
583 prime). Finding safe primes takes a very long time. In this case, the
588 If a size is chosen for
590 and Lim-Lee primes are not selected then the prime
601 option was given Lim-Lee primes are selected: the parameters are chosen
603 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
606 are primes at least as large as the setting given by the
608 option (or 256 bits, if no setting was given).
612 option was given, the generator
614 is chosen to generate the subgroup of order
618 will generate the group of order
619 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
623 option can be given, in which case the parameters are taken directly
624 from the provided group specification, which may either be the the name
625 of one of the built-in groups (say
627 for a list) or a triple
629 separated by commas. No random generation is done in this case: the
630 given parameters are simply stored.
633 Generates a public/private key pair for use with offline Diffie-Hellman,
634 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
637 and computes the public key
638 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
641 Generates parameters for the DSA algorithm. DSA parameters are also
642 suitable for use with Diffie-Hellman and ElGamal system.
644 The main difference between DSA and Diffie-Hellman parameter generation
645 is thatthe DSA parameter generation
648 from which the parameters are derived, and, assuming that the SHA-1 hash
649 function is strong, it's not feasible to construct a seed from which
650 deliberately weak parameters are derived. The algorithm used is the one
651 described in the DSA standard, FIPS\ 186, extended only to allow
652 sequential search for a prime
654 and to allow arbitrary parameter sizes. The seed is stored,
655 Base64-encoded, as the value of the attribute
658 The default lengths for
662 are 768 and 160 bits respectively, since the DSA standard specifies that
664 be 160 bits, and the choice of 768 bits for
666 gives commensurate security.
669 Generates a public/private key pair for DSA. As for Diffie-Hellman
673 and computes the public key
674 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
677 Generates a public/private key pair for the Blum-Blum-Shub random-number
678 generator, and the Blum-Goldwasser semantically-secure public-key
681 The key components are prime numbers
685 both congruent to 3 (mod\ 4), and their product
687 The public key is simply the modulus
695 The key-generation algorithm ensures that the two primes
701 (see the discussion of strong primes above, in the section on RSA keys),
706 are relatively prime, giving a maximum possible period length.
708 The key size requested by the
710 option determines the length of the modulus
712 the default length is 1024 bits.
715 Store an elliptic curve specification. If no explicit
719 option) then a curve is chosen whose order is about the size given by the
721 option (default is 256 bits).
725 can be given explicitly (in which case
727 is ignored). It can either be the name of a built-in curve (say
729 for a list of curve names) or a full specification. The curve is
730 checked for correctness and security according to the SEC1
731 specification: failed checks cause a warning to be issued to standard
732 error (though the program continues anyway). The check can be
737 A curve specification consists of the following elements optionally
738 separated by whitespace: a
754 and the representation of the normal element \*(*b; an optional
764 (the `proj' types currently have much better performance);
767 the two field-element parameters
771 which define the elliptic curve
773 separated by an optional
781 of the generator point
783 separated by an optional
789 of the group generated by
800 Generate a private scalar and a corresponding public point on an
803 above for how to specify elliptic curve parameter sets. The scalar
805 is chosen unformly between 0 and the curve order
807 the public point is then
812 Forces keys to immediately expire. An expired key is not chosen when a
813 program requests a key by its type. The keys to expire are listed by
817 Deletes keys immediately. The keys to delete are listed by their
819 Be careful when deleting keys. It might be a better idea
820 to expire keys rather than deleting them.
822 Sets, deletes or changes the tag attached to a key. The first tag or
823 keyid names the key to be modified; the second, if present specifies the
824 new tag to be set. If no second argument is given, the existing tag, if
825 any, is removed and no new tag is set. It is an error to set a tag
826 which already exists on another key, unless you give the
828 option, which removes the tag first.
830 Attaches attributes to a key. The key to which the attributes should be
831 attached is given by its
833 Each attribute has the form
835 An attribute can be deleted by assigning it an empty value. Although
836 the keyring file format is capable of representing an attribute with an
837 empty value as distinct from a nonexistant attribute, this interface
838 does not allow empty attributes to be set.
840 Sets, deletes or changes the comment attached to a key. The first
841 argument is a key tag or keyid which names the key to be modified; the
842 second, if present, is the new comment. If no second argument is given,
843 the existing comment, if any, is removed, and no new comment is set.
845 Locks a key or key component using a passphrase. If the key is already
846 locked, the existing passphrase is requested, and a new passphrase is
849 Unlocks a passphrase-locked key or key component. If the key is not
850 locked, an error is reported.
852 Lists the keys in the keyring. A couple of options are supported:
854 .B "\-v, \-\-verbose"
855 Increases the amount of information displayed for each key. Repeat for
859 Decreases the amount of information displayed for each key. Each use
865 Display key expiry times as UTC rather than using the local time zone.
867 .BI "\-f, \-\-filter " filter
868 Specifies a filter. Only keys and key components which match the filter
871 By default, a single line of output is generated for each, showing
872 keyids, types, expiry and deletion dates, and comments. Additional
874 options show more information, such as the exact time of day for expiry
875 and deletion, key attributes, and a dump of the actual key data. If the
876 verbosity level is sufficiently high, passphrases are requested to
877 decrypt locked keys. Make sure nobody is looking over your shoulder
880 Reports a fingerprint (secure hash) on components of requested keys.
881 The following options are supported:
883 .BI "\-f, \-\-filter " filter
884 Specifies a filter. Only keys and key components which match the filter
885 are fingerprinted. The default is to only fingerprint nonsecret
888 .BI "\-a, \-\-algorithm " hash
889 Names the hashing algorithm. Run
891 for a list of hashing algorithms. The default is
894 The keys to be fingerprinted are named by their tags or keyids given as
895 command line arguments. If no key tags are given, all keys which match
896 the filter are fingerprinted. See
898 for a description of how key fingerprints are computed.
900 Check a key's fingerprint against a reference copy. The following
901 options are supported:
903 .BI "\-f, \-\-filter " filter
904 Specifies a filter. Only key components which match the filter are
905 hashed. The default is to only fingerprint nonsecret components. An
906 error is reported if no part of the key matches.
908 .BI "\-a, \-\-algorithm " hash
909 Names the hashing algorithm. Run
911 for a list of hashing algorithms. The default is
914 The reference fingerprint is given as hex, in upper or lower case. The
915 hash may contain hyphens, colons and whitespace. Other characters are
918 Simply reads the keyring from file and writes it back again. This has
919 the effect of removing any deleted keys from the file.
921 Writes a selection of keys to a file. An option is supported:
923 .BI "\-f, \-\-filter " filter
924 Specifies a filter. Only keys and key components which match the filter
927 Keys extracted are written to the file named by the first argument,
930 to designate standard output. The keys to extract are listed by their
931 tags; if no tags are given, all keys which match the filter are
932 extracted. The output is a valid keyring file.
934 Merges the keys from the named
938 to designate standard input, with the keyring. Keys already in the
939 keyring are not overwritten: you must explicitly remove them first if
940 you want them to be replaced during the merge.
944 Mark Wooding, <mdw@nsict.org>