d03ab969 |
1 | .\" -*-nroff-*- |
052b36d0 |
2 | .ie t \{\ |
8404fd75 |
3 | . if \n(.g \{\ |
4 | . fam P |
5 | . \} |
052b36d0 |
6 | . ds ss \s8\u |
7 | . ds se \d\s0 |
1476eebc |
8 | . ds us \s8\d |
9 | . ds ue \u\s0 |
8404fd75 |
10 | . ds *b \(*b |
052b36d0 |
11 | .\} |
12 | .el \{\ |
13 | . ds ss ^ |
14 | . ds se |
1476eebc |
15 | . ds us _ |
8404fd75 |
16 | . ds ue |
17 | . ds *b \fIbeta\fP |
052b36d0 |
18 | .\} |
c65df279 |
19 | .de VS |
20 | .sp 1 |
21 | .RS |
22 | .nf |
23 | .ft B |
24 | .. |
25 | .de VE |
26 | .ft R |
27 | .fi |
28 | .RE |
29 | .sp 1 |
30 | .. |
d07dfe80 |
31 | .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library" |
d03ab969 |
32 | .SH NAME |
33 | key \- simple key management system |
34 | .SH SYNOPSIS |
35 | .B key |
36 | .RB [ \-k |
37 | .IR keyring ] |
38 | .I command |
39 | .PP |
40 | where |
41 | .I command |
42 | is one of: |
43 | .PP |
c65df279 |
44 | .B help |
45 | .RI [ command ...] |
46 | .br |
47 | .B show |
48 | .RI [ item ...] |
49 | .br |
d03ab969 |
50 | .B add |
d07dfe80 |
51 | .RB [ \-lqrLS ] |
052b36d0 |
52 | .RB [ \-a |
53 | .IR alg ] |
54 | .RB [ \-b | \-B |
d03ab969 |
55 | .IR bits ] |
052b36d0 |
56 | .RB [ \-p |
57 | .IR param ] |
d07dfe80 |
58 | .RB [ \-R |
052b36d0 |
59 | .IR tag ] |
60 | .br |
61 | \h'8n' |
c65df279 |
62 | .RB [ \-A |
63 | .IR seed-alg ] |
64 | .RB [ \-s |
65 | .IR seed ] |
66 | .RB [ \-n |
67 | .IR bits ] |
68 | .br |
69 | \h'8n' |
d03ab969 |
70 | .RB [ \-e |
71 | .IR expire ] |
052b36d0 |
72 | .RB [ \-t |
73 | .IR tag ] |
d03ab969 |
74 | .RB [ \-c |
75 | .IR comment ] |
eb31b00e |
76 | .RB [ \-C |
77 | .IR curve ] |
78 | .br |
79 | \h'8n' |
d03ab969 |
80 | .I type |
81 | .IR attr ... |
82 | .br |
83 | .B expire |
052b36d0 |
84 | .IR tag ... |
d03ab969 |
85 | .br |
86 | .B delete |
052b36d0 |
87 | .IR tag ... |
88 | .br |
89 | .B tag |
90 | .I tag |
91 | .RI [ new-tag ] |
92 | .br |
93 | .B comment |
94 | .I tag |
95 | .RI [ comment ] |
d03ab969 |
96 | .br |
97 | .B setattr |
052b36d0 |
98 | .I tag |
d03ab969 |
99 | .IR attr ... |
100 | .br |
e9be047b |
101 | .B getattr |
102 | .I tag |
103 | .I attr |
104 | .br |
052b36d0 |
105 | .B lock |
106 | .I qtag |
107 | .br |
108 | .B unlock |
109 | .I qtag |
110 | .br |
d03ab969 |
111 | .B list |
052b36d0 |
112 | .RB [ \-uqv ] |
113 | .RB [ \-f |
114 | .IR filter ] |
115 | .RI [ tag ...] |
116 | .br |
117 | .B fingerprint |
118 | .RB [ \-f |
119 | .IR filter ] |
b817bfc6 |
120 | .RB [ \-a |
121 | .IR hash ] |
052b36d0 |
122 | .RI [ tag ...] |
d03ab969 |
123 | .br |
58507325 |
124 | .B verify |
125 | .RB [ \-f |
126 | .IR filter ] |
127 | .RB [ \-a |
128 | .IR hash ] |
129 | .I tag |
130 | .I fingerprint |
131 | .br |
d03ab969 |
132 | .B tidy |
133 | .br |
134 | .B extract |
052b36d0 |
135 | .RB [ \-f |
136 | .IR filter ] |
d03ab969 |
137 | .I file |
052b36d0 |
138 | .RI [ tag ...] |
d03ab969 |
139 | .br |
140 | .B merge |
141 | .I file |
142 | .SH DESCRIPTION |
143 | The |
144 | .B key |
145 | command performs useful operations on Catacomb keyring files. It |
146 | provides a number of subcommands, by which the various operations may be |
147 | carried out. |
148 | .SS "Global options" |
149 | Before the command name, |
150 | .I "global options" |
151 | may be given. The following global options are supported: |
152 | .TP |
c65df279 |
153 | .BR "\-h, \-\-help " [ \fIcommand ...] |
d03ab969 |
154 | Writes a brief summary of |
155 | .BR key 's |
156 | various options to standard output, and |
c65df279 |
157 | returns a successful exit status. With command names, gives help on |
158 | those commands. |
d03ab969 |
159 | .TP |
160 | .B "\-v, \-\-version" |
161 | Writes the program's version number to standard output, and returns a |
162 | successful exit status. |
163 | .TP |
164 | .B "\-u, \-\-usage" |
165 | Writes a very terse command line summary to standard output, and returns |
166 | a successful exit status. |
167 | .TP |
c9e31e42 |
168 | .BI "\-k, \-\-keyring " file |
d03ab969 |
169 | Names the keyring file which |
170 | .B key |
171 | is to process. The default keyring, used if this option doesn't specify |
172 | one, is the file named |
173 | .B keyring |
174 | in the current directory. The keyring must be stored in a regular file: |
175 | pipes, sockets, devices etc. are not allowed. |
176 | The |
177 | .B key |
178 | program attempts to lock the keyring before accessing it, using |
179 | .BR fcntl (2) |
180 | locking. It will however time out after a short while (10 seconds) and |
181 | report a failure. |
182 | .SS Concepts |
183 | In addition to the actual key data itself, a Catacomb key has a number |
184 | of other pieces of information attached to it: |
185 | .TP |
052b36d0 |
186 | .B "keyid" |
187 | Every key has a 32-bit identifying number, written in hexadecimal. |
188 | Keyids are not actually related to the key contents: they're generated |
189 | randomly. Applications use keyids to refer to specific keys; users are |
190 | probably better off with tags and types. A |
d03ab969 |
191 | .I deleted |
192 | key cannot be looked up by keyid. |
193 | .TP |
052b36d0 |
194 | .B "tag" |
195 | A key's tag is a unique string which can be used by users and |
196 | applications to identify the key. Tag strings may not contain spaces, |
197 | colons or dots. A |
198 | .I deleted |
199 | key cannot be looked up by tag. Whenever a tag name is wanted, a hex |
200 | keyid or key type string can be given instead. |
201 | .TP |
202 | .B "type" |
d03ab969 |
203 | A key's type string describes what the key may be used for. The type |
204 | string is arbitrary, except that it may not contain whitespace |
052b36d0 |
205 | characters, dots or colons. Applications use key types to obtain an |
206 | arbitrary but suitable key for some purpose. An |
d03ab969 |
207 | .I expired |
052b36d0 |
208 | key cannot be looked up by type, but may be looked up by keyid or tag. |
209 | .TP |
210 | .B "key encoding" |
211 | There are a number of different ways in which keys can be represented, |
212 | according to the uses to which the key will be put. Most symmetric |
213 | algorithms use |
214 | .I binary |
215 | keys. Keys used with number-theoretic systems (like most common |
216 | public-key systems) use |
217 | .I "multiprecision integer" |
8404fd75 |
218 | keys. Elliptic curve systems use |
219 | .I "curve point" |
220 | keys, which are either a pair of integers representing field elements, |
221 | or a `point at infinity'. Algorithms which require several key |
222 | constituents (again, like most public-key systems) use |
052b36d0 |
223 | .I structured |
8404fd75 |
224 | keys, which consist of a collection of named parts. It's possible to |
225 | store an |
226 | .I "ASCII string" |
227 | as a key, though this is usually done as a component of a structured |
228 | key. Finally, keys (including structured keys) can be encrypted. |
052b36d0 |
229 | .TP |
230 | .B "filter" |
231 | Keys and key components may be selected by a filter expression, a |
232 | sequence of flag names separated by commas. Flags are: |
233 | .BR binary , |
234 | .BR integer , |
8404fd75 |
235 | .BR struct , |
236 | .BR ec , |
237 | .BR string , |
052b36d0 |
238 | or |
239 | .B encrypt |
240 | (describing the key encoding); |
241 | .BR symmetric , |
242 | .BR private , |
8404fd75 |
243 | .BR public , |
052b36d0 |
244 | or |
245 | .B shared |
246 | (describing the category of key); |
247 | .B burn |
248 | and its negation |
249 | .B \-burn |
250 | (whether the key should be erased from memory after use); and |
251 | .B secret |
252 | and its negation |
253 | .B \-secret |
254 | (whether the key is safe to divulge). |
255 | .TP |
256 | .B "qualified tag" |
257 | A key component may be identified by the key's tag (or keyid, or type). |
258 | Subcomponents of structured keys are identified by following the tag by |
259 | a dot and the name of the subcomponent. |
d03ab969 |
260 | .TP |
261 | .B "expiry time" |
262 | Most keys expire after a certain amount of time. Once a key has |
263 | expired, it will no longer be chosen as a result of a lookup by key |
264 | type. However, it is not deleted until its deletion time is also |
265 | reached. |
266 | .TP |
267 | .B "deletion time" |
268 | A key's deletion time is the latest expiry time of any of the objects |
269 | which require that key. For example, a key used for authenticating |
270 | cryptographic cookies should have its deletion time set to the longest |
052b36d0 |
271 | expiry time of any of the cookies it can authenticate. Once a key's |
272 | deletion time is passed, it can no longer be referred to by |
d03ab969 |
273 | applications, and will be removed from the keyring next time it's |
274 | written to disk. |
275 | .TP |
052b36d0 |
276 | .B "comment" |
d03ab969 |
277 | A key may be given a comment when it's created. The comment is for the |
278 | benefit of users, and isn't interpreted by applications at all. |
279 | (Hopefully.) |
280 | .TP |
052b36d0 |
281 | .B "attributes" |
d03ab969 |
282 | A key as zero or more name/value pairs. The names and values are |
283 | arbitrary strings, except they may not contain null bytes. Some |
284 | attributes may have meaning for particular applications or key types; |
285 | others may be assigned global meanings in future. |
286 | .SH "COMMAND REFERENCE" |
c65df279 |
287 | .SS help |
288 | The |
289 | .B help |
290 | command behaves exactly as the |
291 | .B \-\-help |
292 | option. With no arguments, it shows an overview of |
293 | .BR key 's |
294 | options; with arguments, it describes the named subcommands. |
295 | .SS show |
296 | The |
297 | .B show |
298 | command prints various lists of tokens understood by |
299 | .BR key . |
300 | With no arguments, it prints all of the lists; with arguments, it prints |
301 | just the named lists, in order. The recognized lists can be enumerated |
302 | using the |
303 | .VS |
304 | key show list |
305 | .VE |
306 | command. The lists are as follows. |
307 | .TP |
308 | .B list |
309 | The lists which can be enumerated by the |
310 | .B show |
311 | command. |
312 | .TP |
313 | .B hash |
314 | The hash functions which can be used with the |
315 | .B fingerprint |
58507325 |
316 | and |
317 | .B verify |
318 | commands. |
c65df279 |
319 | .TP |
320 | .B ec |
321 | The built-in elliptic curves which can be used with the |
322 | .B add \-a ec |
323 | command. |
324 | .TP |
325 | .B dh |
326 | The built-in Diffie-Hellman groups which can be used with the |
327 | .B add \-a dh |
328 | command. |
329 | .TP |
330 | .B keygen |
331 | The key-generation algorithms which are acceptable to the |
332 | .B \-a |
333 | option of the |
334 | .B add |
335 | command. |
336 | .TP |
337 | .B seed |
338 | The pseudorandom generators which are acceptable to the |
339 | .B \-s |
340 | option of the |
341 | .B add |
342 | command. |
d03ab969 |
343 | .SS add |
344 | The |
345 | .B add |
346 | command creates a new key and adds it to the keyring. The command |
347 | accepts the following options: |
348 | .TP |
052b36d0 |
349 | .BI "\-a, \-\-algorithm " alg |
350 | Selects a key generation algorithm. The default algorithm is |
351 | .BR binary ; |
c65df279 |
352 | the different algorithms are described below. The command |
353 | .B key show keygen |
354 | lists the recognized key-generation algorithms. |
052b36d0 |
355 | .TP |
c9e31e42 |
356 | .BI "\-b, \-\-bits " bits |
d03ab969 |
357 | The length of the key to generate, in bits. The default, if this option |
052b36d0 |
358 | is not supplied, depends on the key-generation algorithm. |
359 | .TP |
360 | .BI "\-B, \-\-qbits " bits |
361 | The length of the subsidiary key or parameter, in bits. Not all |
362 | key-generation algorithms have a subsidiary key size. |
363 | .TP |
364 | .BI "\-p, \-\-parameters " tag |
365 | Selects a key containing parameter values to copy. Not all |
4739c68a |
366 | key-generation algorithms allow the use of shared parameters. A new key |
367 | also inherits attributes from its parameter key. |
d03ab969 |
368 | .TP |
c65df279 |
369 | .BI "\-A, \-\-seedalg " seed-alg |
370 | Use the deterministic random number generator algorithm |
371 | .I seed-alg |
372 | to generate the key. Use |
373 | .I before |
374 | the |
375 | .B \-s |
376 | or |
377 | .B \-n |
378 | options; without one of these, |
379 | .B \-A |
380 | has no effect. The default algorithm is |
381 | .BR rmd160-mgf . |
382 | The command |
383 | .B key show seed |
384 | shows a list of recognized seeding algorithms. The seeding algorithm |
385 | used to generate a key is recorded as the key's |
386 | .B seedalg |
387 | attribute. |
388 | .TP |
389 | .BI "\-s, \-\-seed " seed |
390 | Generate the key deterministically using the given |
391 | .IR seed , |
392 | which should be a Base64-encoded binary string. This is mainly useful |
393 | for parameters keys (types |
394 | .BR dsa-param |
395 | and |
396 | .BR dh-param ), |
397 | to demonstrate that a set of parameters has been generated in an honest |
398 | fashion. The |
399 | .B dsarand |
400 | generation algorithm can be used to generate |
401 | .B dsa-param |
402 | keys as required by FIPS186. The requested seed is recorded, |
403 | Base64-encoded, as the new key's |
404 | .B seed |
405 | attribute. |
406 | .TP |
407 | .BI "\-n, \-\-newseed " bits |
408 | Generate a new seed, with the given length in |
409 | .IR bits . |
410 | The generated seed is recorded, Base64-encoded, as the new key's |
411 | .B seed |
412 | attribute. |
413 | .TP |
c9e31e42 |
414 | .BI "\-e, \-\-expire " expire |
d03ab969 |
415 | The expiry date for the generated key. This may be the string |
416 | .RB ` forever ' |
417 | if the key should never expire automatically, or any date acceptable to |
418 | the |
419 | .BR getdate (3) |
420 | library function. Briefly, |
421 | .B getdate |
422 | understands absolute dates such as |
423 | .RB ` 1999-08-02 ' |
424 | or |
425 | .RB ` "August 2nd, 1999" ', |
426 | and (perhaps more usefully) relative dates such as |
427 | .RB ` "+2 weeks" '. |
428 | The default is to allow a 2 week expiry, which isn't useful. |
429 | .TP |
c9e31e42 |
430 | .BI "\-c, \-\-comment " comment |
d03ab969 |
431 | Sets a comment for the key. The default is not to attach a comment. |
052b36d0 |
432 | .TP |
eb31b00e |
433 | .BI "\-C, \-\-curve " curve-spec |
434 | Use the elliptic curve described by |
435 | .I curve-spec |
436 | when generating elliptic curve parameters. |
437 | .TP |
052b36d0 |
438 | .BI "\-t, \-\-tag " tag |
439 | Selects a tag string for the key. The default is not to set a tag. It |
440 | is an error to select a tag which already exists. |
441 | .TP |
d07dfe80 |
442 | .BI "\-r, \-\-retag" |
443 | If a |
444 | .B \-t |
445 | option is given, remove this tag from any key which already has it. |
446 | .TP |
447 | .BI "\-R, \-\-rand-id " tag |
052b36d0 |
448 | Selects the key to use for the random number generator. Catacomb's |
449 | random number generator can be |
450 | .IR keyed , |
451 | so that, even if the inputs to the generator are compromised, knowledge |
452 | of the key is also necessary to be able to predict the output. By |
453 | default, the latest-expiring key with type |
454 | .B catacomb-rand |
455 | is used, if present; if not, no key is used. |
456 | .TP |
457 | .BI "\-l, \-\-lock" |
458 | Requests that the secret parts of the newly-generated key be encrypted |
459 | using a passphrase. |
460 | .TP |
461 | .BI "\-q, \-\-quiet" |
462 | Suppresses the progress indication which is usually generated while |
463 | time-consuming key generation tasks are being performed. |
1476eebc |
464 | .TP |
465 | .BI "\-L, --lim-lee" |
466 | When generating Diffie-Hellman parameters, generate a Lim-Lee prime |
467 | rather than a random (or safe) prime. See the details on Diffie-Hellman |
468 | key generation below. |
469 | .TP |
470 | .BI "\-S, --subgroup" |
471 | When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a |
472 | generator of a prime-order subgroup rather than a subgroup of order |
473 | .RI ( p "- 1)/2." |
d03ab969 |
474 | .PP |
475 | The key's type is given by the required |
476 | .I type |
477 | argument. Following the type are zero or more attributes, which are |
478 | attached to the key in the same way as for the |
479 | .B setattr |
480 | command. |
481 | .PP |
052b36d0 |
482 | The key-generation algorithms supported are as follows: |
483 | .TP |
484 | .B "binary" |
485 | Generates a plain binary key of the requested length. If the requested |
486 | key length is not a multiple of eight, the high-order bits of the first |
487 | octet of the key are zeroed. The default key length is 128 bits. |
488 | .TP |
489 | .B "des" |
490 | Generates a DES key, with parity bits. The key length must be 56, 112 |
491 | or 168; the default is 56. The low-order bit of each octet is ignored by |
492 | the DES algorithm; it is used to give each octet odd parity. |
493 | .TP |
494 | .B "rsa" |
495 | Generates a public/private key pair for use with the RSA algorithm. |
496 | .IP |
497 | The key components are |
498 | .I p |
499 | and |
500 | .IR q , |
501 | a pair of prime numbers; |
502 | .IR n , |
503 | the product of |
504 | .I p |
505 | and |
506 | .IR q ; |
507 | .IR e , |
508 | the public exponent; |
509 | .IR d , |
510 | the private exponent, chosen such that |
511 | .IR ed \ \(==\ 1 |
512 | (mod |
513 | .RI ( p \ \-\ 1)( q \ \-\ 1)); |
514 | and some other values useful for optimizing private-key operations: |
515 | .IR q \*(ss\-1\*(se\ mod\ p , |
516 | .IR d \ mod\ p \ \-\ 1, |
517 | and |
518 | .IR d \ mod\ q \ \-\ 1. |
519 | The values |
520 | .I n |
521 | and |
522 | .I e |
523 | constitute the public key; the rest must be kept secret. The key size |
524 | requested by the |
525 | .B \-b |
526 | option determines the size of the modulus |
527 | .IR n ; |
528 | the default is 1024 bits. |
529 | .IP |
530 | The key generation algorithm chooses |
531 | .I p |
532 | and |
533 | .I q |
534 | to be |
535 | .I strong |
536 | primes: both |
537 | .IR p \ \-\ 1 |
538 | and |
539 | .IR p \ +\ 1 |
540 | have large prime factors \- call them |
541 | .I r |
542 | and |
543 | .I s |
544 | respectively \- and |
545 | .IR r \ \-\ 1 |
546 | also has a large prime factor; |
547 | .I q |
548 | has similar properties. |
549 | .IP |
550 | The modulus |
551 | .I n |
552 | cannot be sensibly used as a shared parameter, since knowledge of |
553 | corrssponding public and private exponents is sufficient to be able to |
554 | factor the modulus and recover other users' private keys. |
555 | .TP |
eb31b00e |
556 | .B "dh-param" |
052b36d0 |
557 | Generates parameters for use with the Diffie-Hellman key exchange |
558 | protocol, and many related systems, such as ElGamal encryption and |
1476eebc |
559 | signatures, and even DSA. (The separate DSA algorithm uses the |
560 | generator described in FIPS186-1.) |
561 | .IP |
562 | The Diffie-Hellman parameters are a prime modulus |
563 | .I p |
052b36d0 |
564 | and a generator |
565 | .I g |
1476eebc |
566 | of a subgroup of |
567 | .BR Z / \c |
568 | .IB p Z |
569 | of order |
570 | .IR q . |
571 | The |
052b36d0 |
572 | .B \-b |
1476eebc |
573 | option controls the size of the modulus |
052b36d0 |
574 | .IR p ; |
1476eebc |
575 | the default size is 1024 bits. |
576 | .IP |
577 | If no |
052b36d0 |
578 | .I q |
1476eebc |
579 | size is selected using the |
052b36d0 |
580 | .B \-B |
1476eebc |
581 | option and the Lim-Lee prime option is disabled, then |
582 | .I p |
583 | is chosen to be a `safe' prime (i.e., |
052b36d0 |
584 | .IR p \ =\ 2 q \ +\ 1, |
1476eebc |
585 | with |
586 | .I q |
8404fd75 |
587 | prime). Finding safe primes takes a very long time. In this case, the |
588 | value of |
1476eebc |
589 | .I g |
590 | is fixed as 4. |
591 | .IP |
592 | If a size is chosen for |
593 | .I q |
594 | and Lim-Lee primes are not selected then the prime |
595 | .I q |
596 | is generated and |
597 | .I p |
598 | is chosen so that |
599 | .IR p \ \-\ 1 |
600 | is a multiple of |
601 | .IR q . |
602 | .IP |
603 | If the |
604 | .B \-L |
605 | option was given Lim-Lee primes are selected: the parameters are chosen |
606 | such that |
607 | .IR p \ =\ 2\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1, |
608 | where the |
609 | .IR q \*(us i\*(ue |
610 | are primes at least as large as the setting given by the |
611 | .B \-B |
612 | option (or 256 bits, if no setting was given). |
052b36d0 |
613 | .IP |
1476eebc |
614 | If the |
615 | .B \-S |
616 | option was given, the generator |
617 | .I g |
618 | is chosen to generate the subgroup of order |
619 | .IR q \*(us0\*(ue; |
620 | otherwise, |
621 | .I g |
622 | will generate the group of order |
623 | .RI ( p \ \-\ 1)/2\ =\ q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ... |
8404fd75 |
624 | .IP |
625 | Finally, the |
626 | .B \-C |
627 | option can be given, in which case the parameters are taken directly |
628 | from the provided group specification, which may either be the the name |
629 | of one of the built-in groups (say |
58507325 |
630 | .B "key show dh" |
8404fd75 |
631 | for a list) or a triple |
632 | .RI ( p ,\ q ,\ g ). |
633 | separated by commas. No random generation is done in this case: the |
634 | given parameters are simply stored. |
052b36d0 |
635 | .TP |
636 | .B "dh" |
637 | Generates a public/private key pair for use with offline Diffie-Hellman, |
638 | ElGamal, DSA or similar discrete-logarithm-based systems. It selects a |
639 | private key |
640 | .IR x \ <\ q , |
641 | and computes the public key |
642 | .IR y \ =\ g\*(ssx\*(se \ mod\ p . |
643 | .TP |
644 | .B "dsa-param" |
645 | Generates parameters for the DSA algorithm. DSA parameters are also |
646 | suitable for use with Diffie-Hellman and ElGamal system. |
647 | .IP |
648 | The main difference between DSA and Diffie-Hellman parameter generation |
649 | is thatthe DSA parameter generation |
650 | algorithm creates a |
651 | .I seed |
652 | from which the parameters are derived, and, assuming that the SHA-1 hash |
653 | function is strong, it's not feasible to construct a seed from which |
654 | deliberately weak parameters are derived. The algorithm used is the one |
655 | described in the DSA standard, FIPS\ 186, extended only to allow |
656 | sequential search for a prime |
657 | .I q |
658 | and to allow arbitrary parameter sizes. The seed is stored, |
659 | Base64-encoded, as the value of the attribute |
660 | .BR seed . |
661 | .IP |
662 | The default lengths for |
663 | .I p |
664 | and |
665 | .I q |
666 | are 768 and 160 bits respectively, since the DSA standard specifies that |
667 | .I q |
668 | be 160 bits, and the choice of 768 bits for |
669 | .I p |
670 | gives commensurate security. |
671 | .TP |
672 | .B "dsa" |
673 | Generates a public/private key pair for DSA. As for Diffie-Hellman |
674 | keys, it selects a |
675 | private key |
676 | .IR x \ <\ q , |
677 | and computes the public key |
678 | .IR y \ =\ g\*(ssx\*(se \ mod\ p . |
679 | .TP |
680 | .B "bbs" |
681 | Generates a public/private key pair for the Blum-Blum-Shub random-number |
682 | generator, and the Blum-Goldwasser semantically-secure public-key |
683 | encryption system. |
684 | .IP |
685 | The key components are prime numbers |
686 | .I p |
687 | and |
688 | .IR q , |
689 | both congruent to 3 (mod\ 4), and their product |
690 | .IR n . |
691 | The public key is simply the modulus |
692 | .IR n ; |
693 | the factors |
694 | .I p |
695 | and |
696 | .I q |
697 | are the private key. |
698 | .IP |
699 | The key-generation algorithm ensures that the two primes |
700 | .I p |
701 | and |
702 | .I q |
703 | are |
704 | .I strong |
705 | (see the discussion of strong primes above, in the section on RSA keys), |
706 | and that |
707 | .RI ( p \ \-\ 1)/2 |
708 | and |
709 | .RI ( q \ \-\ 1)/2 |
710 | are relatively prime, giving a maximum possible period length. |
711 | .IP |
712 | The key size requested by the |
713 | .B \-b |
714 | option determines the length of the modulus |
715 | .IR n ; |
716 | the default length is 1024 bits. |
eb31b00e |
717 | .TP |
718 | .B "ec-param" |
719 | Store an elliptic curve specification. If no explicit |
720 | .I curve-spec |
721 | is given (the |
722 | .RB ` \-C ' |
723 | option) then a curve is chosen whose order is about the size given by the |
724 | .RB ` \-b ' |
725 | option (default is 256 bits). |
726 | .IP |
727 | A |
728 | .I curve-spec |
729 | can be given explicitly (in which case |
730 | .RB ` \-b ' |
731 | is ignored). It can either be the name of a built-in curve (say |
58507325 |
732 | .B "key show ec" |
eb31b00e |
733 | for a list of curve names) or a full specification. The curve is |
734 | checked for correctness and security according to the SEC1 |
735 | specification: failed checks cause a warning to be issued to standard |
736 | error (though the program continues anyway). The check can be |
737 | suppressed using the |
738 | .RB ` \-q ' |
739 | option. |
740 | .IP |
741 | A curve specification consists of the following elements optionally |
742 | separated by whitespace: a |
743 | .IR "field type" , |
744 | which is one of |
745 | .BR "prime" , |
746 | .BR "niceprime" , |
8404fd75 |
747 | .BR "binpoly" , |
748 | .or |
749 | .BR "binnorm" ; |
eb31b00e |
750 | an optional |
751 | .RB ` : '; |
752 | the field modulus |
753 | .IR p ; |
8404fd75 |
754 | if the field type is |
755 | .B binnorm |
756 | then an optional |
757 | .RB ` , ' |
758 | and the representation of the normal element \*(*b; an optional |
eb31b00e |
759 | .RB ` / '; |
760 | a |
761 | .IR "curve type" , |
762 | which is one of |
763 | .BR "prime" , |
764 | .BR "primeproj" , |
765 | .BR "bin" , |
766 | and |
767 | .BR "binproj" |
768 | (the `proj' types currently have much better performance); |
769 | an optional |
770 | .RB ` : '; |
771 | the two field-element parameters |
772 | .I a |
773 | and |
774 | .IR b |
775 | which define the elliptic curve |
776 | .IR E , |
777 | separated by an optional |
778 | .RB ` , '; |
779 | an optional |
780 | .RB ` / '; |
781 | the |
782 | .IR x - |
783 | and |
784 | .IR y -coordinates |
785 | of the generator point |
786 | .IR G , |
787 | separated by an optional |
788 | .RB ` , '; |
789 | an optional |
790 | .RB ` : '; |
791 | the order |
792 | .I r |
793 | of the group generated by |
794 | .IR G ; |
795 | an optional |
796 | .RB ` * '; |
797 | and the |
798 | .I cofactor |
799 | .I h |
800 | = |
801 | .RI # E / r . |
802 | .TP |
803 | .B "ec" |
804 | Generate a private scalar and a corresponding public point on an |
805 | elliptic curve. See |
806 | .B ec-param |
807 | above for how to specify elliptic curve parameter sets. The scalar |
808 | .I x |
809 | is chosen unformly between 0 and the curve order |
810 | .IR r ; |
811 | the public point is then |
812 | .I x |
813 | \(mu |
814 | .IR G . |
052b36d0 |
815 | .SS "expire" |
d03ab969 |
816 | Forces keys to immediately expire. An expired key is not chosen when a |
817 | program requests a key by its type. The keys to expire are listed by |
818 | their |
052b36d0 |
819 | .IR tag s. |
820 | .SS "delete" |
d03ab969 |
821 | Deletes keys immediately. The keys to delete are listed by their |
052b36d0 |
822 | .IR tag s. |
d03ab969 |
823 | Be careful when deleting keys. It might be a better idea |
824 | to expire keys rather than deleting them. |
052b36d0 |
825 | .SS "tag" |
826 | Sets, deletes or changes the tag attached to a key. The first tag or |
827 | keyid names the key to be modified; the second, if present specifies the |
828 | new tag to be set. If no second argument is given, the existing tag, if |
d07dfe80 |
829 | any, is removed and no new tag is set. It is an error to set a tag |
830 | which already exists on another key, unless you give the |
831 | .B \-r |
832 | option, which removes the tag first. |
052b36d0 |
833 | .SS "setattr" |
d03ab969 |
834 | Attaches attributes to a key. The key to which the attributes should be |
835 | attached is given by its |
052b36d0 |
836 | .IR tag . |
d03ab969 |
837 | Each attribute has the form |
838 | .IB name = value\fR. |
839 | An attribute can be deleted by assigning it an empty value. Although |
840 | the keyring file format is capable of representing an attribute with an |
841 | empty value as distinct from a nonexistant attribute, this interface |
842 | does not allow empty attributes to be set. |
e9be047b |
843 | .SS "getattr" |
844 | Fetches a single attribute of a key. The key whose attribute is to be |
845 | read is given by its |
846 | .IR tag . |
847 | The attribute's value is written to standard output followed by a |
848 | newline. If the key or attribute is absent, a message is written to |
849 | standard error and the program exits nonzero. |
052b36d0 |
850 | .SS "comment" |
851 | Sets, deletes or changes the comment attached to a key. The first |
852 | argument is a key tag or keyid which names the key to be modified; the |
853 | second, if present, is the new comment. If no second argument is given, |
854 | the existing comment, if any, is removed, and no new comment is set. |
855 | .SS "lock" |
856 | Locks a key or key component using a passphrase. If the key is already |
857 | locked, the existing passphrase is requested, and a new passphrase is |
858 | set. |
859 | .SS "unlock" |
860 | Unlocks a passphrase-locked key or key component. If the key is not |
861 | locked, an error is reported. |
862 | .SS "list" |
d03ab969 |
863 | Lists the keys in the keyring. A couple of options are supported: |
864 | .TP |
865 | .B "\-v, \-\-verbose" |
866 | Increases the amount of information displayed for each key. Repeat for |
867 | a greater effect. |
868 | .TP |
869 | .B "\-q, \-\-quiet" |
870 | Decreases the amount of information displayed for each key. Each use |
871 | cancels a |
872 | .RB ` \-v ' |
873 | option. |
c9e31e42 |
874 | .TP |
875 | .B "\-u, \-\-utc" |
876 | Display key expiry times as UTC rather than using the local time zone. |
052b36d0 |
877 | .TP |
878 | .BI "\-f, \-\-filter " filter |
879 | Specifies a filter. Only keys and key components which match the filter |
880 | are listed. |
d03ab969 |
881 | .PP |
882 | By default, a single line of output is generated for each, showing |
883 | keyids, types, expiry and deletion dates, and comments. Additional |
884 | .RB ` \-v ' |
885 | options show more information, such as the exact time of day for expiry |
052b36d0 |
886 | and deletion, key attributes, and a dump of the actual key data. If the |
887 | verbosity level is sufficiently high, passphrases are requested to |
888 | decrypt locked keys. Make sure nobody is looking over your shoulder |
889 | when you do this! |
890 | .SS "fingerprint" |
891 | Reports a fingerprint (secure hash) on components of requested keys. |
58507325 |
892 | The following options are supported: |
052b36d0 |
893 | .TP |
894 | .BI "\-f, \-\-filter " filter |
895 | Specifies a filter. Only keys and key components which match the filter |
896 | are fingerprinted. The default is to only fingerprint nonsecret |
897 | components. |
b817bfc6 |
898 | .TP |
899 | .BI "\-a, \-\-algorithm " hash |
900 | Names the hashing algorithm. Run |
58507325 |
901 | .B key show hash |
b817bfc6 |
902 | for a list of hashing algorithms. The default is |
903 | .BR rmd160 . |
052b36d0 |
904 | .PP |
905 | The keys to be fingerprinted are named by their tags or keyids given as |
906 | command line arguments. If no key tags are given, all keys which match |
b817bfc6 |
907 | the filter are fingerprinted. See |
908 | .BR keyring (5) |
909 | for a description of how key fingerprints are computed. |
58507325 |
910 | .SS "verify" |
911 | Check a key's fingerprint against a reference copy. The following |
912 | options are supported: |
913 | .TP |
914 | .BI "\-f, \-\-filter " filter |
915 | Specifies a filter. Only key components which match the filter are |
916 | hashed. The default is to only fingerprint nonsecret components. An |
917 | error is reported if no part of the key matches. |
918 | .TP |
919 | .BI "\-a, \-\-algorithm " hash |
920 | Names the hashing algorithm. Run |
921 | .B key show hash |
922 | for a list of hashing algorithms. The default is |
923 | .BR rmd160 . |
924 | .PP |
925 | The reference fingerprint is given as hex, in upper or lower case. The |
926 | hash may contain hyphens, colons and whitespace. Other characters are |
927 | not permitted. |
052b36d0 |
928 | .SS "tidy" |
d03ab969 |
929 | Simply reads the keyring from file and writes it back again. This has |
930 | the effect of removing any deleted keys from the file. |
052b36d0 |
931 | .SS "extract" |
932 | Writes a selection of keys to a file. An option is supported: |
933 | .TP |
934 | .BI "\-f, \-\-filter " filter |
935 | Specifies a filter. Only keys and key components which match the filter |
936 | are written. |
937 | .PP |
938 | Keys extracted are written to the file named by the first argument, |
d03ab969 |
939 | which may be |
940 | .RB ` \- ' |
941 | to designate standard output. The keys to extract are listed by their |
052b36d0 |
942 | tags; if no tags are given, all keys which match the filter are |
943 | extracted. The output is a valid keyring file. |
944 | .SS "merge" |
d03ab969 |
945 | Merges the keys from the named |
946 | .IR file , |
947 | which may be |
948 | .RB ` \- ' |
949 | to designate standard input, with the keyring. Keys already in the |
950 | keyring are not overwritten: you must explicitly remove them first if |
951 | you want them to be replaced during the merge. |
d03ab969 |
952 | .SH "SEE ALSO" |
953 | .BR keyring (5). |
954 | .SH AUTHOR |
f387fcb1 |
955 | Mark Wooding, <mdw@distorted.org.uk> |
d03ab969 |
956 | |