From 25484ae03f91e3b1a5876b4f5987957df3446d19 Mon Sep 17 00:00:00 2001
From: Juanra Dikal <j.hernandez@upc.edu>
Date: Mon, 1 Aug 2022 22:33:53 +0200
Subject: [PATCH] 3.1.4

---
 docs/API.md       | 533 ++++++++++++++++++++++++++++++++++++++++++++++
 package-lock.json |   4 +-
 package.json      |   2 +-
 3 files changed, 536 insertions(+), 3 deletions(-)
 create mode 100644 docs/API.md

diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..14ecb92
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,533 @@
+# bigint-crypto-utils - v3.1.4
+
+## Table of contents
+
+### Functions
+
+- [abs](API.md#abs)
+- [bitLength](API.md#bitlength)
+- [eGcd](API.md#egcd)
+- [gcd](API.md#gcd)
+- [isProbablyPrime](API.md#isprobablyprime)
+- [lcm](API.md#lcm)
+- [max](API.md#max)
+- [min](API.md#min)
+- [modInv](API.md#modinv)
+- [modPow](API.md#modpow)
+- [prime](API.md#prime)
+- [primeSync](API.md#primesync)
+- [randBetween](API.md#randbetween)
+- [randBits](API.md#randbits)
+- [randBitsSync](API.md#randbitssync)
+- [randBytes](API.md#randbytes)
+- [randBytesSync](API.md#randbytessync)
+- [toZn](API.md#tozn)
+
+## Functions
+
+### abs
+
+▸ **abs**(`a`): `number` \| `bigint`
+
+Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `a` | `number` \| `bigint` |
+
+#### Returns
+
+`number` \| `bigint`
+
+The absolute value of a
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/abs.d.ts:8
+
+___
+
+### bitLength
+
+▸ **bitLength**(`a`): `number`
+
+Returns the bitlength of a number
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `a` | `number` \| `bigint` |
+
+#### Returns
+
+`number`
+
+The bit length
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/bitLength.d.ts:7
+
+___
+
+### eGcd
+
+▸ **eGcd**(`a`, `b`): `Egcd`
+
+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).
+
+**`Throws`**
+
+This excepction is thrown if a or b are less than 0
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `a` | `number` \| `bigint` |
+| `b` | `number` \| `bigint` |
+
+#### Returns
+
+`Egcd`
+
+A triple (g, x, y), such that ax + by = g = gcd(a, b).
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/egcd.d.ts:18
+
+___
+
+### gcd
+
+▸ **gcd**(`a`, `b`): `bigint`
+
+Greatest-common divisor of two integers based on the iterative binary algorithm.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `a` | `number` \| `bigint` |
+| `b` | `number` \| `bigint` |
+
+#### Returns
+
+`bigint`
+
+The greatest common divisor of a and b
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/gcd.d.ts:9
+
+___
+
+### isProbablyPrime
+
+▸ **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)
+
+**`Throws`**
+
+w MUST be >= 0
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `w` | `number` \| `bigint` | `undefined` | A positive integer to be tested for primality |
+| `iterations` | `number` | `16` | The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3 |
+| `disableWorkers` | `boolean` | `false` | Disable the use of workers for the primality test |
+
+#### Returns
+
+`Promise`<`boolean`\>
+
+A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
+
+#### Defined in
+
+[src/ts/isProbablyPrime.ts:21](https://github.com/juanelas/bigint-crypto-utils/blob/de4fbee/src/ts/isProbablyPrime.ts#L21)
+
+___
+
+### lcm
+
+▸ **lcm**(`a`, `b`): `bigint`
+
+The least common multiple computed as abs(a*b)/gcd(a,b)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `a` | `number` \| `bigint` |
+| `b` | `number` \| `bigint` |
+
+#### Returns
+
+`bigint`
+
+The least common multiple of a and b
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/lcm.d.ts:8
+
+___
+
+### max
+
+▸ **max**(`a`, `b`): `number` \| `bigint`
+
+Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `a` | `number` \| `bigint` |
+| `b` | `number` \| `bigint` |
+
+#### Returns
+
+`number` \| `bigint`
+
+Maximum of numbers a and b
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/max.d.ts:9
+
+___
+
+### min
+
+▸ **min**(`a`, `b`): `number` \| `bigint`
+
+Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `a` | `number` \| `bigint` |
+| `b` | `number` \| `bigint` |
+
+#### Returns
+
+`number` \| `bigint`
+
+Minimum of numbers a and b
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/min.d.ts:9
+
+___
+
+### modInv
+
+▸ **modInv**(`a`, `n`): `bigint`
+
+Modular inverse.
+
+**`Throws`**
+
+Excpeption thorwn when a does not have inverse modulo n
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `a` | `number` \| `bigint` | The number to find an inverse for |
+| `n` | `number` \| `bigint` | The modulo |
+
+#### Returns
+
+`bigint`
+
+The inverse modulo n
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/modInv.d.ts:12
+
+___
+
+### modPow
+
+▸ **modPow**(`b`, `e`, `n`): `bigint`
+
+Modular exponentiation b**e mod n. Currently using the right-to-left binary method
+
+**`Throws`**
+
+Excpeption thrown when n is not > 0
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `b` | `number` \| `bigint` | base |
+| `e` | `number` \| `bigint` | exponent |
+| `n` | `number` \| `bigint` | modulo |
+
+#### Returns
+
+`bigint`
+
+b**e mod n
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/modPow.d.ts:13
+
+___
+
+### prime
+
+▸ **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).
+
+**`Throws`**
+
+bitLength MUST be > 0
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `bitLength` | `number` | `undefined` | The required bit length for the generated prime |
+| `iterations` | `number` | `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.
+
+#### Defined in
+
+[src/ts/prime.ts:29](https://github.com/juanelas/bigint-crypto-utils/blob/de4fbee/src/ts/prime.ts#L29)
+
+___
+
+### primeSync
+
+▸ **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.
+
+**`Throws`**
+
+bitLength MUST be > 0
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `bitLength` | `number` | `undefined` | The required bit length for the generated prime |
+| `iterations` | `number` | `16` | The number of iterations for the Miller-Rabin Probabilistic Primality Test |
+
+#### Returns
+
+`bigint`
+
+A bigint probable prime of bitLength bits.
+
+#### Defined in
+
+[src/ts/prime.ts:107](https://github.com/juanelas/bigint-crypto-utils/blob/de4fbee/src/ts/prime.ts#L107)
+
+___
+
+### randBetween
+
+▸ **randBetween**(`max`, `min?`): `bigint`
+
+Returns a cryptographically secure random integer between [min,max].
+
+**`Throws`**
+
+Arguments MUST be: max > min
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `max` | `bigint` | Returned value will be <= max |
+| `min` | `bigint` | Returned value will be >= min |
+
+#### Returns
+
+`bigint`
+
+A cryptographically secure random bigint between [min,max]
+
+#### Defined in
+
+[src/ts/randBetween.ts:15](https://github.com/juanelas/bigint-crypto-utils/blob/de4fbee/src/ts/randBetween.ts#L15)
+
+___
+
+### randBits
+
+▸ **randBits**(`bitLength`, `forceLength?`): `Promise`<`Uint8Array` \| `Buffer`\>
+
+Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
+
+**`Throws`**
+
+bitLength MUST be > 0
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `bitLength` | `number` | `undefined` | The desired number of random bits |
+| `forceLength` | `boolean` | `false` | If we want to force the output to have a specific bit length. It basically forces the msb to be 1 |
+
+#### Returns
+
+`Promise`<`Uint8Array` \| `Buffer`\>
+
+A Promise that resolves to a UInt8Array/Buffer (Browser/Node.js) filled with cryptographically secure random bits
+
+#### Defined in
+
+[src/ts/randBits.ts:14](https://github.com/juanelas/bigint-crypto-utils/blob/de4fbee/src/ts/randBits.ts#L14)
+
+___
+
+### randBitsSync
+
+▸ **randBitsSync**(`bitLength`, `forceLength?`): `Uint8Array` \| `Buffer`
+
+Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
+
+**`Throws`**
+
+bitLength MUST be > 0
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `bitLength` | `number` | `undefined` | The desired number of random bits |
+| `forceLength` | `boolean` | `false` | If we want to force the output to have a specific bit length. It basically forces the msb to be 1 |
+
+#### Returns
+
+`Uint8Array` \| `Buffer`
+
+A Uint8Array/Buffer (Browser/Node.js) filled with cryptographically secure random bits
+
+#### Defined in
+
+[src/ts/randBits.ts:45](https://github.com/juanelas/bigint-crypto-utils/blob/de4fbee/src/ts/randBits.ts#L45)
+
+___
+
+### randBytes
+
+▸ **randBytes**(`byteLength`, `forceLength?`): `Promise`<`Uint8Array` \| `Buffer`\>
+
+Secure random bytes for both node and browsers. Node version uses crypto.randomBytes() and browser one self.crypto.getRandomValues()
+
+**`Throws`**
+
+byteLength MUST be > 0
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `byteLength` | `number` | `undefined` | 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 |
+
+#### Returns
+
+`Promise`<`Uint8Array` \| `Buffer`\>
+
+A promise that resolves to a UInt8Array/Buffer (Browser/Node.js) filled with cryptographically secure random bytes
+
+#### Defined in
+
+[src/ts/randBytes.ts:14](https://github.com/juanelas/bigint-crypto-utils/blob/de4fbee/src/ts/randBytes.ts#L14)
+
+___
+
+### randBytesSync
+
+▸ **randBytesSync**(`byteLength`, `forceLength?`): `Uint8Array` \| `Buffer`
+
+Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
+
+**`Throws`**
+
+byteLength MUST be > 0
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `byteLength` | `number` | `undefined` | 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 |
+
+#### Returns
+
+`Uint8Array` \| `Buffer`
+
+A UInt8Array/Buffer (Browser/Node.js) filled with cryptographically secure random bytes
+
+#### Defined in
+
+[src/ts/randBytes.ts:46](https://github.com/juanelas/bigint-crypto-utils/blob/de4fbee/src/ts/randBytes.ts#L46)
+
+___
+
+### toZn
+
+▸ **toZn**(`a`, `n`): `bigint`
+
+Finds the smallest positive element that is congruent to a in modulo n
+
+**`Remarks`**
+
+a and b must be the same type, either number or bigint
+
+**`Throws`**
+
+Excpeption thrown when n is not > 0
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `a` | `number` \| `bigint` | An integer |
+| `n` | `number` \| `bigint` | The modulo |
+
+#### Returns
+
+`bigint`
+
+A bigint with the smallest positive representation of a modulo n
+
+#### Defined in
+
+node_modules/bigint-mod-arith/types/toZn.d.ts:15
diff --git a/package-lock.json b/package-lock.json
index cc3f95c..7bf38e1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "bigint-crypto-utils",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "bigint-crypto-utils",
-      "version": "3.1.3",
+      "version": "3.1.4",
       "license": "MIT",
       "dependencies": {
         "bigint-mod-arith": "^3.1.0"
diff --git a/package.json b/package.json
index b4fd688..c672a48 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bigint-crypto-utils",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "description": "Arbitrary precision modular arithmetic, cryptographically secure random numbers and strong probable prime generation/testing. It works in modern browsers, Angular, React, Node.js, etc. since it uses the native JS implementation of BigInt",
   "keywords": [
     "modular arithmetics",