From 31af1f7e8a7265f9564cf24035efc07d96b291aa Mon Sep 17 00:00:00 2001 From: juanelas Date: Tue, 7 Apr 2020 19:13:23 +0200 Subject: [PATCH 1/5] fixed API reference --- README.md | 170 ++++++- build/build.docs.js | 18 +- build/rollup.config.js | 18 +- build/rollup.tests.config.js | 2 +- lib/index.browser.bundle.mod.js | 793 +++++++++++++++++++++++++++++++- package.json | 2 +- src/doc/readme-template.md | 2 +- test/browser/index.html | 2 +- 8 files changed, 987 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index a577c84..0dabd38 100644 --- a/README.md +++ b/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 + +
+
abs(a) ⇒ bigint
+

Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0

+
+
bitLength(a) ⇒ number
+

Returns the bitlength of a number

+
+
eGcd(a, b) ⇒ egcdReturn
+

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).

+
+
gcd(a, b) ⇒ bigint
+

Greatest-common divisor of two integers based on the iterative binary algorithm.

+
+
lcm(a, b) ⇒ bigint
+

The least common multiple computed as abs(a*b)/gcd(a,b)

+
+
max(a, b) ⇒ bigint
+

Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b

+
+
min(a, b) ⇒ bigint
+

Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b

+
+
modInv(a, n) ⇒ bigint
+

Modular inverse.

+
+
modPow(b, e, n) ⇒ bigint
+

Modular exponentiation b**e mod n. Currently using the right-to-left binary method

+
+
toZn(a, n) ⇒ bigint
+

Finds the smallest positive element that is congruent to a in modulo n

+
+
isProbablyPrime(w, [iterations]) ⇒ Promise.<boolean>
+

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)

+
+
prime(bitLength, [iterations]) ⇒ Promise.<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 +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 >=10.5.0).

+
+
primeSync(bitLength, [iterations]) ⇒ bigint
+

A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator. +The sync version is NOT RECOMMENDED since it won't use workers and thus it'll be slower and may freeze thw window in browser's javascript. Please consider using prime() instead.

+
+
randBetween(max, [min]) ⇒ bigint
+

Returns a cryptographically secure random integer between [min,max]

+
+
randBits(bitLength, [forceLength]) ⇒ Buffer | Uint8Array
+

Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()

+
+
randBytes(byteLength, [forceLength]) ⇒ Promise.<(Buffer|Uint8Array)>
+

Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()

+
+
randBytesSync(byteLength, [forceLength]) ⇒ Buffer | Uint8Array
+

Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()

+
+
+ +### Typedefs + +
+
egcdReturn : Object
+

A triple (g, x, y), such that ax + by = g = gcd(a, b).

