*
* Decryption: checks the overall size, verifies the tag, then decrypts the
* ciphertext and extracts the sequence number.
+ *
+ * Challenge tags are calculated by applying the MAC to the sequence number
+ * and message, concatenated as follows.
+ *
+ * +--------+---...---+
+ * | seq | m |
+ * +--------+---...---+
+ * 32 msz
*/
typedef struct v0_algs {
* | tag | seq | ciphertext |
* +---...---+------+------...------+
* tagsz 32 sz
+ *
+ * Challenge tags are calculated by applying the MAC to the sequence number
+ * and message, concatenated as follows.
+ *
+ * +--------+---...---+
+ * | seq | m |
+ * +--------+---...---+
+ * 32 msz
*/
typedef struct iiv_algs {
/*----- The AEAD transform ------------------------------------------------*
*
- * This transform uses a general authenticated encryption scheme (the
- * additional data isn't necessary). Good options include
- * `chacha20-poly1305' or `rijndael-ocb3'.
+ * This transform uses a general authenticated encryption scheme. Processing
+ * additional authenticated data isn't needed for encrypting messages, but it
+ * is required for challenge generation. Good options include `chacha20-
+ * poly1305' or `rijndael-ocb3'; alas, `salsa20-naclbox' isn't acceptable.
*
* To be acceptable, the scheme must accept at least a 40-bit nonce. (All of
- * Catacomb's current AEAD schemes are suitable.) The low 32 bits are the
- * sequence number. The type is written to the next 8--32 bytes: if the
- * nonce size is 64 bits or more (preferred, for compatibility reasons) then
- * the type is written as 32 bits, and the remaining space is padded with
- * zero bytes; otherwise, the type is right-aligned in the remaining space.
- * Both fields are big-endian.
+ * Catacomb's current AEAD schemes are suitable in this respect.) The low 32
+ * bits are the sequence number. The type is written to the next 8--32
+ * bytes: if the nonce size is 64 bits or more (preferred, for compatibility
+ * reasons) then the type is written as 32 bits, and the remaining space is
+ * padded with zero bytes; otherwise, the type is right-aligned in the
+ * remaining space. Both fields are big-endian.
*
* +--------+--+
* | seq |ty|
* +---...---+--------+------...------+
* tagsz 32 sz
*
+ * Challenge tags are calculated by encrypting the message, using the
+ * sequence number as a nonce (as a big-endian integer, padding with leading
+ * zeroes as needed to fill the space), and discarding the ciphertext.
+ *
+ * +---...---+--------+ +-----...------+
+ * | 0 | seq | | message |
+ * +---...---+--------+ +-----...------+
+ * nsz - 32 32 msz
*/
#define AEAD_NONCEMAX 64
* Note that there is no need to authenticate the type separately, since it
* was used to select the cipher nonce, and hence the Poly1305 key. The
* Poly1305 tag length is fixed.
+ *
+ * Challenge formation is rather tricky. We can't use Poly1305 directly
+ * because we need a random mask. So we proceed as follows. The challenge
+ * generator has a Salsa20 or ChaCha key. The sequence number is used as the
+ * Salsa20 message number/nonce, padded at the start with zeroes to form,
+ * effectively, a 64-bit big-endian integer.
+ *
+ * +--------+--------+
+ * | 0 | seq |
+ * +--------+--------+
+ * 32 32
+ *
+ * 256 bits (32 bytes) of keystream are generated and used as a Poly1305 hash
+ * key r and mask s. These are then used to hash the message, and the
+ * resulting tag is the challenge.
*/
typedef struct naclbox_algs {
of arguments was wrong.
.SP
.BI "bad-time-spec " token
-The
+(For commands accepting a
+.I time
+argument.) The
.I token
is not a valid time interval specification. Acceptable time
specifications are nonnegative integers followed optionally by
.BR DAEMON .)
An error occurred during the attempt to become a daemon, as reported by
.IR message .
+See
+.B WARNINGS
+below for the meanings of
+.I ecode
+and
+.IR message .
.SP
.BI "disabled-address-family " afam
(For
.IR peer .
.SP
.B "ping-send-failed"
+(For
+.BR EPING .)
The attempt to send a ping packet failed, probably due to lack of
encryption keys.
.SP
.SP
.B "CHAL impossible-challenge"
The server hasn't issued any challenges yet. Quite how anyone else
-thought he could make one up is hard to imagine.
+thought they could make one up is hard to imagine.
.SP
.B "CHAL incorrect-tag"
Challenge received contained the wrong authentication data. It might be
.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
The key specifies the use of an unknown bulk-crypto transform
.IR bulk .
-Maybe the key was generated wrongly, or maybe the version of Catacomb
-installed is too old.
+Maybe the key was generated wrongly, or maybe the version of
+.BR tripe (8)
+is too old.
.SP
.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher
The key specifies the use of an unknown symmetric encryption algorithm
The key specifies the use of an unknown serialization format
.I ser
for hashing group elements. Maybe the key was generated wrongly, or
-maybe the version of Catacomb installed is too old.
+maybe the version of
+.BR tripe (8)
+is too old.
.SP
.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "no-aad"
The key specifies the use of an authenticated encryption scheme
.B naclbox
bulk transform rather than
.B aead
-for these
-(or switch to the IETF
+for these, or switch to one of the IETF
.IB cipher -poly1305
-schemes instead).
+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
~mdw / tripe / commitdiff