browser-hmac-obj v0.1.2

BrowserHMACObj

BrowserHMACObj 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 browsers Crypto.subtle method, and also makes it possible to get multiple different digest methods with a little help of BaseEx.

Installation

GitHub

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

npm

nmp install browser-hmac-obj

Builds

You can find builds in dist. If you want to build by yourself run:

npm run build

Two types are available (esm and iife), plus a minified version of each.

• BrowserHMACObj.esm.js
• BrowserHMACObj.esm.min.js
• BrowserHMACObj.iife.js
• BrowserHMACObj.iife.min.js

Usage

Importing

BrowserHMACObj is a ESM module and exported as default. Importing works as follows:

// esm
import BrowserHMACObj from "./path/BrowserHMACObj.esm.min.js";

// esm from CDN (jsdelivr)
import BrowseHMACObj from "https://cdn.jsdelivr.net/npm/browser-hmac-obj@latest/dist/BrowserHMACObj.esm.min.js"

<!-- script tag -->
<script src="./path/BrowserHMACObj.iife.min.js"></script>

<!-- script tag from CDN (jsdelivr)-->
<script src="https://cdn.jsdelivr.net/npm/browser-hmac-obj@latest/dist/BrowserHMACObj.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 methods available to create an instance:

new operator

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

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

BrowserHMACObj.digestmodsAvailable()

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

BrowserHMACObj.keyFormats()

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

BrowserHMACObj.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.

BrowserHMACObj.generateKey()

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

BrowserHMACObj.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.

BrowserHMACObj.baseEx

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 hmacring 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

This work is licensed under GPL-3.0.