31 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
33 key \- simple key management system
133 command performs useful operations on Catacomb keyring files. It
134 provides a number of subcommands, by which the various operations may be
137 Before the command name,
139 may be given. The following global options are supported:
141 .BR "\-h, \-\-help " [ \fIcommand ...]
142 Writes a brief summary of
144 various options to standard output, and
145 returns a successful exit status. With command names, gives help on
148 .B "\-v, \-\-version"
149 Writes the program's version number to standard output, and returns a
150 successful exit status.
153 Writes a very terse command line summary to standard output, and returns
154 a successful exit status.
156 .BI "\-k, \-\-keyring " file
157 Names the keyring file which
159 is to process. The default keyring, used if this option doesn't specify
160 one, is the file named
162 in the current directory. The keyring must be stored in a regular file:
163 pipes, sockets, devices etc. are not allowed.
166 program attempts to lock the keyring before accessing it, using
168 locking. It will however time out after a short while (10 seconds) and
171 In addition to the actual key data itself, a Catacomb key has a number
172 of other pieces of information attached to it:
175 Every key has a 32-bit identifying number, written in hexadecimal.
176 Keyids are not actually related to the key contents: they're generated
177 randomly. Applications use keyids to refer to specific keys; users are
178 probably better off with tags and types. A
180 key cannot be looked up by keyid.
183 A key's tag is a unique string which can be used by users and
184 applications to identify the key. Tag strings may not contain spaces,
187 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
188 keyid or key type string can be given instead.
191 A key's type string describes what the key may be used for. The type
192 string is arbitrary, except that it may not contain whitespace
193 characters, dots or colons. Applications use key types to obtain an
194 arbitrary but suitable key for some purpose. An
196 key cannot be looked up by type, but may be looked up by keyid or tag.
199 There are a number of different ways in which keys can be represented,
200 according to the uses to which the key will be put. Most symmetric
203 keys. Keys used with number-theoretic systems (like most common
204 public-key systems) use
205 .I "multiprecision integer"
206 keys. Elliptic curve systems use
208 keys, which are either a pair of integers representing field elements,
209 or a `point at infinity'. Algorithms which require several key
210 constituents (again, like most public-key systems) use
212 keys, which consist of a collection of named parts. It's possible to
215 as a key, though this is usually done as a component of a structured
216 key. Finally, keys (including structured keys) can be encrypted.
219 Keys and key components may be selected by a filter expression, a
220 sequence of flag names separated by commas. Flags are:
228 (describing the key encoding);
234 (describing the category of key);
238 (whether the key should be erased from memory after use); and
242 (whether the key is safe to divulge).
245 A key component may be identified by the key's tag (or keyid, or type).
246 Subcomponents of structured keys are identified by following the tag by
247 a dot and the name of the subcomponent.
250 Most keys expire after a certain amount of time. Once a key has
251 expired, it will no longer be chosen as a result of a lookup by key
252 type. However, it is not deleted until its deletion time is also
256 A key's deletion time is the latest expiry time of any of the objects
257 which require that key. For example, a key used for authenticating
258 cryptographic cookies should have its deletion time set to the longest
259 expiry time of any of the cookies it can authenticate. Once a key's
260 deletion time is passed, it can no longer be referred to by
261 applications, and will be removed from the keyring next time it's
265 A key may be given a comment when it's created. The comment is for the
266 benefit of users, and isn't interpreted by applications at all.
270 A key as zero or more name/value pairs. The names and values are
271 arbitrary strings, except they may not contain null bytes. Some
272 attributes may have meaning for particular applications or key types;
273 others may be assigned global meanings in future.
274 .SH "COMMAND REFERENCE"
278 command behaves exactly as the
280 option. With no arguments, it shows an overview of
282 options; with arguments, it describes the named subcommands.
286 command prints various lists of tokens understood by
288 With no arguments, it prints all of the lists; with arguments, it prints
289 just the named lists, in order. The recognized lists can be enumerated
294 command. The lists are as follows.
297 The lists which can be enumerated by the
302 The hash functions which can be used with the
307 The built-in elliptic curves which can be used with the
312 The built-in Diffie-Hellman groups which can be used with the
317 The key-generation algorithms which are acceptable to the
324 The pseudorandom generators which are acceptable to the
332 command creates a new key and adds it to the keyring. The command
333 accepts the following options:
335 .BI "\-a, \-\-algorithm " alg
336 Selects a key generation algorithm. The default algorithm is
338 the different algorithms are described below. The command
340 lists the recognized key-generation algorithms.
342 .BI "\-b, \-\-bits " bits
343 The length of the key to generate, in bits. The default, if this option
344 is not supplied, depends on the key-generation algorithm.
346 .BI "\-B, \-\-qbits " bits
347 The length of the subsidiary key or parameter, in bits. Not all
348 key-generation algorithms have a subsidiary key size.
350 .BI "\-p, \-\-parameters " tag
351 Selects a key containing parameter values to copy. Not all
352 key-generation algorithms allow the use of shared parameters. A new key
353 also inherits attributes from its parameter key.
355 .BI "\-A, \-\-seedalg " seed-alg
356 Use the deterministic random number generator algorithm
358 to generate the key. Use
364 options; without one of these,
366 has no effect. The default algorithm is
370 shows a list of recognized seeding algorithms. The seeding algorithm
371 used to generate a key is recorded as the key's
375 .BI "\-s, \-\-seed " seed
376 Generate the key deterministically using the given
378 which should be a Base64-encoded binary string. This is mainly useful
379 for parameters keys (types
383 to demonstrate that a set of parameters has been generated in an honest
386 generation algorithm can be used to generate
388 keys as required by FIPS186. The requested seed is recorded,
389 Base64-encoded, as the new key's
393 .BI "\-n, \-\-newseed " bits
394 Generate a new seed, with the given length in
396 The generated seed is recorded, Base64-encoded, as the new key's
400 .BI "\-e, \-\-expire " expire
401 The expiry date for the generated key. This may be the string
403 if the key should never expire automatically, or any date acceptable to
406 library function. Briefly,
408 understands absolute dates such as
411 .RB ` "August 2nd, 1999" ',
412 and (perhaps more usefully) relative dates such as
414 The default is to allow a 2 week expiry, which isn't useful.
416 .BI "\-c, \-\-comment " comment
417 Sets a comment for the key. The default is not to attach a comment.
419 .BI "\-C, \-\-curve " curve-spec
420 Use the elliptic curve described by
422 when generating elliptic curve parameters.
424 .BI "\-t, \-\-tag " tag
425 Selects a tag string for the key. The default is not to set a tag. It
426 is an error to select a tag which already exists.
431 option is given, remove this tag from any key which already has it.
433 .BI "\-R, \-\-rand-id " tag
434 Selects the key to use for the random number generator. Catacomb's
435 random number generator can be
437 so that, even if the inputs to the generator are compromised, knowledge
438 of the key is also necessary to be able to predict the output. By
439 default, the latest-expiring key with type
441 is used, if present; if not, no key is used.
444 Requests that the secret parts of the newly-generated key be encrypted
448 Suppresses the progress indication which is usually generated while
449 time-consuming key generation tasks are being performed.
452 When generating Diffie-Hellman parameters, generate a Lim-Lee prime
453 rather than a random (or safe) prime. See the details on Diffie-Hellman
454 key generation below.
456 .BI "\-S, --subgroup"
457 When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
458 generator of a prime-order subgroup rather than a subgroup of order
461 The key's type is given by the required
463 argument. Following the type are zero or more attributes, which are
464 attached to the key in the same way as for the
468 The key-generation algorithms supported are as follows:
471 Generates a plain binary key of the requested length. If the requested
472 key length is not a multiple of eight, the high-order bits of the first
473 octet of the key are zeroed. The default key length is 128 bits.
476 Generates a DES key, with parity bits. The key length must be 56, 112
477 or 168; the default is 56. The low-order bit of each octet is ignored by
478 the DES algorithm; it is used to give each octet odd parity.
481 Generates a public/private key pair for use with the RSA algorithm.
483 The key components are
487 a pair of prime numbers;
496 the private exponent, chosen such that
499 .RI ( p \ \-\ 1)( q \ \-\ 1));
500 and some other values useful for optimizing private-key operations:
501 .IR q \*(ss\-1\*(se\ mod\ p ,
502 .IR d \ mod\ p \ \-\ 1,
504 .IR d \ mod\ q \ \-\ 1.
509 constitute the public key; the rest must be kept secret. The key size
512 option determines the size of the modulus
514 the default is 1024 bits.
516 The key generation algorithm chooses
526 have large prime factors \- call them
532 also has a large prime factor;
534 has similar properties.
538 cannot be sensibly used as a shared parameter, since knowledge of
539 corrssponding public and private exponents is sufficient to be able to
540 factor the modulus and recover other users' private keys.
543 Generates parameters for use with the Diffie-Hellman key exchange
544 protocol, and many related systems, such as ElGamal encryption and
545 signatures, and even DSA. (The separate DSA algorithm uses the
546 generator described in FIPS186-1.)
548 The Diffie-Hellman parameters are a prime modulus
559 option controls the size of the modulus
561 the default size is 1024 bits.
565 size is selected using the
567 option and the Lim-Lee prime option is disabled, then
569 is chosen to be a `safe' prime (i.e.,
570 .IR p \ =\ 2 q \ +\ 1,
573 prime). Finding safe primes takes a very long time. In this case, the
578 If a size is chosen for
580 and Lim-Lee primes are not selected then the prime
591 option was given Lim-Lee primes are selected: the parameters are chosen
593 .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
596 are primes at least as large as the setting given by the
598 option (or 256 bits, if no setting was given).
602 option was given, the generator
604 is chosen to generate the subgroup of order
608 will generate the group of order
609 .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
613 option can be given, in which case the parameters are taken directly
614 from the provided group specification, which may either be the the name
615 of one of the built-in groups (say
616 .B "key add \-a dh\-param \-C list 42"
617 for a list) or a triple
619 separated by commas. No random generation is done in this case: the
620 given parameters are simply stored.
623 Generates a public/private key pair for use with offline Diffie-Hellman,
624 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
627 and computes the public key
628 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
631 Generates parameters for the DSA algorithm. DSA parameters are also
632 suitable for use with Diffie-Hellman and ElGamal system.
634 The main difference between DSA and Diffie-Hellman parameter generation
635 is thatthe DSA parameter generation
638 from which the parameters are derived, and, assuming that the SHA-1 hash
639 function is strong, it's not feasible to construct a seed from which
640 deliberately weak parameters are derived. The algorithm used is the one
641 described in the DSA standard, FIPS\ 186, extended only to allow
642 sequential search for a prime
644 and to allow arbitrary parameter sizes. The seed is stored,
645 Base64-encoded, as the value of the attribute
648 The default lengths for
652 are 768 and 160 bits respectively, since the DSA standard specifies that
654 be 160 bits, and the choice of 768 bits for
656 gives commensurate security.
659 Generates a public/private key pair for DSA. As for Diffie-Hellman
663 and computes the public key
664 .IR y \ =\ g\*(ssx\*(se \ mod\ p .
667 Generates a public/private key pair for the Blum-Blum-Shub random-number
668 generator, and the Blum-Goldwasser semantically-secure public-key
671 The key components are prime numbers
675 both congruent to 3 (mod\ 4), and their product
677 The public key is simply the modulus
685 The key-generation algorithm ensures that the two primes
691 (see the discussion of strong primes above, in the section on RSA keys),
696 are relatively prime, giving a maximum possible period length.
698 The key size requested by the
700 option determines the length of the modulus
702 the default length is 1024 bits.
705 Store an elliptic curve specification. If no explicit
709 option) then a curve is chosen whose order is about the size given by the
711 option (default is 256 bits).
715 can be given explicitly (in which case
717 is ignored). It can either be the name of a built-in curve (say
718 .B "key add \-a ec\-param \-C list 42"
719 for a list of curve names) or a full specification. The curve is
720 checked for correctness and security according to the SEC1
721 specification: failed checks cause a warning to be issued to standard
722 error (though the program continues anyway). The check can be
727 A curve specification consists of the following elements optionally
728 separated by whitespace: a
744 and the representation of the normal element \*(*b; an optional
754 (the `proj' types currently have much better performance);
757 the two field-element parameters
761 which define the elliptic curve
763 separated by an optional
771 of the generator point
773 separated by an optional
779 of the group generated by
790 Generate a private scalar and a corresponding public point on an
793 above for how to specify elliptic curve parameter sets. The scalar
795 is chosen unformly between 0 and the curve order
797 the public point is then
802 Forces keys to immediately expire. An expired key is not chosen when a
803 program requests a key by its type. The keys to expire are listed by
807 Deletes keys immediately. The keys to delete are listed by their
809 Be careful when deleting keys. It might be a better idea
810 to expire keys rather than deleting them.
812 Sets, deletes or changes the tag attached to a key. The first tag or
813 keyid names the key to be modified; the second, if present specifies the
814 new tag to be set. If no second argument is given, the existing tag, if
815 any, is removed and no new tag is set. It is an error to set a tag
816 which already exists on another key, unless you give the
818 option, which removes the tag first.
820 Attaches attributes to a key. The key to which the attributes should be
821 attached is given by its
823 Each attribute has the form
825 An attribute can be deleted by assigning it an empty value. Although
826 the keyring file format is capable of representing an attribute with an
827 empty value as distinct from a nonexistant attribute, this interface
828 does not allow empty attributes to be set.
830 Sets, deletes or changes the comment attached to a key. The first
831 argument is a key tag or keyid which names the key to be modified; the
832 second, if present, is the new comment. If no second argument is given,
833 the existing comment, if any, is removed, and no new comment is set.
835 Locks a key or key component using a passphrase. If the key is already
836 locked, the existing passphrase is requested, and a new passphrase is
839 Unlocks a passphrase-locked key or key component. If the key is not
840 locked, an error is reported.
842 Lists the keys in the keyring. A couple of options are supported:
844 .B "\-v, \-\-verbose"
845 Increases the amount of information displayed for each key. Repeat for
849 Decreases the amount of information displayed for each key. Each use
855 Display key expiry times as UTC rather than using the local time zone.
857 .BI "\-f, \-\-filter " filter
858 Specifies a filter. Only keys and key components which match the filter
861 By default, a single line of output is generated for each, showing
862 keyids, types, expiry and deletion dates, and comments. Additional
864 options show more information, such as the exact time of day for expiry
865 and deletion, key attributes, and a dump of the actual key data. If the
866 verbosity level is sufficiently high, passphrases are requested to
867 decrypt locked keys. Make sure nobody is looking over your shoulder
870 Reports a fingerprint (secure hash) on components of requested keys.
871 The following option is supported:
873 .BI "\-f, \-\-filter " filter
874 Specifies a filter. Only keys and key components which match the filter
875 are fingerprinted. The default is to only fingerprint nonsecret
878 .BI "\-a, \-\-algorithm " hash
879 Names the hashing algorithm. Run
881 for a list of hashing algorithms. The default is
884 The keys to be fingerprinted are named by their tags or keyids given as
885 command line arguments. If no key tags are given, all keys which match
886 the filter are fingerprinted. See
888 for a description of how key fingerprints are computed.
890 Simply reads the keyring from file and writes it back again. This has
891 the effect of removing any deleted keys from the file.
893 Writes a selection of keys to a file. An option is supported:
895 .BI "\-f, \-\-filter " filter
896 Specifies a filter. Only keys and key components which match the filter
899 Keys extracted are written to the file named by the first argument,
902 to designate standard output. The keys to extract are listed by their
903 tags; if no tags are given, all keys which match the filter are
904 extracted. The output is a valid keyring file.
906 Merges the keys from the named
910 to designate standard input, with the keyring. Keys already in the
911 keyring are not overwritten: you must explicitly remove them first if
912 you want them to be replaced during the merge.
916 Mark Wooding, <mdw@nsict.org>