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

diff --git a/catcrypt.1 b/catcrypt.1
deleted file mode 100644
index 6bace86..0000000
--- a/catcrypt.1
+++ /dev/null
@@ -1,748 +0,0 @@
-.\" -*-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>