infra: Clean up project setup

[u/mdw/catacomb] / catcrypt.1

.\" -*-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 [ \-aC ]
.RB [ \-k
.IR tag ]
.RB [ \-f
.IR format ]
.RB [ \-o
.IR output ]
.RI [ file ]
.br
.B decrypt
.RB [ \-aqvC ]
.RB [ \-f
.IR format ]
.RB [ \-o
.IR output ]
.RI [ file ]
.br
.B encode
.RB [ \-f
.IR format ]
.RB [ \-b
.IR boundary ]
.RB [ \-o
.IR output ]
.RI [ file ]
.br
.B decode
.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.
.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.
.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 "\-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
.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 "\-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 "\-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>