Commit | Line | Data |
---|---|---|
fa54fe1e | 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 | |
cd6eca43 | 47 | .RB [ \-adptC ] |
fa54fe1e | 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 | |
cd6eca43 | 57 | .RB [ \-apquvC ] |
fa54fe1e | 58 | .RB [ \-k |
59 | .IR tag ] | |
60 | .RB [ \-f | |
61 | .IR format ] | |
9cea6911 | 62 | .RB [ \-t |
63 | .IR time ] | |
fa54fe1e | 64 | .br |
e51127d5 | 65 | \h'8n' |
fa54fe1e | 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 | |
cd6eca43 | 78 | .RB [ \-apuABDET ] |
fa54fe1e | 79 | .RB [ \-f |
80 | .IR format ] | |
81 | .RB [ \-F | |
82 | .IR format ] | |
83 | .br | |
e51127d5 | 84 | \h'8n' |
fa54fe1e | 85 | .RB [ \-m |
86 | .IR file ] | |
87 | .RB [ \-o | |
88 | .IR output ] | |
89 | .RI [ file | |
90 | .RI [ message ]] | |
91 | .br | |
92 | .B encode | |
cd6eca43 | 93 | .RB [ \-p ] |
fa54fe1e | 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 | |
cd6eca43 | 103 | .RB [ \-p ] |
fa54fe1e | 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 | |
45c0fd36 | 153 | uses signing keys in the same way as |
fa54fe1e | 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 | |
45c0fd36 | 181 | wrapped in a DER-encoded |
fa54fe1e | 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 | |
45c0fd36 | 206 | This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the |
fa54fe1e | 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. | |
02dfbd5b | 248 | .TP |
d56fd9d1 MW |
249 | .B ed25519 |
250 | This is Bernstein, Duif, Lange, Schwabe, and Yang's Ed25519 algorithm. | |
251 | More specifically, this is HashEd25519 | |
252 | using the selected | |
253 | .B hash | |
254 | algorithm \(en by default | |
255 | .BR sha512 . | |
256 | Use the | |
257 | .B ed25519 | |
258 | algorithm of the | |
259 | .B key add | |
260 | command | |
261 | (see | |
262 | .BR key (1)) | |
263 | to generate the key. | |
264 | .TP | |
c578d5d8 MW |
265 | .B ed448 |
266 | This is Bernstein, Duif, Lange, Schwabe, and Yang's EdDSA algorithm, | |
267 | using Hamburg's Ed448-Goldilocks elliptic curve, | |
268 | as specified in RFC8032. | |
269 | More specifically, this is HashEd448 | |
270 | using the selected | |
271 | .B hash | |
272 | algorithm \(en by default | |
273 | .BR sha3-512 . | |
274 | Use the | |
275 | .B ed448 | |
276 | algorithm of the | |
277 | .B key add | |
278 | command | |
279 | (see | |
280 | .BR key (1)) | |
281 | to generate the key. | |
282 | .TP | |
02dfbd5b MW |
283 | .B mac |
284 | This uses a symmetric message-authentication algorithm rather than a | |
285 | digital signature. The precise message-authentication scheme used is | |
286 | determined by the | |
287 | .B mac | |
288 | attribute on the key, which defaults to | |
289 | .IB hash -hmac | |
290 | if unspecified. Use the | |
291 | .B binary | |
292 | algorithm of the | |
293 | .B key add | |
294 | command (see | |
295 | .BR key (1)) | |
296 | to generate the key. | |
fa54fe1e | 297 | .PP |
298 | As well as the signature algorithm itself, a hash function is used. | |
299 | This is taken from the | |
300 | .B hash | |
301 | attribute on the key, or, failing that, from the | |
302 | .I hash | |
303 | specified in the | |
304 | .IR sigalgspec , | |
305 | or, if that is absent, determined by the signature algorithm as follows. | |
306 | .hP \*o | |
307 | For | |
308 | .BR rsapkcs1 , | |
309 | .BR rsapss , | |
310 | .BR dsa , | |
311 | and | |
312 | .BR ecdsa , | |
313 | the default hash function is | |
314 | .BR sha . | |
315 | .hP \*o | |
316 | For | |
45c0fd36 | 317 | .BR kcdsa |
fa54fe1e | 318 | and |
319 | .BR eckcdsa , | |
320 | the default hash function is | |
321 | .BR has160 . | |
df8800f1 MW |
322 | For |
323 | .BR ed25519 , | |
324 | the default hash function is | |
325 | .BR sha512 . | |
c578d5d8 MW |
326 | For |
327 | .BR ed448 , | |
328 | the default hash function is | |
329 | .BR shake256 . | |
fa54fe1e | 330 | .PP |
331 | Run | |
332 | .B catsign show hash | |
333 | for a list of supported hash functions. | |
334 | .SH "ENCODINGS" | |
335 | Two encodings for the ciphertext are supported. | |
336 | .TP | |
337 | .B binary | |
338 | The raw format, which has the benefit of being smaller, but needs to be | |
339 | attached to mail messages and generally handled with care. | |
340 | .TP | |
341 | .B pem | |
342 | PEM-encapsulated Base-64 encoded text. This format can be included | |
343 | directly in email and picked out again automatically; but there is a | |
344 | 4-to-3 data expansion as a result. | |
345 | .SH "SIGNATURE FORMATS" | |
346 | There are two basic signature formats understood by | |
347 | .BR catsign . | |
348 | .hP \*o | |
349 | Embedded signatures include (embed) the message they sign; hence they're | |
350 | complete in and of themselves. The | |
351 | .B catsign | |
352 | program extracts the message during signature verification. | |
353 | .hP \*o | |
354 | Detached signatures are separate from the messages they sign, and both | |
355 | the original file and the signature are required for a successful | |
356 | verification. | |
357 | .PP | |
358 | Another important distinction is whether the message data is considered | |
359 | to be plain text or raw binary data. | |
360 | .hP \*o | |
361 | When dealing with plain text, | |
362 | .B catsign | |
363 | allows a limited quantity of leeway in the messages it processes. It | |
364 | ignores trailing whitespace on a line, including stray carriage-returns, | |
365 | which may appear if Windows boxes have had their way with the data. It | |
366 | also appends a final newline if there wasn't one before. In embedded | |
367 | signatures, the text is left unencoded, so that the message is readable. | |
368 | .hP \*o | |
369 | Binary files are preserved completely, and no variation whatever is | |
370 | permitted. | |
371 | .PP | |
372 | The | |
373 | .VS | |
374 | catsign format | |
375 | .VE | |
376 | command can convert between detached and embedded signatures; it cannot | |
377 | convert between binary and text mode signatures. (The data actually | |
378 | signed includes a flag saying whether the message is textual. The | |
379 | rationale here is that what looks like an ASCII space before a newline | |
380 | may be devastatingly significant in a binary data file, and if a message | |
381 | is signed as raw binary then no changes whatever should be allowed.) | |
382 | .SH "COMMAND REFERENCE" | |
383 | .SS help | |
384 | The | |
385 | .B help | |
386 | command behaves exactly as the | |
387 | .B \-\-help | |
388 | option. With no arguments, it shows an overview of | |
389 | .BR catsign 's | |
390 | options; with arguments, it describes the named subcommands. | |
391 | .SS show | |
392 | The | |
393 | .B show | |
394 | command prints various lists of tokens understood by | |
395 | .BR catsign . | |
396 | With no arguments, it prints all of the lists; with arguments, it prints | |
397 | just the named lists, in order. The recognized lists can be enumerated | |
398 | using the | |
399 | .VS | |
400 | catsign show list | |
401 | .VE | |
402 | command. The lists are as follows. | |
403 | .TP | |
404 | .B list | |
405 | The lists which can be enumerated by the | |
406 | .B show | |
407 | command. | |
408 | .TP | |
409 | .B sig | |
410 | The signature algorithms which can be used in a signing key's | |
411 | .B sig | |
412 | attribute. | |
413 | .TP | |
414 | .B hash | |
415 | The hash functions which can be used in a key's | |
416 | .B hash | |
417 | attribute. | |
418 | .TP | |
419 | .B enc | |
45c0fd36 | 420 | The encodings which can be applied to encrypted messages; see |
fa54fe1e | 421 | .B ENCODINGS |
422 | above. | |
423 | .SS sign | |
424 | The | |
425 | .B sign | |
426 | command signs a message and writes out an appropriately-encoded | |
427 | signature. By default, it reads a message from standard input and | |
428 | writes the signature to standard output. If a filename argument is | |
429 | given, this file is read instead. | |
430 | .PP | |
431 | The following options are recognized. | |
432 | .TP | |
433 | .B "\-a, \-\-armour" | |
434 | Produce ASCII-armoured output. This is equivalent to specifying | |
435 | .BR "\-f pem" . | |
436 | The variant spelling | |
437 | .B "\-\-armor" | |
438 | is also accepted. | |
439 | .TP | |
440 | .B "\-b, \-\-binary" | |
441 | Read and sign the input as binary data. The default is to treat the | |
442 | input as text. | |
443 | .TP | |
444 | .B "\-d, \-\-detach" | |
445 | Produce a detached signature. The default is to produce a signature | |
446 | with embedded message. | |
447 | .TP | |
448 | .BI "\-f, \-\-format " format | |
449 | Produce output encoded according to | |
450 | .IR format . | |
451 | .TP | |
452 | .BI "\-k, \-\-key " tag | |
453 | Use the signing key named | |
454 | .I tag | |
455 | in the current keyring; the default key is | |
456 | .BR ccsig . | |
457 | .TP | |
458 | .BI "\-o, \-\-ouptut " file | |
459 | Write output to | |
460 | .I file | |
461 | rather than to standard output. | |
462 | .TP | |
cd6eca43 MW |
463 | .BI "\-p, \-\-progress" |
464 | Write a progress meter to standard error while processing large files. | |
465 | .TP | |
fa54fe1e | 466 | .B "\-t, \-\-text" |
467 | Read and sign the input as text. This is the default. | |
946c3f72 | 468 | .TP |
469 | .B "\-C, \-\-nocheck" | |
470 | Don't check the private key for validity. This makes signing go much | |
471 | faster, but at the risk of using a duff key, and potentially leaking | |
472 | information about the private key. | |
fa54fe1e | 473 | .SS verify |
474 | The | |
475 | .B verify | |
476 | command checks a signature's validity, producing as output information | |
477 | about the signature and the signed message. | |
478 | .PP | |
479 | The first non-option argument is the name of the file containing the | |
45c0fd36 | 480 | signature data; this may be omitted or |
fa54fe1e | 481 | .RB ` \- ' |
482 | to indicate that the signature be read from standard input. The second | |
483 | non-option argument, if any, is the name of the file to read the message | |
484 | from, if the signature is detached. An error is reported if a message | |
485 | file is specified but the signature contains an embedded message | |
486 | already; if the signature is detached but no filename is given, then the | |
487 | message is expected on stdin (immediately after the signature, if any). | |
488 | .TP | |
489 | .B "\-a, \-\-armour" | |
490 | Read ASCII-armoured input. This is equivalent to specifying | |
491 | .BR "\-f pem" . | |
492 | The variant spelling | |
493 | .B "\-\-armor" | |
494 | is also accepted. | |
495 | .TP | |
496 | .B "\-b, \-\-buffer" | |
497 | Buffer the message until the signature is verified. This is forced on | |
498 | if output is to stdout, but is always available as an option. | |
499 | .TP | |
500 | .BI "\-f, \-\-format " format | |
501 | Read input encoded according to | |
502 | .IR format . | |
503 | .TP | |
504 | .B "\-v, \-\-verbose" | |
505 | Produce more verbose messages. See below for the messages produced | |
506 | during decryption. The default verbosity level is 1. (Currently this | |
507 | is the most verbose setting. This might not be the case always.) | |
21aac40c | 508 | .TP |
cd6eca43 MW |
509 | .BI "\-p, \-\-progress" |
510 | Write a progress meter to standard error while processing large files. | |
511 | .TP | |
fa54fe1e | 512 | .B "\-q, \-\-quiet" |
513 | Produce fewer messages. | |
514 | .TP | |
515 | .BI "\-k, \-\-key " tag | |
516 | Usually | |
517 | .B catsign | |
518 | uses the signature header to work out which key to use to verify a | |
519 | signature. Using this option causes verification to fail unless the | |
520 | signature header specifies the key named | |
521 | .IR tag . | |
522 | .TP | |
9cea6911 | 523 | .BI "\-t, \-\-freshtime " time |
524 | Only accept signatures claiming to have been made more recently than | |
525 | .IR time . | |
526 | If | |
527 | .I time | |
528 | is | |
529 | .B always | |
530 | (the default) then any timestamp in the past is acceptable. | |
531 | .TP | |
fa54fe1e | 532 | .B "\-u, \-\-utc" |
533 | Show the datestamp in the signature in UTC rather than (your) local | |
534 | time. The synonym | |
535 | .B \-\-gmt | |
536 | is also accepted. | |
537 | .TP | |
538 | .BI "\-o, \-\-output " file | |
539 | Write the verified message to | |
540 | .IR file . | |
541 | The file is written in text or binary | |
542 | mode as appropriate. The default is to write the message to standard | |
543 | output unless verifying a detached signature, in which case nothing is | |
544 | written. | |
946c3f72 | 545 | .TP |
546 | .B "\-C, \-\-nocheck" | |
547 | Don't check the public key for validity. This makes verification go | |
548 | much faster, but at the risk of using a duff key, and potentially | |
549 | accepting false signatures. | |
fa54fe1e | 550 | .PP |
551 | Output is written to standard output in a machine-readable format. | |
552 | Major problems cause the program to write a diagnostic to standard error | |
553 | and exit nonzero as usual. The quantity of output varies depending on | |
554 | the verbosity level and whether the message is also being written to | |
555 | standard output. Output lines begin with a keyword: | |
556 | .TP | |
557 | .BI "FAIL " reason | |
558 | An error prevented verification. The program will exit nonzero. | |
559 | .TP | |
560 | .BI "WARN " reason | |
561 | .B catsign | |
562 | encountered a situation which may or may not invalidate the | |
563 | verification. | |
564 | .TP | |
565 | .BI "OK " message | |
566 | Verification was successful. This is only produced if the message is | |
567 | being sent somewhere other than standard output. | |
568 | .TP | |
569 | .B "DATA" | |
570 | The message follows, starting just after the next newline character or | |
571 | sequence. This is only produced if the message is being written to | |
572 | standard output. | |
573 | .TP | |
574 | .BI "INFO " note | |
575 | Any other information. | |
576 | .PP | |
577 | The information written at the various verbosity levels is as follows. | |
578 | .hP 0. | |
579 | No output. Watch the exit status. | |
580 | .hP 1. | |
581 | All messages. | |
582 | .PP | |
583 | .B Warning! | |
7cb116b7 MW |
584 | Unless the |
585 | .B \-b | |
586 | option is set (which happens automatically if writing to standard | |
587 | output), | |
588 | .BR catsign 's | |
589 | output is | |
590 | .I not | |
591 | checked for authenticity until it has all been written. Even with | |
592 | .BR \-b , | |
593 | output can fail midway for many reasons, and the resulting message may | |
45c0fd36 | 594 | therefore be truncated. Don't rely on the output being complete until |
4224d0b9 | 595 | .B OK |
596 | is printed or | |
fa54fe1e | 597 | .B catsign verify |
598 | exits successfully. | |
599 | .SS info | |
600 | The | |
601 | .B info | |
602 | command analyses a signature without verifying it, and prints | |
603 | interesting information about it. This might be useful for diagnostic | |
604 | purposes. No keys are needed for this operation, though you get more | |
605 | useful information if you have them. | |
606 | .PP | |
607 | If a non-option argument is given, and it is not | |
608 | .RB ` \- ', | |
609 | then it is taken to name the file containing the signature to parse; | |
610 | otherwise a signature is read from standard input. | |
611 | .PP | |
612 | The following options are recognized. | |
613 | .TP | |
614 | .B "\-a, \-\-armour" | |
615 | Read ASCII-armoured input. This is equivalent to specifying | |
616 | .BR "\-f pem" . | |
617 | The variant spelling | |
618 | .B "\-\-armor" | |
619 | is also accepted. | |
620 | .TP | |
621 | .BI "\-f, \-\-format " format | |
622 | Read input encoded according to | |
623 | .IR format . | |
624 | .TP | |
cd6eca43 MW |
625 | .BI "\-p, \-\-progress" |
626 | Write a progress meter to standard error while processing large files. | |
627 | .TP | |
fa54fe1e | 628 | .B "\-u, \-\-utc" |
629 | Show the datestamp in the signature in UTC rather than (your) local | |
630 | time. The synonym | |
631 | .B \-\-gmt | |
632 | is also accepted. | |
633 | .PP | |
634 | A description of the signature block is produced on standard output; it | |
635 | is mostly machine-readable. The first word on each line explains what | |
636 | kind of output it is. | |
637 | .TP | |
638 | .BI "BAD " message | |
639 | The signature data is invalid and cannot be parsed. | |
640 | .TP | |
641 | .BI "WARN " message | |
642 | Something is wrong with the data, but isn't fatal. | |
643 | .TP | |
644 | .BI "NOTE " message | |
645 | An environmental problem means that the information isn't as helpful as | |
646 | it might be. For example, the keyring file can't be opened, so we don't | |
647 | know whether the verification key is there. | |
648 | .TP | |
649 | .BI "INFO flags " flags | |
650 | Describes the flags set in the signature header. The | |
651 | .I flags | |
652 | are a list of flags, one per word, preceded by a | |
653 | .RB ` ! ' | |
654 | if the flag is clear. | |
655 | .TP | |
656 | .BI "INFO expected-flags " flags | |
657 | If the PEM boundary string didn't match the actual signature data then | |
658 | this line is output, listing the expected flags and their settings. | |
659 | Problems with boundary mismatches can be resolved using the | |
660 | .B format | |
661 | command. | |
662 | .TP | |
663 | .BI "INFO date " yyyy "\-" mm "\-" dd " " hh ":" mm ":" ss " " tz | |
664 | Signature was (allegedly!) made at the given time and date. If the | |
665 | .B \-u | |
666 | option was given, this will be in UTC. | |
667 | .TP | |
668 | .BI "INFO key " tag | |
669 | Signature was (allegedly!) made using the key | |
670 | .IR tag , | |
671 | which is present in the current keyring. | |
672 | .TP | |
673 | .BI "INFO unknown-key " keyid | |
674 | Signature was (allegedly!) made using the key with id | |
675 | .IR keyid | |
676 | which is not in the current keyring (or the keyring wasn't found). | |
677 | .SS format | |
678 | The | |
679 | .B format | |
680 | command translates signatures between the various supported formats. | |
681 | This is a (slightly) more complex operation than re-encoding, though it | |
682 | does not require any cryptographic operations. | |
683 | .PP | |
684 | The first non-option argument is the name of the file containing the | |
45c0fd36 | 685 | signature data; this may be omitted or |
fa54fe1e | 686 | .RB ` \- ' |
687 | to indicate that the signature be read from standard input. The second | |
688 | non-option argument, if any, is the name of the file to read the message | |
689 | from, if the signature is detached. An error is reported if a message | |
690 | file is specified but the signature contains an embedded message | |
691 | already; if the signature is detached but no filename is given, then the | |
692 | message is expected on stdin (immediately after the signature, if any). | |
693 | .PP | |
694 | The options follow a rough convention: options describing the input | |
695 | format are lower-case and options specifying the output format are | |
696 | upper-case. The following options are recognized. | |
0ac1f186 | 697 | .TP |
698 | .BI "\-a, \-\-armour-in" | |
fa54fe1e | 699 | Read ASCII-armoured input. This is equivalent to specifying |
700 | .BR "\-f pem" . | |
701 | The variant spelling | |
702 | .B "\-\-armor" | |
703 | is also accepted. | |
0ac1f186 | 704 | .TP |
cd6eca43 MW |
705 | .BI "\-p, \-\-progress" |
706 | Write a progress meter to standard error while processing large files. | |
707 | .TP | |
0ac1f186 | 708 | .BI "\-A, \-\-armour-out" |
fa54fe1e | 709 | Produce ASCII-armoured output. This is equivalent to specifying |
710 | .BR "\-F pem" . | |
711 | The variant spelling | |
712 | .B "\-\-armor-out" | |
713 | is also accepted. | |
714 | .TP | |
715 | .B "\-D, \-\-detach" | |
716 | Produce a detached signature. This may be used to detach a signature | |
717 | from an embedded message. | |
718 | .TP | |
719 | .B "\-E, \-\-embed" | |
720 | Produce a signature with embedded message. This may be used to | |
721 | reattach a message to its detached signature. | |
722 | .TP | |
723 | .BI "\-f, \-\-format-in " format | |
724 | Read input encoded according to | |
725 | .IR format . | |
726 | .TP | |
727 | .BI "\-F, \-\-format-out " format | |
728 | Produce output encoded according to | |
729 | .IR format . | |
730 | .TP | |
731 | .BI "\-m, \-\-message " file | |
732 | Write the message to | |
733 | .IR file . | |
734 | If | |
735 | .I file | |
736 | is | |
737 | .RB ` \- ' | |
738 | then write the message to standard output. Don't send the message and | |
739 | signature to the same place because it doesn't work. | |
740 | .TP | |
741 | .BI "\-o, \-\-output " file | |
742 | Write the signature to | |
743 | .IR file . | |
744 | If no | |
745 | .B \-m | |
746 | or | |
747 | .B \-o | |
748 | option is given, a signature is written to standard output. | |
e1cba07d | 749 | .SS "encode" |
750 | The | |
751 | .B encode | |
752 | command encodes an input file according to one of the encodings | |
753 | described above in | |
754 | .BR ENCODINGS . | |
45c0fd36 | 755 | The input is read from the |
e1cba07d | 756 | .I file |
757 | given on the command line, or from standard input if none is specified. | |
758 | Options provided are: | |
759 | .TP | |
760 | .BI "\-f, \-\-format " format | |
761 | Produce output in | |
762 | .IR format . | |
763 | Run | |
65802cb1 | 764 | .B catsign show enc |
e1cba07d | 765 | for a list of encoding formats. |
766 | .TP | |
767 | .BI "\-b, \-\-boundary " label | |
768 | Set the PEM boundary string to | |
769 | .IR label ; | |
770 | i.e., assuming we're encoding in PEM format, the output will have | |
771 | .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-" | |
772 | at the top and | |
773 | .BI "\-\-\-\-\-END " label "\-\-\-\-\-" | |
774 | at the bottom. The default | |
775 | .I label | |
776 | is | |
777 | .BR MESSAGE . | |
778 | .TP | |
cd6eca43 MW |
779 | .BI "\-p, \-\-progress" |
780 | Write a progress meter to standard error while processing large files. | |
781 | .TP | |
e1cba07d | 782 | .BI "\-o, \-\-output " file |
783 | Write output to | |
784 | .I file | |
785 | instead of to standard output. | |
786 | .SS "decode" | |
787 | The | |
788 | .B decode | |
789 | command decodes an input file encoded according to one of the encodings | |
790 | described above in | |
791 | .BR ENCODINGS . | |
45c0fd36 | 792 | The input is read from the |
e1cba07d | 793 | .I file |
794 | given on the command line, or from standard input if none is specified. | |
795 | Options provided are: | |
796 | .TP | |
797 | .BI "\-f, \-\-format " format | |
798 | Decode input in | |
799 | .IR format . | |
800 | Run | |
65802cb1 | 801 | .B catsign show enc |
e1cba07d | 802 | for a list of encoding formats. |
803 | .TP | |
804 | .BI "\-b, \-\-boundary " label | |
805 | Set the PEM boundary string to | |
806 | .IR label ; | |
807 | i.e., assuming we're encoding in PEM format, start processing input | |
808 | between | |
809 | .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-" | |
45c0fd36 | 810 | and |
e1cba07d | 811 | .BI "\-\-\-\-\-END " label "\-\-\-\-\-" |
812 | lines. Without this option, | |
65802cb1 | 813 | .B catsign |
e1cba07d | 814 | will start reading at the first plausible boundary string, and continue |
815 | processing until it reaches the matching end boundary. | |
816 | .TP | |
cd6eca43 MW |
817 | .BI "\-p, \-\-progress" |
818 | Write a progress meter to standard error while processing large files. | |
819 | .TP | |
e1cba07d | 820 | .BI "\-o, \-\-output " file |
821 | Write output to | |
822 | .I file | |
823 | instead of to standard output. | |
fa54fe1e | 824 | .SH "BUGS" |
825 | The trailing-whitespace deletion doesn't work for more than 32K of | |
826 | whitespace. I don't think this is a big problem, really. | |
827 | .PP | |
828 | The | |
829 | .B format | |
830 | command does something unhelpful if message and signature are sent to | |
831 | the same file. | |
832 | .SH "SEE ALSO" | |
833 | .BR key (1), | |
834 | .BR catcrypt (1), | |
835 | .BR dsig (1), | |
836 | .BR hashsum (1), | |
837 | .BR keyring (5). | |
838 | .SH AUTHOR | |
f387fcb1 | 839 | Mark Wooding, <mdw@distorted.org.uk> |