crypto-key-composer
Advanced tools
A library to decompose and compose crypto keys of different types and formats
A library to decompose and compose crypto keys of different types and formats.
$ npm install crypto-key-composer
This library is written in modern JavaScript and is published in both CommonJS and ES module transpiled variants. If you target older browsers please make sure to transpile accordingly. Moreover, some of this library's dependencies use the native Node Buffer module. This means that you must compile your app through a bundler that automatically injects a Buffer compatible implementation for the browser, such as Webpack.
decomposePrivateKey(inputKey, [options])composePrivateKey(decomposedKey, [options])decomposePublicKey(inputKey, [options])composePublicKey(decomposedKey)getKeyTypeFromAlgorithm(keyAlgorithm)Parses a private key, extracting information containing its format, keyAlgorithm, keyData and encryptionAlgorithm.
import { decomposePrivateKey } from 'crypto-key-composer';
const myPrivatePemKey = `
-----BEGIN RSA PRIVATE KEY-----
ACTUAL KEY BASE64 HERE
-----END RSA PRIVATE KEY-----
`
const myPrivateDecomposedKey = decomposePrivateKey(myPrivatePemKey)
// {
// format: 'pkcs1-pem',
// keyAlgorithm: {
// id: 'rsa-encryption'
// },
// keyData: {
// modulus: Uint8Array(...),
// publicExponent: Uint8Array(...),
// privateExponent: Uint8Array(...),
// // ...
// },
// encryptionAlgorithm: null
// }
The inputKey may be a TypedArray (including Node's Buffer), an ArrayBuffer or a binary string.
⚠️ Do not use the
keyAlgorithm.idto identify the key type. The reason is that several identifiers map to the same key type. As an example,rsa-encryption,sha512-with-rsa-encryption,rsa-oaepandrsassa-pssare all RSA keys. Instead, usegetKeyTypeFromAlgorithmto properly get the key type.
Available options:
| name | type | default | description |
|---|---|---|---|
| format | string/Array | ['raw-pem', 'pkcs8-pem'] | Limit the parsing to one or more formats |
| password | string | The password to use to decrypt the key |
Meaningful errors with codes are thrown if something went wrong. When options.format is an array, this function will attempt to decompose the key for the specified formats, in order and one by one. It will succeed if the key is using one of the formats or fail if it's using another format, throwing an AggregatedError containing a errors property with the errors indexed by format.
Composes a private key from its parts: format, keyAlgorithm, keyData and encryptionAlgorithm. This function is the inverse of decomposePrivateKey.
import { composePrivateKey } from 'crypto-key-composer';
const myPrivatePemKey = composePrivateKey({
format: 'pkcs1-pem',
keyAlgorithm: {
id: 'rsa-encryption',
},
keyData: {
modulus: Uint8Array(...),
publicExponent: Uint8Array(...),
privateExponent: Uint8Array(...),
// ...
}
});
The return value depends on the format. PEM based formats return a regular string while DER based formats return a Uint8Array.
Available options:
| name | type | default | description |
|---|---|---|---|
| password | string | The password to use to encrypt the key |
Meaningful errors with codes are thrown if something went wrong.
Parses a public key, extracting information containing its format, keyAlgorithm and keyData.
import { decomposePublicKey } from 'crypto-key-composer';
const myPublicPemKey = `
-----BEGIN PUBLIC KEY-----
ACTUAL KEY BASE64 HERE
-----END PUBLIC KEY-----
`
const myDecomposedPublicKey = decomposePublicKey(myPublicPemKey)
// {
// format: 'spki-pem',
// keyAlgorithm: {
// id: 'rsa-encryption'
// },
// keyData: {
// modulus: Uint8Array(...),
// publicExponent: Uint8Array(...)
// },
// encryptionAlgorithm: null
// }
The inputKey may be a TypedArray (including Node's Buffer), an ArrayBuffer or a binary string.
⚠️ Do not use the
keyAlgorithm.idto identify the key type. The reason is that several identifiers map to the same key type. As an example,rsa-encryption,rsaes-oaepandrsassa-pssare all RSA keys. Instead, usegetKeyTypeFromAlgorithmto properly get the key type.
Available options:
| name | type | default | description |
|---|---|---|---|
| format | string/Array | ['raw-pem', 'spki-pem'] | Limit the parsing to one or more formats |
Meaningful errors with codes are thrown if something went wrong. When options.format is an array, this function will attempt to decompose the key for the specified formats, in order and one by one. It will succeed if the key is using one of the formats or fail if it's using another format, throwing an AggregatedError containing a errors property with the errors indexed by format.
Composes a public key from its parts: format, keyAlgorithm and keyData. This function is the inverse of decomposePublicKey.
import { composePublicKey } from 'crypto-key-composer';
const myPublicPemKey = composePublicKey({
format: 'spki-pem',
keyAlgorithm: {
id: 'rsa-encryption',
},
keyData: {
modulus: Uint8Array(...),
publicExponent: Uint8Array(...)
}
});
The return value depends on the format. PEM based formats return a regular string while DER based formats return a Uint8Array.
Meaningful errors with codes are thrown if something went wrong.
Returns the key type based on the passed key algorithm. The keyAlgorithm might be an object or a string.
import { getKeyTypeFromAlgorithm } from 'crypto-key-composer';
getKeyTypeFromAlgorithm({ id: 'rsa-encryption' }) // rsa
getKeyTypeFromAlgorithm('rsa-encryption') // rsa
getKeyTypeFromAlgorithm('ed25519') // ed25519
Below you will find the list of supported formats for private and public keys.
The raw-der is the DER encoded ASN1 format defined in RFC 8017 for RSA keys and in RFC5915 for EC keys.
Supported public key algorithms:
rsa-encryption RSA algorithm (or the rsa alias)Supported private key algorithms:
rsa-encryption RSA algorithm (or the rsa alias)ec-public-key EC algorithm (or the ec alias)Supported encryption algorithms: none
⚠️ It's recommended to use the newer PKCS8 & SPKI formats for private and public keys respectively because they are able to store more types of keys. Moreover, PKCS8 keys may be encrypted.
The raw-pem is the PEM encoded version of raw-der and is defined in RFC 1421.
Supported public key algorithms:
rsa-encryption RSA algorithm (or the rsa alias)Supported private key algorithms:
rsa-encryption RSA algorithm (or the rsa alias)ec-public-key RSA algorithm (or the ec alias)Supported encryption algorithms:
openssl-derive-bytes (default)aes256-cbc (default), aes192-cbc, aes128-cbc, des-ede3-cbc, des-cbc, rc2-cbc⚠️ It's recommended to use the newer PKCS8 & SPKI formats for private and public keys respectively because they are able to store more types of keys. Moreover, PKCS8 keys have stronger encryption.
The pkcs1-der is the DER encoded ASN1 format defined in RFC 8017. It's a subset of the raw-der format, supporting only RSA keys.
Supported private key algorithms:
rsa-encryption RSA algorithm (or the rsa alias)Supported encryption algorithms: none
⚠️ It's recommended to use the newer PKCS8 format for private keys because it's able to store more types of keys and support encryption.
The pkcs1-pem is the PEM encoded version of pkcs1-der and is defined in RFC 1421. It's a subset of the raw-pem format, supporting only RSA keys.
Supported private key algorithms:
rsa-encryption RSA algorithm (or the rsa alias)Supported encryption algorithms:
openssl-derive-bytes (default)aes256-cbc (default), aes192-cbc, aes128-cbc, des-ede3-cbc, des-cbc, rc2-cbc⚠️ It's recommended to use the newer PKCS8 format for private keys because it's able to store more types of keys and support stronger encryption algorithms.
The pkcs8-der is the DER encoded ASN1 format defined in RFC 5208 and RFC 5985.
Supported private key algorithms:
Supported encryption algorithms (PKCS#5):
pbkdf2 (default)aes256-cbc (default), aes192-cbc, aes128-cbc, des-ede3-cbc, des-cbc, rc2-cbcThe pkcs8-pem is the PEM encoded version of pkcs8-der and is defined in RFC 1421.
Supported private key algorithms:
Supported encryption algorithms (PKCS#5):
pbkdf2 (default)aes256-cbc (default), aes192-cbc, aes128-cbc, des-ede3-cbc, des-cbc, rc2-cbcThe spki-der is a format to represent various types of public keys and is defined in RFC 5280.
Supported public key algorithms:
Supported encryption algorithms: does not apply
The spki-pem is the PEM encoded version of spki-der and is defined in RFC 1421.
Supported public key algorithms:
Supported encryption algorithms: does not apply
Below you will find the list of supported key algorithms. Because the actual supported key algorithms vary from format to format, be sure to also check the Formats section.
The following RSA key algorithms are supported:
rsa-encryptionmd2-with-rsa-encryptionmd4-with-rsa-encryptionmd5-with-rsa-encryptionsha1-with-rsa-encryptionsha224-with-rsa-encryptionsha256-with-rsa-encryptionsha384-with-rsa-encryptionsha512-with-rsa-encryptionsha512-224-with-rsa-encryptionsha512-256-with-rsa-encryption⚠️ At the moment,
rsaes-oaepandrsassa-pssare not yet supported (see issue #4).
All of them are expressed like so:
{
keyAlgorithm: {
id: 'rsa-encryption'
}
}
Because they have no parameters, the example above may also be expressed like so:
{
keyAlgorithm: 'rsa-encryption'
}
You may use the rsa alias in the key algorithm id, which maps to rsa-encryption.
The following EC (elliptic curve) algorithms are supported:
ec-public-keyec-dhec-mqvOnly named curves may be used. The following curves are supported:
sect163k1sect163r1sect239k1sect113r1sect113r2secp112r1secp112r2secp160r1secp160k1secp256k1sect163r2sect283k1sect283r1sect131r1sect131r2sect193r1sect193r2sect233k1sect233r1secp128r1secp128r2secp160r2secp192k1secp224k1secp224r1secp384r1secp521r1sect409k1sect409r1sect571k1sect571r1secp192r1secp256r1The combination of the key algorithm and the named curve are expressed like so:
{
keyAlgorithm: {
id: 'ec-public-key',
namedCurve: 'secp256k1',
}
}
You may use the ec alias in the key algorithm id, which maps to ec-public-key.
ED25519 keys just have a single algorithm, ed25519, and may be expressed like so:
{
keyAlgorithm: {
id: 'ed25519'
}
}
Because there are no parameters, the example above may also be expressed like so:
{
keyAlgorithm: 'ed25519'
}
The key data is the interpreted key contents. Below, you will find the key data structure for each key type.
{
keyData: {
modulus: Uint8Array(/* ... */),
publicExponent: Uint8Array(/* ... */),
privateExponent: Uint8Array(/* ... */),
prime1: Uint8Array(/* ... */),
prime2: Uint8Array(/* ... */),
exponent1: Uint8Array(/* ... */),
exponent2: Uint8Array(/* ... */),
coefficient: Uint8Array(/* ... */),
// Only defined if number of primes is greater than 2
otherPrimeInfos: [
{
prime: Uint8Array(/* ... */),
exponent: Uint8Array(/* ... */),
coefficient Uint8Array(/* ... */)
}
]
}
}
{
keyData: {
modulus: Uint8Array(/* ... */),
publicExponent: Uint8Array(/* ... */)
}
}
{
keyData: {
d: Uint8Array(/* ... */),
x: Uint8Array(/* ... */),
y: Uint8Array(/* ... */),
}
}
{
keyData: {
x: Uint8Array(/* ... */),
y: Uint8Array(/* ... */),
}
}
{
keyData: {
seed: Uint8Array( /* 32 bytes */)
}
}
The seed is composed of 32 bytes which serves as the basis to derive the 64 bytes private key and the 32 bytes public key. This closely follows what is defined in RFC 8032.
{
keyData: {
bytes: Uint8Array( /* 32 bytes */)
}
}
The encryption algorithm only apply for private keys and is composed by two parts: Key Derivation Function and the Encryption Scheme. Below you will find the supported algorithms for these parts. Because the actual supported encryption algorithms vary from format to format, be sure to also check the Formats section.
The openssl-derive-bytes is used when encrypting PKCS#1 PEM keys and was pionereed by OpenSSL to derive a key from the password.
{
encryptionAlgorithm: {
keyDerivationFunc: {
id: 'openssl-derive-bytes',
}
encryptionScheme: ...
}
}
Because there are no parameters, the example above may also be expressed like so:
{
encryptionAlgorithm: {
keyDerivationFunc: 'openssl-derive-bytes',
encryptionScheme: ...
}
}
The pbkdf2 is used when encrypting PKCS#8 keys and is part of PKCS#5 defined by RFC 8018.
{
encryptionAlgorithm: {
keyDerivationFunc: {
id: 'pbkdf2',
iterationCount: 10000, // The number of iterations
keyLength: 32, // Automatic, based on the `encryptionScheme`
prf: 'hmac-with-sha512' // The pseudo-random function
}
encryptionScheme: ...
}
}
The parameters above are the default ones and may be omited if you don't need to tweak them. In that case, you may express the example above like so:
{
encryptionAlgorithm: {
keyDerivationFunc: 'pbkdf2',
encryptionScheme: ...
}
}
The supported prf values are hmac-with-sha512 (default), hmac-with-sha384, hmac-with-sha256 and hmac-with-sha1.
The supported AES algorithms are aes256-cbc, aes192-cbc and aes128-cbc. Here's an example:
{
encryptionAlgorithm: {
keyDerivationFunc: ...,
encryptionScheme: {
id: 'aes256-cbc',
iv: Uint8Array(/* random bytes */)
}
}
}
The parameters may be omited if you don't need to tweak them. In that case, you may express the example above like so:
{
encryptionAlgorithm: {
keyDerivationFunc: ...,
encryptionScheme: 'aes256-cbc'
}
}
The supported DES algorithms are des-cbc and des-ede3-cbc (triple DES). Here's an example:
{
encryptionAlgorithm: {
keyDerivationFunc: ...,
encryptionScheme: {
id: 'des-ede3-cbc',
iv: Uint8Array(/* random bytes */)
}
}
}
The parameters may be omited if you don't need to tweak them. In that case, you may express the example above like so:
{
encryptionAlgorithm: {
keyDerivationFunc: ...,
encryptionScheme: 'aes256-cbc'
}
}
The supported RC2 algorithm is just rc2-cbc with 128 (default), 64 or 40 bits. Here's an example:
{
encryptionAlgorithm: {
keyDerivationFunc: ...,
encryptionScheme: {
id: 'rc2-cbc',
iv: Uint8Array(/* random bytes */),
bits: 128
}
}
}
The parameters may be omited if you don't need to tweak them. In that case, you may express the example above like so:
{
encryptionAlgorithm: {
keyDerivationFunc: ...,
encryptionScheme: 'rc2-cbc'
}
}
$ npm test
$ npm test -- --watch # during development
Released under the MIT License.
FAQs
A library to decompose and compose crypto keys of different types and formats
We found that crypto-key-composer demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 18 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.