randBitsSync

README.md

@@ -18,7 +18,7 @@ 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.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.mod.js) from GitHub.
+For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.min.mod.js) from GitHub.
 
 ## Usage examples
 
@@ -96,6 +96,77 @@ primeTesting()
 
 ## API reference documentation
 
+### Functions
+
+<dl>
+<dt><a href="#abs">abs(a)</a> ⇒ <code>bigint</code></dt>
+<dd><p>Absolute value. abs(a)==a if a&gt;=0. abs(a)==-a if a&lt;0</p>
+</dd>
+<dt><a href="#bitLength">bitLength(a)</a> ⇒ <code>number</code></dt>
+<dd><p>Returns the bitlength of a number</p>
+</dd>
+<dt><a href="#eGcd">eGcd(a, b)</a> ⇒ <code><a href="#egcdReturn">egcdReturn</a></code></dt>
+<dd><p>An iterative implementation of the extended euclidean algorithm or extended greatest common divisor algorithm.
+Take positive integers a, b as input, and return a triple (g, x, y), such that ax + by = g = gcd(a, b).</p>
+</dd>
+<dt><a href="#gcd">gcd(a, b)</a> ⇒ <code>bigint</code></dt>
+<dd><p>Greatest-common divisor of two integers based on the iterative binary algorithm.</p>
+</dd>
+<dt><a href="#lcm">lcm(a, b)</a> ⇒ <code>bigint</code></dt>
+<dd><p>The least common multiple computed as abs(a*b)/gcd(a,b)</p>
+</dd>
+<dt><a href="#max">max(a, b)</a> ⇒ <code>bigint</code></dt>
+<dd><p>Maximum. max(a,b)==a if a&gt;=b. max(a,b)==b if a&lt;=b</p>
+</dd>
+<dt><a href="#min">min(a, b)</a> ⇒ <code>bigint</code></dt>
+<dd><p>Minimum. min(a,b)==b if a&gt;=b. min(a,b)==a if a&lt;=b</p>
+</dd>
+<dt><a href="#modInv">modInv(a, n)</a> ⇒ <code>bigint</code></dt>
+<dd><p>Modular inverse.</p>
+</dd>
+<dt><a href="#modPow">modPow(b, e, n)</a> ⇒ <code>bigint</code></dt>
+<dd><p>Modular exponentiation b**e mod n. Currently using the right-to-left binary method</p>
+</dd>
+<dt><a href="#toZn">toZn(a, n)</a> ⇒ <code>bigint</code></dt>
+<dd><p>Finds the smallest positive element that is congruent to a in modulo n</p>
+</dd>
+<dt><a href="#isProbablyPrime">isProbablyPrime(w, [iterations])</a> ⇒ <code>Promise.&lt;boolean&gt;</code></dt>
+<dd><p>The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
+iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)</p>
+</dd>
+<dt><a href="#prime">prime(bitLength, [iterations])</a> ⇒ <code>Promise.&lt;bigint&gt;</code></dt>
+<dd><p>A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator.
+The browser version uses web workers to parallelise prime look up. Therefore, it does not lock the UI
+main process, and it can be much faster (if several cores or cpu are available).
+The node version can also use worker_threads if they are available (enabled by default with Node 11 and
+and can be enabled at runtime executing node --experimental-worker with node &gt;=10.5.0).</p>
+</dd>
+<dt><a href="#primeSync">primeSync(bitLength, [iterations])</a> ⇒ <code>bigint</code></dt>
+<dd><p>A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator.
+The sync version is NOT RECOMMENDED since it won&#39;t use workers and thus it&#39;ll be slower and may freeze thw window in browser&#39;s javascript. Please consider using prime() instead.</p>
+</dd>
+<dt><a href="#randBetween">randBetween(max, [min])</a> ⇒ <code>bigint</code></dt>
+<dd><p>Returns a cryptographically secure random integer between [min,max]</p>
+</dd>
+<dt><a href="#randBits">randBits(bitLength, [forceLength])</a> ⇒ <code>Buffer</code> | <code>Uint8Array</code></dt>
+<dd><p>Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()</p>
+</dd>
+<dt><a href="#randBytes">randBytes(byteLength, [forceLength])</a> ⇒ <code>Promise.&lt;(Buffer|Uint8Array)&gt;</code></dt>
+<dd><p>Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()</p>
+</dd>
+<dt><a href="#randBytesSync">randBytesSync(byteLength, [forceLength])</a> ⇒ <code>Buffer</code> | <code>Uint8Array</code></dt>
+<dd><p>Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()</p>
+</dd>
+</dl>
+
+### Typedefs
+
+<dl>
+<dt><a href="#egcdReturn">egcdReturn</a> : <code>Object</code></dt>
+<dd><p>A triple (g, x, y), such that ax + by = g = gcd(a, b).</p>
+</dd>
+</dl>
+
 <a name="abs"></a>
 
 ### abs(a) ⇒ <code>bigint</code>

