31 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
33 key \- simple key management system
145 command performs useful operations on Catacomb keyring files. It
146 provides a number of subcommands, by which the various operations may be
149 Before the command name,
151 may be given. The following global options are supported:
153 .BR "\-h, \-\-help " [ \fIcommand ...]
154 Writes a brief summary of
156 various options to standard output, and
157 returns a successful exit status. With command names, gives help on
160 .B "\-v, \-\-version"
161 Writes the program's version number to standard output, and returns a
162 successful exit status.
165 Writes a very terse command line summary to standard output, and returns
166 a successful exit status.
168 .BI "\-k, \-\-keyring " file
169 Names the keyring file which
171 is to process. The default keyring, used if this option doesn't specify
172 one, is the file named
174 in the current directory. The keyring must be stored in a regular file:
175 pipes, sockets, devices etc. are not allowed.
178 program attempts to lock the keyring before accessing it, using
180 locking. It will however time out after a short while (10 seconds) and
183 In addition to the actual key data itself, a Catacomb key has a number
184 of other pieces of information attached to it:
187 Every key has a 32-bit identifying number, written in hexadecimal.
188 Keyids are not actually related to the key contents: they're generated
189 randomly. Applications use keyids to refer to specific keys; users are
190 probably better off with tags and types. A
192 key cannot be looked up by keyid.
195 A key's tag is a unique string which can be used by users and
196 applications to identify the key. Tag strings may not contain spaces,
199 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
200 keyid or key type string can be given instead.
203 A key's type string describes what the key may be used for. The type
204 string is arbitrary, except that it may not contain whitespace
205 characters, dots or colons. Applications use key types to obtain an
206 arbitrary but suitable key for some purpose. An
208 key cannot be looked up by type, but may be looked up by keyid or tag.
211 There are a number of different ways in which keys can be represented,
212 according to the uses to which the key will be put. Most symmetric
215 keys. Keys used with number-theoretic systems (like most common
216 public-key systems) use
217 .I "multiprecision integer"
218 keys. Elliptic curve systems use
220 keys, which are either a pair of integers representing field elements,
221 or a `point at infinity'. Algorithms which require several key
222 constituents (again, like most public-key systems) use
224 keys, which consist of a collection of named parts. It's possible to
227 as a key, though this is usually done as a component of a structured
228 key. Finally, keys (including structured keys) can be encrypted.
231 Keys and key components may be selected by a filter expression, a
232 sequence of flag names separated by commas. Flags are:
240 (describing the key encoding);
246 (describing the category of key);
250 (whether the key should be erased from memory after use); and
254 (whether the key is safe to divulge).
257 A key component may be identified by the key's tag (or keyid, or type).
258 Subcomponents of structured keys are identified by following the tag by
259 a dot and the name of the subcomponent.
262 Most keys expire after a certain amount of time. Once a key has
263 expired, it will no longer be chosen as a result of a lookup by key
264 type. However, it is not deleted until its deletion time is also
268 A key's deletion time is the latest expiry time of any of the objects
269 which require that key. For example, a key used for authenticating
270 cryptographic cookies should have its deletion time set to the longest
271 expiry time of any of the cookies it can authenticate. Once a key's
272 deletion time is passed, it can no longer be referred to by
273 applications, and will be removed from the keyring next time it's
277 A key may be given a comment when it's created. The comment is for the
278 benefit of users, and isn't interpreted by applications at all.
282 A key as zero or more name/value pairs. The names and values are
283 arbitrary strings, except they may not contain null bytes. Some
284 attributes may have meaning for particular applications or key types;
285 others may be assigned global meanings in future.
286 .SH "COMMAND REFERENCE"
290 command behaves exactly as the
292 option. With no arguments, it shows an overview of
294 options; with arguments, it describes the named subcommands.
298 command prints various lists of tokens understood by
300 With no arguments, it prints all of the lists; with arguments, it prints
301 just the named lists, in order. The recognized lists can be enumerated
306 command. The lists are as follows.
309 The lists which can be enumerated by the
314 The hash functions which can be used with the
321 The built-in elliptic curves which can be used with the
326 The built-in Diffie-Hellman groups which can be used with the
331 The key-generation algorithms which are acceptable to the
338 The pseudorandom generators which are acceptable to the
346 command creates a new key and adds it to the keyring. The command
347 accepts the following options:
349 .BI "\-a, \-\-algorithm " alg
350 Selects a key generation algorithm. The default algorithm is
352 the different algorithms are described below. The command
354 lists the recognized key-generation algorithms.
356 .BI "\-b, \-\-bits " bits
357 The length of the key to generate, in bits. The default, if this option
358 is not supplied, depends on the key-generation algorithm.
360 .BI "\-B, \-\-qbits " bits
361 The length of the subsidiary key or parameter, in bits. Not all
362 key-generation algorithms have a subsidiary key size.
364 .BI "\-p, \-\-parameters " tag
365 Selects a key containing parameter values to copy. Not all
366 key-generation algorithms allow the use of shared parameters. A new key
367 also inherits attributes from its parameter key.
369 .BI "\-A, \-\-seedalg " seed-alg
370 Use the deterministic random number generator algorithm
372 to generate the key. Use
378 options; without one of these,
380 has no effect. The default algorithm is
384 shows a list of recognized seeding algorithms. The seeding algorithm
385 used to generate a key is recorded as the key's
389 .BI "\-s, \-\-seed " seed
390 Generate the key deterministically using the given
392 which should be a Base64-encoded binary string. This is mainly useful
393 for parameters keys (types
397 to demonstrate that a set of parameters has been generated in an honest
400 generation algorithm can be used to generate
402 keys as required by FIPS186. The requested seed is recorded,
403 Base64-encoded, as the new key's
407 .BI "\-n, \-\-newseed " bits
408 Generate a new seed, with the given length in
410 The generated seed is recorded, Base64-encoded, as the new key's
414 .BI "\-e, \-\-expire " expire
415 The expiry date for the generated key. This may be the string
417 if the key should never expire automatically, or any date acceptable to
420 library function. Briefly,
422 understands absolute dates such as
425 .RB ` "August 2nd, 1999" ',
426 and (perhaps more usefully) relative dates such as
428 The default is to allow a 2 week expiry, which isn't useful.
430 .BI "\-c, \-\-comment " comment
431 Sets a comment for the key. The default is not to attach a comment.
433 .BI "\-C, \-\-curve " curve-spec
434 Use the elliptic curve described by
436 when generating elliptic curve parameters.
438 .BI "\-t, \-\-tag " tag
439 Selects a tag string for the key. The default is not to set a tag. It
440 is an error to select a tag which already exists.
445 option is given, remove this tag from any key which already has it.
447 .BI "\-R, \-\-rand-id " tag
448 Selects the key to use for the random number generator. Catacomb's
449 random number generator can be
451 so that, even if the inputs to the generator are compromised, knowledge
452 of the key is also necessary to be able to predict the output. By
453 default, the latest-expiring key with type
455 is used, if present; if not, no key is used.
458 Requests that the secret parts of the newly-generated key be encrypted
462 Suppresses the progress indication which is usually generated while
463 time-consuming key generation tasks are being performed.
466 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
467 rather than a random (or safe) prime. See the details on Diffie-Hellman
468 key generation below.
470 .BI "\-S, --subgroup"
471 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
472 generator of a prime-order subgroup rather than a subgroup of order
475 The key's type is given by the required
477 argument. Following the type are zero or more attributes, which are
478 attached to the key in the same way as for the
482 The key-generation algorithms supported are as follows:
485 Generates a plain binary key of the requested length. If the requested
486 key length is not a multiple of eight, the high-order bits of the first
487 octet of the key are zeroed. The default key length is 128 bits.
490 Generates a DES key, with parity bits. The key length must be 56, 112
491 or 168; the default is 56. The low-order bit of each octet is ignored by
492 the DES algorithm; it is used to give each octet odd parity.
495 Generates a public/private key pair for use with the RSA algorithm.
497 The key components are
501 a pair of prime numbers;
510 the private exponent, chosen such that
513 .RI ( p \ \-\ 1)( q \ \-\ 1));
514 and some other values useful for optimizing private-key operations:
515 .IR q \*(ss\-1\*(se\ mod\ p ,
516 .IR d \ mod\ p \ \-\ 1,
518 .IR d \ mod\ q \ \-\ 1.
523 constitute the public key; the rest must be kept secret. The key size
526 option determines the size of the modulus
528 the default is 1024 bits.
530 The key generation algorithm chooses
540 have large prime factors \- call them
546 also has a large prime factor;
548 has similar properties.
552 cannot be sensibly used as a shared parameter, since knowledge of
553 corrssponding public and private exponents is sufficient to be able to
554 factor the modulus and recover other users' private keys.
557 Generates parameters for use with the Diffie-Hellman key exchange
558 protocol, and many related systems, such as ElGamal encryption and
559 signatures, and even DSA. (The separate DSA algorithm uses the
560 generator described in FIPS186-1.)
562 The Diffie-Hellman parameters are a prime modulus
573 option controls the size of the modulus
575 the default size is 1024 bits.
579 size is selected using the
581 option and the Lim-Lee prime option is disabled, then
583 is chosen to be a `safe' prime (i.e.,
584 .IR p \ =\ 2 q \ +\ 1,
587 prime). Finding safe primes takes a very long time. In this case, the
592 If a size is chosen for
594 and Lim-Lee primes are not selected then the prime
605 option was given Lim-Lee primes are selected: the parameters are chosen
607 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
610 are primes at least as large as the setting given by the
612 option (or 256 bits, if no setting was given).
616 option was given, the generator
618 is chosen to generate the subgroup of order
622 will generate the group of order
623 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
627 option can be given, in which case the parameters are taken directly
628 from the provided group specification, which may either be the the name
629 of one of the built-in groups (say
631 for a list) or a triple
633 separated by commas. No random generation is done in this case: the
634 given parameters are simply stored.
637 Generates a public/private key pair for use with offline Diffie-Hellman,
638 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
641 and computes the public key
642 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
645 Generates parameters for the DSA algorithm. DSA parameters are also
646 suitable for use with Diffie-Hellman and ElGamal system.
648 The main difference between DSA and Diffie-Hellman parameter generation
649 is thatthe DSA parameter generation
652 from which the parameters are derived, and, assuming that the SHA-1 hash
653 function is strong, it's not feasible to construct a seed from which
654 deliberately weak parameters are derived. The algorithm used is the one
655 described in the DSA standard, FIPS\ 186, extended only to allow
656 sequential search for a prime
658 and to allow arbitrary parameter sizes. The seed is stored,
659 Base64-encoded, as the value of the attribute
662 The default lengths for
666 are 768 and 160 bits respectively, since the DSA standard specifies that
668 be 160 bits, and the choice of 768 bits for
670 gives commensurate security.
673 Generates a public/private key pair for DSA. As for Diffie-Hellman
677 and computes the public key
678 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
681 Generates a public/private key pair for the Blum-Blum-Shub random-number
682 generator, and the Blum-Goldwasser semantically-secure public-key
685 The key components are prime numbers
689 both congruent to 3 (mod\ 4), and their product
691 The public key is simply the modulus
699 The key-generation algorithm ensures that the two primes
705 (see the discussion of strong primes above, in the section on RSA keys),
710 are relatively prime, giving a maximum possible period length.
712 The key size requested by the
714 option determines the length of the modulus
716 the default length is 1024 bits.
719 Store an elliptic curve specification. If no explicit
723 option) then a curve is chosen whose order is about the size given by the
725 option (default is 256 bits).
729 can be given explicitly (in which case
731 is ignored). It can either be the name of a built-in curve (say
733 for a list of curve names) or a full specification. The curve is
734 checked for correctness and security according to the SEC1
735 specification: failed checks cause a warning to be issued to standard
736 error (though the program continues anyway). The check can be
741 A curve specification consists of the following elements optionally
742 separated by whitespace: a
758 and the representation of the normal element \*(*b; an optional
768 (the `proj' types currently have much better performance);
771 the two field-element parameters
775 which define the elliptic curve
777 separated by an optional
785 of the generator point
787 separated by an optional
793 of the group generated by
804 Generate a private scalar and a corresponding public point on an
807 above for how to specify elliptic curve parameter sets. The scalar
809 is chosen unformly between 0 and the curve order
811 the public point is then
816 Forces keys to immediately expire. An expired key is not chosen when a
817 program requests a key by its type. The keys to expire are listed by
821 Deletes keys immediately. The keys to delete are listed by their
823 Be careful when deleting keys. It might be a better idea
824 to expire keys rather than deleting them.
826 Sets, deletes or changes the tag attached to a key. The first tag or
827 keyid names the key to be modified; the second, if present specifies the
828 new tag to be set. If no second argument is given, the existing tag, if
829 any, is removed and no new tag is set. It is an error to set a tag
830 which already exists on another key, unless you give the
832 option, which removes the tag first.
834 Attaches attributes to a key. The key to which the attributes should be
835 attached is given by its
837 Each attribute has the form
839 An attribute can be deleted by assigning it an empty value. Although
840 the keyring file format is capable of representing an attribute with an
841 empty value as distinct from a nonexistant attribute, this interface
842 does not allow empty attributes to be set.
844 Fetches a single attribute of a key. The key whose attribute is to be
847 The attribute's value is written to standard output followed by a
848 newline. If the key or attribute is absent, a message is written to
849 standard error and the program exits nonzero.
851 Sets, deletes or changes the comment attached to a key. The first
852 argument is a key tag or keyid which names the key to be modified; the
853 second, if present, is the new comment. If no second argument is given,
854 the existing comment, if any, is removed, and no new comment is set.
856 Locks a key or key component using a passphrase. If the key is already
857 locked, the existing passphrase is requested, and a new passphrase is
860 Unlocks a passphrase-locked key or key component. If the key is not
861 locked, an error is reported.
863 Lists the keys in the keyring. A couple of options are supported:
865 .B "\-v, \-\-verbose"
866 Increases the amount of information displayed for each key. Repeat for
870 Decreases the amount of information displayed for each key. Each use
876 Display key expiry times as UTC rather than using the local time zone.
878 .BI "\-f, \-\-filter " filter
879 Specifies a filter. Only keys and key components which match the filter
882 By default, a single line of output is generated for each, showing
883 keyids, types, expiry and deletion dates, and comments. Additional
885 options show more information, such as the exact time of day for expiry
886 and deletion, key attributes, and a dump of the actual key data. If the
887 verbosity level is sufficiently high, passphrases are requested to
888 decrypt locked keys. Make sure nobody is looking over your shoulder
891 Reports a fingerprint (secure hash) on components of requested keys.
892 The following options are supported:
894 .BI "\-f, \-\-filter " filter
895 Specifies a filter. Only keys and key components which match the filter
896 are fingerprinted. The default is to only fingerprint nonsecret
899 .BI "\-a, \-\-algorithm " hash
900 Names the hashing algorithm. Run
902 for a list of hashing algorithms. The default is
905 The keys to be fingerprinted are named by their tags or keyids given as
906 command line arguments. If no key tags are given, all keys which match
907 the filter are fingerprinted. See
909 for a description of how key fingerprints are computed.
911 Check a key's fingerprint against a reference copy. The following
912 options are supported:
914 .BI "\-f, \-\-filter " filter
915 Specifies a filter. Only key components which match the filter are
916 hashed. The default is to only fingerprint nonsecret components. An
917 error is reported if no part of the key matches.
919 .BI "\-a, \-\-algorithm " hash
920 Names the hashing algorithm. Run
922 for a list of hashing algorithms. The default is
925 The reference fingerprint is given as hex, in upper or lower case. The
926 hash may contain hyphens, colons and whitespace. Other characters are
929 Simply reads the keyring from file and writes it back again. This has
930 the effect of removing any deleted keys from the file.
932 Writes a selection of keys to a file. An option is supported:
934 .BI "\-f, \-\-filter " filter
935 Specifies a filter. Only keys and key components which match the filter
938 Keys extracted are written to the file named by the first argument,
941 to designate standard output. The keys to extract are listed by their
942 tags; if no tags are given, all keys which match the filter are
943 extracted. The output is a valid keyring file.
945 Merges the keys from the named
949 to designate standard input, with the keyring. Keys already in the
950 keyring are not overwritten: you must explicitly remove them first if
951 you want them to be replaced during the merge.
955 Mark Wooding, <mdw@distorted.org.uk>