| 1 | .\" -*-nroff-*- |
| 2 | .ie t \{\ |
| 3 | . if \n(.g \{\ |
| 4 | . fam P |
| 5 | . \} |
| 6 | . ds ss \s8\u |
| 7 | . ds se \d\s0 |
| 8 | . ds us \s8\d |
| 9 | . ds ue \u\s0 |
| 10 | . ds *b \(*b |
| 11 | .\} |
| 12 | .el \{\ |
| 13 | . ds ss ^ |
| 14 | . ds se |
| 15 | . ds us _ |
| 16 | . ds ue |
| 17 | . ds *b \fIbeta\fP |
| 18 | .\} |
| 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 | .. |
| 31 | .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library" |
| 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 |
| 44 | .B help |
| 45 | .RI [ command ...] |
| 46 | .br |
| 47 | .B show |
| 48 | .RI [ item ...] |
| 49 | .br |
| 50 | .B add |
| 51 | .RB [ \-lqrLKS ] |
| 52 | .RB [ \-a |
| 53 | .IR alg ] |
| 54 | .RB [ \-b | \-B |
| 55 | .IR bits ] |
| 56 | .RB [ \-p |
| 57 | .IR param ] |
| 58 | .RB [ \-R |
| 59 | .IR tag ] |
| 60 | .br |
| 61 | \h'8n' |
| 62 | .RB [ \-A |
| 63 | .IR seed-alg ] |
| 64 | .RB [ \-s |
| 65 | .IR seed ] |
| 66 | .RB [ \-n |
| 67 | .IR bits ] |
| 68 | .br |
| 69 | \h'8n' |
| 70 | .RB [ \-e |
| 71 | .IR expire ] |
| 72 | .RB [ \-t |
| 73 | .IR tag ] |
| 74 | .RB [ \-c |
| 75 | .IR comment ] |
| 76 | .RB [ \-C |
| 77 | .IR curve ] |
| 78 | .br |
| 79 | \h'8n' |
| 80 | .I type |
| 81 | .IR attr ... |
| 82 | .br |
| 83 | .B expire |
| 84 | .IR tag ... |
| 85 | .br |
| 86 | .B delete |
| 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 ] |
| 96 | .br |
| 97 | .B setattr |
| 98 | .I tag |
| 99 | .IR attr ... |
| 100 | .br |
| 101 | .B getattr |
| 102 | .I tag |
| 103 | .I attr |
| 104 | .br |
| 105 | .B lock |
| 106 | .I qtag |
| 107 | .br |
| 108 | .B unlock |
| 109 | .I qtag |
| 110 | .br |
| 111 | .B list |
| 112 | .RB [ \-uqv ] |
| 113 | .RB [ \-f |
| 114 | .IR filter ] |
| 115 | .RI [ tag ...] |
| 116 | .br |
| 117 | .B fingerprint |
| 118 | .RB [ \-f |
| 119 | .IR filter ] |
| 120 | .RB [ \-p |
| 121 | .IR style ] |
| 122 | .RB [ \-a |
| 123 | .IR hash ] |
| 124 | .RI [ tag ...] |
| 125 | .br |
| 126 | .B verify |
| 127 | .RB [ \-f |
| 128 | .IR filter ] |
| 129 | .RB [ \-p |
| 130 | .IR style ] |
| 131 | .RB [ \-a |
| 132 | .IR hash ] |
| 133 | .I tag |
| 134 | .I fingerprint |
| 135 | .br |
| 136 | .B tidy |
| 137 | .br |
| 138 | .B extract |
| 139 | .RB [ \-f |
| 140 | .IR filter ] |
| 141 | .I file |
| 142 | .RI [ tag ...] |
| 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 |
| 157 | .BR "\-h, \-\-help " [ \fIcommand ...] |
| 158 | Writes a brief summary of |
| 159 | .BR key 's |
| 160 | various options to standard output, and |
| 161 | returns a successful exit status. With command names, gives help on |
| 162 | those commands. |
| 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 |
| 172 | .BI "\-k, \-\-keyring " file |
| 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 |
| 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 |
| 195 | .I deleted |
| 196 | key cannot be looked up by keyid. |
| 197 | .TP |
| 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" |
| 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 |
| 209 | characters, dots or colons. Applications use key types to obtain an |
| 210 | arbitrary but suitable key for some purpose. An |
| 211 | .I expired |
| 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" |
| 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 |
| 227 | .I structured |
| 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. |
| 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 , |
| 239 | .BR struct , |
| 240 | .BR ec , |
| 241 | .BR string , |
| 242 | or |
| 243 | .B encrypt |
| 244 | (describing the key encoding); |
| 245 | .BR symmetric , |
| 246 | .BR private , |
| 247 | .BR public , |
| 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. |
| 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 |
| 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 |
| 277 | applications, and will be removed from the keyring next time it's |
| 278 | written to disk. |
| 279 | .TP |
| 280 | .B "comment" |
| 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 |
| 285 | .B "attributes" |
| 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 |
| 288 | attributes may have meaning for particular applications or key types; |
| 289 | others may be assigned global meanings in future. |
| 290 | .SH "COMMAND REFERENCE" |
| 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 |
| 320 | and |
| 321 | .B verify |
| 322 | commands. |
| 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 |
| 330 | The built-in Diffie\(enHellman groups which can be used with the |
| 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. |
| 347 | .TP |
| 348 | .B fpres |
| 349 | Fingerprint presentation styles, as used by the |
| 350 | .B fingerprint |
| 351 | and |
| 352 | .B verify |
| 353 | commands. |
| 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 |
| 360 | .BI "\-a, \-\-algorithm " alg |
| 361 | Selects a key generation algorithm. The default algorithm is |
| 362 | .BR binary ; |
| 363 | the different algorithms are described below. The command |
| 364 | .B key show keygen |
| 365 | lists the recognized key-generation algorithms. |
| 366 | .TP |
| 367 | .BI "\-b, \-\-bits " bits |
| 368 | The length of the key to generate, in bits. The default, if this option |
| 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. |
| 377 | A new key also inherits attributes from its parameter key. |
| 378 | .TP |
| 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 |
| 424 | .BI "\-e, \-\-expire " expire |
| 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 |
| 440 | .BI "\-c, \-\-comment " comment |
| 441 | Sets a comment for the key. The default is not to attach a comment. |
| 442 | .TP |
| 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 |
| 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 |
| 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 |
| 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. |
| 474 | .TP |
| 475 | .BI "\-E, \-\-public-exponent" |
| 476 | Set the public exponent for RSA keys. |
| 477 | The default is 65537, |
| 478 | because this seems to be the overwhelmingly popular choice |
| 479 | among practitioners |
| 480 | and because it was the exponent used before this option was introduced. |
| 481 | The value 3 is fine unless you use a completely terrible padding scheme. |
| 482 | .TP |
| 483 | .BI "\-L, \-\-lim-lee" |
| 484 | When generating Diffie\(enHellman parameters, generate a Lim\(enLee |
| 485 | prime rather than a random (or safe) prime. See the details on |
| 486 | Diffie\(enHellman key generation below. |
| 487 | .TP |
| 488 | .BI "\-K, \-\-kcdsa" |
| 489 | When generating Diffie\(enHellman parameters, generate a KCDSA-style |
| 490 | Lim\(enLee prime rather than a random (or safe) prime. See the details |
| 491 | on Diffie\(enHellman key generation below. |
| 492 | .TP |
| 493 | .BI "\-S, \-\-subgroup" |
| 494 | When generating Diffie\(enHellman parameters with a Lim\(enLee prime, |
| 495 | choose a generator of a prime-order subgroup rather than a subgroup of |
| 496 | order |
| 497 | .RI ( p "\ \-\ 1)/2." |
| 498 | .PP |
| 499 | The key's type is given by the required |
| 500 | .I type |
| 501 | argument. Following the type are zero or more attributes, which are |
| 502 | attached to the key in the same way as for the |
| 503 | .B setattr |
| 504 | command. |
| 505 | .PP |
| 506 | The key-generation algorithms supported are as follows: |
| 507 | .TP |
| 508 | .B "binary" |
| 509 | Generates a plain binary key of the requested length. If the requested |
| 510 | key length is not a multiple of eight, the high-order bits of the first |
| 511 | octet of the key are zeroed. The default key length is 128 bits. |
| 512 | .TP |
| 513 | .B "des" |
| 514 | Generates a DES key, with parity bits. The key length must be 56, 112 |
| 515 | or 168; the default is 56. The low-order bit of each octet is ignored by |
| 516 | the DES algorithm; it is used to give each octet odd parity. |
| 517 | .TP |
| 518 | .B "rsa" |
| 519 | Generates a public/private key pair for use with the RSA algorithm. |
| 520 | .IP |
| 521 | The key components are |
| 522 | .I p |
| 523 | and |
| 524 | .IR q , |
| 525 | a pair of prime numbers; |
| 526 | .IR n , |
| 527 | the product of |
| 528 | .I p |
| 529 | and |
| 530 | .IR q ; |
| 531 | .IR e , |
| 532 | the public exponent; |
| 533 | .IR d , |
| 534 | the private exponent, chosen such that |
| 535 | .IR ed \~\(==\~1 |
| 536 | (mod |
| 537 | .RI lcm( p "\~\-\~1, " q \~\-\~1)); |
| 538 | and some other values useful for optimizing private-key operations: |
| 539 | .IR q "\*(ss\-1\*(se mod " p , |
| 540 | .IR d "\~mod " p \~\-\~1, |
| 541 | and |
| 542 | .IR d "\~mod " q \~\-\~1. |
| 543 | The values |
| 544 | .I n |
| 545 | and |
| 546 | .I e |
| 547 | constitute the public key; the rest must be kept secret. The key size |
| 548 | requested by the |
| 549 | .B \-b |
| 550 | option determines the size of the modulus |
| 551 | .IR n ; |
| 552 | the default is 1024 bits. |
| 553 | .IP |
| 554 | The key generation algorithm chooses |
| 555 | .I p |
| 556 | and |
| 557 | .I q |
| 558 | to be |
| 559 | .I strong |
| 560 | primes: both |
| 561 | .IR p \~\-\~1 |
| 562 | and |
| 563 | .IR p \~+\~1 |
| 564 | have large prime factors \(en call them |
| 565 | .I r |
| 566 | and |
| 567 | .I s |
| 568 | respectively \(en and |
| 569 | .IR r \~\-\~1 |
| 570 | also has a large prime factor; |
| 571 | .I q |
| 572 | has similar properties. |
| 573 | .IP |
| 574 | The modulus |
| 575 | .I n |
| 576 | cannot be sensibly used as a shared parameter, since knowledge of |
| 577 | corrssponding public and private exponents is sufficient to be able to |
| 578 | factor the modulus and recover other users' private keys. |
| 579 | .TP |
| 580 | .B "dh-param" |
| 581 | Generates parameters for use with the Diffie\(enHellman key exchange |
| 582 | protocol, and many related systems, such as ElGamal encryption and |
| 583 | signatures, and even DSA. (The separate DSA algorithm uses the |
| 584 | generator described in FIPS186-1.) |
| 585 | .IP |
| 586 | The Diffie\(enHellman parameters are a prime modulus |
| 587 | .I p |
| 588 | and a generator |
| 589 | .I g |
| 590 | of a subgroup of |
| 591 | .BR Z / \c |
| 592 | .IB p Z |
| 593 | of order |
| 594 | .IR q . |
| 595 | The |
| 596 | .B \-b |
| 597 | option controls the size of the modulus |
| 598 | .IR p ; |
| 599 | the default size is 1024 bits. |
| 600 | .IP |
| 601 | If no |
| 602 | .I q |
| 603 | size is selected using the |
| 604 | .B \-B |
| 605 | option and the Lim\(enLee prime options are disabled, then |
| 606 | .I p |
| 607 | is chosen to be a `safe' prime (i.e., |
| 608 | .IR p "\~= 2" q \~+\~1, |
| 609 | with |
| 610 | .I q |
| 611 | prime). Finding safe primes takes a very long time. In this case, the |
| 612 | value of |
| 613 | .I g |
| 614 | is fixed as 4. |
| 615 | .IP |
| 616 | If a size is chosen for |
| 617 | .I q |
| 618 | and Lim\(enLee primes are not selected then the prime |
| 619 | .I q |
| 620 | is generated and |
| 621 | .I p |
| 622 | is chosen so that |
| 623 | .IR p \~\-\~1 |
| 624 | is a multiple of |
| 625 | .IR q . |
| 626 | .IP |
| 627 | If the |
| 628 | .B \-L |
| 629 | option was given, Lim\(enLee primes are selected: the parameters are |
| 630 | chosen such that |
| 631 | .IR p "\~= 2\~" q \*(us0\*(ue |
| 632 | .IR q \*(us1\*(ue |
| 633 | .IR q \*(us2\*(ue\~...\~+\~1, |
| 634 | where the |
| 635 | .IR q \*(us i \*(ue |
| 636 | are primes at least as large as the setting given by the |
| 637 | .B \-B |
| 638 | option (or 256 bits, if no setting was given). |
| 639 | .IP |
| 640 | If the |
| 641 | .B \-K |
| 642 | option was given, KCDSA-style Lim\(enLee primes are selected: the |
| 643 | parameters are chosen such that |
| 644 | .IR p "\~= 2" qv \~+\~1, |
| 645 | where |
| 646 | .IR p, |
| 647 | .I q |
| 648 | and |
| 649 | .I v |
| 650 | are primes. |
| 651 | .IP |
| 652 | If the |
| 653 | .B \-S |
| 654 | or |
| 655 | .B \-K |
| 656 | options were given, the generator |
| 657 | .I g |
| 658 | is chosen to generate the subgroup of order |
| 659 | .IR q \*(us0\*(ue; |
| 660 | otherwise, |
| 661 | .I g |
| 662 | will generate the group of order |
| 663 | .RI ( p "\~\-\~1)/2\~= " q "\*(us0\*(ue " q \*(us1\*(ue |
| 664 | .IR q \*(us2\*(ue\~... |
| 665 | .IP |
| 666 | Finally, the |
| 667 | .B \-C |
| 668 | option can be given, in which case the parameters are taken directly |
| 669 | from the provided group specification, which may either be the the name |
| 670 | of one of the built-in groups (say |
| 671 | .B "key show dh" |
| 672 | for a list) or a triple |
| 673 | .RI ( p ,\~ q ,\~ g ). |
| 674 | separated by commas. No random generation is done in this case: the |
| 675 | given parameters are simply stored. |
| 676 | .TP |
| 677 | .B "dh" |
| 678 | Generates a public/private key pair for use with offline Diffie\(enHellman, |
| 679 | ElGamal, DSA or similar discrete-logarithm-based systems. It selects a |
| 680 | private key |
| 681 | .IR x \~<\~ q , |
| 682 | and computes the public key |
| 683 | .IR y "\~= " g \*(ss x "\*(se mod\~" p . |
| 684 | .TP |
| 685 | .B "dsa-param" |
| 686 | Generates parameters for the DSA algorithm. DSA parameters are also |
| 687 | suitable for use with Diffie\(enHellman and ElGamal system. |
| 688 | .IP |
| 689 | The main difference between DSA and Diffie\(enHellman parameter generation |
| 690 | is thatthe DSA parameter generation |
| 691 | algorithm creates a |
| 692 | .I seed |
| 693 | from which the parameters are derived, and, assuming that the SHA-1 hash |
| 694 | function is strong, it's not feasible to construct a seed from which |
| 695 | deliberately weak parameters are derived. The algorithm used is the one |
| 696 | described in the DSA standard, FIPS\ 186, extended only to allow |
| 697 | sequential search for a prime |
| 698 | .I q |
| 699 | and to allow arbitrary parameter sizes. The seed is stored, |
| 700 | Base64-encoded, as the value of the attribute |
| 701 | .BR seed . |
| 702 | .IP |
| 703 | The default lengths for |
| 704 | .I p |
| 705 | and |
| 706 | .I q |
| 707 | are 768 and 160 bits respectively, since the DSA standard specifies that |
| 708 | .I q |
| 709 | be 160 bits, and the choice of 768 bits for |
| 710 | .I p |
| 711 | gives commensurate security. |
| 712 | .TP |
| 713 | .B "dsa" |
| 714 | Generates a public/private key pair for DSA. As for Diffie\(enHellman |
| 715 | keys, it selects a |
| 716 | private key |
| 717 | .IR x \~<\~ q , |
| 718 | and computes the public key |
| 719 | .IR y "\~= " g \*(ss x "\*(se mod\~" p . |
| 720 | .TP |
| 721 | .B "bbs" |
| 722 | Generates a public/private key pair for the Blum-Blum-Shub random-number |
| 723 | generator, and the Blum-Goldwasser semantically-secure public-key |
| 724 | encryption system. |
| 725 | .IP |
| 726 | The key components are prime numbers |
| 727 | .I p |
| 728 | and |
| 729 | .IR q , |
| 730 | both congruent to 3 (mod\~4), and their product |
| 731 | .IR n . |
| 732 | The public key is simply the modulus |
| 733 | .IR n ; |
| 734 | the factors |
| 735 | .I p |
| 736 | and |
| 737 | .I q |
| 738 | are the private key. |
| 739 | .IP |
| 740 | The key-generation algorithm ensures that the two primes |
| 741 | .I p |
| 742 | and |
| 743 | .I q |
| 744 | are |
| 745 | .I strong |
| 746 | (see the discussion of strong primes above, in the section on RSA keys), |
| 747 | and that |
| 748 | .RI ( p \~\-\~1)/2 |
| 749 | and |
| 750 | .RI ( q \~\-\~1)/2 |
| 751 | are relatively prime, giving a maximum possible period length. |
| 752 | .IP |
| 753 | The key size requested by the |
| 754 | .B \-b |
| 755 | option determines the length of the modulus |
| 756 | .IR n ; |
| 757 | the default length is 1024 bits. |
| 758 | .TP |
| 759 | .B "ec-param" |
| 760 | Store an elliptic curve specification. If no explicit |
| 761 | .I curve-spec |
| 762 | is given (the |
| 763 | .RB ` \-C ' |
| 764 | option) then a curve is chosen whose order is about the size given by the |
| 765 | .RB ` \-b ' |
| 766 | option (default is 256 bits). |
| 767 | .IP |
| 768 | A |
| 769 | .I curve-spec |
| 770 | can be given explicitly (in which case |
| 771 | .RB ` \-b ' |
| 772 | is ignored). It can either be the name of a built-in curve (say |
| 773 | .B "key show ec" |
| 774 | for a list of curve names) or a full specification. The curve is |
| 775 | checked for correctness and security according to the SEC1 |
| 776 | specification: failed checks cause a warning to be issued to standard |
| 777 | error (though the program continues anyway). The check can be |
| 778 | suppressed using the |
| 779 | .RB ` \-q ' |
| 780 | option. |
| 781 | .IP |
| 782 | A curve specification consists of the following elements optionally |
| 783 | separated by whitespace: a |
| 784 | .IR "field type" , |
| 785 | which is one of |
| 786 | .BR "prime" , |
| 787 | .BR "niceprime" , |
| 788 | .BR "binpoly" , |
| 789 | .or |
| 790 | .BR "binnorm" ; |
| 791 | an optional |
| 792 | .RB ` : '; |
| 793 | the field modulus |
| 794 | .IR p ; |
| 795 | if the field type is |
| 796 | .B binnorm |
| 797 | then an optional |
| 798 | .RB ` , ' |
| 799 | and the representation of the normal element \*(*b; an optional |
| 800 | .RB ` ; '; |
| 801 | a |
| 802 | .IR "curve type" , |
| 803 | which is one of |
| 804 | .BR "prime" , |
| 805 | .BR "primeproj" , |
| 806 | .BR "bin" , |
| 807 | and |
| 808 | .BR "binproj" |
| 809 | (the `proj' types currently have much better performance); |
| 810 | an optional |
| 811 | .RB ` : '; |
| 812 | the two field-element parameters |
| 813 | .I a |
| 814 | and |
| 815 | .IR b |
| 816 | which define the elliptic curve |
| 817 | .IR E , |
| 818 | separated by an optional |
| 819 | .RB ` , '; |
| 820 | an optional |
| 821 | .RB ` ; '; |
| 822 | the |
| 823 | .IR x - |
| 824 | and |
| 825 | .IR y -coordinates |
| 826 | of the generator point |
| 827 | .IR G , |
| 828 | separated by an optional |
| 829 | .RB ` , '; |
| 830 | an optional |
| 831 | .RB ` : '; |
| 832 | the order |
| 833 | .I r |
| 834 | of the group generated by |
| 835 | .IR G ; |
| 836 | an optional |
| 837 | .RB ` * '; |
| 838 | and the |
| 839 | .I cofactor |
| 840 | .I h |
| 841 | = |
| 842 | .RI # E / r . |
| 843 | .TP |
| 844 | .B "ec" |
| 845 | Generate a private scalar and a corresponding public point on an |
| 846 | elliptic curve. See |
| 847 | .B ec-param |
| 848 | above for how to specify elliptic curve parameter sets. The scalar |
| 849 | .I x |
| 850 | is chosen unformly between 0 and the curve order |
| 851 | .IR r ; |
| 852 | the public point is then |
| 853 | .I x |
| 854 | \(mu |
| 855 | .IR G . |
| 856 | .TP |
| 857 | .B x25519 |
| 858 | Generate a private scalar and a corresponding public point on the |
| 859 | (Montgomery-form) Curve25519 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 |
| 865 | .B x448 |
| 866 | Generate a private scalar and a corresponding public point on the |
| 867 | (Montgomery-form) Ed448-Goldilocks elliptic curve. |
| 868 | The scalar is simply a random 256-bit string; |
| 869 | the public key is the |
| 870 | .IR x -coordinate |
| 871 | of the corresponding point. |
| 872 | .TP |
| 873 | .B ed25519 |
| 874 | Generate a private key and a corresponding public point on the |
| 875 | (twisted Edwards-form) Curve25519 elliptic curve. |
| 876 | The private key is simply a random 256-bit string, |
| 877 | from which a scalar and secret prefix are derived; |
| 878 | the public key is the compressed form of the corresponding point. |
| 879 | .TP |
| 880 | .B ed448 |
| 881 | Generate a private key and a corresponding public point on the |
| 882 | (Edwards-form) Ed448-Goldilocks elliptic curve. |
| 883 | The private key is simply a random 456-bit string, |
| 884 | from which a scalar and secret prefix are derived; |
| 885 | the public key is the compressed form of the corresponding point. |
| 886 | .TP |
| 887 | .B empty |
| 888 | Generate an empty key, with trivial contents. |
| 889 | This is useful as a `parameters' key, |
| 890 | carrying attributes to be applied to other keys |
| 891 | if they don't require more detailed parameters. |
| 892 | .SS "expire" |
| 893 | Forces keys to immediately expire. An expired key is not chosen when a |
| 894 | program requests a key by its type. The keys to expire are listed by |
| 895 | their |
| 896 | .IR tag s. |
| 897 | .SS "delete" |
| 898 | Deletes keys immediately. The keys to delete are listed by their |
| 899 | .IR tag s. |
| 900 | Be careful when deleting keys. It might be a better idea |
| 901 | to expire keys rather than deleting them. |
| 902 | .SS "tag" |
| 903 | Sets, deletes or changes the tag attached to a key. The first tag or |
| 904 | keyid names the key to be modified; the second, if present specifies the |
| 905 | new tag to be set. If no second argument is given, the existing tag, if |
| 906 | any, is removed and no new tag is set. It is an error to set a tag |
| 907 | which already exists on another key, unless you give the |
| 908 | .B \-r |
| 909 | option. |
| 910 | .PP |
| 911 | The following options are recognized. |
| 912 | .TP |
| 913 | .B "\-r, \-\-retag" |
| 914 | Untag the existing key with the desired new tag, if any. |
| 915 | .SS "setattr" |
| 916 | Attaches attributes to a key. The key to which the attributes should be |
| 917 | attached is given by its |
| 918 | .IR tag . |
| 919 | Each attribute has the form |
| 920 | .IB name = value\fR. |
| 921 | An attribute can be deleted by assigning it an empty value. Although |
| 922 | the keyring file format is capable of representing an attribute with an |
| 923 | empty value as distinct from a nonexistant attribute, this interface |
| 924 | does not allow empty attributes to be set. |
| 925 | .SS "getattr" |
| 926 | Fetches a single attribute of a key. The key whose attribute is to be |
| 927 | read is given by its |
| 928 | .IR tag . |
| 929 | The attribute's value is written to standard output followed by a |
| 930 | newline. If the key or attribute is absent, a message is written to |
| 931 | standard error and the program exits nonzero. |
| 932 | .SS "comment" |
| 933 | Sets, deletes or changes the comment attached to a key. The first |
| 934 | argument is a key tag or keyid which names the key to be modified; the |
| 935 | second, if present, is the new comment. If no second argument is given, |
| 936 | the existing comment, if any, is removed, and no new comment is set. |
| 937 | .SS "lock" |
| 938 | Locks a key or key component using a passphrase. If the key is already |
| 939 | locked, the existing passphrase is requested, and a new passphrase is |
| 940 | set. |
| 941 | .SS "unlock" |
| 942 | Unlocks a passphrase-locked key or key component. If the key is not |
| 943 | locked, an error is reported. |
| 944 | .SS "list" |
| 945 | Lists the keys in the keyring. A couple of options are supported: |
| 946 | .TP |
| 947 | .B "\-v, \-\-verbose" |
| 948 | Increases the amount of information displayed for each key. Repeat for |
| 949 | a greater effect. |
| 950 | .TP |
| 951 | .B "\-q, \-\-quiet" |
| 952 | Decreases the amount of information displayed for each key. Each use |
| 953 | cancels a |
| 954 | .RB ` \-v ' |
| 955 | option. |
| 956 | .TP |
| 957 | .B "\-u, \-\-utc" |
| 958 | Display key expiry times as UTC rather than using the local time zone. |
| 959 | .TP |
| 960 | .BI "\-f, \-\-filter " filter |
| 961 | Specifies a filter. Only keys and key components which match the filter |
| 962 | are listed. |
| 963 | .PP |
| 964 | By default, a single line of output is generated for each, showing |
| 965 | keyids, types, expiry and deletion dates, and comments. Additional |
| 966 | .RB ` \-v ' |
| 967 | options show more information, such as the exact time of day for expiry |
| 968 | and deletion, key attributes, and a dump of the actual key data. If the |
| 969 | verbosity level is sufficiently high, passphrases are requested to |
| 970 | decrypt locked keys. Make sure nobody is looking over your shoulder |
| 971 | when you do this! |
| 972 | .SS "fingerprint" |
| 973 | Reports a fingerprint (secure hash) on components of requested keys. |
| 974 | The following options are supported: |
| 975 | .TP |
| 976 | .BI "\-f, \-\-filter " filter |
| 977 | Specifies a filter. Only keys and key components which match the filter |
| 978 | are fingerprinted. The default is to only fingerprint nonsecret |
| 979 | components. |
| 980 | .TP |
| 981 | .BI "\-p, \-\-presentation " style |
| 982 | Write fingerprints in the given |
| 983 | .IR style . |
| 984 | See below for a list of presentation styles. |
| 985 | .TP |
| 986 | .BI "\-a, \-\-algorithm " hash |
| 987 | Names the hashing algorithm. Run |
| 988 | .B key show hash |
| 989 | for a list of hashing algorithms. The default is |
| 990 | .BR rmd160 . |
| 991 | .PP |
| 992 | The keys to be fingerprinted are named by their tags or keyids given as |
| 993 | command line arguments. If no key tags are given, all keys which match |
| 994 | the filter are fingerprinted. See |
| 995 | .BR keyring (5) |
| 996 | for a description of how key fingerprints are computed. |
| 997 | .PP |
| 998 | The fingerprint may be shown in the following styles. |
| 999 | .TP |
| 1000 | .B hex |
| 1001 | Lowercase hexadecimal, with groups of eight digits separated by hyphens |
| 1002 | (`\-'). This is the default presentation style. (On input, colons are |
| 1003 | also permitted as separators.) |
| 1004 | .TP |
| 1005 | .B base32 |
| 1006 | Lowercase Base32 encoding, without `=' padding, with groups of six |
| 1007 | digits separated by colons (`:'). (On input, padding characters are |
| 1008 | ignored.) |
| 1009 | .SS "verify" |
| 1010 | Check a key's fingerprint against a reference copy. The following |
| 1011 | options are supported: |
| 1012 | .TP |
| 1013 | .BI "\-f, \-\-filter " filter |
| 1014 | Specifies a filter. Only key components which match the filter are |
| 1015 | hashed. The default is to only fingerprint nonsecret components. An |
| 1016 | error is reported if no part of the key matches. |
| 1017 | .TP |
| 1018 | .BI "\-p, \-\-presentation " style |
| 1019 | Expect the |
| 1020 | .I fingerprint |
| 1021 | to be in the given presentation |
| 1022 | .IR style . |
| 1023 | These match the styles produced by the |
| 1024 | .B fingerprint |
| 1025 | command described above. |
| 1026 | .TP |
| 1027 | .BI "\-a, \-\-algorithm " hash |
| 1028 | Names the hashing algorithm. Run |
| 1029 | .B key show hash |
| 1030 | for a list of hashing algorithms. The default is |
| 1031 | .BR rmd160 . |
| 1032 | .PP |
| 1033 | The fingerprint should be provided in the form printed by the |
| 1034 | .B fingerprint |
| 1035 | command, using the same presentation |
| 1036 | .IR style . |
| 1037 | A little flexibility is permitted: separators may be placed anywhere (or |
| 1038 | not at all) and are ignored; whitespace is permitted and ignored; and |
| 1039 | case is ignored in presentation styles which don't make use of both |
| 1040 | upper- and lower-case characters. |
| 1041 | .SS "tidy" |
| 1042 | Simply reads the keyring from file and writes it back again. This has |
| 1043 | the effect of removing any deleted keys from the file. |
| 1044 | .SS "extract" |
| 1045 | Writes a selection of keys to a file. An option is supported: |
| 1046 | .TP |
| 1047 | .BI "\-f, \-\-filter " filter |
| 1048 | Specifies a filter. Only keys and key components which match the filter |
| 1049 | are written. |
| 1050 | .PP |
| 1051 | Keys extracted are written to the file named by the first argument, |
| 1052 | which may be |
| 1053 | .RB ` \- ' |
| 1054 | to designate standard output. The keys to extract are listed by their |
| 1055 | tags; if no tags are given, all keys which match the filter are |
| 1056 | extracted. The output is a valid keyring file. |
| 1057 | .SS "merge" |
| 1058 | Merges the keys from the named |
| 1059 | .IR file , |
| 1060 | which may be |
| 1061 | .RB ` \- ' |
| 1062 | to designate standard input, with the keyring. Keys already in the |
| 1063 | keyring are not overwritten: you must explicitly remove them first if |
| 1064 | you want them to be replaced during the merge. |
| 1065 | .SH "SEE ALSO" |
| 1066 | .BR keyring (5). |
| 1067 | .SH AUTHOR |
| 1068 | Mark Wooding, <mdw@distorted.org.uk> |