From 1d356ca4e6b9e63dd77aae970dfb56ea652bd9c2 Mon Sep 17 00:00:00 2001
From: Paul Miller <paul@paulmillr.com>
Date: Mon, 9 Sep 2024 21:12:33 +0000
Subject: [PATCH] aes, chacha, salsa: adjust comments

---
 src/aes.ts    | 4 +++-
 src/chacha.ts | 7 ++++---
 src/salsa.ts  | 7 ++++---
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/src/aes.ts b/src/aes.ts
index 4dec346..f357427 100644
--- a/src/aes.ts
+++ b/src/aes.ts
@@ -578,8 +578,10 @@ function computeTag(
 
 /**
  * GCM: Galois/Counter Mode.
- * Good, modern version of CTR, parallel, with MAC.
+ * Modern, parallel version of CTR, with MAC.
  * Be careful: MACs can be forged.
+ * Unsafe to use random nonces under the same key, due to collision chance.
+ * As for nonce size, prefer 12-byte, instead of 8-byte.
  */
 export const gcm = wrapCipher(
   { blockSize: 16, nonceLength: 12, tagLength: 16 },
diff --git a/src/chacha.ts b/src/chacha.ts
index 47a131b..043810a 100644
--- a/src/chacha.ts
+++ b/src/chacha.ts
@@ -276,7 +276,8 @@ export const _poly1305_aead =
 
 /**
  * ChaCha20-Poly1305 from RFC 8439.
- * With 12-byte nonce, it's not safe to use fill it with random (CSPRNG), due to collision chance.
+ * Unsafe to use random nonces under the same key, due to collision chance.
+ * Prefer XChaCha instead.
  */
 export const chacha20poly1305 = /* @__PURE__ */ wrapCipher(
   { blockSize: 64, nonceLength: 12, tagLength: 16 },
@@ -284,8 +285,8 @@ export const chacha20poly1305 = /* @__PURE__ */ wrapCipher(
 );
 /**
  * XChaCha20-Poly1305 extended-nonce chacha.
- * https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha
- * With 24-byte nonce, it's safe to use fill it with random (CSPRNG).
+ * Can be safely used with random nonces (CSPRNG).
+ * [IRTF draft](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha).
  */
 export const xchacha20poly1305 = /* @__PURE__ */ wrapCipher(
   { blockSize: 64, nonceLength: 24, tagLength: 16 },
diff --git a/src/salsa.ts b/src/salsa.ts
index 4478732..ae5d44c 100644
--- a/src/salsa.ts
+++ b/src/salsa.ts
@@ -96,7 +96,8 @@ export function hsalsa(
 
 /**
  * Salsa20 from original paper.
- * With 12-byte nonce, it's not safe to use fill it with random (CSPRNG), due to collision chance.
+ * Unsafe to use random nonces under the same key, due to collision chance.
+ * Prefer XSalsa instead.
  */
 export const salsa20 = /* @__PURE__ */ createCipher(salsaCore, {
   allowShortKeys: true,
@@ -105,7 +106,7 @@ export const salsa20 = /* @__PURE__ */ createCipher(salsaCore, {
 
 /**
  * xsalsa20 eXtended-nonce salsa.
- * With 24-byte nonce, it's safe to use fill it with random (CSPRNG).
+ * Can be safely used with random 24-byte nonces (CSPRNG).
  */
 export const xsalsa20 = /* @__PURE__ */ createCipher(salsaCore, {
   counterRight: true,
@@ -114,7 +115,7 @@ export const xsalsa20 = /* @__PURE__ */ createCipher(salsaCore, {
 
 /**
  * xsalsa20-poly1305 eXtended-nonce salsa.
- * With 24-byte nonce, it's safe to use fill it with random (CSPRNG).
+ * Can be safely used with random 24-byte nonces (CSPRNG).
  * Also known as secretbox from libsodium / nacl.
  */
 export const xsalsa20poly1305 = /* @__PURE__ */ wrapCipher(