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
185 command to generate the key.
187 As well as the KEM itself, a number of supporting algorithms are used.
188 These are taken from appropriately named attributes on the key or,
189 failing that, derived from other attributes as described below.
192 This is the symmetric encryption algorithm used for bulk data
193 encryption. If there is no
199 is used; if that it absent, then the default of
202 .B catcrypt show cipher
203 for a list of supported symmetric encryption algorithms.
206 This is the hash function used to distil entropy from the shared secret
207 constructed by the raw KEM. If there is no
212 .I kemalgspec is used; if that is absent then the default of
215 .B catcrypt show hash
216 for a list of supported symmetric encryption algorithms.
219 This is the message authentication algorithm used during bulk data
220 encryption to ensure integrity of the encrypted message and defend
221 against chosen-ciphertext attacks. If there is no
225 is chosen as a default. Run
227 for a list of supported message authentication algorithms.
230 This is the key derivation function used to stretch the hashed shared
231 secret to a sufficient length to select symmetric encryption and
232 authentication keys, initialization vectors and other necessary
233 pseudorandom quantities. If there is no
237 is chosen as a default. Run
239 for a list of supported key derivation functions.
241 Not all supported functions have the required security features: don't
242 override the default choice unless you know what you're doing.
252 attribute is present on the key, then it must have this form; otherwise,
253 the key's type must have the form
256 Algorithm selections are taken from appropriately-named attributes, or,
257 failing that, from the
260 The signature algorithm is chosen according to the setting of
264 for a list of supported signature algorithms.
267 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
268 RFC3447; the difference is that the hash is left bare rather than being
269 wrapped in a DER-encoded
271 structure. This doesn't affect security since the key can only be used
272 with the one hash function anyway, and dropping the DER wrapping permits
273 rapid adoption of new hash functions. Regardless, use of this algorithm
274 is not recommended, since the padding method has been shown vulnerable
284 This is the RSASSA-PSS algorithm described in RFC3447. It is the
285 preferred RSA-based signature scheme. Use the
294 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
303 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
313 This is the revised KCDSA (Korean Certificate-based Digital Signature
314 Algorithm) described in
315 .I The Revised Version of KCDSA
316 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
328 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
337 As well as the signature algorithm itself, a hash function is used.
338 This is taken from the
340 attribute on the key, or, failing that, from the
344 or, if that is absent, determined by the signature algorithm as follows.
352 the default hash function is
359 the default hash function is
363 .B catcrypt show hash
364 for a list of supported hash functions.
366 Two encodings for the ciphertext are supported.
369 The raw format, which has the benefit of being smaller, but needs to be
370 attached to mail messages and generally handled with care.
373 PEM-encapsulated Base-64 encoded text. This format can be included
374 directly in email and picked out again automatically; but there is a
375 4-to-3 data expansion as a result.
376 .SH "COMMAND REFERENCE"
380 command behaves exactly as the
382 option. With no arguments, it shows an overview of
384 options; with arguments, it describes the named subcommands.
388 command prints various lists of tokens understood by
390 With no arguments, it prints all of the lists; with arguments, it prints
391 just the named lists, in order. The recognized lists can be enumerated
396 command. The lists are as follows.
399 The lists which can be enumerated by the
404 The key-encapsulation algorithms which can be used in a
405 key-encapsulation key's
410 The symmetric encryption algorithms which can be used in a
411 key-encapsulation key's
416 The message authentication algorithms which can be used in a
417 key-encapsulation key's
422 The signature algorithms which can be used in a signing key's
427 The hash functions which can be used in a key's
432 The encodings which can be applied to encrypted messages; see
438 command encrypts a file and writes out the appropriately-encoded
439 ciphertext. By default, it reads from standard input and writes to
440 standard output. If a filename argument is given, this file is read
441 instead (as binary data).
443 The following options are recognized.
446 Produce ASCII-armoured output. This is equivalent to specifying
452 .BI "\-f, \-\-format " format
453 Produce output encoded according to
456 .BI "\-k, \-\-key " tag
457 Use the key-encapsulation key named
459 in the current keyring; the default key is
462 .BI "\-s, \-\-sign-key " tag
463 Use the signature key named
465 in the current keyring; the default is not to sign the ciphertext.
467 .BI "\-o, \-\-ouptut " file
470 rather than to standard output.
474 command decrypts a ciphertext and writes out the plaintext. By default,
475 it reads from standard input and writes to standard output. If a
476 filename argument is given, this file is read instead.
478 The following options are recognized.
481 Read ASCII-armoured input. This is equivalent to specifying
488 Buffer plaintext data until we're sure we've got it all. This is forced
489 on if output is to stdout, but is always available as an option.
491 .BI "\-f, \-\-format " format
492 Read input encoded according to
495 .B "\-v, \-\-verbose"
496 Produce more verbose messages. See below for the messages produced
497 during decryption. The default verbosity level is 1. (Currently this
498 is the most verbose setting. This might not be the case always.)
501 Produce fewer messages.
503 .BI "\-o, \-\-output " file
506 instead of to standard output. The file is written in binary mode.
507 Fixing line-end conventions is your problem; there are lots of good
508 tools for dealing with it.
510 Output is written to standard output in a machine-readable format.
511 Major problems cause the program to write a diagnostic to standard error
512 and exit nonzero as usual. The quantity of output varies depending on
513 the verbosity level and whether the plaintext is also being written to
514 standard output. Output lines begin with a keyword:
517 An error prevented decryption. The program will exit nonzero.
521 encountered a situation which may or may not invalidate the decryption.
524 Decryption was successful. This is only produced if main output is
525 being sent somewhere other than standard output.
528 The plaintext follows, starting just after the next newline character or
529 sequence. This is only produced if main output is being sent to
533 Any other information.
535 The information written at the various verbosity levels is as follows.
537 No output. Watch the exit status.
542 All output written has been checked for authenticity. However, output
543 can fail madway through for many reasons, and the resulting message may
544 therefore be truncated. Don't rely on the output being complete until
551 command encodes an input file according to one of the encodings
554 The input is read from the
556 given on the command line, or from standard input if none is specified.
557 Options provided are:
559 .BI "\-f, \-\-format " format
564 for a list of encoding formats.
566 .BI "\-b, \-\-boundary " label
567 Set the PEM boundary string to
569 i.e., assuming we're encoding in PEM format, the output will have
570 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
572 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
573 at the bottom. The default
578 .BI "\-o, \-\-output " file
581 instead of to standard output.
585 command decodes an input file encoded according to one of the encodings
588 The input is read from the
590 given on the command line, or from standard input if none is specified.
591 Options provided are:
593 .BI "\-f, \-\-format " format
598 for a list of encoding formats.
600 .BI "\-b, \-\-boundary " label
601 Set the PEM boundary string to
603 i.e., assuming we're encoding in PEM format, start processing input
605 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
607 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
608 lines. Without this option,
610 will start reading at the first plausible boundary string, and continue
611 processing until it reaches the matching end boundary.
613 .BI "\-o, \-\-output " file
616 instead of to standard output.
617 .SH "SECURITY PROPERTIES"
618 Assuming the security of the underlying primitive algorithms, the
619 following security properties of the ciphertext hold.
621 An adversary given the public key-encapsulation key and capable of
622 requesting encryption of arbitrary plaintexts of his own devising is
623 unable to decide whether he is given ciphertexts corresponding to his
624 chosen plaintexts or random plaintexts of the same length. This holds
625 even if the adversary is permitted to request decryption of any
626 ciphertext other than one produced as a result of an encryption request.
627 This property is called
630 An adversary given the public key-encapsulation and verification keys,
631 and capable of requesting encryption of arbitrary plaintext of his own
632 devising is unable to produce a new ciphertext which will be accepted as
633 genuine. This property is called
636 An adversary given the public key-encapsulation and verification keys,
637 and capable of requesting encryption of arbitrary plaintext of his own
638 devising is unable to decide whether the ciphertexts he is given are
639 correctly signed. This property doesn't seem to have a name.
641 Not all is rosy. If you leak intermediate values during decryption then
642 an adversary can construct a new correctly-signed message. Don't do
643 that, then \(en leaking intermediate values often voids security
644 warranties. But it does avoid the usual problem with separate signing
645 and encryption that a careful leak by the recipient can produce evidence
646 that you signed some incriminating message.
647 .SH "CRYPTOGRAPHIC THEORY"
648 Encryption of a message proceeds as follows.
650 Emit a header packet containing the key-ids for the key-encapsulation
651 key, and signature key if any.
653 Use the KEM to produce a public value and a shared secret the recipient
654 will be able to extract from the public value using his private key.
655 Emit a packet containing the public value.
657 Hash the shared secret. Use the KDF to produce a pseudorandom keystream
658 of indefinite length.
660 Use the first bits of the keystream to key a symmetric encryption
661 scheme; use the next bits to key a message authentication code.
663 If we're signing the message then extract 1024 bytes from the keystream,
664 sign them, and emit a packet containing the signature. The signature
665 packet doesn't contain the signed message, just the signature.
667 Split the message into blocks. For each block, pick a random IV from
668 the keystream, encrypt the block and emit a packet containing the
669 IV, ciphertext, and a MAC tag over the ciphertext and a sequence number.
671 The last chunk is the encryption of an empty plaintext block. No
672 previous plaintext block is empty. This lets us determine the
673 difference between a complete file and one that's been maliciously
676 That's it. Nothing terribly controversial, really.
684 Mark Wooding, <mdw@nsict.org>
projects / u / mdw / catacomb / blob