X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/f387fcb17a980fe165218d217b0187a8c279508a..7280f7f44cfae62f6d34761ac88aa19da7da5dd8:/catcrypt.1

diff --git a/catcrypt.1 b/catcrypt.1
index 56fe297..6bace86 100644
--- a/catcrypt.1
+++ b/catcrypt.1
@@ -44,7 +44,7 @@ is one of:
 .RI [ item ...]
 .br
 .B encrypt
-.RB [ \-a ]
+.RB [ \-apC ]
 .RB [ \-k
 .IR tag ]
 .RB [ \-f
@@ -54,7 +54,7 @@ is one of:
 .RI [ file ]
 .br
 .B decrypt
-.RB [ \-aqv ]
+.RB [ \-apqvC ]
 .RB [ \-f
 .IR format ]
 .RB [ \-o
@@ -62,6 +62,7 @@ is one of:
 .RI [ file ]
 .br
 .B encode
+.RB [ \-p ]
 .RB [ \-f
 .IR format ]
 .RB [ \-b
@@ -71,6 +72,7 @@ is one of:
 .RI [ file ]
 .br
 .B decode
+.RB [ \-p ]
 .RB [ \-f
 .IR format ]
 .RB [ \-b
@@ -120,7 +122,7 @@ 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 
+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
@@ -184,6 +186,16 @@ Use the
 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,
@@ -268,7 +280,7 @@ for a list of supported signature algorithms.
 .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 
+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
@@ -293,7 +305,7 @@ command (see
 to generate the key.
 .TP
 .B dsa
-This is the DSA algorithm described in FIPS180-1 and FIPS180-2.    Use the
+This is the DSA algorithm described in FIPS180-1 and FIPS180-2.  Use the
 .B dsa
 algorithm of the
 .B key add
@@ -335,6 +347,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
@@ -355,7 +382,7 @@ the default hash function is
 .BR sha .
 .hP \*o
 For
-.BR kcdsa 
+.BR kcdsa
 and
 .BR eckcdsa ,
 the default hash function is
@@ -431,7 +458,7 @@ The hash functions which can be used in a key's
 attribute.
 .TP
 .B enc
-The encodings which can be applied to encrypted messages; see 
+The encodings which can be applied to encrypted messages; see
 .B ENCODINGS
 above.
 .SS encrypt
@@ -461,6 +488,9 @@ Use the key-encapsulation key named
 in the current keyring; the default key is
 .BR ccrypt .
 .TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
 .BI "\-s, \-\-sign-key " tag
 Use the signature key named
 .I tag
@@ -470,6 +500,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
@@ -494,6 +528,9 @@ on if output is to stdout, but is always available as an option.
 Read input encoded according to
 .IR format .
 .TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
 .B "\-v, \-\-verbose"
 Produce more verbose messages.  See below for the messages produced
 during decryption.  The default verbosity level is 1.  (Currently this
@@ -508,6 +545,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
@@ -521,7 +563,7 @@ An error prevented decryption.  The program will exit nonzero.
 .BI "WARN " reason
 .B catcrypt
 encountered a situation which may or may not invalidate the decryption.
-.TP 
+.TP
 .BI "OK " message
 Decryption was successful.  This is only produced if main output is
 being sent somewhere other than standard output.
@@ -543,7 +585,7 @@ All messages.
 .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 
+therefore be truncated.  Don't rely on the output being complete until
 .B OK
 is printed or
 .B catcrypt decrypt
@@ -554,11 +596,14 @@ The
 command encodes an input file according to one of the encodings
 described above in
 .BR ENCODINGS .
-The input is read from the 
+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 "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
 .BI "\-f, \-\-format " format
 Produce output in
 .IR format .
@@ -588,7 +633,7 @@ The
 command decodes an input file encoded according to one of the encodings
 described above in
 .BR ENCODINGS .
-The input is read from the 
+The input is read from the
 .I file
 given on the command line, or from standard input if none is specified.
 Options provided are:
@@ -606,13 +651,16 @@ Set the PEM boundary string to
 i.e., assuming we're encoding in PEM format, start processing input
 between
 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
-and 
+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 "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
 .BI "\-o, \-\-output " file
 Write output to
 .I file
@@ -676,8 +724,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