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.
465 .BI "\-L, \-\-lim-lee"
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.
471 When generating Diffie-Hellman parameters, generate a KCDSA-style
472 Lim-Lee prime rather than a random (or safe) prime. See the details on
473 Diffie-Hellman key generation below.
475 .BI "\-S, \-\-subgroup"
476 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
477 generator of a prime-order subgroup rather than a subgroup of order
480 The key's type is given by the required
482 argument. Following the type are zero or more attributes, which are
483 attached to the key in the same way as for the
487 The key-generation algorithms supported are as follows:
490 Generates a plain binary key of the requested length. If the requested
491 key length is not a multiple of eight, the high-order bits of the first
492 octet of the key are zeroed. The default key length is 128 bits.
495 Generates a DES key, with parity bits. The key length must be 56, 112
496 or 168; the default is 56. The low-order bit of each octet is ignored by
497 the DES algorithm; it is used to give each octet odd parity.
500 Generates a public/private key pair for use with the RSA algorithm.
502 The key components are
506 a pair of prime numbers;
515 the private exponent, chosen such that
518 .RI ( p \ \-\ 1)( q \ \-\ 1));
519 and some other values useful for optimizing private-key operations:
520 .IR q \*(ss\-1\*(se\ mod\ p ,
521 .IR d \ mod\ p \ \-\ 1,
523 .IR d \ mod\ q \ \-\ 1.
528 constitute the public key; the rest must be kept secret. The key size
531 option determines the size of the modulus
533 the default is 1024 bits.
535 The key generation algorithm chooses
545 have large prime factors \- call them
551 also has a large prime factor;
553 has similar properties.
557 cannot be sensibly used as a shared parameter, since knowledge of
558 corrssponding public and private exponents is sufficient to be able to
559 factor the modulus and recover other users' private keys.
562 Generates parameters for use with the Diffie-Hellman key exchange
563 protocol, and many related systems, such as ElGamal encryption and
564 signatures, and even DSA. (The separate DSA algorithm uses the
565 generator described in FIPS186-1.)
567 The Diffie-Hellman parameters are a prime modulus
578 option controls the size of the modulus
580 the default size is 1024 bits.
584 size is selected using the
586 option and the Lim-Lee prime options are disabled, then
588 is chosen to be a `safe' prime (i.e.,
589 .IR p \ =\ 2 q \ +\ 1,
592 prime). Finding safe primes takes a very long time. In this case, the
597 If a size is chosen for
599 and Lim-Lee primes are not selected then the prime
610 option was given, Lim-Lee primes are selected: the parameters are chosen
612 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
615 are primes at least as large as the setting given by the
617 option (or 256 bits, if no setting was given).
621 option was given, KCDSA-style Lim-Lee primes are selected: the
622 parameters are chosen such that
623 .IR p \ =\ 2\ q\ v \ +\ 1,
635 options were given, the generator
637 is chosen to generate the subgroup of order
641 will generate the group of order
642 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
646 option can be given, in which case the parameters are taken directly
647 from the provided group specification, which may either be the the name
648 of one of the built-in groups (say
650 for a list) or a triple
652 separated by commas. No random generation is done in this case: the
653 given parameters are simply stored.
656 Generates a public/private key pair for use with offline Diffie-Hellman,
657 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
660 and computes the public key
661 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
664 Generates parameters for the DSA algorithm. DSA parameters are also
665 suitable for use with Diffie-Hellman and ElGamal system.
667 The main difference between DSA and Diffie-Hellman parameter generation
668 is thatthe DSA parameter generation
671 from which the parameters are derived, and, assuming that the SHA-1 hash
672 function is strong, it's not feasible to construct a seed from which
673 deliberately weak parameters are derived. The algorithm used is the one
674 described in the DSA standard, FIPS\ 186, extended only to allow
675 sequential search for a prime
677 and to allow arbitrary parameter sizes. The seed is stored,
678 Base64-encoded, as the value of the attribute
681 The default lengths for
685 are 768 and 160 bits respectively, since the DSA standard specifies that
687 be 160 bits, and the choice of 768 bits for
689 gives commensurate security.
692 Generates a public/private key pair for DSA. As for Diffie-Hellman
696 and computes the public key
697 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
700 Generates a public/private key pair for the Blum-Blum-Shub random-number
701 generator, and the Blum-Goldwasser semantically-secure public-key
704 The key components are prime numbers
708 both congruent to 3 (mod\ 4), and their product
710 The public key is simply the modulus
718 The key-generation algorithm ensures that the two primes
724 (see the discussion of strong primes above, in the section on RSA keys),
729 are relatively prime, giving a maximum possible period length.
731 The key size requested by the
733 option determines the length of the modulus
735 the default length is 1024 bits.
738 Store an elliptic curve specification. If no explicit
742 option) then a curve is chosen whose order is about the size given by the
744 option (default is 256 bits).
748 can be given explicitly (in which case
750 is ignored). It can either be the name of a built-in curve (say
752 for a list of curve names) or a full specification. The curve is
753 checked for correctness and security according to the SEC1
754 specification: failed checks cause a warning to be issued to standard
755 error (though the program continues anyway). The check can be
760 A curve specification consists of the following elements optionally
761 separated by whitespace: a
777 and the representation of the normal element \*(*b; an optional
787 (the `proj' types currently have much better performance);
790 the two field-element parameters
794 which define the elliptic curve
796 separated by an optional
804 of the generator point
806 separated by an optional
812 of the group generated by
823 Generate a private scalar and a corresponding public point on an
826 above for how to specify elliptic curve parameter sets. The scalar
828 is chosen unformly between 0 and the curve order
830 the public point is then
835 Forces keys to immediately expire. An expired key is not chosen when a
836 program requests a key by its type. The keys to expire are listed by
840 Deletes keys immediately. The keys to delete are listed by their
842 Be careful when deleting keys. It might be a better idea
843 to expire keys rather than deleting them.
845 Sets, deletes or changes the tag attached to a key. The first tag or
846 keyid names the key to be modified; the second, if present specifies the
847 new tag to be set. If no second argument is given, the existing tag, if
848 any, is removed and no new tag is set. It is an error to set a tag
849 which already exists on another key, unless you give the
851 option, which removes the tag first.
853 Attaches attributes to a key. The key to which the attributes should be
854 attached is given by its
856 Each attribute has the form
858 An attribute can be deleted by assigning it an empty value. Although
859 the keyring file format is capable of representing an attribute with an
860 empty value as distinct from a nonexistant attribute, this interface
861 does not allow empty attributes to be set.
863 Fetches a single attribute of a key. The key whose attribute is to be
866 The attribute's value is written to standard output followed by a
867 newline. If the key or attribute is absent, a message is written to
868 standard error and the program exits nonzero.
870 Sets, deletes or changes the comment attached to a key. The first
871 argument is a key tag or keyid which names the key to be modified; the
872 second, if present, is the new comment. If no second argument is given,
873 the existing comment, if any, is removed, and no new comment is set.
875 Locks a key or key component using a passphrase. If the key is already
876 locked, the existing passphrase is requested, and a new passphrase is
879 Unlocks a passphrase-locked key or key component. If the key is not
880 locked, an error is reported.
882 Lists the keys in the keyring. A couple of options are supported:
884 .B "\-v, \-\-verbose"
885 Increases the amount of information displayed for each key. Repeat for
889 Decreases the amount of information displayed for each key. Each use
895 Display key expiry times as UTC rather than using the local time zone.
897 .BI "\-f, \-\-filter " filter
898 Specifies a filter. Only keys and key components which match the filter
901 By default, a single line of output is generated for each, showing
902 keyids, types, expiry and deletion dates, and comments. Additional
904 options show more information, such as the exact time of day for expiry
905 and deletion, key attributes, and a dump of the actual key data. If the
906 verbosity level is sufficiently high, passphrases are requested to
907 decrypt locked keys. Make sure nobody is looking over your shoulder
910 Reports a fingerprint (secure hash) on components of requested keys.
911 The following options are supported:
913 .BI "\-f, \-\-filter " filter
914 Specifies a filter. Only keys and key components which match the filter
915 are fingerprinted. The default is to only fingerprint nonsecret
918 .BI "\-a, \-\-algorithm " hash
919 Names the hashing algorithm. Run
921 for a list of hashing algorithms. The default is
924 The keys to be fingerprinted are named by their tags or keyids given as
925 command line arguments. If no key tags are given, all keys which match
926 the filter are fingerprinted. See
928 for a description of how key fingerprints are computed.
930 Check a key's fingerprint against a reference copy. The following
931 options are supported:
933 .BI "\-f, \-\-filter " filter
934 Specifies a filter. Only key components which match the filter are
935 hashed. The default is to only fingerprint nonsecret components. An
936 error is reported if no part of the key matches.
938 .BI "\-a, \-\-algorithm " hash
939 Names the hashing algorithm. Run
941 for a list of hashing algorithms. The default is
944 The reference fingerprint is given as hex, in upper or lower case. The
945 hash may contain hyphens, colons and whitespace. Other characters are
948 Simply reads the keyring from file and writes it back again. This has
949 the effect of removing any deleted keys from the file.
951 Writes a selection of keys to a file. An option is supported:
953 .BI "\-f, \-\-filter " filter
954 Specifies a filter. Only keys and key components which match the filter
957 Keys extracted are written to the file named by the first argument,
960 to designate standard output. The keys to extract are listed by their
961 tags; if no tags are given, all keys which match the filter are
962 extracted. The output is a valid keyring file.
964 Merges the keys from the named
968 to designate standard input, with the keyring. Keys already in the
969 keyring are not overwritten: you must explicitly remove them first if
970 you want them to be replaced during the merge.
974 Mark Wooding, <mdw@distorted.org.uk>