2 .TH key 1 "5 June 1999" Catacomb
4 key \- simple key management system
49 command performs useful operations on Catacomb keyring files. It
50 provides a number of subcommands, by which the various operations may be
53 Before the command name,
55 may be given. The following global options are supported:
58 Writes a brief summary of
60 various options to standard output, and
61 returns a successful exit status.
64 Writes the program's version number to standard output, and returns a
65 successful exit status.
68 Writes a very terse command line summary to standard output, and returns
69 a successful exit status.
71 .BI "\-k, \-\-keyring=" file
72 Names the keyring file which
74 is to process. The default keyring, used if this option doesn't specify
75 one, is the file named
77 in the current directory. The keyring must be stored in a regular file:
78 pipes, sockets, devices etc. are not allowed.
81 program attempts to lock the keyring before accessing it, using
83 locking. It will however time out after a short while (10 seconds) and
86 In addition to the actual key data itself, a Catacomb key has a number
87 of other pieces of information attached to it:
90 Every key has a 32-bit identifying number, written in hexadecimal. The
91 keyid is derived from the actual key contents (although knowledge of a
92 key's keyid doesn't help one to guess the key itself). Applications use
93 keyids to refer to specific keys. A
95 key cannot be looked up by keyid.
98 A key's type string describes what the key may be used for. The type
99 string is arbitrary, except that it may not contain whitespace
100 characters. Applications use key types to obtain an arbitrary but
101 suitable key for some purpose. An
103 key cannot be looked up by type, but may be looked up by keyid.
106 Most keys expire after a certain amount of time. Once a key has
107 expired, it will no longer be chosen as a result of a lookup by key
108 type. However, it is not deleted until its deletion time is also
112 A key's deletion time is the latest expiry time of any of the objects
113 which require that key. For example, a key used for authenticating
114 cryptographic cookies should have its deletion time set to the longest
115 expiry time of any of the cookies it can authenticate. A key is never
116 deleted until it has also expired. Once a key has expired
118 its deletion time is passed, it can no longer be referred to by
119 applications, and will be removed from the keyring next time it's
123 A key may be given a comment when it's created. The comment is for the
124 benefit of users, and isn't interpreted by applications at all.
128 A key as zero or more name/value pairs. The names and values are
129 arbitrary strings, except they may not contain null bytes. Some
130 attributes may have meaning for particular applications or key types;
131 others may be assigned global meanings in future.
132 .SH "COMMAND REFERENCE"
136 command creates a new key and adds it to the keyring. The command
137 accepts the following options:
139 .BI "\-b, \-\-bits=" bits
140 The length of the key to generate, in bits. The default, if this option
141 is not supplied, is 128 bits. The bit length must be nonzero, and must
144 .BI "\-e, \-\-expire=" expire
145 The expiry date for the generated key. This may be the string
147 if the key should never expire automatically, or any date acceptable to
150 library function. Briefly,
152 understands absolute dates such as
155 .RB ` "August 2nd, 1999" ',
156 and (perhaps more usefully) relative dates such as
158 The default is to allow a 2 week expiry, which isn't useful.
160 .BI "\-c, \-\-comment=" comment
161 Sets a comment for the key. The default is not to attach a comment.
163 The key's type is given by the required
165 argument. Following the type are zero or more attributes, which are
166 attached to the key in the same way as for the
172 program only generates random bitstrings, which are suitable for most
173 symmetric algorithms but not for public key cryptography. Generating
174 keys for more exotic algorithms is a feature which will be added later.
175 The keys are generated using the Catacomb random number generator, using
178 function. The Catacomb generator is believed to be strong.
180 Forces keys to immediately expire. An expired key is not chosen when a
181 program requests a key by its type. The keys to expire are listed by
185 Deletes keys immediately. The keys to delete are listed by their
187 Be careful when deleting keys. It might be a better idea
188 to expire keys rather than deleting them.
190 Attaches attributes to a key. The key to which the attributes should be
191 attached is given by its
193 Each attribute has the form
195 An attribute can be deleted by assigning it an empty value. Although
196 the keyring file format is capable of representing an attribute with an
197 empty value as distinct from a nonexistant attribute, this interface
198 does not allow empty attributes to be set.
200 Lists the keys in the keyring. A couple of options are supported:
202 .B "\-v, \-\-verbose"
203 Increases the amount of information displayed for each key. Repeat for
207 Decreases the amount of information displayed for each key. Each use
212 By default, a single line of output is generated for each, showing
213 keyids, types, expiry and deletion dates, and comments. Additional
215 options show more information, such as the exact time of day for expiry
216 and deletion, key attributes, and a hex dump of the actual key data.
218 Simply reads the keyring from file and writes it back again. This has
219 the effect of removing any deleted keys from the file.
221 Writes a selection of keys to the named
225 to designate standard output. The keys to extract are listed by their
227 The output is a valid keyring file.
229 Merges the keys from the named
233 to designate standard input, with the keyring. Keys already in the
234 keyring are not overwritten: you must explicitly remove them first if
235 you want them to be replaced during the merge.
237 The ability to generate keys for specific algorithms ought to be added,
238 for DES (setting the parity bits correctly), RSA, ElGamal and DSA, at
239 the very least. (None of these systems are actually implemented in
240 Catacomb at the moment, however.)
244 Mark Wooding, <mdw@nsict.org>
projects / u / mdw / catacomb / blob