| 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 catsign 1 "17 March 2005" "Straylight/Edgeware" "Catacomb cryptographic library" |
| 28 | .SH NAME |
| 29 | catsign \- sign and verify messages |
| 30 | .SH SYNOPSIS |
| 31 | .B catsign |
| 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 sign |
| 47 | .RB [ \-adptC ] |
| 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 verify |
| 57 | .RB [ \-apquvC ] |
| 58 | .RB [ \-k |
| 59 | .IR tag ] |
| 60 | .RB [ \-f |
| 61 | .IR format ] |
| 62 | .RB [ \-t |
| 63 | .IR time ] |
| 64 | .br |
| 65 | |
| 66 | .RB [ \-o |
| 67 | .IR output ] |
| 68 | .RI [ file |
| 69 | .RI [ message ]] |
| 70 | .br |
| 71 | .B info |
| 72 | .RB [ \-a ] |
| 73 | .RB [ \-f |
| 74 | .IR format ] |
| 75 | .RI [ file ] |
| 76 | .br |
| 77 | .B format |
| 78 | .RB [ \-apuABDET ] |
| 79 | .RB [ \-f |
| 80 | .IR format ] |
| 81 | .RB [ \-F |
| 82 | .IR format ] |
| 83 | .br |
| 84 | |
| 85 | .RB [ \-m |
| 86 | .IR file ] |
| 87 | .RB [ \-o |
| 88 | .IR output ] |
| 89 | .RI [ file |
| 90 | .RI [ message ]] |
| 91 | .br |
| 92 | .B encode |
| 93 | .RB [ \-p ] |
| 94 | .RB [ \-f |
| 95 | .IR format ] |
| 96 | .RB [ \-b |
| 97 | .IR boundary ] |
| 98 | .RB [ \-o |
| 99 | .IR output ] |
| 100 | .RI [ file ] |
| 101 | .br |
| 102 | .B decode |
| 103 | .RB [ \-p ] |
| 104 | .RB [ \-f |
| 105 | .IR format ] |
| 106 | .RB [ \-b |
| 107 | .IR boundary ] |
| 108 | .RB [ \-o |
| 109 | .IR output ] |
| 110 | .RI [ file ] |
| 111 | .SH "DESCRIPTION" |
| 112 | The |
| 113 | .B catsign |
| 114 | command signs and verifies messages. It also works as a simple PEM |
| 115 | encoder and decoder. It provides a number of subcommands, by which the |
| 116 | various operations may be carried out. |
| 117 | .SS "Global options" |
| 118 | Before the command name, |
| 119 | .I "global options" |
| 120 | may be given. The following global options are supported: |
| 121 | .TP |
| 122 | .BR "\-h, \-\-help " [ \fIcommand ...] |
| 123 | Writes a brief summary of |
| 124 | .BR catsign 's |
| 125 | various options to standard output, and returns a successful exit |
| 126 | status. With command names, gives help on those commands. |
| 127 | .TP |
| 128 | .B "\-v, \-\-version" |
| 129 | Writes the program's version number to standard output, and returns a |
| 130 | successful exit status. |
| 131 | .TP |
| 132 | .B "\-u, \-\-usage" |
| 133 | Writes a very terse command line summary to standard output, and returns |
| 134 | a successful exit status. |
| 135 | .TP |
| 136 | .BI "\-k, \-\-keyring " file |
| 137 | Names the keyring file which |
| 138 | .B key |
| 139 | is to process. The default keyring, used if this option doesn't specify |
| 140 | one, is the file named |
| 141 | .B keyring |
| 142 | in the current directory. See |
| 143 | .BR key (1) |
| 144 | and |
| 145 | .BR keyring (5) |
| 146 | for more details about keyring files. |
| 147 | .SH "KEY SETUP" |
| 148 | Algorithms to be used with a particular key are described by attributes |
| 149 | on the key, or its type. The |
| 150 | .B catsign |
| 151 | command deals with signing keys. (Note that |
| 152 | .B catsign |
| 153 | uses signing keys in the same way as |
| 154 | .BR catcrypt (1).) |
| 155 | .PP |
| 156 | A |
| 157 | .I sigalgspec |
| 158 | has the form |
| 159 | .IR sig \c |
| 160 | .RB [ / \c |
| 161 | .IR hash ]. |
| 162 | If a |
| 163 | .B sig |
| 164 | attribute is present on the key, then it must have this form; otherwise, |
| 165 | the key's type must have the form |
| 166 | .BI ccsig- \c |
| 167 | .IR sigalgspec . |
| 168 | Algorithm selections are taken from appropriately-named attributes, or, |
| 169 | failing that, from the |
| 170 | .IR sigalgspec . |
| 171 | .PP |
| 172 | The signature algorithm is chosen according to the setting of |
| 173 | .I sig |
| 174 | as follows. Run |
| 175 | .B catsign show sig |
| 176 | for a list of supported signature algorithms. |
| 177 | .TP |
| 178 | .B rsapkcs1 |
| 179 | This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in |
| 180 | RFC3447; the difference is that the hash is left bare rather than being |
| 181 | wrapped in a DER-encoded |
| 182 | .B DigestInfo |
| 183 | structure. This doesn't affect security since the key can only be used |
| 184 | with the one hash function anyway, and dropping the DER wrapping permits |
| 185 | rapid adoption of new hash functions. Regardless, use of this algorithm |
| 186 | is not recommended, since the padding method has been shown vulnerable |
| 187 | to attack. Use the |
| 188 | .B rsa |
| 189 | algorithm of the |
| 190 | .B key add |
| 191 | command (see |
| 192 | .BR key (1)) |
| 193 | to generate the key. |
| 194 | .TP |
| 195 | .B rsapss |
| 196 | This is the RSASSA-PSS algorithm described in RFC3447. It is the |
| 197 | preferred RSA-based signature scheme. Use the |
| 198 | .B rsa |
| 199 | algorithm of the |
| 200 | .B key add |
| 201 | command (see |
| 202 | .BR key (1)) |
| 203 | to generate the key. |
| 204 | .TP |
| 205 | .B dsa |
| 206 | This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the |
| 207 | .B dsa |
| 208 | algorithm of the |
| 209 | .B key add |
| 210 | command (see |
| 211 | .BR key (1)) |
| 212 | to generate the key. |
| 213 | .TP |
| 214 | .B ecdsa |
| 215 | This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use |
| 216 | the |
| 217 | .B ec |
| 218 | algorithm of the |
| 219 | .B key add |
| 220 | command (see |
| 221 | .BR key (1)) |
| 222 | to generate the key. |
| 223 | .TP |
| 224 | .B kcdsa |
| 225 | This is the revised KCDSA (Korean Certificate-based Digital Signature |
| 226 | Algorithm) described in |
| 227 | .I The Revised Version of KCDSA |
| 228 | .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ). |
| 229 | Use the |
| 230 | .B dh |
| 231 | algorithm of the |
| 232 | .B key add |
| 233 | command with the |
| 234 | .B \-LS |
| 235 | options (see |
| 236 | .BR key (1)) |
| 237 | to generate the key. |
| 238 | .TP |
| 239 | .B eckcdsa |
| 240 | This is an unofficial elliptic-curve analogue of the KCDSA algorithm. |
| 241 | Use the |
| 242 | .B ec |
| 243 | algorithm of the |
| 244 | .B key add |
| 245 | command (see |
| 246 | .BR key (1)) |
| 247 | to generate the key. |
| 248 | .TP |
| 249 | .B mac |
| 250 | This uses a symmetric message-authentication algorithm rather than a |
| 251 | digital signature. The precise message-authentication scheme used is |
| 252 | determined by the |
| 253 | .B mac |
| 254 | attribute on the key, which defaults to |
| 255 | .IB hash -hmac |
| 256 | if unspecified. Use the |
| 257 | .B binary |
| 258 | algorithm of the |
| 259 | .B key add |
| 260 | command (see |
| 261 | .BR key (1)) |
| 262 | to generate the key. |
| 263 | .PP |
| 264 | As well as the signature algorithm itself, a hash function is used. |
| 265 | This is taken from the |
| 266 | .B hash |
| 267 | attribute on the key, or, failing that, from the |
| 268 | .I hash |
| 269 | specified in the |
| 270 | .IR sigalgspec , |
| 271 | or, if that is absent, determined by the signature algorithm as follows. |
| 272 | .hP \*o |
| 273 | For |
| 274 | .BR rsapkcs1 , |
| 275 | .BR rsapss , |
| 276 | .BR dsa , |
| 277 | and |
| 278 | .BR ecdsa , |
| 279 | the default hash function is |
| 280 | .BR sha . |
| 281 | .hP \*o |
| 282 | For |
| 283 | .BR kcdsa |
| 284 | and |
| 285 | .BR eckcdsa , |
| 286 | the default hash function is |
| 287 | .BR has160 . |
| 288 | .PP |
| 289 | Run |
| 290 | .B catsign show hash |
| 291 | for a list of supported hash functions. |
| 292 | .SH "ENCODINGS" |
| 293 | Two encodings for the ciphertext are supported. |
| 294 | .TP |
| 295 | .B binary |
| 296 | The raw format, which has the benefit of being smaller, but needs to be |
| 297 | attached to mail messages and generally handled with care. |
| 298 | .TP |
| 299 | .B pem |
| 300 | PEM-encapsulated Base-64 encoded text. This format can be included |
| 301 | directly in email and picked out again automatically; but there is a |
| 302 | 4-to-3 data expansion as a result. |
| 303 | .SH "SIGNATURE FORMATS" |
| 304 | There are two basic signature formats understood by |
| 305 | .BR catsign . |
| 306 | .hP \*o |
| 307 | Embedded signatures include (embed) the message they sign; hence they're |
| 308 | complete in and of themselves. The |
| 309 | .B catsign |
| 310 | program extracts the message during signature verification. |
| 311 | .hP \*o |
| 312 | Detached signatures are separate from the messages they sign, and both |
| 313 | the original file and the signature are required for a successful |
| 314 | verification. |
| 315 | .PP |
| 316 | Another important distinction is whether the message data is considered |
| 317 | to be plain text or raw binary data. |
| 318 | .hP \*o |
| 319 | When dealing with plain text, |
| 320 | .B catsign |
| 321 | allows a limited quantity of leeway in the messages it processes. It |
| 322 | ignores trailing whitespace on a line, including stray carriage-returns, |
| 323 | which may appear if Windows boxes have had their way with the data. It |
| 324 | also appends a final newline if there wasn't one before. In embedded |
| 325 | signatures, the text is left unencoded, so that the message is readable. |
| 326 | .hP \*o |
| 327 | Binary files are preserved completely, and no variation whatever is |
| 328 | permitted. |
| 329 | .PP |
| 330 | The |
| 331 | .VS |
| 332 | catsign format |
| 333 | .VE |
| 334 | command can convert between detached and embedded signatures; it cannot |
| 335 | convert between binary and text mode signatures. (The data actually |
| 336 | signed includes a flag saying whether the message is textual. The |
| 337 | rationale here is that what looks like an ASCII space before a newline |
| 338 | may be devastatingly significant in a binary data file, and if a message |
| 339 | is signed as raw binary then no changes whatever should be allowed.) |
| 340 | .SH "COMMAND REFERENCE" |
| 341 | .SS help |
| 342 | The |
| 343 | .B help |
| 344 | command behaves exactly as the |
| 345 | .B \-\-help |
| 346 | option. With no arguments, it shows an overview of |
| 347 | .BR catsign 's |
| 348 | options; with arguments, it describes the named subcommands. |
| 349 | .SS show |
| 350 | The |
| 351 | .B show |
| 352 | command prints various lists of tokens understood by |
| 353 | .BR catsign . |
| 354 | With no arguments, it prints all of the lists; with arguments, it prints |
| 355 | just the named lists, in order. The recognized lists can be enumerated |
| 356 | using the |
| 357 | .VS |
| 358 | catsign show list |
| 359 | .VE |
| 360 | command. The lists are as follows. |
| 361 | .TP |
| 362 | .B list |
| 363 | The lists which can be enumerated by the |
| 364 | .B show |
| 365 | command. |
| 366 | .TP |
| 367 | .B sig |
| 368 | The signature algorithms which can be used in a signing key's |
| 369 | .B sig |
| 370 | attribute. |
| 371 | .TP |
| 372 | .B hash |
| 373 | The hash functions which can be used in a key's |
| 374 | .B hash |
| 375 | attribute. |
| 376 | .TP |
| 377 | .B enc |
| 378 | The encodings which can be applied to encrypted messages; see |
| 379 | .B ENCODINGS |
| 380 | above. |
| 381 | .SS sign |
| 382 | The |
| 383 | .B sign |
| 384 | command signs a message and writes out an appropriately-encoded |
| 385 | signature. By default, it reads a message from standard input and |
| 386 | writes the signature to standard output. If a filename argument is |
| 387 | given, this file is read instead. |
| 388 | .PP |
| 389 | The following options are recognized. |
| 390 | .TP |
| 391 | .B "\-a, \-\-armour" |
| 392 | Produce ASCII-armoured output. This is equivalent to specifying |
| 393 | .BR "\-f pem" . |
| 394 | The variant spelling |
| 395 | .B "\-\-armor" |
| 396 | is also accepted. |
| 397 | .TP |
| 398 | .B "\-b, \-\-binary" |
| 399 | Read and sign the input as binary data. The default is to treat the |
| 400 | input as text. |
| 401 | .TP |
| 402 | .B "\-d, \-\-detach" |
| 403 | Produce a detached signature. The default is to produce a signature |
| 404 | with embedded message. |
| 405 | .TP |
| 406 | .BI "\-f, \-\-format " format |
| 407 | Produce output encoded according to |
| 408 | .IR format . |
| 409 | .TP |
| 410 | .BI "\-k, \-\-key " tag |
| 411 | Use the signing key named |
| 412 | .I tag |
| 413 | in the current keyring; the default key is |
| 414 | .BR ccsig . |
| 415 | .TP |
| 416 | .BI "\-o, \-\-ouptut " file |
| 417 | Write output to |
| 418 | .I file |
| 419 | rather than to standard output. |
| 420 | .TP |
| 421 | .BI "\-p, \-\-progress" |
| 422 | Write a progress meter to standard error while processing large files. |
| 423 | .TP |
| 424 | .B "\-t, \-\-text" |
| 425 | Read and sign the input as text. This is the default. |
| 426 | .TP |
| 427 | .B "\-C, \-\-nocheck" |
| 428 | Don't check the private key for validity. This makes signing go much |
| 429 | faster, but at the risk of using a duff key, and potentially leaking |
| 430 | information about the private key. |
| 431 | .SS verify |
| 432 | The |
| 433 | .B verify |
| 434 | command checks a signature's validity, producing as output information |
| 435 | about the signature and the signed message. |
| 436 | .PP |
| 437 | The first non-option argument is the name of the file containing the |
| 438 | signature data; this may be omitted or |
| 439 | .RB ` \- ' |
| 440 | to indicate that the signature be read from standard input. The second |
| 441 | non-option argument, if any, is the name of the file to read the message |
| 442 | from, if the signature is detached. An error is reported if a message |
| 443 | file is specified but the signature contains an embedded message |
| 444 | already; if the signature is detached but no filename is given, then the |
| 445 | message is expected on stdin (immediately after the signature, if any). |
| 446 | .TP |
| 447 | .B "\-a, \-\-armour" |
| 448 | Read ASCII-armoured input. This is equivalent to specifying |
| 449 | .BR "\-f pem" . |
| 450 | The variant spelling |
| 451 | .B "\-\-armor" |
| 452 | is also accepted. |
| 453 | .TP |
| 454 | .B "\-b, \-\-buffer" |
| 455 | Buffer the message until the signature is verified. This is forced on |
| 456 | if output is to stdout, but is always available as an option. |
| 457 | .TP |
| 458 | .BI "\-f, \-\-format " format |
| 459 | Read input encoded according to |
| 460 | .IR format . |
| 461 | .TP |
| 462 | .B "\-v, \-\-verbose" |
| 463 | Produce more verbose messages. See below for the messages produced |
| 464 | during decryption. The default verbosity level is 1. (Currently this |
| 465 | is the most verbose setting. This might not be the case always.) |
| 466 | .TP |
| 467 | .BI "\-p, \-\-progress" |
| 468 | Write a progress meter to standard error while processing large files. |
| 469 | .TP |
| 470 | .B "\-q, \-\-quiet" |
| 471 | Produce fewer messages. |
| 472 | .TP |
| 473 | .BI "\-k, \-\-key " tag |
| 474 | Usually |
| 475 | .B catsign |
| 476 | uses the signature header to work out which key to use to verify a |
| 477 | signature. Using this option causes verification to fail unless the |
| 478 | signature header specifies the key named |
| 479 | .IR tag . |
| 480 | .TP |
| 481 | .BI "\-t, \-\-freshtime " time |
| 482 | Only accept signatures claiming to have been made more recently than |
| 483 | .IR time . |
| 484 | If |
| 485 | .I time |
| 486 | is |
| 487 | .B always |
| 488 | (the default) then any timestamp in the past is acceptable. |
| 489 | .TP |
| 490 | .B "\-u, \-\-utc" |
| 491 | Show the datestamp in the signature in UTC rather than (your) local |
| 492 | time. The synonym |
| 493 | .B \-\-gmt |
| 494 | is also accepted. |
| 495 | .TP |
| 496 | .BI "\-o, \-\-output " file |
| 497 | Write the verified message to |
| 498 | .IR file . |
| 499 | The file is written in text or binary |
| 500 | mode as appropriate. The default is to write the message to standard |
| 501 | output unless verifying a detached signature, in which case nothing is |
| 502 | written. |
| 503 | .TP |
| 504 | .B "\-C, \-\-nocheck" |
| 505 | Don't check the public key for validity. This makes verification go |
| 506 | much faster, but at the risk of using a duff key, and potentially |
| 507 | accepting false signatures. |
| 508 | .PP |
| 509 | Output is written to standard output in a machine-readable format. |
| 510 | Major problems cause the program to write a diagnostic to standard error |
| 511 | and exit nonzero as usual. The quantity of output varies depending on |
| 512 | the verbosity level and whether the message is also being written to |
| 513 | standard output. Output lines begin with a keyword: |
| 514 | .TP |
| 515 | .BI "FAIL " reason |
| 516 | An error prevented verification. The program will exit nonzero. |
| 517 | .TP |
| 518 | .BI "WARN " reason |
| 519 | .B catsign |
| 520 | encountered a situation which may or may not invalidate the |
| 521 | verification. |
| 522 | .TP |
| 523 | .BI "OK " message |
| 524 | Verification was successful. This is only produced if the message is |
| 525 | being sent somewhere other than standard output. |
| 526 | .TP |
| 527 | .B "DATA" |
| 528 | The message follows, starting just after the next newline character or |
| 529 | sequence. This is only produced if the message is being written to |
| 530 | standard output. |
| 531 | .TP |
| 532 | .BI "INFO " note |
| 533 | Any other information. |
| 534 | .PP |
| 535 | The information written at the various verbosity levels is as follows. |
| 536 | .hP 0. |
| 537 | No output. Watch the exit status. |
| 538 | .hP 1. |
| 539 | All messages. |
| 540 | .PP |
| 541 | .B Warning! |
| 542 | Unless the |
| 543 | .B \-b |
| 544 | option is set (which happens automatically if writing to standard |
| 545 | output), |
| 546 | .BR catsign 's |
| 547 | output is |
| 548 | .I not |
| 549 | checked for authenticity until it has all been written. Even with |
| 550 | .BR \-b , |
| 551 | output can fail midway for many reasons, and the resulting message may |
| 552 | therefore be truncated. Don't rely on the output being complete until |
| 553 | .B OK |
| 554 | is printed or |
| 555 | .B catsign verify |
| 556 | exits successfully. |
| 557 | .SS info |
| 558 | The |
| 559 | .B info |
| 560 | command analyses a signature without verifying it, and prints |
| 561 | interesting information about it. This might be useful for diagnostic |
| 562 | purposes. No keys are needed for this operation, though you get more |
| 563 | useful information if you have them. |
| 564 | .PP |
| 565 | If a non-option argument is given, and it is not |
| 566 | .RB ` \- ', |
| 567 | then it is taken to name the file containing the signature to parse; |
| 568 | otherwise a signature is read from standard input. |
| 569 | .PP |
| 570 | The following options are recognized. |
| 571 | .TP |
| 572 | .B "\-a, \-\-armour" |
| 573 | Read ASCII-armoured input. This is equivalent to specifying |
| 574 | .BR "\-f pem" . |
| 575 | The variant spelling |
| 576 | .B "\-\-armor" |
| 577 | is also accepted. |
| 578 | .TP |
| 579 | .BI "\-f, \-\-format " format |
| 580 | Read input encoded according to |
| 581 | .IR format . |
| 582 | .TP |
| 583 | .BI "\-p, \-\-progress" |
| 584 | Write a progress meter to standard error while processing large files. |
| 585 | .TP |
| 586 | .B "\-u, \-\-utc" |
| 587 | Show the datestamp in the signature in UTC rather than (your) local |
| 588 | time. The synonym |
| 589 | .B \-\-gmt |
| 590 | is also accepted. |
| 591 | .PP |
| 592 | A description of the signature block is produced on standard output; it |
| 593 | is mostly machine-readable. The first word on each line explains what |
| 594 | kind of output it is. |
| 595 | .TP |
| 596 | .BI "BAD " message |
| 597 | The signature data is invalid and cannot be parsed. |
| 598 | .TP |
| 599 | .BI "WARN " message |
| 600 | Something is wrong with the data, but isn't fatal. |
| 601 | .TP |
| 602 | .BI "NOTE " message |
| 603 | An environmental problem means that the information isn't as helpful as |
| 604 | it might be. For example, the keyring file can't be opened, so we don't |
| 605 | know whether the verification key is there. |
| 606 | .TP |
| 607 | .BI "INFO flags " flags |
| 608 | Describes the flags set in the signature header. The |
| 609 | .I flags |
| 610 | are a list of flags, one per word, preceded by a |
| 611 | .RB ` ! ' |
| 612 | if the flag is clear. |
| 613 | .TP |
| 614 | .BI "INFO expected-flags " flags |
| 615 | If the PEM boundary string didn't match the actual signature data then |
| 616 | this line is output, listing the expected flags and their settings. |
| 617 | Problems with boundary mismatches can be resolved using the |
| 618 | .B format |
| 619 | command. |
| 620 | .TP |
| 621 | .BI "INFO date " yyyy "\-" mm "\-" dd " " hh ":" mm ":" ss " " tz |
| 622 | Signature was (allegedly!) made at the given time and date. If the |
| 623 | .B \-u |
| 624 | option was given, this will be in UTC. |
| 625 | .TP |
| 626 | .BI "INFO key " tag |
| 627 | Signature was (allegedly!) made using the key |
| 628 | .IR tag , |
| 629 | which is present in the current keyring. |
| 630 | .TP |
| 631 | .BI "INFO unknown-key " keyid |
| 632 | Signature was (allegedly!) made using the key with id |
| 633 | .IR keyid |
| 634 | which is not in the current keyring (or the keyring wasn't found). |
| 635 | .SS format |
| 636 | The |
| 637 | .B format |
| 638 | command translates signatures between the various supported formats. |
| 639 | This is a (slightly) more complex operation than re-encoding, though it |
| 640 | does not require any cryptographic operations. |
| 641 | .PP |
| 642 | The first non-option argument is the name of the file containing the |
| 643 | signature data; this may be omitted or |
| 644 | .RB ` \- ' |
| 645 | to indicate that the signature be read from standard input. The second |
| 646 | non-option argument, if any, is the name of the file to read the message |
| 647 | from, if the signature is detached. An error is reported if a message |
| 648 | file is specified but the signature contains an embedded message |
| 649 | already; if the signature is detached but no filename is given, then the |
| 650 | message is expected on stdin (immediately after the signature, if any). |
| 651 | .PP |
| 652 | The options follow a rough convention: options describing the input |
| 653 | format are lower-case and options specifying the output format are |
| 654 | upper-case. The following options are recognized. |
| 655 | .TP |
| 656 | .BI "\-a, \-\-armour-in" |
| 657 | Read ASCII-armoured input. This is equivalent to specifying |
| 658 | .BR "\-f pem" . |
| 659 | The variant spelling |
| 660 | .B "\-\-armor" |
| 661 | is also accepted. |
| 662 | .TP |
| 663 | .BI "\-p, \-\-progress" |
| 664 | Write a progress meter to standard error while processing large files. |
| 665 | .TP |
| 666 | .BI "\-A, \-\-armour-out" |
| 667 | Produce ASCII-armoured output. This is equivalent to specifying |
| 668 | .BR "\-F pem" . |
| 669 | The variant spelling |
| 670 | .B "\-\-armor-out" |
| 671 | is also accepted. |
| 672 | .TP |
| 673 | .B "\-D, \-\-detach" |
| 674 | Produce a detached signature. This may be used to detach a signature |
| 675 | from an embedded message. |
| 676 | .TP |
| 677 | .B "\-E, \-\-embed" |
| 678 | Produce a signature with embedded message. This may be used to |
| 679 | reattach a message to its detached signature. |
| 680 | .TP |
| 681 | .BI "\-f, \-\-format-in " format |
| 682 | Read input encoded according to |
| 683 | .IR format . |
| 684 | .TP |
| 685 | .BI "\-F, \-\-format-out " format |
| 686 | Produce output encoded according to |
| 687 | .IR format . |
| 688 | .TP |
| 689 | .BI "\-m, \-\-message " file |
| 690 | Write the message to |
| 691 | .IR file . |
| 692 | If |
| 693 | .I file |
| 694 | is |
| 695 | .RB ` \- ' |
| 696 | then write the message to standard output. Don't send the message and |
| 697 | signature to the same place because it doesn't work. |
| 698 | .TP |
| 699 | .BI "\-o, \-\-output " file |
| 700 | Write the signature to |
| 701 | .IR file . |
| 702 | If no |
| 703 | .B \-m |
| 704 | or |
| 705 | .B \-o |
| 706 | option is given, a signature is written to standard output. |
| 707 | .SS "encode" |
| 708 | The |
| 709 | .B encode |
| 710 | command encodes an input file according to one of the encodings |
| 711 | described above in |
| 712 | .BR ENCODINGS . |
| 713 | The input is read from the |
| 714 | .I file |
| 715 | given on the command line, or from standard input if none is specified. |
| 716 | Options provided are: |
| 717 | .TP |
| 718 | .BI "\-f, \-\-format " format |
| 719 | Produce output in |
| 720 | .IR format . |
| 721 | Run |
| 722 | .B catsign show enc |
| 723 | for a list of encoding formats. |
| 724 | .TP |
| 725 | .BI "\-b, \-\-boundary " label |
| 726 | Set the PEM boundary string to |
| 727 | .IR label ; |
| 728 | i.e., assuming we're encoding in PEM format, the output will have |
| 729 | .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-" |
| 730 | at the top and |
| 731 | .BI "\-\-\-\-\-END " label "\-\-\-\-\-" |
| 732 | at the bottom. The default |
| 733 | .I label |
| 734 | is |
| 735 | .BR MESSAGE . |
| 736 | .TP |
| 737 | .BI "\-p, \-\-progress" |
| 738 | Write a progress meter to standard error while processing large files. |
| 739 | .TP |
| 740 | .BI "\-o, \-\-output " file |
| 741 | Write output to |
| 742 | .I file |
| 743 | instead of to standard output. |
| 744 | .SS "decode" |
| 745 | The |
| 746 | .B decode |
| 747 | command decodes an input file encoded according to one of the encodings |
| 748 | described above in |
| 749 | .BR ENCODINGS . |
| 750 | The input is read from the |
| 751 | .I file |
| 752 | given on the command line, or from standard input if none is specified. |
| 753 | Options provided are: |
| 754 | .TP |
| 755 | .BI "\-f, \-\-format " format |
| 756 | Decode input in |
| 757 | .IR format . |
| 758 | Run |
| 759 | .B catsign show enc |
| 760 | for a list of encoding formats. |
| 761 | .TP |
| 762 | .BI "\-b, \-\-boundary " label |
| 763 | Set the PEM boundary string to |
| 764 | .IR label ; |
| 765 | i.e., assuming we're encoding in PEM format, start processing input |
| 766 | between |
| 767 | .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-" |
| 768 | and |
| 769 | .BI "\-\-\-\-\-END " label "\-\-\-\-\-" |
| 770 | lines. Without this option, |
| 771 | .B catsign |
| 772 | will start reading at the first plausible boundary string, and continue |
| 773 | processing until it reaches the matching end boundary. |
| 774 | .TP |
| 775 | .BI "\-p, \-\-progress" |
| 776 | Write a progress meter to standard error while processing large files. |
| 777 | .TP |
| 778 | .BI "\-o, \-\-output " file |
| 779 | Write output to |
| 780 | .I file |
| 781 | instead of to standard output. |
| 782 | .SH "BUGS" |
| 783 | The trailing-whitespace deletion doesn't work for more than 32K of |
| 784 | whitespace. I don't think this is a big problem, really. |
| 785 | .PP |
| 786 | The |
| 787 | .B format |
| 788 | command does something unhelpful if message and signature are sent to |
| 789 | the same file. |
| 790 | .SH "SEE ALSO" |
| 791 | .BR key (1), |
| 792 | .BR catcrypt (1), |
| 793 | .BR dsig (1), |
| 794 | .BR hashsum (1), |
| 795 | .BR keyring (5). |
| 796 | .SH AUTHOR |
| 797 | Mark Wooding, <mdw@distorted.org.uk> |