crypto.hmac-sha256

export function hmacSha256(key: readonly number[], message: readonly number[]): readonly number[]

import { hmacSha256 } from "#fune/crypto.hmac-sha256@^1";

import { sha256 } from "./crypto_sha256.ts";  ← from crypto.sha256 ^1.0.0 · built alongside by fune

const BLOCK = 64;

function checkBytes(value: readonly number[], name: string): void {
  if (!Array.isArray(value) && !(value instanceof Uint8Array)) {
    throw new TypeError(`${name} must be a list of integers from 0 to 255`);
  }
  for (let i = 0; i < value.length; i++) {
    const b = value[i];
    if (typeof b !== "number" || !Number.isInteger(b) || b < 0 || b > 255) {
      throw new RangeError(`${name} must be a list of integers from 0 to 255`);
    }
  }
}

/**
 * HMAC-SHA256 (RFC 2104): H((K ^ opad) || H((K ^ ipad) || message)), with a
 * key longer than the 64-byte block hashed down to 32 bytes first.
 */
export function hmacSha256(key: readonly number[], message: readonly number[]): readonly number[] {
  checkBytes(key, "key");
  checkBytes(message, "message");
  const k = key.length > BLOCK ? sha256(key) : key;
  const inner: number[] = new Array(BLOCK + message.length);
  const outer: number[] = new Array(BLOCK + 32);
  for (let i = 0; i < BLOCK; i++) {
    const b = i < k.length ? k[i] : 0;
    inner[i] = b ^ 0x36;
    outer[i] = b ^ 0x5c;
  }
  for (let i = 0; i < message.length; i++) inner[BLOCK + i] = message[i];
  const innerHash = sha256(inner);
  for (let i = 0; i < 32; i++) outer[BLOCK + i] = innerHash[i];
  return sha256(outer);
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add crypto.hmac-sha256

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./crypto.hmac-sha256-1.0.0-typescript.fune, or fetch it from a terminal with fune pull crypto.hmac-sha256@1.0.0:typescript.

The whole function, every language, is one file too: crypto.hmac-sha256-1.0.0.fune, 14,277 bytes, sha256 aefbaef231a3cc8016bbff5c5226b4169f41ea671335aac1093c35e6d5bbf81e. It installs into a project of any language.

// fune: before crypto.hmac-sha256

// fune: after crypto.hmac-sha256

// fune: replace crypto.sha256 in crypto.hmac-sha256

// fune: step crypto.hmac-sha256 after <n|label>

More from the author

The construction is `H((K xor opad) || H((K xor ipad) || message))` with the key zero-padded to SHA-256's 64-byte block, or first hashed to 32 bytes when it is longer than 64. That last rule is the one a naive implementation misses, and RFC 4231 test cases 6 and 7 (a 131-byte key) are among the vectors. The empty key is allowed, as the RFC allows it, but a real key should be at least 32 random bytes (RFC 2104 section 3; RFC 7518 requires it for HS256).

**Compare tags with `crypto.constant-time-equal`.** Comparing with `==` stops at the first differing byte, and the time that takes tells an attacker how many leading bytes of a forged tag were right.

TypeScript and Rust build on `crypto.sha256` and so run anywhere, the browser included, with no `node:crypto` or `crypto.subtle`; Python uses the standard library's `hmac`. Test case 5 of RFC 4231 publishes only the first 16 bytes of its tag; its vector holds the full 32, computed with Python's `hmac` module as the reference, and begins with the RFC's 16.

Source: RFC 2104, HMAC: Keyed-Hashing for Message Authentication (https://www.rfc-editor.org/rfc/rfc2104); RFC 4231, Identifiers and Test Vectors for HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512, section 4 (https://www.rfc-editor.org/rfc/rfc4231).

Files