Manual review: side channel protection nitpicking

diff --git a/doc/man/man3/crypto_chacha20_encrypt.3monocypher b/doc/man/man3/crypto_chacha20_encrypt.3monocypher
index cdb315cda575e5c07db386565bd4065359cfc409..dba7cc1459b27cda60b1339eff2691511a4c2116 100644 (file)
--- a/doc/man/man3/crypto_chacha20_encrypt.3monocypher
+++ b/doc/man/man3/crypto_chacha20_encrypt.3monocypher
@@ -170,6 +170,10 @@ uint8_t       cipher_text[500];  /* Will be the encrypted message  */
 crypto_chacha_ctx ctx;
 crypto_chacha20_x_init(&ctx, key, nonce);
 crypto_chacha20_encrypt(&ctx, cipher_text, plain_text, 500);
+/* Wipe secrets if they're no longer needed */
+crypto_wipe(key,        sizeof(key));
+crypto_wipe(&ctx,       sizeof(ctx));
+crypto_wipe(plain_text, sizeof(plain_text));
 .Ed
 .Pp
 To decrypt the above:
@@ -181,12 +185,10 @@ uint8_t plain_text       [500];  /* Will be the decrypted message  */
 crypto_chacha_ctx ctx;
 crypto_chacha20_x_init(&ctx, key, nonce);
 crypto_chacha20_encrypt(&ctx, plain_text, cipher_text, 500);
-/* If you're done with encryption, you will want to wipe the key and
- * context, possibly the plaintext, too.
- */
-crypto_wipe(key,        sizeof(key));
-crypto_wipe(&ctx,       sizeof(ctx));
-crypto_wipe(plain_text, sizeof(plain_text));
+/* Wipe secrets if they're no longer needed */
+crypto_wipe(key,  sizeof(key));
+crypto_wipe(&ctx, sizeof(ctx));
+/* The plain text likely needs to be processed before you wipe it */
 .Ed
 .Pp
 Encryption chunk by chunk (same as simple encryption):
@@ -200,11 +202,10 @@ crypto_chacha20_x_init(&ctx, key, nonce);
 for(int i = 0; i < 500; i += 100) {
     crypto_chacha20_encrypt(&ctx, cipher_text+i, plain_text+i, 100);
 }
-/* If you're done with decryption, you will want to wipe the key and
- * context.
- */
-crypto_wipe(key,  sizeof(key));
-crypto_wipe(&ctx, sizeof(ctx));
+/* Wipe secrets if they're no longer needed */
+crypto_wipe(key,        sizeof(key));
+crypto_wipe(&ctx,       sizeof(ctx));
+crypto_wipe(plain_text, sizeof(plain_text));
 .Ed
 .Pp
 In place encryption (same results as simple encryption):
@@ -217,6 +218,9 @@ crypto_chacha20_x_init(&ctx, key, nonce);
 crypto_chacha20_encrypt(&ctx, message, message, 500);
 crypto_wipe(key,  sizeof(key));
 crypto_wipe(&ctx, sizeof(ctx));
+/* Wipe secrets if they're no longer needed */
+crypto_wipe(key,  sizeof(key));
+crypto_wipe(&ctx, sizeof(ctx));
 .Ed
 .Pp
 Simple encryption with a small,
@@ -231,6 +235,10 @@ crypto_chacha20_init(&ctx, key, nonce);
 crypto_chacha20_encrypt(&ctx, cipher_text, plain_text, 500);
 crypto_wipe(key,  sizeof(key));
 crypto_wipe(&ctx, sizeof(ctx));
