X-Git-Url: https://git.distorted.org.uk/~mdw/catacomb/blobdiff_plain/0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a..7b0d1a63587f3cb1ae3bb8b248bbb1b82bdca7bd:/progs/catcrypt.1

diff --git a/progs/catcrypt.1 b/progs/catcrypt.1
index 6bace86f..d944bfab 100644
--- a/progs/catcrypt.1
+++ b/progs/catcrypt.1
@@ -134,6 +134,14 @@ A
 has the syntax
 .IR kem \c
 .RB [ / \c
+.IR bulk \c
+.RB [ \- \c
+.IR cipher ] \c
+.RB [ / \c
+.IR hash ]]
+or
+.IR kem \c
+.RB [ / \c
 .IR cipher \c
 .RB [ / \c
 .IR hash ]].
@@ -196,24 +204,109 @@ algorithm of the
 command (see
 .BR key (1))
 to generate the key.
+.TP
+.B x25519
+This is Bernstein's Curve25519, a fast Diffie-Hellman using a specific
+elliptic curve.
+Use the
+.B x25519
+algorithm of the
+.B key add
+command
+(see
+.BR key (1))
+to generate the key.
+.TP
+.B x448
+This is Hamburg's Curve25519, a strong Diffie-Hellman using a specific
+elliptic curve.
+Use the
+.B x448
+algorithm of the
+.B key add
+command
+(see
+.BR key (1))
+to generate the key.
+.PP
+The bulk crypto transform is chosen based on the
+.B bulk
+attribute on the key, or, failing that,
+from the
+.I bulk
+stated in the
+.IR kemalgspec .
+Run
+.B catcrypt show bulk
+for a list of supported bulk crypto transforms.
+.TP
+.B gencomp
+A generic composition of
+a cipher secure against chosen-plaintext attack,
+and a message authentication code.
+Makes use of
+.B cipher
+and
+.B mac
+attributes.  Run
+.B catcrypt show cipher
+for a list of supported symmetric encryption algorithms; the default
+.I cipher
+is
+.BR blowfish-cbc .
+This is the default transform.
+.TP
+.B aead
+Use an `authenticated encryption with additional data' (AEAD) scheme.
+The specific scheme is named by the
+.B cipher
+attribute.  Run
+.B catcrypt show aead
+for a list of supported AEAD schemes; the default is
+.BR chacha20-poly1305 .
+.TP
+.B naclbox
+Use Salsa20 or ChaCha and Poly1305 to secure the bulk data.
+This is nearly the same as the NaCl
+.B crypto_secretbox
+construction,
+except that
+.B catcrypt
+uses Salsa20 or ChaCha rather than XSalsa20,
+because it doesn't need the latter's extended nonce.
+The
+.B cipher
+attribute may be set to one of
+.BR salsa20 ,
+.BR salsa20/12 ,
+.BR salsa20/8 ,
+.BR chacha20 ,
+.BR chacha12 ,
+or
+.BR chacha8 ;
+the default is
+.BR salsa20 .
+Nowadays, this is equivalent to the
+.B aead
+transform, using
+.IB cipher -naclbox
+as the cipher.
 .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,
 failing that, derived from other attributes as described below.
 .TP
 .B cipher
-This is the symmetric encryption algorithm used for bulk data
-encryption.  If there is no
+This is the symmetric encryption algorithm
+used by the bulk data transform.
+If there is no
 .B cipher
 attribute then the
-.I cipher
+.I bulk
 in the
 .I kemalgspec
-is used; if that it absent, then the default of
-.B blowfish-cbc
-is used.  Run
-.B catcrypt show cipher
-for a list of supported symmetric encryption algorithms.
+is used; if that it absent, then the default depends on the bulk
+transform.
 .TP
 .B hash
 This is the hash function used to distil entropy from the shared secret
@@ -230,9 +323,13 @@ is used.  Run
 for a list of supported symmetric encryption algorithms.
 .TP
 .B mac
-This is the message authentication algorithm used during bulk data
-encryption to ensure integrity of the encrypted message and defend
-against chosen-ciphertext attacks.  If there is no
+This is the message authentication algorithm
+used by the
+.B gencomp
+bulk data transform
+to ensure integrity of the encrypted message and
+defend against chosen-ciphertext attacks.
+If there is no
 .B mac
 attribute then
 .IB hash -hmac
@@ -348,6 +445,40 @@ command (see
 .BR key (1))
 to generate the key.
 .TP
+.B ed25519
+This is Bernstein, Duif, Lange, Schwabe, and Yang's Ed25519 algorithm.
+More specifically, this is HashEd25519
+using the selected
+.B hash
+algorithm \(en by default
+.BR sha512 .
+Use the
+.B ed25519
+algorithm of the
+.B key add
+command
+(see
+.BR key (1))
+to generate the key.
+.TP
+.B ed448
+This is Bernstein, Duif, Lange, Schwabe, and Yang's EdDSA algorithm,
+using Hamburg's Ed448-Goldilocks elliptic curve,
+as specified in RFC8032.
+More specifically, this is HashEd448
+using the selected
+.B hash
+algorithm \(en by default
+.BR sha3-512 .
+Use the
+.B ed448
+algorithm of the
+.B key add
+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
@@ -387,6 +518,14 @@ and
 .BR eckcdsa ,
 the default hash function is
 .BR has160 .
+For
+.BR ed25519 ,
+the default hash function is
+.BR sha512 .
+For
+.BR ed448 ,
+the default hash function is
+.BR shake256 .
 .PP
 Run
 .B catcrypt show hash
@@ -436,24 +575,26 @@ key-encapsulation key's
 attribute.
 .TP
 .B cipher
-The symmetric encryption algorithms which can be used in a
+The symmetric encryption algorithms which can be named in a
 key-encapsulation key's
 .B cipher
-attribute.
+attribute when using the
+.B gencomp
+bulk transform.
 .TP
 .B mac
-The message authentication algorithms which can be used in a
+The message authentication algorithms which can be named in a
 key-encapsulation key's
 .B mac
 attribute.
 .TP
 .B sig
-The signature algorithms which can be used in a signing key's
+The signature algorithms which can be named in a signing key's
 .B sig
 attribute.
 .TP
 .B hash
-The hash functions which can be used in a key's
+The hash functions which can be named in a key's
 .B hash
 attribute.
 .TP
@@ -584,7 +725,7 @@ All messages.
 .PP
 .B Warning!
 All output written has been checked for authenticity.  However, output
-can fail madway through for many reasons, and the resulting message may
+can fail midway 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