| 1 | .\" -*-nroff-*- |
| 2 | .de VS |
| 3 | .sp 1 |
| 4 | .RS |
| 5 | .nf |
| 6 | .ft B |
| 7 | .. |
| 8 | .de VE |
| 9 | .ft R |
| 10 | .fi |
| 11 | .RE |
| 12 | .sp 1 |
| 13 | .. |
| 14 | .ie t \{\ |
| 15 | . if \n(.g \{\ |
| 16 | . fam P |
| 17 | . \} |
| 18 | .\} |
| 19 | .de hP |
| 20 | .IP |
| 21 | .ft B |
| 22 | \h'-\w'\\$1\ 'u'\\$1\ \c |
| 23 | .ft P |
| 24 | .. |
| 25 | .ie t .ds o \(bu |
| 26 | .el .ds o o |
| 27 | .TH catcrypt 1 "30 September 2004" "Straylight/Edgeware" "Catacomb cryptographic library" |
| 28 | .SH NAME |
| 29 | catcrypt \- encrypt and decrypt messages |
| 30 | .SH SYNOPSIS |
| 31 | .B catcrypt |
| 32 | .RB [ \-k |
| 33 | .IR keyring ] |
| 34 | .I command |
| 35 | .PP |
| 36 | where |
| 37 | .I command |
| 38 | is one of: |
| 39 | .PP |
| 40 | .B help |
| 41 | .RI [ command ...] |
| 42 | .br |
| 43 | .B show |
| 44 | .RI [ item ...] |
| 45 | .br |
| 46 | .B encrypt |
| 47 | .RB [ \-apC ] |
| 48 | .RB [ \-k |
| 49 | .IR tag ] |
| 50 | .RB [ \-f |
| 51 | .IR format ] |
| 52 | .RB [ \-o |
| 53 | .IR output ] |
| 54 | .RI [ file ] |
| 55 | .br |
| 56 | .B decrypt |
| 57 | .RB [ \-apqvC ] |
| 58 | .RB [ \-f |
| 59 | .IR format ] |
| 60 | .RB [ \-o |
| 61 | .IR output ] |
| 62 | .RI [ file ] |
| 63 | .br |
| 64 | .B encode |
| 65 | .RB [ \-p ] |
| 66 | .RB [ \-f |
| 67 | .IR format ] |
| 68 | .RB [ \-b |
| 69 | .IR boundary ] |
| 70 | .RB [ \-o |
| 71 | .IR output ] |
| 72 | .RI [ file ] |
| 73 | .br |
| 74 | .B decode |
| 75 | .RB [ \-p ] |
| 76 | .RB [ \-f |
| 77 | .IR format ] |
| 78 | .RB [ \-b |
| 79 | .IR boundary ] |
| 80 | .RB [ \-o |
| 81 | .IR output ] |
| 82 | .RI [ file ] |
| 83 | .SH "DESCRIPTION" |
| 84 | The |
| 85 | .B catcrypt |
| 86 | command encrypts and decrypts messages. It also works as a simple PEM |
| 87 | encoder and decoder. It provides a number of subcommands, by which the |
| 88 | various operations may be carried out. |
| 89 | .SS "Global options" |
| 90 | Before the command name, |
| 91 | .I "global options" |
| 92 | may be given. The following global options are supported: |
| 93 | .TP |
| 94 | .BR "\-h, \-\-help " [ \fIcommand ...] |
| 95 | Writes a brief summary of |
| 96 | .BR catcrypt 's |
| 97 | various options to standard output, and returns a successful exit |
| 98 | status. With command names, gives help on those commands. |
| 99 | .TP |
| 100 | .B "\-v, \-\-version" |
| 101 | Writes the program's version number to standard output, and returns a |
| 102 | successful exit status. |
| 103 | .TP |
| 104 | .B "\-u, \-\-usage" |
| 105 | Writes a very terse command line summary to standard output, and returns |
| 106 | a successful exit status. |
| 107 | .TP |
| 108 | .BI "\-k, \-\-keyring " file |
| 109 | Names the keyring file which |
| 110 | .B key |
| 111 | is to process. The default keyring, used if this option doesn't specify |
| 112 | one, is the file named |
| 113 | .B keyring |
| 114 | in the current directory. See |
| 115 | .BR key (1) |
| 116 | and |
| 117 | .BR keyring (5) |
| 118 | for more details about keyring files. |
| 119 | .SH "KEY SETUP" |
| 120 | Algorithms to be used with a particular key are described by attributes |
| 121 | on the key, or its type. The |
| 122 | .B catcrypt |
| 123 | command deals with both signing and key-encapsulation keys. (Note that |
| 124 | .B catcrypt |
| 125 | uses signing keys in the same way as |
| 126 | .BR catsign (1).) |
| 127 | .SS "Key-encapsulation keys" |
| 128 | (Key encapsulation is a means of transmitting a short, known, random |
| 129 | secret to a recipient. It differs from encryption in technical ways |
| 130 | which are largely uninteresting at this point.) |
| 131 | .PP |
| 132 | A |
| 133 | .I kemalgspec |
| 134 | has the syntax |
| 135 | .IR kem \c |
| 136 | .RB [ / \c |
| 137 | .IR cipher \c |
| 138 | .RB [ / \c |
| 139 | .IR hash ]]. |
| 140 | If a |
| 141 | .B kem |
| 142 | attribute is present on the key, then it must have this form; otherwise, |
| 143 | the key's type must have the form |
| 144 | .BR cckem- \c |
| 145 | .IR kemalgspec . |
| 146 | Algorithm selections are taken from appropriately-named attributes, or, |
| 147 | failing that, from the |
| 148 | .IR kemalgspec . |
| 149 | .PP |
| 150 | The key-encapsulation mechanism is chosen according to the setting of |
| 151 | .I kem |
| 152 | as follows. Run |
| 153 | .B catcrypt show kem |
| 154 | for a list of supported KEMs. |
| 155 | .TP |
| 156 | .B rsa |
| 157 | This is Shoup's RSA-KEM (formerly Simple RSA); see |
| 158 | .I |
| 159 | A proposal for an ISO standard for public key encryption (version 2.0) |
| 160 | available at |
| 161 | .BR http://eprint.iacr.org/2000/060/ . |
| 162 | Use the |
| 163 | .B rsa |
| 164 | algorithm of the |
| 165 | .B key add |
| 166 | command (see |
| 167 | .BR key (1)) |
| 168 | to generate the key. |
| 169 | .TP |
| 170 | .B dh |
| 171 | This is standard Diffie-Hellman key exchange, hashing the resulting |
| 172 | shared secret to form the key, as used in, e.g., DLIES (P1363a). |
| 173 | Use the |
| 174 | .B dh |
| 175 | algorithm of the |
| 176 | .B key add |
| 177 | command, preferably with the |
| 178 | .B \-LS |
| 179 | options, to generate the key. |
| 180 | .TP |
| 181 | .B ec |
| 182 | This is the elliptic-curve analogue of |
| 183 | .BR dh . |
| 184 | Use the |
| 185 | .B ec |
| 186 | algorithm of the |
| 187 | .BR key (1)) |
| 188 | command to generate the key. |
| 189 | .TP |
| 190 | .B symm |
| 191 | This is a simple symmetric encapsulation scheme. It works by hashing a |
| 192 | binary key with a randomly-generated salt. Use the |
| 193 | .B binary |
| 194 | algorithm of the |
| 195 | .B key add |
| 196 | command (see |
| 197 | .BR key (1)) |
| 198 | to generate the key. |
| 199 | .PP |
| 200 | As well as the KEM itself, a number of supporting algorithms are used. |
| 201 | These are taken from appropriately named attributes on the key or, |
| 202 | failing that, derived from other attributes as described below. |
| 203 | .TP |
| 204 | .B cipher |
| 205 | This is the symmetric encryption algorithm used for bulk data |
| 206 | encryption. If there is no |
| 207 | .B cipher |
| 208 | attribute then the |
| 209 | .I cipher |
| 210 | in the |
| 211 | .I kemalgspec |
| 212 | is used; if that it absent, then the default of |
| 213 | .B blowfish-cbc |
| 214 | is used. Run |
| 215 | .B catcrypt show cipher |
| 216 | for a list of supported symmetric encryption algorithms. |
| 217 | .TP |
| 218 | .B hash |
| 219 | This is the hash function used to distil entropy from the shared secret |
| 220 | constructed by the raw KEM. If there is no |
| 221 | .B hash |
| 222 | attribute then the |
| 223 | .I hash |
| 224 | in the |
| 225 | .I kemalgspec |
| 226 | is used; if that is absent then the default of |
| 227 | .B rmd160 |
| 228 | is used. Run |
| 229 | .B catcrypt show hash |
| 230 | for a list of supported symmetric encryption algorithms. |
| 231 | .TP |
| 232 | .B mac |
| 233 | This is the message authentication algorithm used during bulk data |
| 234 | encryption to ensure integrity of the encrypted message and defend |
| 235 | against chosen-ciphertext attacks. If there is no |
| 236 | .B mac |
| 237 | attribute then |
| 238 | .IB hash -hmac |
| 239 | is chosen as a default. Run |
| 240 | .B catcrypt show mac |
| 241 | for a list of supported message authentication algorithms. |
| 242 | .TP |
| 243 | .B kdf |
| 244 | This is the key derivation function used to stretch the hashed shared |
| 245 | secret to a sufficient length to select symmetric encryption and |
| 246 | authentication keys, initialization vectors and other necessary |
| 247 | pseudorandom quantities. If there is no |
| 248 | .B kdf |
| 249 | attribute then |
| 250 | .IB hash -mgf |
| 251 | is chosen as a default. Run |
| 252 | .B catcrypt show kdf |
| 253 | for a list of supported key derivation functions. |
| 254 | .B Caution! |
| 255 | Not all supported functions have the required security features: don't |
| 256 | override the default choice unless you know what you're doing. |
| 257 | .SS "Signing keys" |
| 258 | A |
| 259 | .I sigalgspec |
| 260 | has the form |
| 261 | .IR sig \c |
| 262 | .RB [ / \c |
| 263 | .IR hash ]. |
| 264 | If a |
| 265 | .B sig |
| 266 | attribute is present on the key, then it must have this form; otherwise, |
| 267 | the key's type must have the form |
| 268 | .BI ccsig- \c |
| 269 | .IR sigalgspec . |
| 270 | Algorithm selections are taken from appropriately-named attributes, or, |
| 271 | failing that, from the |
| 272 | .IR sigalgspec . |
| 273 | .PP |
| 274 | The signature algorithm is chosen according to the setting of |
| 275 | .I sig |
| 276 | as follows. Run |
| 277 | .B catcrypt show sig |
| 278 | for a list of supported signature algorithms. |
| 279 | .TP |
| 280 | .B rsapkcs1 |
| 281 | This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in |
| 282 | RFC3447; the difference is that the hash is left bare rather than being |
| 283 | wrapped in a DER-encoded |
| 284 | .B DigestInfo |
| 285 | structure. This doesn't affect security since the key can only be used |
| 286 | with the one hash function anyway, and dropping the DER wrapping permits |
| 287 | rapid adoption of new hash functions. Regardless, use of this algorithm |
| 288 | is not recommended, since the padding method has been shown vulnerable |
| 289 | to attack. Use the |
| 290 | .B rsa |
| 291 | algorithm of the |
| 292 | .B key add |
| 293 | command (see |
| 294 | .BR key (1)) |
| 295 | to generate the key. |
| 296 | .TP |
| 297 | .B rsapss |
| 298 | This is the RSASSA-PSS algorithm described in RFC3447. It is the |
| 299 | preferred RSA-based signature scheme. Use the |
| 300 | .B rsa |
| 301 | algorithm of the |
| 302 | .B key add |
| 303 | command (see |
| 304 | .BR key (1)) |
| 305 | to generate the key. |
| 306 | .TP |
| 307 | .B dsa |
| 308 | This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the |
| 309 | .B dsa |
| 310 | algorithm of the |
| 311 | .B key add |
| 312 | command (see |
| 313 | .BR key (1)) |
| 314 | to generate the key. |
| 315 | .TP |
| 316 | .B ecdsa |
| 317 | This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use |
| 318 | the |
| 319 | .B ec |
| 320 | algorithm of the |
| 321 | .B key add |
| 322 | command (see |
| 323 | .BR key (1)) |
| 324 | to generate the key. |
| 325 | .TP |
| 326 | .B kcdsa |
| 327 | This is the revised KCDSA (Korean Certificate-based Digital Signature |
| 328 | Algorithm) described in |
| 329 | .I The Revised Version of KCDSA |
| 330 | .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ). |
| 331 | Use the |
| 332 | .B dh |
| 333 | algorithm of the |
| 334 | .B key add |
| 335 | command with the |
| 336 | .B \-LS |
| 337 | options (see |
| 338 | .BR key (1)) |
| 339 | to generate the key. |
| 340 | .TP |
| 341 | .B eckcdsa |
| 342 | This is an unofficial elliptic-curve analogue of the KCDSA algorithm. |
| 343 | Use the |
| 344 | .B ec |
| 345 | algorithm of the |
| 346 | .B key add |
| 347 | command (see |
| 348 | .BR key (1)) |
| 349 | to generate the key. |
| 350 | .TP |
| 351 | .B mac |
| 352 | This uses a symmetric message-authentication algorithm rather than a |
| 353 | digital signature. The precise message-authentication scheme used is |
| 354 | determined by the |
| 355 | .B mac |
| 356 | attribute on the key, which defaults to |
| 357 | .IB hash -hmac |
| 358 | if unspecified. Use the |
| 359 | .B binary |
| 360 | algorithm of the |
| 361 | .B key add |
| 362 | command (see |
| 363 | .BR key (1)) |
| 364 | to generate the key. |
| 365 | .PP |
| 366 | As well as the signature algorithm itself, a hash function is used. |
| 367 | This is taken from the |
| 368 | .B hash |
| 369 | attribute on the key, or, failing that, from the |
| 370 | .I hash |
| 371 | specified in the |
| 372 | .IR sigalgspec , |
| 373 | or, if that is absent, determined by the signature algorithm as follows. |
| 374 | .hP \*o |
| 375 | For |
| 376 | .BR rsapkcs1 , |
| 377 | .BR rsapss , |
| 378 | .BR dsa , |
| 379 | and |
| 380 | .BR ecdsa , |
| 381 | the default hash function is |
| 382 | .BR sha . |
| 383 | .hP \*o |
| 384 | For |
| 385 | .BR kcdsa |
| 386 | and |
| 387 | .BR eckcdsa , |
| 388 | the default hash function is |
| 389 | .BR has160 . |
| 390 | .PP |
| 391 | Run |
| 392 | .B catcrypt show hash |
| 393 | for a list of supported hash functions. |
| 394 | .SH "ENCODINGS" |
| 395 | Two encodings for the ciphertext are supported. |
| 396 | .TP |
| 397 | .B binary |
| 398 | The raw format, which has the benefit of being smaller, but needs to be |
| 399 | attached to mail messages and generally handled with care. |
| 400 | .TP |
| 401 | .B pem |
| 402 | PEM-encapsulated Base-64 encoded text. This format can be included |
| 403 | directly in email and picked out again automatically; but there is a |
| 404 | 4-to-3 data expansion as a result. |
| 405 | .SH "COMMAND REFERENCE" |
| 406 | .SS help |
| 407 | The |
| 408 | .B help |
| 409 | command behaves exactly as the |
| 410 | .B \-\-help |
| 411 | option. With no arguments, it shows an overview of |
| 412 | .BR catcrypt 's |
| 413 | options; with arguments, it describes the named subcommands. |
| 414 | .SS show |
| 415 | The |
| 416 | .B show |
| 417 | command prints various lists of tokens understood by |
| 418 | .BR catcrypt . |
| 419 | With no arguments, it prints all of the lists; with arguments, it prints |
| 420 | just the named lists, in order. The recognized lists can be enumerated |
| 421 | using the |
| 422 | .VS |
| 423 | catcrypt show list |
| 424 | .VE |
| 425 | command. The lists are as follows. |
| 426 | .TP |
| 427 | .B list |
| 428 | The lists which can be enumerated by the |
| 429 | .B show |
| 430 | command. |
| 431 | .TP |
| 432 | .B kem |
| 433 | The key-encapsulation algorithms which can be used in a |
| 434 | key-encapsulation key's |
| 435 | .B kem |
| 436 | attribute. |
| 437 | .TP |
| 438 | .B cipher |
| 439 | The symmetric encryption algorithms which can be used in a |
| 440 | key-encapsulation key's |
| 441 | .B cipher |
| 442 | attribute. |
| 443 | .TP |
| 444 | .B mac |
| 445 | The message authentication algorithms which can be used in a |
| 446 | key-encapsulation key's |
| 447 | .B mac |
| 448 | attribute. |
| 449 | .TP |
| 450 | .B sig |
| 451 | The signature algorithms which can be used in a signing key's |
| 452 | .B sig |
| 453 | attribute. |
| 454 | .TP |
| 455 | .B hash |
| 456 | The hash functions which can be used in a key's |
| 457 | .B hash |
| 458 | attribute. |
| 459 | .TP |
| 460 | .B enc |
| 461 | The encodings which can be applied to encrypted messages; see |
| 462 | .B ENCODINGS |
| 463 | above. |
| 464 | .SS encrypt |
| 465 | The |
| 466 | .B encrypt |
| 467 | command encrypts a file and writes out the appropriately-encoded |
| 468 | ciphertext. By default, it reads from standard input and writes to |
| 469 | standard output. If a filename argument is given, this file is read |
| 470 | instead (as binary data). |
| 471 | .PP |
| 472 | The following options are recognized. |
| 473 | .TP |
| 474 | .B "\-a, \-\-armour" |
| 475 | Produce ASCII-armoured output. This is equivalent to specifying |
| 476 | .BR "\-f pem" . |
| 477 | The variant spelling |
| 478 | .B "\-\-armor" |
| 479 | is also accepted. |
| 480 | .TP |
| 481 | .BI "\-f, \-\-format " format |
| 482 | Produce output encoded according to |
| 483 | .IR format . |
| 484 | .TP |
| 485 | .BI "\-k, \-\-key " tag |
| 486 | Use the key-encapsulation key named |
| 487 | .I tag |
| 488 | in the current keyring; the default key is |
| 489 | .BR ccrypt . |
| 490 | .TP |
| 491 | .BI "\-p, \-\-progress" |
| 492 | Write a progress meter to standard error while processing large files. |
| 493 | .TP |
| 494 | .BI "\-s, \-\-sign-key " tag |
| 495 | Use the signature key named |
| 496 | .I tag |
| 497 | in the current keyring; the default is not to sign the ciphertext. |
| 498 | .TP |
| 499 | .BI "\-o, \-\-ouptut " file |
| 500 | Write output to |
| 501 | .I file |
| 502 | rather than to standard output. |
| 503 | .TP |
| 504 | .B "\-C, \-\-nocheck" |
| 505 | Don't check the public key for validity. This makes encryption go much |
| 506 | faster, but at the risk of using a duff key. |
| 507 | .SS decrypt |
| 508 | The |
| 509 | .B decrypt |
| 510 | command decrypts a ciphertext and writes out the plaintext. By default, |
| 511 | it reads from standard input and writes to standard output. If a |
| 512 | filename argument is given, this file is read instead. |
| 513 | .PP |
| 514 | The following options are recognized. |
| 515 | .TP |
| 516 | .B "\-a, \-\-armour" |
| 517 | Read ASCII-armoured input. This is equivalent to specifying |
| 518 | .BR "\-f pem" . |
| 519 | The variant spelling |
| 520 | .B "\-\-armor" |
| 521 | is also accepted. |
| 522 | .TP |
| 523 | .B "\-b, \-\-buffer" |
| 524 | Buffer plaintext data until we're sure we've got it all. This is forced |
| 525 | on if output is to stdout, but is always available as an option. |
| 526 | .TP |
| 527 | .BI "\-f, \-\-format " format |
| 528 | Read input encoded according to |
| 529 | .IR format . |
| 530 | .TP |
| 531 | .BI "\-p, \-\-progress" |
| 532 | Write a progress meter to standard error while processing large files. |
| 533 | .TP |
| 534 | .B "\-v, \-\-verbose" |
| 535 | Produce more verbose messages. See below for the messages produced |
| 536 | during decryption. The default verbosity level is 1. (Currently this |
| 537 | is the most verbose setting. This might not be the case always.) |
| 538 | .TP |
| 539 | .B "\-q, \-\-quiet" |
| 540 | Produce fewer messages. |
| 541 | .TP |
| 542 | .BI "\-o, \-\-output " file |
| 543 | Write output to |
| 544 | .I file |
| 545 | instead of to standard output. The file is written in binary mode. |
| 546 | Fixing line-end conventions is your problem; there are lots of good |
| 547 | tools for dealing with it. |
| 548 | .TP |
| 549 | .B "\-C, \-\-nocheck" |
| 550 | Don't check the private key for validity. This makes decryption go much |
| 551 | faster, but at the risk of using a duff key, and possibly leaking |
| 552 | information about the private key. |
| 553 | .PP |
| 554 | Output is written to standard output in a machine-readable format. |
| 555 | Major problems cause the program to write a diagnostic to standard error |
| 556 | and exit nonzero as usual. The quantity of output varies depending on |
| 557 | the verbosity level and whether the plaintext is also being written to |
| 558 | standard output. Output lines begin with a keyword: |
| 559 | .TP |
| 560 | .BI "FAIL " reason |
| 561 | An error prevented decryption. The program will exit nonzero. |
| 562 | .TP |
| 563 | .BI "WARN " reason |
| 564 | .B catcrypt |
| 565 | encountered a situation which may or may not invalidate the decryption. |
| 566 | .TP |
| 567 | .BI "OK " message |
| 568 | Decryption was successful. This is only produced if main output is |
| 569 | being sent somewhere other than standard output. |
| 570 | .TP |
| 571 | .B "DATA" |
| 572 | The plaintext follows, starting just after the next newline character or |
| 573 | sequence. This is only produced if main output is also being sent to |
| 574 | standard output. |
| 575 | .TP |
| 576 | .BI "INFO " note |
| 577 | Any other information. |
| 578 | .PP |
| 579 | The information written at the various verbosity levels is as follows. |
| 580 | .hP 0. |
| 581 | No output. Watch the exit status. |
| 582 | .hP 1. |
| 583 | All messages. |
| 584 | .PP |
| 585 | .B Warning! |
| 586 | All output written has been checked for authenticity. However, output |
| 587 | can fail madway through for many reasons, and the resulting message may |
| 588 | therefore be truncated. Don't rely on the output being complete until |
| 589 | .B OK |
| 590 | is printed or |
| 591 | .B catcrypt decrypt |
| 592 | exits successfully. |
| 593 | .SS "encode" |
| 594 | The |
| 595 | .B encode |
| 596 | command encodes an input file according to one of the encodings |
| 597 | described above in |
| 598 | .BR ENCODINGS . |
| 599 | The input is read from the |
| 600 | .I file |
| 601 | given on the command line, or from standard input if none is specified. |
| 602 | Options provided are: |
| 603 | .TP |
| 604 | .BI "\-p, \-\-progress" |
| 605 | Write a progress meter to standard error while processing large files. |
| 606 | .TP |
| 607 | .BI "\-f, \-\-format " format |
| 608 | Produce output in |
| 609 | .IR format . |
| 610 | Run |
| 611 | .B catcrypt show enc |
| 612 | for a list of encoding formats. |
| 613 | .TP |
| 614 | .BI "\-b, \-\-boundary " label |
| 615 | Set the PEM boundary string to |
| 616 | .IR label ; |
| 617 | i.e., assuming we're encoding in PEM format, the output will have |
| 618 | .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-" |
| 619 | at the top and |
| 620 | .BI "\-\-\-\-\-END " label "\-\-\-\-\-" |
| 621 | at the bottom. The default |
| 622 | .I label |
| 623 | is |
| 624 | .BR MESSAGE . |
| 625 | .TP |
| 626 | .BI "\-o, \-\-output " file |
| 627 | Write output to |
| 628 | .I file |
| 629 | instead of to standard output. |
| 630 | .SS "decode" |
| 631 | The |
| 632 | .B decode |
| 633 | command decodes an input file encoded according to one of the encodings |
| 634 | described above in |
| 635 | .BR ENCODINGS . |
| 636 | The input is read from the |
| 637 | .I file |
| 638 | given on the command line, or from standard input if none is specified. |
| 639 | Options provided are: |
| 640 | .TP |
| 641 | .BI "\-f, \-\-format " format |
| 642 | Decode input in |
| 643 | .IR format . |
| 644 | Run |
| 645 | .B catcrypt show enc |
| 646 | for a list of encoding formats. |
| 647 | .TP |
| 648 | .BI "\-b, \-\-boundary " label |
| 649 | Set the PEM boundary string to |
| 650 | .IR label ; |
| 651 | i.e., assuming we're encoding in PEM format, start processing input |
| 652 | between |
| 653 | .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-" |
| 654 | and |
| 655 | .BI "\-\-\-\-\-END " label "\-\-\-\-\-" |
| 656 | lines. Without this option, |
| 657 | .B catcrypt |
| 658 | will start reading at the first plausible boundary string, and continue |
| 659 | processing until it reaches the matching end boundary. |
| 660 | .TP |
| 661 | .BI "\-p, \-\-progress" |
| 662 | Write a progress meter to standard error while processing large files. |
| 663 | .TP |
| 664 | .BI "\-o, \-\-output " file |
| 665 | Write output to |
| 666 | .I file |
| 667 | instead of to standard output. |
| 668 | .SH "SECURITY PROPERTIES" |
| 669 | Assuming the security of the underlying primitive algorithms, the |
| 670 | following security properties of the ciphertext hold. |
| 671 | .hP \*o |
| 672 | An adversary given the public key-encapsulation key and capable of |
| 673 | requesting encryption of arbitrary plaintexts of his own devising is |
| 674 | unable to decide whether he is given ciphertexts corresponding to his |
| 675 | chosen plaintexts or random plaintexts of the same length. This holds |
| 676 | even if the adversary is permitted to request decryption of any |
| 677 | ciphertext other than one produced as a result of an encryption request. |
| 678 | This property is called |
| 679 | .BR IND-CCA2 . |
| 680 | .hP \*o |
| 681 | An adversary given the public key-encapsulation and verification keys, |
| 682 | and capable of requesting encryption of arbitrary plaintext of his own |
| 683 | devising is unable to produce a new ciphertext which will be accepted as |
| 684 | genuine. This property is called |
| 685 | .BR INT-CTXT . |
| 686 | .hP \*o |
| 687 | An adversary given the public key-encapsulation and verification keys, |
| 688 | and capable of requesting encryption of arbitrary plaintext of his own |
| 689 | devising is unable to decide whether the ciphertexts he is given are |
| 690 | correctly signed. This property doesn't seem to have a name. |
| 691 | .PP |
| 692 | Not all is rosy. If you leak intermediate values during decryption then |
| 693 | an adversary can construct a new correctly-signed message. Don't do |
| 694 | that, then \(en leaking intermediate values often voids security |
| 695 | warranties. But it does avoid the usual problem with separate signing |
| 696 | and encryption that a careful leak by the recipient can produce evidence |
| 697 | that you signed some incriminating message. |
| 698 | .PP |
| 699 | Note that |
| 700 | .BR catcrypt 's |
| 701 | signatures do |
| 702 | .I not |
| 703 | provide `non-repudiation' in any useful way. This is deliberate: the |
| 704 | purpose of signing is to convince the recipient of the sender's |
| 705 | identity, rather than to allow the recipient to persuade anyone else. |
| 706 | Indeed, given an encrypted and signed message, the recipient can |
| 707 | straightforwardly construct a new message, apparently from the same |
| 708 | sender, and whose signature still verifies, but with arbitrarily chosen |
| 709 | content. |
| 710 | .SH "CRYPTOGRAPHIC THEORY" |
| 711 | Encryption of a message proceeds as follows. |
| 712 | .hP 0. |
| 713 | Emit a header packet containing the key-ids for the key-encapsulation |
| 714 | key, and signature key if any. |
| 715 | .hP 1. |
| 716 | Use the KEM to produce a public value and a shared secret the recipient |
| 717 | will be able to extract from the public value using his private key. |
| 718 | Emit a packet containing the public value. |
| 719 | .hP 2. |
| 720 | Hash the shared secret. Use the KDF to produce a pseudorandom keystream |
| 721 | of indefinite length. |
| 722 | .hP 3. |
| 723 | Use the first bits of the keystream to key a symmetric encryption |
| 724 | scheme; use the next bits to key a message authentication code. |
| 725 | .hP 4. |
| 726 | If we're signing the message then extract 1024 bytes from the keystream, |
| 727 | sign the header and public value, and the keystream bytes; emit a packet |
| 728 | containing the signature. The signature packet doesn't contain the |
| 729 | signed message, just the signature. |
| 730 | .hP 5. |
| 731 | Split the message into blocks. For each block, pick a random IV from |
| 732 | the keystream, encrypt the block and emit a packet containing the |
| 733 | IV, ciphertext, and a MAC tag over the ciphertext and a sequence number. |
| 734 | .hP 6. |
| 735 | The last chunk is the encryption of an empty plaintext block. No |
| 736 | previous plaintext block is empty. This lets us determine the |
| 737 | difference between a complete file and one that's been maliciously |
| 738 | truncated. |
| 739 | .PP |
| 740 | That's it. Nothing terribly controversial, really. |
| 741 | .SH "SEE ALSO" |
| 742 | .BR key (1), |
| 743 | .BR catsign (1), |
| 744 | .BR dsig (1), |
| 745 | .BR hashsum (1), |
| 746 | .BR keyring (5). |
| 747 | .SH AUTHOR |
| 748 | Mark Wooding, <mdw@distorted.org.uk> |