hmac-obj
v1.0.6
Published
JavaScript implementation of HMAC generation and verification for the browser and node.js.
Downloads
52
Maintainers
Readme
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
Builds without BaseEx (make sure BaseEx
is globally available)
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
Copyright (c) 2023, UmamiAppearance