.RI [ item ...]
.br
.B encrypt
-.RB [ \-a ]
+.RB [ \-aC ]
.RB [ \-k
.IR tag ]
.RB [ \-f
.RI [ file ]
.br
.B decrypt
-.RB [ \-aqv ]
+.RB [ \-aqvC ]
.RB [ \-f
.IR format ]
.RB [ \-o
.IR output ]
.RI [ file ]
.br
-.B encode
+.B decode
.RB [ \-f
.IR format ]
.RB [ \-b
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.
+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
.TP
.B ec
This is the elliptic-curve analogue of
-.BR dh . Use the
+.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,
attribute then the
.I hash
in the
-.I kemalgspec is used; if that is absent then the default of
+.I kemalgspec
+is used; if that is absent then the default of
.B rmd160
is used. Run
.B catcrypt show hash
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
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
The following options are recognized.
.TP
.B "\-a, \-\-armour"
-Read ASCII-armoured output. This is equivalent to specifying
+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 .
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.:
+standard output. Output lines begin with a keyword:
.TP
.BI "FAIL " reason
An error prevented decryption. The program will exit nonzero.
.TP
.B "DATA"
The plaintext follows, starting just after the next newline character or
-sequence. This is only produced if main output is being sent to
-standard output. If anything goes wrong, a
-.B FAIL
-message is printed, preceded and followed by a newline, and the program
-exits nonzero.
+sequence. This is only produced if main output is also being sent to
+standard output.
.TP
.BI "INFO " note
Any other information.
All messages.
.PP
.B Warning!
-All output written has been checked for authenticity. However, since
-the input is chunked, a chunk will be checked and written before the
-authenticity of following chunks is established. Don't rely on the
-output being complete until
-.B catcrypt decrypt
-prints
+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
-and/or exits successfully.
+is printed or
+.B catcrypt decrypt
+exits successfully.
.SS "encode"
The
.B encode
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.
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 them, and emit a packet containing the signature. The signature
-packet doesn't contain the signed message, just the signature.
+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.
+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@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blobdiff