d03ab969 |
1 | .\" -*-nroff-*- |
052b36d0 |
2 | .ie t \{\ |
3 | . ds ss \s8\u |
4 | . ds se \d\s0 |
5 | .\} |
6 | .el \{\ |
7 | . ds ss ^ |
8 | . ds se |
9 | .\} |
d03ab969 |
10 | .TH key 1 "5 June 1999" Catacomb |
11 | .SH NAME |
12 | key \- simple key management system |
13 | .SH SYNOPSIS |
14 | .B key |
15 | .RB [ \-k |
16 | .IR keyring ] |
17 | .I command |
18 | .PP |
19 | where |
20 | .I command |
21 | is one of: |
22 | .PP |
23 | .B add |
052b36d0 |
24 | .RB [ \-lq ] |
25 | .RB [ \-a |
26 | .IR alg ] |
27 | .RB [ \-b | \-B |
d03ab969 |
28 | .IR bits ] |
052b36d0 |
29 | .RB [ \-p |
30 | .IR param ] |
31 | .RB [ \-r |
32 | .IR tag ] |
33 | .br |
34 | \h'8n' |
d03ab969 |
35 | .RB [ \-e |
36 | .IR expire ] |
052b36d0 |
37 | .RB [ \-t |
38 | .IR tag ] |
d03ab969 |
39 | .RB [ \-c |
40 | .IR comment ] |
41 | .I type |
42 | .IR attr ... |
43 | .br |
44 | .B expire |
052b36d0 |
45 | .IR tag ... |
d03ab969 |
46 | .br |
47 | .B delete |
052b36d0 |
48 | .IR tag ... |
49 | .br |
50 | .B tag |
51 | .I tag |
52 | .RI [ new-tag ] |
53 | .br |
54 | .B comment |
55 | .I tag |
56 | .RI [ comment ] |
d03ab969 |
57 | .br |
58 | .B setattr |
052b36d0 |
59 | .I tag |
d03ab969 |
60 | .IR attr ... |
61 | .br |
052b36d0 |
62 | .B lock |
63 | .I qtag |
64 | .br |
65 | .B unlock |
66 | .I qtag |
67 | .br |
d03ab969 |
68 | .B list |
052b36d0 |
69 | .RB [ \-uqv ] |
70 | .RB [ \-f |
71 | .IR filter ] |
72 | .RI [ tag ...] |
73 | .br |
74 | .B fingerprint |
75 | .RB [ \-f |
76 | .IR filter ] |
77 | .RI [ tag ...] |
d03ab969 |
78 | .br |
79 | .B tidy |
80 | .br |
81 | .B extract |
052b36d0 |
82 | .RB [ \-f |
83 | .IR filter ] |
d03ab969 |
84 | .I file |
052b36d0 |
85 | .RI [ tag ...] |
d03ab969 |
86 | .br |
87 | .B merge |
88 | .I file |
89 | .SH DESCRIPTION |
90 | The |
91 | .B key |
92 | command performs useful operations on Catacomb keyring files. It |
93 | provides a number of subcommands, by which the various operations may be |
94 | carried out. |
95 | .SS "Global options" |
96 | Before the command name, |
97 | .I "global options" |
98 | may be given. The following global options are supported: |
99 | .TP |
100 | .B "\-h, \-\-help" |
101 | Writes a brief summary of |
102 | .BR key 's |
103 | various options to standard output, and |
104 | returns a successful exit status. |
105 | .TP |
106 | .B "\-v, \-\-version" |
107 | Writes the program's version number to standard output, and returns a |
108 | successful exit status. |
109 | .TP |
110 | .B "\-u, \-\-usage" |
111 | Writes a very terse command line summary to standard output, and returns |
112 | a successful exit status. |
113 | .TP |
c9e31e42 |
114 | .BI "\-k, \-\-keyring " file |
d03ab969 |
115 | Names the keyring file which |
116 | .B key |
117 | is to process. The default keyring, used if this option doesn't specify |
118 | one, is the file named |
119 | .B keyring |
120 | in the current directory. The keyring must be stored in a regular file: |
121 | pipes, sockets, devices etc. are not allowed. |
122 | The |
123 | .B key |
124 | program attempts to lock the keyring before accessing it, using |
125 | .BR fcntl (2) |
126 | locking. It will however time out after a short while (10 seconds) and |
127 | report a failure. |
128 | .SS Concepts |
129 | In addition to the actual key data itself, a Catacomb key has a number |
130 | of other pieces of information attached to it: |
131 | .TP |
052b36d0 |
132 | .B "keyid" |
133 | Every key has a 32-bit identifying number, written in hexadecimal. |
134 | Keyids are not actually related to the key contents: they're generated |
135 | randomly. Applications use keyids to refer to specific keys; users are |
136 | probably better off with tags and types. A |
d03ab969 |
137 | .I deleted |
138 | key cannot be looked up by keyid. |
139 | .TP |
052b36d0 |
140 | .B "tag" |
141 | A key's tag is a unique string which can be used by users and |
142 | applications to identify the key. Tag strings may not contain spaces, |
143 | colons or dots. A |
144 | .I deleted |
145 | key cannot be looked up by tag. Whenever a tag name is wanted, a hex |
146 | keyid or key type string can be given instead. |
147 | .TP |
148 | .B "type" |
d03ab969 |
149 | A key's type string describes what the key may be used for. The type |
150 | string is arbitrary, except that it may not contain whitespace |
052b36d0 |
151 | characters, dots or colons. Applications use key types to obtain an |
152 | arbitrary but suitable key for some purpose. An |
d03ab969 |
153 | .I expired |
052b36d0 |
154 | key cannot be looked up by type, but may be looked up by keyid or tag. |
155 | .TP |
156 | .B "key encoding" |
157 | There are a number of different ways in which keys can be represented, |
158 | according to the uses to which the key will be put. Most symmetric |
159 | algorithms use |
160 | .I binary |
161 | keys. Keys used with number-theoretic systems (like most common |
162 | public-key systems) use |
163 | .I "multiprecision integer" |
164 | keys. Algorithms which require several key constituents (again, like |
165 | most public-key systems) use |
166 | .I structured |
167 | keys, which consist of a collection of named parts. Finally, keys |
168 | (including structured keys) can be encrypted. |
169 | .TP |
170 | .B "filter" |
171 | Keys and key components may be selected by a filter expression, a |
172 | sequence of flag names separated by commas. Flags are: |
173 | .BR binary , |
174 | .BR integer , |
175 | .B struct |
176 | or |
177 | .B encrypt |
178 | (describing the key encoding); |
179 | .BR symmetric , |
180 | .BR private , |
181 | .B public |
182 | or |
183 | .B shared |
184 | (describing the category of key); |
185 | .B burn |
186 | and its negation |
187 | .B \-burn |
188 | (whether the key should be erased from memory after use); and |
189 | .B secret |
190 | and its negation |
191 | .B \-secret |
192 | (whether the key is safe to divulge). |
193 | .TP |
194 | .B "qualified tag" |
195 | A key component may be identified by the key's tag (or keyid, or type). |
196 | Subcomponents of structured keys are identified by following the tag by |
197 | a dot and the name of the subcomponent. |
d03ab969 |
198 | .TP |
199 | .B "expiry time" |
200 | Most keys expire after a certain amount of time. Once a key has |
201 | expired, it will no longer be chosen as a result of a lookup by key |
202 | type. However, it is not deleted until its deletion time is also |
203 | reached. |
204 | .TP |
205 | .B "deletion time" |
206 | A key's deletion time is the latest expiry time of any of the objects |
207 | which require that key. For example, a key used for authenticating |
208 | cryptographic cookies should have its deletion time set to the longest |
052b36d0 |
209 | expiry time of any of the cookies it can authenticate. Once a key's |
210 | deletion time is passed, it can no longer be referred to by |
d03ab969 |
211 | applications, and will be removed from the keyring next time it's |
212 | written to disk. |
213 | .TP |
052b36d0 |
214 | .B "comment" |
d03ab969 |
215 | A key may be given a comment when it's created. The comment is for the |
216 | benefit of users, and isn't interpreted by applications at all. |
217 | (Hopefully.) |
218 | .TP |
052b36d0 |
219 | .B "attributes" |
d03ab969 |
220 | A key as zero or more name/value pairs. The names and values are |
221 | arbitrary strings, except they may not contain null bytes. Some |
222 | attributes may have meaning for particular applications or key types; |
223 | others may be assigned global meanings in future. |
224 | .SH "COMMAND REFERENCE" |
225 | .SS add |
226 | The |
227 | .B add |
228 | command creates a new key and adds it to the keyring. The command |
229 | accepts the following options: |
230 | .TP |
052b36d0 |
231 | .BI "\-a, \-\-algorithm " alg |
232 | Selects a key generation algorithm. The default algorithm is |
233 | .BR binary ; |
234 | the different algorithms are described below. |
235 | .TP |
c9e31e42 |
236 | .BI "\-b, \-\-bits " bits |
d03ab969 |
237 | The length of the key to generate, in bits. The default, if this option |
052b36d0 |
238 | is not supplied, depends on the key-generation algorithm. |
239 | .TP |
240 | .BI "\-B, \-\-qbits " bits |
241 | The length of the subsidiary key or parameter, in bits. Not all |
242 | key-generation algorithms have a subsidiary key size. |
243 | .TP |
244 | .BI "\-p, \-\-parameters " tag |
245 | Selects a key containing parameter values to copy. Not all |
246 | key-generation algorithms allow the use of shared parameters. |
d03ab969 |
247 | .TP |
c9e31e42 |
248 | .BI "\-e, \-\-expire " expire |
d03ab969 |
249 | The expiry date for the generated key. This may be the string |
250 | .RB ` forever ' |
251 | if the key should never expire automatically, or any date acceptable to |
252 | the |
253 | .BR getdate (3) |
254 | library function. Briefly, |
255 | .B getdate |
256 | understands absolute dates such as |
257 | .RB ` 1999-08-02 ' |
258 | or |
259 | .RB ` "August 2nd, 1999" ', |
260 | and (perhaps more usefully) relative dates such as |
261 | .RB ` "+2 weeks" '. |
262 | The default is to allow a 2 week expiry, which isn't useful. |
263 | .TP |
c9e31e42 |
264 | .BI "\-c, \-\-comment " comment |
d03ab969 |
265 | Sets a comment for the key. The default is not to attach a comment. |
052b36d0 |
266 | .TP |
267 | .BI "\-t, \-\-tag " tag |
268 | Selects a tag string for the key. The default is not to set a tag. It |
269 | is an error to select a tag which already exists. |
270 | .TP |
271 | .BI "\-r, \-\-rand-id " tag |
272 | Selects the key to use for the random number generator. Catacomb's |
273 | random number generator can be |
274 | .IR keyed , |
275 | so that, even if the inputs to the generator are compromised, knowledge |
276 | of the key is also necessary to be able to predict the output. By |
277 | default, the latest-expiring key with type |
278 | .B catacomb-rand |
279 | is used, if present; if not, no key is used. |
280 | .TP |
281 | .BI "\-l, \-\-lock" |
282 | Requests that the secret parts of the newly-generated key be encrypted |
283 | using a passphrase. |
284 | .TP |
285 | .BI "\-q, \-\-quiet" |
286 | Suppresses the progress indication which is usually generated while |
287 | time-consuming key generation tasks are being performed. |
d03ab969 |
288 | .PP |
289 | The key's type is given by the required |
290 | .I type |
291 | argument. Following the type are zero or more attributes, which are |
292 | attached to the key in the same way as for the |
293 | .B setattr |
294 | command. |
295 | .PP |
052b36d0 |
296 | The key-generation algorithms supported are as follows: |
297 | .TP |
298 | .B "binary" |
299 | Generates a plain binary key of the requested length. If the requested |
300 | key length is not a multiple of eight, the high-order bits of the first |
301 | octet of the key are zeroed. The default key length is 128 bits. |
302 | .TP |
303 | .B "des" |
304 | Generates a DES key, with parity bits. The key length must be 56, 112 |
305 | or 168; the default is 56. The low-order bit of each octet is ignored by |
306 | the DES algorithm; it is used to give each octet odd parity. |
307 | .TP |
308 | .B "rsa" |
309 | Generates a public/private key pair for use with the RSA algorithm. |
310 | .IP |
311 | The key components are |
312 | .I p |
313 | and |
314 | .IR q , |
315 | a pair of prime numbers; |
316 | .IR n , |
317 | the product of |
318 | .I p |
319 | and |
320 | .IR q ; |
321 | .IR e , |
322 | the public exponent; |
323 | .IR d , |
324 | the private exponent, chosen such that |
325 | .IR ed \ \(==\ 1 |
326 | (mod |
327 | .RI ( p \ \-\ 1)( q \ \-\ 1)); |
328 | and some other values useful for optimizing private-key operations: |
329 | .IR q \*(ss\-1\*(se\ mod\ p , |
330 | .IR d \ mod\ p \ \-\ 1, |
331 | and |
332 | .IR d \ mod\ q \ \-\ 1. |
333 | The values |
334 | .I n |
335 | and |
336 | .I e |
337 | constitute the public key; the rest must be kept secret. The key size |
338 | requested by the |
339 | .B \-b |
340 | option determines the size of the modulus |
341 | .IR n ; |
342 | the default is 1024 bits. |
343 | .IP |
344 | The key generation algorithm chooses |
345 | .I p |
346 | and |
347 | .I q |
348 | to be |
349 | .I strong |
350 | primes: both |
351 | .IR p \ \-\ 1 |
352 | and |
353 | .IR p \ +\ 1 |
354 | have large prime factors \- call them |
355 | .I r |
356 | and |
357 | .I s |
358 | respectively \- and |
359 | .IR r \ \-\ 1 |
360 | also has a large prime factor; |
361 | .I q |
362 | has similar properties. |
363 | .IP |
364 | The modulus |
365 | .I n |
366 | cannot be sensibly used as a shared parameter, since knowledge of |
367 | corrssponding public and private exponents is sufficient to be able to |
368 | factor the modulus and recover other users' private keys. |
369 | .TP |
370 | .B "dh-params" |
371 | Generates parameters for use with the Diffie-Hellman key exchange |
372 | protocol, and many related systems, such as ElGamal encryption and |
373 | signatures, and even DSA (although the DSA algorithm is probably better |
374 | for this). The parameters are a prime number |
375 | .IR q , |
376 | a larger prime number |
377 | .IR p , |
378 | and a generator |
379 | .I g |
380 | of the |
381 | .RI order- q |
382 | subgroup of the integers |
383 | .RI mod\ p . |
384 | .IP |
385 | The key size set by the |
386 | .B \-b |
387 | option determines the size of the modulus |
388 | .IR p ; |
389 | the size of the generator order |
390 | .I q |
391 | is set by the |
392 | .B \-B |
393 | option. The default modulus size is 1024 bits; if no size is specified |
394 | for |
395 | .IR q , |
396 | the parameters are chosen such that |
397 | .IR p \ =\ 2 q \ +\ 1, |
398 | and |
399 | .I |
400 | g |
401 | is assigned the value 4. This takes much longer. |
402 | .IP |
403 | If used with the |
404 | .B \-p |
405 | option, the algorithm simply copies the parameters from an existing key. |
406 | .TP |
407 | .B "dh" |
408 | Generates a public/private key pair for use with offline Diffie-Hellman, |
409 | ElGamal, DSA or similar discrete-logarithm-based systems. It selects a |
410 | private key |
411 | .IR x \ <\ q , |
412 | and computes the public key |
413 | .IR y \ =\ g\*(ssx\*(se \ mod\ p . |
414 | .TP |
415 | .B "dsa-param" |
416 | Generates parameters for the DSA algorithm. DSA parameters are also |
417 | suitable for use with Diffie-Hellman and ElGamal system. |
418 | .IP |
419 | The main difference between DSA and Diffie-Hellman parameter generation |
420 | is thatthe DSA parameter generation |
421 | algorithm creates a |
422 | .I seed |
423 | from which the parameters are derived, and, assuming that the SHA-1 hash |
424 | function is strong, it's not feasible to construct a seed from which |
425 | deliberately weak parameters are derived. The algorithm used is the one |
426 | described in the DSA standard, FIPS\ 186, extended only to allow |
427 | sequential search for a prime |
428 | .I q |
429 | and to allow arbitrary parameter sizes. The seed is stored, |
430 | Base64-encoded, as the value of the attribute |
431 | .BR seed . |
432 | .IP |
433 | The default lengths for |
434 | .I p |
435 | and |
436 | .I q |
437 | are 768 and 160 bits respectively, since the DSA standard specifies that |
438 | .I q |
439 | be 160 bits, and the choice of 768 bits for |
440 | .I p |
441 | gives commensurate security. |
442 | .TP |
443 | .B "dsa" |
444 | Generates a public/private key pair for DSA. As for Diffie-Hellman |
445 | keys, it selects a |
446 | private key |
447 | .IR x \ <\ q , |
448 | and computes the public key |
449 | .IR y \ =\ g\*(ssx\*(se \ mod\ p . |
450 | .TP |
451 | .B "bbs" |
452 | Generates a public/private key pair for the Blum-Blum-Shub random-number |
453 | generator, and the Blum-Goldwasser semantically-secure public-key |
454 | encryption system. |
455 | .IP |
456 | The key components are prime numbers |
457 | .I p |
458 | and |
459 | .IR q , |
460 | both congruent to 3 (mod\ 4), and their product |
461 | .IR n . |
462 | The public key is simply the modulus |
463 | .IR n ; |
464 | the factors |
465 | .I p |
466 | and |
467 | .I q |
468 | are the private key. |
469 | .IP |
470 | The key-generation algorithm ensures that the two primes |
471 | .I p |
472 | and |
473 | .I q |
474 | are |
475 | .I strong |
476 | (see the discussion of strong primes above, in the section on RSA keys), |
477 | and that |
478 | .RI ( p \ \-\ 1)/2 |
479 | and |
480 | .RI ( q \ \-\ 1)/2 |
481 | are relatively prime, giving a maximum possible period length. |
482 | .IP |
483 | The key size requested by the |
484 | .B \-b |
485 | option determines the length of the modulus |
486 | .IR n ; |
487 | the default length is 1024 bits. |
488 | .SS "expire" |
d03ab969 |
489 | Forces keys to immediately expire. An expired key is not chosen when a |
490 | program requests a key by its type. The keys to expire are listed by |
491 | their |
052b36d0 |
492 | .IR tag s. |
493 | .SS "delete" |
d03ab969 |
494 | Deletes keys immediately. The keys to delete are listed by their |
052b36d0 |
495 | .IR tag s. |
d03ab969 |
496 | Be careful when deleting keys. It might be a better idea |
497 | to expire keys rather than deleting them. |
052b36d0 |
498 | .SS "tag" |
499 | Sets, deletes or changes the tag attached to a key. The first tag or |
500 | keyid names the key to be modified; the second, if present specifies the |
501 | new tag to be set. If no second argument is given, the existing tag, if |
502 | any, is removed and no new tag is set. |
503 | .SS "setattr" |
d03ab969 |
504 | Attaches attributes to a key. The key to which the attributes should be |
505 | attached is given by its |
052b36d0 |
506 | .IR tag . |
d03ab969 |
507 | Each attribute has the form |
508 | .IB name = value\fR. |
509 | An attribute can be deleted by assigning it an empty value. Although |
510 | the keyring file format is capable of representing an attribute with an |
511 | empty value as distinct from a nonexistant attribute, this interface |
512 | does not allow empty attributes to be set. |
052b36d0 |
513 | .SS "comment" |
514 | Sets, deletes or changes the comment attached to a key. The first |
515 | argument is a key tag or keyid which names the key to be modified; the |
516 | second, if present, is the new comment. If no second argument is given, |
517 | the existing comment, if any, is removed, and no new comment is set. |
518 | .SS "lock" |
519 | Locks a key or key component using a passphrase. If the key is already |
520 | locked, the existing passphrase is requested, and a new passphrase is |
521 | set. |
522 | .SS "unlock" |
523 | Unlocks a passphrase-locked key or key component. If the key is not |
524 | locked, an error is reported. |
525 | .SS "list" |
d03ab969 |
526 | Lists the keys in the keyring. A couple of options are supported: |
527 | .TP |
528 | .B "\-v, \-\-verbose" |
529 | Increases the amount of information displayed for each key. Repeat for |
530 | a greater effect. |
531 | .TP |
532 | .B "\-q, \-\-quiet" |
533 | Decreases the amount of information displayed for each key. Each use |
534 | cancels a |
535 | .RB ` \-v ' |
536 | option. |
c9e31e42 |
537 | .TP |
538 | .B "\-u, \-\-utc" |
539 | Display key expiry times as UTC rather than using the local time zone. |
052b36d0 |
540 | .TP |
541 | .BI "\-f, \-\-filter " filter |
542 | Specifies a filter. Only keys and key components which match the filter |
543 | are listed. |
d03ab969 |
544 | .PP |
545 | By default, a single line of output is generated for each, showing |
546 | keyids, types, expiry and deletion dates, and comments. Additional |
547 | .RB ` \-v ' |
548 | options show more information, such as the exact time of day for expiry |
052b36d0 |
549 | and deletion, key attributes, and a dump of the actual key data. If the |
550 | verbosity level is sufficiently high, passphrases are requested to |
551 | decrypt locked keys. Make sure nobody is looking over your shoulder |
552 | when you do this! |
553 | .SS "fingerprint" |
554 | Reports a fingerprint (secure hash) on components of requested keys. |
555 | The following option is supported: |
556 | .TP |
557 | .BI "\-f, \-\-filter " filter |
558 | Specifies a filter. Only keys and key components which match the filter |
559 | are fingerprinted. The default is to only fingerprint nonsecret |
560 | components. |
561 | .PP |
562 | The keys to be fingerprinted are named by their tags or keyids given as |
563 | command line arguments. If no key tags are given, all keys which match |
564 | the filter are fingerprinted. |
565 | .SS "tidy" |
d03ab969 |
566 | Simply reads the keyring from file and writes it back again. This has |
567 | the effect of removing any deleted keys from the file. |
052b36d0 |
568 | .SS "extract" |
569 | Writes a selection of keys to a file. An option is supported: |
570 | .TP |
571 | .BI "\-f, \-\-filter " filter |
572 | Specifies a filter. Only keys and key components which match the filter |
573 | are written. |
574 | .PP |
575 | Keys extracted are written to the file named by the first argument, |
d03ab969 |
576 | which may be |
577 | .RB ` \- ' |
578 | to designate standard output. The keys to extract are listed by their |
052b36d0 |
579 | tags; if no tags are given, all keys which match the filter are |
580 | extracted. The output is a valid keyring file. |
581 | .SS "merge" |
d03ab969 |
582 | Merges the keys from the named |
583 | .IR file , |
584 | which may be |
585 | .RB ` \- ' |
586 | to designate standard input, with the keyring. Keys already in the |
587 | keyring are not overwritten: you must explicitly remove them first if |
588 | you want them to be replaced during the merge. |
d03ab969 |
589 | .SH "SEE ALSO" |
590 | .BR keyring (5). |
591 | .SH AUTHOR |
592 | Mark Wooding, <mdw@nsict.org> |
593 | |