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 + +
bigint
Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
+number
Returns the bitlength of a number
+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).
+bigint
Greatest-common divisor of two integers based on the iterative binary algorithm.
+bigint
The least common multiple computed as abs(a*b)/gcd(a,b)
+bigint
Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b
+bigint
Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b
+bigint
Modular inverse.
+bigint
Modular exponentiation b**e mod n. Currently using the right-to-left binary method
+bigint
Finds the smallest positive element that is congruent to a in modulo n
+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)
+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).
+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.
+bigint
Returns a cryptographically secure random integer between [min,max]
+Buffer
| Uint8Array
Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
+Promise.<(Buffer|Uint8Array)>
Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
+Buffer
| Uint8Array
Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
+Object
A triple (g, x, y), such that ax + by = g = gcd(a, b).
+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 = `