31 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
33 key \- simple key management system
149 command performs useful operations on Catacomb keyring files. It
150 provides a number of subcommands, by which the various operations may be
153 Before the command name,
155 may be given. The following global options are supported:
157 .BR "\-h, \-\-help " [ \fIcommand ...]
158 Writes a brief summary of
160 various options to standard output, and
161 returns a successful exit status. With command names, gives help on
164 .B "\-v, \-\-version"
165 Writes the program's version number to standard output, and returns a
166 successful exit status.
169 Writes a very terse command line summary to standard output, and returns
170 a successful exit status.
172 .BI "\-k, \-\-keyring " file
173 Names the keyring file which
175 is to process. The default keyring, used if this option doesn't specify
176 one, is the file named
178 in the current directory. The keyring must be stored in a regular file:
179 pipes, sockets, devices etc. are not allowed.
182 program attempts to lock the keyring before accessing it, using
184 locking. It will however time out after a short while (10 seconds) and
187 In addition to the actual key data itself, a Catacomb key has a number
188 of other pieces of information attached to it:
191 Every key has a 32-bit identifying number, written in hexadecimal.
192 Keyids are not actually related to the key contents: they're generated
193 randomly. Applications use keyids to refer to specific keys; users are
194 probably better off with tags and types. A
196 key cannot be looked up by keyid.
199 A key's tag is a unique string which can be used by users and
200 applications to identify the key. Tag strings may not contain spaces,
203 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
204 keyid or key type string can be given instead.
207 A key's type string describes what the key may be used for. The type
208 string is arbitrary, except that it may not contain whitespace
209 characters, dots or colons. Applications use key types to obtain an
210 arbitrary but suitable key for some purpose. An
212 key cannot be looked up by type, but may be looked up by keyid or tag.
215 There are a number of different ways in which keys can be represented,
216 according to the uses to which the key will be put. Most symmetric
219 keys. Keys used with number-theoretic systems (like most common
220 public-key systems) use
221 .I "multiprecision integer"
222 keys. Elliptic curve systems use
224 keys, which are either a pair of integers representing field elements,
225 or a `point at infinity'. Algorithms which require several key
226 constituents (again, like most public-key systems) use
228 keys, which consist of a collection of named parts. It's possible to
231 as a key, though this is usually done as a component of a structured
232 key. Finally, keys (including structured keys) can be encrypted.
235 Keys and key components may be selected by a filter expression, a
236 sequence of flag names separated by commas. Flags are:
244 (describing the key encoding);
250 (describing the category of key);
254 (whether the key should be erased from memory after use); and
258 (whether the key is safe to divulge).
261 A key component may be identified by the key's tag (or keyid, or type).
262 Subcomponents of structured keys are identified by following the tag by
263 a dot and the name of the subcomponent.
266 Most keys expire after a certain amount of time. Once a key has
267 expired, it will no longer be chosen as a result of a lookup by key
268 type. However, it is not deleted until its deletion time is also
272 A key's deletion time is the latest expiry time of any of the objects
273 which require that key. For example, a key used for authenticating
274 cryptographic cookies should have its deletion time set to the longest
275 expiry time of any of the cookies it can authenticate. Once a key's
276 deletion time is passed, it can no longer be referred to by
277 applications, and will be removed from the keyring next time it's
281 A key may be given a comment when it's created. The comment is for the
282 benefit of users, and isn't interpreted by applications at all.
286 A key has zero or more name/value pairs. The names and values are
287 arbitrary strings, except that they may not contain null bytes. Some
288 attributes may have meaning for particular applications or key types;
289 others may be assigned global meanings in future.
290 .SH "COMMAND REFERENCE"
294 command behaves exactly as the
296 option. With no arguments, it shows an overview of
298 options; with arguments, it describes the named subcommands.
302 command prints various lists of tokens understood by
304 With no arguments, it prints all of the lists; with arguments, it prints
305 just the named lists, in order. The recognized lists can be enumerated
310 command. The lists are as follows.
313 The lists which can be enumerated by the
318 The hash functions which can be used with the
325 The built-in elliptic curves which can be used with the
330 The built-in Diffie\(enHellman groups which can be used with the
335 The key-generation algorithms which are acceptable to the
342 The pseudorandom generators which are acceptable to the
349 Fingerprint presentation styles, as used by the
357 command creates a new key and adds it to the keyring. The command
358 accepts the following options:
360 .BI "\-a, \-\-algorithm " alg
361 Selects a key generation algorithm. The default algorithm is
363 the different algorithms are described below. The command
365 lists the recognized key-generation algorithms.
367 .BI "\-b, \-\-bits " bits
368 The length of the key to generate, in bits. The default, if this option
369 is not supplied, depends on the key-generation algorithm.
371 .BI "\-B, \-\-qbits " bits
372 The length of the subsidiary key or parameter, in bits. Not all
373 key-generation algorithms have a subsidiary key size.
375 .BI "\-p, \-\-parameters " tag
376 Selects a key containing parameter values to copy.
377 A new key also inherits attributes from its parameter key.
379 .BI "\-A, \-\-seedalg " seed-alg
380 Use the deterministic random number generator algorithm
382 to generate the key. Use
388 options; without one of these,
390 has no effect. The default algorithm is
394 shows a list of recognized seeding algorithms. The seeding algorithm
395 used to generate a key is recorded as the key's
399 .BI "\-s, \-\-seed " seed
400 Generate the key deterministically using the given
402 which should be a Base64-encoded binary string. This is mainly useful
403 for parameters keys (types
407 to demonstrate that a set of parameters has been generated in an honest
410 generation algorithm can be used to generate
412 keys as required by FIPS186. The requested seed is recorded,
413 Base64-encoded, as the new key's
417 .BI "\-n, \-\-newseed " bits
418 Generate a new seed, with the given length in
420 The generated seed is recorded, Base64-encoded, as the new key's
424 .BI "\-e, \-\-expire " expire
425 The expiry date for the generated key. This may be the string
427 if the key should never expire automatically, or any date acceptable to
430 library function. Briefly,
432 understands absolute dates such as
435 .RB ` "August 2nd, 1999" ',
436 and (perhaps more usefully) relative dates such as
438 The default is to allow a 2 week expiry, which isn't useful.
440 .BI "\-c, \-\-comment " comment
441 Sets a comment for the key. The default is not to attach a comment.
443 .BI "\-C, \-\-curve " curve-spec
444 Use the elliptic curve described by
446 when generating elliptic curve parameters.
448 .BI "\-t, \-\-tag " tag
449 Selects a tag string for the key. The default is not to set a tag. It
450 is an error to select a tag which already exists.
455 option is given, remove this tag from any key which already has it.
457 .BI "\-R, \-\-rand-id " tag
458 Selects the key to use for the random number generator. Catacomb's
459 random number generator can be
461 so that, even if the inputs to the generator are compromised, knowledge
462 of the key is also necessary to be able to predict the output. By
463 default, the latest-expiring key with type
465 is used, if present; if not, no key is used.
468 Requests that the secret parts of the newly-generated key be encrypted
472 Suppresses the progress indication which is usually generated while
473 time-consuming key generation tasks are being performed.
475 .BI "\-E, \-\-public-exponent"
476 Set the public exponent for RSA keys.
477 The default is 65537,
478 because this seems to be the overwhelmingly popular choice
480 and because it was the exponent used before this option was introduced.
481 The value 3 is fine unless you use a completely terrible padding scheme.
483 .BI "\-L, \-\-lim-lee"
484 When generating Diffie\(enHellman parameters, generate a Lim\(enLee
485 prime rather than a random (or safe) prime. See the details on
486 Diffie\(enHellman key generation below.
489 When generating Diffie\(enHellman parameters, generate a KCDSA-style
490 Lim\(enLee prime rather than a random (or safe) prime. See the details
491 on Diffie\(enHellman key generation below.
493 .BI "\-S, \-\-subgroup"
494 When generating Diffie\(enHellman parameters with a Lim\(enLee prime,
495 choose a generator of a prime-order subgroup rather than a subgroup of
497 .RI ( p "\ \-\ 1)/2."
499 The key's type is given by the required
501 argument. Following the type are zero or more attributes, which are
502 attached to the key in the same way as for the
506 The key-generation algorithms supported are as follows:
509 Generates a plain binary key of the requested length. If the requested
510 key length is not a multiple of eight, the high-order bits of the first
511 octet of the key are zeroed. The default key length is 128 bits.
514 Generates a DES key, with parity bits. The key length must be 56, 112
515 or 168; the default is 56. The low-order bit of each octet is ignored by
516 the DES algorithm; it is used to give each octet odd parity.
519 Generates a public/private key pair for use with the RSA algorithm.
521 The key components are
525 a pair of prime numbers;
534 the private exponent, chosen such that
537 .RI lcm( p "\~\-\~1, " q \~\-\~1));
538 and some other values useful for optimizing private-key operations:
539 .IR q "\*(ss\-1\*(se mod " p ,
540 .IR d "\~mod " p \~\-\~1,
542 .IR d "\~mod " q \~\-\~1.
547 constitute the public key; the rest must be kept secret. The key size
550 option determines the size of the modulus
552 the default is 1024 bits.
554 The key generation algorithm chooses
564 have large prime factors \(en call them
568 respectively \(en and
570 also has a large prime factor;
572 has similar properties.
576 cannot be sensibly used as a shared parameter, since knowledge of
577 corrssponding public and private exponents is sufficient to be able to
578 factor the modulus and recover other users' private keys.
581 Generates parameters for use with the Diffie\(enHellman key exchange
582 protocol, and many related systems, such as ElGamal encryption and
583 signatures, and even DSA. (The separate DSA algorithm uses the
584 generator described in FIPS186-1.)
586 The Diffie\(enHellman parameters are a prime modulus
597 option controls the size of the modulus
599 the default size is 1024 bits.
603 size is selected using the
605 option and the Lim\(enLee prime options are disabled, then
607 is chosen to be a `safe' prime (i.e.,
608 .IR p "\~= 2" q \~+\~1,
611 prime). Finding safe primes takes a very long time. In this case, the
616 If a size is chosen for
618 and Lim\(enLee primes are not selected then the prime
629 option was given, Lim\(enLee primes are selected: the parameters are
631 .IR p "\~= 2\~" q \*(us0\*(ue
633 .IR q \*(us2\*(ue\~...\~+\~1,
636 are primes at least as large as the setting given by the
638 option (or 256 bits, if no setting was given).
642 option was given, KCDSA-style Lim\(enLee primes are selected: the
643 parameters are chosen such that
644 .IR p "\~= 2" qv \~+\~1,
656 options were given, the generator
658 is chosen to generate the subgroup of order
662 will generate the group of order
663 .RI ( p "\~\-\~1)/2\~= " q "\*(us0\*(ue " q \*(us1\*(ue
664 .IR q \*(us2\*(ue\~...
668 option can be given, in which case the parameters are taken directly
669 from the provided group specification, which may either be the the name
670 of one of the built-in groups (say
672 for a list) or a triple
673 .RI ( p ,\~ q ,\~ g ).
674 separated by commas. No random generation is done in this case: the
675 given parameters are simply stored.
678 Generates a public/private key pair for use with offline Diffie\(enHellman,
679 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
682 and computes the public key
683 .IR y "\~= " g \*(ss x "\*(se mod\~" p .
686 Generates parameters for the DSA algorithm. DSA parameters are also
687 suitable for use with Diffie\(enHellman and ElGamal system.
689 The main difference between DSA and Diffie\(enHellman parameter generation
690 is thatthe DSA parameter generation
693 from which the parameters are derived, and, assuming that the SHA-1 hash
694 function is strong, it's not feasible to construct a seed from which
695 deliberately weak parameters are derived. The algorithm used is the one
696 described in the DSA standard, FIPS\ 186, extended only to allow
697 sequential search for a prime
699 and to allow arbitrary parameter sizes. The seed is stored,
700 Base64-encoded, as the value of the attribute
703 The default lengths for
707 are 768 and 160 bits respectively, since the DSA standard specifies that
709 be 160 bits, and the choice of 768 bits for
711 gives commensurate security.
714 Generates a public/private key pair for DSA. As for Diffie\(enHellman
718 and computes the public key
719 .IR y "\~= " g \*(ss x "\*(se mod\~" p .
722 Generates a public/private key pair for the Blum-Blum-Shub random-number
723 generator, and the Blum-Goldwasser semantically-secure public-key
726 The key components are prime numbers
730 both congruent to 3 (mod\~4), and their product
732 The public key is simply the modulus
740 The key-generation algorithm ensures that the two primes
746 (see the discussion of strong primes above, in the section on RSA keys),
751 are relatively prime, giving a maximum possible period length.
753 The key size requested by the
755 option determines the length of the modulus
757 the default length is 1024 bits.
760 Store an elliptic curve specification. If no explicit
764 option) then a curve is chosen whose order is about the size given by the
766 option (default is 256 bits).
770 can be given explicitly (in which case
772 is ignored). It can either be the name of a built-in curve (say
774 for a list of curve names) or a full specification. The curve is
775 checked for correctness and security according to the SEC1
776 specification: failed checks cause a warning to be issued to standard
777 error (though the program continues anyway). The check can be
782 A curve specification consists of the following elements optionally
783 separated by whitespace: a
799 and the representation of the normal element \*(*b; an optional
809 (the `proj' types currently have much better performance);
812 the two field-element parameters
816 which define the elliptic curve
818 separated by an optional
826 of the generator point
828 separated by an optional
834 of the group generated by
845 Generate a private scalar and a corresponding public point on an
848 above for how to specify elliptic curve parameter sets. The scalar
850 is chosen unformly between 0 and the curve order
852 the public point is then
858 Generate a private scalar and a corresponding public point on the
859 (Montgomery-form) Curve25519 elliptic curve.
860 The scalar is simply a random 256-bit string;
861 the public key is the
863 of the corresponding point.
866 Generate a private scalar and a corresponding public point on the
867 (Montgomery-form) Ed448-Goldilocks elliptic curve.
868 The scalar is simply a random 256-bit string;
869 the public key is the
871 of the corresponding point.
874 Generate a private key and a corresponding public point on the
875 (twisted Edwards-form) Curve25519 elliptic curve.
876 The private key is simply a random 256-bit string,
877 from which a scalar and secret prefix are derived;
878 the public key is the compressed form of the corresponding point.
881 Generate a private key and a corresponding public point on the
882 (Edwards-form) Ed448-Goldilocks elliptic curve.
883 The private key is simply a random 456-bit string,
884 from which a scalar and secret prefix are derived;
885 the public key is the compressed form of the corresponding point.
888 Generate an empty key, with trivial contents.
889 This is useful as a `parameters' key,
890 carrying attributes to be applied to other keys
891 if they don't require more detailed parameters.
893 Forces keys to immediately expire. An expired key is not chosen when a
894 program requests a key by its type. The keys to expire are listed by
898 Deletes keys immediately. The keys to delete are listed by their
900 Be careful when deleting keys. It might be a better idea
901 to expire keys rather than deleting them.
903 Sets, deletes or changes the tag attached to a key. The first tag or
904 keyid names the key to be modified; the second, if present specifies the
905 new tag to be set. If no second argument is given, the existing tag, if
906 any, is removed and no new tag is set. It is an error to set a tag
907 which already exists on another key, unless you give the
911 The following options are recognized.
914 Untag the existing key with the desired new tag, if any.
916 Attaches attributes to a key. The key to which the attributes should be
917 attached is given by its
919 Each attribute has the form
921 An attribute can be deleted by assigning it an empty value. Although
922 the keyring file format is capable of representing an attribute with an
923 empty value as distinct from a nonexistant attribute, this interface
924 does not allow empty attributes to be set.
926 Fetches a single attribute of a key. The key whose attribute is to be
929 The attribute's value is written to standard output followed by a
930 newline. If the key or attribute is absent, a message is written to
931 standard error and the program exits nonzero.
933 Sets, deletes or changes the comment attached to a key. The first
934 argument is a key tag or keyid which names the key to be modified; the
935 second, if present, is the new comment. If no second argument is given,
936 the existing comment, if any, is removed, and no new comment is set.
938 Locks a key or key component using a passphrase. If the key is already
939 locked, the existing passphrase is requested, and a new passphrase is
942 Unlocks a passphrase-locked key or key component. If the key is not
943 locked, an error is reported.
945 Lists the keys in the keyring. A couple of options are supported:
947 .B "\-v, \-\-verbose"
948 Increases the amount of information displayed for each key. Repeat for
952 Decreases the amount of information displayed for each key. Each use
958 Display key expiry times as UTC rather than using the local time zone.
960 .BI "\-f, \-\-filter " filter
961 Specifies a filter. Only keys and key components which match the filter
964 By default, a single line of output is generated for each, showing
965 keyids, types, expiry and deletion dates, and comments. Additional
967 options show more information, such as the exact time of day for expiry
968 and deletion, key attributes, and a dump of the actual key data. If the
969 verbosity level is sufficiently high, passphrases are requested to
970 decrypt locked keys. Make sure nobody is looking over your shoulder
973 Reports a fingerprint (secure hash) on components of requested keys.
974 The following options are supported:
976 .BI "\-f, \-\-filter " filter
977 Specifies a filter. Only keys and key components which match the filter
978 are fingerprinted. The default is to only fingerprint nonsecret
981 .BI "\-p, \-\-presentation " style
982 Write fingerprints in the given
984 See below for a list of presentation styles.
986 .BI "\-a, \-\-algorithm " hash
987 Names the hashing algorithm. Run
989 for a list of hashing algorithms. The default is
992 The keys to be fingerprinted are named by their tags or keyids given as
993 command line arguments. If no key tags are given, all keys which match
994 the filter are fingerprinted. See
996 for a description of how key fingerprints are computed.
998 The fingerprint may be shown in the following styles.
1001 Lowercase hexadecimal, with groups of eight digits separated by hyphens
1002 (`\-'). This is the default presentation style. (On input, colons are
1003 also permitted as separators.)
1006 Lowercase Base32 encoding, without `=' padding, with groups of six
1007 digits separated by colons (`:'). (On input, padding characters are
1010 Check a key's fingerprint against a reference copy. The following
1011 options are supported:
1013 .BI "\-f, \-\-filter " filter
1014 Specifies a filter. Only key components which match the filter are
1015 hashed. The default is to only fingerprint nonsecret components. An
1016 error is reported if no part of the key matches.
1018 .BI "\-p, \-\-presentation " style
1021 to be in the given presentation
1023 These match the styles produced by the
1025 command described above.
1027 .BI "\-a, \-\-algorithm " hash
1028 Names the hashing algorithm. Run
1030 for a list of hashing algorithms. The default is
1033 The fingerprint should be provided in the form printed by the
1035 command, using the same presentation
1037 A little flexibility is permitted: separators may be placed anywhere (or
1038 not at all) and are ignored; whitespace is permitted and ignored; and
1039 case is ignored in presentation styles which don't make use of both
1040 upper- and lower-case characters.
1042 Simply reads the keyring from file and writes it back again. This has
1043 the effect of removing any deleted keys from the file.
1045 Writes a selection of keys to a file. An option is supported:
1047 .BI "\-f, \-\-filter " filter
1048 Specifies a filter. Only keys and key components which match the filter
1051 Keys extracted are written to the file named by the first argument,
1054 to designate standard output. The keys to extract are listed by their
1055 tags; if no tags are given, all keys which match the filter are
1056 extracted. The output is a valid keyring file.
1058 Merges the keys from the named
1062 to designate standard input, with the keyring. Keys already in the
1063 keyring are not overwritten: you must explicitly remove them first if
1064 you want them to be replaced during the merge.
1068 Mark Wooding, <mdw@distorted.org.uk>