|
|
|
# Crypto
|
|
|
|
|
|
|
|
Stability: 2 - Unstable; API changes are being discussed for
|
|
|
|
future versions. Breaking changes will be minimized. See below.
|
|
|
|
|
|
|
|
Use `require('crypto')` to access this module.
|
|
|
|
|
|
|
|
The crypto module offers a way of encapsulating secure credentials to be
|
|
|
|
used as part of a secure HTTPS net or http connection.
|
|
|
|
|
|
|
|
It also offers a set of wrappers for OpenSSL's hash, hmac, cipher,
|
|
|
|
decipher, sign and verify methods.
|
|
|
|
|
|
|
|
|
|
|
|
## crypto.getCiphers()
|
|
|
|
|
|
|
|
Returns an array with the names of the supported ciphers.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
var ciphers = crypto.getCiphers();
|
|
|
|
console.log(ciphers); // ['AES-128-CBC', 'AES-128-CBC-HMAC-SHA1', ...]
|
|
|
|
|
|
|
|
|
|
|
|
## crypto.getHashes()
|
|
|
|
|
|
|
|
Returns an array with the names of the supported hash algorithms.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
var hashes = crypto.getHashes();
|
|
|
|
console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
|
|
|
|
|
|
|
|
|
|
|
|
## crypto.createCredentials(details)
|
|
|
|
|
|
|
|
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.createHash(algorithm)
|
|
|
|
|
|
|
|
Creates and returns a hash object, a cryptographic hash with the given
|
|
|
|
algorithm which can be used to generate hash digests.
|
|
|
|
|
|
|
|
`algorithm` is dependent on the available algorithms supported by the
|
|
|
|
version of OpenSSL on the platform. Examples are `'sha1'`, `'md5'`,
|
|
|
|
`'sha256'`, `'sha512'`, etc. On recent releases, `openssl
|
|
|
|
list-message-digest-algorithms` will display the available digest
|
|
|
|
algorithms.
|
|
|
|
|
|
|
|
Example: this program that takes the sha1 sum of a file
|
|
|
|
|
|
|
|
var filename = process.argv[2];
|
|
|
|
var crypto = require('crypto');
|
|
|
|
var fs = require('fs');
|
|
|
|
|
|
|
|
var shasum = crypto.createHash('sha1');
|
|
|
|
|
|
|
|
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);
|
|
|
|
});
|
|
|
|
|
|
|
|
## Class: Hash
|
|
|
|
|
|
|
|
The class for creating hash digests of data.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
Returned by `crypto.createHash`.
|
|
|
|
|
|
|
|
### hash.update(data, [input_encoding])
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
This can be called many times with new data as it is streamed.
|
|
|
|
|
|
|
|
### hash.digest([encoding])
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
## crypto.createHmac(algorithm, key)
|
|
|
|
|
|
|
|
Creates and returns a hmac object, a cryptographic hmac with the given
|
|
|
|
algorithm and key.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
`algorithm` is dependent on the available algorithms supported by
|
|
|
|
OpenSSL - see createHash above. `key` is the hmac key to be used.
|
|
|
|
|
|
|
|
## Class: Hmac
|
|
|
|
|
|
|
|
Class for creating cryptographic hmac content.
|
|
|
|
|
|
|
|
Returned by `crypto.createHmac`.
|
|
|
|
|
|
|
|
### hmac.update(data)
|
|
|
|
|
|
|
|
Update the hmac content with the given `data`. This can be called
|
|
|
|
many times with new data as it is streamed.
|
|
|
|
|
|
|
|
### hmac.digest([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.
|
|
|
|
|
|
|
|
Note: `hmac` object can not be used after `digest()` method has been
|
|
|
|
called.
|
|
|
|
|
|
|
|
|
|
|
|
## 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 computed hash
|
|
|
|
digest. The legacy `update` and `digest` methods are also supported.
|
|
|
|
|
|
|
|
## 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).
|
|
|
|
|
|
|
|
## Class: Cipher
|
|
|
|
|
|
|
|
Class for encrypting data.
|
|
|
|
|
|
|
|
Returned by `crypto.createCipher` and `crypto.createCipheriv`.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### cipher.update(data, [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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
Returns the enciphered contents, and can be called many times with new
|
|
|
|
data as it is streamed.
|
|
|
|
|
|
|
|
### cipher.final([output_encoding])
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### 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.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.
|
|
|
|
|
|
|
|
## Class: Decipher
|
|
|
|
|
|
|
|
Class for decrypting data.
|
|
|
|
|
|
|
|
Returned by `crypto.createDecipher` and `crypto.createDecipheriv`.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### decipher.final([output_encoding])
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
Note: `decipher` object can not be used after `final()` method has been
|
|
|
|
called.
|
|
|
|
|
|
|
|
### decipher.setAutoPadding(auto_padding=true)
|
|
|
|
|
|
|
|
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
|
|
|
|
the ciphers block size. You must call this before streaming data to
|
|
|
|
`decipher.update`.
|
|
|
|
|
|
|
|
## crypto.createSign(algorithm)
|
|
|
|
|
|
|
|
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'`.
|
|
|
|
|
|
|
|
## Class: Sign
|
|
|
|
|
|
|
|
Class for generating signatures.
|
|
|
|
|
|
|
|
Returned by `crypto.createSign`.
|
|
|
|
|
|
|
|
Sign objects are writable [streams](stream.html). The written data is
|
|
|
|
used to generate the signature. Once all of the data has been
|
|
|
|
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
|
|
|
|
sign. `private_key` is a string containing the PEM encoded private
|
|
|
|
key for signing.
|
|
|
|
|
|
|
|
Returns the signature in `output_format` which can be `'binary'`,
|
|
|
|
`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
|
|
|
|
returned.
|
|
|
|
|
|
|
|
Note: `sign` object can not be used after `sign()` method has been
|
|
|
|
called.
|
|
|
|
|
|
|
|
## crypto.createVerify(algorithm)
|
|
|
|
|
|
|
|
Creates and returns a verification object, with the given algorithm.
|
|
|
|
This is the mirror of the signing object above.
|
|
|
|
|
|
|
|
## Class: Verify
|
|
|
|
|
|
|
|
Class for verifying signatures.
|
|
|
|
|
|
|
|
Returned by `crypto.createVerify`.
|
|
|
|
|
|
|
|
Verify objects are writable [streams](stream.html). The written data
|
|
|
|
is used to validate against the supplied signature. Once all of the
|
|
|
|
data has been written, the `verify` method will return true if the
|
|
|
|
supplied signature is valid. The legacy `update` method is also
|
|
|
|
supported.
|
|
|
|
|
|
|
|
### verifier.update(data)
|
|
|
|
|
|
|
|
Updates the verifier object with data. This can be called many times
|
|
|
|
with new data as it is streamed.
|
|
|
|
|
|
|
|
### verifier.verify(object, signature, [signature_format])
|
|
|
|
|
|
|
|
Verifies the signed data by using the `object` and `signature`.
|
|
|
|
`object` is a string containing a PEM encoded object, which can be
|
|
|
|
one of RSA public key, DSA public key, or X.509 certificate.
|
|
|
|
`signature` is the previously calculated signature for the data, in
|
|
|
|
the `signature_format` which can be `'binary'`, `'hex'` or `'base64'`.
|
|
|
|
If no encoding is specified, then a buffer is expected.
|
|
|
|
|
|
|
|
Returns true or false depending on the validity of the signature for
|
|
|
|
the data and public key.
|
|
|
|
|
|
|
|
Note: `verifier` object can not be used after `verify()` method has been
|
|
|
|
called.
|
|
|
|
|
|
|
|
## crypto.createDiffieHellman(prime_length)
|
|
|
|
|
|
|
|
Creates a Diffie-Hellman key exchange object and generates a prime of
|
|
|
|
the given bit length. The generator used is `2`.
|
|
|
|
|
|
|
|
## crypto.createDiffieHellman(prime, [encoding])
|
|
|
|
|
|
|
|
Creates a Diffie-Hellman key exchange object using the supplied prime.
|
|
|
|
The generator used is `2`. Encoding can be `'binary'`, `'hex'`, or
|
|
|
|
`'base64'`. If no encoding is specified, then a buffer is expected.
|
|
|
|
|
|
|
|
## Class: DiffieHellman
|
|
|
|
|
|
|
|
The class for creating Diffie-Hellman key exchanges.
|
|
|
|
|
|
|
|
Returned by `crypto.createDiffieHellman`.
|
|
|
|
|
|
|
|
### diffieHellman.generateKeys([encoding])
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### diffieHellman.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.
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
|
|
|
|
### diffieHellman.getGenerator([encoding])
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### diffieHellman.getPublicKey([encoding])
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### diffieHellman.getPrivateKey([encoding])
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### diffieHellman.setPublicKey(public_key, [encoding])
|
|
|
|
|
|
|
|
Sets the Diffie-Hellman public key. Key encoding can be `'binary'`,
|
|
|
|
`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
|
|
|
|
expected.
|
|
|
|
|
|
|
|
### diffieHellman.setPrivateKey(private_key, [encoding])
|
|
|
|
|
|
|
|
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.getDiffieHellman(group_name)
|
|
|
|
|
|
|
|
Creates a predefined Diffie-Hellman key exchange object. The
|
|
|
|
supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in [RFC
|
|
|
|
2412][]) and `'modp14'`, `'modp15'`, `'modp16'`, `'modp17'`,
|
|
|
|
`'modp18'` (defined in [RFC 3526][]). The returned object mimics the
|
|
|
|
interface of objects created by [crypto.createDiffieHellman()][]
|
|
|
|
above, but will not allow to change the keys (with
|
|
|
|
[diffieHellman.setPublicKey()][] for example). The advantage of using
|
|
|
|
this routine is that the parties don't have to generate nor exchange
|
|
|
|
group modulus beforehand, saving both processor and communication
|
|
|
|
time.
|
|
|
|
|
|
|
|
Example (obtaining a shared secret):
|
|
|
|
|
|
|
|
var crypto = require('crypto');
|
|
|
|
var alice = crypto.getDiffieHellman('modp5');
|
|
|
|
var bob = crypto.getDiffieHellman('modp5');
|
|
|
|
|
|
|
|
alice.generateKeys();
|
|
|
|
bob.generateKeys();
|
|
|
|
|
|
|
|
var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
|
|
|
|
var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
|
|
|
|
|
|
|
|
/* alice_secret and bob_secret should be the same */
|
|
|
|
console.log(alice_secret == bob_secret);
|
|
|
|
|
|
|
|
## crypto.pbkdf2(password, salt, iterations, keylen, callback)
|
|
|
|
|
|
|
|
Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive
|
|
|
|
a key of given length from the given password, salt and iterations.
|
|
|
|
The callback gets two arguments `(err, derivedKey)`.
|
|
|
|
|
|
|
|
## crypto.pbkdf2Sync(password, salt, iterations, keylen)
|
|
|
|
|
|
|
|
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
|
|
|
|
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
|
|
|
|
}
|
|
|
|
|
|
|
|
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`.
|
|
|
|
|
|
|
|
## crypto.DEFAULT_ENCODING
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
## Recent API Changes
|
|
|
|
|
|
|
|
The Crypto module was added to Node 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
|
|
|
|
Binary-encoded strings by default rather than Buffers. This was
|
|
|
|
changed to use Buffers by default instead.
|
|
|
|
|
|
|
|
This is a breaking change for some use cases, but not all.
|
|
|
|
|
|
|
|
For example, if you currently use the default arguments to the Sign
|
|
|
|
class, and then pass the results to the Verify class, without ever
|
|
|
|
inspecting the data, then it will continue to work as before. Where
|
|
|
|
you once got a binary string and then presented the binary string to
|
|
|
|
the Verify object, you'll now get a Buffer, and present the Buffer to
|
|
|
|
the Verify object.
|
|
|
|
|
|
|
|
However, if you were doing things with the string data that will not
|
|
|
|
work properly on Buffers (such as, concatenating them, storing in
|
|
|
|
databases, etc.), or you are passing binary strings to the crypto
|
|
|
|
functions without an encoding argument, then you will need to start
|
|
|
|
providing encoding arguments to specify which encoding you'd like to
|
|
|
|
use. To switch to the previous style of using binary strings by
|
|
|
|
default, set the `crypto.DEFAULT_ENCODING` field to 'binary'. Note
|
|
|
|
that new programs will probably expect buffers, so only use this as a
|
|
|
|
temporary measure.
|
|
|
|
|
|
|
|
|
|
|
|
[createCipher()]: #crypto_crypto_createcipher_algorithm_password
|
|
|
|
[createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv
|
|
|
|
[crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_encoding
|
|
|
|
[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
|