22 \h'-\w'\\$1\ 'u'\\$1\ \c
27 .TH catcrypt 1 "30 September 2004" "Straylight/Edgeware" "Catacomb cryptographic library"
29 catcrypt \- encrypt and decrypt messages
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.
88 Before the command name,
90 may be given. The following global options are supported:
92 .BR "\-h, \-\-help " [ \fIcommand ...]
93 Writes a brief summary of
95 various options to standard output, and returns a successful exit
96 status. With command names, gives help on those commands.
99 Writes the program's version number to standard output, and returns a
100 successful exit status.
103 Writes a very terse command line summary to standard output, and returns
104 a successful exit status.
106 .BI "\-k, \-\-keyring " file
107 Names the keyring file which
109 is to process. The default keyring, used if this option doesn't specify
110 one, is the file named
112 in the current directory. See
116 for more details about keyring files.
118 Algorithms to be used with a particular key are described by attributes
119 on the key, or its type. The
121 command deals with both signing and key-encapsulation keys. (Note that
123 uses signing keys in the same way as
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.)
140 attribute is present on the key, then it must have this form; otherwise,
141 the key's type must have the form
144 Algorithm selections are taken from appropriately-named attributes, or,
145 failing that, from the
148 The key-encapsulation mechanism is chosen according to the setting of
152 for a list of supported KEMs.
155 This is Shoup's RSA-KEM (formerly Simple RSA); see
157 A proposal for an ISO standard for public key encryption (version 2.0)
159 .BR http://eprint.iacr.org/2000/060/ .
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).
175 command, preferably with the
177 options, to generate the key.
180 This is the elliptic-curve analogue of
186 command to generate the key.
189 This is a simple symmetric encapsulation scheme. It works by hashing a
190 binary key with a randomly-generated salt. Use the
198 As well as the KEM itself, a number of supporting algorithms are used.
199 These are taken from appropriately named attributes on the key or,
200 failing that, derived from other attributes as described below.
203 This is the symmetric encryption algorithm used for bulk data
204 encryption. If there is no
210 is used; if that it absent, then the default of
213 .B catcrypt show cipher
214 for a list of supported symmetric encryption algorithms.
217 This is the hash function used to distil entropy from the shared secret
218 constructed by the raw KEM. If there is no
224 is used; if that is absent then the default of
227 .B catcrypt show hash
228 for a list of supported symmetric encryption algorithms.
231 This is the message authentication algorithm used during bulk data
232 encryption to ensure integrity of the encrypted message and defend
233 against chosen-ciphertext attacks. If there is no
237 is chosen as a default. Run
239 for a list of supported message authentication algorithms.
242 This is the key derivation function used to stretch the hashed shared
243 secret to a sufficient length to select symmetric encryption and
244 authentication keys, initialization vectors and other necessary
245 pseudorandom quantities. If there is no
249 is chosen as a default. Run
251 for a list of supported key derivation functions.
253 Not all supported functions have the required security features: don't
254 override the default choice unless you know what you're doing.
264 attribute is present on the key, then it must have this form; otherwise,
265 the key's type must have the form
268 Algorithm selections are taken from appropriately-named attributes, or,
269 failing that, from the
272 The signature algorithm is chosen according to the setting of
276 for a list of supported signature algorithms.
279 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
280 RFC3447; the difference is that the hash is left bare rather than being
281 wrapped in a DER-encoded
283 structure. This doesn't affect security since the key can only be used
284 with the one hash function anyway, and dropping the DER wrapping permits
285 rapid adoption of new hash functions. Regardless, use of this algorithm
286 is not recommended, since the padding method has been shown vulnerable
296 This is the RSASSA-PSS algorithm described in RFC3447. It is the
297 preferred RSA-based signature scheme. Use the
306 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
315 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
325 This is the revised KCDSA (Korean Certificate-based Digital Signature
326 Algorithm) described in
327 .I The Revised Version of KCDSA
328 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
340 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
350 This uses a symmetric message-authentication algorithm rather than a
351 digital signature. The precise message-authentication scheme used is
354 attribute on the key, which defaults to
356 if unspecified. Use the
364 As well as the signature algorithm itself, a hash function is used.
365 This is taken from the
367 attribute on the key, or, failing that, from the
371 or, if that is absent, determined by the signature algorithm as follows.
379 the default hash function is
386 the default hash function is
390 .B catcrypt show hash
391 for a list of supported hash functions.
393 Two encodings for the ciphertext are supported.
396 The raw format, which has the benefit of being smaller, but needs to be
397 attached to mail messages and generally handled with care.
400 PEM-encapsulated Base-64 encoded text. This format can be included
401 directly in email and picked out again automatically; but there is a
402 4-to-3 data expansion as a result.
403 .SH "COMMAND REFERENCE"
407 command behaves exactly as the
409 option. With no arguments, it shows an overview of
411 options; with arguments, it describes the named subcommands.
415 command prints various lists of tokens understood by
417 With no arguments, it prints all of the lists; with arguments, it prints
418 just the named lists, in order. The recognized lists can be enumerated
423 command. The lists are as follows.
426 The lists which can be enumerated by the
431 The key-encapsulation algorithms which can be used in a
432 key-encapsulation key's
437 The symmetric encryption algorithms which can be used in a
438 key-encapsulation key's
443 The message authentication algorithms which can be used in a
444 key-encapsulation key's
449 The signature algorithms which can be used in a signing key's
454 The hash functions which can be used in a key's
459 The encodings which can be applied to encrypted messages; see
465 command encrypts a file and writes out the appropriately-encoded
466 ciphertext. By default, it reads from standard input and writes to
467 standard output. If a filename argument is given, this file is read
468 instead (as binary data).
470 The following options are recognized.
473 Produce ASCII-armoured output. This is equivalent to specifying
479 .BI "\-f, \-\-format " format
480 Produce output encoded according to
483 .BI "\-k, \-\-key " tag
484 Use the key-encapsulation key named
486 in the current keyring; the default key is
489 .BI "\-s, \-\-sign-key " tag
490 Use the signature key named
492 in the current keyring; the default is not to sign the ciphertext.
494 .BI "\-o, \-\-ouptut " file
497 rather than to standard output.
499 .B "\-C, \-\-nocheck"
500 Don't check the public key for validity. This makes encryption go much
501 faster, but at the risk of using a duff key.
505 command decrypts a ciphertext and writes out the plaintext. By default,
506 it reads from standard input and writes to standard output. If a
507 filename argument is given, this file is read instead.
509 The following options are recognized.
512 Read ASCII-armoured input. This is equivalent to specifying
519 Buffer plaintext data until we're sure we've got it all. This is forced
520 on if output is to stdout, but is always available as an option.
522 .BI "\-f, \-\-format " format
523 Read input encoded according to
526 .B "\-v, \-\-verbose"
527 Produce more verbose messages. See below for the messages produced
528 during decryption. The default verbosity level is 1. (Currently this
529 is the most verbose setting. This might not be the case always.)
532 Produce fewer messages.
534 .BI "\-o, \-\-output " file
537 instead of to standard output. The file is written in binary mode.
538 Fixing line-end conventions is your problem; there are lots of good
539 tools for dealing with it.
541 .B "\-C, \-\-nocheck"
542 Don't check the private key for validity. This makes decryption go much
543 faster, but at the risk of using a duff key, and possibly leaking
544 information about the private key.
546 Output is written to standard output in a machine-readable format.
547 Major problems cause the program to write a diagnostic to standard error
548 and exit nonzero as usual. The quantity of output varies depending on
549 the verbosity level and whether the plaintext is also being written to
550 standard output. Output lines begin with a keyword:
553 An error prevented decryption. The program will exit nonzero.
557 encountered a situation which may or may not invalidate the decryption.
560 Decryption was successful. This is only produced if main output is
561 being sent somewhere other than standard output.
564 The plaintext follows, starting just after the next newline character or
565 sequence. This is only produced if main output is also being sent to
569 Any other information.
571 The information written at the various verbosity levels is as follows.
573 No output. Watch the exit status.
578 All output written has been checked for authenticity. However, output
579 can fail madway through for many reasons, and the resulting message may
580 therefore be truncated. Don't rely on the output being complete until
588 command encodes an input file according to one of the encodings
591 The input is read from the
593 given on the command line, or from standard input if none is specified.
594 Options provided are:
596 .BI "\-f, \-\-format " format
601 for a list of encoding formats.
603 .BI "\-b, \-\-boundary " label
604 Set the PEM boundary string to
606 i.e., assuming we're encoding in PEM format, the output will have
607 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
609 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
610 at the bottom. The default
615 .BI "\-o, \-\-output " file
618 instead of to standard output.
622 command decodes an input file encoded according to one of the encodings
625 The input is read from the
627 given on the command line, or from standard input if none is specified.
628 Options provided are:
630 .BI "\-f, \-\-format " format
635 for a list of encoding formats.
637 .BI "\-b, \-\-boundary " label
638 Set the PEM boundary string to
640 i.e., assuming we're encoding in PEM format, start processing input
642 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
644 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
645 lines. Without this option,
647 will start reading at the first plausible boundary string, and continue
648 processing until it reaches the matching end boundary.
650 .BI "\-o, \-\-output " file
653 instead of to standard output.
654 .SH "SECURITY PROPERTIES"
655 Assuming the security of the underlying primitive algorithms, the
656 following security properties of the ciphertext hold.
658 An adversary given the public key-encapsulation key and capable of
659 requesting encryption of arbitrary plaintexts of his own devising is
660 unable to decide whether he is given ciphertexts corresponding to his
661 chosen plaintexts or random plaintexts of the same length. This holds
662 even if the adversary is permitted to request decryption of any
663 ciphertext other than one produced as a result of an encryption request.
664 This property is called
667 An adversary given the public key-encapsulation and verification keys,
668 and capable of requesting encryption of arbitrary plaintext of his own
669 devising is unable to produce a new ciphertext which will be accepted as
670 genuine. This property is called
673 An adversary given the public key-encapsulation and verification keys,
674 and capable of requesting encryption of arbitrary plaintext of his own
675 devising is unable to decide whether the ciphertexts he is given are
676 correctly signed. This property doesn't seem to have a name.
678 Not all is rosy. If you leak intermediate values during decryption then
679 an adversary can construct a new correctly-signed message. Don't do
680 that, then \(en leaking intermediate values often voids security
681 warranties. But it does avoid the usual problem with separate signing
682 and encryption that a careful leak by the recipient can produce evidence
683 that you signed some incriminating message.
689 provide `non-repudiation' in any useful way. This is deliberate: the
690 purpose of signing is to convince the recipient of the sender's
691 identity, rather than to allow the recipient to persuade anyone else.
692 Indeed, given an encrypted and signed message, the recipient can
693 straightforwardly construct a new message, apparently from the same
694 sender, and whose signature still verifies, but with arbitrarily chosen
696 .SH "CRYPTOGRAPHIC THEORY"
697 Encryption of a message proceeds as follows.
699 Emit a header packet containing the key-ids for the key-encapsulation
700 key, and signature key if any.
702 Use the KEM to produce a public value and a shared secret the recipient
703 will be able to extract from the public value using his private key.
704 Emit a packet containing the public value.
706 Hash the shared secret. Use the KDF to produce a pseudorandom keystream
707 of indefinite length.
709 Use the first bits of the keystream to key a symmetric encryption
710 scheme; use the next bits to key a message authentication code.
712 If we're signing the message then extract 1024 bytes from the keystream,
713 sign the header and public value, and the keystream bytes; emit a packet
714 containing the signature. The signature packet doesn't contain the
715 signed message, just the signature.
717 Split the message into blocks. For each block, pick a random IV from
718 the keystream, encrypt the block and emit a packet containing the
719 IV, ciphertext, and a MAC tag over the ciphertext and a sequence number.
721 The last chunk is the encryption of an empty plaintext block. No
722 previous plaintext block is empty. This lets us determine the
723 difference between a complete file and one that's been maliciously
726 That's it. Nothing terribly controversial, really.
734 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob