aes, chacha, salsa: adjust comments

paulmillr · Sep 9, 2024 · 1d356ca · 1d356ca
1 parent ceaeb80
commit 1d356ca
Show file tree

Hide file tree

Showing 3 changed files with 11 additions and 7 deletions.
diff --git 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
@@ -276,16 +276,17 @@ 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 },
   _poly1305_aead(chacha20)
 );
 /**
  * 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
@@ -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(