Use auto-version machinery for building.

[u/mdw/catacomb] / catcrypt.1

diff --git a/catcrypt.1 b/catcrypt.1
index 56fe297..6bace86 100644 (file)
--- a/catcrypt.1
+++ b/catcrypt.1
@@ -44,7 +44,7 @@ is one of:
 .RI [ item ...]
 .br
 .B encrypt
 .RI [ item ...]
 .br
 .B encrypt

-.RB [ \-a ]
+.RB [ \-apC ]

 .RB [ \-k
 .IR tag ]
 .RB [ \-f
 .RB [ \-k
 .IR tag ]
 .RB [ \-f


@@ -54,7 +54,7 @@ is one of:
 .RI [ file ]
 .br
 .B decrypt
 .RI [ file ]
 .br
 .B decrypt

-.RB [ \-aqv ]
+.RB [ \-apqvC ]

 .RB [ \-f
 .IR format ]
 .RB [ \-o
 .RB [ \-f
 .IR format ]
 .RB [ \-o


@@ -62,6 +62,7 @@ is one of:
 .RI [ file ]
 .br
 .B encode
 .RI [ file ]
 .br
 .B encode

+.RB [ \-p ]

 .RB [ \-f
 .IR format ]
 .RB [ \-b
 .RB [ \-f
 .IR format ]
 .RB [ \-b


@@ -71,6 +72,7 @@ is one of:
 .RI [ file ]
 .br
 .B decode
 .RI [ file ]
 .br
 .B decode

+.RB [ \-p ]

 .RB [ \-f
 .IR format ]
 .RB [ \-b
 .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
 .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
 .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.
 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,
 .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
 .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
 .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
 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
 .B dsa
 algorithm of the
 .B key add


@@ -335,6 +347,21 @@ algorithm of the
 command (see
 .BR key (1))
 to generate the key.
 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
 .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 sha .
 .hP \*o
 For

-.BR kcdsa 
+.BR kcdsa

 and
 .BR eckcdsa ,
 the default hash function is
 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
 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
 .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
 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
 .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.
 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
 .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
 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
 .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.
 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
 .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.
 .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.
 .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
 .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
 .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 .
 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
 .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 .
 .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 .
 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:
 .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 "\-\-\-\-\-"
 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 "\-\-\-\-\-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
 .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,
 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
 .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