Remove buf bits which moved to mLib. Fix email addresses.

[u/mdw/catacomb] / catcrypt.1

diff --git a/catcrypt.1 b/catcrypt.1
index 603d1d1..56fe297 100644 (file)
--- a/catcrypt.1
+++ b/catcrypt.1
@@ -70,7 +70,7 @@ is one of:
 .IR output ]
 .RI [ file ]
 .br
-.B encode
+.B decode
 .RB [ \-f
 .IR format ]
 .RB [ \-b
@@ -118,7 +118,10 @@ for more details about keyring files.
 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
@@ -175,7 +178,8 @@ options, to generate the key.
 .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))
@@ -206,7 +210,8 @@ constructed by the raw KEM.  If there is no
 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
@@ -475,12 +480,16 @@ filename argument is given, this file is read instead.
 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 .
@@ -504,7 +513,7 @@ 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.
@@ -519,11 +528,8 @@ 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 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.
@@ -535,14 +541,13 @@ No output.  Watch the exit status.
 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
@@ -642,6 +647,18 @@ 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.
@@ -664,13 +681,19 @@ 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>