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

fixed JS Doc and typescript definitions

This commit is contained in:
juanelas 2020-03-25 00:34:22 +01:00
parent 3602667de4
commit d4ee54748b
9 changed files with 238 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
README.md
View File

@ -107,7 +107,7 @@ 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> <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><p>Greatest-common divisor of two integers based on the iterative binary algorithm.</p>
</dd> </dd>
<dt><a href="#isProbablyPrime">isProbablyPrime(w, [iterations])</a> ⇒ <code>Promise</code></dt> <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 <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> iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)</p>
</dd> </dd>
@ -126,7 +126,7 @@ iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)</p>
<dt><a href="#modPow">modPow(b, e, n)</a> ⇒ <code>bigint</code></dt> <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><p>Modular exponentiation b**e mod n. Currently using the right-to-left binary method</p>
</dd> </dd>
<dt><a href="#prime">prime(bitLength, [iterations])</a> ⇒ <code>Promise</code></dt> <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. <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 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). main process, and it can be much faster (if several cores or cpu are available).
@ -143,7 +143,7 @@ The sync version is NOT RECOMMENDED since it won&#39;t use workers and thus it&#
<dt><a href="#randBits">randBits(bitLength, [forceLength])</a> ⇒ <code>Buffer</code> | <code>Uint8Array</code></dt> <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><p>Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()</p>
</dd> </dd>
<dt><a href="#randBytes">randBytes(byteLength, [forceLength])</a> ⇒ <code>Promise</code></dt> <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><p>Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()</p>
</dd> </dd>
<dt><a href="#randBytesSync">randBytesSync(byteLength, [forceLength])</a> ⇒ <code>Buffer</code> | <code>Uint8Array</code></dt> <dt><a href="#randBytesSync">randBytesSync(byteLength, [forceLength])</a> ⇒ <code>Buffer</code> | <code>Uint8Array</code></dt>
@ -215,12 +215,12 @@ Greatest-common divisor of two integers based on the iterative binary algorithm.
<a name="isProbablyPrime"></a> <a name="isProbablyPrime"></a>
## isProbablyPrime(w, [iterations]) ⇒ <code>Promise</code> ## 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 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) iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)
**Kind**: global function **Kind**: global function
**Returns**: <code>Promise</code> - A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite) **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 | | Param | Type | Default | Description |
| --- | --- | --- | --- | | --- | --- | --- | --- |
@ -295,7 +295,7 @@ Modular exponentiation b**e mod n. Currently using the right-to-left binary meth
<a name="prime"></a> <a name="prime"></a>
## prime(bitLength, [iterations]) ⇒ <code>Promise</code> ## prime(bitLength, [iterations]) ⇒ <code>Promise.&lt;bigint&gt;</code>
A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator. 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 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). main process, and it can be much faster (if several cores or cpu are available).
@ -303,7 +303,7 @@ The node version can also use worker_threads if they are available (enabled by d
and can be enabled at runtime executing node --experimental-worker with node >=10.5.0). and can be enabled at runtime executing node --experimental-worker with node >=10.5.0).
**Kind**: global function **Kind**: global function
**Returns**: <code>Promise</code> - A promise that resolves to a bigint probable prime of bitLength bits. **Returns**: <code>Promise.&lt;bigint&gt;</code> - A promise that resolves to a bigint probable prime of bitLength bits.
| Param | Type | Default | Description | | Param | Type | Default | Description |
| --- | --- | --- | --- | | --- | --- | --- | --- |
@ -352,11 +352,11 @@ Secure random bits for both node and browsers. Node version uses crypto.randomFi
<a name="randBytes"></a> <a name="randBytes"></a>
## randBytes(byteLength, [forceLength]) ⇒ <code>Promise</code> ## 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() Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
**Kind**: global function **Kind**: global function
**Returns**: <code>Promise</code> - A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes **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 | | Param | Type | Default | Description |
| --- | --- | --- | --- | | --- | --- | --- | --- |

6
dist/bigint-crypto-utils-latest.browser.js vendored
View File

