Merge branch '2.5.x'

[catacomb] / progs / catcrypt.1

diff --git a/progs/catcrypt.1 b/progs/catcrypt.1
index 6bace86..d944bfa 100644 (file)
--- a/progs/catcrypt.1
+++ b/progs/catcrypt.1
@@ -134,6 +134,14 @@ A
 has the syntax
 .IR kem \c
 .RB [ / \c
 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 ]].
 .IR cipher \c
 .RB [ / \c
 .IR hash ]].


@@ -196,24 +204,109 @@ algorithm of the
 command (see
 .BR key (1))
 to generate the key.
 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
 .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
 .B cipher
 attribute then the

-.I cipher
+.I bulk

 in the
 .I kemalgspec
 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
 .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
 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
 .B mac
 attribute then
 .IB hash -hmac


@@ -348,6 +445,40 @@ command (see
 .BR key (1))
 to generate the key.
 .TP
 .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
 .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 .
 .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
 .PP
 Run
 .B catcrypt show hash


@@ -436,24 +575,26 @@ key-encapsulation key's
 attribute.
 .TP
 .B cipher
 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
 key-encapsulation key's
 .B cipher

-attribute.
+attribute when using the
+.B gencomp
+bulk transform.

 .TP
 .B mac
 .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
 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
 .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
 .B hash
 attribute.
 .TP


@@ -584,7 +725,7 @@ All messages.
 .PP
 .B Warning!
 All output written has been checked for authenticity.  However, output
 .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
 therefore be truncated.  Don't rely on the output being complete until
 .B OK
 is printed or