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
 .IR output ]
 .RI [ file ]
 .br

-.B encode
+.B decode

 .RB [ \-f
 .IR format ]
 .RB [ \-b
 .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
 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
 .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
 .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))
 .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
 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
 .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"
 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
 .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 .
 .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
 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
 .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
 .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.
 .TP
 .BI "INFO " note
 Any other information.


@@ -535,14 +541,13 @@ No output.  Watch the exit status.
 All messages.
 .PP
 .B Warning!
 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
 .B OK

-and/or exits successfully.
+is printed or
+.B catcrypt decrypt
+exits successfully.

 .SS "encode"
 The
 .B encode
 .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.
 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.
 .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
 .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),
 .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
 .BR dsig (1),
 .BR hashsum (1),
 .BR keyring (5).
 .SH AUTHOR

-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>