# 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.
the stream is ended, use the `read()` method to get the enciphered
contents. The legacy `update` and `final` methods are also supported.
+Note: `createCipher` derives keys with the OpenSSL function [EVP_BytesToKey][]
+with the digest algorithm set to MD5, one iteration, and no salt. The lack of
+salt allows dictionary attacks as the same password always creates the same key.
+The low iteration count and non-cryptographically secure hash algorithm allow
+passwords to be tested very rapidly.
+
+In line with OpenSSL's recommendation to use pbkdf2 instead of EVP_BytesToKey it
+is recommended you derive a key and iv yourself with [crypto.pbkdf2][] and to
+then use [createCipheriv()][] to create the cipher stream.
+
## crypto.createCipheriv(algorithm, key, iv)
Creates and returns a cipher object, with the given algorithm, key and
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: Will throw error or invoke callback with error, if there is not enough
-accumulated entropy to generate cryptographically strong data. In other words,
-`crypto.randomBytes` without callback will not block even if all entropy sources
-are drained.
-
-## crypto.pseudoRandomBytes(size[, callback])
-
-Generates *non*-cryptographically strong pseudo-random data. The data
-returned will be unique if it is sufficiently long, but is not
-necessarily unpredictable. For this reason, the output of this
-function should never be used where unpredictability is important,
-such as in the generation of encryption keys.
-
-Usage is otherwise identical to `crypto.randomBytes`.
+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
+may conceivably block is right after boot, when the whole system is still
+low on entropy.
## Class: Certificate
`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_digest_callback
+[EVP_BytesToKey]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html
projects / platform / upstream / nodejs.git / blobdiff