From 2179954b1e651f6668363efe4044771f6c521d26 Mon Sep 17 00:00:00 2001 From: juanelas Date: Tue, 21 Apr 2020 01:33:41 +0200 Subject: [PATCH] fixed doc --- README.md | 220 ++++++++++++++++++++++++++++++++++++- build/build.docs.js | 12 +- src/doc/readme-template.md | 2 - 3 files changed, 226 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 8b71e6a..e9ef641 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,6 @@ Secure random numbers are generated using the native crypto implementation of th ## Installation -bigint-crypto-utils is distributed for [web browsers and/or webviews supporting BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#Browser_compatibility) as an ES6 module or an IIFE file; and for Node.js (>=10.4.0), as a CJS module. - bigint-crypto-utils can be imported to your project with `npm`: ```bash @@ -122,6 +120,210 @@ You can find examples in the [examples folder of the repository](https://github. ## API reference documentation +### Functions + +
+
abs(a) ⇒ bigint
+

Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0

+
+
bitLength(a) ⇒ number
+

Returns the bitlength of a number

+
+
eGcd(a, b) ⇒ egcdReturn
+

An iterative implementation of the extended euclidean algorithm or extended greatest common divisor algorithm. +Take positive integers a, b as input, and return a triple (g, x, y), such that ax + by = g = gcd(a, b).

+
+
gcd(a, b) ⇒ bigint
+

Greatest-common divisor of two integers based on the iterative binary algorithm.

+
+
lcm(a, b) ⇒ bigint
+

The least common multiple computed as abs(a*b)/gcd(a,b)

+
+
max(a, b) ⇒ bigint
+

Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b

+
+
min(a, b) ⇒ bigint
+

Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b

+
+
modInv(a, n) ⇒ bigint | NaN
+

Modular inverse.

+
+
modPow(b, e, n) ⇒ bigint
+

Modular exponentiation b**e mod n. Currently using the right-to-left binary method

+
+
toZn(a, n) ⇒ bigint
+

Finds the smallest positive element that is congruent to a in modulo n

+
+
isProbablyPrime(w, [iterations], [disableWorkers]) ⇒ Promise.<boolean>
+

The test first tries if any of the first 250 small primes are a factor of the input number and then passes several +iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)

+
+
prime(bitLength, [iterations]) ⇒ Promise.<bigint>
+

A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator. +The browser version uses web workers to parallelise prime look up. Therefore, it does not lock the UI +main process, and it can be much faster (if several cores or cpu are available). +The node version can also use worker_threads if they are available (enabled by default with Node 11 and +and can be enabled at runtime executing node --experimental-worker with node >=10.5.0).

+
+
primeSync(bitLength, [iterations]) ⇒ bigint
+

A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator. +The sync version is NOT RECOMMENDED since it won't use workers and thus it'll be slower and may freeze thw window in browser's javascript. Please consider using prime() instead.

+
+
randBetween(max, [min]) ⇒ bigint
+

Returns a cryptographically secure random integer between [min,max]. Both numbers must be >=0

+
+
randBits(bitLength, [forceLength]) ⇒ Promise.<(Buffer|Uint8Array)>
+

Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()

+
+
randBitsSync(bitLength, [forceLength]) ⇒ Buffer | Uint8Array
+

Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()

+
+
randBytes(byteLength, [forceLength]) ⇒ Promise.<(Buffer|Uint8Array)>
+

Secure random bytes for both node and browsers. Node version uses crypto.randomBytes() and browser one self.crypto.getRandomValues()

+
+
randBytesSync(byteLength, [forceLength]) ⇒ Buffer | Uint8Array
+

Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()

+
+
+ +### Typedefs + +
+
egcdReturn : Object
+

A triple (g, x, y), such that ax + by = g = gcd(a, b).

