nish/crypto/hmac

HMAC as RFC 2104 defines it, over SHA-256, SHA-384 and SHA-512.

import {
  HMAC_SHA256,
  HMAC_SHA384,
  HMAC_SHA512,
  HmacKey,
  HmacSha256,
  HmacSha256Scratch,
  HmacSha384,
  HmacSha384Scratch,
  HmacSha512,
  hmacCopySha256,
  hmacCopySha384,
  hmacKeyedInto,
  hmacKeyedVerify,
  hmacSha256,
  hmacSha256Secret,
  hmacSha256Verify,
  hmacSha384,
  hmacSha384Secret,
  hmacSha384Verify,
  hmacSha512,
  hmacSha512Secret,
  hmacSha512Verify,
  pbkdf2HmacSha256,
} from "nish/crypto/hmac";
import { HmacSha256, hmacSha256, hmacSha256Verify } from "nish/crypto/hmac";

const tag: u8[] = hmacSha256(key, message);
const ok: boolean = hmacSha256Verify(key, message, received);

const mac = new HmacSha256(key);
mac.update(record, off, len);
const tag2: u8[] = mac.digest();
H(K XOR opad, H(K XOR ipad, text))

K is the key zero-padded to the hash's block size, or first hashed when it is longer than a block (RFC 2104 §2); ipad is the byte 0x36 and opad the byte 0x5c, repeated a block long. The key is absorbed into both hashers in the constructor, so a HmacSha256 is a keyed inner hash waiting for the message and a keyed outer hash waiting for the inner digest.

Like the hashers underneath, a digest ends the computation: a later update or a second digest panics in the hasher it reaches, and so does a window outside its buffer. The only branch on the key is on its length, which HMAC does not keep secret; a received tag is compared with timingSafeEqual, never ===.

What the key reaches is wiped

What the key reaches is wiped (CLAUDE.md, "Security"). The key block is wiped once both hashers have absorbed it, and so is the hash of a key longer than a block and the hasher that made it. digest wipes the inner digest and both keyed hashers (chaining value, pending block and message schedule) before it answers, so a finished HmacSha256 holds nothing of the key. The wipes are wipe's volatile stores, which -O2 keeps (tests/wipes/crypto.js, "crypto_hmac crypto_hkdf: the wipes survive -O2"). What no wipe here reaches is the caller's own key array, and an HmacSha256 that is keyed and then dropped without a digest keeps its keyed hashers (docs/security/crypto-k1.md, K1-7).

A caller that holds its key as a Secret<u8[]> (nish:secret) MACs with hmacSha256Secret, hmacSha384Secret or hmacSha512Secret, which read the key only inside exposeWith; the tag they answer is public and plain.

HmacSha256Scratch and HmacSha384Scratch are the same computation in hashers the caller allocates once: begin keys them again in place and finishInto writes the tag into the caller's array, so a loop of them stores nothing of its own and an arena scope around it releases all it allocated (see "Caller-owned scratch" below).