build/build.docs.js

@@ -14,8 +14,8 @@ const source = fs.readFileSync(input, { encoding: 'UTF-8' }).replace(/([0-9]+)n(
 const options = {
   source, // we need to use this instead of files in order to avoid issues with esnext features
   template: fs.readFileSync(template, { encoding: 'UTF-8' }),
-  'heading-depth': 3, // The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading"
+  'heading-depth': 3 // The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading"
-  'global-index-format': 'none' // none, grouped, table, dl.
+  // 'global-index-format': 'none' // none, grouped, table, dl.
 }
 
 jsdoc2md.clear().then(() => {

build/build.dts.js

@@ -4,7 +4,7 @@ const path = require('path')
 const pkgJson = require('../package.json')
 
 const rootDir = path.join(__dirname, '..')
-const jsFile = path.join(rootDir, pkgJson.browser)
+const jsFile = path.join(rootDir, pkgJson.directories.lib, 'index.browser.bundle.mod.js')
 const dtsFile = path.join(rootDir, pkgJson.types)
 
 const compilerOptions = {

build/rollup.tests.config.js

@@ -21,7 +21,7 @@ const dstDir = path.join(rootDir, pkgJson.directories.test, 'browser')
 const dstFileName = path.join(dstDir, 'index.html')
 
 const template = fs.readFileSync(templatePath, 'utf-8')
-const bundleFile = path.join(rootDir, pkgJson.directories.lib, 'index.browser.bundle.mod.js')
+const bundleFile = path.join(rootDir, pkgJson.directories.lib, 'index.browser.bundle.min.mod.js')
 const testsJs = `
     <script type="module">
         import * as _pkg from '${path.relative(templatePath, bundleFile)}'

lib/index.browser.mod.js

@@ -113,7 +113,7 @@ function primeSync (bitLength, iterations = 16) {
   if (bitLength < 1) { throw new RangeError(`bitLength MUST be > 0 and it is ${bitLength}`) }
   let rnd = 0n
   do {
-    rnd = fromBuffer(randBytesSync(bitLength / 8, true))
+    rnd = fromBuffer(randBits(bitLength, true))
   } while (!_isProbablyPrime(rnd, iterations))
   return rnd
 }

lib/index.node.js

@@ -65,7 +65,7 @@ function prime (bitLength, iterations = 16) {
   if (!_useWorkers) {
     let rnd = 0n
     do {
-      rnd = fromBuffer(randBytesSync(bitLength / 8, true))
+      rnd = fromBuffer(randBits(bitLength, true))
     } while (!_isProbablyPrime(rnd, iterations))
     return new Promise((resolve) => { resolve(rnd) })
   }
@@ -131,7 +131,7 @@ function primeSync (bitLength, iterations = 16) {
   if (bitLength < 1) { throw new RangeError(`bitLength MUST be > 0 and it is ${bitLength}`) }
   let rnd = 0n
   do {
-    rnd = fromBuffer(randBytesSync(bitLength / 8, true))
+    rnd = fromBuffer(randBits(bitLength, true))
   } while (!_isProbablyPrime(rnd, iterations))
   return rnd
 }

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "bigint-crypto-utils",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigint-crypto-utils",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "description": "Utils for working with cryptography using native JS implementation of BigInt. It includes arbitrary precision modular arithmetic, cryptographically secure random numbers and strong probable prime generation/testing.",
   "keywords": [
     "modular arithmetics",

src/doc/readme-template.md

@@ -18,7 +18,7 @@ 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.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.mod.js) from GitHub.
+For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.min.mod.js) from GitHub.
 
 ## Usage examples
 

src/js/index.js

@@ -81,7 +81,7 @@ export function prime (bitLength, iterations = 16) {
   if (!process.browser && !_useWorkers) {
     let rnd = 0n
     do {
-      rnd = fromBuffer(randBytesSync(bitLength / 8, true))
+      rnd = fromBuffer(randBits(bitLength, true))
     } while (!_isProbablyPrime(rnd, iterations))
     return new Promise((resolve) => { resolve(rnd) })
   }
@@ -154,7 +154,7 @@ export function primeSync (bitLength, iterations = 16) {
   if (bitLength < 1) { throw new RangeError(`bitLength MUST be > 0 and it is ${bitLength}`) }
   let rnd = 0n
   do {
-    rnd = fromBuffer(randBytesSync(bitLength / 8, true))
+    rnd = fromBuffer(randBits(bitLength, true))
   } while (!_isProbablyPrime(rnd, iterations))
   return rnd
 }

test/browser/index.html

@@ -13,7 +13,7 @@
     <script>mocha.setup('bdd'); mocha.setup({ timeout: 90000 });</script>
 
     <script type="module">
-        import * as _pkg from '../../../lib/index.browser.bundle.mod.js'
+        import * as _pkg from '../../../lib/index.browser.bundle.min.mod.js'
         window._pkg = _pkg;
         import './tests.js';
         mocha.run();

types/index.d.ts

@@ -1,3 +1,51 @@
+/**
+ * A triple (g, x, y), such that ax + by = g = gcd(a, b).
+ */
+export type egcdReturn = {
+    g: bigint;
+    x: bigint;
+    y: bigint;
+};
+/**
+ * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
+ *
+ * @param {number|bigint} a
+ *
+ * @returns {bigint} the absolute value of a
+ */
+export function abs(a: number | bigint): bigint;
+/**
+ * Returns the bitlength of a number
+ *
+ * @param {number|bigint} a
+ * @returns {number} - the bit length
+ */
+export function bitLength(a: number | bigint): number;
+/**
+ * @typedef {Object} egcdReturn A triple (g, x, y), such that ax + by = g = gcd(a, b).
+ * @property {bigint} g
+ * @property {bigint} x
+ * @property {bigint} y
+ */
+/**
+ * An iterative implementation of the extended euclidean algorithm or extended greatest common divisor algorithm.
+ * Take positive integers a, b as input, and return a triple (g, x, y), such that ax + by = g = gcd(a, b).
+ *
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {egcdReturn} A triple (g, x, y), such that ax + by = g = gcd(a, b).
+ */
+export function eGcd(a: number | bigint, b: number | bigint): egcdReturn;
+/**
+ * Greatest-common divisor of two integers based on the iterative binary algorithm.
+ *
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {bigint} The greatest common divisor of a and b
+ */
+export function gcd(a: number | bigint, b: number | bigint): bigint;
 /**
  * The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
  * iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)
@@ -8,6 +56,51 @@
  * @return {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
  */
 export function isProbablyPrime(w: number | bigint, iterations?: number): Promise<boolean>;
+/**
+ * The least common multiple computed as abs(a*b)/gcd(a,b)
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {bigint} The least common multiple of a and b
+ */
+export function lcm(a: number | bigint, b: number | bigint): bigint;
+/**
+ * Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b
+ *
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {bigint} maximum of numbers a and b
+ */
+export function max(a: number | bigint, b: number | bigint): bigint;
+/**
+ * Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b
+ *
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {bigint} minimum of numbers a and b
+ */
+export function min(a: number | bigint, b: number | bigint): bigint;
+/**
+ * Modular inverse.
+ *
+ * @param {number|bigint} a The number to find an inverse for
+ * @param {number|bigint} n The modulo
+ *
+ * @returns {bigint} the inverse modulo n or NaN if it does not exist
+ */
+export function modInv(a: number | bigint, n: number | bigint): bigint;
+/**
+ * Modular exponentiation b**e mod n. Currently using the right-to-left binary method
+ *
+ * @param {number|bigint} b base
+ * @param {number|bigint} e exponent
+ * @param {number|bigint} n modulo
+ *
+ * @returns {bigint} b**e mod n
+ */
+export function modPow(b: number | bigint, e: number | bigint, n: number | bigint): bigint;
 /**
  * A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator.
  * The browser version uses web workers to parallelise prime look up. Therefore, it does not lock the UI
@@ -75,4 +168,11 @@ export function randBytes(byteLength: number, forceLength?: boolean): Promise<Ui
  * @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
  */
 export function randBytesSync(byteLength: number, forceLength?: boolean): Uint8Array | Buffer;
-export { abs, bitLength, eGcd, gcd, lcm, max, min, modInv, modPow, toZn } from "bigint-mod-arith";
+/**
+ * Finds the smallest positive element that is congruent to a in modulo n
+ * @param {number|bigint} a An integer
+ * @param {number|bigint} n The modulo
+ *
+ * @returns {bigint} The smallest positive representation of a in modulo n
+ */
+export function toZn(a: number | bigint, n: number | bigint): bigint;