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

JSDoc throws. API is now sorted by function name

This commit is contained in:
juanelas 2020-04-21 10:06:04 +02:00
parent 4f9659707f
commit c246ef34f2
8 changed files with 166 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
README.md
View File

@ -135,6 +135,10 @@ Take positive integers a, b as input, and return a triple (g, x, y), such that a
<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="#isProbablyPrime">isProbablyPrime(w, [iterations], [disableWorkers])</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="#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>
@ -150,13 +154,6 @@ Take positive integers a, b as input, and return a triple (g, x, y), such that a
<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], [disableWorkers])</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
@ -183,6 +180,9 @@ The sync version is NOT RECOMMENDED since it won&#39;t use workers and thus it&#
<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>
<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>
</dl>
### Typedefs
@ -231,6 +231,20 @@ Take positive integers a, b as input, and return a triple (g, x, y), such that a
| a | <code>number</code> \| <code>bigint</code> |
| b | <code>number</code> \| <code>bigint</code> |
<a name="egcdReturn"></a>
### egcdReturn : <code>Object</code>
A triple (g, x, y), such that ax + by = g = gcd(a, b).
**Kind**: global typedef
**Properties**
| Name | Type |
| --- | --- |
| g | <code>bigint</code> |
| x | <code>bigint</code> |
| y | <code>bigint</code> |
<a name="gcd"></a>
### gcd(a, b) ⇒ <code>bigint</code>
@ -244,6 +258,25 @@ Greatest-common divisor of two integers based on the iterative binary algorithm.
| a | <code>number</code> \| <code>bigint</code> |
| b | <code>number</code> \| <code>bigint</code> |
<a name="isProbablyPrime"></a>
### isProbablyPrime(w, [iterations], [disableWorkers]) ⇒ <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)
**Throws**:
- <code>RangeError</code> w MUST be >= 0
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| w | <code>number</code> \| <code>bigint</code> | | A positive 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 |
| [disableWorkers] | <code>boolean</code> | <code>false</code> | Disable the use of workers for the primality test |
<a name="lcm"></a>
### lcm(a, b) ⇒ <code>bigint</code>
@ -310,34 +343,6 @@ Modular exponentiation b**e mod n. Currently using the right-to-left binary meth
| e | <code>number</code> \| <code>bigint</code> | exponent |
| n | <code>number</code> \| <code>bigint</code> | modulo |
<a name="toZn"></a>
### toZn(a, n) ⇒ <code>bigint</code>
Finds the smallest positive element that is congruent to a in modulo n
**Kind**: global function
**Returns**: <code>bigint</code> - The smallest positive representation of a in modulo n
| Param | Type | Description |
| --- | --- | --- |
| 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], [disableWorkers]) ⇒ <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 |
| [disableWorkers] | <code>boolean</code> | <code>false</code> | Disable the use of workers for the primality test |
<a name="prime"></a>
### prime(bitLength, [iterations]) ⇒ <code>Promise.&lt;bigint&gt;</code>
@ -349,6 +354,10 @@ and can be enabled at runtime executing node --experimental-worker with node >=1
**Kind**: global function
**Returns**: <code>Promise.&lt;bigint&gt;</code> - A promise that resolves to a bigint probable prime of bitLength bits.
**Throws**:
- <code>RangeError</code> bitLength MUST be > 0
| Param | Type | Default | Description |
| --- | --- | --- | --- |
@ -363,6 +372,10 @@ The sync version is NOT RECOMMENDED since it won't use workers and thus it'll be
**Kind**: global function
**Returns**: <code>bigint</code> - A bigint probable prime of bitLength bits.
**Throws**:
- <code>RangeError</code> bitLength MUST be > 0
| Param | Type | Default | Description |
| --- | --- | --- | --- |
@ -376,6 +389,10 @@ Returns a cryptographically secure random integer between [min,max]. Both number
**Kind**: global function
**Returns**: <code>bigint</code> - A cryptographically secure random bigint between [min,max]
**Throws**:
- <code>RangeError</code> Arguments MUST be: max > 0 && min >=0 && max > min
| Param | Type | Default | Description |
| --- | --- | --- | --- |
@ -389,6 +406,10 @@ Secure random bits for both node and browsers. Node version uses crypto.randomFi
**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 bits
**Throws**:
- <code>RangeError</code> bitLength MUST be > 0
| Param | Type | Default | Description |
| --- | --- | --- | --- |
@ -402,6 +423,10 @@ Secure random bits for both node and browsers. Node version uses crypto.randomFi
**Kind**: global function
**Returns**: <code>Buffer</code> \| <code>Uint8Array</code> - A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
**Throws**:
- <code>RangeError</code> bitLength MUST be > 0
| Param | Type | Default | Description |
| --- | --- | --- | --- |
@ -415,6 +440,10 @@ Secure random bytes for both node and browsers. Node version uses crypto.randomB
**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
**Throws**:
- <code>RangeError</code> byteLength MUST be > 0
| Param | Type | Default | Description |
| --- | --- | --- | --- |
@ -428,23 +457,26 @@ Secure random bytes for both node and browsers. Node version uses crypto.randomF
**Kind**: global function
**Returns**: <code>Buffer</code> \| <code>Uint8Array</code> - A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
**Throws**:
- <code>RangeError</code> byteLength MUST be > 0
| 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="toZn"></a>
### egcdReturn : <code>Object</code>
A triple (g, x, y), such that ax + by = g = gcd(a, b).
### toZn(a, n) ⇒ <code>bigint</code>
Finds the smallest positive element that is congruent to a in modulo n
**Kind**: global typedef
**Properties**
**Kind**: global function
**Returns**: <code>bigint</code> - The smallest positive representation of a in modulo n
| Name | Type |
| --- | --- |
| g | <code>bigint</code> |
| x | <code>bigint</code> |
| y | <code>bigint</code> |
| Param | Type | Description |
| --- | --- | --- |
| a | <code>number</code> \| <code>bigint</code> | An integer |
| n | <code>number</code> \| <code>bigint</code> | The modulo |

