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 | |
7532e25e MW |
376 | Selects a key containing parameter values to copy. |
377 | A new key also inherits attributes from its parameter key. | |
d03ab969 | 378 | .TP |
c65df279 | 379 | .BI "\-A, \-\-seedalg " seed-alg |
380 | Use the deterministic random number generator algorithm | |
381 | .I seed-alg | |
382 | to generate the key. Use | |
383 | .I before | |
384 | the | |
385 | .B \-s | |
386 | or | |
387 | .B \-n | |
388 | options; without one of these, | |
389 | .B \-A | |
390 | has no effect. The default algorithm is | |
391 | .BR rmd160-mgf . | |
392 | The command | |
393 | .B key show seed | |
394 | shows a list of recognized seeding algorithms. The seeding algorithm | |
395 | used to generate a key is recorded as the key's | |
396 | .B seedalg | |
397 | attribute. | |
398 | .TP | |
399 | .BI "\-s, \-\-seed " seed | |
400 | Generate the key deterministically using the given | |
401 | .IR seed , | |
402 | which should be a Base64-encoded binary string. This is mainly useful | |
403 | for parameters keys (types | |
404 | .BR dsa-param | |
405 | and | |
406 | .BR dh-param ), | |
407 | to demonstrate that a set of parameters has been generated in an honest | |
408 | fashion. The | |
409 | .B dsarand | |
410 | generation algorithm can be used to generate | |
411 | .B dsa-param | |
412 | keys as required by FIPS186. The requested seed is recorded, | |
413 | Base64-encoded, as the new key's | |
414 | .B seed | |
415 | attribute. | |
416 | .TP | |
417 | .BI "\-n, \-\-newseed " bits | |
418 | Generate a new seed, with the given length in | |
419 | .IR bits . | |
420 | The generated seed is recorded, Base64-encoded, as the new key's | |
421 | .B seed | |
422 | attribute. | |
423 | .TP | |
c9e31e42 | 424 | .BI "\-e, \-\-expire " expire |
d03ab969 | 425 | The expiry date for the generated key. This may be the string |
426 | .RB ` forever ' | |
427 | if the key should never expire automatically, or any date acceptable to | |
428 | the | |
429 | .BR getdate (3) | |
430 | library function. Briefly, | |
431 | .B getdate | |
432 | understands absolute dates such as | |
433 | .RB ` 1999-08-02 ' | |
434 | or | |
435 | .RB ` "August 2nd, 1999" ', | |
436 | and (perhaps more usefully) relative dates such as | |
437 | .RB ` "+2 weeks" '. | |
438 | The default is to allow a 2 week expiry, which isn't useful. | |
439 | .TP | |
c9e31e42 | 440 | .BI "\-c, \-\-comment " comment |
d03ab969 | 441 | Sets a comment for the key. The default is not to attach a comment. |
052b36d0 | 442 | .TP |
eb31b00e | 443 | .BI "\-C, \-\-curve " curve-spec |
444 | Use the elliptic curve described by | |
445 | .I curve-spec | |
446 | when generating elliptic curve parameters. | |
447 | .TP | |
052b36d0 | 448 | .BI "\-t, \-\-tag " tag |
449 | Selects a tag string for the key. The default is not to set a tag. It | |
450 | is an error to select a tag which already exists. | |
451 | .TP | |
d07dfe80 | 452 | .BI "\-r, \-\-retag" |
453 | If a | |
454 | .B \-t | |
455 | option is given, remove this tag from any key which already has it. | |
456 | .TP | |
457 | .BI "\-R, \-\-rand-id " tag | |
052b36d0 | 458 | Selects the key to use for the random number generator. Catacomb's |
459 | random number generator can be | |
460 | .IR keyed , | |
461 | so that, even if the inputs to the generator are compromised, knowledge | |
462 | of the key is also necessary to be able to predict the output. By | |
463 | default, the latest-expiring key with type | |
464 | .B catacomb-rand | |
465 | is used, if present; if not, no key is used. | |
466 | .TP | |
467 | .BI "\-l, \-\-lock" | |
468 | Requests that the secret parts of the newly-generated key be encrypted | |
469 | using a passphrase. | |
470 | .TP | |
471 | .BI "\-q, \-\-quiet" | |
472 | Suppresses the progress indication which is usually generated while | |
473 | time-consuming key generation tasks are being performed. | |
1476eebc | 474 | .TP |
4e67e30b | 475 | .BI "\-L, \-\-lim-lee" |
ef3b232f MW |
476 | When generating Diffie\(enHellman parameters, generate a Lim\(enLee |
477 | prime rather than a random (or safe) prime. See the details on | |
478 | Diffie\(enHellman key generation below. | |
1476eebc | 479 | .TP |
4e67e30b | 480 | .BI "\-K, \-\-kcdsa" |
ef3b232f MW |
481 | When generating Diffie\(enHellman parameters, generate a KCDSA-style |
482 | Lim\(enLee prime rather than a random (or safe) prime. See the details | |
483 | on Diffie\(enHellman key generation below. | |
4e67e30b MW |
484 | .TP |
485 | .BI "\-S, \-\-subgroup" | |
ef3b232f MW |
486 | When generating Diffie\(enHellman parameters with a Lim\(enLee prime, |
487 | choose a generator of a prime-order subgroup rather than a subgroup of | |
488 | order | |
489 | .RI ( p "\ \-\ 1)/2." | |
d03ab969 | 490 | .PP |
491 | The key's type is given by the required | |
492 | .I type | |
493 | argument. Following the type are zero or more attributes, which are | |
494 | attached to the key in the same way as for the | |
495 | .B setattr | |
496 | command. | |
497 | .PP | |
052b36d0 | 498 | The key-generation algorithms supported are as follows: |
499 | .TP | |
500 | .B "binary" | |
501 | Generates a plain binary key of the requested length. If the requested | |
502 | key length is not a multiple of eight, the high-order bits of the first | |
503 | octet of the key are zeroed. The default key length is 128 bits. | |
504 | .TP | |
505 | .B "des" | |
506 | Generates a DES key, with parity bits. The key length must be 56, 112 | |
507 | or 168; the default is 56. The low-order bit of each octet is ignored by | |
508 | the DES algorithm; it is used to give each octet odd parity. | |
509 | .TP | |
510 | .B "rsa" | |
511 | Generates a public/private key pair for use with the RSA algorithm. | |
512 | .IP | |
513 | The key components are | |
514 | .I p | |
515 | and | |
516 | .IR q , | |
517 | a pair of prime numbers; | |
518 | .IR n , | |
519 | the product of | |
520 | .I p | |
521 | and | |
522 | .IR q ; | |
523 | .IR e , | |
524 | the public exponent; | |
525 | .IR d , | |
526 | the private exponent, chosen such that | |
ef3b232f | 527 | .IR ed \~\(==\~1 |
052b36d0 | 528 | (mod |
ef3b232f | 529 | .RI lcm( p "\~\-\~1, " q \~\-\~1)); |
052b36d0 | 530 | and some other values useful for optimizing private-key operations: |
ef3b232f MW |
531 | .IR q "\*(ss\-1\*(se mod " p , |
532 | .IR d "\~mod " p \~\-\~1, | |
052b36d0 | 533 | and |
ef3b232f | 534 | .IR d "\~mod " q \~\-\~1. |
052b36d0 | 535 | The values |
536 | .I n | |
537 | and | |
538 | .I e | |
539 | constitute the public key; the rest must be kept secret. The key size | |
540 | requested by the | |
541 | .B \-b | |
542 | option determines the size of the modulus | |
543 | .IR n ; | |
544 | the default is 1024 bits. | |
545 | .IP | |
546 | The key generation algorithm chooses | |
547 | .I p | |
548 | and | |
549 | .I q | |
550 | to be | |
551 | .I strong | |
552 | primes: both | |
ef3b232f | 553 | .IR p \~\-\~1 |
052b36d0 | 554 | and |
ef3b232f MW |
555 | .IR p \~+\~1 |
556 | have large prime factors \(en call them | |
052b36d0 | 557 | .I r |
558 | and | |
559 | .I s | |
ef3b232f MW |
560 | respectively \(en and |
561 | .IR r \~\-\~1 | |
052b36d0 | 562 | also has a large prime factor; |
563 | .I q | |
564 | has similar properties. | |
565 | .IP | |
566 | The modulus | |
567 | .I n | |
568 | cannot be sensibly used as a shared parameter, since knowledge of | |
569 | corrssponding public and private exponents is sufficient to be able to | |
570 | factor the modulus and recover other users' private keys. | |
571 | .TP | |
eb31b00e | 572 | .B "dh-param" |
ef3b232f | 573 | Generates parameters for use with the Diffie\(enHellman key exchange |
052b36d0 | 574 | protocol, and many related systems, such as ElGamal encryption and |
1476eebc | 575 | signatures, and even DSA. (The separate DSA algorithm uses the |
576 | generator described in FIPS186-1.) | |
577 | .IP | |
ef3b232f | 578 | The Diffie\(enHellman parameters are a prime modulus |
1476eebc | 579 | .I p |
052b36d0 | 580 | and a generator |
581 | .I g | |
1476eebc | 582 | of a subgroup of |
583 | .BR Z / \c | |
584 | .IB p Z | |
585 | of order | |
586 | .IR q . | |
587 | The | |
052b36d0 | 588 | .B \-b |
1476eebc | 589 | option controls the size of the modulus |
052b36d0 | 590 | .IR p ; |
1476eebc | 591 | the default size is 1024 bits. |
592 | .IP | |
45c0fd36 | 593 | If no |
052b36d0 | 594 | .I q |
1476eebc | 595 | size is selected using the |
052b36d0 | 596 | .B \-B |
ef3b232f | 597 | option and the Lim\(enLee prime options are disabled, then |
1476eebc | 598 | .I p |
599 | is chosen to be a `safe' prime (i.e., | |
ef3b232f | 600 | .IR p "\~= 2" q \~+\~1, |
1476eebc | 601 | with |
602 | .I q | |
8404fd75 | 603 | prime). Finding safe primes takes a very long time. In this case, the |
604 | value of | |
1476eebc | 605 | .I g |
606 | is fixed as 4. | |
607 | .IP | |
608 | If a size is chosen for | |
609 | .I q | |
ef3b232f | 610 | and Lim\(enLee primes are not selected then the prime |
1476eebc | 611 | .I q |
612 | is generated and | |
613 | .I p | |
614 | is chosen so that | |
ef3b232f | 615 | .IR p \~\-\~1 |
1476eebc | 616 | is a multiple of |
617 | .IR q . | |
618 | .IP | |
619 | If the | |
620 | .B \-L | |
ef3b232f MW |
621 | option was given, Lim\(enLee primes are selected: the parameters are |
622 | chosen such that | |
623 | .IR p "\~= 2\~" q \*(us0\*(ue | |
624 | .IR q \*(us1\*(ue | |
625 | .IR q \*(us2\*(ue\~...\~+\~1, | |
1476eebc | 626 | where the |
ef3b232f | 627 | .IR q \*(us i \*(ue |
1476eebc | 628 | are primes at least as large as the setting given by the |
629 | .B \-B | |
630 | option (or 256 bits, if no setting was given). | |
052b36d0 | 631 | .IP |
1476eebc | 632 | If the |
45c0fd36 | 633 | .B \-K |
ef3b232f | 634 | option was given, KCDSA-style Lim\(enLee primes are selected: the |
4e67e30b | 635 | parameters are chosen such that |
ef3b232f | 636 | .IR p "\~= 2" qv \~+\~1, |
4e67e30b | 637 | where |
45c0fd36 | 638 | .IR p, |
4e67e30b MW |
639 | .I q |
640 | and | |
641 | .I v | |
642 | are primes. | |
643 | .IP | |
644 | If the | |
1476eebc | 645 | .B \-S |
4e67e30b MW |
646 | or |
647 | .B \-K | |
648 | options were given, the generator | |
1476eebc | 649 | .I g |
650 | is chosen to generate the subgroup of order | |
651 | .IR q \*(us0\*(ue; | |
652 | otherwise, | |
653 | .I g | |
654 | will generate the group of order | |
ef3b232f MW |
655 | .RI ( p "\~\-\~1)/2\~= " q "\*(us0\*(ue " q \*(us1\*(ue |
656 | .IR q \*(us2\*(ue\~... | |
8404fd75 | 657 | .IP |
658 | Finally, the | |
659 | .B \-C | |
660 | option can be given, in which case the parameters are taken directly | |
661 | from the provided group specification, which may either be the the name | |
662 | of one of the built-in groups (say | |
58507325 | 663 | .B "key show dh" |
8404fd75 | 664 | for a list) or a triple |
ef3b232f | 665 | .RI ( p ,\~ q ,\~ g ). |
8404fd75 | 666 | separated by commas. No random generation is done in this case: the |
667 | given parameters are simply stored. | |
052b36d0 | 668 | .TP |
669 | .B "dh" | |
ef3b232f | 670 | Generates a public/private key pair for use with offline Diffie\(enHellman, |
052b36d0 | 671 | ElGamal, DSA or similar discrete-logarithm-based systems. It selects a |
672 | private key | |
ef3b232f | 673 | .IR x \~<\~ q , |
052b36d0 | 674 | and computes the public key |
ef3b232f | 675 | .IR y "\~= " g \*(ss x "\*(se mod\~" p . |
052b36d0 | 676 | .TP |
677 | .B "dsa-param" | |
678 | Generates parameters for the DSA algorithm. DSA parameters are also | |
ef3b232f | 679 | suitable for use with Diffie\(enHellman and ElGamal system. |
052b36d0 | 680 | .IP |
ef3b232f | 681 | The main difference between DSA and Diffie\(enHellman parameter generation |
052b36d0 | 682 | is thatthe DSA parameter generation |
683 | algorithm creates a | |
684 | .I seed | |
685 | from which the parameters are derived, and, assuming that the SHA-1 hash | |
686 | function is strong, it's not feasible to construct a seed from which | |
687 | deliberately weak parameters are derived. The algorithm used is the one | |
688 | described in the DSA standard, FIPS\ 186, extended only to allow | |
689 | sequential search for a prime | |
690 | .I q | |
691 | and to allow arbitrary parameter sizes. The seed is stored, | |
692 | Base64-encoded, as the value of the attribute | |
693 | .BR seed . | |
694 | .IP | |
695 | The default lengths for | |
696 | .I p | |
697 | and | |
698 | .I q | |
699 | are 768 and 160 bits respectively, since the DSA standard specifies that | |
700 | .I q | |
701 | be 160 bits, and the choice of 768 bits for | |
702 | .I p | |
703 | gives commensurate security. | |
704 | .TP | |
705 | .B "dsa" | |
ef3b232f | 706 | Generates a public/private key pair for DSA. As for Diffie\(enHellman |
052b36d0 | 707 | keys, it selects a |
708 | private key | |
ef3b232f | 709 | .IR x \~<\~ q , |
052b36d0 | 710 | and computes the public key |
ef3b232f | 711 | .IR y "\~= " g \*(ss x "\*(se mod\~" p . |
052b36d0 | 712 | .TP |
713 | .B "bbs" | |
714 | Generates a public/private key pair for the Blum-Blum-Shub random-number | |
715 | generator, and the Blum-Goldwasser semantically-secure public-key | |
716 | encryption system. | |
717 | .IP | |
718 | The key components are prime numbers | |
719 | .I p | |
720 | and | |
721 | .IR q , | |
ef3b232f | 722 | both congruent to 3 (mod\~4), and their product |
052b36d0 | 723 | .IR n . |
724 | The public key is simply the modulus | |
725 | .IR n ; | |
726 | the factors | |
727 | .I p | |
728 | and | |
729 | .I q | |
730 | are the private key. | |
731 | .IP | |
732 | The key-generation algorithm ensures that the two primes | |
733 | .I p | |
734 | and | |
735 | .I q | |
736 | are | |
737 | .I strong | |
738 | (see the discussion of strong primes above, in the section on RSA keys), | |
739 | and that | |
ef3b232f | 740 | .RI ( p \~\-\~1)/2 |
052b36d0 | 741 | and |
ef3b232f | 742 | .RI ( q \~\-\~1)/2 |
052b36d0 | 743 | are relatively prime, giving a maximum possible period length. |
744 | .IP | |
745 | The key size requested by the | |
746 | .B \-b | |
747 | option determines the length of the modulus | |
748 | .IR n ; | |
749 | the default length is 1024 bits. | |
eb31b00e | 750 | .TP |
751 | .B "ec-param" | |
752 | Store an elliptic curve specification. If no explicit | |
753 | .I curve-spec | |
754 | is given (the | |
755 | .RB ` \-C ' | |
756 | option) then a curve is chosen whose order is about the size given by the | |
757 | .RB ` \-b ' | |
758 | option (default is 256 bits). | |
759 | .IP | |
760 | A | |
761 | .I curve-spec | |
762 | can be given explicitly (in which case | |
763 | .RB ` \-b ' | |
764 | is ignored). It can either be the name of a built-in curve (say | |
58507325 | 765 | .B "key show ec" |
eb31b00e | 766 | for a list of curve names) or a full specification. The curve is |
767 | checked for correctness and security according to the SEC1 | |
768 | specification: failed checks cause a warning to be issued to standard | |
769 | error (though the program continues anyway). The check can be | |
770 | suppressed using the | |
771 | .RB ` \-q ' | |
772 | option. | |
773 | .IP | |
774 | A curve specification consists of the following elements optionally | |
775 | separated by whitespace: a | |
776 | .IR "field type" , | |
777 | which is one of | |
778 | .BR "prime" , | |
779 | .BR "niceprime" , | |
8404fd75 | 780 | .BR "binpoly" , |
781 | .or | |
782 | .BR "binnorm" ; | |
eb31b00e | 783 | an optional |
784 | .RB ` : '; | |
785 | the field modulus | |
786 | .IR p ; | |
8404fd75 | 787 | if the field type is |
788 | .B binnorm | |
789 | then an optional | |
790 | .RB ` , ' | |
791 | and the representation of the normal element \*(*b; an optional | |
20095408 | 792 | .RB ` ; '; |
eb31b00e | 793 | a |
794 | .IR "curve type" , | |
795 | which is one of | |
796 | .BR "prime" , | |
797 | .BR "primeproj" , | |
798 | .BR "bin" , | |
799 | and | |
800 | .BR "binproj" | |
801 | (the `proj' types currently have much better performance); | |
802 | an optional | |
803 | .RB ` : '; | |
804 | the two field-element parameters | |
805 | .I a | |
806 | and | |
45c0fd36 | 807 | .IR b |
eb31b00e | 808 | which define the elliptic curve |
809 | .IR E , | |
810 | separated by an optional | |
811 | .RB ` , '; | |
812 | an optional | |
20095408 | 813 | .RB ` ; '; |
45c0fd36 | 814 | the |
eb31b00e | 815 | .IR x - |
816 | and | |
817 | .IR y -coordinates | |
818 | of the generator point | |
819 | .IR G , | |
820 | separated by an optional | |
821 | .RB ` , '; | |
822 | an optional | |
823 | .RB ` : '; | |
824 | the order | |
825 | .I r | |
45c0fd36 | 826 | of the group generated by |
eb31b00e | 827 | .IR G ; |
828 | an optional | |
829 | .RB ` * '; | |
45c0fd36 | 830 | and the |
eb31b00e | 831 | .I cofactor |
832 | .I h | |
833 | = | |
834 | .RI # E / r . | |
835 | .TP | |
836 | .B "ec" | |
837 | Generate a private scalar and a corresponding public point on an | |
838 | elliptic curve. See | |
839 | .B ec-param | |
840 | above for how to specify elliptic curve parameter sets. The scalar | |
841 | .I x | |
842 | is chosen unformly between 0 and the curve order | |
843 | .IR r ; | |
844 | the public point is then | |
845 | .I x | |
846 | \(mu | |
847 | .IR G . | |
7532e25e | 848 | .TP |
fc2d44af MW |
849 | .B x25519 |
850 | Generate a private scalar and a corresponding public point on the | |
851 | (Montgomery-form) Curve25519 elliptic curve. | |
852 | The scalar is simply a random 256-bit string; | |
853 | the public key is the | |
854 | .IR x -coordinate | |
855 | of the corresponding point. | |
856 | .TP | |
643eb1bb MW |
857 | .B x448 |
858 | Generate a private scalar and a corresponding public point on the | |
859 | (Montgomery-form) Ed448-Goldilocks elliptic curve. | |
860 | The scalar is simply a random 256-bit string; | |
861 | the public key is the | |
862 | .IR x -coordinate | |
863 | of the corresponding point. | |
864 | .TP | |
d56fd9d1 MW |
865 | .B ed25519 |
866 | Generate a private key and a corresponding public point on the | |
867 | (twisted Edwards-form) Curve25519 elliptic curve. | |
868 | The private key is simply a random 256-bit string, | |
869 | from which a scalar and secret prefix are derived; | |
870 | the public key is the compressed form of the corresponding point. | |
871 | .TP | |
7532e25e MW |
872 | .B empty |
873 | Generate an empty key, with trivial contents. | |
874 | This is useful as a `parameters' key, | |
875 | carrying attributes to be applied to other keys | |
876 | if they don't require more detailed parameters. | |
052b36d0 | 877 | .SS "expire" |
d03ab969 | 878 | Forces keys to immediately expire. An expired key is not chosen when a |
879 | program requests a key by its type. The keys to expire are listed by | |
880 | their | |
052b36d0 | 881 | .IR tag s. |
882 | .SS "delete" | |
d03ab969 | 883 | Deletes keys immediately. The keys to delete are listed by their |
052b36d0 | 884 | .IR tag s. |
d03ab969 | 885 | Be careful when deleting keys. It might be a better idea |
886 | to expire keys rather than deleting them. | |
052b36d0 | 887 | .SS "tag" |
888 | Sets, deletes or changes the tag attached to a key. The first tag or | |
889 | keyid names the key to be modified; the second, if present specifies the | |
890 | new tag to be set. If no second argument is given, the existing tag, if | |
d07dfe80 | 891 | any, is removed and no new tag is set. It is an error to set a tag |
892 | which already exists on another key, unless you give the | |
893 | .B \-r | |
894 | option, which removes the tag first. | |
052b36d0 | 895 | .SS "setattr" |
d03ab969 | 896 | Attaches attributes to a key. The key to which the attributes should be |
897 | attached is given by its | |
052b36d0 | 898 | .IR tag . |
d03ab969 | 899 | Each attribute has the form |
900 | .IB name = value\fR. | |
901 | An attribute can be deleted by assigning it an empty value. Although | |
902 | the keyring file format is capable of representing an attribute with an | |
903 | empty value as distinct from a nonexistant attribute, this interface | |
904 | does not allow empty attributes to be set. | |
e9be047b | 905 | .SS "getattr" |
906 | Fetches a single attribute of a key. The key whose attribute is to be | |
907 | read is given by its | |
908 | .IR tag . | |
909 | The attribute's value is written to standard output followed by a | |
910 | newline. If the key or attribute is absent, a message is written to | |
911 | standard error and the program exits nonzero. | |
052b36d0 | 912 | .SS "comment" |
913 | Sets, deletes or changes the comment attached to a key. The first | |
914 | argument is a key tag or keyid which names the key to be modified; the | |
915 | second, if present, is the new comment. If no second argument is given, | |
916 | the existing comment, if any, is removed, and no new comment is set. | |
917 | .SS "lock" | |
918 | Locks a key or key component using a passphrase. If the key is already | |
919 | locked, the existing passphrase is requested, and a new passphrase is | |
920 | set. | |
921 | .SS "unlock" | |
922 | Unlocks a passphrase-locked key or key component. If the key is not | |
923 | locked, an error is reported. | |
924 | .SS "list" | |
d03ab969 | 925 | Lists the keys in the keyring. A couple of options are supported: |
926 | .TP | |
927 | .B "\-v, \-\-verbose" | |
928 | Increases the amount of information displayed for each key. Repeat for | |
929 | a greater effect. | |
930 | .TP | |
931 | .B "\-q, \-\-quiet" | |
932 | Decreases the amount of information displayed for each key. Each use | |
933 | cancels a | |
934 | .RB ` \-v ' | |
935 | option. | |
c9e31e42 | 936 | .TP |
937 | .B "\-u, \-\-utc" | |
938 | Display key expiry times as UTC rather than using the local time zone. | |
052b36d0 | 939 | .TP |
940 | .BI "\-f, \-\-filter " filter | |
941 | Specifies a filter. Only keys and key components which match the filter | |
942 | are listed. | |
d03ab969 | 943 | .PP |
944 | By default, a single line of output is generated for each, showing | |
945 | keyids, types, expiry and deletion dates, and comments. Additional | |
946 | .RB ` \-v ' | |
947 | options show more information, such as the exact time of day for expiry | |
052b36d0 | 948 | and deletion, key attributes, and a dump of the actual key data. If the |
949 | verbosity level is sufficiently high, passphrases are requested to | |
950 | decrypt locked keys. Make sure nobody is looking over your shoulder | |
951 | when you do this! | |
952 | .SS "fingerprint" | |
953 | Reports a fingerprint (secure hash) on components of requested keys. | |
58507325 | 954 | The following options are supported: |
052b36d0 | 955 | .TP |
956 | .BI "\-f, \-\-filter " filter | |
957 | Specifies a filter. Only keys and key components which match the filter | |
958 | are fingerprinted. The default is to only fingerprint nonsecret | |
959 | components. | |
b817bfc6 | 960 | .TP |
16810bbd MW |
961 | .BI "\-p, \-\-presentation " style |
962 | Write fingerprints in the given | |
963 | .IR style . | |
964 | See below for a list of presentation styles. | |
965 | .TP | |
b817bfc6 | 966 | .BI "\-a, \-\-algorithm " hash |
967 | Names the hashing algorithm. Run | |
58507325 | 968 | .B key show hash |
b817bfc6 | 969 | for a list of hashing algorithms. The default is |
970 | .BR rmd160 . | |
052b36d0 | 971 | .PP |
972 | The keys to be fingerprinted are named by their tags or keyids given as | |
973 | command line arguments. If no key tags are given, all keys which match | |
b817bfc6 | 974 | the filter are fingerprinted. See |
975 | .BR keyring (5) | |
976 | for a description of how key fingerprints are computed. | |
16810bbd MW |
977 | .PP |
978 | The fingerprint may be shown in the following styles. | |
979 | .TP | |
980 | .B hex | |
981 | Lowercase hexadecimal, with groups of eight digits separated by hyphens | |
982 | (`\-'). This is the default presentation style. (On input, colons are | |
983 | also permitted as separators.) | |
984 | .TP | |
985 | .B base32 | |
986 | Lowercase Base32 encoding, without `=' padding, with groups of six | |
987 | digits separated by colons (`:'). (On input, padding characters are | |
988 | ignored.) | |
58507325 | 989 | .SS "verify" |
990 | Check a key's fingerprint against a reference copy. The following | |
991 | options are supported: | |
992 | .TP | |
993 | .BI "\-f, \-\-filter " filter | |
994 | Specifies a filter. Only key components which match the filter are | |
995 | hashed. The default is to only fingerprint nonsecret components. An | |
996 | error is reported if no part of the key matches. | |
997 | .TP | |
16810bbd MW |
998 | .BI "\-p, \-\-presentation " style |
999 | Expect the | |
1000 | .I fingerprint | |
1001 | to be in the given presentation | |
1002 | .IR style . | |
1003 | These match the styles produced by the | |
1004 | .B fingerprint | |
1005 | command described above. | |
1006 | .TP | |
58507325 | 1007 | .BI "\-a, \-\-algorithm " hash |
1008 | Names the hashing algorithm. Run | |
1009 | .B key show hash | |
1010 | for a list of hashing algorithms. The default is | |
1011 | .BR rmd160 . | |
1012 | .PP | |
16810bbd MW |
1013 | The fingerprint should be provided in the form printed by the |
1014 | .B fingerprint | |
1015 | command, using the same presentation | |
1016 | .IR style . | |
1017 | A little flexibility is permitted: separators may be placed anywhere (or | |
1018 | not at all) and are ignored; whitespace is permitted and ignored; and | |
1019 | case is ignored in presentation styles which don't make use of both | |
1020 | upper- and lower-case characters. | |
052b36d0 | 1021 | .SS "tidy" |
d03ab969 | 1022 | Simply reads the keyring from file and writes it back again. This has |
1023 | the effect of removing any deleted keys from the file. | |
052b36d0 | 1024 | .SS "extract" |
1025 | Writes a selection of keys to a file. An option is supported: | |
1026 | .TP | |
1027 | .BI "\-f, \-\-filter " filter | |
1028 | Specifies a filter. Only keys and key components which match the filter | |
1029 | are written. | |
1030 | .PP | |
1031 | Keys extracted are written to the file named by the first argument, | |
d03ab969 | 1032 | which may be |
1033 | .RB ` \- ' | |
1034 | to designate standard output. The keys to extract are listed by their | |
052b36d0 | 1035 | tags; if no tags are given, all keys which match the filter are |
1036 | extracted. The output is a valid keyring file. | |
1037 | .SS "merge" | |
d03ab969 | 1038 | Merges the keys from the named |
1039 | .IR file , | |
1040 | which may be | |
1041 | .RB ` \- ' | |
1042 | to designate standard input, with the keyring. Keys already in the | |
1043 | keyring are not overwritten: you must explicitly remove them first if | |
1044 | you want them to be replaced during the merge. | |
d03ab969 | 1045 | .SH "SEE ALSO" |
1046 | .BR keyring (5). | |
1047 | .SH AUTHOR | |
f387fcb1 | 1048 | Mark Wooding, <mdw@distorted.org.uk> |