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
209 This is Bernstein's Curve25519, a fast Diffie-Hellman using a specific
221 This is Hamburg's Curve25519, a strong Diffie-Hellman using a specific
232 The bulk crypto transform is chosen based on the
234 attribute on the key, or, failing that,
240 .B catcrypt show bulk
241 for a list of supported bulk crypto transforms.
244 A generic composition of
245 a cipher secure against chosen-plaintext attack,
246 and a message authentication code.
252 .B catcrypt show cipher
253 for a list of supported symmetric encryption algorithms; the default
257 This is the default transform.
260 Use an `authenticated encryption with additional data' (AEAD) scheme.
261 The specific scheme is named by the
264 .B catcrypt show aead
265 for a list of supported AEAD schemes; the default is
266 .BR chacha20-poly1305 .
269 Use Salsa20 or ChaCha and Poly1305 to secure the bulk data.
270 This is nearly the same as the NaCl
275 uses Salsa20 or ChaCha rather than XSalsa20,
276 because it doesn't need the latter's extended nonce.
279 attribute may be set to one of
289 Nowadays, this is equivalent to the
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.
300 This is the symmetric encryption algorithm
301 used by the bulk data transform.
308 is used; if that it absent, then the default depends on the bulk
312 This is the hash function used to distil entropy from the shared secret
313 constructed by the raw KEM. If there is no
319 is used; if that is absent then the default of
322 .B catcrypt show hash
323 for a list of supported symmetric encryption algorithms.
326 This is the message authentication algorithm
330 to ensure integrity of the encrypted message and
331 defend against chosen-ciphertext attacks.
336 is chosen as a default. Run
338 for a list of supported message authentication algorithms.
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
348 is chosen as a default. Run
350 for a list of supported key derivation functions.
352 Not all supported functions have the required security features: don't
353 override the default choice unless you know what you're doing.
363 attribute is present on the key, then it must have this form; otherwise,
364 the key's type must have the form
367 Algorithm selections are taken from appropriately-named attributes, or,
368 failing that, from the
371 The signature algorithm is chosen according to the setting of
375 for a list of supported signature algorithms.
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
380 wrapped in a DER-encoded
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
395 This is the RSASSA-PSS algorithm described in RFC3447. It is the
396 preferred RSA-based signature scheme. Use the
405 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
414 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
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 ).
439 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
449 This is Bernstein, Duif, Lange, Schwabe, and Yang's Ed25519 algorithm.
450 More specifically, this is HashEd25519
453 algorithm \(en by default
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
471 algorithm \(en by default
483 This uses a symmetric message-authentication algorithm rather than a
484 digital signature. The precise message-authentication scheme used is
487 attribute on the key, which defaults to
489 if unspecified. Use the
497 As well as the signature algorithm itself, a hash function is used.
498 This is taken from the
500 attribute on the key, or, failing that, from the
504 or, if that is absent, determined by the signature algorithm as follows.
512 the default hash function is
519 the default hash function is
523 the default hash function is
527 the default hash function is
531 .B catcrypt show hash
532 for a list of supported hash functions.
534 Two encodings for the ciphertext are supported.
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.
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"
548 command behaves exactly as the
550 option. With no arguments, it shows an overview of
552 options; with arguments, it describes the named subcommands.
556 command prints various lists of tokens understood by
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
564 command. The lists are as follows.
567 The lists which can be enumerated by the
572 The key-encapsulation algorithms which can be used in a
573 key-encapsulation key's
578 The symmetric encryption algorithms which can be named in a
579 key-encapsulation key's
581 attribute when using the
586 The message authentication algorithms which can be named in a
587 key-encapsulation key's
592 The signature algorithms which can be named in a signing key's
597 The hash functions which can be named in a key's
602 The encodings which can be applied to encrypted messages; see
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).
613 The following options are recognized.
616 Produce ASCII-armoured output. This is equivalent to specifying
622 .BI "\-f, \-\-format " format
623 Produce output encoded according to
626 .BI "\-k, \-\-key " tag
627 Use the key-encapsulation key named
629 in the current keyring; the default key is
632 .BI "\-p, \-\-progress"
633 Write a progress meter to standard error while processing large files.
635 .BI "\-s, \-\-sign-key " tag
636 Use the signature key named
638 in the current keyring; the default is not to sign the ciphertext.
640 .BI "\-o, \-\-ouptut " file
643 rather than to standard output.
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.
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.
655 The following options are recognized.
658 Read ASCII-armoured input. This is equivalent to specifying
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.
668 .BI "\-f, \-\-format " format
669 Read input encoded according to
672 .BI "\-p, \-\-progress"
673 Write a progress meter to standard error while processing large files.
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.)
681 Produce fewer messages.
683 .BI "\-o, \-\-output " 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.
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.
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
699 standard output. Output lines begin with a keyword:
702 An error prevented decryption. The program will exit nonzero.
706 encountered a situation which may or may not invalidate the decryption.
709 Decryption was successful. This is only produced if main output is
710 being sent somewhere other than standard output.
713 The plaintext follows, starting just after the next newline character or
714 sequence. This is only produced if main output is also being sent to
718 Any other information.
720 The information written at the various verbosity levels is as follows.
722 No output. Watch the exit status.
727 All output written has been checked for authenticity. However, output
728 can fail midway through for many reasons, and the resulting message may
729 therefore be truncated. Don't rely on the output being complete until
737 command encodes an input file according to one of the encodings
740 The input is read from the
742 given on the command line, or from standard input if none is specified.
743 Options provided are:
745 .BI "\-p, \-\-progress"
746 Write a progress meter to standard error while processing large files.
748 .BI "\-f, \-\-format " format
753 for a list of encoding formats.
755 .BI "\-b, \-\-boundary " label
756 Set the PEM boundary string to
758 i.e., assuming we're encoding in PEM format, the output will have
759 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
761 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
762 at the bottom. The default
767 .BI "\-o, \-\-output " file
770 instead of to standard output.
774 command decodes an input file encoded according to one of the encodings
777 The input is read from the
779 given on the command line, or from standard input if none is specified.
780 Options provided are:
782 .BI "\-f, \-\-format " format
787 for a list of encoding formats.
789 .BI "\-b, \-\-boundary " label
790 Set the PEM boundary string to
792 i.e., assuming we're encoding in PEM format, start processing input
794 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
796 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
797 lines. Without this option,
799 will start reading at the first plausible boundary string, and continue
800 processing until it reaches the matching end boundary.
802 .BI "\-p, \-\-progress"
803 Write a progress meter to standard error while processing large files.
805 .BI "\-o, \-\-output " 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.
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
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
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.
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.
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
851 .SH "CRYPTOGRAPHIC THEORY"
852 Encryption of a message proceeds as follows.
854 Emit a header packet containing the key-ids for the key-encapsulation
855 key, and signature key if any.
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.
861 Hash the shared secret. Use the KDF to produce a pseudorandom keystream
862 of indefinite length.
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.
867 If we're signing the message then extract 1024 bytes from the keystream,
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.
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
874 IV, ciphertext, and a MAC tag over the ciphertext and a sequence number.
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
881 That's it. Nothing terribly controversial, really.
889 Mark Wooding, <mdw@distorted.org.uk>
~mdw / catacomb / blob