JavaScript Cryptographic Utilities for Browsers and Node.js Crypto-Suite Compatibility

WARNING: At this time this solution should be considered suitable for research and experimentation, further code and security review is needed before utilization in a production application.

Overview

This library is being developed to provide unified cryptographic APIs for browsers and Node.js. There currently exist various sophisticated cryptographic suites for JavaScript that are implemented as native functions, e.g., WebCrypto API and crypto in Node.js. However, they have different interfaces and are NOT supported at all platforms. For instance, FireFox cannot be fed PKCS8-formatted private key in WebCrypto API but Chrome does. On the other hand, such suites have not been designed to keep compatibility to existing non-Web cryptographic suites like OpenSSL. This can be seen from the fact that WebCrypto API does not support PEM-formatted keys. Hence we (actually I!) need to write ugly codes so as to enable apps to work in various environments. From this observation, we aim that this library provides support functions to fill such gaps among JS cryptographic suites and that between JavaScript and other popular crypto suites.

Firstly, this library provides following functions that works in most modern browsers and Node.js.

• ECDSA signing, verification, key generation (P-256/P-384/P-521/P-256K)
• RSA-PSS/RSASSA-PKCS1-v1_5 signing, verification, key generation.
• Encryption using ECDH and HKDF.
• Encryption using RSA-OAEP.
• Public/private key format conversion between JWK and PEM/DER (SPKI for public/PKCS8 for private)
• Generation of JWK Thumbprint
• Generation of X.509 public key certificate from JWK and extraction of JWK public key from X.509 public key certificate. Additionally, this library provides random, hash, AES, HMAC, HKDF, and PBKDF functions.

Module structure

The module structure of this library can be illustrated as follows.

/**
 * index.js
 * Structure of API
 *  |-- Key (Key object handling EC and RSA public/private keys)
 *  |
 *  |-- pkc (public key crypto, EC and RSA)
 *  |    |-- generateKey
 *  |    |-- encrypt
 *  |    |-- decrypt
 *  |    |-- sign
 *  |    |-- verify
 *  |
 *  |-- x509
 *  |    |-- toJwk
 *  |    |-- fromJwk
 *  |    |-- parse (to verify)
 *  |
 *  |-- aes
 *  |-- random
 *  |-- hash
 *  |-- hmac
 *  |-- hkdf
 *  |-- pbkdf
 */

We should note that most of this library's functions are independently available through NPM and GitHub as modules. In other words, this library is being developed as an integrated wrapper of those independent modules. The independent modules are listed as follows:

• Key: https://github.com/junkurihara/jscu/tree/develop/packages/js-crypto-key-utils
• pkc (EC): https://github.com/junkurihara/jscu/tree/develop/packages/js-crypto-ec
• pkc (RSA): https://github.com/junkurihara/jscu/tree/develop/packages/js-crypto-rsa
• x509: https://github.com/junkurihara/jscu/tree/develop/packages/js-x509-utils
• aes: https://github.com/junkurihara/jscu/tree/develop/packages/js-crypto-aes
• random: https://github.com/junkurihara/jscu/tree/develop/packages/js-crypto-random
• hash: https://github.com/junkurihara/jscu/tree/develop/packages/js-crypto-hash
• hkdf: https://github.com/junkurihara/jscu/tree/develop/packages/js-crypto-hkdf
• pbkdf: https://github.com/junkurihara/jscu/tree/develop/packages/js-crypto-pbkdf
• hmac: https://github.com/junkurihara/jscu/tree/develop/packages/js-crypto-hmac

Please refer to the above repos for further information.

NOTE: If you would use only few modules and employ neither Key nor pkc, we highly recommend use our independent modules since those independent ones are relatively small and this library would be overkill.

Installation

At your project directory, do either one of the following.

• From npm/yarn:

  1$ npm install --save js-crypto-utils // npm
  2$ yarn add js-crypto-utils // yarn

• From GitHub:

  1$ git clone https://github.com/junkurihara/jscu.git
  2$ cd js-crypto-utils/packages/js-crypto-utils
  3& yarn build

Then you should import the package as follows.

1import jscu from 'js-crypto-utils'; // for npm
2import jscu from 'path/to/js-crypto-utils/dist/index.js'; // for github

The bundled file is also given as js-crypto-utils/dist/jscu.bundle.js for a use case where the module is imported as a window.jscu object via script tags.

