bigint-crypto-utils/src/doc/readme-template.md

[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

# bigint-crypto-utils

Utils for working with cryptography using native JS ([ES-2020](https://tc39.es/ecma262/#sec-bigint-objects)) implementation of BigInt. It includes some extra functions to work with modular arithmetic along with secure random numbers and a fast strong probable prime generator/tester (parallelized multi-threaded Miller-Rabin primality tests if workers are supported). It can be used by any [Web Browser or webview supporting BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#Browser_compatibility) and with Node.js (>=10.4.0).

> The operations supported on BigInts are not constant time. BigInt can be therefore **[unsuitable for use in cryptography](https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html).** Many platforms provide native support for cryptography, such as [Web Cryptography API](https://w3c.github.io/webcrypto/) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html).

## 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
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.iife.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.mod.js) from GitHub.

## Usage examples

Import your module as :

 - Node.js
   ```javascript
   const bigintCryptoUtils = require('bigint-crypto-utils')
   ... // your code here
   ```
 - JavaScript native or TypeScript project
   ```javascript
   import * as bigintCryptoUtils from 'bigint-crypto-utils'
   ... // your code here
   ```
   > BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`.
 - JavaScript native browser ES6 mod
   ```html
   <script type="module">
      import * as bigintCryptoUtils from 'lib/index.browser.bundle.mod.js'  // Use you actual path to the broser mod bundle
      ... // your code here
    </script>
   ```
 - JavaScript native browser IIFE
   ```html
   <head>
     ...
     <script src="../../lib/index.browser.bundle.js"></script> <!-- Use you actual path to the browser bundle -->
   </head>
   <body>
     ...
     <script>
       ... // your code here
     </script>
   </body>
   ```

An example of usage could be:

```javascript
/* A BigInt with value 666 can be declared calling the bigint constructor as 
BigInt('666') or with the shorter 666n.
Notice that you can also pass a number to the constructor, e.g. BigInt(666). 
However, it is not recommended since values over 2**53 - 1 won't be safe but 
no warning will be raised.
*/
const a = BigInt('5')
const b = BigInt('2')
const n = 19n

console.log(bigintCryptoUtils.modPow(a, b, n)) // prints 6

console.log(bigintCryptoUtils.modInv(2n, 5n)) // prints 3

console.log(bigintCryptoUtils.modInv(BigInt('3'), BigInt('5'))) // prints 2

console.log(bigintCryptoUtils.randBetween(2n ** 256n)) // Prints a cryptographically secure random number between 1 and 2**256 bits.

async function primeTesting () {
  // Output of a probable prime of 2048 bits
  console.log(await bigintCryptoUtils.prime(2048))

  // Testing if a number is a probable prime (Miller-Rabin)
  const number = 27n
  const isPrime = await bigintCryptoUtils.isProbablyPrime(number)
  if (isPrime) {
    console.log(`${number} is prime`)
  } else {
    console.log(`${number} is composite`)
  }
}

primeTesting()

```

You can find examples in the [examples folder of the repository](https://github.com/juanelas/bigint-crypto-utils/tree/master/examples).


## API reference documentation

{{>main}}
JS Standard. Some fixes with the test. Better structure 2020-04-06 11:17:22 +00:00			`[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)`

Fixed typo 2019-04-21 07:50:50 +00:00			`# bigint-crypto-utils`
working with worker file 2019-04-19 07:42:28 +00:00
Examples of code. If a webview doesn't support Web Workers, they are not used 2020-04-08 15:09:52 +00:00			Utils for working with cryptography using native JS ([ES-2020](https://tc39.es/ecma262/#sec-bigint-objects)) implementation of BigInt. It includes some extra functions to work with modular arithmetic along with secure random numbers and a fast strong probable prime generator/tester (parallelized multi-threaded Miller-Rabin primality tests if workers are supported). It can be used by any [Web Browser or webview supporting BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#Browser_compatibility) and with Node.js (>=10.4.0).
working with worker file 2019-04-19 07:42:28 +00:00
updated readme: BigInt is now is es2020, instructions for typescript 2020-02-27 20:51:48 +00:00			`> The operations supported on BigInts are not constant time. BigInt can be therefore [unsuitable for use in cryptography](https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html). Many platforms provide native support for cryptography, such as [Web Cryptography API](https://w3c.github.io/webcrypto/) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html).`
working with worker file 2019-04-19 07:42:28 +00:00
			`## Installation`
updated readme: BigInt is now is es2020, instructions for typescript 2020-02-27 20:51:48 +00:00
fixed line wrapping in README.hbs 2019-04-25 15:28:42 +00:00			`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.`
working with worker file 2019-04-19 07:42:28 +00:00
Working! 2019-04-19 10:04:06 +00:00			bigint-crypto-utils can be imported to your project with `npm`:
updated readme: BigInt is now is es2020, instructions for typescript 2020-02-27 20:51:48 +00:00
working with worker file 2019-04-19 07:42:28 +00:00			```bash
Working! 2019-04-19 10:04:06 +00:00			`npm install bigint-crypto-utils`
working with worker file 2019-04-19 07:42:28 +00:00			```
updated readme: BigInt is now is es2020, instructions for typescript 2020-02-27 20:51:48 +00:00
Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00			`NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js.`
working with worker file 2019-04-19 07:42:28 +00:00
better dependencies 2020-04-07 22:21:02 +00:00			`For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.iife.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/lib/index.browser.bundle.mod.js) from GitHub.`
working with worker file 2019-04-19 07:42:28 +00:00
updated readme: BigInt is now is es2020, instructions for typescript 2020-02-27 20:51:48 +00:00			`## Usage examples`

shorter but better readme 2020-04-06 12:17:24 +00:00			`Import your module as :`

			`- Node.js`
			```javascript
			`const bigintCryptoUtils = require('bigint-crypto-utils')`
			`... // your code here`
			```
better dependencies 2020-04-07 22:21:02 +00:00			`- JavaScript native or TypeScript project`
shorter but better readme 2020-04-06 12:17:24 +00:00			```javascript
			`import * as bigintCryptoUtils from 'bigint-crypto-utils'`
			`... // your code here`
			```
better dependencies 2020-04-07 22:21:02 +00:00			> BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`.
Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00			`- JavaScript native browser ES6 mod`
shorter but better readme 2020-04-06 12:17:24 +00:00			```html
			`<script type="module">`
			`import * as bigintCryptoUtils from 'lib/index.browser.bundle.mod.js' // Use you actual path to the broser mod bundle`
			`... // your code here`
			`</script>`
			```
Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00			`- JavaScript native browser IIFE`
shorter but better readme 2020-04-06 12:17:24 +00:00			```html
better dependencies 2020-04-07 22:21:02 +00:00			`<head>`
			`...`
			`<script src="../../lib/index.browser.bundle.js"></script> <!-- Use you actual path to the browser bundle -->`
			`</head>`
			`<body>`
			`...`
			`<script>`
			`... // your code here`
			`</script>`
			`</body>`
Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00			```
working with worker file 2019-04-19 07:42:28 +00:00
Examples of code. If a webview doesn't support Web Workers, they are not used 2020-04-08 15:09:52 +00:00			`An example of usage could be:`
Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00
working with worker file 2019-04-19 07:42:28 +00:00			```javascript
Examples of code. If a webview doesn't support Web Workers, they are not used 2020-04-08 15:09:52 +00:00			`/* A BigInt with value 666 can be declared calling the bigint constructor as`
			`BigInt('666') or with the shorter 666n.`
			`Notice that you can also pass a number to the constructor, e.g. BigInt(666).`
			`However, it is not recommended since values over 2**53 - 1 won't be safe but`
			`no warning will be raised.`
Fixed typo 2019-04-21 07:39:28 +00:00			`*/`
shorter but better readme 2020-04-06 12:17:24 +00:00			`const a = BigInt('5')`
			`const b = BigInt('2')`
Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00			`const n = 19n`
working with worker file 2019-04-19 07:42:28 +00:00
shorter but better readme 2020-04-06 12:17:24 +00:00			`console.log(bigintCryptoUtils.modPow(a, b, n)) // prints 6`
updated readme: BigInt is now is es2020, instructions for typescript 2020-02-27 20:51:48 +00:00
Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00			`console.log(bigintCryptoUtils.modInv(2n, 5n)) // prints 3`
working with worker file 2019-04-19 07:42:28 +00:00
shorter but better readme 2020-04-06 12:17:24 +00:00			`console.log(bigintCryptoUtils.modInv(BigInt('3'), BigInt('5'))) // prints 2`
working with worker file 2019-04-19 07:42:28 +00:00
Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00			`console.log(bigintCryptoUtils.randBetween(2n 256n)) // Prints a cryptographically secure random number between 1 and 2256 bits.`
working with worker file 2019-04-19 07:42:28 +00:00
shorter but better readme 2020-04-06 12:17:24 +00:00			`async function primeTesting () {`
			`// Output of a probable prime of 2048 bits`
			`console.log(await bigintCryptoUtils.prime(2048))`
working with worker file 2019-04-19 07:42:28 +00:00
shorter but better readme 2020-04-06 12:17:24 +00:00			`// Testing if a number is a probable prime (Miller-Rabin)`
Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00			`const number = 27n`
shorter but better readme 2020-04-06 12:17:24 +00:00			`const isPrime = await bigintCryptoUtils.isProbablyPrime(number)`
			`if (isPrime) {`
			console.log(`${number} is prime`)
			`} else {`
			console.log(`${number} is composite`)
			`}`
			`}`
working with worker file 2019-04-19 07:42:28 +00:00
shorter but better readme 2020-04-06 12:17:24 +00:00			`primeTesting()`
working with worker file 2019-04-19 07:42:28 +00:00
			```

Examples of code. If a webview doesn't support Web Workers, they are not used 2020-04-08 15:09:52 +00:00			`You can find examples in the [examples folder of the repository](https://github.com/juanelas/bigint-crypto-utils/tree/master/examples).`


Now the bundle can be mangled. Multi-threaded uses all CPUs but 1. Readme improvements 2020-04-07 15:03:30 +00:00			`## API reference documentation`
working with worker file 2019-04-19 07:42:28 +00:00
			`{{>main}}`