# Crypto
- Stability: 2 - Unstable; API changes are being discussed for
- future versions. Breaking changes will be minimized. See below.
+ Stability: 2 - Stable
Use `require('crypto')` to access this module.
Load and set engine for some/all OpenSSL functions (selected by flags).
-`engine` could be either an id or a path to the to the engine's shared library.
+`engine` could be either an id or a path to the engine's shared library.
`flags` is optional and has `ENGINE_METHOD_ALL` value by default. It could take
one of or mix of following flags (defined in `constants` module):
Example:
var ciphers = crypto.getCiphers();
- console.log(ciphers); // ['AES-128-CBC', 'AES-128-CBC-HMAC-SHA1', ...]
+ console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
## crypto.getHashes()
console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
+## crypto.getCurves()
+
+Returns an array with the names of the supported elliptic curves.
+
+Example:
+
+ var curves = crypto.getCurves();
+ console.log(curves); // ['secp256k1', 'secp384r1', ...]
+
+
## crypto.createCredentials(details)
- Stability: 0 - Deprecated. Use [tls.createSecureContext][] instead.
+ Stability: 0 - Deprecated: Use [tls.createSecureContext][] instead.
Creates a credentials object, with the optional details being a
dictionary with keys:
<http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>
for details on the format.
-If no 'ca' details are given, then node.js will use the default
+If no 'ca' details are given, then Node.js will use the default
publicly trusted list of CAs as given in
<http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
Updates the hash content with the given `data`, the encoding of which
is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
-`'binary'`. If no encoding is provided and the input is a string an
+`'binary'`. If no encoding is provided, and the input is a string, an
encoding of `'binary'` is enforced. If `data` is a `Buffer` then
`input_encoding` is ignored.
You can disable auto padding if the data has been encrypted without
standard block padding to prevent `decipher.final` from checking and
-removing it. Can only work if the input data's length is a multiple of
+removing it. This will only work if the input data's length is a multiple of
the ciphers block size. You must call this before streaming data to
`decipher.update`.
## crypto.createECDH(curve_name)
-Creates a Elliptic Curve (EC) Diffie-Hellman key exchange object using a
-predefined curve specified by `curve_name` string.
+Creates an Elliptic Curve (EC) Diffie-Hellman key exchange object using a
+predefined curve specified by the `curve_name` string. Use [getCurves()][] to
+obtain a list of available curve names. On recent releases,
+`openssl ecparam -list_curves` will also display the name and description of
+each available elliptic curve.
## Class: ECDH
## crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback)
Asynchronous PBKDF2 function. Applies the selected HMAC digest function
-(default: SHA1) to derive a key of the requested length from the password,
+(default: SHA1) to derive a key of the requested byte length from the password,
salt and number of iterations. The callback gets two arguments:
`(err, derivedKey)`.
Example:
- crypto.pbkdf2('secret', 'salt', 4096, 512, 'sha256', function(err, key) {
+ crypto.pbkdf2('secret', 'salt', 4096, 64, 'sha256', function(err, key) {
if (err)
throw err;
console.log(key.toString('hex')); // 'c5e478d...1469e50'
});
// sync
- try {
- var buf = crypto.randomBytes(256);
- console.log('Have %d bytes of random data: %s', buf.length, buf);
- } catch (ex) {
- // handle error
- // most likely, entropy sources are drained
- }
+ const buf = crypto.randomBytes(256);
+ console.log('Have %d bytes of random data: %s', buf.length, buf);
NOTE: This will block if there is insufficient entropy, although it should
normally never take longer than a few milliseconds. The only time when this
`public_key` can be an object or a string. If `public_key` is a string, it is
treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
+Since RSA public keys may be derived from private keys you may pass a private
+key to this method.
`public_key`:
* `key` : A string holding the PEM encoded private key
+* `passphrase` : An optional string of passphrase for the private key
* `padding` : An optional padding value, one of the following:
* `constants.RSA_NO_PADDING`
* `constants.RSA_PKCS1_PADDING`
NOTE: All paddings are defined in `constants` module.
+## crypto.publicDecrypt(public_key, buffer)
+
+See above for details. Has the same API as `crypto.publicEncrypt`. Default
+padding is `RSA_PKCS1_PADDING`.
+
## crypto.privateDecrypt(private_key, buffer)
Decrypts `buffer` with `private_key`.
NOTE: All paddings are defined in `constants` module.
+## crypto.privateEncrypt(private_key, buffer)
+
+See above for details. Has the same API as `crypto.privateDecrypt`.
+Default padding is `RSA_PKCS1_PADDING`.
+
## crypto.DEFAULT_ENCODING
The default encoding to use for functions that can take either strings
## Recent API Changes
-The Crypto module was added to Node before there was the concept of a
+The Crypto module was added to Node.js before there was the concept of a
unified Stream API, and before there were Buffer objects for handling
binary data.
As such, the streaming classes don't have the typical methods found on
-other Node classes, and many methods accepted and returned
+other Node.js classes, and many methods accepted and returned
Binary-encoded strings by default rather than Buffers. This was
changed to use Buffers by default instead.
[createCipher()]: #crypto_crypto_createcipher_algorithm_password
[createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv
-[crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_encoding
+[getCurves()]: #crypto_crypto_getcurves
+[crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_encoding
[tls.createSecureContext]: tls.html#tls_tls_createsecurecontext_details
[diffieHellman.setPublicKey()]: #crypto_diffiehellman_setpublickey_public_key_encoding
[RFC 2412]: http://www.rfc-editor.org/rfc/rfc2412.txt
[RFC 3526]: http://www.rfc-editor.org/rfc/rfc3526.txt
-[crypto.pbkdf2]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_callback
+[crypto.pbkdf2]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
[EVP_BytesToKey]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html