Merge branch 'master' of git+ssh://metalzone.distorted.org.uk/~mdw/public-git/catacomb/

[u/mdw/catacomb] / catcrypt.1

diff --git a/catcrypt.1 b/catcrypt.1
index aa410b8..61da7f9 100644 (file)
--- a/catcrypt.1
+++ b/catcrypt.1
@@ -44,7 +44,7 @@ is one of:
 .RI [ item ...]
 .br
 .B encrypt
-.RB [ \-a ]
+.RB [ \-aC ]
 .RB [ \-k
 .IR tag ]
 .RB [ \-f
@@ -54,7 +54,7 @@ is one of:
 .RI [ file ]
 .br
 .B decrypt
-.RB [ \-aqv ]
+.RB [ \-aqvC ]
 .RB [ \-f
 .IR format ]
 .RB [ \-o
@@ -178,11 +178,22 @@ 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))
 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,
@@ -209,7 +220,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
@@ -333,6 +345,21 @@ algorithm of the
 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
@@ -468,6 +495,10 @@ in the current keyring; the default is not to sign the ciphertext.
 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
@@ -506,6 +537,11 @@ Write output to
 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
@@ -526,7 +562,7 @@ 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
+sequence.  This is only produced if main output is also being sent to
 standard output.
 .TP
 .BI "INFO " note
@@ -542,7 +578,8 @@ All messages.
 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 OK
+is printed or
 .B catcrypt decrypt
 exits successfully.
 .SS "encode"
@@ -644,6 +681,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.
@@ -661,8 +710,9 @@ 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 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
@@ -681,4 +731,4 @@ That's it.  Nothing terribly controversial, really.
 .BR hashsum (1),
 .BR keyring (5).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>