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