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

updated usage instructions. updated deps

This commit is contained in:
juanelas 2020-11-12 12:04:13 +01:00
parent 98c552773b
commit ee20c7d313
12 changed files with 1191 additions and 1283 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@ -9,7 +9,7 @@ Arbitrary precision modular arithmetic, cryptographically secure random numbers
It relies on the native JS implementation of ([BigInt](https://tc39.es/ecma262/#sec-bigint-objects)). 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 bundles can be imported directly by the browser or in Angular projects, React apps, Node.js, etc.
Secure random numbers are generated using the native crypto implementation of the browsers ([Web Cryptography API](https://w3c.github.io/webcrypto/)) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html)). Strong probable prime generation and testing use Miller-Rabin primality tests and are automatically sped up using parallel workers both in browsers and Node.js.
Secure random numbers are generated using the native crypto implementation of the browsers ([Web Cryptography API](https://w3c.github.io/webcrypto/)) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html)). Strong probable prime generation and testing use Miller-Rabin primality tests and are automatically sped up using parallel workers both in browsers and Node.js.
> 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).
@ -27,17 +27,22 @@ NPM installation defaults to the ES6 module for browsers and the CJS one for Nod
Import your module as :
- Node.js
- Node.js
```javascript
const bigintCryptoUtils = require('bigint-crypto-utils')
... // your code here
```
- JavaScript native or TypeScript project (including React and Angular JS)
- JavaScript native or TypeScript project (including React and Angular JS)
```javascript
import * as bigintCryptoUtils from 'bigint-crypto-utils'
... // your code here
```
`bigint-crypto-utils` **CANNOT BE POLYFILLED** to suport older browsers. If you are using webpack/babel to create your production bundles, you should target only the most modern browsers. For instance, for **React** apps created with [`create-react-app`](https://create-react-app.dev/), you should edit your `package.json` and modify the `browserList` so that it only targets the latest browsers (supporting the latest features):
`bigint-crypto-utils` **CANNOT BE POLYFILLED** to suport older browsers. If you are using webpack/babel to create your production bundles, you should target only the most modern browsers. For instance, for **React** apps created with [`create-react-app`](https://create-react-app.dev/), you should edit your `package.json` and modify the `browserList` so that it only targets the latest browsers (play with the number of versions that do not need polyfilling):
```json
"browserslist": {
"production": [
@ -52,20 +57,33 @@ Import your module as :
]
}
```
Also, notice that [BigInt implementation is quite recent](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you will probably need to set `lib`, `target` and/or `module` to `esnext` in your project's `tsconfig.json`.
- JavaScript native browser ES module
Also, notice that [BigInt implementation is ES2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you will probably need to set `lib`, `target` and/or `module` to `es2020` in your project's `tsconfig.json`.
If you are using Angular, since this library uses node typings, you should also add them to the `angularCompilerOptions` in your `tsconfig.json`:
```json
"angularCompilerOptions": {
"types": ["node"]
...
}
```
- JavaScript native browser ES module
```html
<script type="module">
import * as bigintCryptoUtils from 'lib/index.browser.bundle.mod.js' // Use you actual path to the broser mod bundle
import * as bigintCryptoUtils from 'index.browser.bundle.mod.js' // Use your actual path to the broser mod bundle that is in the lib directory
... // your code here
</script>
```
- JavaScript native browser IIFE
- JavaScript native browser IIFE
```html
<head>
...
<script src="../../lib/index.browser.bundle.iife.js"></script> <!-- Use you actual path to the browser bundle -->
<script src="index.browser.bundle.iife.js"></script> <!-- Use your actual path to the browser iife bundle that is in the lib directory -->
</head>
<body>
...
@ -78,10 +96,10 @@ Import your module as :
An example of usage could be:
```javascript
/* A BigInt with value 666 can be declared calling the bigint constructor as
/* 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
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')
@ -116,7 +134,6 @@ 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
### Functions

2
build/rollup.config.js
View File

@ -1,6 +1,6 @@
'use strict'
const resolve = require('@rollup/plugin-node-resolve')
const resolve = require('@rollup/plugin-node-resolve').nodeResolve
const replace = require('@rollup/plugin-replace')
const { terser } = require('rollup-plugin-terser')

2
build/rollup.tests.config.js
View File

@ -1,6 +1,6 @@
'use strict'
const resolve = require('@rollup/plugin-node-resolve')
const resolve = require('@rollup/plugin-node-resolve').nodeResolve
const replace = require('@rollup/plugin-replace')
const commonjs = require('@rollup/plugin-commonjs')
const multi = require('@rollup/plugin-multi-entry')

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

2340
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

20
package.json
View File

@ -64,21 +64,21 @@
]
},
"devDependencies": {
"@rollup/plugin-commonjs": "^11.1.0",
"@rollup/plugin-multi-entry": "^3.0.1",
"@rollup/plugin-node-resolve": "^7.1.3",
"@rollup/plugin-replace": "^2.3.3",
"@rollup/plugin-commonjs": "^16.0.0",
"@rollup/plugin-multi-entry": "^4.0.0",
"@rollup/plugin-node-resolve": "^10.0.0",
"@rollup/plugin-replace": "^2.3.4",
"chai": "^4.2.0",
"jsdoc-to-markdown": "^5.0.3",
"mocha": "^7.2.0",
"jsdoc-to-markdown": "^6.0.1",
"mocha": "^8.2.1",
"npm-run-all": "^4.1.5",
"nyc": "^15.1.0",
"rollup": "^2.28.1",
"rollup-plugin-terser": "^5.3.1",
"standard": "^14.3.4",
"rollup": "^2.33.1",
"rollup-plugin-terser": "^7.0.2",
"standard": "^16.0.2",
"typescript": "^3.9.7"
},
"dependencies": {
"@types/node": "^14.11.2"
"@types/node": ">=10.4"
}
}

43
src/doc/readme-template.md
View File

@ -8,7 +8,7 @@ Arbitrary precision modular arithmetic, cryptographically secure random numbers
It relies on the native JS implementation of ([BigInt](https://tc39.es/ecma262/#sec-bigint-objects)). 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 bundles can be imported directly by the browser or in Angular projects, React apps, Node.js, etc.
Secure random numbers are generated using the native crypto implementation of the browsers ([Web Cryptography API](https://w3c.github.io/webcrypto/)) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html)). Strong probable prime generation and testing use Miller-Rabin primality tests and are automatically sped up using parallel workers both in browsers and Node.js.
Secure random numbers are generated using the native crypto implementation of the browsers ([Web Cryptography API](https://w3c.github.io/webcrypto/)) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html)). Strong probable prime generation and testing use Miller-Rabin primality tests and are automatically sped up using parallel workers both in browsers and Node.js.
> 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).
@ -26,17 +26,22 @@ NPM installation defaults to the ES6 module for browsers and the CJS one for Nod
Import your module as :
- Node.js
- Node.js
```javascript
const bigintCryptoUtils = require('bigint-crypto-utils')
... // your code here
```
- JavaScript native or TypeScript project (including React and Angular JS)
- JavaScript native or TypeScript project (including React and Angular JS)
```javascript
import * as bigintCryptoUtils from 'bigint-crypto-utils'
... // your code here
```
`{{PKG_NAME}}` **CANNOT BE POLYFILLED** to suport older browsers. If you are using webpack/babel to create your production bundles, you should target only the most modern browsers. For instance, for **React** apps created with [`create-react-app`](https://create-react-app.dev/), you should edit your `package.json` and modify the `browserList` so that it only targets the latest browsers (supporting the latest features):
`{{PKG_NAME}}` **CANNOT BE POLYFILLED** to suport older browsers. If you are using webpack/babel to create your production bundles, you should target only the most modern browsers. For instance, for **React** apps created with [`create-react-app`](https://create-react-app.dev/), you should edit your `package.json` and modify the `browserList` so that it only targets the latest browsers (play with the number of versions that do not need polyfilling):
```json
"browserslist": {
"production": [
@ -51,20 +56,33 @@ Import your module as :
]
}
```
Also, notice that [BigInt implementation is quite recent](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you will probably need to set `lib`, `target` and/or `module` to `esnext` in your project's `tsconfig.json`.
- JavaScript native browser ES module
Also, notice that [BigInt implementation is ES2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you will probably need to set `lib`, `target` and/or `module` to `es2020` in your project's `tsconfig.json`.
If you are using Angular, since this library uses node typings, you should also add them to the `angularCompilerOptions` in your `tsconfig.json`:
```json
"angularCompilerOptions": {
"types": ["node"]
...
}
```
- JavaScript native browser ES module
```html
<script type="module">
import * as bigintCryptoUtils from 'lib/index.browser.bundle.mod.js' // Use you actual path to the broser mod bundle
import * as bigintCryptoUtils from 'index.browser.bundle.mod.js' // Use your actual path to the broser mod bundle that is in the lib directory
... // your code here
</script>
```
- JavaScript native browser IIFE
- JavaScript native browser IIFE
```html
<head>
...
<script src="../../lib/index.browser.bundle.iife.js"></script> <!-- Use you actual path to the browser bundle -->
<script src="index.browser.bundle.iife.js"></script> <!-- Use your actual path to the browser iife bundle that is in the lib directory -->
</head>
<body>
...
@ -77,10 +95,10 @@ Import your module as :
An example of usage could be:
```javascript
/* A BigInt with value 666 can be declared calling the bigint constructor as
/* 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
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')
@ -115,7 +133,6 @@ 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}}

4
test/bitLength.js
View File

@ -16,8 +16,8 @@ const inputs = [
bitLength: 2
},
{
value: BigInt(11592217955149597331),
abs: BigInt(11592217955149597331),
value: BigInt('11592217955149597331'),
abs: BigInt('11592217955149597331'),
bitLength: 64
}
]

4
test/browser/index.html
View File

@ -3,8 +3,8 @@
<head>
<title>bigint-crypto-utils - Mocha Tests</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/mocha/7.1.2/mocha.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/mocha/7.1.2/mocha.min.js"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/mocha/8.2.1/mocha.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/mocha/8.2.1/mocha.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/chai/4.2.0/chai.min.js"></script>
</head>

4
test/browser/tests.js
View File

@ -50,8 +50,8 @@ const inputs$1 = [
bitLength: 2
},
{
value: BigInt(11592217955149597331),
abs: BigInt(11592217955149597331),
value: BigInt('11592217955149597331'),
abs: BigInt('11592217955149597331'),
bitLength: 64
}
];

8
types/index.d.ts vendored
View File

@ -155,7 +155,7 @@ export function randBetween(max: bigint, min?: bigint): bigint;
*
* @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>;
export function randBits(bitLength: number, forceLength?: boolean): Promise<Buffer | Uint8Array>;
/**
* 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
@ -165,7 +165,7 @@ export function randBits(bitLength: number, forceLength?: boolean): Promise<Uint
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
*/
export function randBitsSync(bitLength: number, forceLength?: boolean): Uint8Array | Buffer;
export function randBitsSync(bitLength: number, forceLength?: boolean): Buffer | Uint8Array;
/**
* Secure random bytes for both node and browsers. Node version uses crypto.randomBytes() and browser one self.crypto.getRandomValues()
*
@ -176,7 +176,7 @@ export function randBitsSync(bitLength: number, forceLength?: boolean): Uint8Arr
*
* @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>;
export function randBytes(byteLength: number, forceLength?: boolean): Promise<Buffer | Uint8Array>;
/**
* Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
*
@ -187,7 +187,7 @@ export function randBytes(byteLength: number, forceLength?: boolean): Promise<Ui
*
* @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
*/
export function randBytesSync(byteLength: number, forceLength?: boolean): Uint8Array | Buffer;
export function randBytesSync(byteLength: number, forceLength?: boolean): Buffer | Uint8Array;
/**
* Finds the smallest positive element that is congruent to a in modulo n
* @param {number|bigint} a An integer