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.
122 .SS "Key-encapsulation keys"
123 (Key encapsulation is a means of transmitting a short, known, random
124 secret to a recipient. It differs from encryption in technical ways
125 which are largely uninteresting at this point.)
137 attribute is present on the key, then it must have this form; otherwise,
138 the key's type must have the form
141 Algorithm selections are taken from appropriately-named attributes, or,
142 failing that, from the
145 The key-encapsulation mechanism is chosen according to the setting of
149 for a list of supported KEMs.
152 This is Shoup's RSA-KEM (formerly Simple RSA); see
154 A proposal for an ISO standard for public key encryption (version 2.0)
156 .BR http://eprint.iacr.org/2000/060/ .
166 This is standard Diffie-Hellman key exchange, hashing the resulting
167 shared secret to form the key, as used in, e.g., DLIES (P1363a).
172 command, preferably with the
174 options, to generate the key.
177 This is the elliptic-curve analogue of
182 command to generate the key.
184 As well as the KEM itself, a number of supporting algorithms are used.
185 These are taken from appropriately named attributes on the key or,
186 failing that, derived from other attributes as described below.
189 This is the symmetric encryption algorithm used for bulk data
190 encryption. If there is no
196 is used; if that it absent, then the default of
199 .B catcrypt show cipher
200 for a list of supported symmetric encryption algorithms.
203 This is the hash function used to distil entropy from the shared secret
204 constructed by the raw KEM. If there is no
209 .I kemalgspec is used; if that is absent then the default of
212 .B catcrypt show hash
213 for a list of supported symmetric encryption algorithms.
216 This is the message authentication algorithm used during bulk data
217 encryption to ensure integrity of the encrypted message and defend
218 against chosen-ciphertext attacks. If there is no
222 is chosen as a default. Run
224 for a list of supported message authentication algorithms.
227 This is the key derivation function used to stretch the hashed shared
228 secret to a sufficient length to select symmetric encryption and
229 authentication keys, initialization vectors and other necessary
230 pseudorandom quantities. If there is no
234 is chosen as a default. Run
236 for a list of supported key derivation functions.
238 Not all supported functions have the required security features: don't
239 override the default choice unless you know what you're doing.
249 attribute is present on the key, then it must have this form; otherwise,
250 the key's type must have the form
253 Algorithm selections are taken from appropriately-named attributes, or,
254 failing that, from the
257 The signature algorithm is chosen according to the setting of
261 for a list of supported signature algorithms.
264 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
265 RFC3447; the difference is that the hash is left bare rather than being
266 wrapped in a DER-encoded
268 structure. This doesn't affect security since the key can only be used
269 with the one hash function anyway, and dropping the DER wrapping permits
270 rapid adoption of new hash functions. Regardless, use of this algorithm
271 is not recommended, since the padding method has been shown vulnerable
281 This is the RSASSA-PSS algorithm described in RFC3447. It is the
282 preferred RSA-based signature scheme. Use the
291 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
300 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
310 This is the revised KCDSA (Korean Certificate-based Digital Signature
311 Algorithm) described in
312 .I The Revised Version of KCDSA
313 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
325 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
334 As well as the signature algorithm itself, a hash function is used.
335 This is taken from the
337 attribute on the key, or, failing that, from the
341 or, if that is absent, determined by the signature algorithm as follows.
349 the default hash function is
356 the default hash function is
360 .B catcrypt show hash
361 for a list of supported hash functions.
363 Two encodings for the ciphertext are supported.
366 The raw format, which has the benefit of being smaller, but needs to be
367 attached to mail messages and generally handled with care.
370 PEM-encapsulated Base-64 encoded text. This format can be included
371 directly in email and picked out again automatically; but there is a
372 4-to-3 data expansion as a result.
373 .SH "COMMAND REFERENCE"
377 command behaves exactly as the
379 option. With no arguments, it shows an overview of
381 options; with arguments, it describes the named subcommands.
385 command prints various lists of tokens understood by
387 With no arguments, it prints all of the lists; with arguments, it prints
388 just the named lists, in order. The recognized lists can be enumerated
393 command. The lists are as follows.
396 The lists which can be enumerated by the
401 The key-encapsulation algorithms which can be used in a
402 key-encapsulation key's
407 The symmetric encryption algorithms which can be used in a
408 key-encapsulation key's
413 The message authentication algorithms which can be used in a
414 key-encapsulation key's
419 The signature algorithms which can be used in a signing key's
424 The hash functions which can be used in a key's
429 The encodings which can be applied to encrypted messages; see
435 command encrypts a file and writes out the appropriately-encoded
436 ciphertext. By default, it reads from standard input and writes to
437 standard output. If a filename argument is given, this file is read
438 instead (as binary data).
440 The following options are recognized.
443 Produce ASCII-armoured output. This is equivalent to specifying
449 .BI "\-f, \-\-format " format
450 Produce output encoded according to
453 .BI "\-k, \-\-key " tag
454 Use the key-encapsulation key named
456 in the current keyring; the default key is
459 .BI "\-s, \-\-sign-key " tag
460 Use the signature key named
462 in the current keyring; the default is not to sign the ciphertext.
464 .BI "\-o, \-\-ouptut " file
467 rather than to standard output.
471 command decrypts a ciphertext and writes out the plaintext. By default,
472 it reads from standard input and writes to standard output. If a
473 filename argument is given, this file is read instead.
475 The following options are recognized.
478 Read ASCII-armoured output. This is equivalent to specifying
484 .BI "\-f, \-\-format " format
485 Read input encoded according to
488 .B "\-v, \-\-verbose"
489 Produce more verbose messages. See below for the messages produced
490 during decryption. The default verbosity level is 1. (Currently this
491 is the most verbose setting. This might not be the case always.)
494 Produce fewer messages.
496 .BI "\-o, \-\-output " file
499 instead of to standard output. The file is written in binary mode.
500 Fixing line-end conventions is your problem; there are lots of good
501 tools for dealing with it.
503 Output is written to standard output in a machine-readable format.
504 Major problems cause the program to write a diagnostic to standard error
505 and exit nonzero as usual. The quantity of output varies depending on
506 the verbosity level and whether the plaintext is also being written to
507 standard output. Output lines begin with a keyword.:
510 An error prevented decryption. The program will exit nonzero.
514 encountered a situation which may or may not invalidate the decryption.
517 Decryption was successful. This is only produced if main output is
518 being sent somewhere other than standard output.
521 The plaintext follows, starting just after the next newline character or
522 sequence. This is only produced if main output is being sent to
523 standard output. If anything goes wrong, a
525 message is printed, preceded and followed by a newline, and the program
529 Any other information.
531 The information written at the various verbosity levels is as follows.
533 No output. Watch the exit status.
538 All output written has been checked for authenticity. However, since
539 the input is chunked, a chunk will be checked and written before the
540 authenticity of following chunks is established. Don't rely on the
541 output being complete until
545 and/or exits successfully.
549 command encodes an input file according to one of the encodings
552 The input is read from the
554 given on the command line, or from standard input if none is specified.
555 Options provided are:
557 .BI "\-f, \-\-format " format
562 for a list of encoding formats.
564 .BI "\-b, \-\-boundary " label
565 Set the PEM boundary string to
567 i.e., assuming we're encoding in PEM format, the output will have
568 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
570 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
571 at the bottom. The default
576 .BI "\-o, \-\-output " file
579 instead of to standard output.
583 command decodes an input file encoded according to one of the encodings
586 The input is read from the
588 given on the command line, or from standard input if none is specified.
589 Options provided are:
591 .BI "\-f, \-\-format " format
596 for a list of encoding formats.
598 .BI "\-b, \-\-boundary " label
599 Set the PEM boundary string to
601 i.e., assuming we're encoding in PEM format, start processing input
603 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
605 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
606 lines. Without this option,
608 will start reading at the first plausible boundary string, and continue
609 processing until it reaches the matching end boundary.
611 .BI "\-o, \-\-output " file
614 instead of to standard output.
615 .SH "SECURITY PROPERTIES"
616 Assuming the security of the underlying primitive algorithms, the
617 following security properties of the ciphertext hold.
619 An adversary given the public key-encapsulation key and capable of
620 requesting encryption of arbitrary plaintexts of his own devising is
621 unable to decide whether he is given ciphertexts corresponding to his
622 chosen plaintexts or random plaintexts of the same length. This holds
623 even if the adversary is permitted to request decryption of any
624 ciphertext other than one produced as a result of an encryption request.
625 This property is called
628 An adversary given the public key-encapsulation and verification keys,
629 and capable of requesting encryption of arbitrary plaintext of his own
630 devising is unable to produce a new ciphertext which will be accepted as
631 genuine. This property is called
634 An adversary given the public key-encapsulation and verification keys,
635 and capable of requesting encryption of arbitrary plaintext of his own
636 devising is unable to decide whether the ciphertexts he is given are
637 correctly signed. This property doesn't seem to have a name.
639 Not all is rosy. If you leak intermediate values during decryption then
640 an adversary can construct a new correctly-signed message. Don't do
641 that, then \(en leaking intermediate values often voids security
642 warranties. But it does avoid the usual problem with separate signing
643 and encryption that a careful leak by the recipient can produce evidence
644 that you signed some incriminating message.
645 .SH "CRYPTOGRAPHIC THEORY"
646 Encryption of a message proceeds as follows.
648 Emit a header packet containing the key-ids for the key-encapsulation
649 key, and signature key if any.
651 Use the KEM to produce a public value and a shared secret the recipient
652 will be able to extract from the public value using his private key.
653 Emit a packet containing the public value.
655 Hash the shared secret. Use the KDF to produce a pseudorandom keystream
656 of indefinite length.
658 Use the first bits of the keystream to key a symmetric encryption
659 scheme; use the next bits to key a message authentication code.
661 If we're signing the message then extract 1024 bytes from the keystream,
662 sign them, and emit a packet containing the signature. The signature
663 packet doesn't contain the signed message, just the signature.
665 Split the message into blocks. For each block, pick a random IV from
666 the keystream, encrypt the block and emit a packet containing the
667 IV, ciphertext and a MAC tag.
669 That's it. Nothing terribly controversial, really.
676 Mark Wooding, <mdw@nsict.org>
projects / u / mdw / catacomb / blob