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.)
150 attribute is present on the key, then it must have this form; otherwise,
151 the key's type must have the form
154 Algorithm selections are taken from appropriately-named attributes, or,
155 failing that, from the
158 The key-encapsulation mechanism is chosen according to the setting of
162 for a list of supported KEMs.
165 This is Shoup's RSA-KEM (formerly Simple RSA); see
167 A proposal for an ISO standard for public key encryption (version 2.0)
169 .BR http://eprint.iacr.org/2000/060/ .
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).
185 command, preferably with the
187 options, to generate the key.
190 This is the elliptic-curve analogue of
196 command to generate the key.
199 This is a simple symmetric encapsulation scheme. It works by hashing a
200 binary key with a randomly-generated salt. Use the
208 The bulk crypto transform is chosen based on the
210 attribute on the key, or, failing that,
216 .B catcrypt show bulk
217 for a list of supported bulk crypto transforms.
220 A generic composition of
221 a cipher secure against chosen-plaintext attack,
222 and a message authentication code.
228 This is the default transform.
231 Use Salsa20 or ChaCha and Poly1305 to secure the bulk data.
232 This is nearly the same as the NaCl
237 uses Salsa20 or ChaCha rather than XSalsa20,
238 because it doesn't need the latter's extended nonce.
241 attribute may be set to one of
252 As well as the KEM itself, a number of supporting algorithms are used.
253 These are taken from appropriately named attributes on the key or,
254 failing that, derived from other attributes as described below.
257 This is the symmetric encryption algorithm
258 used by the bulk data transform.
265 is used; if that it absent, then the default of
268 .B catcrypt show cipher
269 for a list of supported symmetric encryption algorithms.
272 This is the hash function used to distil entropy from the shared secret
273 constructed by the raw KEM. If there is no
279 is used; if that is absent then the default of
282 .B catcrypt show hash
283 for a list of supported symmetric encryption algorithms.
286 This is the message authentication algorithm
290 to ensure integrity of the encrypted message and
291 defend against chosen-ciphertext attacks.
296 is chosen as a default. Run
298 for a list of supported message authentication algorithms.
301 This is the key derivation function used to stretch the hashed shared
302 secret to a sufficient length to select symmetric encryption and
303 authentication keys, initialization vectors and other necessary
304 pseudorandom quantities. If there is no
308 is chosen as a default. Run
310 for a list of supported key derivation functions.
312 Not all supported functions have the required security features: don't
313 override the default choice unless you know what you're doing.
323 attribute is present on the key, then it must have this form; otherwise,
324 the key's type must have the form
327 Algorithm selections are taken from appropriately-named attributes, or,
328 failing that, from the
331 The signature algorithm is chosen according to the setting of
335 for a list of supported signature algorithms.
338 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
339 RFC3447; the difference is that the hash is left bare rather than being
340 wrapped in a DER-encoded
342 structure. This doesn't affect security since the key can only be used
343 with the one hash function anyway, and dropping the DER wrapping permits
344 rapid adoption of new hash functions. Regardless, use of this algorithm
345 is not recommended, since the padding method has been shown vulnerable
355 This is the RSASSA-PSS algorithm described in RFC3447. It is the
356 preferred RSA-based signature scheme. Use the
365 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
374 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
384 This is the revised KCDSA (Korean Certificate-based Digital Signature
385 Algorithm) described in
386 .I The Revised Version of KCDSA
387 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
399 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
409 This uses a symmetric message-authentication algorithm rather than a
410 digital signature. The precise message-authentication scheme used is
413 attribute on the key, which defaults to
415 if unspecified. Use the
423 As well as the signature algorithm itself, a hash function is used.
424 This is taken from the
426 attribute on the key, or, failing that, from the
430 or, if that is absent, determined by the signature algorithm as follows.
438 the default hash function is
445 the default hash function is
449 .B catcrypt show hash
450 for a list of supported hash functions.
452 Two encodings for the ciphertext are supported.
455 The raw format, which has the benefit of being smaller, but needs to be
456 attached to mail messages and generally handled with care.
459 PEM-encapsulated Base-64 encoded text. This format can be included
460 directly in email and picked out again automatically; but there is a
461 4-to-3 data expansion as a result.
462 .SH "COMMAND REFERENCE"
466 command behaves exactly as the
468 option. With no arguments, it shows an overview of
470 options; with arguments, it describes the named subcommands.
474 command prints various lists of tokens understood by
476 With no arguments, it prints all of the lists; with arguments, it prints
477 just the named lists, in order. The recognized lists can be enumerated
482 command. The lists are as follows.
485 The lists which can be enumerated by the
490 The key-encapsulation algorithms which can be used in a
491 key-encapsulation key's
496 The symmetric encryption algorithms which can be used in a
497 key-encapsulation key's
502 The message authentication algorithms which can be used in a
503 key-encapsulation key's
508 The signature algorithms which can be used in a signing key's
513 The hash functions which can be used in a key's
518 The encodings which can be applied to encrypted messages; see
524 command encrypts a file and writes out the appropriately-encoded
525 ciphertext. By default, it reads from standard input and writes to
526 standard output. If a filename argument is given, this file is read
527 instead (as binary data).
529 The following options are recognized.
532 Produce ASCII-armoured output. This is equivalent to specifying
538 .BI "\-f, \-\-format " format
539 Produce output encoded according to
542 .BI "\-k, \-\-key " tag
543 Use the key-encapsulation key named
545 in the current keyring; the default key is
548 .BI "\-p, \-\-progress"
549 Write a progress meter to standard error while processing large files.
551 .BI "\-s, \-\-sign-key " tag
552 Use the signature key named
554 in the current keyring; the default is not to sign the ciphertext.
556 .BI "\-o, \-\-ouptut " file
559 rather than to standard output.
561 .B "\-C, \-\-nocheck"
562 Don't check the public key for validity. This makes encryption go much
563 faster, but at the risk of using a duff key.
567 command decrypts a ciphertext and writes out the plaintext. By default,
568 it reads from standard input and writes to standard output. If a
569 filename argument is given, this file is read instead.
571 The following options are recognized.
574 Read ASCII-armoured input. This is equivalent to specifying
581 Buffer plaintext data until we're sure we've got it all. This is forced
582 on if output is to stdout, but is always available as an option.
584 .BI "\-f, \-\-format " format
585 Read input encoded according to
588 .BI "\-p, \-\-progress"
589 Write a progress meter to standard error while processing large files.
591 .B "\-v, \-\-verbose"
592 Produce more verbose messages. See below for the messages produced
593 during decryption. The default verbosity level is 1. (Currently this
594 is the most verbose setting. This might not be the case always.)
597 Produce fewer messages.
599 .BI "\-o, \-\-output " file
602 instead of to standard output. The file is written in binary mode.
603 Fixing line-end conventions is your problem; there are lots of good
604 tools for dealing with it.
606 .B "\-C, \-\-nocheck"
607 Don't check the private key for validity. This makes decryption go much
608 faster, but at the risk of using a duff key, and possibly leaking
609 information about the private key.
611 Output is written to standard output in a machine-readable format.
612 Major problems cause the program to write a diagnostic to standard error
613 and exit nonzero as usual. The quantity of output varies depending on
614 the verbosity level and whether the plaintext is also being written to
615 standard output. Output lines begin with a keyword:
618 An error prevented decryption. The program will exit nonzero.
622 encountered a situation which may or may not invalidate the decryption.
625 Decryption was successful. This is only produced if main output is
626 being sent somewhere other than standard output.
629 The plaintext follows, starting just after the next newline character or
630 sequence. This is only produced if main output is also being sent to
634 Any other information.
636 The information written at the various verbosity levels is as follows.
638 No output. Watch the exit status.
643 All output written has been checked for authenticity. However, output
644 can fail midway through for many reasons, and the resulting message may
645 therefore be truncated. Don't rely on the output being complete until
653 command encodes an input file according to one of the encodings
656 The input is read from the
658 given on the command line, or from standard input if none is specified.
659 Options provided are:
661 .BI "\-p, \-\-progress"
662 Write a progress meter to standard error while processing large files.
664 .BI "\-f, \-\-format " format
669 for a list of encoding formats.
671 .BI "\-b, \-\-boundary " label
672 Set the PEM boundary string to
674 i.e., assuming we're encoding in PEM format, the output will have
675 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
677 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
678 at the bottom. The default
683 .BI "\-o, \-\-output " file
686 instead of to standard output.
690 command decodes an input file encoded according to one of the encodings
693 The input is read from the
695 given on the command line, or from standard input if none is specified.
696 Options provided are:
698 .BI "\-f, \-\-format " format
703 for a list of encoding formats.
705 .BI "\-b, \-\-boundary " label
706 Set the PEM boundary string to
708 i.e., assuming we're encoding in PEM format, start processing input
710 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
712 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
713 lines. Without this option,
715 will start reading at the first plausible boundary string, and continue
716 processing until it reaches the matching end boundary.
718 .BI "\-p, \-\-progress"
719 Write a progress meter to standard error while processing large files.
721 .BI "\-o, \-\-output " file
724 instead of to standard output.
725 .SH "SECURITY PROPERTIES"
726 Assuming the security of the underlying primitive algorithms, the
727 following security properties of the ciphertext hold.
729 An adversary given the public key-encapsulation key and capable of
730 requesting encryption of arbitrary plaintexts of his own devising is
731 unable to decide whether he is given ciphertexts corresponding to his
732 chosen plaintexts or random plaintexts of the same length. This holds
733 even if the adversary is permitted to request decryption of any
734 ciphertext other than one produced as a result of an encryption request.
735 This property is called
738 An adversary given the public key-encapsulation and verification keys,
739 and capable of requesting encryption of arbitrary plaintext of his own
740 devising is unable to produce a new ciphertext which will be accepted as
741 genuine. This property is called
744 An adversary given the public key-encapsulation and verification keys,
745 and capable of requesting encryption of arbitrary plaintext of his own
746 devising is unable to decide whether the ciphertexts he is given are
747 correctly signed. This property doesn't seem to have a name.
749 Not all is rosy. If you leak intermediate values during decryption then
750 an adversary can construct a new correctly-signed message. Don't do
751 that, then \(en leaking intermediate values often voids security
752 warranties. But it does avoid the usual problem with separate signing
753 and encryption that a careful leak by the recipient can produce evidence
754 that you signed some incriminating message.
760 provide `non-repudiation' in any useful way. This is deliberate: the
761 purpose of signing is to convince the recipient of the sender's
762 identity, rather than to allow the recipient to persuade anyone else.
763 Indeed, given an encrypted and signed message, the recipient can
764 straightforwardly construct a new message, apparently from the same
765 sender, and whose signature still verifies, but with arbitrarily chosen
767 .SH "CRYPTOGRAPHIC THEORY"
768 Encryption of a message proceeds as follows.
770 Emit a header packet containing the key-ids for the key-encapsulation
771 key, and signature key if any.
773 Use the KEM to produce a public value and a shared secret the recipient
774 will be able to extract from the public value using his private key.
775 Emit a packet containing the public value.
777 Hash the shared secret. Use the KDF to produce a pseudorandom keystream
778 of indefinite length.
780 Use the first bits of the keystream to key a symmetric encryption
781 scheme; use the next bits to key a message authentication code.
783 If we're signing the message then extract 1024 bytes from the keystream,
784 sign the header and public value, and the keystream bytes; emit a packet
785 containing the signature. The signature packet doesn't contain the
786 signed message, just the signature.
788 Split the message into blocks. For each block, pick a random IV from
789 the keystream, encrypt the block and emit a packet containing the
790 IV, ciphertext, and a MAC tag over the ciphertext and a sequence number.
792 The last chunk is the encryption of an empty plaintext block. No
793 previous plaintext block is empty. This lets us determine the
794 difference between a complete file and one that's been maliciously
797 That's it. Nothing terribly controversial, really.
805 Mark Wooding, <mdw@distorted.org.uk>
~mdw / catacomb / blob