Usage

NOTE: This library always uses jscu.Key objects as instances of public and private keys, and the Key object can be instantiated from and can export ones in various formats. For the detailed usage of Key object, please refer to another GitHub repo.

Key generation, sign and verify

1// case of ECDSA
2jscu.pkc.generateKey(  // key generation
3  'EC', // ECDSA or ECDH key pair
4  {namedCurve: 'P-256'} // or 'P-384', 'P-521', 'P-256K'
5)
6.then( async (keyPair) => { // get a key pair in jscu.Key object
7  const msg = new Uint8Array(32);
8  for(let i = 0; i < 32; i++) msg[i] = 0xFF & i;
9
10  const sig = await jscu.pkc.sign(msg, keyPair.privateKey, 'SHA-256'); // uint8array
11  const result = await jscu.pkc.verify(msg, sig, keyPair.publicKey, 'SHA-256'); // true or false
12});

1// case of RSA
2jscu.pkc.generateKey(  // key generation
3  'RSA', // RSA key pair
4  {modulusLength: 2048}
5)
6.then( async (keyPair) => { // get a key pair in jscu.Key object
7  const msg = new Uint8Array(32);
8  for(let i = 0; i < 32; i++) msg[i] = 0xFF & i;
9
10  // case of RSA-PSS
11  // RSASSA-PKCS1-v1_5 is supported as well. see test files.
12  const sig = await jscu.pkc.sign(msg, keyPair.privateKey, 'SHA-256', {name: 'RSA-PSS', saltLength: 32}); // uint8array
13  const result = await jscu.pkc.verify(msg, sig, keyPair.publicKey, 'SHA-256', {name: 'RSA-PSS', saltLength: 32}); // true or false
14});

Encryption and decryption through ECDH with AES-GCM of 256 bits key and SHA-256 based HKDF

1const msg = new Uint8Array(32);
2for(let i = 0; i < 32; i++) msg[i] = 0xFF & i;
3
4const remotePublicKey = {...}; // destination's publicKey in jscu.Key object
5const remotePrivateKey = {...}; // destination's privateKey in jscu.Key object
6
7jscu.pkc.generateKey(  // key generation
8  'EC', // ECDSA or ECDH key pair
9  {namedCurve: 'P-256'} // or 'P-384', 'P-521', 'P-256K'
10).then( async (keyPair) => { // get a key pair in jscu.Key object
11  ////////////////////////////
12  // encryption at my side
13  ////////////////////////////
14  const optionsEncryption = {
15    privateKey: keyPair.privateKey, // for ECDH, my private key
16    hash: 'SHA-256', // for HKDF
17    encrypt: 'AES-GCM', // for encryption of message, if message is a key, 'AES-KW' can be used as well.
18    keyLength: 32, // key length of AES
19    info: '' // for HKDF
20  };
21  const encrypted = await jscu.pkc.encrypt(msg, remotePublicKey, optionsEncryption);
22  // now you get the encrypted message
23
24  ////////////////////////////
25  // decryption at remote side
26  ////////////////////////////
27  const optionsDecryption = {
28    publicKey: keyPair.publicKey, // for ECDH, my public key
29    hash: 'SHA-256', // for HKDF
30    encrypt: 'AES-GCM', // for encryption of message. 'AES-KW' can be used as well
31    keyLength: 32, // key length of AES
32    info: '', // for HKDF
33    salt: encrypted.salt, // for HKDF
34    iv: encrypted.iv // for AES
35  };
36  const decrypted = await jscu.pkc.decrypt(encrypted.data, remotePrivateKey, optionsDecryption);
37  // now you get decrypted message
38});

