Makefile: Link tests against stuff like -lm.

[u/mdw/catacomb] / catcrypt.1

diff --git a/catcrypt.1 b/catcrypt.1
index 56fe297..72bfe12 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
@@ -120,7 +120,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 +184,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 +278,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 +303,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 +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
@@ -355,7 +380,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 +456,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
@@ -470,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
@@ -508,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
@@ -521,7 +555,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 +577,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,7 +588,7 @@ 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:
@@ -588,7 +622,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,7 +640,7 @@ 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
@@ -676,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