X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/ba6e6b64033b1f9de49feccb5c9cd438354481f7..0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a:/progs/catcrypt.1

diff --git a/progs/catcrypt.1 b/progs/catcrypt.1
new file mode 100644
index 0000000..6bace86
--- /dev/null
+++ b/progs/catcrypt.1
@@ -0,0 +1,748 @@
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.ie t \{\
+.  if \n(.g \{\
+.    fam P
+.  \}
+.\}
+.de hP
+.IP
+.ft B
+\h'-\w'\\$1\ 'u'\\$1\ \c
+.ft P
+..
+.ie t .ds o \(bu
+.el .ds o o
+.TH catcrypt 1 "30 September 2004" "Straylight/Edgeware" "Catacomb cryptographic library"
+.SH NAME
+catcrypt \- encrypt and decrypt messages
+.SH SYNOPSIS
+.B catcrypt
+.RB [ \-k
+.IR keyring ]
+.I command
+.PP
+where
+.I command
+is one of:
+.PP
+.B help
+.RI [ command ...]
+.br
+.B show
+.RI [ item ...]
+.br
+.B encrypt
+.RB [ \-apC ]
+.RB [ \-k
+.IR tag ]
+.RB [ \-f
+.IR format ]
+.RB [ \-o
+.IR output ]
+.RI [ file ]
+.br
+.B decrypt
+.RB [ \-apqvC ]
+.RB [ \-f
+.IR format ]
+.RB [ \-o
+.IR output ]
+.RI [ file ]
+.br
+.B encode
+.RB [ \-p ]
+.RB [ \-f
+.IR format ]
+.RB [ \-b
+.IR boundary ]
+.RB [ \-o
+.IR output ]
+.RI [ file ]
+.br
+.B decode
+.RB [ \-p ]
+.RB [ \-f
+.IR format ]
+.RB [ \-b
+.IR boundary ]
+.RB [ \-o
+.IR output ]
+.RI [ file ]
+.SH "DESCRIPTION"
+The
+.B catcrypt
+command encrypts and decrypts messages.  It also works as a simple PEM
+encoder and decoder.  It provides a number of subcommands, by which the
+various operations may be carried out.
+.SS "Global options"
+Before the command name,
+.I "global options"
+may be given.  The following global options are supported:
+.TP
+.BR "\-h, \-\-help " [ \fIcommand ...]
+Writes a brief summary of
+.BR catcrypt 's
+various options to standard output, and returns a successful exit
+status.  With command names, gives help on those commands.
+.TP
+.B "\-v, \-\-version"
+Writes the program's version number to standard output, and returns a
+successful exit status.
+.TP
+.B "\-u, \-\-usage"
+Writes a very terse command line summary to standard output, and returns
+a successful exit status.
+.TP
+.BI "\-k, \-\-keyring " file
+Names the keyring file which
+.B key
+is to process.  The default keyring, used if this option doesn't specify
+one, is the file named
+.B keyring
+in the current directory.  See
+.BR key (1)
+and
+.BR keyring (5)
+for more details about keyring files.
+.SH "KEY SETUP"
+Algorithms to be used with a particular key are described by attributes
+on the key, or its type.  The
+.B catcrypt
+command deals with both signing and key-encapsulation keys.  (Note that
+.B catcrypt
+uses signing keys in the same way as
+.BR catsign (1).)
+.SS "Key-encapsulation keys"
+(Key encapsulation is a means of transmitting a short, known, random
+secret to a recipient.  It differs from encryption in technical ways
+which are largely uninteresting at this point.)
+.PP
+A
+.I kemalgspec
+has the syntax
+.IR kem \c
+.RB [ / \c
+.IR cipher \c
+.RB [ / \c
+.IR hash ]].
+If a
+.B kem
+attribute is present on the key, then it must have this form; otherwise,
+the key's type must have the form
+.BR cckem- \c
+.IR kemalgspec .
+Algorithm selections are taken from appropriately-named attributes, or,
+failing that, from the
+.IR kemalgspec .
+.PP
+The key-encapsulation mechanism is chosen according to the setting of
+.I kem
+as follows.  Run
+.B catcrypt show kem
+for a list of supported KEMs.
+.TP
+.B rsa
+This is Shoup's RSA-KEM (formerly Simple RSA); see
+.I
+A proposal for an ISO standard for public key encryption (version 2.0)
+available at
+.BR http://eprint.iacr.org/2000/060/ .
+Use the
+.B rsa
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B dh
+This is standard Diffie-Hellman key exchange, hashing the resulting
+shared secret to form the key, as used in, e.g., DLIES (P1363a).
+Use the
+.B dh
+algorithm of the
+.B key add
+command, preferably with the
+.B \-LS
+options, to generate the key.
+.TP
+.B ec
+This is the elliptic-curve analogue of
+.BR dh .
+Use the
+.B ec
+algorithm of the
+.BR key (1))
+command to generate the key.
+.TP
+.B symm
+This is a simple symmetric encapsulation scheme.  It works by hashing a
+binary key with a randomly-generated salt.  Use the
+.B binary
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.PP
+As well as the KEM itself, a number of supporting algorithms are used.
+These are taken from appropriately named attributes on the key or,
+failing that, derived from other attributes as described below.
+.TP
+.B cipher
+This is the symmetric encryption algorithm used for bulk data
+encryption.  If there is no
+.B cipher
+attribute then the
+.I cipher
+in the
+.I kemalgspec
+is used; if that it absent, then the default of
+.B blowfish-cbc
+is used.  Run
+.B catcrypt show cipher
+for a list of supported symmetric encryption algorithms.
+.TP
+.B hash
+This is the hash function used to distil entropy from the shared secret
+constructed by the raw KEM.  If there is no
+.B hash
+attribute then the
+.I hash
+in the
+.I kemalgspec
+is used; if that is absent then the default of
+.B rmd160
+is used.  Run
+.B catcrypt show hash
+for a list of supported symmetric encryption algorithms.
+.TP
+.B mac
+This is the message authentication algorithm used during bulk data
+encryption to ensure integrity of the encrypted message and defend
+against chosen-ciphertext attacks.  If there is no
+.B mac
+attribute then
+.IB hash -hmac
+is chosen as a default.  Run
+.B catcrypt show mac
+for a list of supported message authentication algorithms.
+.TP
+.B kdf
+This is the key derivation function used to stretch the hashed shared
+secret to a sufficient length to select symmetric encryption and
+authentication keys, initialization vectors and other necessary
+pseudorandom quantities.  If there is no
+.B kdf
+attribute then
+.IB hash -mgf
+is chosen as a default.  Run
+.B catcrypt show kdf
+for a list of supported key derivation functions.
+.B Caution!
+Not all supported functions have the required security features: don't
+override the default choice unless you know what you're doing.
+.SS "Signing keys"
+A
+.I sigalgspec
+has the form
+.IR sig \c
+.RB [ / \c
+.IR hash ].
+If a
+.B sig
+attribute is present on the key, then it must have this form; otherwise,
+the key's type must have the form
+.BI ccsig- \c
+.IR sigalgspec .
+Algorithm selections are taken from appropriately-named attributes, or,
+failing that, from the
+.IR sigalgspec .
+.PP
+The signature algorithm is chosen according to the setting of
+.I sig
+as follows.  Run
+.B catcrypt show sig
+for a list of supported signature algorithms.
+.TP
+.B rsapkcs1
+This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
+RFC3447; the difference is that the hash is left bare rather than being
+wrapped in a DER-encoded
+.B DigestInfo
+structure.  This doesn't affect security since the key can only be used
+with the one hash function anyway, and dropping the DER wrapping permits
+rapid adoption of new hash functions.  Regardless, use of this algorithm
+is not recommended, since the padding method has been shown vulnerable
+to attack.  Use the
+.B rsa
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B rsapss
+This is the RSASSA-PSS algorithm described in RFC3447.  It is the
+preferred RSA-based signature scheme.  Use the
+.B rsa
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B dsa
+This is the DSA algorithm described in FIPS180-1 and FIPS180-2.  Use the
+.B dsa
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B ecdsa
+This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2.  Use
+the
+.B ec
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B kcdsa
+This is the revised KCDSA (Korean Certificate-based Digital Signature
+Algorithm) described in
+.I The Revised Version of KCDSA
+.RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
+Use the
+.B dh
+algorithm of the
+.B key add
+command with the
+.B \-LS
+options (see
+.BR key (1))
+to generate the key.
+.TP
+.B eckcdsa
+This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
+Use the
+.B ec
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B mac
+This uses a symmetric message-authentication algorithm rather than a
+digital signature.  The precise message-authentication scheme used is
+determined by the
+.B mac
+attribute on the key, which defaults to
+.IB hash -hmac
+if unspecified.  Use the
+.B binary
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.PP
+As well as the signature algorithm itself, a hash function is used.
+This is taken from the
+.B hash
+attribute on the key, or, failing that, from the
+.I hash
+specified in the
+.IR sigalgspec ,
+or, if that is absent, determined by the signature algorithm as follows.
+.hP \*o
+For
+.BR rsapkcs1 ,
+.BR rsapss ,
+.BR dsa ,
+and
+.BR ecdsa ,
+the default hash function is
+.BR sha .
+.hP \*o
+For
+.BR kcdsa
+and
+.BR eckcdsa ,
+the default hash function is
+.BR has160 .
+.PP
+Run
+.B catcrypt show hash
+for a list of supported hash functions.
+.SH "ENCODINGS"
+Two encodings for the ciphertext are supported.
+.TP
+.B binary
+The raw format, which has the benefit of being smaller, but needs to be
+attached to mail messages and generally handled with care.
+.TP
+.B pem
+PEM-encapsulated Base-64 encoded text.  This format can be included
+directly in email and picked out again automatically; but there is a
+4-to-3 data expansion as a result.
+.SH "COMMAND REFERENCE"
+.SS help
+The
+.B help
+command behaves exactly as the
+.B \-\-help
+option.  With no arguments, it shows an overview of
+.BR catcrypt 's
+options; with arguments, it describes the named subcommands.
+.SS show
+The
+.B show
+command prints various lists of tokens understood by
+.BR catcrypt .
+With no arguments, it prints all of the lists; with arguments, it prints
+just the named lists, in order.  The recognized lists can be enumerated
+using the
+.VS
+catcrypt show list
+.VE
+command.  The lists are as follows.
+.TP
+.B list
+The lists which can be enumerated by the
+.B show
+command.
+.TP
+.B kem
+The key-encapsulation algorithms which can be used in a
+key-encapsulation key's
+.B kem
+attribute.
+.TP
+.B cipher
+The symmetric encryption algorithms which can be used in a
+key-encapsulation key's
+.B cipher
+attribute.
+.TP
+.B mac
+The message authentication algorithms which can be used in a
+key-encapsulation key's
+.B mac
+attribute.
+.TP
+.B sig
+The signature algorithms which can be used in a signing key's
+.B sig
+attribute.
+.TP
+.B hash
+The hash functions which can be used in a key's
+.B hash
+attribute.
+.TP
+.B enc
+The encodings which can be applied to encrypted messages; see
+.B ENCODINGS
+above.
+.SS encrypt
+The
+.B encrypt
+command encrypts a file and writes out the appropriately-encoded
+ciphertext.  By default, it reads from standard input and writes to
+standard output.  If a filename argument is given, this file is read
+instead (as binary data).
+.PP
+The following options are recognized.
+.TP
+.B "\-a, \-\-armour"
+Produce ASCII-armoured output.  This is equivalent to specifying
+.BR "\-f pem" .
+The variant spelling
+.B "\-\-armor"
+is also accepted.
+.TP
+.BI "\-f, \-\-format " format
+Produce output encoded according to
+.IR format .
+.TP
+.BI "\-k, \-\-key " tag
+Use the key-encapsulation key named
+.I tag
+in the current keyring; the default key is
+.BR ccrypt .
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.BI "\-s, \-\-sign-key " tag
+Use the signature key named
+.I tag
+in the current keyring; the default is not to sign the ciphertext.
+.TP
+.BI "\-o, \-\-ouptut " file
+Write output to
+.I file
+rather than to standard output.
+.TP
+.B "\-C, \-\-nocheck"
+Don't check the public key for validity.  This makes encryption go much
+faster, but at the risk of using a duff key.
+.SS decrypt
+The
+.B decrypt
+command decrypts a ciphertext and writes out the plaintext.  By default,
+it reads from standard input and writes to standard output.  If a
+filename argument is given, this file is read instead.
+.PP
+The following options are recognized.
+.TP
+.B "\-a, \-\-armour"
+Read ASCII-armoured input.  This is equivalent to specifying
+.BR "\-f pem" .
+The variant spelling
+.B "\-\-armor"
+is also accepted.
+.TP
+.B "\-b, \-\-buffer"
+Buffer plaintext data until we're sure we've got it all.  This is forced
+on if output is to stdout, but is always available as an option.
+.TP
+.BI "\-f, \-\-format " format
+Read input encoded according to
+.IR format .
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.B "\-v, \-\-verbose"
+Produce more verbose messages.  See below for the messages produced
+during decryption.  The default verbosity level is 1.  (Currently this
+is the most verbose setting.  This might not be the case always.)
+.TP
+.B "\-q, \-\-quiet"
+Produce fewer messages.
+.TP
+.BI "\-o, \-\-output " file
+Write output to
+.I file
+instead of to standard output.  The file is written in binary mode.
+Fixing line-end conventions is your problem; there are lots of good
+tools for dealing with it.
+.TP
+.B "\-C, \-\-nocheck"
+Don't check the private key for validity.  This makes decryption go much
+faster, but at the risk of using a duff key, and possibly leaking
+information about the private key.
+.PP
+Output is written to standard output in a machine-readable format.
+Major problems cause the program to write a diagnostic to standard error
+and exit nonzero as usual.  The quantity of output varies depending on
+the verbosity level and whether the plaintext is also being written to
+standard output.  Output lines begin with a keyword:
+.TP
+.BI "FAIL " reason
+An error prevented decryption.  The program will exit nonzero.
+.TP
+.BI "WARN " reason
+.B catcrypt
+encountered a situation which may or may not invalidate the decryption.
+.TP
+.BI "OK " message
+Decryption was successful.  This is only produced if main output is
+being sent somewhere other than standard output.
+.TP
+.B "DATA"
+The plaintext follows, starting just after the next newline character or
+sequence.  This is only produced if main output is also being sent to
+standard output.
+.TP
+.BI "INFO " note
+Any other information.
+.PP
+The information written at the various verbosity levels is as follows.
+.hP 0.
+No output.  Watch the exit status.
+.hP 1.
+All messages.
+.PP
+.B Warning!
+All output written has been checked for authenticity.  However, output
+can fail madway through for many reasons, and the resulting message may
+therefore be truncated.  Don't rely on the output being complete until
+.B OK
+is printed or
+.B catcrypt decrypt
+exits successfully.
+.SS "encode"
+The
+.B encode
+command encodes an input file according to one of the encodings
+described above in
+.BR ENCODINGS .
+The input is read from the
+.I file
+given on the command line, or from standard input if none is specified.
+Options provided are:
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.BI "\-f, \-\-format " format
+Produce output in
+.IR format .
+Run
+.B catcrypt show enc
+for a list of encoding formats.
+.TP
+.BI "\-b, \-\-boundary " label
+Set the PEM boundary string to
+.IR label ;
+i.e., assuming we're encoding in PEM format, the output will have
+.BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
+at the top and
+.BI "\-\-\-\-\-END " label "\-\-\-\-\-"
+at the bottom.  The default
+.I label
+is
+.BR MESSAGE .
+.TP
+.BI "\-o, \-\-output " file
+Write output to
+.I file
+instead of to standard output.
+.SS "decode"
+The
+.B decode
+command decodes an input file encoded according to one of the encodings
+described above in
+.BR ENCODINGS .
+The input is read from the
+.I file
+given on the command line, or from standard input if none is specified.
+Options provided are:
+.TP
+.BI "\-f, \-\-format " format
+Decode input in
+.IR format .
+Run
+.B catcrypt show enc
+for a list of encoding formats.
+.TP
+.BI "\-b, \-\-boundary " label
+Set the PEM boundary string to
+.IR label ;
+i.e., assuming we're encoding in PEM format, start processing input
+between
+.BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
+and
+.BI "\-\-\-\-\-END " label "\-\-\-\-\-"
+lines.  Without this option,
+.B catcrypt
+will start reading at the first plausible boundary string, and continue
+processing until it reaches the matching end boundary.
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.BI "\-o, \-\-output " file
+Write output to
+.I file
+instead of to standard output.
+.SH "SECURITY PROPERTIES"
+Assuming the security of the underlying primitive algorithms, the
+following security properties of the ciphertext hold.
+.hP \*o
+An adversary given the public key-encapsulation key and capable of
+requesting encryption of arbitrary plaintexts of his own devising is
+unable to decide whether he is given ciphertexts corresponding to his
+chosen plaintexts or random plaintexts of the same length.  This holds
+even if the adversary is permitted to request decryption of any
+ciphertext other than one produced as a result of an encryption request.
+This property is called
+.BR IND-CCA2 .
+.hP \*o
+An adversary given the public key-encapsulation and verification keys,
+and capable of requesting encryption of arbitrary plaintext of his own
+devising is unable to produce a new ciphertext which will be accepted as
+genuine.  This property is called
+.BR INT-CTXT .
+.hP \*o
+An adversary given the public key-encapsulation and verification keys,
+and capable of requesting encryption of arbitrary plaintext of his own
+devising is unable to decide whether the ciphertexts he is given are
+correctly signed.  This property doesn't seem to have a name.
+.PP
+Not all is rosy.  If you leak intermediate values during decryption then
+an adversary can construct a new correctly-signed message.  Don't do
+that, then \(en leaking intermediate values often voids security
+warranties.  But it does avoid the usual problem with separate signing
+and encryption that a careful leak by the recipient can produce evidence
+that you signed some incriminating message.
+.PP
+Note that
+.BR catcrypt 's
+signatures do
+.I not
+provide `non-repudiation' in any useful way.  This is deliberate: the
+purpose of signing is to convince the recipient of the sender's
+identity, rather than to allow the recipient to persuade anyone else.
+Indeed, given an encrypted and signed message, the recipient can
+straightforwardly construct a new message, apparently from the same
+sender, and whose signature still verifies, but with arbitrarily chosen
+content.
+.SH "CRYPTOGRAPHIC THEORY"
+Encryption of a message proceeds as follows.
+.hP 0.
+Emit a header packet containing the key-ids for the key-encapsulation
+key, and signature key if any.
+.hP 1.
+Use the KEM to produce a public value and a shared secret the recipient
+will be able to extract from the public value using his private key.
+Emit a packet containing the public value.
+.hP 2.
+Hash the shared secret.  Use the KDF to produce a pseudorandom keystream
+of indefinite length.
+.hP 3.
+Use the first bits of the keystream to key a symmetric encryption
+scheme; use the next bits to key a message authentication code.
+.hP 4.
+If we're signing the message then extract 1024 bytes from the keystream,
+sign the header and public value, and the keystream bytes; emit a packet
+containing the signature.  The signature packet doesn't contain the
+signed message, just the signature.
+.hP 5.
+Split the message into blocks.  For each block, pick a random IV from
+the keystream, encrypt the block and emit a packet containing the
+IV, ciphertext, and a MAC tag over the ciphertext and a sequence number.
+.hP 6.
+The last chunk is the encryption of an empty plaintext block.  No
+previous plaintext block is empty.  This lets us determine the
+difference between a complete file and one that's been maliciously
+truncated.
+.PP
+That's it.  Nothing terribly controversial, really.
+.SH "SEE ALSO"
+.BR key (1),
+.BR catsign (1),
+.BR dsig (1),
+.BR hashsum (1),
+.BR keyring (5).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>