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