+
+
+ ### abs(a) ⇒ bigint @@ -226,6 +297,103 @@ Finds the smallest positive element that is congruent to a in modulo n | a | number \| bigint | An integer | | n | number \| bigint | The modulo | + + +### isProbablyPrime(w, [iterations]) ⇒ Promise.<boolean> +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) + +**Kind**: global function +**Returns**: Promise.<boolean> - A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| w | number \| bigint | | An integer to be tested for primality | +| [iterations] | number | 16 | The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3 | + + + +### prime(bitLength, [iterations]) ⇒ Promise.<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 +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 >=10.5.0). + +**Kind**: global function +**Returns**: Promise.<bigint> - A promise that resolves to a bigint probable prime of bitLength bits. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| bitLength | number | | The required bit length for the generated prime | +| [iterations] | number | 16 | The number of iterations for the Miller-Rabin Probabilistic Primality Test | + + + +### primeSync(bitLength, [iterations]) ⇒ bigint +A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator. +The sync version is NOT RECOMMENDED since it won't use workers and thus it'll be slower and may freeze thw window in browser's javascript. Please consider using prime() instead. + +**Kind**: global function +**Returns**: bigint - A bigint probable prime of bitLength bits. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| bitLength | number | | The required bit length for the generated prime | +| [iterations] | number | 16 | The number of iterations for the Miller-Rabin Probabilistic Primality Test | + + + +### randBetween(max, [min]) ⇒ bigint +Returns a cryptographically secure random integer between [min,max] + +**Kind**: global function +**Returns**: bigint - A cryptographically secure random bigint between [min,max] + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| max | bigint | | Returned value will be <= max | +| [min] | bigint | BigInt(1) | Returned value will be >= min | + + + +### randBits(bitLength, [forceLength]) ⇒ Buffer \| Uint8Array +Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues() + +**Kind**: global function +**Returns**: Buffer \| Uint8Array - A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| bitLength | number | | The desired number of random bits | +| [forceLength] | boolean | false | If we want to force the output to have a specific bit length. It basically forces the msb to be 1 | + + + +### randBytes(byteLength, [forceLength]) ⇒ Promise.<(Buffer\|Uint8Array)> +Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues() + +**Kind**: global function +**Returns**: Promise.<(Buffer\|Uint8Array)> - A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| byteLength | number | | The desired number of random bytes | +| [forceLength] | boolean | false | If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1 | + + + +### randBytesSync(byteLength, [forceLength]) ⇒ Buffer \| Uint8Array +Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues() + +**Kind**: global function +**Returns**: Buffer \| Uint8Array - A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| byteLength | number | | The desired number of random bytes | +| [forceLength] | boolean | false | If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1 | + ### egcdReturn : Object diff --git a/build/build.docs.js b/build/build.docs.js index 4db18de..09264e5 100644 --- a/build/build.docs.js +++ b/build/build.docs.js @@ -8,17 +8,19 @@ const pkgJson = require('../package.json') const rootDir = path.join(__dirname, '..') const template = path.join(rootDir, pkgJson.directories.src, 'doc', 'readme-template.md') -const input = path.join(rootDir, pkgJson.directories.lib, 'index.node.js') +const input = path.join(rootDir, pkgJson.directories.lib, 'index.browser.bundle.mod.js') +const source = fs.readFileSync(input, { encoding: 'UTF-8' }).replace(/([0-9]+)n([,\s\n)])/g, '$1$2') const options = { - source: fs.readFileSync(input, { encoding: 'UTF-8' }), // we need to use this instead of files in order to avoid issues with esnext features + 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. } -const readmeContents = jsdoc2md.renderSync(options) +jsdoc2md.clear().then(() => { + const readmeContents = jsdoc2md.renderSync(options) -const readmeFile = path.join(rootDir, 'README.md') - -fs.writeFileSync(readmeFile, readmeContents) + const readmeFile = path.join(rootDir, 'README.md') + fs.writeFileSync(readmeFile, readmeContents) +}) diff --git a/build/rollup.config.js b/build/rollup.config.js index 3467cf5..ae7cd52 100644 --- a/build/rollup.config.js +++ b/build/rollup.config.js @@ -29,7 +29,7 @@ module.exports = [ input: input, output: [ { - file: path.join(dstDir, 'index.browser.mod.js'), + file: path.join(rootDir, pkgJson.browser), format: 'esm' } ], @@ -46,7 +46,17 @@ module.exports = [ { file: path.join(dstDir, 'index.browser.bundle.js'), format: 'iife', - name: pkgCamelisedName + name: pkgCamelisedName, + plugins: [ + terser() + ] + }, + { + file: path.join(dstDir, 'index.browser.bundle.min.mod.js'), + format: 'es', + plugins: [ + terser() + ] }, { file: path.join(dstDir, 'index.browser.bundle.mod.js'), @@ -59,10 +69,6 @@ module.exports = [ }), resolve({ browser: true - }), - terser({ - // mangle: false, - // compress: false }) ] }, diff --git a/build/rollup.tests.config.js b/build/rollup.tests.config.js index b5da420..3fc0b03 100644 --- a/build/rollup.tests.config.js +++ b/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 = `