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.
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.
193 This is the symmetric encryption algorithm used for bulk data
194 encryption. If there is no
200 is used; if that it absent, then the default of
203 .B catcrypt show cipher
204 for a list of supported symmetric encryption algorithms.
207 This is the hash function used to distil entropy from the shared secret
208 constructed by the raw KEM. If there is no
214 is used; if that is absent then the default of
217 .B catcrypt show hash
218 for a list of supported symmetric encryption algorithms.
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
227 is chosen as a default. Run
229 for a list of supported message authentication algorithms.
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
239 is chosen as a default. Run
241 for a list of supported key derivation functions.
243 Not all supported functions have the required security features: don't
244 override the default choice unless you know what you're doing.
254 attribute is present on the key, then it must have this form; otherwise,
255 the key's type must have the form
258 Algorithm selections are taken from appropriately-named attributes, or,
259 failing that, from the
262 The signature algorithm is chosen according to the setting of
266 for a list of supported signature algorithms.
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
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
286 This is the RSASSA-PSS algorithm described in RFC3447. It is the
287 preferred RSA-based signature scheme. Use the
296 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
305 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
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 ).
330 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
339 As well as the signature algorithm itself, a hash function is used.
340 This is taken from the
342 attribute on the key, or, failing that, from the
346 or, if that is absent, determined by the signature algorithm as follows.
354 the default hash function is
361 the default hash function is
365 .B catcrypt show hash
366 for a list of supported hash functions.
368 Two encodings for the ciphertext are supported.
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.
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"
382 command behaves exactly as the
384 option. With no arguments, it shows an overview of
386 options; with arguments, it describes the named subcommands.
390 command prints various lists of tokens understood by
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
398 command. The lists are as follows.
401 The lists which can be enumerated by the
406 The key-encapsulation algorithms which can be used in a
407 key-encapsulation key's
412 The symmetric encryption algorithms which can be used in a
413 key-encapsulation key's
418 The message authentication algorithms which can be used in a
419 key-encapsulation key's
424 The signature algorithms which can be used in a signing key's
429 The hash functions which can be used in a key's
434 The encodings which can be applied to encrypted messages; see
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).
445 The following options are recognized.
448 Produce ASCII-armoured output. This is equivalent to specifying
454 .BI "\-f, \-\-format " format
455 Produce output encoded according to
458 .BI "\-k, \-\-key " tag
459 Use the key-encapsulation key named
461 in the current keyring; the default key is
464 .BI "\-s, \-\-sign-key " tag
465 Use the signature key named
467 in the current keyring; the default is not to sign the ciphertext.
469 .BI "\-o, \-\-ouptut " file
472 rather than to standard output.
474 .B "\-C, \-\-nocheck"
475 Don't check the public key for validity. This makes encryption go much
476 faster, but at the risk of using a duff key.
480 command decrypts a ciphertext and writes out the plaintext. By default,
481 it reads from standard input and writes to standard output. If a
482 filename argument is given, this file is read instead.
484 The following options are recognized.
487 Read ASCII-armoured input. This is equivalent to specifying
494 Buffer plaintext data until we're sure we've got it all. This is forced
495 on if output is to stdout, but is always available as an option.
497 .BI "\-f, \-\-format " format
498 Read input encoded according to
501 .B "\-v, \-\-verbose"
502 Produce more verbose messages. See below for the messages produced
503 during decryption. The default verbosity level is 1. (Currently this
504 is the most verbose setting. This might not be the case always.)
507 Produce fewer messages.
509 .BI "\-o, \-\-output " file
512 instead of to standard output. The file is written in binary mode.
513 Fixing line-end conventions is your problem; there are lots of good
514 tools for dealing with it.
516 .B "\-C, \-\-nocheck"
517 Don't check the private key for validity. This makes decryption go much
518 faster, but at the risk of using a duff key, and possibly leaking
519 information about the private key.
521 Output is written to standard output in a machine-readable format.
522 Major problems cause the program to write a diagnostic to standard error
523 and exit nonzero as usual. The quantity of output varies depending on
524 the verbosity level and whether the plaintext is also being written to
525 standard output. Output lines begin with a keyword:
528 An error prevented decryption. The program will exit nonzero.
532 encountered a situation which may or may not invalidate the decryption.
535 Decryption was successful. This is only produced if main output is
536 being sent somewhere other than standard output.
539 The plaintext follows, starting just after the next newline character or
540 sequence. This is only produced if main output is also being sent to
544 Any other information.
546 The information written at the various verbosity levels is as follows.
548 No output. Watch the exit status.
553 All output written has been checked for authenticity. However, output
554 can fail madway through for many reasons, and the resulting message may
555 therefore be truncated. Don't rely on the output being complete until
563 command encodes an input file according to one of the encodings
566 The input is read from the
568 given on the command line, or from standard input if none is specified.
569 Options provided are:
571 .BI "\-f, \-\-format " format
576 for a list of encoding formats.
578 .BI "\-b, \-\-boundary " label
579 Set the PEM boundary string to
581 i.e., assuming we're encoding in PEM format, the output will have
582 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
584 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
585 at the bottom. The default
590 .BI "\-o, \-\-output " file
593 instead of to standard output.
597 command decodes an input file encoded according to one of the encodings
600 The input is read from the
602 given on the command line, or from standard input if none is specified.
603 Options provided are:
605 .BI "\-f, \-\-format " format
610 for a list of encoding formats.
612 .BI "\-b, \-\-boundary " label
613 Set the PEM boundary string to
615 i.e., assuming we're encoding in PEM format, start processing input
617 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
619 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
620 lines. Without this option,
622 will start reading at the first plausible boundary string, and continue
623 processing until it reaches the matching end boundary.
625 .BI "\-o, \-\-output " file
628 instead of to standard output.
629 .SH "SECURITY PROPERTIES"
630 Assuming the security of the underlying primitive algorithms, the
631 following security properties of the ciphertext hold.
633 An adversary given the public key-encapsulation key and capable of
634 requesting encryption of arbitrary plaintexts of his own devising is
635 unable to decide whether he is given ciphertexts corresponding to his
636 chosen plaintexts or random plaintexts of the same length. This holds
637 even if the adversary is permitted to request decryption of any
638 ciphertext other than one produced as a result of an encryption request.
639 This property is called
642 An adversary given the public key-encapsulation and verification keys,
643 and capable of requesting encryption of arbitrary plaintext of his own
644 devising is unable to produce a new ciphertext which will be accepted as
645 genuine. This property is called
648 An adversary given the public key-encapsulation and verification keys,
649 and capable of requesting encryption of arbitrary plaintext of his own
650 devising is unable to decide whether the ciphertexts he is given are
651 correctly signed. This property doesn't seem to have a name.
653 Not all is rosy. If you leak intermediate values during decryption then
654 an adversary can construct a new correctly-signed message. Don't do
655 that, then \(en leaking intermediate values often voids security
656 warranties. But it does avoid the usual problem with separate signing
657 and encryption that a careful leak by the recipient can produce evidence
658 that you signed some incriminating message.
664 provide `non-repudiation' in any useful way. This is deliberate: the
665 purpose of signing is to convince the recipient of the sender's
666 identity, rather than to allow the recipient to persuade anyone else.
667 Indeed, given an encrypted and signed message, the recipient can
668 straightforwardly construct a new message, apparently from the same
669 sender, and whose signature still verifies, but with arbitrarily chosen
671 .SH "CRYPTOGRAPHIC THEORY"
672 Encryption of a message proceeds as follows.
674 Emit a header packet containing the key-ids for the key-encapsulation
675 key, and signature key if any.
677 Use the KEM to produce a public value and a shared secret the recipient
678 will be able to extract from the public value using his private key.
679 Emit a packet containing the public value.
681 Hash the shared secret. Use the KDF to produce a pseudorandom keystream
682 of indefinite length.
684 Use the first bits of the keystream to key a symmetric encryption
685 scheme; use the next bits to key a message authentication code.
687 If we're signing the message then extract 1024 bytes from the keystream,
688 sign the header and public value, and the keystream bytes; emit a packet
689 containing the signature. The signature packet doesn't contain the
690 signed message, just the signature.
692 Split the message into blocks. For each block, pick a random IV from
693 the keystream, encrypt the block and emit a packet containing the
694 IV, ciphertext, and a MAC tag over the ciphertext and a sequence number.
696 The last chunk is the encryption of an empty plaintext block. No
697 previous plaintext block is empty. This lets us determine the
698 difference between a complete file and one that's been maliciously
701 That's it. Nothing terribly controversial, really.
709 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob