LumeWeb
/
bigint-crypto-utils
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

randBitsSync

This commit is contained in:
juanelas 2020-04-07 19:35:38 +02:00
parent c52d54f66b 29faa429bb
commit 5c410d60c1
13 changed files with 187 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
README.md
View File

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

4
build/build.docs.js
View File

@ -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"
'global-index-format': 'none' // none, grouped, table, dl.
'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.
}
jsdoc2md.clear().then(() => {

2
build/build.dts.js
View File

@ -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 = {

2
build/rollup.tests.config.js
View File

@ -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)}'

1
lib/index.browser.bundle.min.mod.js Normal file
View File

File diff suppressed because one or more lines are too long

2
lib/index.browser.mod.js
View File

@ -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
}

4
lib/index.node.js
View File

@ -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
}

2
package-lock.json generated
View File

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

2
package.json
View File

@ -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",

2
src/doc/readme-template.md
View File

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

4
src/js/index.js
View File

@ -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
}

2
test/browser/index.html
View File

@ -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();

102
types/index.d.ts vendored
View File

@ -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;