HmacKey keys a Secret<u8[]> once, for a key MACed with many times (a JWT verifier's HS key): it keeps the inner and outer midstates (RFC 2104 §4) as a Secret<u64[]>, and hmacKeyedVerify / hmacKeyedInto copy them into the key's own hashers per message instead of absorbing the key again. Each call wipes the copy, the hashers and the inner digest before it answers; HmacKey.wipe() zeroes the pads (see "A key held keyed" below).

pbkdf2HmacSha256 is PBKDF2 with HMAC-SHA-256 (RFC 8018 §5.2), the key derivation SCRAM-SHA-256 runs over a password: the password goes in as a Secret<u8[]> and the derived key comes out as one, and every U_j and T_i is wiped before it answers (see "PBKDF2" below).

Written from RFC 2104 and RFC 8018, not ported from another implementation.

Functions

hmacCopySha256

Makes to the hasher from is — the same point in the same message, as Sha256.copy makes it — in a hasher the caller already holds, so that nothing is allocated. Copying from a hasher nothing has been fed starts to again. It is here rather than beside Sha256 because the scratch below and the TLS transcript are what need it, and HMAC is the module both sit on.

const hmacCopySha256: (from: Sha256, to: Sha256) => void
fromSha256required

The hasher to copy; it is not changed.

toSha256required

The hasher overwritten with from's position.

hmacCopySha384

hmacCopySha256 for SHA-384: to made the hasher from is, in place.

const hmacCopySha384: (from: Sha384, to: Sha384) => void
fromSha384required

The hasher to copy; it is not changed.

toSha384required

The hasher overwritten with from's position.

hmacKeyedInto

The tag of data[off .. off + len) under key, written at out[at .. at + key.size()). A window outside its array panics before anything is read. It runs in an arena block of its own and stores nothing, so a tag leaves the arena where it was.

const hmacKeyedInto: (
  key: HmacKey,
  data: u8[],
  off: i32,
  len: i32,
  out: u8[],
  at: i32,
) => void
keyHmacKeyrequired

The absorbed key; a wiped one panics.

datau8[]required

The buffer holding the message.

offi32required

Where the message starts in data.

leni32required

The message's length in bytes.

outu8[]required

The caller's array the tag is written into.

ati32required

Where the tag starts in out.

hmacKeyedVerify

Whether tag[tagAt .. tagAt + key.size()) is the tag of data[off .. off + len) under key, compared in constant time and the computed tag wiped, since it is the one tag a forger needs. A tag window that does not fit answers false; a message window outside its array panics. It runs in an arena block of its own and stores nothing.

const hmacKeyedVerify: (
  key: HmacKey,
  data: u8[],
  off: i32,
  len: i32,
  tag: u8[],
  tagAt: i32,
) => boolean
keyHmacKeyrequired

The absorbed key; a wiped one answers false.

datau8[]required

The buffer holding the message.

offi32required

Where the message starts in data.

leni32required

The message's length in bytes.

tagu8[]required

The buffer holding the tag to check.

tagAti32required

Where the tag starts in tag.

returnsboolean

true only if the tag window holds the correct tag.

hmacSha256

The HMAC-SHA-256 of all of data under key, as a fresh 32-byte array.

data longer than 2^31 - 1 bytes panics, as sha256 does and for its reason: under --number-mode f64 the tag would be of a prefix, and a tag that verifies every message sharing that prefix is a forgery. A key that long panics in the constructor for the same reason.

const hmacSha256: (key: u8[], data: u8[]) => u8[]
keyu8[]required

The secret key; it is read, not kept.

datau8[]required

The whole message.

returnsu8[]

A fresh 32-byte tag, which the caller owns.

hmacSha256Secret

hmacSha256 under a key held as a Secret, read only inside exposeWith. The tag is public, so it is answered plain; the caller still wipes the key.

const hmacSha256Secret: (
  key: Secret<u8[]>,
  data: u8[],
) => u8[]
keySecret<u8[]>required

The secret key; the caller still owns and wipes it.

datau8[]required

The whole message.

returnsu8[]

A fresh 32-byte tag, plain because a tag is public.

hmacSha256Verify

Whether tag is the HMAC-SHA-256 of data under key, compared by timingSafeEqual. A tag that is not 32 bytes answers false without a byte compare, since its length is public; one that is is compared in full, so the time taken does not say how many leading bytes were right.

const hmacSha256Verify: (
  key: u8[],
  data: u8[],
  tag: u8[],
) => boolean
keyu8[]required

The secret key.

datau8[]required

The whole message the tag claims to cover.

tagu8[]required

The tag to check, as received.

returnsboolean

true only if tag is the full, correct tag.

hmacSha384

The HMAC-SHA-384 of all of data under key, as a fresh 48-byte array. data longer than 2^31 - 1 bytes panics, as in hmacSha256.

const hmacSha384: (key: u8[], data: u8[]) => u8[]
keyu8[]required

The secret key; it is read, not kept.

datau8[]required

The whole message.

returnsu8[]

A fresh 48-byte tag, which the caller owns.

hmacSha384Secret

hmacSha384 under a key held as a Secret, as hmacSha256Secret is.

const hmacSha384Secret: (
  key: Secret<u8[]>,
  data: u8[],
) => u8[]
keySecret<u8[]>required

The secret key; the caller still owns and wipes it.

datau8[]required

The whole message.

returnsu8[]

A fresh 48-byte tag, plain because a tag is public.

hmacSha384Verify

Whether tag is the HMAC-SHA-384 of data under key, compared as hmacSha256Verify does.

const hmacSha384Verify: (
  key: u8[],
  data: u8[],
  tag: u8[],
) => boolean
keyu8[]required

The secret key.

datau8[]required

The whole message the tag claims to cover.

tagu8[]required

The tag to check, as received.

returnsboolean

true only if tag is the full, correct tag.

hmacSha512

The HMAC-SHA-512 of all of data under key, as a fresh 64-byte array. data longer than 2^31 - 1 bytes panics, as in hmacSha256.

const hmacSha512: (key: u8[], data: u8[]) => u8[]
keyu8[]required

The secret key; it is read, not kept.

datau8[]required

The whole message.

returnsu8[]

A fresh 64-byte tag, which the caller owns.

hmacSha512Secret

hmacSha512 under a key held as a Secret, as hmacSha256Secret is.

const hmacSha512Secret: (
  key: Secret<u8[]>,
  data: u8[],
) => u8[]
keySecret<u8[]>required

The secret key; the caller still owns and wipes it.

datau8[]required

The whole message.

returnsu8[]

A fresh 64-byte tag, plain because a tag is public.

hmacSha512Verify

Whether tag is the HMAC-SHA-512 of data under key, compared as hmacSha256Verify does.

const hmacSha512Verify: (
  key: u8[],
  data: u8[],
  tag: u8[],
) => boolean
keyu8[]required

The secret key.

datau8[]required

The whole message the tag claims to cover.

tagu8[]required

The tag to check, as received.

returnsboolean

true only if tag is the full, correct tag.

pbkdf2HmacSha256

PBKDF2-HMAC-SHA256(P, S, c, dkLen) as RFC 8018 §5.2 defines it: the dkLen-byte key derived from the password password and the salt salt over iterations rounds, as a Secret.

const salted: Secret<u8[]> | null = pbkdf2HmacSha256(password, salt, 4096, 32);

Bad input answers null and never panics: an iteration count or a length below 1, or a password or salt longer than 2^31 - 1 bytes. The password is read only inside exposeWith, and every U_j, every T_i, both keyed hashers and the working one are wiped before the key is answered; the digests on the way are wiped in the call that made them. The time taken depends on iterations, dkLen and the password's length past a block, all of which RFC 8018 treats as public, and on nothing of the password's bytes.

The time is linear in iterations and nothing here bounds it, so a caller that takes the count from an untrusted peer (a SCRAM server's i=) must cap it first: 2^31 - 1 rounds is about 2^32 compressions.

const pbkdf2HmacSha256: (
  password: Secret<u8[]>,
  salt: u8[],
  iterations: i32,
  length: i32,
) => Secret<u8[]> | null
passwordSecret<u8[]>required

The password P, read only inside exposeWith; the caller still owns and wipes it.

saltu8[]required

The salt S, public.

iterationsi32required

The round count c; below 1 answers null.

lengthi32required

The derived key's length dkLen in bytes; below 1 answers null.

returnsSecret<u8[]> | null

The derived key, which the caller wipes, or null for bad input.

Classes

HmacKey

An HMAC key absorbed once: the inner and outer chaining values after the key's pad blocks (RFC 2104 §4), held as a Secret<u64[]>. Every tag it makes or checks starts from them, so a tag costs the message's blocks and two finishing blocks, and never the key's two again.

const key = new HmacKey(HMAC_SHA256, secretKey);   // once
hmacKeyedInto(key, data, 0, data.length, tag, 0);  // per message
const ok: boolean = hmacKeyedVerify(key, data, 0, data.length, tag, 0);
key.wipe();                                        // when done

The tags are hmacSha256's, hmacSha384's and hmacSha512's for the same key. The key itself is read only inside exposeWith, and the hashers that keyed it are wiped; the caller still owns and wipes the Secret it passed. An unknown hash panics.

The key also owns two hashers of its family, made once, that each tag is computed in and that are wiped before the tag call returns. One key is therefore used by one computation at a time, as a Sha256 is.

class HmacKey
Member
new HmacKey(hash: i32, key: Secret<u8[]>) Absorbs key's two pad blocks for hash and keeps the chaining values. An unknown hash panics.
size(): i32 The tag length in bytes.
wipe(): void Zero both keyed chaining values and the work hashers; the key MACs nothing after.

HmacSha256

HMAC-SHA-256 in progress (RFC 2104 with RFC 4231's SHA-256): feed the message with update, as many windows as it takes, and take the 32-byte tag with digest.

class HmacSha256
Member
new HmacSha256(key: u8[]) Keys the computation. A key longer than 64 bytes is replaced by its SHA-256 (RFC 2104 §2), which is wiped once used (hmacKeySha256).

Besides the two hashers it allocates the 32-byte innerDigest buffer that every digest and digestInto reuses.
inner: Sha256 H(K XOR ipad, …), fed the key block in the constructor and the message after.
innerDigest: u8[] Where digestInto puts the inner digest on its way into outer, so that it allocates nothing; zero except during that call, which wipes it.
outer: Sha256 H(K XOR opad, …), fed the key block in the constructor and the inner digest last.
digest(): u8[] Ends the computation and wipes both hashers and the inner digest. The tag is the one allocation.
digestInto(out: u8[], at: i32): void Writes the 32-byte tag at out[at .. at + 32), ends the computation and wipes both hashers and the inner digest, with nothing allocated. A window outside out panics before anything is written; so does a second digest or digestInto, in the inner hasher.
update(data: u8[], off: i32, len: i32): void Absorbs data[off .. off + len); a window outside data panics in Sha256.update.

HmacSha256Scratch

HMAC-SHA-256 over hashers the caller owns: allocate one, then for each tag begin with the key, update with the message, and finishInto the caller's array. The tag is the one hmacSha256 answers.

const mac = new HmacSha256Scratch();          // once, outside the loop
mac.begin(key, 0, key.length);
mac.update(message, 0, message.length);
mac.finishInto(tag, 0);                       // 32 bytes at tag[0]

The key block is wiped with secureZero once both hashers have absorbed it, and so is every digest on the way; wipe zeroes the hashers too, for a caller done with the key. A key or tag window outside its array panics, as a message window does in Sha256.update.

class HmacSha256Scratch
Member
new HmacSha256Scratch() Allocates the hashers and buffers every tag reuses; begin keys them.
inner: Sha256 H(K XOR ipad, …): keyed by begin, fed the message by update.
outer: Sha256 H(K XOR opad, …): keyed by begin, fed the inner digest by finishInto.
begin(key: u8[], off: i32, len: i32): void Keys a new computation with key[off .. off + len), a key longer than 64 bytes by its SHA-256 (RFC 2104 §2).
finishInto(out: u8[], at: i32): void Writes the 32-byte tag at out[at] and ends the computation; a window outside out panics.
update(data: u8[], off: i32, len: i32): void Absorbs data[off .. off + len); a window outside data panics in Sha256.update.
wipe(): void Zeroes both keyed hashers, for a caller done with the key; begin starts again.

HmacSha384

HMAC-SHA-384 in progress (RFC 2104 with RFC 4231's SHA-384), with HmacSha256's methods. The block is SHA-384's 128 bytes and the tag 48.

class HmacSha384
Member
new HmacSha384(key: u8[]) Keys the computation. A key longer than 128 bytes is replaced by its SHA-384 (RFC 2104 §2).
inner: Sha384 H(K XOR ipad, …), fed the key block in the constructor and the message after.
outer: Sha384 H(K XOR opad, …), fed the key block in the constructor and the inner digest last.
digest(): u8[] Ends the computation and wipes both hashers.
update(data: u8[], off: i32, len: i32): void Absorbs data[off .. off + len); a window outside data panics in Sha384.update.

HmacSha384Scratch

HMAC-SHA-384 over hashers the caller owns, with HmacSha256Scratch's methods. The block is 128 bytes and the tag 48.

class HmacSha384Scratch
Member
new HmacSha384Scratch() Allocates the hashers and buffers every tag reuses; begin keys them.
inner: Sha384 H(K XOR ipad, …): keyed by begin, fed the message by update.
outer: Sha384 H(K XOR opad, …): keyed by begin, fed the inner digest by finishInto.
begin(key: u8[], off: i32, len: i32): void Keys a new computation with key[off .. off + len), a key longer than 128 bytes by its SHA-384 (RFC 2104 §2).
finishInto(out: u8[], at: i32): void Writes the 48-byte tag at out[at] and ends the computation; a window outside out panics.
update(data: u8[], off: i32, len: i32): void Absorbs data[off .. off + len); a window outside data panics in the hasher.
wipe(): void Zeroes both keyed hashers, for a caller done with the key; begin starts again.

HmacSha512

HMAC-SHA-512 in progress (RFC 2104 with RFC 4231's SHA-512), with HmacSha256's methods. The block is SHA-512's 128 bytes and the tag 64.

class HmacSha512
Member
new HmacSha512(key: u8[]) Keys the computation. A key longer than 128 bytes is replaced by its SHA-512 (RFC 2104 §2).
inner: Sha512 H(K XOR ipad, …), fed the key block in the constructor and the message after.
outer: Sha512 H(K XOR opad, …), fed the key block in the constructor and the inner digest last.
digest(): u8[] Ends the computation and wipes both hashers.
update(data: u8[], off: i32, len: i32): void Absorbs data[off .. off + len); a window outside data panics in Sha512.update.

Constants

1

HMAC_SHA256: i32

HmacKey's hash: HMAC-SHA-256.

2

HMAC_SHA384: i32

HmacKey's hash: HMAC-SHA-384.

3

HMAC_SHA512: i32

HmacKey's hash: HMAC-SHA-512.