It also offers a set of wrappers for OpenSSL's hash, hmac, cipher,
decipher, sign and verify methods.
+## Class: Certificate
-## crypto.setEngine(engine[, flags])
-
-Load and set engine for some/all OpenSSL functions (selected by flags).
-
-`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):
-
-* `ENGINE_METHOD_RSA`
-* `ENGINE_METHOD_DSA`
-* `ENGINE_METHOD_DH`
-* `ENGINE_METHOD_RAND`
-* `ENGINE_METHOD_ECDH`
-* `ENGINE_METHOD_ECDSA`
-* `ENGINE_METHOD_CIPHERS`
-* `ENGINE_METHOD_DIGESTS`
-* `ENGINE_METHOD_STORE`
-* `ENGINE_METHOD_PKEY_METH`
-* `ENGINE_METHOD_PKEY_ASN1_METH`
-* `ENGINE_METHOD_ALL`
-* `ENGINE_METHOD_NONE`
-
-
-## crypto.getCiphers()
+The class used for working with signed public key & challenges. The most
+common usage for this series of functions is when dealing with the `<keygen>`
+element. http://www.openssl.org/docs/apps/spkac.html
-Returns an array with the names of the supported ciphers.
+Returned by `crypto.Certificate`.
-Example:
+### Certificate.exportChallenge(spkac)
- var ciphers = crypto.getCiphers();
- console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
+Exports the encoded challenge associated with the SPKAC.
+### Certificate.exportPublicKey(spkac)
-## crypto.getHashes()
+Exports the encoded public key from the supplied SPKAC.
-Returns an array with the names of the supported hash algorithms.
+### Certificate.verifySpkac(spkac)
-Example:
+Returns true of false based on the validity of the SPKAC.
- var hashes = crypto.getHashes();
- console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
+## Class: Cipher
+Class for encrypting data.
-## crypto.getCurves()
+Returned by `crypto.createCipher` and `crypto.createCipheriv`.
-Returns an array with the names of the supported elliptic curves.
+Cipher objects are [streams](stream.html) that are both readable and
+writable. The written plain text data is used to produce the
+encrypted data on the readable side. The legacy `update` and `final`
+methods are also supported.
-Example:
+### cipher.final([output_encoding])
- var curves = crypto.getCurves();
- console.log(curves); // ['secp256k1', 'secp384r1', ...]
+Returns any remaining enciphered contents, with `output_encoding`
+being one of: `'binary'`, `'base64'` or `'hex'`. If no encoding is
+provided, then a buffer is returned.
+Note: `cipher` object can not be used after `final()` method has been
+called.
-## crypto.createCredentials(details)
+### cipher.getAuthTag()
- Stability: 0 - Deprecated: Use [tls.createSecureContext][] instead.
+For authenticated encryption modes (currently supported: GCM), this
+method returns a `Buffer` that represents the _authentication tag_ that
+has been computed from the given data. Should be called after
+encryption has been completed using the `final` method!
-Creates a credentials object, with the optional details being a
-dictionary with keys:
+### cipher.setAAD(buffer)
-* `pfx` : A string or buffer holding the PFX or PKCS12 encoded private
- key, certificate and CA certificates
-* `key` : A string holding the PEM encoded private key
-* `passphrase` : A string of passphrase for the private key or pfx
-* `cert` : A string holding the PEM encoded certificate
-* `ca` : Either a string or list of strings of PEM encoded CA
- certificates to trust.
-* `crl` : Either a string or list of strings of PEM encoded CRLs
- (Certificate Revocation List)
-* `ciphers`: A string describing the ciphers to use or exclude.
- Consult
- <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>
- for details on the format.
+For authenticated encryption modes (currently supported: GCM), this
+method sets the value used for the additional authenticated data (AAD) input
+parameter.
-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>.
+### cipher.setAutoPadding(auto_padding=true)
+You can disable automatic padding of the input data to block size. If
+`auto_padding` is false, the length of the entire input data must be a
+multiple of the cipher's block size or `final` will fail. Useful for
+non-standard padding, e.g. using `0x0` instead of PKCS padding. You
+must call this before `cipher.final`.
-## crypto.createHash(algorithm)
+### cipher.update(data[, input_encoding][, output_encoding])
-Creates and returns a hash object, a cryptographic hash with the given
-algorithm which can be used to generate hash digests.
+Updates the cipher with `data`, the encoding of which is given in
+`input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`. If no
+encoding is provided, then a buffer is expected.
+If `data` is a `Buffer` then `input_encoding` is ignored.
-`algorithm` is dependent on the available algorithms supported by the
-version of OpenSSL on the platform. Examples are `'sha256'`,
-`'sha512'`, etc. On recent releases, `openssl
-list-message-digest-algorithms` will display the available digest
-algorithms.
+The `output_encoding` specifies the output format of the enciphered
+data, and can be `'binary'`, `'base64'` or `'hex'`. If no encoding is
+provided, then a buffer is returned.
-Example: this program that takes the sha256 sum of a file
+Returns the enciphered contents, and can be called many times with new
+data as it is streamed.
- var filename = process.argv[2];
- var crypto = require('crypto');
- var fs = require('fs');
+## Class: Decipher
- var shasum = crypto.createHash('sha256');
+Class for decrypting data.
- var s = fs.ReadStream(filename);
- s.on('data', function(d) {
- shasum.update(d);
- });
+Returned by `crypto.createDecipher` and `crypto.createDecipheriv`.
- s.on('end', function() {
- var d = shasum.digest('hex');
- console.log(d + ' ' + filename);
- });
+Decipher objects are [streams](stream.html) that are both readable and
+writable. The written enciphered data is used to produce the
+plain-text data on the the readable side. The legacy `update` and
+`final` methods are also supported.
-## Class: Hash
+### decipher.final([output_encoding])
-The class for creating hash digests of data.
+Returns any remaining plaintext which is deciphered, with
+`output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`. If
+no encoding is provided, then a buffer is returned.
-It is a [stream](stream.html) that is both readable and writable. The
-written data is used to compute the hash. Once the writable side of
-the stream is ended, use the `read()` method to get the computed hash
-digest. The legacy `update` and `digest` methods are also supported.
+Note: `decipher` object can not be used after `final()` method has been
+called.
-Returned by `crypto.createHash`.
+### decipher.setAAD(buffer)
-### hash.update(data[, input_encoding])
+For authenticated encryption modes (currently supported: GCM), this
+method sets the value used for the additional authenticated data (AAD) input
+parameter.
-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
-encoding of `'binary'` is enforced. If `data` is a `Buffer` then
-`input_encoding` is ignored.
+### decipher.setAuthTag(buffer)
-This can be called many times with new data as it is streamed.
+For authenticated encryption modes (currently supported: GCM), this
+method must be used to pass in the received _authentication tag_.
+If no tag is provided or if the ciphertext has been tampered with,
+`final` will throw, thus indicating that the ciphertext should
+be discarded due to failed authentication.
-### hash.digest([encoding])
+### decipher.setAutoPadding(auto_padding=true)
-Calculates the digest of all of the passed data to be hashed. The
-`encoding` can be `'hex'`, `'binary'` or `'base64'`. If no encoding
-is provided, then a buffer is returned.
+You can disable auto padding if the data has been encrypted without
+standard block padding to prevent `decipher.final` from checking and
+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`.
-Note: `hash` object can not be used after `digest()` method has been
-called.
+### decipher.update(data[, input_encoding][, output_encoding])
+Updates the decipher with `data`, which is encoded in `'binary'`,
+`'base64'` or `'hex'`. If no encoding is provided, then a buffer is
+expected.
+If `data` is a `Buffer` then `input_encoding` is ignored.
-## crypto.createHmac(algorithm, key)
+The `output_decoding` specifies in what format to return the
+deciphered plaintext: `'binary'`, `'ascii'` or `'utf8'`. If no
+encoding is provided, then a buffer is returned.
-Creates and returns a hmac object, a cryptographic hmac with the given
-algorithm and key.
+## Class: DiffieHellman
-It is a [stream](stream.html) that is both readable and writable. The
-written data is used to compute the hmac. Once the writable side of
-the stream is ended, use the `read()` method to get the computed
-digest. The legacy `update` and `digest` methods are also supported.
+The class for creating Diffie-Hellman key exchanges.
-`algorithm` is dependent on the available algorithms supported by
-OpenSSL - see createHash above. `key` is the hmac key to be used.
+Returned by `crypto.createDiffieHellman`.
-## Class: Hmac
+### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding])
-Class for creating cryptographic hmac content.
+Computes the shared secret using `other_public_key` as the other
+party's public key and returns the computed shared secret. Supplied
+key is interpreted using specified `input_encoding`, and secret is
+encoded using specified `output_encoding`. Encodings can be
+`'binary'`, `'hex'`, or `'base64'`. If the input encoding is not
+provided, then a buffer is expected.
-Returned by `crypto.createHmac`.
+If no output encoding is given, then a buffer is returned.
-### hmac.update(data)
+### diffieHellman.generateKeys([encoding])
-Update the hmac content with the given `data`. This can be called
-many times with new data as it is streamed.
+Generates private and public Diffie-Hellman key values, and returns
+the public key in the specified encoding. This key should be
+transferred to the other party. Encoding can be `'binary'`, `'hex'`,
+or `'base64'`. If no encoding is provided, then a buffer is returned.
-### hmac.digest([encoding])
+### diffieHellman.getGenerator([encoding])
-Calculates the digest of all of the passed data to the hmac. The
-`encoding` can be `'hex'`, `'binary'` or `'base64'`. If no encoding
-is provided, then a buffer is returned.
+Returns the Diffie-Hellman generator in the specified encoding, which can
+be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
+then a buffer is returned.
-Note: `hmac` object can not be used after `digest()` method has been
-called.
+### diffieHellman.getPrime([encoding])
+Returns the Diffie-Hellman prime in the specified encoding, which can
+be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
+then a buffer is returned.
-## crypto.createCipher(algorithm, password)
+### diffieHellman.getPrivateKey([encoding])
-Creates and returns a cipher object, with the given algorithm and
-password.
+Returns the Diffie-Hellman private key in the specified encoding,
+which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is
+provided, then a buffer is returned.
-`algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
-recent releases, `openssl list-cipher-algorithms` will display the
-available cipher algorithms. `password` is used to derive key and IV,
-which must be a `'binary'` encoded string or a [buffer](buffer.html).
+### diffieHellman.getPublicKey([encoding])
-It is a [stream](stream.html) that is both readable and writable. The
-written data is used to compute the hash. Once the writable side of
-the stream is ended, use the `read()` method to get the enciphered
-contents. The legacy `update` and `final` methods are also supported.
+Returns the Diffie-Hellman public key in the specified encoding, which
+can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
+then a buffer is returned.
-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.
+### diffieHellman.setPrivateKey(private_key[, encoding])
-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.
+Sets the Diffie-Hellman private key. Key encoding can be `'binary'`,
+`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
+expected.
-## crypto.createCipheriv(algorithm, key, iv)
+### diffieHellman.setPublicKey(public_key[, encoding])
-Creates and returns a cipher object, with the given algorithm, key and
-iv.
+Sets the Diffie-Hellman public key. Key encoding can be `'binary'`,
+`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
+expected.
-`algorithm` is the same as the argument to `createCipher()`. `key` is
-the raw key used by the algorithm. `iv` is an [initialization
-vector](http://en.wikipedia.org/wiki/Initialization_vector).
+### diffieHellman.verifyError
-`key` and `iv` must be `'binary'` encoded strings or
-[buffers](buffer.html).
+A bit field containing any warnings and/or errors as a result of a check performed
+during initialization. The following values are valid for this property
+(defined in `constants` module):
-## Class: Cipher
+* `DH_CHECK_P_NOT_SAFE_PRIME`
+* `DH_CHECK_P_NOT_PRIME`
+* `DH_UNABLE_TO_CHECK_GENERATOR`
+* `DH_NOT_SUITABLE_GENERATOR`
-Class for encrypting data.
+## Class: ECDH
-Returned by `crypto.createCipher` and `crypto.createCipheriv`.
+The class for creating EC Diffie-Hellman key exchanges.
-Cipher objects are [streams](stream.html) that are both readable and
-writable. The written plain text data is used to produce the
-encrypted data on the readable side. The legacy `update` and `final`
-methods are also supported.
+Returned by `crypto.createECDH`.
-### cipher.update(data[, input_encoding][, output_encoding])
+### ECDH.computeSecret(other_public_key[, input_encoding][, output_encoding])
-Updates the cipher with `data`, the encoding of which is given in
-`input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`. If no
-encoding is provided, then a buffer is expected.
-If `data` is a `Buffer` then `input_encoding` is ignored.
+Computes the shared secret using `other_public_key` as the other
+party's public key and returns the computed shared secret. Supplied
+key is interpreted using specified `input_encoding`, and secret is
+encoded using specified `output_encoding`. Encodings can be
+`'binary'`, `'hex'`, or `'base64'`. If the input encoding is not
+provided, then a buffer is expected.
-The `output_encoding` specifies the output format of the enciphered
-data, and can be `'binary'`, `'base64'` or `'hex'`. If no encoding is
-provided, then a buffer is returned.
+If no output encoding is given, then a buffer is returned.
-Returns the enciphered contents, and can be called many times with new
-data as it is streamed.
+### ECDH.generateKeys([encoding[, format]])
-### cipher.final([output_encoding])
+Generates private and public EC Diffie-Hellman key values, and returns
+the public key in the specified format and encoding. This key should be
+transferred to the other party.
-Returns any remaining enciphered contents, with `output_encoding`
-being one of: `'binary'`, `'base64'` or `'hex'`. If no encoding is
-provided, then a buffer is returned.
+Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
+`'hybrid'`. If no format is provided - the point will be returned in
+`'uncompressed'` format.
-Note: `cipher` object can not be used after `final()` method has been
-called.
+Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
+then a buffer is returned.
-### cipher.setAutoPadding(auto_padding=true)
+### ECDH.getPrivateKey([encoding])
-You can disable automatic padding of the input data to block size. If
-`auto_padding` is false, the length of the entire input data must be a
-multiple of the cipher's block size or `final` will fail. Useful for
-non-standard padding, e.g. using `0x0` instead of PKCS padding. You
-must call this before `cipher.final`.
+Returns the EC Diffie-Hellman private key in the specified encoding,
+which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is
+provided, then a buffer is returned.
-### cipher.getAuthTag()
+### ECDH.getPublicKey([encoding[, format]])
-For authenticated encryption modes (currently supported: GCM), this
-method returns a `Buffer` that represents the _authentication tag_ that
-has been computed from the given data. Should be called after
-encryption has been completed using the `final` method!
+Returns the EC Diffie-Hellman public key in the specified encoding and format.
-### cipher.setAAD(buffer)
+Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
+`'hybrid'`. If no format is provided - the point will be returned in
+`'uncompressed'` format.
-For authenticated encryption modes (currently supported: GCM), this
-method sets the value used for the additional authenticated data (AAD) input
-parameter.
+Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
+then a buffer is returned.
+### ECDH.setPrivateKey(private_key[, encoding])
-## crypto.createDecipher(algorithm, password)
+Sets the EC Diffie-Hellman private key. Key encoding can be `'binary'`,
+`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
+expected.
-Creates and returns a decipher object, with the given algorithm and
-key. This is the mirror of the [createCipher()][] above.
+Example (obtaining a shared secret):
-## crypto.createDecipheriv(algorithm, key, iv)
+ var crypto = require('crypto');
+ var alice = crypto.createECDH('secp256k1');
+ var bob = crypto.createECDH('secp256k1');
-Creates and returns a decipher object, with the given algorithm, key
-and iv. This is the mirror of the [createCipheriv()][] above.
+ alice.generateKeys();
+ bob.generateKeys();
-## Class: Decipher
+ var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
+ var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
-Class for decrypting data.
+ /* alice_secret and bob_secret should be the same */
+ console.log(alice_secret == bob_secret);
-Returned by `crypto.createDecipher` and `crypto.createDecipheriv`.
+### ECDH.setPublicKey(public_key[, encoding])
-Decipher objects are [streams](stream.html) that are both readable and
-writable. The written enciphered data is used to produce the
-plain-text data on the the readable side. The legacy `update` and
-`final` methods are also supported.
+Sets the EC Diffie-Hellman public key. Key encoding can be `'binary'`,
+`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
+expected.
-### decipher.update(data[, input_encoding][, output_encoding])
+## Class: Hash
-Updates the decipher with `data`, which is encoded in `'binary'`,
-`'base64'` or `'hex'`. If no encoding is provided, then a buffer is
-expected.
-If `data` is a `Buffer` then `input_encoding` is ignored.
+The class for creating hash digests of data.
-The `output_decoding` specifies in what format to return the
-deciphered plaintext: `'binary'`, `'ascii'` or `'utf8'`. If no
-encoding is provided, then a buffer is returned.
+It is a [stream](stream.html) that is both readable and writable. The
+written data is used to compute the hash. Once the writable side of
+the stream is ended, use the `read()` method to get the computed hash
+digest. The legacy `update` and `digest` methods are also supported.
-### decipher.final([output_encoding])
+Returned by `crypto.createHash`.
-Returns any remaining plaintext which is deciphered, with
-`output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`. If
-no encoding is provided, then a buffer is returned.
+### hash.digest([encoding])
-Note: `decipher` object can not be used after `final()` method has been
+Calculates the digest of all of the passed data to be hashed. The
+`encoding` can be `'hex'`, `'binary'` or `'base64'`. If no encoding
+is provided, then a buffer is returned.
+
+Note: `hash` object can not be used after `digest()` method has been
called.
-### decipher.setAutoPadding(auto_padding=true)
+### hash.update(data[, input_encoding])
-You can disable auto padding if the data has been encrypted without
-standard block padding to prevent `decipher.final` from checking and
-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`.
+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
+encoding of `'binary'` is enforced. If `data` is a `Buffer` then
+`input_encoding` is ignored.
-### decipher.setAuthTag(buffer)
+This can be called many times with new data as it is streamed.
-For authenticated encryption modes (currently supported: GCM), this
-method must be used to pass in the received _authentication tag_.
-If no tag is provided or if the ciphertext has been tampered with,
-`final` will throw, thus indicating that the ciphertext should
-be discarded due to failed authentication.
+## Class: Hmac
-### decipher.setAAD(buffer)
+Class for creating cryptographic hmac content.
-For authenticated encryption modes (currently supported: GCM), this
-method sets the value used for the additional authenticated data (AAD) input
-parameter.
+Returned by `crypto.createHmac`.
+### hmac.digest([encoding])
-## crypto.createSign(algorithm)
+Calculates the digest of all of the passed data to the hmac. The
+`encoding` can be `'hex'`, `'binary'` or `'base64'`. If no encoding
+is provided, then a buffer is returned.
-Creates and returns a signing object, with the given algorithm. On
-recent OpenSSL releases, `openssl list-public-key-algorithms` will
-display the available signing algorithms. Examples are `'RSA-SHA256'`.
+Note: `hmac` object can not be used after `digest()` method has been
+called.
+
+### hmac.update(data)
+
+Update the hmac content with the given `data`. This can be called
+many times with new data as it is streamed.
## Class: Sign
written, the `sign` method will return the signature. The legacy
`update` method is also supported.
-### sign.update(data)
-
-Updates the sign object with data. This can be called many times
-with new data as it is streamed.
-
### sign.sign(private_key[, output_format])
Calculates the signature on all the updated data passed through the
Note: `sign` object can not be used after `sign()` method has been
called.
-## crypto.createVerify(algorithm)
+### sign.update(data)
-Creates and returns a verification object, with the given algorithm.
-This is the mirror of the signing object above.
+Updates the sign object with data. This can be called many times
+with new data as it is streamed.
## Class: Verify
Note: `verifier` object can not be used after `verify()` method has been
called.
-## crypto.createDiffieHellman(prime_length[, generator])
+## crypto.DEFAULT_ENCODING
-Creates a Diffie-Hellman key exchange object and generates a prime of
-`prime_length` bits and using an optional specific numeric `generator`.
-If no `generator` is specified, then `2` is used.
+The default encoding to use for functions that can take either strings
+or buffers. The default value is `'buffer'`, which makes it default
+to using Buffer objects. This is here to make the crypto module more
+easily compatible with legacy programs that expected `'binary'` to be
+the default encoding.
+
+Note that new programs will probably expect buffers, so only use this
+as a temporary measure.
+
+## crypto.createCipher(algorithm, password)
+
+Creates and returns a cipher object, with the given algorithm and
+password.
+
+`algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
+recent releases, `openssl list-cipher-algorithms` will display the
+available cipher algorithms. `password` is used to derive key and IV,
+which must be a `'binary'` encoded string or a [buffer](buffer.html).
+
+It is a [stream](stream.html) that is both readable and writable. The
+written data is used to compute the hash. Once the writable side of
+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
+iv.
+
+`algorithm` is the same as the argument to `createCipher()`. `key` is
+the raw key used by the algorithm. `iv` is an [initialization
+vector](http://en.wikipedia.org/wiki/Initialization_vector).
+
+`key` and `iv` must be `'binary'` encoded strings or
+[buffers](buffer.html).
+
+## crypto.createCredentials(details)
+
+ Stability: 0 - Deprecated: Use [tls.createSecureContext][] instead.
+
+Creates a credentials object, with the optional details being a
+dictionary with keys:
+
+* `pfx` : A string or buffer holding the PFX or PKCS12 encoded private
+ key, certificate and CA certificates
+* `key` : A string holding the PEM encoded private key
+* `passphrase` : A string of passphrase for the private key or pfx
+* `cert` : A string holding the PEM encoded certificate
+* `ca` : Either a string or list of strings of PEM encoded CA
+ certificates to trust.
+* `crl` : Either a string or list of strings of PEM encoded CRLs
+ (Certificate Revocation List)
+* `ciphers`: A string describing the ciphers to use or exclude.
+ Consult
+ <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
+publicly trusted list of CAs as given in
+<http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
+
+## crypto.createDecipher(algorithm, password)
+
+Creates and returns a decipher object, with the given algorithm and
+key. This is the mirror of the [createCipher()][] above.
+
+## crypto.createDecipheriv(algorithm, key, iv)
+
+Creates and returns a decipher object, with the given algorithm, key
+and iv. This is the mirror of the [createCipheriv()][] above.
## crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding])
If no `prime_encoding` is specified, then a Buffer is expected for `prime`.
If no `generator_encoding` is specified, then a Buffer is expected for `generator`.
-## Class: DiffieHellman
+## crypto.createDiffieHellman(prime_length[, generator])
-The class for creating Diffie-Hellman key exchanges.
+Creates a Diffie-Hellman key exchange object and generates a prime of
+`prime_length` bits and using an optional specific numeric `generator`.
+If no `generator` is specified, then `2` is used.
-Returned by `crypto.createDiffieHellman`.
+## crypto.createECDH(curve_name)
-### diffieHellman.verifyError
+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.
-A bit field containing any warnings and/or errors as a result of a check performed
-during initialization. The following values are valid for this property
-(defined in `constants` module):
+## crypto.createHash(algorithm)
-* `DH_CHECK_P_NOT_SAFE_PRIME`
-* `DH_CHECK_P_NOT_PRIME`
-* `DH_UNABLE_TO_CHECK_GENERATOR`
-* `DH_NOT_SUITABLE_GENERATOR`
+Creates and returns a hash object, a cryptographic hash with the given
+algorithm which can be used to generate hash digests.
-### diffieHellman.generateKeys([encoding])
+`algorithm` is dependent on the available algorithms supported by the
+version of OpenSSL on the platform. Examples are `'sha256'`,
+`'sha512'`, etc. On recent releases, `openssl
+list-message-digest-algorithms` will display the available digest
+algorithms.
+
+Example: this program that takes the sha256 sum of a file
+
+ var filename = process.argv[2];
+ var crypto = require('crypto');
+ var fs = require('fs');
+
+ var shasum = crypto.createHash('sha256');
+
+ var s = fs.ReadStream(filename);
+ s.on('data', function(d) {
+ shasum.update(d);
+ });
+
+ s.on('end', function() {
+ var d = shasum.digest('hex');
+ console.log(d + ' ' + filename);
+ });
-Generates private and public Diffie-Hellman key values, and returns
-the public key in the specified encoding. This key should be
-transferred to the other party. Encoding can be `'binary'`, `'hex'`,
-or `'base64'`. If no encoding is provided, then a buffer is returned.
+## crypto.createHmac(algorithm, key)
-### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding])
+Creates and returns a hmac object, a cryptographic hmac with the given
+algorithm and key.
-Computes the shared secret using `other_public_key` as the other
-party's public key and returns the computed shared secret. Supplied
-key is interpreted using specified `input_encoding`, and secret is
-encoded using specified `output_encoding`. Encodings can be
-`'binary'`, `'hex'`, or `'base64'`. If the input encoding is not
-provided, then a buffer is expected.
+It is a [stream](stream.html) that is both readable and writable. The
+written data is used to compute the hmac. Once the writable side of
+the stream is ended, use the `read()` method to get the computed
+digest. The legacy `update` and `digest` methods are also supported.
-If no output encoding is given, then a buffer is returned.
+`algorithm` is dependent on the available algorithms supported by
+OpenSSL - see createHash above. `key` is the hmac key to be used.
-### diffieHellman.getPrime([encoding])
+## crypto.createSign(algorithm)
-Returns the Diffie-Hellman prime in the specified encoding, which can
-be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
-then a buffer is returned.
+Creates and returns a signing object, with the given algorithm. On
+recent OpenSSL releases, `openssl list-public-key-algorithms` will
+display the available signing algorithms. Examples are `'RSA-SHA256'`.
-### diffieHellman.getGenerator([encoding])
+## crypto.createVerify(algorithm)
-Returns the Diffie-Hellman generator in the specified encoding, which can
-be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
-then a buffer is returned.
+Creates and returns a verification object, with the given algorithm.
+This is the mirror of the signing object above.
-### diffieHellman.getPublicKey([encoding])
+## crypto.getCiphers()
-Returns the Diffie-Hellman public key in the specified encoding, which
-can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
-then a buffer is returned.
+Returns an array with the names of the supported ciphers.
-### diffieHellman.getPrivateKey([encoding])
+Example:
-Returns the Diffie-Hellman private key in the specified encoding,
-which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is
-provided, then a buffer is returned.
+ var ciphers = crypto.getCiphers();
+ console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
-### diffieHellman.setPublicKey(public_key[, encoding])
+## crypto.getCurves()
-Sets the Diffie-Hellman public key. Key encoding can be `'binary'`,
-`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
-expected.
+Returns an array with the names of the supported elliptic curves.
-### diffieHellman.setPrivateKey(private_key[, encoding])
+Example:
-Sets the Diffie-Hellman private key. Key encoding can be `'binary'`,
-`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
-expected.
+ var curves = crypto.getCurves();
+ console.log(curves); // ['secp256k1', 'secp384r1', ...]
## crypto.getDiffieHellman(group_name)
/* alice_secret and bob_secret should be the same */
console.log(alice_secret == bob_secret);
-## crypto.createECDH(curve_name)
-
-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
-
-The class for creating EC Diffie-Hellman key exchanges.
-
-Returned by `crypto.createECDH`.
-
-### ECDH.generateKeys([encoding[, format]])
-
-Generates private and public EC Diffie-Hellman key values, and returns
-the public key in the specified format and encoding. This key should be
-transferred to the other party.
-
-Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
-`'hybrid'`. If no format is provided - the point will be returned in
-`'uncompressed'` format.
-
-Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
-then a buffer is returned.
-
-### ECDH.computeSecret(other_public_key[, input_encoding][, output_encoding])
-
-Computes the shared secret using `other_public_key` as the other
-party's public key and returns the computed shared secret. Supplied
-key is interpreted using specified `input_encoding`, and secret is
-encoded using specified `output_encoding`. Encodings can be
-`'binary'`, `'hex'`, or `'base64'`. If the input encoding is not
-provided, then a buffer is expected.
-
-If no output encoding is given, then a buffer is returned.
-
-### ECDH.getPublicKey([encoding[, format]])
-
-Returns the EC Diffie-Hellman public key in the specified encoding and format.
-
-Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
-`'hybrid'`. If no format is provided - the point will be returned in
-`'uncompressed'` format.
-
-Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
-then a buffer is returned.
-
-### ECDH.getPrivateKey([encoding])
-
-Returns the EC Diffie-Hellman private key in the specified encoding,
-which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is
-provided, then a buffer is returned.
-
-### ECDH.setPublicKey(public_key[, encoding])
-
-Sets the EC Diffie-Hellman public key. Key encoding can be `'binary'`,
-`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
-expected.
-
-### ECDH.setPrivateKey(private_key[, encoding])
-
-Sets the EC Diffie-Hellman private key. Key encoding can be `'binary'`,
-`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
-expected.
-
-Example (obtaining a shared secret):
-
- var crypto = require('crypto');
- var alice = crypto.createECDH('secp256k1');
- var bob = crypto.createECDH('secp256k1');
+## crypto.getHashes()
- alice.generateKeys();
- bob.generateKeys();
+Returns an array with the names of the supported hash algorithms.
- var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
- var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
+Example:
- /* alice_secret and bob_secret should be the same */
- console.log(alice_secret == bob_secret);
+ var hashes = crypto.getHashes();
+ console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
## crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback)
Synchronous PBKDF2 function. Returns derivedKey or throws error.
-## crypto.randomBytes(size[, callback])
-
-Generates cryptographically strong pseudo-random data. Usage:
-
- // async
- crypto.randomBytes(256, function(ex, buf) {
- if (ex) throw ex;
- console.log('Have %d bytes of random data: %s', buf.length, buf);
- });
-
- // sync
- 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
-may conceivably block is right after boot, when the whole system is still
-low on entropy.
+## crypto.privateDecrypt(private_key, buffer)
-## Class: Certificate
+Decrypts `buffer` with `private_key`.
-The class used for working with signed public key & challenges. The most
-common usage for this series of functions is when dealing with the `<keygen>`
-element. http://www.openssl.org/docs/apps/spkac.html
+`private_key` can be an object or a string. If `private_key` is a string, it is
+treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
-Returned by `crypto.Certificate`.
+`private_key`:
-### Certificate.verifySpkac(spkac)
+* `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`
+ * `constants.RSA_PKCS1_OAEP_PADDING`
-Returns true of false based on the validity of the SPKAC.
+NOTE: All paddings are defined in `constants` module.
-### Certificate.exportChallenge(spkac)
+## crypto.privateEncrypt(private_key, buffer)
-Exports the encoded challenge associated with the SPKAC.
+See above for details. Has the same API as `crypto.privateDecrypt`.
+Default padding is `RSA_PKCS1_PADDING`.
-### Certificate.exportPublicKey(spkac)
+## crypto.publicDecrypt(public_key, buffer)
-Exports the encoded public key from the supplied SPKAC.
+See above for details. Has the same API as `crypto.publicEncrypt`. Default
+padding is `RSA_PKCS1_PADDING`.
## crypto.publicEncrypt(public_key, buffer)
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`.
+## crypto.randomBytes(size[, callback])
-`private_key` can be an object or a string. If `private_key` is a string, it is
-treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
+Generates cryptographically strong pseudo-random data. Usage:
-`private_key`:
+ // async
+ crypto.randomBytes(256, function(ex, buf) {
+ if (ex) throw ex;
+ console.log('Have %d bytes of random data: %s', buf.length, buf);
+ });
-* `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`
- * `constants.RSA_PKCS1_OAEP_PADDING`
+ // sync
+ const buf = crypto.randomBytes(256);
+ console.log('Have %d bytes of random data: %s', buf.length, buf);
-NOTE: All paddings are defined in `constants` module.
+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.
-## crypto.privateEncrypt(private_key, buffer)
+## crypto.setEngine(engine[, flags])
-See above for details. Has the same API as `crypto.privateDecrypt`.
-Default padding is `RSA_PKCS1_PADDING`.
+Load and set engine for some/all OpenSSL functions (selected by flags).
-## crypto.DEFAULT_ENCODING
+`engine` could be either an id or a path to the engine's shared library.
-The default encoding to use for functions that can take either strings
-or buffers. The default value is `'buffer'`, which makes it default
-to using Buffer objects. This is here to make the crypto module more
-easily compatible with legacy programs that expected `'binary'` to be
-the default encoding.
+`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):
-Note that new programs will probably expect buffers, so only use this
-as a temporary measure.
+* `ENGINE_METHOD_RSA`
+* `ENGINE_METHOD_DSA`
+* `ENGINE_METHOD_DH`
+* `ENGINE_METHOD_RAND`
+* `ENGINE_METHOD_ECDH`
+* `ENGINE_METHOD_ECDSA`
+* `ENGINE_METHOD_CIPHERS`
+* `ENGINE_METHOD_DIGESTS`
+* `ENGINE_METHOD_STORE`
+* `ENGINE_METHOD_PKEY_METH`
+* `ENGINE_METHOD_PKEY_ASN1_METH`
+* `ENGINE_METHOD_ALL`
+* `ENGINE_METHOD_NONE`
## Recent API Changes
projects / platform / upstream / nodejs.git / commitdiff