@ -123,7 +123,7 @@ var bigintCryptoUtils = (function (exports) {
* @param {number|bigint} w An integer to be tested for primality * @param {number|bigint} w An 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 {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
* *
* @return {Promise} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite) * @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
*/ */
async function isProbablyPrime(w, iterations = 16) { async function isProbablyPrime(w, iterations = 16) {
if (typeof w === 'number') { if (typeof w === 'number') {
@ -258,7 +258,7 @@ var bigintCryptoUtils = (function (exports) {
* @param {number} bitLength The required bit length for the generated prime * @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 * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
* *
* @returns {Promise} A promise that resolves to a bigint probable prime of bitLength bits. * @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
*/ */
function prime(bitLength, iterations = 16) { function prime(bitLength, iterations = 16) {
if (bitLength < 1) if (bitLength < 1)
@ -379,7 +379,7 @@ var bigintCryptoUtils = (function (exports) {
* @param {number} byteLength The desired number of random bytes * @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 * @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
* *
* @returns {Promise} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes * @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) { function randBytes(byteLength, forceLength = false) {
if (byteLength < 1) if (byteLength < 1)

6
dist/bigint-crypto-utils-latest.browser.mod.js vendored
View File

@ -120,7 +120,7 @@ function gcd(a, b) {
* @param {number|bigint} w An integer to be tested for primality * @param {number|bigint} w An 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 {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
* *
* @return {Promise} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite) * @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
*/ */
async function isProbablyPrime(w, iterations = 16) { async function isProbablyPrime(w, iterations = 16) {
if (typeof w === 'number') { if (typeof w === 'number') {
@ -255,7 +255,7 @@ function modPow(b, e, n) {
* @param {number} bitLength The required bit length for the generated prime * @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 * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
* *
* @returns {Promise} A promise that resolves to a bigint probable prime of bitLength bits. * @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
*/ */
function prime(bitLength, iterations = 16) { function prime(bitLength, iterations = 16) {
if (bitLength < 1) if (bitLength < 1)
@ -376,7 +376,7 @@ function randBits(bitLength, forceLength = false) {
* @param {number} byteLength The desired number of random bytes * @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 * @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
* *
* @returns {Promise} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes * @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) { function randBytes(byteLength, forceLength = false) {
if (byteLength < 1) if (byteLength < 1)

6
dist/bigint-crypto-utils-latest.node.js vendored
View File

@ -124,7 +124,7 @@ function gcd(a, b) {
* @param {number|bigint} w An integer to be tested for primality * @param {number|bigint} w An 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 {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
* *
* @return {Promise} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite) * @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
*/ */
async function isProbablyPrime(w, iterations = 16) { async function isProbablyPrime(w, iterations = 16) {
if (typeof w === 'number') { if (typeof w === 'number') {
@ -265,7 +265,7 @@ function modPow(b, e, n) {
* @param {number} bitLength The required bit length for the generated prime * @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 * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
* *
* @returns {Promise} A promise that resolves to a bigint probable prime of bitLength bits. * @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
*/ */
function prime(bitLength, iterations = 16) { function prime(bitLength, iterations = 16) {
if (bitLength < 1) if (bitLength < 1)
@ -395,7 +395,7 @@ function randBits(bitLength, forceLength = false) {
* @param {number} byteLength The desired number of random bytes * @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 * @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
* *
* @returns {Promise} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes * @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) { function randBytes(byteLength, forceLength = false) {
if (byteLength < 1) if (byteLength < 1)

60
package-lock.json generated
View File

@ -97,10 +97,9 @@
"dev": true "dev": true
}, },
"@types/node": { "@types/node": {
"version": "13.9.1", "version": "13.9.3",
"resolved": "https://registry.npmjs.org/@types/node/-/node-13.9.1.tgz", "resolved": "https://registry.npmjs.org/@types/node/-/node-13.9.3.tgz",
"integrity": "sha512-E6M6N0blf/jiZx8Q3nb0vNaswQeEyn0XlupO+xN6DtJ6r6IT4nXrTry7zhIfYvFCl3/8Cu6WIysmUBKiqV0bqQ==", "integrity": "sha512-01s+ac4qerwd6RHD+mVbOEsraDHSgUaefQlEdBbUolnQFjKwCr7luvAlEwW1RFojh67u0z4OUTjPn9LEl4zIkA=="
"dev": true
}, },
"@types/resolve": { "@types/resolve": {
"version": "0.0.8", "version": "0.0.8",
@ -1799,9 +1798,9 @@
"dev": true "dev": true
}, },
"mocha": { "mocha": {
"version": "7.1.0", "version": "7.1.1",
"resolved": "https://registry.npmjs.org/mocha/-/mocha-7.1.0.tgz", "resolved": "https://registry.npmjs.org/mocha/-/mocha-7.1.1.tgz",
"integrity": "sha512-MymHK8UkU0K15Q/zX7uflZgVoRWiTjy0fXE/QjKts6mowUvGxOdPhZ2qj3b0iZdUrNZlW9LAIMFHB4IW+2b3EQ==", "integrity": "sha512-3qQsu3ijNS3GkWcccT5Zw0hf/rWvu1fTN9sPvEd81hlwsr30GX2GcDSSoBxo24IR8FelmrAydGC6/1J5QQP4WA==",
"dev": true, "dev": true,
"requires": { "requires": {
"ansi-colors": "3.2.3", "ansi-colors": "3.2.3",
@ -1817,7 +1816,7 @@
"js-yaml": "3.13.1", "js-yaml": "3.13.1",
"log-symbols": "3.0.0", "log-symbols": "3.0.0",
"minimatch": "3.0.4", "minimatch": "3.0.4",
"mkdirp": "0.5.1", "mkdirp": "0.5.3",
"ms": "2.1.1", "ms": "2.1.1",
"node-environment-flags": "1.0.6", "node-environment-flags": "1.0.6",
"object.assign": "4.1.0", "object.assign": "4.1.0",
@ -1825,8 +1824,8 @@
"supports-color": "6.0.0", "supports-color": "6.0.0",
"which": "1.3.1", "which": "1.3.1",
"wide-align": "1.1.3", "wide-align": "1.1.3",
"yargs": "13.3.0", "yargs": "13.3.2",
"yargs-parser": "13.1.1", "yargs-parser": "13.1.2",
"yargs-unparser": "1.6.0" "yargs-unparser": "1.6.0"
}, },
"dependencies": { "dependencies": {
@ -1853,6 +1852,21 @@
"path-is-absolute": "^1.0.0" "path-is-absolute": "^1.0.0"
} }
}, },
"minimist": {
"version": "1.2.5",
"resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.5.tgz",
"integrity": "sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw==",
"dev": true
},
"mkdirp": {
"version": "0.5.3",
"resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.3.tgz",
"integrity": "sha512-P+2gwrFqx8lhew375MQHHeTlY8AuOJSrGf0R5ddkEndUkmwpgUob/vQuBD1V22/Cw1/lJr4x+EjllSezBThzBg==",
"dev": true,
"requires": {
"minimist": "^1.2.5"
}
},
"ms": { "ms": {
"version": "2.1.1", "version": "2.1.1",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz", "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz",
@ -2150,9 +2164,9 @@
"dev": true "dev": true
}, },
"picomatch": { "picomatch": {
"version": "2.2.1", "version": "2.2.2",
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.2.1.tgz", "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.2.2.tgz",
"integrity": "sha512-ISBaA8xQNmwELC7eOjqFKMESB2VIqt4PPDD0nsS95b/9dZXvVKOlz9keMSnoGGKcOHXfTvDD6WMaRoSc9UuhRA==", "integrity": "sha512-q0M/9eZHzmr0AulXyPwNfZjtwZ/RBZlbN3K3CErVrk50T2ASYI7Bye0EvekFY3IP1Nt2DHu0re+V2ZHIpMkuWg==",
"dev": true "dev": true
}, },
"pidtree": { "pidtree": {
@ -2349,9 +2363,9 @@
} }
}, },
"rollup": { "rollup": {
"version": "2.0.6", "version": "2.2.0",
"resolved": "https://registry.npmjs.org/rollup/-/rollup-2.0.6.tgz", "resolved": "https://registry.npmjs.org/rollup/-/rollup-2.2.0.tgz",
"integrity": "sha512-P42IlI6a/bxh52ed8hEXXe44LcHfep2f26OZybMJPN1TTQftibvQEl3CWeOmJrzqGbFxOA000QXDWO9WJaOQpA==", "integrity": "sha512-iAu/j9/WJ0i+zT0sAMuQnsEbmOKzdQ4Yxu5rbPs9aUCyqveI1Kw3H4Fi9NWfCOpb8luEySD2lDyFWL9CrLE8iw==",
"dev": true, "dev": true,
"requires": { "requires": {
"fsevents": "~2.1.2" "fsevents": "~2.1.2"
@ -3044,9 +3058,9 @@
"dev": true "dev": true
}, },
"yargs": { "yargs": {
"version": "13.3.0", "version": "13.3.2",
"resolved": "https://registry.npmjs.org/yargs/-/yargs-13.3.0.tgz", "resolved": "https://registry.npmjs.org/yargs/-/yargs-13.3.2.tgz",
"integrity": "sha512-2eehun/8ALW8TLoIl7MVaRUrg+yCnenu8B4kBlRxj3GJGDKU1Og7sMXPNm1BYyM1DOJmTZ4YeN/Nwxv+8XJsUA==", "integrity": "sha512-AX3Zw5iPruN5ie6xGRIDgqkT+ZhnRlZMLMHAs8tg7nRruy2Nb+i5o9bwghAogtM08q1dpr2LVoS8KSTMYpWXUw==",
"dev": true, "dev": true,
"requires": { "requires": {
"cliui": "^5.0.0", "cliui": "^5.0.0",
@ -3058,7 +3072,7 @@
"string-width": "^3.0.0", "string-width": "^3.0.0",
"which-module": "^2.0.0", "which-module": "^2.0.0",
"y18n": "^4.0.0", "y18n": "^4.0.0",
"yargs-parser": "^13.1.1" "yargs-parser": "^13.1.2"
}, },
"dependencies": { "dependencies": {
"emoji-regex": { "emoji-regex": {
@ -3087,9 +3101,9 @@
} }
}, },
"yargs-parser": { "yargs-parser": {
"version": "13.1.1", "version": "13.1.2",
"resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-13.1.1.tgz", "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-13.1.2.tgz",
"integrity": "sha512-oVAVsHz6uFrg3XQheFII8ESO2ssAf9luWuAd6Wexsu4F3OtIW0o8IribPXYrD4WC24LWtPrJlGy87y5udK+dxQ==", "integrity": "sha512-3lbsNRf/j+A4QuSZfDRA7HRSfWrzO0YjqTJd5kjAq37Zep1CEgaYmrH9Q3GwPiB9cHyd1Y1UwggGhJGoxipbzg==",
"dev": true, "dev": true,
"requires": { "requires": {
"camelcase": "^5.0.0", "camelcase": "^5.0.0",

13
package.json
View File

@ -15,19 +15,19 @@
"license": "MIT", "license": "MIT",
"author": { "author": {
"name": "Juan Hernández Serrano", "name": "Juan Hernández Serrano",
"email": "jserrano@entel.upc.edu", "email": "j.hernandez@upc.edu",
"url": "https://github.com/juanelas" "url": "https://github.com/juanelas"
}, },
"repository": "github:juanelas/bigint-crypto-utils", "repository": "github:juanelas/bigint-crypto-utils",
"main": "./dist/bigint-crypto-utils-latest.node.js", "main": "./dist/bigint-crypto-utils-latest.node.js",
"browser": "./dist/bigint-crypto-utils-latest.browser.mod.min.js", "browser": "./dist/bigint-crypto-utils-latest.browser.mod.js",
"types": "./types/bigint-crypto-utils.d.ts", "types": "./types/bigint-crypto-utils.d.ts",
"directories": { "directories": {
"build": "./build", "build": "./build",
"dist": "./dist", "dist": "./dist",
"src": "./src", "src": "./src",
"test": "./test", "test": "./test",
"types": "/types" "types": "./types"
}, },
"scripts": { "scripts": {
"test": "mocha --timeout 600000", "test": "mocha --timeout 600000",
@ -46,10 +46,13 @@
"chai": ">=4.2.0", "chai": ">=4.2.0",
"eslint": "^6.8.0", "eslint": "^6.8.0",
"jsdoc-to-markdown": "^5.0.3", "jsdoc-to-markdown": "^5.0.3",
"mocha": "^7.1.0", "mocha": "^7.1.1",
"npm-run-all": "^4.1.5", "npm-run-all": "^4.1.5",
"rollup": "^2.0.6", "rollup": "^2.2.0",
"rollup-plugin-terser": "^5.3.0", "rollup-plugin-terser": "^5.3.0",
"typescript": "^3.8.3" "typescript": "^3.8.3"
},
"dependencies": {
"@types/node": "^13.9.3"
} }
} }

6
src/main.js
View File

@ -122,7 +122,7 @@ export function gcd(a, b) {
* @param {number|bigint} w An integer to be tested for primality * @param {number|bigint} w An 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 {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
* *
* @return {Promise} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite) * @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
*/ */
export async function isProbablyPrime(w, iterations = 16) { export async function isProbablyPrime(w, iterations = 16) {
if (typeof w === 'number') { if (typeof w === 'number') {
@ -282,7 +282,7 @@ export function modPow(b, e, n) {
* @param {number} bitLength The required bit length for the generated prime * @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 * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
* *
* @returns {Promise} A promise that resolves to a bigint probable prime of bitLength bits. * @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
*/ */
export function prime(bitLength, iterations = 16) { export function prime(bitLength, iterations = 16) {
if (bitLength < 1) if (bitLength < 1)
@ -419,7 +419,7 @@ export function randBits(bitLength, forceLength = false) {
* @param {number} byteLength The desired number of random bytes * @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 * @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
* *
* @returns {Promise} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes * @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) { export function randBytes(byteLength, forceLength = false) {
if (byteLength < 1) if (byteLength < 1)

4
test/browser/index.html
View File

@ -2,11 +2,11 @@
<html> <html>
<head> <head>
<title>bigint-crypto-utils - Mocha Tests</title> <title>bigint-crypto-utils - Mocha Tests</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/mocha/7.1.0/mocha.min.css"> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/mocha/7.1.1/mocha.min.css">
</head> </head>
<body> <body>
<div id="mocha"></div> <div id="mocha"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mocha/7.1.0/mocha.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/mocha/7.1.1/mocha.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/chai/4.2.0/chai.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/chai/4.2.0/chai.min.js"></script>
<script>mocha.setup('bdd'); mocha.setup({ timeout: 90000 });</script> <script>mocha.setup('bdd'); mocha.setup({ timeout: 90000 });</script>

184
types/bigint-crypto-utils.d.ts vendored
View File

@ -1,21 +1,169 @@
export function abs(a: any): any; /**
export function bitLength(a: any): number; * A triple (g, x, y), such that ax + by = g = gcd(a, b).
export function eGcd(a: any, b: any): number | { */
b: any; export type egcdReturn = {
g: bigint;
x: bigint; x: bigint;
y: bigint; y: bigint;
}; };
export function gcd(a: any, b: any): any; /**
export function isProbablyPrime(w: any, iterations?: number): Promise<any>; * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
export function lcm(a: any, b: any): number | bigint; *
export function max(a: any, b: any): any; * @param {number | bigint} a
export function min(a: any, b: any): any; *
export function modInv(a: any, n: any): any; * @returns {bigint} the absolute value of a
export function modPow(b: any, e: any, n: any): any; */
export function prime(bitLength: any, iterations?: number): Promise<any>; export function abs(a: number | bigint): bigint;
export function primeSync(bitLength: any, iterations?: number): bigint; /**
export function randBetween(max: any, min?: bigint): bigint; * Returns the bitlength of a number
export function randBits(bitLength: any, forceLength?: boolean): Uint8Array; *
export function randBytes(byteLength: any, forceLength?: boolean): Promise<any>; * @param {number|bigint} a
export function randBytesSync(byteLength: any, forceLength?: boolean): Uint8Array; * @returns {number} - the bit length
export function toZn(a: any, n: any): any; */
export function bitLength(a: number | bigint): number;
/**
* @typedef {Object} egcdReturn A triple (g, x, y), such that ax + by = g = gcd(a, b).
* @property {bigint} g
* @property {bigint} x
* @property {bigint} y
*/
/**
* 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).
*
* @param {number|bigint} a
* @param {number|bigint} b
*
* @returns {egcdReturn} A triple (g, x, y), such that ax + by = g = gcd(a, b).
*/
export function eGcd(a: number | bigint, b: number | bigint): egcdReturn;
/**
* Greatest-common divisor of two integers based on the iterative binary algorithm.
*
* @param {number|bigint} a
* @param {number|bigint} b
*
* @returns {bigint} The greatest common divisor of a and b
*/
export function gcd(a: number | bigint, b: number | bigint): bigint;
/**
* 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} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
*
* @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): Promise<boolean>;
/**
* The least common multiple computed as abs(a*b)/gcd(a,b)
* @param {number|bigint} a
* @param {number|bigint} b
*
* @returns {bigint} The least common multiple of a and b
*/
export function lcm(a: number | bigint, b: number | bigint): bigint;
/**
* Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b
*
* @param {number|bigint} a
* @param {number|bigint} b
*
* @returns {bigint} maximum of numbers a and b
*/
export function max(a: number | bigint, b: number | bigint): bigint;
/**
* Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b
*
* @param {number|bigint} a
* @param {number|bigint} b
*
* @returns {bigint} minimum of numbers a and b
*/
export function min(a: number | bigint, b: number | bigint): bigint;
/**
* Modular inverse.
*
* @param {number|bigint} a The number to find an inverse for
* @param {number|bigint} n The modulo
*
* @returns {bigint} the inverse modulo n or NaN if it does not exist
*/
export function modInv(a: number | bigint, n: number | bigint): bigint;
/**
* Modular exponentiation b**e mod n. Currently using the right-to-left binary method
*
* @param {number|bigint} b base
* @param {number|bigint} e exponent
* @param {number|bigint} n modulo
*
* @returns {bigint} b**e mod n
*/
export function modPow(b: number | bigint, e: number | bigint, n: number | bigint): 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).
*
* @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
*
* @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
*/
export function prime(bitLength: number, iterations?: number): Promise<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.
*
* @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
*
* @returns {bigint} A bigint probable prime of bitLength bits.
*/
export function primeSync(bitLength: number, iterations?: number): bigint;
/**
* Returns a cryptographically secure random integer between [min,max]
* @param {bigint} max Returned value will be <= max
* @param {bigint} [min = BigInt(1)] Returned value will be >= min
*
* @returns {bigint} A cryptographically secure random bigint between [min,max]
*/
export function randBetween(max: bigint, min?: bigint): bigint;
/**
* Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
*
* @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
*
* @returns {Buffer|Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
export function randBits(bitLength: number, forceLength?: boolean): Uint8Array | Buffer;
/**
* Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
*
* @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
*
* @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>;
/**
* Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
*
* @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
*
* @returns {Buffer|Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
export function randBytesSync(byteLength: number, forceLength?: boolean): Uint8Array | Buffer;
/**
* Finds the smallest positive element that is congruent to a in modulo n
* @param {number|bigint} a An integer
* @param {number|bigint} n The modulo
*
* @returns {bigint} The smallest positive representation of a in modulo n
*/
export function toZn(a: number | bigint, n: number | bigint): bigint;