fixed API reference
This commit is contained in:
juanelas
parent
66b4d7fad1
commit
31af1f7e8a
170
README.md
170
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>=0. abs(a)==-a if a<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>=b. max(a,b)==b if a<=b</p>
|
||||
</dd>
|
||||
<dt><a href="#min">min(a, b)</a> ⇒ <code>bigint</code></dt>
|
||||
<dd><p>Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=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.<boolean></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.<bigint></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 >=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't use workers and thus it'll be slower and may freeze thw window in browser'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.<(Buffer|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>
|
||||
<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>
|
||||
|
|
@ -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 |
|
||||
| n | <code>number</code> \| <code>bigint</code> | The modulo |
|
||||
|
||||
<a name="isProbablyPrime"></a>
|
||||
|
||||
### isProbablyPrime(w, [iterations]) ⇒ <code>Promise.<boolean></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.<boolean></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.<bigint></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.<bigint></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.<(Buffer\|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>Promise.<(Buffer\|Uint8Array)></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>
|
||||
|
||||
### egcdReturn : <code>Object</code>
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
}
|
||||
|
||||
jsdoc2md.clear().then(() => {
|
||||
const readmeContents = jsdoc2md.renderSync(options)
|
||||
|
||||
const readmeFile = path.join(rootDir, 'README.md')
|
||||
|
||||
fs.writeFileSync(readmeFile, readmeContents)
|
||||
})
|
||||
|
|
|
|||
|
|
@ -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
|
||||
})
|
||||
]
|
||||
},
|
||||
|
|
|
|||
|
|
@ -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)}'
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -53,7 +53,7 @@
|
|||
"ignore": [
|
||||
"/test/browser/",
|
||||
"/lib/index.browser.bundle.js",
|
||||
"/lib/index.browser.bundle.mod.js"
|
||||
"/lib/index.browser.bundle.min.mod.js"
|
||||
]
|
||||
},
|
||||
"devDependencies": {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
|
|
|||
Loading…
Reference in New Issue