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();
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.
hmacCopySha384
hmacCopySha256 for SHA-384: to made the hasher from is, in place.
hmacKeyedInto
The tag of data[off .. off + len) under key, written at out[at .. at + key.size()).
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.
hmacSha256
The HMAC-SHA-256 of all of data under key, as a fresh 32-byte array.
hmacSha256Secret
hmacSha256 under a key held as a Secret, read only inside exposeWith.
hmacSha256Verify
Whether tag is the HMAC-SHA-256 of data under key, compared by timingSafeEqual.
hmacSha384
The HMAC-SHA-384 of all of data under key, as a fresh 48-byte array.
hmacSha384Secret
hmacSha384 under a key held as a Secret, as hmacSha256Secret is.
hmacSha384Verify
Whether tag is the HMAC-SHA-384 of data under key, compared as hmacSha256Verify does.
hmacSha512
The HMAC-SHA-512 of all of data under key, as a fresh 64-byte array.
hmacSha512Secret
hmacSha512 under a key held as a Secret, as hmacSha256Secret is.
hmacSha512Verify
Whether tag is the HMAC-SHA-512 of data under key, compared as hmacSha256Verify does.
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.
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[]>.
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.
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.
HmacSha384
HMAC-SHA-384 in progress (RFC 2104 with RFC 4231's SHA-384), with HmacSha256's methods.
HmacSha384Scratch
HMAC-SHA-384 over hashers the caller owns, with HmacSha256Scratch's methods.
HmacSha512
HMAC-SHA-512 in progress (RFC 2104 with RFC 4231's SHA-512), with HmacSha256's methods.
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
fromSha256requiredThe hasher to copy; it is not changed.
toSha256requiredThe 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
fromSha384requiredThe hasher to copy; it is not changed.
toSha384requiredThe 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
keyHmacKeyrequiredThe absorbed key; a wiped one panics.
datau8[]requiredThe buffer holding the message.
offi32requiredWhere the message starts in data.
leni32requiredThe message's length in bytes.
outu8[]requiredThe caller's array the tag is written into.
ati32requiredWhere 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
keyHmacKeyrequiredThe absorbed key; a wiped one answers false.
datau8[]requiredThe buffer holding the message.
offi32requiredWhere the message starts in data.
leni32requiredThe message's length in bytes.
tagu8[]requiredThe buffer holding the tag to check.
tagAti32requiredWhere the tag starts in tag.
returnsbooleantrue 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[]requiredThe secret key; it is read, not kept.
datau8[]requiredThe 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[]>requiredThe secret key; the caller still owns and wipes it.
datau8[]requiredThe 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[]requiredThe secret key.
datau8[]requiredThe whole message the tag claims to cover.
tagu8[]requiredThe tag to check, as received.
returnsbooleantrue 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[]requiredThe secret key; it is read, not kept.
datau8[]requiredThe 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[]>requiredThe secret key; the caller still owns and wipes it.
datau8[]requiredThe 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[]requiredThe secret key.
datau8[]requiredThe whole message the tag claims to cover.
tagu8[]requiredThe tag to check, as received.
returnsbooleantrue 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[]requiredThe secret key; it is read, not kept.
datau8[]requiredThe 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[]>requiredThe secret key; the caller still owns and wipes it.
datau8[]requiredThe 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[]requiredThe secret key.
datau8[]requiredThe whole message the tag claims to cover.
tagu8[]requiredThe tag to check, as received.
returnsbooleantrue 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[]requiredThe salt S, public.
iterationsi32requiredThe round count c; below 1 answers null.
lengthi32required
The derived key's length dkLen in bytes; below 1 answers
null.
returnsSecret<u8[]> | nullThe 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.

