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