Commit | Line | Data |
---|---|---|
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 |
4e67e30b | 51 | .RB [ \-lqrLKS ] |
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" |
ef3b232f MW |
282 | A key has zero or more name/value pairs. The names and values are |
283 | arbitrary strings, except that they may not contain null bytes. Some | |
d03ab969 | 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 | |
ef3b232f | 326 | The built-in Diffie\(enHellman groups which can be used with the |
c65df279 | 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 |
4e67e30b | 465 | .BI "\-L, \-\-lim-lee" |
ef3b232f MW |
466 | When generating Diffie\(enHellman parameters, generate a Lim\(enLee |
467 | prime rather than a random (or safe) prime. See the details on | |
468 | Diffie\(enHellman key generation below. | |
1476eebc | 469 | .TP |
4e67e30b | 470 | .BI "\-K, \-\-kcdsa" |
ef3b232f MW |
471 | When generating Diffie\(enHellman parameters, generate a KCDSA-style |
472 | Lim\(enLee prime rather than a random (or safe) prime. See the details | |
473 | on Diffie\(enHellman key generation below. | |
4e67e30b MW |
474 | .TP |
475 | .BI "\-S, \-\-subgroup" | |
ef3b232f MW |
476 | When generating Diffie\(enHellman parameters with a Lim\(enLee prime, |
477 | choose a generator of a prime-order subgroup rather than a subgroup of | |
478 | order | |
479 | .RI ( p "\ \-\ 1)/2." | |
d03ab969 | 480 | .PP |
481 | The key's type is given by the required | |
482 | .I type | |
483 | argument. Following the type are zero or more attributes, which are | |
484 | attached to the key in the same way as for the | |
485 | .B setattr | |
486 | command. | |
487 | .PP | |
052b36d0 | 488 | The key-generation algorithms supported are as follows: |
489 | .TP | |
490 | .B "binary" | |
491 | Generates a plain binary key of the requested length. If the requested | |
492 | key length is not a multiple of eight, the high-order bits of the first | |
493 | octet of the key are zeroed. The default key length is 128 bits. | |
494 | .TP | |
495 | .B "des" | |
496 | Generates a DES key, with parity bits. The key length must be 56, 112 | |
497 | or 168; the default is 56. The low-order bit of each octet is ignored by | |
498 | the DES algorithm; it is used to give each octet odd parity. | |
499 | .TP | |
500 | .B "rsa" | |
501 | Generates a public/private key pair for use with the RSA algorithm. | |
502 | .IP | |
503 | The key components are | |
504 | .I p | |
505 | and | |
506 | .IR q , | |
507 | a pair of prime numbers; | |
508 | .IR n , | |
509 | the product of | |
510 | .I p | |
511 | and | |
512 | .IR q ; | |
513 | .IR e , | |
514 | the public exponent; | |
515 | .IR d , | |
516 | the private exponent, chosen such that | |
ef3b232f | 517 | .IR ed \~\(==\~1 |
052b36d0 | 518 | (mod |
ef3b232f | 519 | .RI lcm( p "\~\-\~1, " q \~\-\~1)); |
052b36d0 | 520 | and some other values useful for optimizing private-key operations: |
ef3b232f MW |
521 | .IR q "\*(ss\-1\*(se mod " p , |
522 | .IR d "\~mod " p \~\-\~1, | |
052b36d0 | 523 | and |
ef3b232f | 524 | .IR d "\~mod " q \~\-\~1. |
052b36d0 | 525 | The values |
526 | .I n | |
527 | and | |
528 | .I e | |
529 | constitute the public key; the rest must be kept secret. The key size | |
530 | requested by the | |
531 | .B \-b | |
532 | option determines the size of the modulus | |
533 | .IR n ; | |
534 | the default is 1024 bits. | |
535 | .IP | |
536 | The key generation algorithm chooses | |
537 | .I p | |
538 | and | |
539 | .I q | |
540 | to be | |
541 | .I strong | |
542 | primes: both | |
ef3b232f | 543 | .IR p \~\-\~1 |
052b36d0 | 544 | and |
ef3b232f MW |
545 | .IR p \~+\~1 |
546 | have large prime factors \(en call them | |
052b36d0 | 547 | .I r |
548 | and | |
549 | .I s | |
ef3b232f MW |
550 | respectively \(en and |
551 | .IR r \~\-\~1 | |
052b36d0 | 552 | also has a large prime factor; |
553 | .I q | |
554 | has similar properties. | |
555 | .IP | |
556 | The modulus | |
557 | .I n | |
558 | cannot be sensibly used as a shared parameter, since knowledge of | |
559 | corrssponding public and private exponents is sufficient to be able to | |
560 | factor the modulus and recover other users' private keys. | |
561 | .TP | |
eb31b00e | 562 | .B "dh-param" |
ef3b232f | 563 | Generates parameters for use with the Diffie\(enHellman key exchange |
052b36d0 | 564 | protocol, and many related systems, such as ElGamal encryption and |
1476eebc | 565 | signatures, and even DSA. (The separate DSA algorithm uses the |
566 | generator described in FIPS186-1.) | |
567 | .IP | |
ef3b232f | 568 | The Diffie\(enHellman parameters are a prime modulus |
1476eebc | 569 | .I p |
052b36d0 | 570 | and a generator |
571 | .I g | |
1476eebc | 572 | of a subgroup of |
573 | .BR Z / \c | |
574 | .IB p Z | |
575 | of order | |
576 | .IR q . | |
577 | The | |
052b36d0 | 578 | .B \-b |
1476eebc | 579 | option controls the size of the modulus |
052b36d0 | 580 | .IR p ; |
1476eebc | 581 | the default size is 1024 bits. |
582 | .IP | |
45c0fd36 | 583 | If no |
052b36d0 | 584 | .I q |
1476eebc | 585 | size is selected using the |
052b36d0 | 586 | .B \-B |
ef3b232f | 587 | option and the Lim\(enLee prime options are disabled, then |
1476eebc | 588 | .I p |
589 | is chosen to be a `safe' prime (i.e., | |
ef3b232f | 590 | .IR p "\~= 2" q \~+\~1, |
1476eebc | 591 | with |
592 | .I q | |
8404fd75 | 593 | prime). Finding safe primes takes a very long time. In this case, the |
594 | value of | |
1476eebc | 595 | .I g |
596 | is fixed as 4. | |
597 | .IP | |
598 | If a size is chosen for | |
599 | .I q | |
ef3b232f | 600 | and Lim\(enLee primes are not selected then the prime |
1476eebc | 601 | .I q |
602 | is generated and | |
603 | .I p | |
604 | is chosen so that | |
ef3b232f | 605 | .IR p \~\-\~1 |
1476eebc | 606 | is a multiple of |
607 | .IR q . | |
608 | .IP | |
609 | If the | |
610 | .B \-L | |
ef3b232f MW |
611 | option was given, Lim\(enLee primes are selected: the parameters are |
612 | chosen such that | |
613 | .IR p "\~= 2\~" q \*(us0\*(ue | |
614 | .IR q \*(us1\*(ue | |
615 | .IR q \*(us2\*(ue\~...\~+\~1, | |
1476eebc | 616 | where the |
ef3b232f | 617 | .IR q \*(us i \*(ue |
1476eebc | 618 | are primes at least as large as the setting given by the |
619 | .B \-B | |
620 | option (or 256 bits, if no setting was given). | |
052b36d0 | 621 | .IP |
1476eebc | 622 | If the |
45c0fd36 | 623 | .B \-K |
ef3b232f | 624 | option was given, KCDSA-style Lim\(enLee primes are selected: the |
4e67e30b | 625 | parameters are chosen such that |
ef3b232f | 626 | .IR p "\~= 2" qv \~+\~1, |
4e67e30b | 627 | where |
45c0fd36 | 628 | .IR p, |
4e67e30b MW |
629 | .I q |
630 | and | |
631 | .I v | |
632 | are primes. | |
633 | .IP | |
634 | If the | |
1476eebc | 635 | .B \-S |
4e67e30b MW |
636 | or |
637 | .B \-K | |
638 | options were given, the generator | |
1476eebc | 639 | .I g |
640 | is chosen to generate the subgroup of order | |
641 | .IR q \*(us0\*(ue; | |
642 | otherwise, | |
643 | .I g | |
644 | will generate the group of order | |
ef3b232f MW |
645 | .RI ( p "\~\-\~1)/2\~= " q "\*(us0\*(ue " q \*(us1\*(ue |
646 | .IR q \*(us2\*(ue\~... | |
8404fd75 | 647 | .IP |
648 | Finally, the | |
649 | .B \-C | |
650 | option can be given, in which case the parameters are taken directly | |
651 | from the provided group specification, which may either be the the name | |
652 | of one of the built-in groups (say | |
58507325 | 653 | .B "key show dh" |
8404fd75 | 654 | for a list) or a triple |
ef3b232f | 655 | .RI ( p ,\~ q ,\~ g ). |
8404fd75 | 656 | separated by commas. No random generation is done in this case: the |
657 | given parameters are simply stored. | |
052b36d0 | 658 | .TP |
659 | .B "dh" | |
ef3b232f | 660 | Generates a public/private key pair for use with offline Diffie\(enHellman, |
052b36d0 | 661 | ElGamal, DSA or similar discrete-logarithm-based systems. It selects a |
662 | private key | |
ef3b232f | 663 | .IR x \~<\~ q , |
052b36d0 | 664 | and computes the public key |
ef3b232f | 665 | .IR y "\~= " g \*(ss x "\*(se mod\~" p . |
052b36d0 | 666 | .TP |
667 | .B "dsa-param" | |
668 | Generates parameters for the DSA algorithm. DSA parameters are also | |
ef3b232f | 669 | suitable for use with Diffie\(enHellman and ElGamal system. |
052b36d0 | 670 | .IP |
ef3b232f | 671 | The main difference between DSA and Diffie\(enHellman parameter generation |
052b36d0 | 672 | is thatthe DSA parameter generation |
673 | algorithm creates a | |
674 | .I seed | |
675 | from which the parameters are derived, and, assuming that the SHA-1 hash | |
676 | function is strong, it's not feasible to construct a seed from which | |
677 | deliberately weak parameters are derived. The algorithm used is the one | |
678 | described in the DSA standard, FIPS\ 186, extended only to allow | |
679 | sequential search for a prime | |
680 | .I q | |
681 | and to allow arbitrary parameter sizes. The seed is stored, | |
682 | Base64-encoded, as the value of the attribute | |
683 | .BR seed . | |
684 | .IP | |
685 | The default lengths for | |
686 | .I p | |
687 | and | |
688 | .I q | |
689 | are 768 and 160 bits respectively, since the DSA standard specifies that | |
690 | .I q | |
691 | be 160 bits, and the choice of 768 bits for | |
692 | .I p | |
693 | gives commensurate security. | |
694 | .TP | |
695 | .B "dsa" | |
ef3b232f | 696 | Generates a public/private key pair for DSA. As for Diffie\(enHellman |
052b36d0 | 697 | keys, it selects a |
698 | private key | |
ef3b232f | 699 | .IR x \~<\~ q , |
052b36d0 | 700 | and computes the public key |
ef3b232f | 701 | .IR y "\~= " g \*(ss x "\*(se mod\~" p . |
052b36d0 | 702 | .TP |
703 | .B "bbs" | |
704 | Generates a public/private key pair for the Blum-Blum-Shub random-number | |
705 | generator, and the Blum-Goldwasser semantically-secure public-key | |
706 | encryption system. | |
707 | .IP | |
708 | The key components are prime numbers | |
709 | .I p | |
710 | and | |
711 | .IR q , | |
ef3b232f | 712 | both congruent to 3 (mod\~4), and their product |
052b36d0 | 713 | .IR n . |
714 | The public key is simply the modulus | |
715 | .IR n ; | |
716 | the factors | |
717 | .I p | |
718 | and | |
719 | .I q | |
720 | are the private key. | |
721 | .IP | |
722 | The key-generation algorithm ensures that the two primes | |
723 | .I p | |
724 | and | |
725 | .I q | |
726 | are | |
727 | .I strong | |
728 | (see the discussion of strong primes above, in the section on RSA keys), | |
729 | and that | |
ef3b232f | 730 | .RI ( p \~\-\~1)/2 |
052b36d0 | 731 | and |
ef3b232f | 732 | .RI ( q \~\-\~1)/2 |
052b36d0 | 733 | are relatively prime, giving a maximum possible period length. |
734 | .IP | |
735 | The key size requested by the | |
736 | .B \-b | |
737 | option determines the length of the modulus | |
738 | .IR n ; | |
739 | the default length is 1024 bits. | |
eb31b00e | 740 | .TP |
741 | .B "ec-param" | |
742 | Store an elliptic curve specification. If no explicit | |
743 | .I curve-spec | |
744 | is given (the | |
745 | .RB ` \-C ' | |
746 | option) then a curve is chosen whose order is about the size given by the | |
747 | .RB ` \-b ' | |
748 | option (default is 256 bits). | |
749 | .IP | |
750 | A | |
751 | .I curve-spec | |
752 | can be given explicitly (in which case | |
753 | .RB ` \-b ' | |
754 | is ignored). It can either be the name of a built-in curve (say | |
58507325 | 755 | .B "key show ec" |
eb31b00e | 756 | for a list of curve names) or a full specification. The curve is |
757 | checked for correctness and security according to the SEC1 | |
758 | specification: failed checks cause a warning to be issued to standard | |
759 | error (though the program continues anyway). The check can be | |
760 | suppressed using the | |
761 | .RB ` \-q ' | |
762 | option. | |
763 | .IP | |
764 | A curve specification consists of the following elements optionally | |
765 | separated by whitespace: a | |
766 | .IR "field type" , | |
767 | which is one of | |
768 | .BR "prime" , | |
769 | .BR "niceprime" , | |
8404fd75 | 770 | .BR "binpoly" , |
771 | .or | |
772 | .BR "binnorm" ; | |
eb31b00e | 773 | an optional |
774 | .RB ` : '; | |
775 | the field modulus | |
776 | .IR p ; | |
8404fd75 | 777 | if the field type is |
778 | .B binnorm | |
779 | then an optional | |
780 | .RB ` , ' | |
781 | and the representation of the normal element \*(*b; an optional | |
20095408 | 782 | .RB ` ; '; |
eb31b00e | 783 | a |
784 | .IR "curve type" , | |
785 | which is one of | |
786 | .BR "prime" , | |
787 | .BR "primeproj" , | |
788 | .BR "bin" , | |
789 | and | |
790 | .BR "binproj" | |
791 | (the `proj' types currently have much better performance); | |
792 | an optional | |
793 | .RB ` : '; | |
794 | the two field-element parameters | |
795 | .I a | |
796 | and | |
45c0fd36 | 797 | .IR b |
eb31b00e | 798 | which define the elliptic curve |
799 | .IR E , | |
800 | separated by an optional | |
801 | .RB ` , '; | |
802 | an optional | |
20095408 | 803 | .RB ` ; '; |
45c0fd36 | 804 | the |
eb31b00e | 805 | .IR x - |
806 | and | |
807 | .IR y -coordinates | |
808 | of the generator point | |
809 | .IR G , | |
810 | separated by an optional | |
811 | .RB ` , '; | |
812 | an optional | |
813 | .RB ` : '; | |
814 | the order | |
815 | .I r | |
45c0fd36 | 816 | of the group generated by |
eb31b00e | 817 | .IR G ; |
818 | an optional | |
819 | .RB ` * '; | |
45c0fd36 | 820 | and the |
eb31b00e | 821 | .I cofactor |
822 | .I h | |
823 | = | |
824 | .RI # E / r . | |
825 | .TP | |
826 | .B "ec" | |
827 | Generate a private scalar and a corresponding public point on an | |
828 | elliptic curve. See | |
829 | .B ec-param | |
830 | above for how to specify elliptic curve parameter sets. The scalar | |
831 | .I x | |
832 | is chosen unformly between 0 and the curve order | |
833 | .IR r ; | |
834 | the public point is then | |
835 | .I x | |
836 | \(mu | |
837 | .IR G . | |
052b36d0 | 838 | .SS "expire" |
d03ab969 | 839 | Forces keys to immediately expire. An expired key is not chosen when a |
840 | program requests a key by its type. The keys to expire are listed by | |
841 | their | |
052b36d0 | 842 | .IR tag s. |
843 | .SS "delete" | |
d03ab969 | 844 | Deletes keys immediately. The keys to delete are listed by their |
052b36d0 | 845 | .IR tag s. |
d03ab969 | 846 | Be careful when deleting keys. It might be a better idea |
847 | to expire keys rather than deleting them. | |
052b36d0 | 848 | .SS "tag" |
849 | Sets, deletes or changes the tag attached to a key. The first tag or | |
850 | keyid names the key to be modified; the second, if present specifies the | |
851 | new tag to be set. If no second argument is given, the existing tag, if | |
d07dfe80 | 852 | any, is removed and no new tag is set. It is an error to set a tag |
853 | which already exists on another key, unless you give the | |
854 | .B \-r | |
855 | option, which removes the tag first. | |
052b36d0 | 856 | .SS "setattr" |
d03ab969 | 857 | Attaches attributes to a key. The key to which the attributes should be |
858 | attached is given by its | |
052b36d0 | 859 | .IR tag . |
d03ab969 | 860 | Each attribute has the form |
861 | .IB name = value\fR. | |
862 | An attribute can be deleted by assigning it an empty value. Although | |
863 | the keyring file format is capable of representing an attribute with an | |
864 | empty value as distinct from a nonexistant attribute, this interface | |
865 | does not allow empty attributes to be set. | |
e9be047b | 866 | .SS "getattr" |
867 | Fetches a single attribute of a key. The key whose attribute is to be | |
868 | read is given by its | |
869 | .IR tag . | |
870 | The attribute's value is written to standard output followed by a | |
871 | newline. If the key or attribute is absent, a message is written to | |
872 | standard error and the program exits nonzero. | |
052b36d0 | 873 | .SS "comment" |
874 | Sets, deletes or changes the comment attached to a key. The first | |
875 | argument is a key tag or keyid which names the key to be modified; the | |
876 | second, if present, is the new comment. If no second argument is given, | |
877 | the existing comment, if any, is removed, and no new comment is set. | |
878 | .SS "lock" | |
879 | Locks a key or key component using a passphrase. If the key is already | |
880 | locked, the existing passphrase is requested, and a new passphrase is | |
881 | set. | |
882 | .SS "unlock" | |
883 | Unlocks a passphrase-locked key or key component. If the key is not | |
884 | locked, an error is reported. | |
885 | .SS "list" | |
d03ab969 | 886 | Lists the keys in the keyring. A couple of options are supported: |
887 | .TP | |
888 | .B "\-v, \-\-verbose" | |
889 | Increases the amount of information displayed for each key. Repeat for | |
890 | a greater effect. | |
891 | .TP | |
892 | .B "\-q, \-\-quiet" | |
893 | Decreases the amount of information displayed for each key. Each use | |
894 | cancels a | |
895 | .RB ` \-v ' | |
896 | option. | |
c9e31e42 | 897 | .TP |
898 | .B "\-u, \-\-utc" | |
899 | Display key expiry times as UTC rather than using the local time zone. | |
052b36d0 | 900 | .TP |
901 | .BI "\-f, \-\-filter " filter | |
902 | Specifies a filter. Only keys and key components which match the filter | |
903 | are listed. | |
d03ab969 | 904 | .PP |
905 | By default, a single line of output is generated for each, showing | |
906 | keyids, types, expiry and deletion dates, and comments. Additional | |
907 | .RB ` \-v ' | |
908 | options show more information, such as the exact time of day for expiry | |
052b36d0 | 909 | and deletion, key attributes, and a dump of the actual key data. If the |
910 | verbosity level is sufficiently high, passphrases are requested to | |
911 | decrypt locked keys. Make sure nobody is looking over your shoulder | |
912 | when you do this! | |
913 | .SS "fingerprint" | |
914 | Reports a fingerprint (secure hash) on components of requested keys. | |
58507325 | 915 | The following options are supported: |
052b36d0 | 916 | .TP |
917 | .BI "\-f, \-\-filter " filter | |
918 | Specifies a filter. Only keys and key components which match the filter | |
919 | are fingerprinted. The default is to only fingerprint nonsecret | |
920 | components. | |
b817bfc6 | 921 | .TP |
922 | .BI "\-a, \-\-algorithm " hash | |
923 | Names the hashing algorithm. Run | |
58507325 | 924 | .B key show hash |
b817bfc6 | 925 | for a list of hashing algorithms. The default is |
926 | .BR rmd160 . | |
052b36d0 | 927 | .PP |
928 | The keys to be fingerprinted are named by their tags or keyids given as | |
929 | command line arguments. If no key tags are given, all keys which match | |
b817bfc6 | 930 | the filter are fingerprinted. See |
931 | .BR keyring (5) | |
932 | for a description of how key fingerprints are computed. | |
58507325 | 933 | .SS "verify" |
934 | Check a key's fingerprint against a reference copy. The following | |
935 | options are supported: | |
936 | .TP | |
937 | .BI "\-f, \-\-filter " filter | |
938 | Specifies a filter. Only key components which match the filter are | |
939 | hashed. The default is to only fingerprint nonsecret components. An | |
940 | error is reported if no part of the key matches. | |
941 | .TP | |
942 | .BI "\-a, \-\-algorithm " hash | |
943 | Names the hashing algorithm. Run | |
944 | .B key show hash | |
945 | for a list of hashing algorithms. The default is | |
946 | .BR rmd160 . | |
947 | .PP | |
948 | The reference fingerprint is given as hex, in upper or lower case. The | |
949 | hash may contain hyphens, colons and whitespace. Other characters are | |
950 | not permitted. | |
052b36d0 | 951 | .SS "tidy" |
d03ab969 | 952 | Simply reads the keyring from file and writes it back again. This has |
953 | the effect of removing any deleted keys from the file. | |
052b36d0 | 954 | .SS "extract" |
955 | Writes a selection of keys to a file. An option is supported: | |
956 | .TP | |
957 | .BI "\-f, \-\-filter " filter | |
958 | Specifies a filter. Only keys and key components which match the filter | |
959 | are written. | |
960 | .PP | |
961 | Keys extracted are written to the file named by the first argument, | |
d03ab969 | 962 | which may be |
963 | .RB ` \- ' | |
964 | to designate standard output. The keys to extract are listed by their | |
052b36d0 | 965 | tags; if no tags are given, all keys which match the filter are |
966 | extracted. The output is a valid keyring file. | |
967 | .SS "merge" | |
d03ab969 | 968 | Merges the keys from the named |
969 | .IR file , | |
970 | which may be | |
971 | .RB ` \- ' | |
972 | to designate standard input, with the keyring. Keys already in the | |
973 | keyring are not overwritten: you must explicitly remove them first if | |
974 | you want them to be replaced during the merge. | |
d03ab969 | 975 | .SH "SEE ALSO" |
976 | .BR keyring (5). | |
977 | .SH AUTHOR | |
f387fcb1 | 978 | Mark Wooding, <mdw@distorted.org.uk> |