More comments

paulmillr · Jan 2, 2025 · 99d03d2 · 99d03d2
1 parent 7c74b0d
commit 99d03d2
Show file tree

Hide file tree

Showing 4 changed files with 17 additions and 4 deletions.
diff --git a/src/chacha.ts b/src/chacha.ts
@@ -276,6 +276,7 @@ export const _poly1305_aead =
 
 /**
  * ChaCha20-Poly1305 from RFC 8439.
+ *
  * Unsafe to use random nonces under the same key, due to collision chance.
  * Prefer XChaCha instead.
  */
@@ -285,8 +286,9 @@ export const chacha20poly1305: ARXCipher = /* @__PURE__ */ wrapCipher(
 );
 /**
  * XChaCha20-Poly1305 extended-nonce chacha.
+ *
  * Can be safely used with random nonces (CSPRNG).
- * [IRTF draft](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha).
+ * See [IRTF draft](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha).
  */
 export const xchacha20poly1305: ARXCipher = /* @__PURE__ */ wrapCipher(
   { blockSize: 64, nonceLength: 24, tagLength: 16 },

diff --git a/src/ff1.ts b/src/ff1.ts
@@ -96,6 +96,7 @@ function getRound(radix: number, key: Uint8Array, tweak: Uint8Array, x: number[]
 
 const EMPTY_BUF = new Uint8Array([]);
 
+/** FPE-FF1 format-preserving encryption */
 export function FF1(
   radix: number,
   key: Uint8Array,
@@ -153,6 +154,7 @@ const binLE = {
   },
 };
 
+/** Binary version of FPE-FF1 format-preserving encryption. */
 export function BinaryFF1(key: Uint8Array, tweak: Uint8Array = EMPTY_BUF): Cipher {
   const ff1 = FF1(2, key, tweak);
   return {

diff --git a/src/salsa.ts b/src/salsa.ts
@@ -178,7 +178,7 @@ export const xsalsa20poly1305: ARXCipher = /* @__PURE__ */ wrapCipher(
 );
 
 /**
- * Alias to xsalsa20poly1305, for compatibility with libsodium / nacl
+ * Alias to `xsalsa20poly1305`, for compatibility with libsodium / nacl
  */
 export function secretbox(
   key: Uint8Array,

diff --git a/src/webcrypto.ts b/src/webcrypto.ts
@@ -47,7 +47,13 @@ type CipherWithNonce = ((key: Uint8Array, nonce: Uint8Array, ...args: any[]) =>
   nonceLength: number;
 };
 
-// Uses CSPRG for nonce, nonce injected in ciphertext
+/**
+ * Uses CSPRG for nonce, nonce injected in ciphertext.
+ * @example
+ * const gcm = managedNonce(aes.gcm);
+ * const ciphr = gcm(key).encrypt(data);
+ * const plain = gcm(key).decrypt(ciph);
+ */
 export function managedNonce<T extends CipherWithNonce>(fn: T): RemoveNonce<T> {
   const { nonceLength } = fn;
   anumber(nonceLength);
@@ -138,10 +144,13 @@ function generate(algo: BlockMode) {
   };
 }
 
-export const cbc: (key: Uint8Array, nonce: Uint8Array) => AsyncCipher = /* @__PURE__ */ (() =>
+/** AES-CBC, native webcrypto version */
+export const cbc: (key: Uint8Array, iv: Uint8Array) => AsyncCipher = /* @__PURE__ */ (() =>
   generate(mode.CBC))();
+/** AES-CTR, native webcrypto version */
 export const ctr: (key: Uint8Array, nonce: Uint8Array) => AsyncCipher = /* @__PURE__ */ (() =>
   generate(mode.CTR))();
+/** AES-GCM, native webcrypto version */
 export const gcm: (key: Uint8Array, nonce: Uint8Array, AAD?: Uint8Array) => AsyncCipher =
   /* @__PURE__ */ (() => generate(mode.GCM))();