[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com) # bigint-crypto-utils Utils for working with cryptography using native JS ([ES-2020](https://tc39.es/ecma262/#sec-bigint-objects)) implementation of BigInt. It includes some extra functions to work with modular arithmetic along with secure random numbers and a fast strong probable prime generator/tester (parallelized multi-threaded Miller-Rabin primality tests if workers are supported). It can be used by any [Web Browser or webview supporting BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#Browser_compatibility) and with Node.js (>=10.4.0). > The operations supported on BigInts are not constant time. BigInt can be therefore **[unsuitable for use in cryptography](https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html).** Many platforms provide native support for cryptography, such as [Web Cryptography API](https://w3c.github.io/webcrypto/) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html). ## Installation bigint-crypto-utils is distributed for [web browsers and/or webviews supporting BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#Browser_compatibility) as an ES6 module or an IIFE file; and for Node.js (>=10.4.0), as a CJS module. bigint-crypto-utils can be imported to your project with `npm`: ```bash npm install bigint-crypto-utils ``` NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js. For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.iife.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.mod.js) from GitHub. ## Usage examples Import your module as : - Node.js ```javascript const bigintCryptoUtils = require('bigint-crypto-utils') ... // your code here ``` - JavaScript native or TypeScript project ```javascript import * as bigintCryptoUtils from 'bigint-crypto-utils' ... // your code here ``` > BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`. - JavaScript native browser ES6 mod ```html ``` - JavaScript native browser IIFE ```html
... ... ``` An example of usage could be: ```javascript /* A BigInt with value 666 can be declared calling the bigint constructor as BigInt('666') or with the shorter 666n. Notice that you can also pass a number to the constructor, e.g. BigInt(666). However, it is not recommended since values over 2**53 - 1 won't be safe but no warning will be raised. */ const a = BigInt('5') const b = BigInt('2') const n = 19n console.log(bigintCryptoUtils.modPow(a, b, n)) // prints 6 console.log(bigintCryptoUtils.modInv(2n, 5n)) // prints 3 console.log(bigintCryptoUtils.modInv(BigInt('3'), BigInt('5'))) // prints 2 console.log(bigintCryptoUtils.randBetween(2n ** 256n)) // Prints a cryptographically secure random number between 1 and 2**256 bits. async function primeTesting () { // Output of a probable prime of 2048 bits console.log(await bigintCryptoUtils.prime(2048)) // Testing if a number is a probable prime (Miller-Rabin) const number = 27n const isPrime = await bigintCryptoUtils.isProbablyPrime(number) if (isPrime) { console.log(`${number} is prime`) } else { console.log(`${number} is composite`) } } primeTesting() ``` You can find examples in the [examples folder of the repository](https://github.com/juanelas/bigint-crypto-utils/tree/master/examples). ## API reference documentation {{>main}}