Commit | Line | Data |
---|---|---|
c65df279 | 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 | |
cd6eca43 | 47 | .RB [ \-apC ] |
c65df279 | 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 | |
cd6eca43 | 57 | .RB [ \-apqvC ] |
c65df279 | 58 | .RB [ \-f |
59 | .IR format ] | |
60 | .RB [ \-o | |
61 | .IR output ] | |
62 | .RI [ file ] | |
63 | .br | |
64 | .B encode | |
cd6eca43 | 65 | .RB [ \-p ] |
c65df279 | 66 | .RB [ \-f |
67 | .IR format ] | |
68 | .RB [ \-b | |
69 | .IR boundary ] | |
70 | .RB [ \-o | |
71 | .IR output ] | |
72 | .RI [ file ] | |
73 | .br | |
fa54fe1e | 74 | .B decode |
cd6eca43 | 75 | .RB [ \-p ] |
c65df279 | 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 | |
fa54fe1e | 123 | command deals with both signing and key-encapsulation keys. (Note that |
124 | .B catcrypt | |
45c0fd36 | 125 | uses signing keys in the same way as |
fa54fe1e | 126 | .BR catsign (1).) |
c65df279 | 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 | |
66ff643c MW |
137 | .IR bulk \c |
138 | .RB [ \- \c | |
139 | .IR cipher ] \c | |
140 | .RB [ / \c | |
141 | .IR hash ]] | |
142 | or | |
143 | .IR kem \c | |
144 | .RB [ / \c | |
c65df279 | 145 | .IR cipher \c |
146 | .RB [ / \c | |
147 | .IR hash ]]. | |
148 | If a | |
149 | .B kem | |
150 | attribute is present on the key, then it must have this form; otherwise, | |
151 | the key's type must have the form | |
152 | .BR cckem- \c | |
153 | .IR kemalgspec . | |
154 | Algorithm selections are taken from appropriately-named attributes, or, | |
155 | failing that, from the | |
156 | .IR kemalgspec . | |
157 | .PP | |
158 | The key-encapsulation mechanism is chosen according to the setting of | |
159 | .I kem | |
160 | as follows. Run | |
161 | .B catcrypt show kem | |
162 | for a list of supported KEMs. | |
163 | .TP | |
164 | .B rsa | |
165 | This is Shoup's RSA-KEM (formerly Simple RSA); see | |
166 | .I | |
167 | A proposal for an ISO standard for public key encryption (version 2.0) | |
168 | available at | |
169 | .BR http://eprint.iacr.org/2000/060/ . | |
170 | Use the | |
171 | .B rsa | |
172 | algorithm of the | |
173 | .B key add | |
174 | command (see | |
175 | .BR key (1)) | |
176 | to generate the key. | |
177 | .TP | |
178 | .B dh | |
179 | This is standard Diffie-Hellman key exchange, hashing the resulting | |
180 | shared secret to form the key, as used in, e.g., DLIES (P1363a). | |
181 | Use the | |
182 | .B dh | |
183 | algorithm of the | |
184 | .B key add | |
185 | command, preferably with the | |
186 | .B \-LS | |
187 | options, to generate the key. | |
188 | .TP | |
189 | .B ec | |
190 | This is the elliptic-curve analogue of | |
b98200ad | 191 | .BR dh . |
192 | Use the | |
c65df279 | 193 | .B ec |
194 | algorithm of the | |
195 | .BR key (1)) | |
196 | command to generate the key. | |
02dfbd5b MW |
197 | .TP |
198 | .B symm | |
199 | This is a simple symmetric encapsulation scheme. It works by hashing a | |
200 | binary key with a randomly-generated salt. Use the | |
201 | .B binary | |
202 | algorithm of the | |
203 | .B key add | |
204 | command (see | |
205 | .BR key (1)) | |
206 | to generate the key. | |
fc2d44af MW |
207 | .TP |
208 | .B x25519 | |
209 | This is Bernstein's Curve25519, a fast Diffie-Hellman using a specific | |
210 | elliptic curve. | |
211 | Use the | |
212 | .B x25519 | |
213 | algorithm of the | |
214 | .B key add | |
215 | command | |
216 | (see | |
217 | .BR key (1)) | |
218 | to generate the key. | |
643eb1bb MW |
219 | .TP |
220 | .B x448 | |
221 | This is Hamburg's Curve25519, a strong Diffie-Hellman using a specific | |
222 | elliptic curve. | |
223 | Use the | |
224 | .B x448 | |
225 | algorithm of the | |
226 | .B key add | |
227 | command | |
228 | (see | |
229 | .BR key (1)) | |
230 | to generate the key. | |
c65df279 | 231 | .PP |
66ff643c MW |
232 | The bulk crypto transform is chosen based on the |
233 | .B bulk | |
234 | attribute on the key, or, failing that, | |
235 | from the | |
236 | .I bulk | |
237 | stated in the | |
238 | .IR kemalgspec . | |
239 | Run | |
240 | .B catcrypt show bulk | |
241 | for a list of supported bulk crypto transforms. | |
242 | .TP | |
243 | .B gencomp | |
244 | A generic composition of | |
245 | a cipher secure against chosen-plaintext attack, | |
246 | and a message authentication code. | |
247 | Makes use of | |
248 | .B cipher | |
249 | and | |
250 | .B mac | |
b2973dcf MW |
251 | attributes. Run |
252 | .B catcrypt show cipher | |
253 | for a list of supported symmetric encryption algorithms; the default | |
254 | .I cipher | |
255 | is | |
256 | .BR blowfish-cbc . | |
66ff643c | 257 | This is the default transform. |
d9d419b0 | 258 | .TP |
11ee758a MW |
259 | .B aead |
260 | Use an `authenticated encryption with additional data' (AEAD) scheme. | |
261 | The specific scheme is named by the | |
262 | .B cipher | |
263 | attribute. Run | |
264 | .B catcrypt show aead | |
265 | for a list of supported AEAD schemes; the default is | |
266 | .BR chacha20-poly1305 . | |
267 | .TP | |
d9d419b0 MW |
268 | .B naclbox |
269 | Use Salsa20 or ChaCha and Poly1305 to secure the bulk data. | |
270 | This is nearly the same as the NaCl | |
271 | .B crypto_secretbox | |
272 | construction, | |
273 | except that | |
274 | .B catcrypt | |
275 | uses Salsa20 or ChaCha rather than XSalsa20, | |
276 | because it doesn't need the latter's extended nonce. | |
277 | The | |
278 | .B cipher | |
279 | attribute may be set to one of | |
280 | .BR salsa20 , | |
281 | .BR salsa20/12 , | |
282 | .BR salsa20/8 , | |
283 | .BR chacha20 , | |
284 | .BR chacha12 , | |
285 | or | |
286 | .BR chacha8 ; | |
287 | the default is | |
288 | .BR salsa20 . | |
4a39374f MW |
289 | Nowadays, this is equivalent to the |
290 | .B aead | |
291 | transform, using | |
292 | .IB cipher -naclbox | |
293 | as the cipher. | |
66ff643c | 294 | .PP |
c65df279 | 295 | As well as the KEM itself, a number of supporting algorithms are used. |
296 | These are taken from appropriately named attributes on the key or, | |
297 | failing that, derived from other attributes as described below. | |
298 | .TP | |
299 | .B cipher | |
66ff643c MW |
300 | This is the symmetric encryption algorithm |
301 | used by the bulk data transform. | |
302 | If there is no | |
c65df279 | 303 | .B cipher |
304 | attribute then the | |
66ff643c | 305 | .I bulk |
c65df279 | 306 | in the |
307 | .I kemalgspec | |
b2973dcf MW |
308 | is used; if that it absent, then the default depends on the bulk |
309 | transform. | |
c65df279 | 310 | .TP |
311 | .B hash | |
312 | This is the hash function used to distil entropy from the shared secret | |
313 | constructed by the raw KEM. If there is no | |
314 | .B hash | |
315 | attribute then the | |
316 | .I hash | |
317 | in the | |
b98200ad | 318 | .I kemalgspec |
319 | is used; if that is absent then the default of | |
c65df279 | 320 | .B rmd160 |
321 | is used. Run | |
322 | .B catcrypt show hash | |
323 | for a list of supported symmetric encryption algorithms. | |
324 | .TP | |
325 | .B mac | |
66ff643c MW |
326 | This is the message authentication algorithm |
327 | used by the | |
328 | .B gencomp | |
329 | bulk data transform | |
330 | to ensure integrity of the encrypted message and | |
331 | defend against chosen-ciphertext attacks. | |
332 | If there is no | |
c65df279 | 333 | .B mac |
334 | attribute then | |
335 | .IB hash -hmac | |
336 | is chosen as a default. Run | |
337 | .B catcrypt show mac | |
338 | for a list of supported message authentication algorithms. | |
339 | .TP | |
340 | .B kdf | |
341 | This is the key derivation function used to stretch the hashed shared | |
342 | secret to a sufficient length to select symmetric encryption and | |
343 | authentication keys, initialization vectors and other necessary | |
344 | pseudorandom quantities. If there is no | |
345 | .B kdf | |
346 | attribute then | |
347 | .IB hash -mgf | |
348 | is chosen as a default. Run | |
349 | .B catcrypt show kdf | |
350 | for a list of supported key derivation functions. | |
351 | .B Caution! | |
352 | Not all supported functions have the required security features: don't | |
353 | override the default choice unless you know what you're doing. | |
354 | .SS "Signing keys" | |
355 | A | |
356 | .I sigalgspec | |
357 | has the form | |
358 | .IR sig \c | |
359 | .RB [ / \c | |
360 | .IR hash ]. | |
361 | If a | |
362 | .B sig | |
363 | attribute is present on the key, then it must have this form; otherwise, | |
364 | the key's type must have the form | |
365 | .BI ccsig- \c | |
366 | .IR sigalgspec . | |
367 | Algorithm selections are taken from appropriately-named attributes, or, | |
368 | failing that, from the | |
369 | .IR sigalgspec . | |
370 | .PP | |
371 | The signature algorithm is chosen according to the setting of | |
372 | .I sig | |
373 | as follows. Run | |
374 | .B catcrypt show sig | |
375 | for a list of supported signature algorithms. | |
376 | .TP | |
377 | .B rsapkcs1 | |
378 | This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in | |
379 | RFC3447; the difference is that the hash is left bare rather than being | |
45c0fd36 | 380 | wrapped in a DER-encoded |
c65df279 | 381 | .B DigestInfo |
382 | structure. This doesn't affect security since the key can only be used | |
383 | with the one hash function anyway, and dropping the DER wrapping permits | |
384 | rapid adoption of new hash functions. Regardless, use of this algorithm | |
385 | is not recommended, since the padding method has been shown vulnerable | |
386 | to attack. Use the | |
387 | .B rsa | |
388 | algorithm of the | |
389 | .B key add | |
390 | command (see | |
391 | .BR key (1)) | |
392 | to generate the key. | |
393 | .TP | |
394 | .B rsapss | |
395 | This is the RSASSA-PSS algorithm described in RFC3447. It is the | |
396 | preferred RSA-based signature scheme. Use the | |
397 | .B rsa | |
398 | algorithm of the | |
399 | .B key add | |
400 | command (see | |
401 | .BR key (1)) | |
402 | to generate the key. | |
403 | .TP | |
404 | .B dsa | |
45c0fd36 | 405 | This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the |
c65df279 | 406 | .B dsa |
407 | algorithm of the | |
408 | .B key add | |
409 | command (see | |
410 | .BR key (1)) | |
411 | to generate the key. | |
412 | .TP | |
413 | .B ecdsa | |
414 | This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use | |
415 | the | |
416 | .B ec | |
417 | algorithm of the | |
418 | .B key add | |
419 | command (see | |
420 | .BR key (1)) | |
421 | to generate the key. | |
422 | .TP | |
423 | .B kcdsa | |
424 | This is the revised KCDSA (Korean Certificate-based Digital Signature | |
425 | Algorithm) described in | |
426 | .I The Revised Version of KCDSA | |
427 | .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ). | |
428 | Use the | |
429 | .B dh | |
430 | algorithm of the | |
431 | .B key add | |
432 | command with the | |
433 | .B \-LS | |
434 | options (see | |
435 | .BR key (1)) | |
436 | to generate the key. | |
437 | .TP | |
438 | .B eckcdsa | |
439 | This is an unofficial elliptic-curve analogue of the KCDSA algorithm. | |
440 | Use the | |
441 | .B ec | |
442 | algorithm of the | |
443 | .B key add | |
444 | command (see | |
445 | .BR key (1)) | |
446 | to generate the key. | |
02dfbd5b | 447 | .TP |
d56fd9d1 MW |
448 | .B ed25519 |
449 | This is Bernstein, Duif, Lange, Schwabe, and Yang's Ed25519 algorithm. | |
450 | More specifically, this is HashEd25519 | |
451 | using the selected | |
452 | .B hash | |
453 | algorithm \(en by default | |
454 | .BR sha512 . | |
455 | Use the | |
456 | .B ed25519 | |
457 | algorithm of the | |
458 | .B key add | |
459 | command | |
460 | (see | |
461 | .BR key (1)) | |
462 | to generate the key. | |
463 | .TP | |
c578d5d8 MW |
464 | .B ed448 |
465 | This is Bernstein, Duif, Lange, Schwabe, and Yang's EdDSA algorithm, | |
466 | using Hamburg's Ed448-Goldilocks elliptic curve, | |
467 | as specified in RFC8032. | |
468 | More specifically, this is HashEd448 | |
469 | using the selected | |
470 | .B hash | |
471 | algorithm \(en by default | |
472 | .BR sha3-512 . | |
473 | Use the | |
474 | .B ed448 | |
475 | algorithm of the | |
476 | .B key add | |
477 | command | |
478 | (see | |
479 | .BR key (1)) | |
480 | to generate the key. | |
481 | .TP | |
02dfbd5b MW |
482 | .B mac |
483 | This uses a symmetric message-authentication algorithm rather than a | |
484 | digital signature. The precise message-authentication scheme used is | |
485 | determined by the | |
486 | .B mac | |
487 | attribute on the key, which defaults to | |
488 | .IB hash -hmac | |
489 | if unspecified. Use the | |
490 | .B binary | |
491 | algorithm of the | |
492 | .B key add | |
493 | command (see | |
494 | .BR key (1)) | |
495 | to generate the key. | |
c65df279 | 496 | .PP |
497 | As well as the signature algorithm itself, a hash function is used. | |
498 | This is taken from the | |
499 | .B hash | |
500 | attribute on the key, or, failing that, from the | |
501 | .I hash | |
502 | specified in the | |
503 | .IR sigalgspec , | |
504 | or, if that is absent, determined by the signature algorithm as follows. | |
505 | .hP \*o | |
506 | For | |
507 | .BR rsapkcs1 , | |
508 | .BR rsapss , | |
509 | .BR dsa , | |
510 | and | |
511 | .BR ecdsa , | |
512 | the default hash function is | |
513 | .BR sha . | |
514 | .hP \*o | |
515 | For | |
45c0fd36 | 516 | .BR kcdsa |
c65df279 | 517 | and |
518 | .BR eckcdsa , | |
519 | the default hash function is | |
520 | .BR has160 . | |
df8800f1 MW |
521 | For |
522 | .BR ed25519 , | |
523 | the default hash function is | |
524 | .BR sha512 . | |
c578d5d8 MW |
525 | For |
526 | .BR ed448 , | |
527 | the default hash function is | |
528 | .BR shake256 . | |
c65df279 | 529 | .PP |
530 | Run | |
531 | .B catcrypt show hash | |
532 | for a list of supported hash functions. | |
533 | .SH "ENCODINGS" | |
534 | Two encodings for the ciphertext are supported. | |
535 | .TP | |
536 | .B binary | |
537 | The raw format, which has the benefit of being smaller, but needs to be | |
538 | attached to mail messages and generally handled with care. | |
539 | .TP | |
540 | .B pem | |
541 | PEM-encapsulated Base-64 encoded text. This format can be included | |
542 | directly in email and picked out again automatically; but there is a | |
543 | 4-to-3 data expansion as a result. | |
544 | .SH "COMMAND REFERENCE" | |
545 | .SS help | |
546 | The | |
547 | .B help | |
548 | command behaves exactly as the | |
549 | .B \-\-help | |
550 | option. With no arguments, it shows an overview of | |
551 | .BR catcrypt 's | |
552 | options; with arguments, it describes the named subcommands. | |
553 | .SS show | |
554 | The | |
555 | .B show | |
556 | command prints various lists of tokens understood by | |
557 | .BR catcrypt . | |
558 | With no arguments, it prints all of the lists; with arguments, it prints | |
559 | just the named lists, in order. The recognized lists can be enumerated | |
560 | using the | |
561 | .VS | |
562 | catcrypt show list | |
563 | .VE | |
564 | command. The lists are as follows. | |
565 | .TP | |
566 | .B list | |
567 | The lists which can be enumerated by the | |
568 | .B show | |
569 | command. | |
570 | .TP | |
571 | .B kem | |
572 | The key-encapsulation algorithms which can be used in a | |
573 | key-encapsulation key's | |
574 | .B kem | |
575 | attribute. | |
576 | .TP | |
577 | .B cipher | |
f54be224 | 578 | The symmetric encryption algorithms which can be named in a |
c65df279 | 579 | key-encapsulation key's |
580 | .B cipher | |
b2973dcf MW |
581 | attribute when using the |
582 | .B gencomp | |
583 | bulk transform. | |
c65df279 | 584 | .TP |
585 | .B mac | |
f54be224 | 586 | The message authentication algorithms which can be named in a |
c65df279 | 587 | key-encapsulation key's |
588 | .B mac | |
589 | attribute. | |
590 | .TP | |
591 | .B sig | |
f54be224 | 592 | The signature algorithms which can be named in a signing key's |
c65df279 | 593 | .B sig |
594 | attribute. | |
595 | .TP | |
596 | .B hash | |
f54be224 | 597 | The hash functions which can be named in a key's |
c65df279 | 598 | .B hash |
599 | attribute. | |
600 | .TP | |
601 | .B enc | |
45c0fd36 | 602 | The encodings which can be applied to encrypted messages; see |
c65df279 | 603 | .B ENCODINGS |
604 | above. | |
605 | .SS encrypt | |
606 | The | |
607 | .B encrypt | |
608 | command encrypts a file and writes out the appropriately-encoded | |
609 | ciphertext. By default, it reads from standard input and writes to | |
610 | standard output. If a filename argument is given, this file is read | |
611 | instead (as binary data). | |
612 | .PP | |
613 | The following options are recognized. | |
614 | .TP | |
615 | .B "\-a, \-\-armour" | |
616 | Produce ASCII-armoured output. This is equivalent to specifying | |
617 | .BR "\-f pem" . | |
618 | The variant spelling | |
619 | .B "\-\-armor" | |
620 | is also accepted. | |
621 | .TP | |
622 | .BI "\-f, \-\-format " format | |
623 | Produce output encoded according to | |
624 | .IR format . | |
625 | .TP | |
626 | .BI "\-k, \-\-key " tag | |
627 | Use the key-encapsulation key named | |
628 | .I tag | |
629 | in the current keyring; the default key is | |
630 | .BR ccrypt . | |
631 | .TP | |
cd6eca43 MW |
632 | .BI "\-p, \-\-progress" |
633 | Write a progress meter to standard error while processing large files. | |
634 | .TP | |
c65df279 | 635 | .BI "\-s, \-\-sign-key " tag |
636 | Use the signature key named | |
637 | .I tag | |
638 | in the current keyring; the default is not to sign the ciphertext. | |
639 | .TP | |
640 | .BI "\-o, \-\-ouptut " file | |
641 | Write output to | |
642 | .I file | |
643 | rather than to standard output. | |
946c3f72 | 644 | .TP |
645 | .B "\-C, \-\-nocheck" | |
646 | Don't check the public key for validity. This makes encryption go much | |
647 | faster, but at the risk of using a duff key. | |
c65df279 | 648 | .SS decrypt |
649 | The | |
650 | .B decrypt | |
651 | command decrypts a ciphertext and writes out the plaintext. By default, | |
652 | it reads from standard input and writes to standard output. If a | |
653 | filename argument is given, this file is read instead. | |
654 | .PP | |
655 | The following options are recognized. | |
656 | .TP | |
657 | .B "\-a, \-\-armour" | |
fa54fe1e | 658 | Read ASCII-armoured input. This is equivalent to specifying |
c65df279 | 659 | .BR "\-f pem" . |
660 | The variant spelling | |
661 | .B "\-\-armor" | |
662 | is also accepted. | |
663 | .TP | |
fa54fe1e | 664 | .B "\-b, \-\-buffer" |
665 | Buffer plaintext data until we're sure we've got it all. This is forced | |
666 | on if output is to stdout, but is always available as an option. | |
667 | .TP | |
c65df279 | 668 | .BI "\-f, \-\-format " format |
669 | Read input encoded according to | |
670 | .IR format . | |
671 | .TP | |
cd6eca43 MW |
672 | .BI "\-p, \-\-progress" |
673 | Write a progress meter to standard error while processing large files. | |
674 | .TP | |
c65df279 | 675 | .B "\-v, \-\-verbose" |
676 | Produce more verbose messages. See below for the messages produced | |
677 | during decryption. The default verbosity level is 1. (Currently this | |
678 | is the most verbose setting. This might not be the case always.) | |
679 | .TP | |
680 | .B "\-q, \-\-quiet" | |
681 | Produce fewer messages. | |
682 | .TP | |
683 | .BI "\-o, \-\-output " file | |
684 | Write output to | |
685 | .I file | |
686 | instead of to standard output. The file is written in binary mode. | |
687 | Fixing line-end conventions is your problem; there are lots of good | |
688 | tools for dealing with it. | |
946c3f72 | 689 | .TP |
690 | .B "\-C, \-\-nocheck" | |
691 | Don't check the private key for validity. This makes decryption go much | |
692 | faster, but at the risk of using a duff key, and possibly leaking | |
693 | information about the private key. | |
c65df279 | 694 | .PP |
695 | Output is written to standard output in a machine-readable format. | |
696 | Major problems cause the program to write a diagnostic to standard error | |
697 | and exit nonzero as usual. The quantity of output varies depending on | |
698 | the verbosity level and whether the plaintext is also being written to | |
fa54fe1e | 699 | standard output. Output lines begin with a keyword: |
c65df279 | 700 | .TP |
701 | .BI "FAIL " reason | |
702 | An error prevented decryption. The program will exit nonzero. | |
703 | .TP | |
704 | .BI "WARN " reason | |
705 | .B catcrypt | |
706 | encountered a situation which may or may not invalidate the decryption. | |
45c0fd36 | 707 | .TP |
c65df279 | 708 | .BI "OK " message |
709 | Decryption was successful. This is only produced if main output is | |
710 | being sent somewhere other than standard output. | |
711 | .TP | |
712 | .B "DATA" | |
713 | The plaintext follows, starting just after the next newline character or | |
b98200ad | 714 | sequence. This is only produced if main output is also being sent to |
fa54fe1e | 715 | standard output. |
c65df279 | 716 | .TP |
717 | .BI "INFO " note | |
718 | Any other information. | |
719 | .PP | |
720 | The information written at the various verbosity levels is as follows. | |
721 | .hP 0. | |
722 | No output. Watch the exit status. | |
723 | .hP 1. | |
724 | All messages. | |
725 | .PP | |
726 | .B Warning! | |
fa54fe1e | 727 | All output written has been checked for authenticity. However, output |
77e4471a | 728 | can fail midway through for many reasons, and the resulting message may |
45c0fd36 | 729 | therefore be truncated. Don't rely on the output being complete until |
4224d0b9 | 730 | .B OK |
731 | is printed or | |
c65df279 | 732 | .B catcrypt decrypt |
fa54fe1e | 733 | exits successfully. |
c65df279 | 734 | .SS "encode" |
735 | The | |
736 | .B encode | |
737 | command encodes an input file according to one of the encodings | |
738 | described above in | |
739 | .BR ENCODINGS . | |
45c0fd36 | 740 | The input is read from the |
c65df279 | 741 | .I file |
742 | given on the command line, or from standard input if none is specified. | |
743 | Options provided are: | |
744 | .TP | |
cd6eca43 MW |
745 | .BI "\-p, \-\-progress" |
746 | Write a progress meter to standard error while processing large files. | |
747 | .TP | |
c65df279 | 748 | .BI "\-f, \-\-format " format |
749 | Produce output in | |
750 | .IR format . | |
751 | Run | |
752 | .B catcrypt show enc | |
753 | for a list of encoding formats. | |
754 | .TP | |
755 | .BI "\-b, \-\-boundary " label | |
756 | Set the PEM boundary string to | |
757 | .IR label ; | |
758 | i.e., assuming we're encoding in PEM format, the output will have | |
759 | .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-" | |
760 | at the top and | |
761 | .BI "\-\-\-\-\-END " label "\-\-\-\-\-" | |
762 | at the bottom. The default | |
763 | .I label | |
764 | is | |
765 | .BR MESSAGE . | |
766 | .TP | |
767 | .BI "\-o, \-\-output " file | |
768 | Write output to | |
769 | .I file | |
770 | instead of to standard output. | |
771 | .SS "decode" | |
772 | The | |
773 | .B decode | |
774 | command decodes an input file encoded according to one of the encodings | |
775 | described above in | |
776 | .BR ENCODINGS . | |
45c0fd36 | 777 | The input is read from the |
c65df279 | 778 | .I file |
779 | given on the command line, or from standard input if none is specified. | |
780 | Options provided are: | |
781 | .TP | |
782 | .BI "\-f, \-\-format " format | |
783 | Decode input in | |
784 | .IR format . | |
785 | Run | |
786 | .B catcrypt show enc | |
787 | for a list of encoding formats. | |
788 | .TP | |
789 | .BI "\-b, \-\-boundary " label | |
790 | Set the PEM boundary string to | |
791 | .IR label ; | |
792 | i.e., assuming we're encoding in PEM format, start processing input | |
793 | between | |
794 | .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-" | |
45c0fd36 | 795 | and |
c65df279 | 796 | .BI "\-\-\-\-\-END " label "\-\-\-\-\-" |
797 | lines. Without this option, | |
798 | .B catcrypt | |
799 | will start reading at the first plausible boundary string, and continue | |
800 | processing until it reaches the matching end boundary. | |
801 | .TP | |
cd6eca43 MW |
802 | .BI "\-p, \-\-progress" |
803 | Write a progress meter to standard error while processing large files. | |
804 | .TP | |
c65df279 | 805 | .BI "\-o, \-\-output " file |
806 | Write output to | |
807 | .I file | |
808 | instead of to standard output. | |
809 | .SH "SECURITY PROPERTIES" | |
810 | Assuming the security of the underlying primitive algorithms, the | |
811 | following security properties of the ciphertext hold. | |
812 | .hP \*o | |
813 | An adversary given the public key-encapsulation key and capable of | |
814 | requesting encryption of arbitrary plaintexts of his own devising is | |
815 | unable to decide whether he is given ciphertexts corresponding to his | |
816 | chosen plaintexts or random plaintexts of the same length. This holds | |
817 | even if the adversary is permitted to request decryption of any | |
818 | ciphertext other than one produced as a result of an encryption request. | |
819 | This property is called | |
820 | .BR IND-CCA2 . | |
821 | .hP \*o | |
822 | An adversary given the public key-encapsulation and verification keys, | |
823 | and capable of requesting encryption of arbitrary plaintext of his own | |
824 | devising is unable to produce a new ciphertext which will be accepted as | |
825 | genuine. This property is called | |
826 | .BR INT-CTXT . | |
827 | .hP \*o | |
828 | An adversary given the public key-encapsulation and verification keys, | |
829 | and capable of requesting encryption of arbitrary plaintext of his own | |
830 | devising is unable to decide whether the ciphertexts he is given are | |
831 | correctly signed. This property doesn't seem to have a name. | |
832 | .PP | |
833 | Not all is rosy. If you leak intermediate values during decryption then | |
834 | an adversary can construct a new correctly-signed message. Don't do | |
835 | that, then \(en leaking intermediate values often voids security | |
836 | warranties. But it does avoid the usual problem with separate signing | |
837 | and encryption that a careful leak by the recipient can produce evidence | |
838 | that you signed some incriminating message. | |
4224d0b9 | 839 | .PP |
840 | Note that | |
841 | .BR catcrypt 's | |
842 | signatures do | |
843 | .I not | |
844 | provide `non-repudiation' in any useful way. This is deliberate: the | |
845 | purpose of signing is to convince the recipient of the sender's | |
846 | identity, rather than to allow the recipient to persuade anyone else. | |
847 | Indeed, given an encrypted and signed message, the recipient can | |
848 | straightforwardly construct a new message, apparently from the same | |
849 | sender, and whose signature still verifies, but with arbitrarily chosen | |
850 | content. | |
c65df279 | 851 | .SH "CRYPTOGRAPHIC THEORY" |
852 | Encryption of a message proceeds as follows. | |
853 | .hP 0. | |
854 | Emit a header packet containing the key-ids for the key-encapsulation | |
855 | key, and signature key if any. | |
856 | .hP 1. | |
857 | Use the KEM to produce a public value and a shared secret the recipient | |
858 | will be able to extract from the public value using his private key. | |
859 | Emit a packet containing the public value. | |
860 | .hP 2. | |
861 | Hash the shared secret. Use the KDF to produce a pseudorandom keystream | |
862 | of indefinite length. | |
863 | .hP 3. | |
864 | Use the first bits of the keystream to key a symmetric encryption | |
865 | scheme; use the next bits to key a message authentication code. | |
866 | .hP 4. | |
867 | If we're signing the message then extract 1024 bytes from the keystream, | |
f9e51332 | 868 | sign the header and public value, and the keystream bytes; emit a packet |
869 | containing the signature. The signature packet doesn't contain the | |
870 | signed message, just the signature. | |
c65df279 | 871 | .hP 5. |
872 | Split the message into blocks. For each block, pick a random IV from | |
873 | the keystream, encrypt the block and emit a packet containing the | |
aaa2361e | 874 | IV, ciphertext, and a MAC tag over the ciphertext and a sequence number. |
875 | .hP 6. | |
876 | The last chunk is the encryption of an empty plaintext block. No | |
877 | previous plaintext block is empty. This lets us determine the | |
878 | difference between a complete file and one that's been maliciously | |
879 | truncated. | |
c65df279 | 880 | .PP |
881 | That's it. Nothing terribly controversial, really. | |
882 | .SH "SEE ALSO" | |
883 | .BR key (1), | |
fa54fe1e | 884 | .BR catsign (1), |
c65df279 | 885 | .BR dsig (1), |
886 | .BR hashsum (1), | |
887 | .BR keyring (5). | |
888 | .SH AUTHOR | |
f387fcb1 | 889 | Mark Wooding, <mdw@distorted.org.uk> |