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
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.
90 Before the command name,
92 may be given. The following global options are supported:
94 .BR "\-h, \-\-help " [ \fIcommand ...]
95 Writes a brief summary of
97 various options to standard output, and returns a successful exit
98 status. With command names, gives help on those commands.
100 .B "\-v, \-\-version"
101 Writes the program's version number to standard output, and returns a
102 successful exit status.
105 Writes a very terse command line summary to standard output, and returns
106 a successful exit status.
108 .BI "\-k, \-\-keyring " file
109 Names the keyring file which
111 is to process. The default keyring, used if this option doesn't specify
112 one, is the file named
114 in the current directory. See
118 for more details about keyring files.
120 Algorithms to be used with a particular key are described by attributes
121 on the key, or its type. The
123 command deals with both signing and key-encapsulation keys. (Note that
125 uses signing keys in the same way as
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.)
142 attribute is present on the key, then it must have this form; otherwise,
143 the key's type must have the form
146 Algorithm selections are taken from appropriately-named attributes, or,
147 failing that, from the
150 The key-encapsulation mechanism is chosen according to the setting of
154 for a list of supported KEMs.
157 This is Shoup's RSA-KEM (formerly Simple RSA); see
159 A proposal for an ISO standard for public key encryption (version 2.0)
161 .BR http://eprint.iacr.org/2000/060/ .
171 This is standard Diffie-Hellman key exchange, hashing the resulting
172 shared secret to form the key, as used in, e.g., DLIES (P1363a).
177 command, preferably with the
179 options, to generate the key.
182 This is the elliptic-curve analogue of
188 command to generate the key.
191 This is a simple symmetric encapsulation scheme. It works by hashing a
192 binary key with a randomly-generated salt. Use the
200 As well as the KEM itself, a number of supporting algorithms are used.
201 These are taken from appropriately named attributes on the key or,
202 failing that, derived from other attributes as described below.
205 This is the symmetric encryption algorithm used for bulk data
206 encryption. If there is no
212 is used; if that it absent, then the default of
215 .B catcrypt show cipher
216 for a list of supported symmetric encryption algorithms.
219 This is the hash function used to distil entropy from the shared secret
220 constructed by the raw KEM. If there is no
226 is used; if that is absent then the default of
229 .B catcrypt show hash
230 for a list of supported symmetric encryption algorithms.
233 This is the message authentication algorithm used during bulk data
234 encryption to ensure integrity of the encrypted message and defend
235 against chosen-ciphertext attacks. If there is no
239 is chosen as a default. Run
241 for a list of supported message authentication algorithms.
244 This is the key derivation function used to stretch the hashed shared
245 secret to a sufficient length to select symmetric encryption and
246 authentication keys, initialization vectors and other necessary
247 pseudorandom quantities. If there is no
251 is chosen as a default. Run
253 for a list of supported key derivation functions.
255 Not all supported functions have the required security features: don't
256 override the default choice unless you know what you're doing.
266 attribute is present on the key, then it must have this form; otherwise,
267 the key's type must have the form
270 Algorithm selections are taken from appropriately-named attributes, or,
271 failing that, from the
274 The signature algorithm is chosen according to the setting of
278 for a list of supported signature algorithms.
281 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
282 RFC3447; the difference is that the hash is left bare rather than being
283 wrapped in a DER-encoded
285 structure. This doesn't affect security since the key can only be used
286 with the one hash function anyway, and dropping the DER wrapping permits
287 rapid adoption of new hash functions. Regardless, use of this algorithm
288 is not recommended, since the padding method has been shown vulnerable
298 This is the RSASSA-PSS algorithm described in RFC3447. It is the
299 preferred RSA-based signature scheme. Use the
308 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
317 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
327 This is the revised KCDSA (Korean Certificate-based Digital Signature
328 Algorithm) described in
329 .I The Revised Version of KCDSA
330 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
342 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
352 This uses a symmetric message-authentication algorithm rather than a
353 digital signature. The precise message-authentication scheme used is
356 attribute on the key, which defaults to
358 if unspecified. Use the
366 As well as the signature algorithm itself, a hash function is used.
367 This is taken from the
369 attribute on the key, or, failing that, from the
373 or, if that is absent, determined by the signature algorithm as follows.
381 the default hash function is
388 the default hash function is
392 .B catcrypt show hash
393 for a list of supported hash functions.
395 Two encodings for the ciphertext are supported.
398 The raw format, which has the benefit of being smaller, but needs to be
399 attached to mail messages and generally handled with care.
402 PEM-encapsulated Base-64 encoded text. This format can be included
403 directly in email and picked out again automatically; but there is a
404 4-to-3 data expansion as a result.
405 .SH "COMMAND REFERENCE"
409 command behaves exactly as the
411 option. With no arguments, it shows an overview of
413 options; with arguments, it describes the named subcommands.
417 command prints various lists of tokens understood by
419 With no arguments, it prints all of the lists; with arguments, it prints
420 just the named lists, in order. The recognized lists can be enumerated
425 command. The lists are as follows.
428 The lists which can be enumerated by the
433 The key-encapsulation algorithms which can be used in a
434 key-encapsulation key's
439 The symmetric encryption algorithms which can be used in a
440 key-encapsulation key's
445 The message authentication algorithms which can be used in a
446 key-encapsulation key's
451 The signature algorithms which can be used in a signing key's
456 The hash functions which can be used in a key's
461 The encodings which can be applied to encrypted messages; see
467 command encrypts a file and writes out the appropriately-encoded
468 ciphertext. By default, it reads from standard input and writes to
469 standard output. If a filename argument is given, this file is read
470 instead (as binary data).
472 The following options are recognized.
475 Produce ASCII-armoured output. This is equivalent to specifying
481 .BI "\-f, \-\-format " format
482 Produce output encoded according to
485 .BI "\-k, \-\-key " tag
486 Use the key-encapsulation key named
488 in the current keyring; the default key is
491 .BI "\-p, \-\-progress"
492 Write a progress meter to standard error while processing large files.
494 .BI "\-s, \-\-sign-key " tag
495 Use the signature key named
497 in the current keyring; the default is not to sign the ciphertext.
499 .BI "\-o, \-\-ouptut " file
502 rather than to standard output.
504 .B "\-C, \-\-nocheck"
505 Don't check the public key for validity. This makes encryption go much
506 faster, but at the risk of using a duff key.
510 command decrypts a ciphertext and writes out the plaintext. By default,
511 it reads from standard input and writes to standard output. If a
512 filename argument is given, this file is read instead.
514 The following options are recognized.
517 Read ASCII-armoured input. This is equivalent to specifying
524 Buffer plaintext data until we're sure we've got it all. This is forced
525 on if output is to stdout, but is always available as an option.
527 .BI "\-f, \-\-format " format
528 Read input encoded according to
531 .BI "\-p, \-\-progress"
532 Write a progress meter to standard error while processing large files.
534 .B "\-v, \-\-verbose"
535 Produce more verbose messages. See below for the messages produced
536 during decryption. The default verbosity level is 1. (Currently this
537 is the most verbose setting. This might not be the case always.)
540 Produce fewer messages.
542 .BI "\-o, \-\-output " file
545 instead of to standard output. The file is written in binary mode.
546 Fixing line-end conventions is your problem; there are lots of good
547 tools for dealing with it.
549 .B "\-C, \-\-nocheck"
550 Don't check the private key for validity. This makes decryption go much
551 faster, but at the risk of using a duff key, and possibly leaking
552 information about the private key.
554 Output is written to standard output in a machine-readable format.
555 Major problems cause the program to write a diagnostic to standard error
556 and exit nonzero as usual. The quantity of output varies depending on
557 the verbosity level and whether the plaintext is also being written to
558 standard output. Output lines begin with a keyword:
561 An error prevented decryption. The program will exit nonzero.
565 encountered a situation which may or may not invalidate the decryption.
568 Decryption was successful. This is only produced if main output is
569 being sent somewhere other than standard output.
572 The plaintext follows, starting just after the next newline character or
573 sequence. This is only produced if main output is also being sent to
577 Any other information.
579 The information written at the various verbosity levels is as follows.
581 No output. Watch the exit status.
586 All output written has been checked for authenticity. However, output
587 can fail madway through for many reasons, and the resulting message may
588 therefore be truncated. Don't rely on the output being complete until
596 command encodes an input file according to one of the encodings
599 The input is read from the
601 given on the command line, or from standard input if none is specified.
602 Options provided are:
604 .BI "\-p, \-\-progress"
605 Write a progress meter to standard error while processing large files.
607 .BI "\-f, \-\-format " format
612 for a list of encoding formats.
614 .BI "\-b, \-\-boundary " label
615 Set the PEM boundary string to
617 i.e., assuming we're encoding in PEM format, the output will have
618 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
620 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
621 at the bottom. The default
626 .BI "\-o, \-\-output " file
629 instead of to standard output.
633 command decodes an input file encoded according to one of the encodings
636 The input is read from the
638 given on the command line, or from standard input if none is specified.
639 Options provided are:
641 .BI "\-f, \-\-format " format
646 for a list of encoding formats.
648 .BI "\-b, \-\-boundary " label
649 Set the PEM boundary string to
651 i.e., assuming we're encoding in PEM format, start processing input
653 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
655 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
656 lines. Without this option,
658 will start reading at the first plausible boundary string, and continue
659 processing until it reaches the matching end boundary.
661 .BI "\-p, \-\-progress"
662 Write a progress meter to standard error while processing large files.
664 .BI "\-o, \-\-output " file
667 instead of to standard output.
668 .SH "SECURITY PROPERTIES"
669 Assuming the security of the underlying primitive algorithms, the
670 following security properties of the ciphertext hold.
672 An adversary given the public key-encapsulation key and capable of
673 requesting encryption of arbitrary plaintexts of his own devising is
674 unable to decide whether he is given ciphertexts corresponding to his
675 chosen plaintexts or random plaintexts of the same length. This holds
676 even if the adversary is permitted to request decryption of any
677 ciphertext other than one produced as a result of an encryption request.
678 This property is called
681 An adversary given the public key-encapsulation and verification keys,
682 and capable of requesting encryption of arbitrary plaintext of his own
683 devising is unable to produce a new ciphertext which will be accepted as
684 genuine. This property is called
687 An adversary given the public key-encapsulation and verification keys,
688 and capable of requesting encryption of arbitrary plaintext of his own
689 devising is unable to decide whether the ciphertexts he is given are
690 correctly signed. This property doesn't seem to have a name.
692 Not all is rosy. If you leak intermediate values during decryption then
693 an adversary can construct a new correctly-signed message. Don't do
694 that, then \(en leaking intermediate values often voids security
695 warranties. But it does avoid the usual problem with separate signing
696 and encryption that a careful leak by the recipient can produce evidence
697 that you signed some incriminating message.
703 provide `non-repudiation' in any useful way. This is deliberate: the
704 purpose of signing is to convince the recipient of the sender's
705 identity, rather than to allow the recipient to persuade anyone else.
706 Indeed, given an encrypted and signed message, the recipient can
707 straightforwardly construct a new message, apparently from the same
708 sender, and whose signature still verifies, but with arbitrarily chosen
710 .SH "CRYPTOGRAPHIC THEORY"
711 Encryption of a message proceeds as follows.
713 Emit a header packet containing the key-ids for the key-encapsulation
714 key, and signature key if any.
716 Use the KEM to produce a public value and a shared secret the recipient
717 will be able to extract from the public value using his private key.
718 Emit a packet containing the public value.
720 Hash the shared secret. Use the KDF to produce a pseudorandom keystream
721 of indefinite length.
723 Use the first bits of the keystream to key a symmetric encryption
724 scheme; use the next bits to key a message authentication code.
726 If we're signing the message then extract 1024 bytes from the keystream,
727 sign the header and public value, and the keystream bytes; emit a packet
728 containing the signature. The signature packet doesn't contain the
729 signed message, just the signature.
731 Split the message into blocks. For each block, pick a random IV from
732 the keystream, encrypt the block and emit a packet containing the
733 IV, ciphertext, and a MAC tag over the ciphertext and a sequence number.
735 The last chunk is the encryption of an empty plaintext block. No
736 previous plaintext block is empty. This lets us determine the
737 difference between a complete file and one that's been maliciously
740 That's it. Nothing terribly controversial, really.
748 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob