2025-06-21 23:30:33 +03:00

207 lines
6.4 KiB
TypeScript

// Copyright (C) 2016 Dmitry Chestnykh
// MIT License. See LICENSE file for details.
/**
* Package hmac implements HMAC algorithm.
*/
import { Hash, SerializableHash, isSerializableHash } from "@stablelib/hash";
import { equal as constantTimeEqual } from "@stablelib/constant-time";
import { wipe } from "@stablelib/wipe";
/**
* HMAC implements hash-based message authentication algorithm.
*/
export class HMAC implements SerializableHash {
readonly blockSize: number;
readonly digestLength: number;
private _inner: Hash; // inner hash
private _outer: Hash; // outer hash
private _finished = false; // true if HMAC was finalized
// Copies of hash states after keying.
// Need for quick reset without hashing the key again.
private _innerKeyedState: any | undefined;
private _outerKeyedState: any | undefined;
/**
* Constructs a new HMAC with the given Hash and secret key.
*/
constructor(hash: new () => Hash | SerializableHash, key: Uint8Array) {
// Initialize inner and outer hashes.
this._inner = new hash();
this._outer = new hash();
// Set block and digest sizes for this HMAC
// instance to values from the hash.
this.blockSize = this._outer.blockSize;
this.digestLength = this._outer.digestLength;
// Pad temporary stores a key (or its hash) padded with zeroes.
const pad = new Uint8Array(this.blockSize);
if (key.length > this.blockSize) {
// If key is bigger than hash block size, it must be
// hashed and this hash is used as a key instead.
this._inner.update(key).finish(pad).clean();
} else {
// Otherwise, copy the key into pad.
pad.set(key);
}
// Now two different keys are derived from padded key
// by xoring a different byte value to each.
// To make inner hash key, xor byte 0x36 into pad.
for (let i = 0; i < pad.length; i++) {
pad[i] ^= 0x36;
}
// Update inner hash with the result.
this._inner.update(pad);
// To make outer hash key, xor byte 0x5c into pad.
// But since we already xored 0x36 there, we must
// first undo this by xoring it again.
for (let i = 0; i < pad.length; i++) {
pad[i] ^= 0x36 ^ 0x5c;
}
// Update outer hash with the result.
this._outer.update(pad);
// Save states of both hashes, so that we can quickly restore
// them later in reset() without the need to remember the actual
// key and perform this initialization again.
if (isSerializableHash(this._inner) && isSerializableHash(this._outer)) {
this._innerKeyedState = this._inner.saveState();
this._outerKeyedState = this._outer.saveState();
}
// Clean pad.
wipe(pad);
}
/**
* Returns HMAC state to the state initialized with key
* to make it possible to run HMAC over the other data with the same
* key without creating a new instance.
*/
reset(): this {
if (!isSerializableHash(this._inner) || !isSerializableHash(this._outer)) {
throw new Error("hmac: can't reset() because hash doesn't implement restoreState()");
}
// Restore keyed states of inner and outer hashes.
this._inner.restoreState(this._innerKeyedState);
this._outer.restoreState(this._outerKeyedState);
this._finished = false;
return this;
}
/**
* Cleans HMAC state.
*/
clean() {
if (isSerializableHash(this._inner)) {
this._inner.cleanSavedState(this._innerKeyedState);
}
if (isSerializableHash(this._outer)) {
this._outer.cleanSavedState(this._outerKeyedState);
}
this._inner.clean();
this._outer.clean();
}
/**
* Updates state with provided data.
*/
update(data: Uint8Array): this {
this._inner.update(data);
return this;
}
/**
* Finalizes HMAC and puts the result in out.
*/
finish(out: Uint8Array): this {
if (this._finished) {
// If HMAC was finalized, outer hash is also finalized,
// so it produces the same digest it produced when it
// was finalized.
this._outer.finish(out);
return this;
}
// Finalize inner hash and store the result temporarily.
this._inner.finish(out);
// Update outer hash with digest of inner hash and and finalize it.
this._outer.update(out.subarray(0, this.digestLength)).finish(out);
this._finished = true;
return this;
}
/**
* Returns the computed message authentication code.
*/
digest(): Uint8Array {
const out = new Uint8Array(this.digestLength);
this.finish(out);
return out;
}
/**
* Saves HMAC state.
* This function is needed for PBKDF2 optimization.
*/
saveState(): any {
if (!isSerializableHash(this._inner)) {
throw new Error("hmac: can't saveState() because hash doesn't implement it");
}
return this._inner.saveState();
}
restoreState(savedState: any): this {
if (!isSerializableHash(this._inner) || !isSerializableHash(this._outer)) {
throw new Error("hmac: can't restoreState() because hash doesn't implement it");
}
this._inner.restoreState(savedState);
this._outer.restoreState(this._outerKeyedState);
this._finished = false;
return this;
}
cleanSavedState(savedState: any) {
if (!isSerializableHash(this._inner)) {
throw new Error("hmac: can't cleanSavedState() because hash doesn't implement it");
}
this._inner.cleanSavedState(savedState);
}
}
/**
* Returns HMAC using the given hash constructor for the key over data.
*/
export function hmac(hash: new () => Hash, key: Uint8Array, data: Uint8Array): Uint8Array {
const h = new HMAC(hash, key);
h.update(data);
const digest = h.digest();
h.clean();
return digest;
}
/**
* Returns true if two HMAC digests are equal.
* Uses constant-time comparison to avoid leaking timing information.
*
* Example:
*
* const receivedDigest = ...
* const realDigest = hmac(SHA256, key, data);
* if (!equal(receivedDigest, realDigest)) {
* throw new Error("Authentication error");
* }
*/
export const equal = constantTimeEqual;