23
build/build.docs.js
View File

@ -53,18 +53,21 @@ const input1 = path.join(rootDir, 'node_modules', 'bigint-mod-arith', pkgJson.br
const input2 = path.join(rootDir, pkgJson.browser) // this module
// Let us replace bigint literals by standard numbers to avoid issues with bigint
const source1 = fs.readFileSync(input1, { encoding: 'UTF-8' }).replace(/([0-9]+)n([,\s\n)])/g, '$1$2')
const source2 = fs.readFileSync(input2, { encoding: 'UTF-8' }).replace(/([0-9]+)n([,\s\n)])/g, '$1$2')
const source = (source1 + '\n' + source2).replace(/^.*bigint-mod-arith.*$/mg, '') // remove import/export of bigint-mod-arith
const options = {
source,
template,
'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 source1 = fs.readFileSync(input1, { encoding: 'UTF-8' })
const source2 = fs.readFileSync(input2, { encoding: 'UTF-8' })
const source = (source1 + '\n' + source2)
.replace(/^.*bigint-mod-arith.*$/mg, '') // remove import/export of bigint-mod-arith
.replace(/([0-9]+)n([,\s\n)])/g, '$1$2') // replace bigint literals by standard numbers to avoid issues with bigint
jsdoc2md.clear().then(() => {
const data = jsdoc2md.getTemplateDataSync({ source })
data.sort((fn1, fn2) => (fn1.id > fn2.id) ? 1 : -1)
const options = {
data,
template,
'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)
const readmeFile = path.join(rootDir, 'README.md')

2
lib/index.browser.bundle.iife.js
View File

File diff suppressed because one or more lines are too long

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

File diff suppressed because one or more lines are too long

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

@ -5,16 +5,19 @@ export { abs, bitLength, eGcd, gcd, lcm, max, min, modInv, modPow, toZn } from '
* 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)
*
* @param {number | bigint} w An integer to be tested for primality
* @param {number | bigint} w A positive integer to be tested for primality
* @param {number} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
* @param {boolean} [disableWorkers = false] Disable the use of workers for the primality test
*
* @throws {RangeError} w MUST be >= 0
*
* @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
*/
function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
if (typeof w === 'number') {
w = BigInt(w)
}
if (w < 0) throw RangeError('w MUST be >= 0')
/* eslint-disable no-lone-blocks */
{ // browser
return new Promise((resolve, reject) => {
@ -49,6 +52,8 @@ function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
* @param {number} bitLength The required bit length for the generated prime
* @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
*/
function prime (bitLength, iterations = 16) {
@ -118,6 +123,8 @@ function prime (bitLength, iterations = 16) {
* @param {number} bitLength The required bit length for the generated prime
* @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {bigint} A bigint probable prime of bitLength bits.
*/
function primeSync (bitLength, iterations = 16) {
@ -134,10 +141,12 @@ function primeSync (bitLength, iterations = 16) {
* @param {bigint} max Returned value will be <= max
* @param {bigint} [min = BigInt(1)] Returned value will be >= min
*
* @throws {RangeError} Arguments MUST be: max > 0 && min >=0 && max > min
*
* @returns {bigint} A cryptographically secure random bigint between [min,max]
*/
function randBetween (max, min = 1n) {
if (max <= 0n || min < 0n || max <= min) throw new RangeError('inputs should be max > 0, min >= 0; max > min')
if (max <= 0n || min < 0n || max <= min) throw new RangeError('Arguments MUST be: max > 0 && min >=0 && max > min')
const interval = max - min
const bitLen = bitLength(interval)
let rnd
@ -154,6 +163,8 @@ function randBetween (max, min = 1n) {
* @param {number} bitLength The desired number of random bits
* @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Promise<Buffer | Uint8Array>} A Promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
function randBits (bitLength, forceLength = false) {
@ -182,6 +193,8 @@ function randBits (bitLength, forceLength = false) {
* @param {number} bitLength The desired number of random bits
* @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
function randBitsSync (bitLength, forceLength = false) {
@ -207,6 +220,8 @@ function randBitsSync (bitLength, forceLength = false) {
* @param {number} byteLength The desired number of random bytes
* @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
*
* @throws {RangeError} byteLength MUST be > 0
*
* @returns {Promise<Buffer | Uint8Array>} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
function randBytes (byteLength, forceLength = false) {
@ -231,6 +246,8 @@ function randBytes (byteLength, forceLength = false) {
* @param {number} byteLength The desired number of random bytes
* @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
*
* @throws {RangeError} byteLength MUST be > 0
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
function randBytesSync (byteLength, forceLength = false) {

21
lib/index.node.js
View File

@ -6,16 +6,19 @@ var bigintModArith = require('bigint-mod-arith')
* 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)
*
* @param {number | bigint} w An integer to be tested for primality
* @param {number | bigint} w A positive integer to be tested for primality
* @param {number} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
* @param {boolean} [disableWorkers = false] Disable the use of workers for the primality test
*
* @throws {RangeError} w MUST be >= 0
*
* @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
*/
function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
if (typeof w === 'number') {
w = BigInt(w)
}
if (w < 0) throw RangeError('w MUST be >= 0')
/* eslint-disable no-lone-blocks */
{ // Node.js
/* istanbul ignore else */
@ -56,6 +59,8 @@ function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
* @param {number} bitLength The required bit length for the generated prime
* @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
*/
function prime (bitLength, iterations = 16) {
@ -126,6 +131,8 @@ function prime (bitLength, iterations = 16) {
* @param {number} bitLength The required bit length for the generated prime
* @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {bigint} A bigint probable prime of bitLength bits.
*/
function primeSync (bitLength, iterations = 16) {
@ -142,10 +149,12 @@ function primeSync (bitLength, iterations = 16) {
* @param {bigint} max Returned value will be <= max
* @param {bigint} [min = BigInt(1)] Returned value will be >= min
*
* @throws {RangeError} Arguments MUST be: max > 0 && min >=0 && max > min
*
* @returns {bigint} A cryptographically secure random bigint between [min,max]
*/
function randBetween (max, min = 1n) {
if (max <= 0n || min < 0n || max <= min) throw new RangeError('inputs should be max > 0, min >= 0; max > min')
if (max <= 0n || min < 0n || max <= min) throw new RangeError('Arguments MUST be: max > 0 && min >=0 && max > min')
const interval = max - min
const bitLen = bigintModArith.bitLength(interval)
let rnd
@ -162,6 +171,8 @@ function randBetween (max, min = 1n) {
* @param {number} bitLength The desired number of random bits
* @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Promise<Buffer | Uint8Array>} A Promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
function randBits (bitLength, forceLength = false) {
@ -190,6 +201,8 @@ function randBits (bitLength, forceLength = false) {
* @param {number} bitLength The desired number of random bits
* @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
function randBitsSync (bitLength, forceLength = false) {
@ -215,6 +228,8 @@ function randBitsSync (bitLength, forceLength = false) {
* @param {number} byteLength The desired number of random bytes
* @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
*
* @throws {RangeError} byteLength MUST be > 0
*
* @returns {Promise<Buffer | Uint8Array>} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
function randBytes (byteLength, forceLength = false) {
@ -242,6 +257,8 @@ function randBytes (byteLength, forceLength = false) {
* @param {number} byteLength The desired number of random bytes
* @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
*
* @throws {RangeError} byteLength MUST be > 0
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
function randBytesSync (byteLength, forceLength = false) {

21
src/js/index.js
View File

@ -6,16 +6,19 @@ export { abs, bitLength, eGcd, gcd, lcm, max, min, modInv, modPow, toZn } from '
* 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)
*
* @param {number | bigint} w An integer to be tested for primality
* @param {number | bigint} w A positive integer to be tested for primality
* @param {number} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
* @param {boolean} [disableWorkers = false] Disable the use of workers for the primality test
*
* @throws {RangeError} w MUST be >= 0
*
* @returns {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, iterations = 16, disableWorkers = false) {
if (typeof w === 'number') {
w = BigInt(w)
}
if (w < 0) throw RangeError('w MUST be >= 0')
/* eslint-disable no-lone-blocks */
if (!process.browser) { // Node.js
/* istanbul ignore else */
@ -75,6 +78,8 @@ export function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
* @param {number} bitLength The required bit length for the generated prime
* @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
*/
export function prime (bitLength, iterations = 16) {
@ -152,6 +157,8 @@ export function prime (bitLength, iterations = 16) {
* @param {number} bitLength The required bit length for the generated prime
* @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {bigint} A bigint probable prime of bitLength bits.
*/
export function primeSync (bitLength, iterations = 16) {
@ -168,10 +175,12 @@ export function primeSync (bitLength, iterations = 16) {
* @param {bigint} max Returned value will be <= max
* @param {bigint} [min = BigInt(1)] Returned value will be >= min
*
* @throws {RangeError} Arguments MUST be: max > 0 && min >=0 && max > min
*
* @returns {bigint} A cryptographically secure random bigint between [min,max]
*/
export function randBetween (max, min = 1n) {
if (max <= 0n || min < 0n || max <= min) throw new RangeError('inputs should be max > 0, min >= 0; max > min')
if (max <= 0n || min < 0n || max <= min) throw new RangeError('Arguments MUST be: max > 0 && min >=0 && max > min')
const interval = max - min
const bitLen = bitLength(interval)
let rnd
@ -188,6 +197,8 @@ export function randBetween (max, min = 1n) {
* @param {number} bitLength The desired number of random bits
* @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Promise<Buffer | Uint8Array>} A Promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
export function randBits (bitLength, forceLength = false) {
@ -216,6 +227,8 @@ export function randBits (bitLength, forceLength = false) {
* @param {number} bitLength The desired number of random bits
* @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
export function randBitsSync (bitLength, forceLength = false) {
@ -241,6 +254,8 @@ export function randBitsSync (bitLength, forceLength = false) {
* @param {number} byteLength The desired number of random bytes
* @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
*
* @throws {RangeError} byteLength MUST be > 0
*
* @returns {Promise<Buffer | Uint8Array>} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
export function randBytes (byteLength, forceLength = false) {
@ -274,6 +289,8 @@ export function randBytes (byteLength, forceLength = false) {
* @param {number} byteLength The desired number of random bytes
* @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
*
* @throws {RangeError} byteLength MUST be > 0
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
export function randBytesSync (byteLength, forceLength = false) {

18
types/index.d.ts vendored
View File

@ -2,10 +2,12 @@
* 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)
*
* @param {number | bigint} w An integer to be tested for primality
* @param {number | bigint} w A positive integer to be tested for primality
* @param {number} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
* @param {boolean} [disableWorkers = false] Disable the use of workers for the primality test
*
* @throws {RangeError} w MUST be >= 0
*
* @returns {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, disableWorkers?: boolean): Promise<boolean>;
@ -19,6 +21,8 @@ export function isProbablyPrime(w: number | bigint, iterations?: number, disable
* @param {number} bitLength The required bit length for the generated prime
* @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
*/
export function prime(bitLength: number, iterations?: number): Promise<bigint>;
@ -29,6 +33,8 @@ export function prime(bitLength: number, iterations?: number): Promise<bigint>;
* @param {number} bitLength The required bit length for the generated prime
* @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {bigint} A bigint probable prime of bitLength bits.
*/
export function primeSync(bitLength: number, iterations?: number): bigint;
@ -37,6 +43,8 @@ export function primeSync(bitLength: number, iterations?: number): bigint;
* @param {bigint} max Returned value will be <= max
* @param {bigint} [min = BigInt(1)] Returned value will be >= min
*
* @throws {RangeError} Arguments MUST be: max > 0 && min >=0 && max > min
*
* @returns {bigint} A cryptographically secure random bigint between [min,max]
*/
export function randBetween(max: bigint, min?: bigint): bigint;
@ -46,6 +54,8 @@ export function randBetween(max: bigint, min?: bigint): bigint;
* @param {number} bitLength The desired number of random bits
* @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Promise<Buffer | Uint8Array>} A Promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
export function randBits(bitLength: number, forceLength?: boolean): Promise<Uint8Array | Buffer>;
@ -54,6 +64,8 @@ export function randBits(bitLength: number, forceLength?: boolean): Promise<Uint
* @param {number} bitLength The desired number of random bits
* @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
*
* @throws {RangeError} bitLength MUST be > 0
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
export function randBitsSync(bitLength: number, forceLength?: boolean): Uint8Array | Buffer;
@ -63,6 +75,8 @@ export function randBitsSync(bitLength: number, forceLength?: boolean): Uint8Arr
* @param {number} byteLength The desired number of random bytes
* @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
*
* @throws {RangeError} byteLength MUST be > 0
*
* @returns {Promise<Buffer | Uint8Array>} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
export function randBytes(byteLength: number, forceLength?: boolean): Promise<Uint8Array | Buffer>;
@ -72,6 +86,8 @@ export function randBytes(byteLength: number, forceLength?: boolean): Promise<Ui
* @param {number} byteLength The desired number of random bytes
* @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
*
* @throws {RangeError} byteLength MUST be > 0
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
export function randBytesSync(byteLength: number, forceLength?: boolean): Uint8Array | Buffer;