crypto2
crypto2 is a convenience wrapper around Node.js' crypto module.
Installation
$ npm install crypto2
Quick start
First you need to integrate crypto2 with your application. For that add a reference to the crypto2
module.
const crypto2 = require('crypto2');
Creating passwords
For encrypting and decrypting you will need a password. To create a secure password, run the createPassword
function and hand over a secret key:
const password = await crypto2.createPassword('secret');
By default, createPassword
returns passwords with 32 bytes length. If you have to use passwords of a different length, provide the number of bytes you want the password to have:
const password = await crypto2.createPassword('secret', 64);
Please note that running createPassword
twice with the same key results in two different passwords, so you must store the generated password. It can not be recovered if you lost it, even if you know the original key.
Creating and managing keys
For signing and verifying as well as for encrypting and decrypting using asymmetric encryption algorithms you will need a PEM encoded private and public key pair. You can use the openssl
command-line tool to create both of them:
$ openssl genrsa -out privateKey.pem 2048
$ openssl rsa -in privateKey.pem -pubout > publicKey.pem
Alternatively the key pair may be created programmatically by calling the createKeyPair
function. This function creates a 2048-bit strong RSA key pair in PEM format:
const { privateKey, publicKey } = await crypto2.createKeyPair();
To load a private key from a .pem
file call the readPrivateKey
function and specify the name of the key file:
const privateKey = await crypto2.readPrivateKey('key.pem');
To load a public key from a .pub
file call the readPublicKey
function and specify the name of the key file:
const publicKey = await crypto2.readPublicKey('key.pub');
Symmetrically encrypting and decrypting
If you want crypto2 to select an encryption algorithm for you, call the encrypt
and decrypt
functions without any specific algorithm. This defaults to the AES 256 CBC encryption algorithm. Please note that you must provide an initialization vector (iv). To create one, use the createIv
function:
const password = await crypto2.createPassword('secret');
const iv = await crypto2.createIv();
const encrypted = await crypto2.encrypt('the native web', password, iv);
const decrypted = await crypto2.decrypt(encrypted, password, iv);
To encrypt and decrypt using the AES 256 CBC encryption algorithm call the encrypt.aes256cbc
and decrypt.aes256cbc
functions:
const password = await crypto2.createPassword('secret');
const iv = await crypto2.createIv();
const encrypted = await crypto2.encrypt.aes256cbc('the native web', password, iv);
const decrypted = await crypto2.decrypt.aes256cbc(encrypted, password, iv);
Asymmetrically encrypting and decrypting
To encrypt and decrypt using the asymmetric RSA encryption algorithm call the encrypt.rsa
and decrypt.rsa
functions. Due to technical limitations of the RSA algorithm the text to be encrypted must not be longer than 215 bytes when using keys with 2048 bits:
const encrypted = await crypto2.encrypt.rsa('the native web', publicKey);
const decrypted = await crypto2.decrypt.rsa(encrypted, privateKey);
Signing and verifying
If you want crypto2 to select a signing algorithm for you, call the sign
and verify
functions without any specific algorithm. This defaults to the SHA256 signing algorithm:
const signature = await crypto2.sign('the native web', privateKey);
const isSignatureValid = await crypto2.verify('the native web', publicKey, signature);
To sign and verify using the SHA256 signing algorithm call the sign.sha256
and verify.sha256
functions:
const signature = await crypto2.sign.sha256('the native web', privateKey);
const isSignatureValid = await crypto2.verify.sha256('the native web', publicKey, signature);
Hashing
If you want crypto2 to select a hash algorithm for you, call the hash
function without any specific algorithm. This defaults to the SHA256 hash algorithm:
const hash = await crypto2.hash('the native web');
To calculate the MD5 hash value of a string call the hash.md5
function:
const hash = await crypto2.hash.md5('the native web');
To calculate the SHA1 hash value of a string call the hash.sha1
function:
const hash = await crypto2.hash.sha1('the native web');
To calculate the SHA256 hash value of a string call the hash.sha256
function:
const hash = await crypto2.hash.sha256('the native web');
Message authentication
If you want crypto2 to select a HMAC algorithm for you, call the hmac
function without any specific algorithm. This defaults to the SHA256 hash algorithm:
const hmac = await crypto2.hmac('the native web', 'secret');
To calculate the SHA1-based HMAC value of a string call the hmac.sha1
function:
const hmac = await crypto2.hmac.sha1('the native web', 'secret');
To calculate the SHA256-based HMAC value of a string call the hmac.sha256
function:
const hmac = await crypto2.hmac.sha256('the native web', 'secret');
Running the build
To build this module use roboter.
$ npx roboter
License
The MIT License (MIT)
Copyright (c) 2013-2018 the native web.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.