HMACObj

HMACObj creates a HMAC-SHA-(1/256/384/512) object. It is related to pythons hmac libary in its methods and features but with many extras. It provides an easy access to the Crypto.subtle method provided by modern browsers and node.js.

Optionally it possible to get multiple different digest methods with a little help of BaseEx. BaseEx also enables the feature to feed the HMAC Object with not just byte-like input but almost any type available in JavaScript.

Installation

GitHub

git clone https://github.com/UmamiAppearance/HMACObj.git

npm

nmp install hmac-obj

Builds

You can find builds in dist. Builds include versions with BaseEx build in and without the library. Two types for both kinds are available (esm and iife), plus a minified version of each.

If you want to build it by yourself run:

npm run build

Builds with BaseEx included

• hmac-obj-bex.esm.js
• hmac-obj-bex.esm.min.js
• hmac-obj-bex.iife.js
• hmac-obj-bex.iife.min.js

Builds without BaseEx (make sure BaseEx is globally available)

• hmac-obj.esm.js
• hmac-obj.esm.min.js
• hmac-obj.iife.js
• hmac-obj.iife.min.js

Usage

Importing

node.js

esm

import HMACObj from "hmac-obj";

cjs

const HMACObj = require("hmac-obj");

Browser

esm

import HMACObj from "./path/hmac-obj-bex.esm.min.js";

esm from CDN (jsdelivr)

import HMACObj from "https://cdn.jsdelivr.net/npm/hmac-obj@latest/dist/hmac-obj-bex.esm.min.js"

iife script tag

<script src="./path/hmac-obj-bex.iife.min.js"></script>

iife script tag from CDN (jsdelivr)

<script src="https://cdn.jsdelivr.net/npm/hmac-obj@latest/dist/hmac-obj-bex.iife.min.js"></script>

Creating an instance

The constructor takes one argument for the digestmod. Available options are:

• SHA-1
• SHA-256
• SHA-384
• SHA-512

There a two possible ways available to create an instance:

the new operator

const hmacSHA256 = new HMACObj("SHA-256");

the new method

This method is asynchronous to allow you to associate a message in one go.

const hmacSHA512 = await HMACObj.new("super_secret_key", "Hello World!", "SHA-512");

Methods and Properties

Static

HMACObj.digestmodsAvailable()

A set containing the names of the hash algorithms that are available.

HMACObj.keyFormats()

Static method to receive a set of the available key formats.

HMACObj.new(key=null, msg=null, digestmod=""[, keyFormat="raw", permitExports=false])

Asynchronously creates a new instance. In contrast to the regular new operator a message and key can be provided. If a message is set, a key must also be handed over or a crypto key gets generated automatically.

A message gets passed to the update method.

HMACObj.generateKey(digestmod=""[, permitExports=false])

Static asynchronous method to generate a crypto key for the HMAC algorithm.

HMACObj.compareDigest(a, b)

Return a === b. This function uses an approach designed to prevent timing analysis by avoiding content-based short circuiting behavior, making it appropriate for cryptography.

a and b (or more precisely their byte representation) must both be of the same type.

HMACObj.baseEx [object]

A BaseEx Instance for the possibility to manually convert (byte) representations.

Instance

digestSize [property]

The size of the resulting HMAC in bytes.

blockSize [property]

The internal block size of the hash algorithm in bytes.

name [property]

The canonical name of this HMAC, always uppercase and always suitable as a parameter to create another HMAC of this type.

update(input[, replace=false])

Update the HMAC object with almost any input. The input gets converted to a Uint8Array. Unless replace is set to true, repeated calls are equivalent to a single call with the concatenation of all the arguments:
hmacObj.update(a); hmacObj.update(b) is in many occasions equivalent to hmacObj.update(a+b).

(Note: The process is a concatenation of bytes. Take as an exception for instance hmacObj.update(1); hmacObj.update(2), which is not the same as hmacObj.update(1+2))

replace(input)

Replace the the HMAC object with fresh input (the same as update(input, true)).

sign(msg[, base=null])

Signs a single message independent from the current instance message. If a base is provided, the key gets returned in the corresponding base representation.

verify(msg, signature)

A given message (msg) and signature can be tested if it is signed with the current instance crypto key.

setKey(cryptoKey)

Method to set or replace the associated crypto key. The key must be as provided of the Web Crypto API.

generateKey(permitExports=true)

Like the static method, with the difference, that the key is not returned but assigned to the instance. By default the key is exportable.

importKey(key[, format="raw", permitExports=false])

Import a Crypto Key from almost any input or a pre existing key.

exportKey(format="raw")

Exports the Crypto Key assigned to the instance, if it is an exportable key.

digest()

Return the digest of the data passed to the update method so far. This is an ArrayBuffer of size digestSize.

hexdigest()

Like digest except the digest is returned as a string of double length, containing only hexadecimal digits. This may be used (as one of many options) to exchange the value safely in non-binary environments.

basedigest (object)

Provides many different methods to convert the digest into different base representations. Take a look at the live-examples, to see it in action.
Every basedigest optionally takes additional BaseEx Parameters.

copy()

Async method to return a copy/clone of the HMAC object. This can be used to efficiently compute the digests of data sharing a common initial substring.

Examples

Here you can find many live-examples. To get a better idea of a possible use case, take a look at the Online HMAC Generator.

License

MIT

Copyright (c) 2023, UmamiAppearance