31 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
33 key \- simple key management system
151 command performs useful operations on Catacomb keyring files. It
152 provides a number of subcommands, by which the various operations may be
155 Before the command name,
157 may be given. The following global options are supported:
159 .BR "\-h, \-\-help " [ \fIcommand ...]
160 Writes a brief summary of
162 various options to standard output, and
163 returns a successful exit status. With command names, gives help on
166 .B "\-v, \-\-version"
167 Writes the program's version number to standard output, and returns a
168 successful exit status.
171 Writes a very terse command line summary to standard output, and returns
172 a successful exit status.
174 .BI "\-k, \-\-keyring " file
175 Names the keyring file which
177 is to process. The default keyring, used if this option doesn't specify
178 one, is the file named
180 in the current directory. The keyring must be stored in a regular file:
181 pipes, sockets, devices etc. are not allowed.
184 program attempts to lock the keyring before accessing it, using
186 locking. It will however time out after a short while (10 seconds) and
189 In addition to the actual key data itself, a Catacomb key has a number
190 of other pieces of information attached to it:
193 Every key has a 32-bit identifying number, written in hexadecimal.
194 Keyids are not actually related to the key contents: they're generated
195 randomly. Applications use keyids to refer to specific keys; users are
196 probably better off with tags and types. A
198 key cannot be looked up by keyid.
201 A key's tag is a unique string which can be used by users and
202 applications to identify the key. Tag strings may not contain spaces,
205 key cannot be looked up by tag. Whenever a tag name is wanted, a hex
206 keyid or key type string can be given instead.
209 A key's type string describes what the key may be used for. The type
210 string is arbitrary, except that it may not contain whitespace
211 characters, dots or colons. Applications use key types to obtain an
212 arbitrary but suitable key for some purpose. An
214 key cannot be looked up by type, but may be looked up by keyid or tag.
217 There are a number of different ways in which keys can be represented,
218 according to the uses to which the key will be put. Most symmetric
221 keys. Keys used with number-theoretic systems (like most common
222 public-key systems) use
223 .I "multiprecision integer"
224 keys. Elliptic curve systems use
226 keys, which are either a pair of integers representing field elements,
227 or a `point at infinity'. Algorithms which require several key
228 constituents (again, like most public-key systems) use
230 keys, which consist of a collection of named parts. It's possible to
233 as a key, though this is usually done as a component of a structured
234 key. Finally, keys (including structured keys) can be encrypted.
237 Keys and key components may be selected by a filter expression, a
238 sequence of flag names separated by commas. Flags are:
246 (describing the key encoding);
252 (describing the category of key);
256 (whether the key should be erased from memory after use); and
260 (whether the key is safe to divulge).
263 A key component may be identified by the key's tag (or keyid, or type).
264 Subcomponents of structured keys are identified by following the tag by
265 a dot and the name of the subcomponent.
268 Most keys expire after a certain amount of time. Once a key has
269 expired, it will no longer be chosen as a result of a lookup by key
270 type. However, it is not deleted until its deletion time is also
274 A key's deletion time is the latest expiry time of any of the objects
275 which require that key. For example, a key used for authenticating
276 cryptographic cookies should have its deletion time set to the longest
277 expiry time of any of the cookies it can authenticate. Once a key's
278 deletion time is passed, it can no longer be referred to by
279 applications, and will be removed from the keyring next time it's
283 A key may be given a comment when it's created. The comment is for the
284 benefit of users, and isn't interpreted by applications at all.
288 A key has zero or more name/value pairs. The names and values are
289 arbitrary strings, except that they may not contain null bytes. Some
290 attributes may have meaning for particular applications or key types;
291 others may be assigned global meanings in future.
292 .SH "COMMAND REFERENCE"
296 command behaves exactly as the
298 option. With no arguments, it shows an overview of
300 options; with arguments, it describes the named subcommands.
304 command prints various lists of tokens understood by
306 With no arguments, it prints all of the lists; with arguments, it prints
307 just the named lists, in order. The recognized lists can be enumerated
312 command. The lists are as follows.
315 The lists which can be enumerated by the
320 The hash functions which can be used with the
327 The built-in elliptic curves which can be used with the
332 The built-in Diffie\(enHellman groups which can be used with the
337 The key-generation algorithms which are acceptable to the
344 The pseudorandom generators which are acceptable to the
351 Fingerprint presentation styles, as used by the
359 command creates a new key and adds it to the keyring. The command
360 accepts the following options:
362 .BI "\-a, \-\-algorithm " alg
363 Selects a key generation algorithm. The default algorithm is
365 the different algorithms are described below. The command
367 lists the recognized key-generation algorithms.
369 .BI "\-b, \-\-bits " bits
370 The length of the key to generate, in bits. The default, if this option
371 is not supplied, depends on the key-generation algorithm.
373 .BI "\-B, \-\-qbits " bits
374 The length of the subsidiary key or parameter, in bits. Not all
375 key-generation algorithms have a subsidiary key size.
377 .BI "\-p, \-\-parameters " tag
378 Selects a key containing parameter values to copy.
379 A new key also inherits attributes from its parameter key.
381 .BI "\-A, \-\-seedalg " seed-alg
382 Use the deterministic random number generator algorithm
384 to generate the key. Use
390 options; without one of these,
392 has no effect. The default algorithm is
396 shows a list of recognized seeding algorithms. The seeding algorithm
397 used to generate a key is recorded as the key's
401 .BI "\-s, \-\-seed " seed
402 Generate the key deterministically using the given
404 which should be a Base64-encoded binary string. This is mainly useful
405 for parameters keys (types
409 to demonstrate that a set of parameters has been generated in an honest
412 generation algorithm can be used to generate
414 keys as required by FIPS186. The requested seed is recorded,
415 Base64-encoded, as the new key's
419 .BI "\-n, \-\-newseed " bits
420 Generate a new seed, with the given length in
422 The generated seed is recorded, Base64-encoded, as the new key's
426 .BI "\-e, \-\-expire " expire
427 The expiry date for the generated key. This may be the string
429 if the key should never expire automatically, or any date acceptable to
432 library function. Briefly,
434 understands absolute dates such as
437 .RB ` "August 2nd, 1999" ',
438 and (perhaps more usefully) relative dates such as
440 The default is to allow a 2 week expiry, which isn't useful.
442 .BI "\-c, \-\-comment " comment
443 Sets a comment for the key. The default is not to attach a comment.
445 .BI "\-C, \-\-curve " curve-spec
446 Use the elliptic curve described by
448 when generating elliptic curve parameters.
450 .BI "\-t, \-\-tag " tag
451 Selects a tag string for the key. The default is not to set a tag. It
452 is an error to select a tag which already exists.
457 option is given, remove this tag from any key which already has it.
459 .BI "\-R, \-\-rand-id " tag
460 Selects the key to use for the random number generator. Catacomb's
461 random number generator can be
463 so that, even if the inputs to the generator are compromised, knowledge
464 of the key is also necessary to be able to predict the output. By
465 default, the latest-expiring key with type
467 is used, if present; if not, no key is used.
470 Requests that the secret parts of the newly-generated key be encrypted
474 Suppresses the progress indication which is usually generated while
475 time-consuming key generation tasks are being performed.
477 .BI "\-E, \-\-public-exponent"
478 Set the public exponent for RSA keys.
479 The default is 65537,
480 because this seems to be the overwhelmingly popular choice
482 and because it was the exponent used before this option was introduced.
483 The value 3 is fine unless you use a completely terrible padding scheme.
485 .BI "\-L, \-\-lim-lee"
486 When generating Diffie\(enHellman parameters, generate a Lim\(enLee
487 prime rather than a random (or safe) prime. See the details on
488 Diffie\(enHellman key generation below.
491 When generating Diffie\(enHellman parameters, generate a KCDSA-style
492 Lim\(enLee prime rather than a random (or safe) prime. See the details
493 on Diffie\(enHellman key generation below.
495 .BI "\-S, \-\-subgroup"
496 When generating Diffie\(enHellman parameters with a Lim\(enLee prime,
497 choose a generator of a prime-order subgroup rather than a subgroup of
499 .RI ( p "\ \-\ 1)/2."
501 The key's type is given by the required
503 argument. Following the type are zero or more attributes, which are
504 attached to the key in the same way as for the
508 The key-generation algorithms supported are as follows:
511 Generates a plain binary key of the requested length. If the requested
512 key length is not a multiple of eight, the high-order bits of the first
513 octet of the key are zeroed. The default key length is 128 bits.
516 Generates a DES key, with parity bits. The key length must be 56, 112
517 or 168; the default is 56. The low-order bit of each octet is ignored by
518 the DES algorithm; it is used to give each octet odd parity.
521 Generates a public/private key pair for use with the RSA algorithm.
523 The key components are
527 a pair of prime numbers;
536 the private exponent, chosen such that
539 .RI lcm( p "\~\-\~1, " q \~\-\~1));
540 and some other values useful for optimizing private-key operations:
541 .IR q "\*(ss\-1\*(se mod " p ,
542 .IR d "\~mod " p \~\-\~1,
544 .IR d "\~mod " q \~\-\~1.
549 constitute the public key; the rest must be kept secret. The key size
552 option determines the size of the modulus
554 the default is 1024 bits.
556 The key generation algorithm chooses
566 have large prime factors \(en call them
570 respectively \(en and
572 also has a large prime factor;
574 has similar properties.
578 cannot be sensibly used as a shared parameter, since knowledge of
579 corrssponding public and private exponents is sufficient to be able to
580 factor the modulus and recover other users' private keys.
583 Generates parameters for use with the Diffie\(enHellman key exchange
584 protocol, and many related systems, such as ElGamal encryption and
585 signatures, and even DSA. (The separate DSA algorithm uses the
586 generator described in FIPS186-1.)
588 The Diffie\(enHellman parameters are a prime modulus
599 option controls the size of the modulus
601 the default size is 1024 bits.
605 size is selected using the
607 option and the Lim\(enLee prime options are disabled, then
609 is chosen to be a `safe' prime (i.e.,
610 .IR p "\~= 2" q \~+\~1,
613 prime). Finding safe primes takes a very long time. In this case, the
618 If a size is chosen for
620 and Lim\(enLee primes are not selected then the prime
631 option was given, Lim\(enLee primes are selected: the parameters are
633 .IR p "\~= 2\~" q \*(us0\*(ue
635 .IR q \*(us2\*(ue\~...\~+\~1,
638 are primes at least as large as the setting given by the
640 option (or 256 bits, if no setting was given).
644 option was given, KCDSA-style Lim\(enLee primes are selected: the
645 parameters are chosen such that
646 .IR p "\~= 2" qv \~+\~1,
658 options were given, the generator
660 is chosen to generate the subgroup of order
664 will generate the group of order
665 .RI ( p "\~\-\~1)/2\~= " q "\*(us0\*(ue " q \*(us1\*(ue
666 .IR q \*(us2\*(ue\~...
670 option can be given, in which case the parameters are taken directly
671 from the provided group specification, which may either be the the name
672 of one of the built-in groups (say
674 for a list) or a triple
675 .RI ( p ,\~ q ,\~ g ).
676 separated by commas. No random generation is done in this case: the
677 given parameters are simply stored.
680 Generates a public/private key pair for use with offline Diffie\(enHellman,
681 ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
684 and computes the public key
685 .IR y "\~= " g \*(ss x "\*(se mod\~" p .
688 Generates parameters for the DSA algorithm. DSA parameters are also
689 suitable for use with Diffie\(enHellman and ElGamal system.
691 The main difference between DSA and Diffie\(enHellman parameter generation
692 is thatthe DSA parameter generation
695 from which the parameters are derived, and, assuming that the SHA-1 hash
696 function is strong, it's not feasible to construct a seed from which
697 deliberately weak parameters are derived. The algorithm used is the one
698 described in the DSA standard, FIPS\ 186, extended only to allow
699 sequential search for a prime
701 and to allow arbitrary parameter sizes. The seed is stored,
702 Base64-encoded, as the value of the attribute
705 The default lengths for
709 are 768 and 160 bits respectively, since the DSA standard specifies that
711 be 160 bits, and the choice of 768 bits for
713 gives commensurate security.
716 Generates a public/private key pair for DSA. As for Diffie\(enHellman
720 and computes the public key
721 .IR y "\~= " g \*(ss x "\*(se mod\~" p .
724 Generates a public/private key pair for the Blum-Blum-Shub random-number
725 generator, and the Blum-Goldwasser semantically-secure public-key
728 The key components are prime numbers
732 both congruent to 3 (mod\~4), and their product
734 The public key is simply the modulus
742 The key-generation algorithm ensures that the two primes
748 (see the discussion of strong primes above, in the section on RSA keys),
753 are relatively prime, giving a maximum possible period length.
755 The key size requested by the
757 option determines the length of the modulus
759 the default length is 1024 bits.
762 Store an elliptic curve specification. If no explicit
766 option) then a curve is chosen whose order is about the size given by the
768 option (default is 256 bits).
772 can be given explicitly (in which case
774 is ignored). It can either be the name of a built-in curve (say
776 for a list of curve names) or a full specification. The curve is
777 checked for correctness and security according to the SEC1
778 specification: failed checks cause a warning to be issued to standard
779 error (though the program continues anyway). The check can be
784 A curve specification consists of the following elements optionally
785 separated by whitespace: a
801 and the representation of the normal element \*(*b; an optional
811 (the `proj' types currently have much better performance);
814 the two field-element parameters
818 which define the elliptic curve
820 separated by an optional
828 of the generator point
830 separated by an optional
836 of the group generated by
847 Generate a private scalar and a corresponding public point on an
850 above for how to specify elliptic curve parameter sets. The scalar
852 is chosen unformly between 0 and the curve order
854 the public point is then
860 Generate a private scalar and a corresponding public point on the
861 (Montgomery-form) Curve25519 elliptic curve.
862 The scalar is simply a random 256-bit string;
863 the public key is the
865 of the corresponding point.
868 Generate a private scalar and a corresponding public point on the
869 (Montgomery-form) Ed448-Goldilocks elliptic curve.
870 The scalar is simply a random 256-bit string;
871 the public key is the
873 of the corresponding point.
876 Generate a private key and a corresponding public point on the
877 (twisted Edwards-form) Curve25519 elliptic curve.
878 The private key is simply a random 256-bit string,
879 from which a scalar and secret prefix are derived;
880 the public key is the compressed form of the corresponding point.
883 Generate a private key and a corresponding public point on the
884 (Edwards-form) Ed448-Goldilocks elliptic curve.
885 The private key is simply a random 456-bit string,
886 from which a scalar and secret prefix are derived;
887 the public key is the compressed form of the corresponding point.
890 Generate an empty key, with trivial contents.
891 This is useful as a `parameters' key,
892 carrying attributes to be applied to other keys
893 if they don't require more detailed parameters.
895 Forces keys to immediately expire. An expired key is not chosen when a
896 program requests a key by its type. The keys to expire are listed by
900 Deletes keys immediately. The keys to delete are listed by their
902 Be careful when deleting keys. It might be a better idea
903 to expire keys rather than deleting them.
905 Sets, deletes or changes the tag attached to a key. The first tag or
906 keyid names the key to be modified; the second, if present specifies the
907 new tag to be set. If no second argument is given, the existing tag, if
908 any, is removed and no new tag is set. It is an error to set a tag
909 which already exists on another key, unless you give the
913 The following options are recognized.
916 Untag the existing key with the desired new tag, if any.
918 Attaches attributes to a key. The key to which the attributes should be
919 attached is given by its
921 Each attribute has the form
923 An attribute can be deleted by assigning it an empty value. Although
924 the keyring file format is capable of representing an attribute with an
925 empty value as distinct from a nonexistant attribute, this interface
926 does not allow empty attributes to be set.
928 Fetches a single attribute of a key. The key whose attribute is to be
931 The attribute's value is written to standard output followed by a
932 newline. If the key or attribute is absent, a message is written to
933 standard error and the program exits nonzero.
935 Sets, deletes or changes the comment attached to a key. The first
936 argument is a key tag or keyid which names the key to be modified; the
937 second, if present, is the new comment. If no second argument is given,
938 the existing comment, if any, is removed, and no new comment is set.
940 Locks a key or key component using a passphrase. If the key is already
941 locked, the existing passphrase is requested, and a new passphrase is
944 Unlocks a passphrase-locked key or key component. If the key is not
945 locked, an error is reported.
947 Lists the keys in the keyring. A couple of options are supported:
949 .B "\-v, \-\-verbose"
950 Increases the amount of information displayed for each key. Repeat for
954 Decreases the amount of information displayed for each key. Each use
960 Display key expiry times as UTC rather than using the local time zone.
962 .BI "\-f, \-\-filter " filter
963 Specifies a filter. Only keys and key components which match the filter
966 By default, a single line of output is generated for each, showing
967 keyids, types, expiry and deletion dates, and comments. Additional
969 options show more information, such as the exact time of day for expiry
970 and deletion, key attributes, and a dump of the actual key data. If the
971 verbosity level is sufficiently high, secret parts of keys are printed,
972 and passphrases are requested to decrypt locked keys. Make sure nobody
973 is looking over your shoulder when you do this!
975 Reports a fingerprint (secure hash) on components of requested keys.
976 The following options are supported:
978 .BI "\-f, \-\-filter " filter
979 Specifies a filter. Only keys and key components which match the filter
980 are fingerprinted. The default is to only fingerprint nonsecret
983 .BI "\-p, \-\-presentation " style
984 Write fingerprints in the given
986 See below for a list of presentation styles.
988 .BI "\-a, \-\-algorithm " hash
989 Names the hashing algorithm. Run
991 for a list of hashing algorithms. The default is
994 The keys to be fingerprinted are named by their tags or keyids given as
995 command line arguments. If no key tags are given, all keys which match
996 the filter are fingerprinted. See
998 for a description of how key fingerprints are computed.
1000 The fingerprint may be shown in the following styles.
1003 Lowercase hexadecimal, with groups of eight digits separated by hyphens
1004 (`\-'). This is the default presentation style. (On input, colons are
1005 also permitted as separators.)
1008 Lowercase Base32 encoding, without `=' padding, with groups of six
1009 digits separated by colons (`:'). (On input, padding characters are
1012 Check a key's fingerprint against a reference copy. The following
1013 options are supported:
1015 .BI "\-f, \-\-filter " filter
1016 Specifies a filter. Only key components which match the filter are
1017 hashed. The default is to only fingerprint nonsecret components. An
1018 error is reported if no part of the key matches.
1020 .BI "\-p, \-\-presentation " style
1023 to be in the given presentation
1025 These match the styles produced by the
1027 command described above.
1029 .BI "\-a, \-\-algorithm " hash
1030 Names the hashing algorithm. Run
1032 for a list of hashing algorithms. The default is
1035 The fingerprint should be provided in the form printed by the
1037 command, using the same presentation
1039 A little flexibility is permitted: separators may be placed anywhere (or
1040 not at all) and are ignored; whitespace is permitted and ignored; and
1041 case is ignored in presentation styles which don't make use of both
1042 upper- and lower-case characters.
1044 Simply reads the keyring from file and writes it back again. This has
1045 the effect of removing any deleted keys from the file.
1047 Writes a selection of keys to a file. An option is supported:
1049 .BI "\-f, \-\-filter " filter
1050 Specifies a filter. Only keys and key components which match the filter
1053 Keys extracted are written to the file named by the first argument,
1056 to designate standard output. The keys to extract are listed by their
1057 tags; if no tags are given, all keys which match the filter are
1058 extracted. The output is a valid keyring file.
1060 Merges the keys from the named
1064 to designate standard input, with the keyring. Keys already in the
1065 keyring are not overwritten: you must explicitly remove them first if
1066 you want them to be replaced during the merge.
1070 Mark Wooding, <mdw@distorted.org.uk>