Node.js v7.10.1 Documentation

Table of Contents

Crypto#

Stability: 2 - Stable

The crypto module provides cryptographic functionality that includes a set of wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign and verify functions.

Use require('crypto') to access this module.

const crypto = require('crypto');

const secret = 'abcdefg';
const hash = crypto.createHmac('sha256', secret)
                   .update('I love cupcakes')
                   .digest('hex');
console.log(hash);
// Prints:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e

Determining if crypto support is unavailable#

It is possible for Node.js to be built without including support for the crypto module. In such cases, calling require('crypto') will result in an error being thrown.

let crypto;
try {
  crypto = require('crypto');
} catch (err) {
  console.log('crypto support is disabled!');
}

Class: Certificate#

Added in: v0.11.8

SPKAC is a Certificate Signing Request mechanism originally implemented by Netscape and now specified formally as part of HTML5's keygen element.

The crypto module provides the Certificate class for working with SPKAC data. The most common usage is handling output generated by the HTML5 <keygen> element. Node.js uses OpenSSL's SPKAC implementation internally.

new crypto.Certificate()#

Instances of the Certificate class can be created using the new keyword or by calling crypto.Certificate() as a function:

const crypto = require('crypto');

const cert1 = new crypto.Certificate();
const cert2 = crypto.Certificate();

certificate.exportChallenge(spkac)#

Added in: v0.11.8

The spkac data structure includes a public key and a challenge. The certificate.exportChallenge() returns the challenge component in the form of a Node.js Buffer. The spkac argument can be either a string or a Buffer.

const cert = require('crypto').Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string

certificate.exportPublicKey(spkac)#

Added in: v0.11.8

The spkac data structure includes a public key and a challenge. The certificate.exportPublicKey() returns the public key component in the form of a Node.js Buffer. The spkac argument can be either a string or a Buffer.

const cert = require('crypto').Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>

certificate.verifySpkac(spkac)#

Added in: v0.11.8

Returns true if the given spkac data structure is valid, false otherwise. The spkac argument must be a Node.js Buffer.

const cert = require('crypto').Certificate();
const spkac = getSpkacSomehow();
console.log(cert.verifySpkac(Buffer.from(spkac)));
// Prints: true or false

Class: Cipher#

Added in: v0.1.94

Instances of the Cipher class are used to encrypt data. The class can be used in one of two ways:

  • As a stream that is both readable and writable, where plain unencrypted data is written to produce encrypted data on the readable side, or
  • Using the cipher.update() and cipher.final() methods to produce the encrypted data.

The crypto.createCipher() or crypto.createCipheriv() methods are used to create Cipher instances. Cipher objects are not to be created directly using the new keyword.

Example: Using Cipher objects as streams:

const crypto = require('crypto');
const cipher = crypto.createCipher('aes192', 'a password');

let encrypted = '';
cipher.on('readable', () => {
  const data = cipher.read();
  if (data)
    encrypted += data.toString('hex');
});
cipher.on('end', () => {
  console.log(encrypted);
  // Prints: ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504
});

cipher.write('some clear text data');
cipher.end();

Example: Using Cipher and piped streams:

const crypto = require('crypto');
const fs = require('fs');
const cipher = crypto.createCipher('aes192', 'a password');

const input = fs.createReadStream('test.js');
const output = fs.createWriteStream('test.enc');

input.pipe(cipher).pipe(output);

Example: Using the cipher.update() and cipher.final() methods:

const crypto = require('crypto');
const cipher = crypto.createCipher('aes192', 'a password');

let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
encrypted += cipher.final('hex');
console.log(encrypted);
// Prints: ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504

cipher.final([output_encoding])#

Added in: v0.1.94

Returns any remaining enciphered contents. If output_encoding parameter is one of 'latin1', 'base64' or 'hex', a string is returned. If an output_encoding is not provided, a Buffer is returned.

Once the cipher.final() method has been called, the Cipher object can no longer be used to encrypt data. Attempts to call cipher.final() more than once will result in an error being thrown.

cipher.setAAD(buffer)#

Added in: v1.0.0

When using an authenticated encryption mode (only GCM is currently supported), the cipher.setAAD() method sets the value used for the additional authenticated data (AAD) input parameter.