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.
Then you should import the package as follows.
import keyutil from 'js-crypto-key-utils'; // for npm
import 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.
const yourStringPemKey = '------BEGIN PRIVATE...';
const yourBinaryDerKey = new Uint8Array([...]);
const yourJasonWebKey = {kty: 'EC', ... };
const yourOctetFormKey = new Uint8Array([0x04, ...])
const keyObjFromPem = new keyutil.Key('pem', yourStringPemKey);
const keyObjFromDer = new keyutil.Key('der', yourBinaryDerKey);
const keyObjFromJwk = new keyutil.Key('jwk', yourJasonWebKey);
const keyObjFromOct = new keyutil.Key('oct', yourOctetFormKey, {namedCurve: '...'});
Handling key objects
In a case where the imported key is encrypted (pem/der), it needs to be decrypted before getting exported.
const keyObj = new keyutil.Key('pem', encryptedPemKey);
const yourPassphrase = '...';
const isEncrypted = keyObj.isEncrypted;
if(isEncrypted) await keyObj.decrypt(yourPassphrase);
const thisMustBeFalse = keyObj.isEncrypted;
if(!thisMustBeFalse) await keyObj.encrypt(yourPassphrase);
const thisMustBeTrue = keyObj.isEncrypted;
Exporting keys in desired format
From instantiated key objects, various types of keys can be exported.
const keyObj = new keyutil.Key('pem', pemKey);
let jwk;
if(!keyObj.isEncrypted) jwk = await keyObj.export('jwk');
if(keyObj.isPrivate) jwk = await keyObj.export('jwk', {outputPublic: true});
let pem;
if(!keyObj.isEncrypted) pem = await keyObj.export('pem');
if(keyObj.isPrivate) pem = await keyObj.export('pem', {outputPublic: true});
pem = await keyObj.export('pem', {outputPublic: true, compact: true});
let der;
if(!keyObj.isEncrypted) der = await keyObj.export('der');
if(keyObj.isPrivate) der = await keyObj.export('der', {outputPublic: true});
der = await keyObj.export('der', {outputPublic: true, compact: true});
let oct;
if(!keyObj.isEncrypted) oct = await keyObj.export('oct');
if(keyObj.isPrivate) oct = await keyObj.export('oct', {outputPublic: true});
oct = 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.
const keyObj = new keyutil.Key('pem', pemKey);
let encryptedPem;
if(!keyObj.isEncrypted && keyObj.isPrivate)
encryptedPem = await keyObj.export('pem', {encryptParams: {passphrase: 'top secret'}});
if(!keyObj.isEncrypted && keyObj.isPrivate)
encryptedPem = await keyObj.export('pem', {
encryptParams: {
passphrase: 'top secret',
algorithm: 'pbes2',
cipher: 'aes256-cbc',
prf: 'hmacWithSHA256'
}
});
Getting JWK Thumbprint
You can obtain the JWK Thumbprint defined in RFC7638 from instantiated key object. The API can be invoked as follows.
const keyObj = new keyutil.Key('pem', pemKey);
let thumbprint;
if(!keyObj.isEncrypted) thumbprint = await keyObj.getJwkThumbprint();
if(!keyObj.isEncrypted) thumbprint = await keyObj.getJwkThumbprint(
'SHA-512',
'hex'
);
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.