{"id":25925317,"url":"https://github.com/umamiappearance/hmacobj","last_synced_at":"2025-03-03T18:47:55.466Z","repository":{"id":65187963,"uuid":"585891910","full_name":"UmamiAppearance/HMACObj","owner":"UmamiAppearance","description":"JavaScript implementation of HMAC generation and verification for the browser and node.js. It uses the global SubtleCrypto interface [Web Crypto API]. Multiple representations of the HMAC are available (e.g. hexadecimal, base32, base64, ...) ","archived":false,"fork":false,"pushed_at":"2023-07-16T21:39:56.000Z","size":265,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-07T03:47:38.869Z","etag":null,"topics":["browser","crypto","cryptography","hmac","hmac-sha1","hmac-sha256","hmac-sha384","hmac-sha512","subtlecrypto","webcrypto-api"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UmamiAppearance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2023-01-06T11:13:42.000Z","updated_at":"2023-01-06T11:21:43.000Z","dependencies_parsed_at":"2023-02-19T08:00:34.224Z","dependency_job_id":null,"html_url":"https://github.com/UmamiAppearance/HMACObj","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmamiAppearance%2FHMACObj","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmamiAppearance%2FHMACObj/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmamiAppearance%2FHMACObj/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmamiAppearance%2FHMACObj/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UmamiAppearance","download_url":"https://codeload.github.com/UmamiAppearance/HMACObj/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241723132,"owners_count":20009412,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","crypto","cryptography","hmac","hmac-sha1","hmac-sha256","hmac-sha384","hmac-sha512","subtlecrypto","webcrypto-api"],"created_at":"2025-03-03T18:47:54.221Z","updated_at":"2025-03-03T18:47:55.447Z","avatar_url":"https://github.com/UmamiAppearance.png","language":"JavaScript","readme":"# HMACObj\n\n[![License](https://img.shields.io/github/license/UmamiAppearance/HMACObj?color=009911\u0026style=for-the-badge)](./LICENSE)\n[![npm](https://img.shields.io/npm/v/hmac-obj?color=%23009911\u0026style=for-the-badge)](https://www.npmjs.com/package/hmac-obj)\n\n\n**HMACObj** creates a HMAC-SHA-(1/256/384/512) object. It is related to [pythons hmac libary](https://docs.python.org/3/library/hmac.html) 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.  \n  \nOptionally it possible to get multiple different digest methods with a little help of [BaseEx](https://github.com/UmamiAppearance/BaseExJS). **BaseEx** also enables the feature to feed the HMAC Object with not just byte-like input but almost any type available in JavaScript. \n\n\n## Installation\n\n### GitHub\n```sh\ngit clone https://github.com/UmamiAppearance/HMACObj.git\n```\n\n### npm\n```sh\nnmp install hmac-obj\n```\n\n## Builds\nYou can find builds in [dist](https://github.com/UmamiAppearance/HMACObj/tree/main/dist). Builds include versions with BaseEx build in and without the library. Two types for both kinds are available ([esm](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and [iife](https://developer.mozilla.org/en-US/docs/Glossary/IIFE)), plus a minified version of each.  \n  \nIf you want to build it by yourself run:\n\n```sh\nnpm run build\n```\n\n#### Builds with BaseEx included\n* [``hmac-obj-bex.esm.js``](https://raw.githubusercontent.com/UmamiAppearance/HMACObj/main/dist/hmac-obj-bex.esm.js)\n* [``hmac-obj-bex.esm.min.js``](https://raw.githubusercontent.com/UmamiAppearance/HMACObj/main/dist/hmac-obj-bex.esm.min.js)\n* [``hmac-obj-bex.iife.js``](https://raw.githubusercontent.com/UmamiAppearance/HMACObj/main/dist/hmac-obj-bex.iife.js)\n* [``hmac-obj-bex.iife.min.js``](https://raw.githubusercontent.com/UmamiAppearance/HMACObj/main/dist/hmac-obj-bex.iife.min.js)\n\n#### Builds without BaseEx _(make sure `BaseEx` is globally available)_\n* [``hmac-obj.esm.js``](https://raw.githubusercontent.com/UmamiAppearance/HMACObj/main/dist/hmac-obj.esm.js)\n* [``hmac-obj.esm.min.js``](https://raw.githubusercontent.com/UmamiAppearance/HMACObj/main/dist/hmac-obj.esm.min.js)\n* [``hmac-obj.iife.js``](https://raw.githubusercontent.com/UmamiAppearance/HMACObj/main/dist/hmac-obj.iife.js)\n* [``hmac-obj.iife.min.js``](https://raw.githubusercontent.com/UmamiAppearance/HMACObj/main/dist/hmac-obj.iife.min.js)\n\n\n\n## Usage\n\n### Importing\n\n#### node.js\n\n##### esm\n```js\nimport HMACObj from \"hmac-obj\";\n```\n\n##### cjs\n```js\nconst HMACObj = require(\"hmac-obj\");\n```\n\n\n#### Browser\n\n##### esm\n```js\nimport HMACObj from \"./path/hmac-obj-bex.esm.min.js\";\n```\n\n##### esm from CDN (jsdelivr)\n```js\nimport HMACObj from \"https://cdn.jsdelivr.net/npm/hmac-obj@latest/dist/hmac-obj-bex.esm.min.js\"\n```\n\n##### iife script tag\n```html\n\u003cscript src=\"./path/hmac-obj-bex.iife.min.js\"\u003e\u003c/script\u003e\n```\n\n##### iife script tag from CDN (jsdelivr)\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/hmac-obj@latest/dist/hmac-obj-bex.iife.min.js\"\u003e\u003c/script\u003e\n```\n\n### Creating an instance    \nThe constructor takes one argument for the ``digestmod``. Available options are:\n* ``SHA-1``\n* ``SHA-256``\n* ``SHA-384``\n* ``SHA-512``\n\nThere a two possible ways available to create an instance:\n\n#### the new operator\n```js\nconst hmacSHA256 = new HMACObj(\"SHA-256\");\n```\n\n#### the new method\nThis method is asynchronous to allow you to associate a message in one go.\n```js\nconst hmacSHA512 = await HMACObj.new(\"super_secret_key\", \"Hello World!\", \"SHA-512\");\n```\n\n\n### Methods and Properties\n\n#### Static\n\n##### ``HMACObj.digestmodsAvailable()``\nA set containing the names of the hash algorithms that are available.\n\n##### ``HMACObj.keyFormats()``\nStatic method to receive a set of the available key formats.\n\n##### ``HMACObj.new(key=null, msg=null, digestmod=\"\"[, keyFormat=\"raw\", permitExports=false])``\nAsynchronously creates a new instance. In contrast to the regular [new operator](#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.  \n  \nA message gets passed to the [``update``](#updateinput-replacefalse) method.\n\n##### ``HMACObj.generateKey(digestmod=\"\"[, permitExports=false])``\nStatic asynchronous method to generate a crypto key for the HMAC algorithm.\n\n##### ``HMACObj.compareDigest(a, b)``\nReturn ``a === b``. This function uses an approach designed to prevent timing analysis by avoiding content-based short circuiting behavior, making it appropriate for cryptography.  \n\n``a`` and ``b`` (or more precisely their byte representation) must both be of the same type.\n\n##### ``HMACObj.baseEx`` _[object]_\nA [BaseEx Instance](https://github.com/UmamiAppearance/BaseExJS#available-converterscharsets) for the possibility to manually convert (byte) representations.\n\n#### Instance\n\n##### ``digestSize`` _[property]_\nThe size of the resulting HMAC in bytes.\n\n##### ``blockSize`` _[property]_\nThe internal block size of the hash algorithm in bytes.\n\n##### ``name`` _[property]_\nThe canonical name of this HMAC, always uppercase and always suitable as a parameter to create another HMAC of this type.\n\n##### ``update(input[, replace=false])``\nUpdate 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:  \n``hmacObj.update(a)``; ``hmacObj.update(b)`` is in many occasions equivalent to ``hmacObj.update(a+b)``.  \n  \n_(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)``)_\n\n##### ``replace(input)``\nReplace the the HMAC object with fresh input (the same as ``update(input, true)``).\n\n##### ``sign(msg[, base=null])``\nSigns a single message independent from the current instance message. If a base is provided, the key gets returned in the corresponding [base representation](https://umamiappearance.github.io/HMACObj/examples/live-examples.html#base-representations).\n\n##### ``verify(msg, signature)``\nA given message (``msg``) and ``signature`` can be tested if it is signed with the current instance crypto key.\n\n##### ``setKey(cryptoKey)``\nMethod to set or replace the associated crypto key. The key must be as provided of the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey).\n\n##### ``generateKey(permitExports=true)``\nLike the [static method](#hmacobjgeneratekey), with the difference, that the key is not returned but assigned to the instance. By default the key is exportable.\n\n##### ``importKey(key[, format=\"raw\", permitExports=false])``\nImport a Crypto Key from almost any input or a pre existing key.\n\n##### ``exportKey(format=\"raw\")``\nExports the Crypto Key assigned to the instance, if it is an exportable key.\n\n##### ``digest()``\nReturn the digest of the data passed to the [``update``](#updateinput-replacefalse) method so far. This is an ``ArrayBuffer`` of size [``digestSize``](#digestsize-property).\n\n##### ``hexdigest()``\nLike [``digest``](#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.\n\n##### ``basedigest`` _(object)_\nProvides many different methods to convert the digest into different base representations. Take a look at the [live-examples](https://umamiappearance.github.io/HMACObj/examples/live-examples.html#base-representations), to see it in action.  \nEvery ``basedigest`` optionally takes additional [BaseEx Parameters](https://github.com/UmamiAppearance/BaseExJS#options).\n\n##### ``copy()``\nAsync 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.\n\n\n## Examples\n[Here](https://umamiappearance.github.io/HMACObj/examples/live-examples.html) you can find many live-examples. To get a better idea of a possible use case, take a look at the [Online HMAC Generator](https://umamiappearance.github.io/HMACObj/examples/generator.html).\n\n\n## License\n\n[MIT](https://opensource.org/licenses/MIT)\n\nCopyright (c) 2023, UmamiAppearance\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumamiappearance%2Fhmacobj","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumamiappearance%2Fhmacobj","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumamiappearance%2Fhmacobj/lists"}