@bsv/sdk 1.9.23 → 1.9.29

package/src/primitives/AESGCM.ts

@@ -202,33 +202,73 @@ export const getBytes = function (numericValue: number): number[] {
   ]
 }
 
-const createZeroBlock = function (length: number): number[] {
-  return new Array(length).fill(0)
+export const getBytes64 = function (numericValue: number): number[] {
+  if (numericValue < 0 || numericValue > Number.MAX_SAFE_INTEGER) {
+    throw new Error('getBytes64: value out of range')
+  }
+
+  const hi = Math.floor(numericValue / 0x100000000)
+  const lo = numericValue >>> 0
+
+  return [
+    (hi >>> 24) & 0xFF,
+    (hi >>> 16) & 0xFF,
+    (hi >>> 8) & 0xFF,
+    hi & 0xFF,
+    (lo >>> 24) & 0xFF,
+    (lo >>> 16) & 0xFF,
+    (lo >>> 8) & 0xFF,
+    lo & 0xFF
+  ]
 }
 
-const R = [0xe1].concat(createZeroBlock(15))
+type Bytes = Uint8Array
 
-export const exclusiveOR = function (block0: number[], block1: number[]): number[] {
+const createZeroBlock = function (length: number): Bytes {
+  // Uint8Array is already zero-filled
+  return new Uint8Array(length)
+}
+
+// R = 0xe1 || 15 zero bytes
+const R: Bytes = (() => {
+  const r = new Uint8Array(16)
+  r[0] = 0xe1
+  return r
+})()
+
+const concatBytes = (...arrays: Bytes[]): Bytes => {
+  let total = 0
+  for (const a of arrays) total += a.length
+
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const a of arrays) {
+    out.set(a, offset)
+    offset += a.length
+  }
+  return out
+}
+
+export const exclusiveOR = function (block0: Bytes, block1: Bytes): Bytes {
   const len = block0.length
-  const result = new Array(len)
+  const result = new Uint8Array(len)
   for (let i = 0; i < len; i++) {
-    result[i] = block0[i] ^ block1[i]
+    result[i] = block0[i] ^ (block1[i] ?? 0)
   }
   return result
 }
 
-const xorInto = function (target: number[], block: number[]): void {
+const xorInto = function (target: Bytes, block: Bytes): void {
   for (let i = 0; i < target.length; i++) {
-    target[i] ^= block[i]
+    target[i] ^= block[i] ?? 0
   }
 }
 
-export const rightShift = function (block: number[]): number[] {
-  let i: number
+export const rightShift = function (block: Bytes): Bytes {
   let carry = 0
   let oldCarry = 0
 
-  for (i = 0; i < block.length; i++) {
+  for (let i = 0; i < block.length; i++) {
     oldCarry = carry
     carry = block[i] & 0x01
     block[i] = block[i] >> 1
@@ -241,7 +281,7 @@ export const rightShift = function (block: number[]): number[] {
   return block
 }
 
-export const multiply = function (block0: number[], block1: number[]): number[] {
+export const multiply = function (block0: Bytes, block1: Bytes): Bytes {
   const v = block1.slice()
   const z = createZeroBlock(16)
 
@@ -264,16 +304,14 @@ export const multiply = function (block0: number[], block1: number[]): number[]
 }
 
 export const incrementLeastSignificantThirtyTwoBits = function (
-  block: number[]
-): number[] {
-  let i
+  block: Bytes
+): Bytes {
   const result = block.slice()
-  for (i = 15; i !== 11; i--) {
-    result[i] = result[i] + 1
 
-    if (result[i] === 256) {
-      result[i] = 0
-    } else {
+  for (let i = 15; i > 11; i--) {
+    result[i] = (result[i] + 1) & 0xff // wrap explicitly
+
+    if (result[i] !== 0) {
       break
     }
   }
@@ -281,11 +319,12 @@ export const incrementLeastSignificantThirtyTwoBits = function (
   return result
 }
 
-export function ghash (input: number[], hashSubKey: number[]): number[] {
+export function ghash (input: Bytes, hashSubKey: Bytes): Bytes {
   let result = createZeroBlock(16)
+  const block = new Uint8Array(16)
 
   for (let i = 0; i < input.length; i += 16) {
-    const block = result.slice()
+    block.set(result)
     for (let j = 0; j < 16; j++) {
       block[j] ^= input[i + j] ?? 0
     }
@@ -296,14 +335,14 @@ export function ghash (input: number[], hashSubKey: number[]): number[] {
 }
 
 function gctr (
-  input: number[],
-  initialCounterBlock: number[],
-  key: number[]
-): number[] {
-  if (input.length === 0) return []
-
-  const output = new Array(input.length)
-  let counterBlock = initialCounterBlock
+  input: Bytes,
+  initialCounterBlock: Bytes,
+  key: Bytes
+): Bytes {
+  if (input.length === 0) return new Uint8Array(0)
+
+  const output = new Uint8Array(input.length)
+  let counterBlock = initialCounterBlock.slice()
   let pos = 0
   const n = Math.ceil(input.length / 16)
 
@@ -323,12 +362,97 @@ function gctr (
   return output
 }
 
+function buildAuthInput (cipherText: Bytes): Bytes {
+  const aadLenBits = 0
+  const ctLenBits = cipherText.length * 8
+
+  let padLen: number
+  if (cipherText.length === 0) {
+    padLen = 16
+  } else if (cipherText.length % 16 === 0) {
+    padLen = 0
+  } else {
+    padLen = 16 - (cipherText.length % 16)
+  }
+
+  const total =
+    16 +
+    cipherText.length +
+    padLen +
+    16
+
+  const out = new Uint8Array(total)
+  let offset = 0
+
+  offset += 16
+
+  out.set(cipherText, offset)
+  offset += cipherText.length
+
+  offset += padLen
+
+  const aadLen = getBytes64(aadLenBits)
+  out.set(aadLen, offset)
+  offset += 8
+
+  const ctLen = getBytes64(ctLenBits)
+  out.set(ctLen, offset)
+
+  return out
+}
+
+/**
+ * SECURITY NOTE – NON-STANDARD AES-GCM PADDING
+ *
+ * This implementation intentionally deviates from NIST SP 800-38D’s AES-GCM
+ * specification in how the GHASH input is formed when the additional
+ * authenticated data (AAD) or ciphertext length is zero.
+ *
+ * In the standard, AAD and ciphertext are each padded with the minimum number
+ * of zero bytes required to reach a multiple of 16 bytes; when the length is
+ * already a multiple of 16 (including the case length = 0), no padding block
+ * is added. In this implementation, when AAD.length === 0 or ciphertext.length
+ * === 0, an extra 16-byte block of zeros is appended before the length fields
+ * are processed. The same formatting logic is used symmetrically in both
+ * AESGCM (encryption) and AESGCMDecrypt (decryption).
+ *
+ * As a result:
+ *   - Authentication tags produced here are NOT compatible with tags produced
+ *     by standards-compliant AES-GCM implementations in the cases where AAD
+ *     or ciphertext are empty.
+ *   - Ciphertexts generated by this code must be decrypted by this exact
+ *     implementation (or one that reproduces the same GHASH formatting), and
+ *     must not be mixed with ciphertexts produced by a strictly standard
+ *     AES-GCM library.
+ *
+ * Cryptographic impact: this change alters only the encoding of the message
+ * that is input to GHASH; it does not change the block cipher, key derivation,
+ * IV handling, or the basic “encrypt-then-MAC over (AAD, ciphertext, lengths)”
+ * structure of AES-GCM. Under the usual assumptions that AES is a secure block
+ * cipher and GHASH with a secret subkey is a secure polynomial MAC, this
+ * variant continues to provide confidentiality and integrity for data encrypted
+ * and decrypted consistently with this implementation. We are not aware of any
+ * attack that exploits the presence of this extra zero block when AAD or
+ * ciphertext are empty.
+ *
+ * However, this padding behavior is non-compliant with NIST SP 800-38D and has
+ * not been analyzed as extensively as standard AES-GCM. Code that requires
+ * strict standards compliance or interoperability with external AES-GCM
+ * implementations SHOULD NOT use this module as-is. Any future migration to a
+ * fully compliant AES-GCM encoding will require a compatibility strategy, as
+ * existing ciphertexts produced by this implementation will otherwise become
+ * undecryptable.
+ *
+ * This non-standard padding behavior is retained intentionally for backward
+ * compatibility: existing ciphertexts in production were generated with this
+ * encoding, and changing it would render previously encrypted data
+ * undecryptable by newer versions of the library.
+ */
 export function AESGCM (
-  plainText: number[],
-  additionalAuthenticatedData: number[],
-  initializationVector: number[],
-  key: number[]
-): { result: number[], authenticationTag: number[] } {
+  plainText: Bytes,
+  initializationVector: Bytes,
+  key: Bytes
+): { result: Bytes, authenticationTag: Bytes } {
   if (initializationVector.length === 0) {
     throw new Error('Initialization vector must not be empty')
   }
@@ -337,60 +461,54 @@ export function AESGCM (
     throw new Error('Key must not be empty')
   }
 
-  let preCounterBlock
-  let plainTag
-  const hashSubKey = AES(createZeroBlock(16), key)
-  preCounterBlock = [...initializationVector]
+  const hashSubKey = new Uint8Array(AES(createZeroBlock(16), key))
+
+  let preCounterBlock: Bytes
+
   if (initializationVector.length === 12) {
-    preCounterBlock = preCounterBlock.concat(createZeroBlock(3)).concat([0x01])
+    preCounterBlock = concatBytes(initializationVector, createZeroBlock(3), new Uint8Array([0x01]))
   } else {
-    if (initializationVector.length % 16 !== 0) {
-      preCounterBlock = preCounterBlock.concat(
-        createZeroBlock(16 - (initializationVector.length % 16))
+    let ivPadded = initializationVector
+    if (ivPadded.length % 16 !== 0) {
+      ivPadded = concatBytes(
+        ivPadded,
+        createZeroBlock(16 - (ivPadded.length % 16))
       )
     }
 
-    preCounterBlock = preCounterBlock.concat(createZeroBlock(8))
+    const lenBlock = getBytes64(initializationVector.length * 8)
+    const s = concatBytes(
+      ivPadded,
+      createZeroBlock(8),
+      new Uint8Array(lenBlock)
+    )
 
-    preCounterBlock = ghash(preCounterBlock.concat(createZeroBlock(4))
-      .concat(getBytes(initializationVector.length * 8)), hashSubKey)
+    preCounterBlock = ghash(s, hashSubKey)
   }
 
-  const cipherText = gctr(plainText, incrementLeastSignificantThirtyTwoBits(preCounterBlock), key)
-
-  plainTag = additionalAuthenticatedData.slice()
+  const cipherText = gctr(
+    plainText,
+    incrementLeastSignificantThirtyTwoBits(preCounterBlock),
+    key
+  )
 
-  if (additionalAuthenticatedData.length === 0) {
-    plainTag = plainTag.concat(createZeroBlock(16))
-  } else if (additionalAuthenticatedData.length % 16 !== 0) {
-    plainTag = plainTag.concat(createZeroBlock(16 - (additionalAuthenticatedData.length % 16)))
-  }
+  const authInput = buildAuthInput(cipherText)
 
-  plainTag = plainTag.concat(cipherText)
-
-  if (cipherText.length === 0) {
-    plainTag = plainTag.concat(createZeroBlock(16))
-  } else if (cipherText.length % 16 !== 0) {
-    plainTag = plainTag.concat(createZeroBlock(16 - (cipherText.length % 16)))
-  }
-
-  plainTag = plainTag.concat(createZeroBlock(4))
-    .concat(getBytes(additionalAuthenticatedData.length * 8))
-    .concat(createZeroBlock(4)).concat(getBytes(cipherText.length * 8))
+  const s = ghash(authInput, hashSubKey)
+  const authenticationTag = gctr(s, preCounterBlock, key)
 
   return {
     result: cipherText,
-    authenticationTag: gctr(ghash(plainTag, hashSubKey), preCounterBlock, key)
+    authenticationTag
   }
 }
 
 export function AESGCMDecrypt (
-  cipherText: number[],
-  additionalAuthenticatedData: number[],
-  initializationVector: number[],
-  authenticationTag: number[],
-  key: number[]
-): number[] | null {
+  cipherText: Bytes,
+  initializationVector: Bytes,
+  authenticationTag: Bytes,
+  key: Bytes
+): Bytes | null {
   if (cipherText.length === 0) {
     throw new Error('Cipher text must not be empty')
   }
@@ -403,53 +521,57 @@ export function AESGCMDecrypt (
     throw new Error('Key must not be empty')
   }
 
-  let preCounterBlock
-  let compareTag
-
   // Generate the hash subkey
-  const hashSubKey = AES(createZeroBlock(16), key)
+  const hashSubKey = new Uint8Array(AES(createZeroBlock(16), key))
+
+  let preCounterBlock: Bytes
 
-  preCounterBlock = [...initializationVector]
   if (initializationVector.length === 12) {
-    preCounterBlock = preCounterBlock.concat(createZeroBlock(3)).concat([0x01])
+    preCounterBlock = concatBytes(
+      initializationVector,
+      createZeroBlock(3),
+      new Uint8Array([0x01])
+    )
   } else {
-    if (initializationVector.length % 16 !== 0) {
-      preCounterBlock = preCounterBlock.concat(createZeroBlock(16 - (initializationVector.length % 16)))
+    let ivPadded = initializationVector
+    if (ivPadded.length % 16 !== 0) {
+      ivPadded = concatBytes(
+        ivPadded,
+        createZeroBlock(16 - (ivPadded.length % 16))
+      )
     }
 
-    preCounterBlock = preCounterBlock.concat(createZeroBlock(8))
+    const lenBlock = getBytes64(initializationVector.length * 8)
+    const s = concatBytes(
+      ivPadded,
+      createZeroBlock(8),
+      new Uint8Array(lenBlock)
+    )
 
-    preCounterBlock = ghash(preCounterBlock.concat(createZeroBlock(4)).concat(getBytes(initializationVector.length * 8)), hashSubKey)
+    preCounterBlock = ghash(s, hashSubKey)
   }
 
   // Decrypt to obtain the plain text
-  const plainText = gctr(cipherText, incrementLeastSignificantThirtyTwoBits(preCounterBlock), key)
+  const plainText = gctr(
+    cipherText,
+    incrementLeastSignificantThirtyTwoBits(preCounterBlock),
+    key
+  )
 
-  compareTag = additionalAuthenticatedData.slice()
+  const authInput = buildAuthInput(cipherText)
+  const s = ghash(authInput, hashSubKey)
+  const calculatedTag = gctr(s, preCounterBlock, key)
 
-  if (additionalAuthenticatedData.length === 0) {
-    compareTag = compareTag.concat(createZeroBlock(16))
-  } else if (additionalAuthenticatedData.length % 16 !== 0) {
-    compareTag = compareTag.concat(createZeroBlock(16 - (additionalAuthenticatedData.length % 16)))
+  if (calculatedTag.length !== authenticationTag.length) {
+    return null
   }
 
-  compareTag = compareTag.concat(cipherText)
-
-  if (cipherText.length === 0) {
-    compareTag = compareTag.concat(createZeroBlock(16))
-  } else if (cipherText.length % 16 !== 0) {
-    compareTag = compareTag.concat(createZeroBlock(16 - (cipherText.length % 16)))
+  let diff = 0
+  for (let i = 0; i < calculatedTag.length; i++) {
+    diff |= calculatedTag[i] ^ authenticationTag[i]
   }
 
-  compareTag = compareTag.concat(createZeroBlock(4))
-    .concat(getBytes(additionalAuthenticatedData.length * 8))
-    .concat(createZeroBlock(4)).concat(getBytes(cipherText.length * 8))
-
-  // Generate the authentication tag
-  const calculatedTag = gctr(ghash(compareTag, hashSubKey), preCounterBlock, key)
-
-  // If the calculated tag does not match the provided tag, return null - the decryption failed.
-  if (calculatedTag.join() !== authenticationTag.join()) {
+  if (diff !== 0) {
     return null
   }
 

package/src/primitives/Hash.ts

@@ -282,13 +282,15 @@ export function toArray (
   return res
 }
 
-function htonl (w: number): number {
-  const res =
-    (w >>> 24) |
-    ((w >>> 8) & 0xff00) |
-    ((w << 8) & 0xff0000) |
-    ((w & 0xff) << 24)
-  return res >>> 0
+/**
+ * @deprecated
+ * This function behaves differently from the standard C `htonl()`.
+ * It always performs an unconditional 32-bit byte swap.
+ * Use `swapBytes32()` for explicit byte swapping, or `realHtonl()` for
+ * standards-compliant host-to-network conversion.
+ */
+export function htonl (w: number): number {
+  return swapBytes32(w)
 }
 
 function toHex32 (msg: number[], endian?: 'little' | 'big'): string {
@@ -1857,3 +1859,66 @@ export function pbkdf2 (
   const out = pbkdf2Fast(p, s, iterations, keylen)
   return Array.from(out)
 }
+
+/**
+ * Unconditionally swaps the byte order of a 32-bit unsigned integer.
+ *
+ * This function performs a strict 32-bit byte swap regardless of host
+ * endianness. It is equivalent to the behavior commonly referred to as
+ * `bswap32` in low-level libraries.
+ *
+ * This function is introduced as part of TOB-20 to provide a clearly-named
+ * alternative to `htonl()`, which was previously implemented as an
+ * unconditional byte swap and did not match the semantics of the traditional
+ * C `htonl()` function.
+ *
+ * @param w - A 32-bit unsigned integer.
+ * @returns The value with its byte order reversed.
+ *
+ * @example
+ * swapBytes32(0x11223344) // → 0x44332211
+ */
+export function swapBytes32 (w: number): number {
+  const res =
+    (w >>> 24) |
+    ((w >>> 8) & 0xff00) |
+    ((w << 8) & 0xff0000) |
+    ((w & 0xff) << 24)
+  return res >>> 0
+}
+
+// Detect the host machine's endianness at runtime.
+//
+// This is used by `realHtonl()` to determine whether the value must be
+// byte-swapped or returned unchanged. JavaScript engines on common platforms
+// are almost always little-endian, but this check is included for correctness.
+const isLittleEndian = (() => {
+  const b = new ArrayBuffer(4)
+  const a = new Uint32Array(b)
+  const c = new Uint8Array(b)
+  a[0] = 0x01020304
+  return c[0] === 0x04
+})()
+
+/**
+ * Converts a 32-bit unsigned integer from host byte order to network byte order.
+ *
+ * Unlike the legacy `htonl()` implementation (which always swapped bytes),
+ * this function behaves like the traditional C `htonl()`:
+ *
+ * - On **little-endian** machines → performs a byte swap.
+ * - On **big-endian** machines → returns the value unchanged.
+ *
+ * This function is provided to resolve TOB-20, which identified that the
+ * previous `htonl()` implementation had a misleading name and did not match
+ * platform-dependent semantics.
+ *
+ * @param w - A 32-bit unsigned integer.
+ * @returns The value converted to network byte order.
+ *
+ * @example
+ * realHtonl(0x11223344) // → 0x44332211 on little-endian systems
+ */
+export function realHtonl (w: number): number {
+  return isLittleEndian ? swapBytes32(w) : (w >>> 0)
+}