.\" -*-nroff-*- .TH key 1 "5 June 1999" Catacomb .SH NAME key \- simple key management system .SH SYNOPSIS .B key .RB [ \-k .IR keyring ] .I command .PP where .I command is one of: .PP .B add .RB [ \-b .IR bits ] .RB [ \-e .IR expire ] .RB [ \-c .IR comment ] .I type .IR attr ... .br .B expire .IR keyid ... .br .B delete .IR keyid ... .br .B setattr .I keyid .IR attr ... .br .B list .RB [ \-quv ] .br .B tidy .br .B extract .I file .IR keyid ... .br .B merge .I file .SH DESCRIPTION The .B key command performs useful operations on Catacomb keyring files. It provides a number of subcommands, by which the various operations may be carried out. .SS "Global options" Before the command name, .I "global options" may be given. The following global options are supported: .TP .B "\-h, \-\-help" Writes a brief summary of .BR key 's various options to standard output, and returns a successful exit status. .TP .B "\-v, \-\-version" Writes the program's version number to standard output, and returns a successful exit status. .TP .B "\-u, \-\-usage" Writes a very terse command line summary to standard output, and returns a successful exit status. .TP .BI "\-k, \-\-keyring " file Names the keyring file which .B key is to process. The default keyring, used if this option doesn't specify one, is the file named .B keyring in the current directory. The keyring must be stored in a regular file: pipes, sockets, devices etc. are not allowed. The .B key program attempts to lock the keyring before accessing it, using .BR fcntl (2) locking. It will however time out after a short while (10 seconds) and report a failure. .SS Concepts In addition to the actual key data itself, a Catacomb key has a number of other pieces of information attached to it: .TP .B keyid Every key has a 32-bit identifying number, written in hexadecimal. The keyid is derived from the actual key contents (although knowledge of a key's keyid doesn't help one to guess the key itself). Applications use keyids to refer to specific keys. A .I deleted key cannot be looked up by keyid. .TP .B type A key's type string describes what the key may be used for. The type string is arbitrary, except that it may not contain whitespace characters. Applications use key types to obtain an arbitrary but suitable key for some purpose. An .I expired key cannot be looked up by type, but may be looked up by keyid. .TP .B "expiry time" Most keys expire after a certain amount of time. Once a key has expired, it will no longer be chosen as a result of a lookup by key type. However, it is not deleted until its deletion time is also reached. .TP .B "deletion time" A key's deletion time is the latest expiry time of any of the objects which require that key. For example, a key used for authenticating cryptographic cookies should have its deletion time set to the longest expiry time of any of the cookies it can authenticate. A key is never deleted until it has also expired. Once a key has expired .I and its deletion time is passed, it can no longer be referred to by applications, and will be removed from the keyring next time it's written to disk. .TP .B comment A key may be given a comment when it's created. The comment is for the benefit of users, and isn't interpreted by applications at all. (Hopefully.) .TP .B attributes A key as zero or more name/value pairs. The names and values are arbitrary strings, except they may not contain null bytes. Some attributes may have meaning for particular applications or key types; others may be assigned global meanings in future. .SH "COMMAND REFERENCE" .SS add The .B add command creates a new key and adds it to the keyring. The command accepts the following options: .TP .BI "\-b, \-\-bits " bits The length of the key to generate, in bits. The default, if this option is not supplied, is 128 bits. The bit length must be nonzero, and must be a multiple of 8. .TP .BI "\-e, \-\-expire " expire The expiry date for the generated key. This may be the string .RB ` forever ' if the key should never expire automatically, or any date acceptable to the .BR getdate (3) library function. Briefly, .B getdate understands absolute dates such as .RB ` 1999-08-02 ' or .RB ` "August 2nd, 1999" ', and (perhaps more usefully) relative dates such as .RB ` "+2 weeks" '. The default is to allow a 2 week expiry, which isn't useful. .TP .BI "\-c, \-\-comment " comment Sets a comment for the key. The default is not to attach a comment. .PP The key's type is given by the required .I type argument. Following the type are zero or more attributes, which are attached to the key in the same way as for the .B setattr command. .PP The .B key program only generates random bitstrings, which are suitable for most symmetric algorithms but not for public key cryptography. Generating keys for more exotic algorithms is a feature which will be added later. The keys are generated using the Catacomb random number generator, using the .B rand_goodbits function. The Catacomb generator is believed to be strong. .SS expire Forces keys to immediately expire. An expired key is not chosen when a program requests a key by its type. The keys to expire are listed by their .IR keyid s. .SS delete Deletes keys immediately. The keys to delete are listed by their .IR keyid s. Be careful when deleting keys. It might be a better idea to expire keys rather than deleting them. .SS setattr Attaches attributes to a key. The key to which the attributes should be attached is given by its .IR keyid . Each attribute has the form .IB name = value\fR. An attribute can be deleted by assigning it an empty value. Although the keyring file format is capable of representing an attribute with an empty value as distinct from a nonexistant attribute, this interface does not allow empty attributes to be set. .SS list Lists the keys in the keyring. A couple of options are supported: .TP .B "\-v, \-\-verbose" Increases the amount of information displayed for each key. Repeat for a greater effect. .TP .B "\-q, \-\-quiet" Decreases the amount of information displayed for each key. Each use cancels a .RB ` \-v ' option. .TP .B "\-u, \-\-utc" Display key expiry times as UTC rather than using the local time zone. .PP By default, a single line of output is generated for each, showing keyids, types, expiry and deletion dates, and comments. Additional .RB ` \-v ' options show more information, such as the exact time of day for expiry and deletion, key attributes, and a hex dump of the actual key data. .SS tidy Simply reads the keyring from file and writes it back again. This has the effect of removing any deleted keys from the file. .SS extract Writes a selection of keys to the named .IR file , which may be .RB ` \- ' to designate standard output. The keys to extract are listed by their .IR keyid s. The output is a valid keyring file. .SS merge Merges the keys from the named .IR file , which may be .RB ` \- ' to designate standard input, with the keyring. Keys already in the keyring are not overwritten: you must explicitly remove them first if you want them to be replaced during the merge. .SH BUGS The ability to generate keys for specific algorithms ought to be added, for DES (setting the parity bits correctly), RSA, ElGamal and DSA, at the very least. (None of these systems are actually implemented in Catacomb at the moment, however.) .SH "SEE ALSO" .BR keyring (5). .SH AUTHOR Mark Wooding,