Universal Module for Cryptographic Key Utilities in JavaScript

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.

Introduction and Overview

This library is designed to 'universally' provide several functions for a cryptographic key handling, which means it works both on most browsers and on Node.js just by importing from npm/source code. This key utility library provides converters for EC/RSA keys in PEM/DER<->JWK, octet form of EC keys <-> JWK, and computation of JWK thumbprints. Especially for the conversion PEM/DER <->JWK, encryption and decryption of private key in DER/PEM are supported.

Installation

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

• From npm/yarn:

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

• From GitHub:

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

Then you should import the package as follows.

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

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

Usage

Supported key types are Json Web Key (JWK, RFC7517), and PEM/DER. Octet-Formatted Key (SECG SEC1 2.3.3 and 2.3.4, link to PDF) is also available for elliptic curve cryptography keys. Note that for PEM/DER, public keys are encoded to the form of SubjectPublicKeyInfo (SPKI) defined as a part of X.509 public key certificate (RFC5280). The detailed encoding rule for elliptic curve cryptographic keys is given in RFC5480. On the other hand, private keys are encoded to hte form of PrivateKeyInfo defined in PKCS#8 (RFC5958). The detailed encoding rule for elliptic curve cryptographic keys is given in RFC5915 as well as SPKI. Please refer to RFC3447 for the detailed encoding rule of RSA public and private keys.

Instantiation

At first, you need to instantiate Key object by importing various type of keys.

1const yourStringPemKey = '------BEGIN PRIVATE...'; // SPKI (public key) or PKCS8 (either encrypted or plaintext private key)
2const yourBinaryDerKey = new Uint8Array([...]); // SPKI (public key) or PKCS8 (either encrypted or plaintext private key)
3const yourJasonWebKey = {kty: 'EC', ... };
4const yourOctetFormKey = new Uint8Array([0x04, ...]) // only for Elliptic Curve Crypto Key.
5
6const keyObjFromPem = new keyutil.Key('pem', yourStringPemKey);
7const keyObjFromDer = new keyutil.Key('der', yourBinaryDerKey);
8const keyObjFromJwk = new keyutil.Key('jwk', yourJasonWebKey);
9const keyObjFromOct = new keyutil.Key('oct', yourOctetFormKey, {namedCurve: '...'}); //namedCurve like 'P-256K' is required.

Handling key objects

In a case where the imported key is encrypted (pem/der), it needs to be decrypted before getting exported.

1const keyObj = new keyutil.Key('pem', encryptedPemKey);
2const yourPassphrase = '...';
3
4// first now you can check the status
5const isEncrypted = keyObj.isEncrypted;
6
7// before using the key object, decrypt the key object with the passphrase.
8if(isEncrypted) await keyObj.decrypt(yourPassphrase);
9
10const thisMustBeFalse = keyObj.isEncrypted; // false
11
12// you can lock the key object by encrypting it as well.
13if(!thisMustBeFalse) await keyObj.encrypt(yourPassphrase);
14
15const thisMustBeTrue = keyObj.isEncrypted; // true;

Exporting keys in desired format

From instantiated key objects, various types of keys can be exported.

1const keyObj = new keyutil.Key('pem', pemKey);
2
3// jwk
4let jwk;
5if(!keyObj.isEncrypted) jwk = await keyObj.export('jwk');
6if(keyObj.isPrivate) jwk = await keyObj.export('jwk', {outputPublic: true}); // export public key from private key.
7
8// pem
9let pem;
10if(!keyObj.isEncrypted) pem = await keyObj.export('pem');
11if(keyObj.isPrivate) pem = await keyObj.export('pem', {outputPublic: true}); // export public key from private key.
12// Only ECC Key: export compressed form of public key from private/public key.
13pem = await keyObj.export('pem', {outputPublic: true, compact: true});
14
15// der
16let der;
17if(!keyObj.isEncrypted) der = await keyObj.export('der');
18if(keyObj.isPrivate) der = await keyObj.export('der', {outputPublic: true}); // export public key from private key.
19// Only ECC Keys: export compressed form of public key from private/public key.
20der = await keyObj.export('der', {outputPublic: true, compact: true});
21
22// Only ECC Keys
23// octet from
24let oct;
25if(!keyObj.isEncrypted) oct = await keyObj.export('oct');
26if(keyObj.isPrivate) oct = await keyObj.export('oct', {outputPublic: true}); // export public key from private key.
27// export compressed form of public key from private/public key.
28oct = await keyObj.export('oct', {outputPublic: true, compact: true});

Exporting encrypted keys with arbitrary specified passphrase.

All you need to export encrypted private keys in PEM/DER is just putting passphrase in the API. The default encryption algorithm follows PKCS#5 v2.1 (RFC8018) and uses AES256-CBC and HMAC-with-SHA-256 to encrypt your private key.

1const keyObj = new keyutil.Key('pem', pemKey);
2
3// encrypt with default params
4let encryptedPem;
5if(!keyObj.isEncrypted && keyObj.isPrivate)
6  encryptedPem = await keyObj.export('pem', {encryptParams: {passphrase: 'top secret'}});
7
8// encrypt with intended params
9if(!keyObj.isEncrypted && keyObj.isPrivate)
10  encryptedPem = await keyObj.export('pem', {
11    encryptParams: {
12      passphrase: 'top secret',
13      algorithm: 'pbes2', // default. 'pbeWith...' is also available, i.e., pbes1.
14      cipher: 'aes256-cbc', // default. for encryption. 'aes128-cbc', 'aes192-cbc'(only node), 'des-ede3-cbc' are available as well.
15      prf: 'hmacWithSHA256' // default. for key derivation
16    }
17  });

Getting JWK Thumbprint

You can obtain the JWK Thumbprint defined in RFC7638 from instantiated key object. The API can be invoked as follows.

1const keyObj = new keyutil.Key('pem', pemKey);
2
3let thumbprint;
4
5// with default params (hash is SHA-256, output is in Uint8Array)
6if(!keyObj.isEncrypted) thumbprint = await keyObj.getJwkThumbprint();
7
8// with intented params
9if(!keyObj.isEncrypted) thumbprint = await keyObj.getJwkThumbprint(
10  'SHA-512',
11  'hex' // output is hex string
12);

Note that the thumbprint generated from a public key is exactly same as that from its paired private key.

Note

Now this library supports the following curve for elliptic curve cryptography.

• P-256 (secp256r1)
• P-384 (secp384r1)
• P-521 (secp521r1)
• P-256K (secp256k1)

License

Licensed under the MIT license, see LICENSE file.