Note that AES and HKDF are independently available from jscu.aes and jscu.hkdf as well as random and hash. Also note that the HKDF employed in this library is the one specified in RFC5869 (https://tools.ietf.org/html/rfc5869).

RSA-OAEP encryption and decryption

1const msg = new Uint8Array(32);
2for(let i = 0; i < 32; i++) msg[i] = 0xFF & i;
3
4const publicKey = {...}; // publicKey in jscu.Key object
5const privateKey = {...}; // privateKey in jscu.Key object
6
7jscu.pkc.encrypt(
8  msg,
9  publicKey,
10  {hash: 'SHA-256'} // for OAEP
11).then( (encrypted) => {
12 // now you get the encrypted message
13 return jscu.pkc.decrypt(
14   encrypted,
15   privateKey,
16   {hash: 'SHA-256'}); // for OAEP
17}).then( (decrypted) => {
18  // now you get the decrypted message
19})

Converting between Json Web Key (JWK) and SPKI-formatted (public key) or PKCS8-formatted (private key) PEM/DER

We shall explain the conversion using an example of elliptic curve cryptography keys. First let an elliptic curve crypto public key is given in the form of JWK (RFC7517) as follows:

1const publicJwk = {kty: 'EC', crv: 'P-256', x: '...', y: '...'};

Given JWKs can be converted to the PEM/DER formatted keys in the following procedure.

1const publicKeyObject = new jscu.Key('jwk', publicJwk);
2const publicAsn = await publicKeyObject.export(
3  'pem', // output format is in string PEM, 'der' is also available
4  {
5    compact: false // if true, compressed form of keys are obtained
6  });

This library also re-convert keys in PEM/DER to JWK as follows.

1const publicKeyObjectR = new jscu.Key('pem', publicASN);
2const publicJwkR = publicKeyObjectR.export('jwk');

Note that JWK/DER/PEM-formatted RSA keys can be handled in the similar manner to the above.

Generation of self-signed X.509 certificate from JWK-formatted public key

1const publicJwk = {kty: 'EC', crv: 'P-256', x: '...', y: '...'}; // public key to be signed
2const privateJwk = {ktyp: 'EC', crv: 'P-256', x: '...', y: '...', d: '...'}; // private key
3
4const name = { // this is optional
5      countryName: 'JP',
6      stateOrProvinceName: 'Tokyo',
7      localityName: 'Chiyoda',
8      organizationName: 'example',
9      organizationalUnitName: 'Research',
10      commonName: 'example.com'
11    };
12
13// generation from JWK
14jscu.keyUtil.x509.fromJwk(
15  publicJwk,
16  privateJwk,
17  'pem',
18  {
19    signature: 'ecdsa-with-sha256', // signature algorithm
20    days: 365, // expired in days
21    issuer: name, // issuer
22    subject: name // assume that issuer = subject, i.e., self-signed certificate
23  },
24  'pem' // output signature is in PEM. DER-encoded signature is available with 'der'.
25).then( (cert) => {
26  // now you get the certificate in PEM string
27});

For signature, rsassaPss (RSA-PSS) and sha*WithRSAEncryption (RSASSA-PKCS1-v1_5) are available as well. When rsassaPss is specified, saltLength and hash are required as its params.

Extract JWK from X.509 certificate

1const crtsample = '-----BEGIN CERTIFICATE-----...';
2const jwkey = jscu.keyUtil.x509.toJwk(crtsample, 'pem');
3// now you get JWK public key from PEM-formatted certificate

Notes

One of the listed APIs/libraries is automatically chosen and leveraged for each implemented function, and unified interfaces are provided for browsers and Node.js.

• ECDSA and ECDH:

  • WebCrypto API for browsers
  • NodeCrypto for Node.js
  • elliptic for browsers

• RSA-PSS, RSASSA-PKCS1-v1_5, RSA-OAEP (RSA-PSSS does not work in Edge)

  • WebCrypto API for browsers
  • NodeCrypto for Node.js

• Key format conversion:

  • WebCrypto API for browsers
  • asn1.js for browsers and Node.js

• X.509 generation from JWK, and extraction of JWK from X.509

  • WebCrypto API for browsers
  • NodeCrypto for Node.js
  • elliptic for browsers

• AES: (may not work in IE)

  • WebCrypto API for browsers
  • NodeCrypto for Node.js

• Random, hash, HKDF, HMAC, JWK Thumbprint

  • WebCrypto API for browsers
  • NodeCrypto for Node.js

  IE is completely out of our scope now.

  Especially for Hash functions, we shall use the following pure JS implementation for some browsers (WebCrypto does not support SHA-3 yet). SHA-1 doesn't work in Edge. I believe Edge should be discarded ASAP.

  • sha3 for SHA3-224, SHA3-256, SHA3-384 and SHA3-512 for browsers
  • hash.js for SHA-1, SHA-256, SHA-384, SHA-512 for some legacy browsers
  • md5 for MD5 for some legacy browsers

License

Licensed under the MIT license, see LICENSE file.