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

fixed API reference

This commit is contained in:
juanelas 2020-04-07 19:13:23 +02:00
parent 66b4d7fad1
commit 31af1f7e8a
8 changed files with 987 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
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. 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 ## Usage examples
@ -96,6 +96,77 @@ primeTesting()
## API reference documentation ## 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> <a name="abs"></a>
### abs(a) ⇒ <code>bigint</code> ### abs(a) ⇒ <code>bigint</code>
@ -226,6 +297,103 @@ Finds the smallest positive element that is congruent to a in modulo n
| a | <code>number</code> \| <code>bigint</code> | An integer | | a | <code>number</code> \| <code>bigint</code> | An integer |
| n | <code>number</code> \| <code>bigint</code> | The modulo | | n | <code>number</code> \| <code>bigint</code> | The modulo |
<a name="isProbablyPrime"></a>
### isProbablyPrime(w, [iterations]) ⇒ <code>Promise.&lt;boolean&gt;</code>
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**: <code>Promise.&lt;boolean&gt;</code> - A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| w | <code>number</code> \| <code>bigint</code> | | An integer to be tested for primality |
| [iterations] | <code>number</code> | <code>16</code> | The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3 |
<a name="prime"></a>
### prime(bitLength, [iterations]) ⇒ <code>Promise.&lt;bigint&gt;</code>
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**: <code>Promise.&lt;bigint&gt;</code> - A promise that resolves to a bigint probable prime of bitLength bits.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| bitLength | <code>number</code> | | The required bit length for the generated prime |
| [iterations] | <code>number</code> | <code>16</code> | The number of iterations for the Miller-Rabin Probabilistic Primality Test |
<a name="primeSync"></a>
### primeSync(bitLength, [iterations]) ⇒ <code>bigint</code>
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**: <code>bigint</code> - A bigint probable prime of bitLength bits.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| bitLength | <code>number</code> | | The required bit length for the generated prime |
| [iterations] | <code>number</code> | <code>16</code> | The number of iterations for the Miller-Rabin Probabilistic Primality Test |
<a name="randBetween"></a>
### randBetween(max, [min]) ⇒ <code>bigint</code>
Returns a cryptographically secure random integer between [min,max]
**Kind**: global function
**Returns**: <code>bigint</code> - A cryptographically secure random bigint between [min,max]
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| max | <code>bigint</code> | | Returned value will be <= max |
| [min] | <code>bigint</code> | <code>BigInt(1)</code> | Returned value will be >= min |
<a name="randBits"></a>
### randBits(bitLength, [forceLength]) ⇒ <code>Buffer</code> \| <code>Uint8Array</code>
Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
**Kind**: global function
**Returns**: <code>Buffer</code> \| <code>Uint8Array</code> - A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| bitLength | <code>number</code> | | The desired number of random bits |
| [forceLength] | <code>boolean</code> | <code>false</code> | If we want to force the output to have a specific bit length. It basically forces the msb to be 1 |
<a name="randBytes"></a>
### randBytes(byteLength, [forceLength]) ⇒ <code>Promise.&lt;(Buffer\|Uint8Array)&gt;</code>
Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
**Kind**: global function
**Returns**: <code>Promise.&lt;(Buffer\|Uint8Array)&gt;</code> - A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| byteLength | <code>number</code> | | The desired number of random bytes |
| [forceLength] | <code>boolean</code> | <code>false</code> | If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1 |
<a name="randBytesSync"></a>
### randBytesSync(byteLength, [forceLength]) ⇒ <code>Buffer</code> \| <code>Uint8Array</code>
Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
**Kind**: global function
**Returns**: <code>Buffer</code> \| <code>Uint8Array</code> - A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| byteLength | <code>number</code> | | The desired number of random bytes |
| [forceLength] | <code>boolean</code> | <code>false</code> | If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1 |
<a name="egcdReturn"></a> <a name="egcdReturn"></a>
### egcdReturn : <code>Object</code> ### egcdReturn : <code>Object</code>

12
build/build.docs.js
View File

@ -8,17 +8,19 @@ const pkgJson = require('../package.json')
const rootDir = path.join(__dirname, '..') const rootDir = path.join(__dirname, '..')
const template = path.join(rootDir, pkgJson.directories.src, 'doc', 'readme-template.md') 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 = { 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' }), 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(() => {
const readmeContents = jsdoc2md.renderSync(options) const readmeContents = jsdoc2md.renderSync(options)
const readmeFile = path.join(rootDir, 'README.md') const readmeFile = path.join(rootDir, 'README.md')
fs.writeFileSync(readmeFile, readmeContents) fs.writeFileSync(readmeFile, readmeContents)
})

18
build/rollup.config.js
View File

@ -29,7 +29,7 @@ module.exports = [
input: input, input: input,
output: [ output: [
{ {
file: path.join(dstDir, 'index.browser.mod.js'), file: path.join(rootDir, pkgJson.browser),
format: 'esm' format: 'esm'
} }
], ],
@ -46,7 +46,17 @@ module.exports = [
{ {
file: path.join(dstDir, 'index.browser.bundle.js'), file: path.join(dstDir, 'index.browser.bundle.js'),
format: 'iife', 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'), file: path.join(dstDir, 'index.browser.bundle.mod.js'),
@ -59,10 +69,6 @@ module.exports = [
}), }),
resolve({ resolve({
browser: true browser: true
}),
terser({
// mangle: false,
// compress: false
}) })
] ]
}, },

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 dstFileName = path.join(dstDir, 'index.html')
const template = fs.readFileSync(templatePath, 'utf-8') 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 = ` const testsJs = `
<script type="module"> <script type="module">
import * as _pkg from '${path.relative(templatePath, bundleFile)}' import * as _pkg from '${path.relative(templatePath, bundleFile)}'

793
lib/index.browser.bundle.mod.js
View File

File diff suppressed because one or more lines are too long

2
package.json
View File

@ -53,7 +53,7 @@
"ignore": [ "ignore": [
"/test/browser/", "/test/browser/",
"/lib/index.browser.bundle.js", "/lib/index.browser.bundle.js",
"/lib/index.browser.bundle.mod.js" "/lib/index.browser.bundle.min.mod.js"
] ]
}, },
"devDependencies": { "devDependencies": {

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. 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 ## Usage examples

2
test/browser/index.html
View File

@ -13,7 +13,7 @@
<script>mocha.setup('bdd'); mocha.setup({ timeout: 90000 });</script> <script>mocha.setup('bdd'); mocha.setup({ timeout: 90000 });</script>
<script type="module"> <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; window._pkg = _pkg;
import './tests.js'; import './tests.js';
mocha.run(); mocha.run();