server/tripe-admin.5.in: Document the `unsuitable-aead-cipher' warnings.

[tripe] / server / tripe-admin.5.in

diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in
index bd0635e..bd2cce8 100644 (file)
--- a/server/tripe-admin.5.in
+++ b/server/tripe-admin.5.in
@@ -1468,9 +1468,6 @@ and the second token is the filename of the keyring.  Frequently a key
 tag may be given next, preceded by the token
 .BR key .
 .SP
-.BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key"
-The private key doesn't record the correct corresponding public key.
-.SP
 .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch"
 A peer's public key doesn't request the same algorithms as our private
 key.
@@ -1486,13 +1483,21 @@ The key attributes contain
 .I str
 where a MAC tag length was expected.  The key was generated wrongly.
 .SP
+.BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key"
+The private key doesn't record the correct corresponding public key.
+.SP
+.BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
+A system error occurred while opening or reading the keyring file.
+.SP
 .BI "KEYMGMT private-keyring " file " key " tag " changed-group"
 The private keyring has been changed, but the new private key can't be
 used because it uses a different group for Diffie\(enHellman key
 exchange.
 .SP
-.BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
-A system error occurred while opening or reading the keyring file.
+.BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
+No message authentication code was given explicitly, and there's no
+implementation of HMAC for the selected hash function
+.IR hash .
 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
 The key specifies the use of an unknown bulk-crypto transform
@@ -1537,10 +1542,51 @@ The key specifies the use of an unknown serialization format
 for hashing group elements.  Maybe the key was generated wrongly, or
 maybe the version of Catacomb installed is too old.
 .SP
-.BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
-No message authentication code was given explicitly, and there's no
-implementation of HMAC for the selected hash function
-.IR hash .
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "no-aad"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which does not support the processing of additional authenticated data.
+The most prominent examples of such schemes are the
+.IB cipher -naclbox
+collection, where
+.I cipher
+is
+.BR salsa20 ,
+.BR salsa20/12 ,
+.BR salsa20/8 ,
+.BR chacha20 ,
+.BR chacha12 ,
+or
+.BR chacha8 ;
+use the
+.B naclbox
+bulk transform rather than
+.B aead
+for these
+(or switch to the IETF
+.IB cipher -poly1305
+schemes instead).
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-small"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which doesn't even allow a 5-byte (40-bit) nonce.  Catacomb doesn't
+implement any such limited AE schemes: you must be doing something
+strange.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-large"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which doesn't support any nonce size smaller than 64 bytes (512 bits).
+Catacomb doesn't implement any such extravagant AE schemes: you must be
+doing something strange.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonempty-ciphertext-for-empty-message"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which produces ciphertext output even when given a completely empty
+message.  Catacomb doesn't implement any such unhelpful AE schemes: you
+must be doing something strange.
 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz
 The