+
+
+ + + +### abs(a) ⇒ bigint +Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 + +**Kind**: global function +**Returns**: bigint - the absolute value of a + +| Param | Type | +| --- | --- | +| a | number \| bigint | + + + +### bitLength(a) ⇒ number +Returns the bitlength of a number + +**Kind**: global function +**Returns**: number - - the bit length + +| Param | Type | +| --- | --- | +| a | number \| bigint | + + + +### eGcd(a, b) ⇒ [egcdReturn](#egcdReturn) +An iterative implementation of the extended euclidean algorithm or extended greatest common divisor algorithm. +Take positive integers a, b as input, and return a triple (g, x, y), such that ax + by = g = gcd(a, b). + +**Kind**: global function +**Returns**: [egcdReturn](#egcdReturn) - A triple (g, x, y), such that ax + by = g = gcd(a, b). + +| Param | Type | +| --- | --- | +| a | number \| bigint | +| b | number \| bigint | + + + +### gcd(a, b) ⇒ bigint +Greatest-common divisor of two integers based on the iterative binary algorithm. + +**Kind**: global function +**Returns**: bigint - The greatest common divisor of a and b + +| Param | Type | +| --- | --- | +| a | number \| bigint | +| b | number \| bigint | + + + +### lcm(a, b) ⇒ bigint +The least common multiple computed as abs(a*b)/gcd(a,b) + +**Kind**: global function +**Returns**: bigint - The least common multiple of a and b + +| Param | Type | +| --- | --- | +| a | number \| bigint | +| b | number \| bigint | + + + +### max(a, b) ⇒ bigint +Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b + +**Kind**: global function +**Returns**: bigint - maximum of numbers a and b + +| Param | Type | +| --- | --- | +| a | number \| bigint | +| b | number \| bigint | + + + +### min(a, b) ⇒ bigint +Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b + +**Kind**: global function +**Returns**: bigint - minimum of numbers a and b + +| Param | Type | +| --- | --- | +| a | number \| bigint | +| b | number \| bigint | + + + +### modInv(a, n) ⇒ bigint \| NaN +Modular inverse. + +**Kind**: global function +**Returns**: bigint \| NaN - the inverse modulo n or NaN if it does not exist + +| Param | Type | Description | +| --- | --- | --- | +| a | number \| bigint | The number to find an inverse for | +| n | number \| bigint | The modulo | + + + +### modPow(b, e, n) ⇒ bigint +Modular exponentiation b**e mod n. Currently using the right-to-left binary method + +**Kind**: global function +**Returns**: bigint - b**e mod n + +| Param | Type | Description | +| --- | --- | --- | +| b | number \| bigint | base | +| e | number \| bigint | exponent | +| n | number \| bigint | modulo | + + + +### toZn(a, n) ⇒ bigint +Finds the smallest positive element that is congruent to a in modulo n + +**Kind**: global function +**Returns**: bigint - The smallest positive representation of a in modulo n + +| Param | Type | Description | +| --- | --- | --- | +| a | number \| bigint | An integer | +| n | number \| bigint | The modulo | + ### isProbablyPrime(w, [iterations], [disableWorkers]) ⇒ Promise.<boolean> @@ -233,3 +435,17 @@ Secure random bytes for both node and browsers. Node version uses crypto.randomF | byteLength | number | | The desired number of random bytes | | [forceLength] | boolean | false | If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1 | + + +### egcdReturn : Object +A triple (g, x, y), such that ax + by = g = gcd(a, b). + +**Kind**: global typedef +**Properties** + +| Name | Type | +| --- | --- | +| g | bigint | +| x | bigint | +| y | bigint | + diff --git a/build/build.docs.js b/build/build.docs.js index afc6d51..3544b68 100644 --- a/build/build.docs.js +++ b/build/build.docs.js @@ -49,15 +49,19 @@ if (repoProvider && repoProvider === 'github') { template = template.replace(/\{\{GITHUB_ACTIONS_BADGES\}\}/g, workflowBadget + '\n' + coverallsBadge) } -const input = path.join(rootDir, pkgJson.browser) +const input1 = path.join(rootDir, 'node_modules', 'bigint-mod-arith', pkgJson.browser) // bigint-mod-arith +const input2 = path.join(rootDir, pkgJson.browser) // this module + // Let us replace bigint literals by standard numbers to avoid issues with bigint -const source = fs.readFileSync(input, { encoding: 'UTF-8' }).replace(/([0-9]+)n([,\s\n)])/g, '$1$2') +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. + '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(() => { diff --git a/src/doc/readme-template.md b/src/doc/readme-template.md index 0ecc36c..4d80f54 100644 --- a/src/doc/readme-template.md +++ b/src/doc/readme-template.md @@ -14,8 +14,6 @@ Secure random numbers are generated using the native crypto implementation of th ## Installation -{{PKG_NAME}} is distributed for [web browsers and/or webviews supporting BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#Browser_compatibility) as an ES6 module or an IIFE file; and for Node.js (>=10.4.0), as a CJS module. - {{PKG_NAME}} can be imported to your project with `npm`: ```bash