+/* Wipe secrets if they're no longer needed */
+crypto_wipe(key,        sizeof(key));
+crypto_wipe(&ctx,       sizeof(ctx));
+crypto_wipe(plain_text, sizeof(plain_text));
 .Ed
 .Pp
 Encryption by jumping around (don't do that):
@@ -250,8 +258,10 @@ crypto_chacha20_encrypt(&ctx,
 /* ...then encrypt the first part */
 crypto_chacha20_set_ctr(&ctx, 0);
 crypto_chacha20_encrypt(&ctx, cipher_text, plain_text, 3 * 64);
-crypto_wipe(key,  sizeof(key));
-crypto_wipe(&ctx, sizeof(ctx));
+/* Wipe secrets if they're no longer needed */
+crypto_wipe(key,        sizeof(key));
+crypto_wipe(&ctx,       sizeof(ctx));
+crypto_wipe(plain_text, sizeof(plain_text));
 .Ed
 .Sh SEE ALSO
 .Xr crypto_lock 3monocypher ,
@@ -264,19 +274,20 @@ XChacha20 derives from Chacha20 the same way XSalsa20 derives from
 Salsa20, and benefits from the same security reduction (proven secure
 as long as Chacha20 itself is secure).
 .Sh SECURITY CONSIDERATIONS
-.Sy Encryption alone is not sufficient for security .
-Chacha20 should never be used alone.
-It only protects against eavesdropping, not forgeries.
+.Ss Encrypted doesn't mean secure
+Chacha20 only protects against eavesdropping, not forgeries.
+Most applications need protection against forgeries to be properly
+secure.
 To ensure the integrity of a message, use Blake2b in keyed mode, or
 authenticated encryption; see
 .Xr crypto_blake2b 3monocypher
 and
 .Xr crypto_lock 3monocypher
+.Ss Nonce reuse
+Repeating a nonce with the same key exposes the XOR of two or more
+plaintext messages, effectively destroying confidentiality.
 .Pp
-Do not reuse a nonce for the same key.
-This would expose the XOR of subsequent encrypted messages, and
-destroy confidentiality.
-.Pp
+For the same reason,
 .Sy do not select small nonces at random .
 The
 .Fn crypto_chacha20_init
@@ -286,8 +297,15 @@ A counter should be used instead.
 If multiple parties send out messages, Each can start with an initial
 nonce of 0, 1 .. n-1 respectively, and increment them by n for each
 new message (make sure the counters never wrap around).
-.Pp
+.Ss Secure random number generation
 Do not use these functions as cryptographic random number generator.
 Always use the operating system's random number generator for
 cryptographic purposes, see
 .Xr intro 3monocypher .
+.Ss Protection against side channels
+Secrets should not dwell in memory longer than needed.
+Use
+.Xr crypto_wipe 3monocypher
+to erase secrets you no longer need.
+For Chacha20, this means the context, the key, and in some cases the
+plain text itself.

diff --git a/doc/man/man3/crypto_poly1305_auth.3monocypher b/doc/man/man3/crypto_poly1305_auth.3monocypher
index b9b52e81a5c213fc71cd79ea0d9f4ed7cce502bc..255f05088f7015575d8139b1a2d6c29e7805c570 100644 (file)
--- a/doc/man/man3/crypto_poly1305_auth.3monocypher
+++ b/doc/man/man3/crypto_poly1305_auth.3monocypher
@@ -126,6 +126,7 @@ crypto_poly1305_final(&ctx, mac);
 .Sh STANDARDS
 These functions implement Poly1305, described in RFC 7539.
 .Sh  SECURITY CONSIDERATIONS
+.Ss User error
 Using Poly1305 correctly is difficult.
 Do not use it unless you are absolutely sure what you are doing.
 Use authenticated encryption instead; see
@@ -152,7 +153,6 @@ The session key cannot be used for this: it is secret and shared, but
 it is
 .Em reused .
 The attacker will recover it and break all security.
-.Pp
 A simple random number cannot be used either: there is no reasonable
 way to give it to the recipient without also revealing it to the
 attacker.
@@ -189,3 +189,9 @@ MAC in relatively few tries.
 The authentication key should be wiped with
 .Xr crypto_wipe 3monocypher
 after use.
+.Pp
+Incremental interface users don't need to wipe the
+.Ft crypto_poly1305_ctx
+explicitly,
+.Fn crypto_poly1305_final
+does it automatically.