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