1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: improvements to crypto.markdown copy

Browse Source 
Fix several typos. Add missing links.

PR-URL: https://github.com/nodejs/node/pull/5230
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Kelvin Knighton <keltheceo@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
This commit is contained in:
Alexander Makarenko 2016-02-15 03:40:53 +03:00 committed by Roman Reiss
parent 725ffdb9b7
commit f0c06147b3
1 changed files with 124 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

231
doc/api/crypto.markdown
View File

@ -55,7 +55,7 @@ console.log(challenge.toString('utf8'));
// Prints the challenge as a UTF8 string // Prints the challenge as a UTF8 string
``` ```
### Certificate.exportPublicKey(spkac) ### certificate.exportPublicKey(spkac)
The `spkac` data structure includes a public key and a challenge. The The `spkac` data structure includes a public key and a challenge. The
`certificate.exportPublicKey()` returns the public key component in the `certificate.exportPublicKey()` returns the public key component in the
@ -70,7 +70,7 @@ console.log(publicKey);
// Prints the public key as <Buffer ...> // Prints the public key as <Buffer ...>
``` ```
### Certificate.verifySpkac(spkac) ### certificate.verifySpkac(spkac)
Returns `true` if the given `spkac` data structure is valid, `false` otherwise. Returns `true` if the given `spkac` data structure is valid, `false` otherwise.
The `spkac` argument must be a Node.js [`Buffer`][]. The `spkac` argument must be a Node.js [`Buffer`][].
@ -89,12 +89,12 @@ used in one of two ways:
- As a [stream][] that is both readable and writable, where plain unencrypted - As a [stream][] that is both readable and writable, where plain unencrypted
data is written to produce encrypted data on the readable side, or data is written to produce encrypted data on the readable side, or
- Using the `cipher.update()` and `cipher.final()` methods to produce the - Using the [`cipher.update()`][] and [`cipher.final()`][] methods to produce
encrypted data. the encrypted data.
The `crypto.createCipher()` or `crypto.createCipheriv()` methods are used to The [`crypto.createCipher()`][] or [`crypto.createCipheriv()`][] methods are
create `Cipher` instances. `Cipher` objects are not to be created directly used to create `Cipher` instances. `Cipher` objects are not to be created
using the `new` keyword. directly using the `new` keyword.
Example: Using `Cipher` objects as streams: Example: Using `Cipher` objects as streams:
@ -130,7 +130,7 @@ const output = fs.createWriteStream('test.enc');
input.pipe(cipher).pipe(output); input.pipe(cipher).pipe(output);
``` ```
Example: Using the `cipher.update()` and `cipher.final()` methods: Example: Using the [`cipher.update()`][] and [`cipher.final()`][] methods:
```js ```js
const crypto = require('crypto'); const crypto = require('crypto');
@ -155,7 +155,7 @@ once will result in an error being thrown.
### cipher.setAAD(buffer) ### cipher.setAAD(buffer)
When using an authenticated encryption mode (only `GCM` is currently When using an authenticated encryption mode (only `GCM` is currently
supported), the `cipher.getAAD()` method sets the value used for the supported), the `cipher.setAAD()` method sets the value used for the
_additional authenticated data_ (AAD) input parameter. _additional authenticated data_ (AAD) input parameter.
### cipher.getAuthTag() ### cipher.getAuthTag()
@ -165,7 +165,7 @@ supported), the `cipher.getAuthTag()` method returns a [`Buffer`][] containing
the _authentication tag_ that has been computed from the given data. the _authentication tag_ that has been computed from the given data.
The `cipher.getAuthTag()` method should only be called after encryption has The `cipher.getAuthTag()` method should only be called after encryption has
been completed using the `cipher.final()` method. been completed using the [`cipher.final()`][] method.
### cipher.setAutoPadding(auto_padding=true) ### cipher.setAutoPadding(auto_padding=true)
@ -174,11 +174,11 @@ add padding to the input data to the appropriate block size. To disable the
default padding call `cipher.setAutoPadding(false)`. default padding call `cipher.setAutoPadding(false)`.
When `auto_padding` is `false`, the length of the entire input data must be a When `auto_padding` is `false`, the length of the entire input data must be a
multiple of the cipher's block size or `cipher.final()` will throw an Error. multiple of the cipher's block size or [`cipher.final()`][] will throw an Error.
Disabling automatic padding is useful for non-standard padding, for instance Disabling automatic padding is useful for non-standard padding, for instance
using `0x0` instead of PKCS padding. using `0x0` instead of PKCS padding.
The `cipher.setAutoPadding()` method must be called before `cipher.final()`. The `cipher.setAutoPadding()` method must be called before [`cipher.final()`][].
### cipher.update(data[, input_encoding][, output_encoding]) ### cipher.update(data[, input_encoding][, output_encoding])
@ -194,8 +194,8 @@ is specified, a string using the specified encoding is returned. If no
`output_encoding` is provided, a [`Buffer`][] is returned. `output_encoding` is provided, a [`Buffer`][] is returned.
The `cipher.update()` method can be called multiple times with new data until The `cipher.update()` method can be called multiple times with new data until
`cipher.final()` is called. Calling `cipher.update()` after `cipher.final()` [`cipher.final()`][] is called. Calling `cipher.update()` after
will result in an error being thrown. [`cipher.final()`][] will result in an error being thrown.
## Class: Decipher ## Class: Decipher
@ -204,11 +204,11 @@ used in one of two ways:
- As a [stream][] that is both readable and writable, where plain encrypted - As a [stream][] that is both readable and writable, where plain encrypted
data is written to produce unencrypted data on the readable side, or data is written to produce unencrypted data on the readable side, or
- Using the `decipher.update()` and `decipher.final()` methods to produce the - Using the [`decipher.update()`][] and [`decipher.final()`][] methods to
unencrypted data. produce the unencrypted data.
The `crypto.createDecipher()` or `crypto.createDecipheriv()` methods are used The [`crypto.createDecipher()`][] or [`crypto.createDecipheriv()`][] methods are
to create `Decipher` instances. `Decipher` objects are not to be created used to create `Decipher` instances. `Decipher` objects are not to be created
directly using the `new` keyword. directly using the `new` keyword.
Example: Using `Decipher` objects as streams: Example: Using `Decipher` objects as streams:
@ -246,7 +246,7 @@ const output = fs.createWriteStream('test.js');
input.pipe(decipher).pipe(output); input.pipe(decipher).pipe(output);
``` ```
Example: Using the `decipher.update()` and `decipher.final()` methods: Example: Using the [`decipher.update()`][] and [`decipher.final()`][] methods:
```js ```js
const crypto = require('crypto'); const crypto = require('crypto');
@ -272,28 +272,28 @@ than once will result in an error being thrown.
### decipher.setAAD(buffer) ### decipher.setAAD(buffer)
When using an authenticated encryption mode (only `GCM` is currently When using an authenticated encryption mode (only `GCM` is currently
supported), the `cipher.getAAD()` method sets the value used for the supported), the `cipher.setAAD()` method sets the value used for the
_additional authenticated data_ (AAD) input parameter. _additional authenticated data_ (AAD) input parameter.
### decipher.setAuthTag(buffer) ### decipher.setAuthTag(buffer)
When using an authenticated encryption mode (only `GCM` is currently When using an authenticated encryption mode (only `GCM` is currently
supported), the `decipher.setAuthTag()` method is used to pass in the supported), the `decipher.setAuthTag()` method is used to pass in the
received _authentication tag_. If no tag is provided, or if the ciphertext received _authentication tag_. If no tag is provided, or if the cipher text
has been tampered with, `decipher.final()` with throw, indicating that the has been tampered with, [`decipher.final()`][] with throw, indicating that the
ciphertext should be discarded due to failed authentication. cipher text should be discarded due to failed authentication.
### decipher.setAutoPadding(auto_padding=true) ### decipher.setAutoPadding(auto_padding=true)
When data has been encrypted without standard block padding, calling When data has been encrypted without standard block padding, calling
`decipher.setAuthPadding(false)` will disable automatic padding to prevent `decipher.setAuthPadding(false)` will disable automatic padding to prevent
`decipher.final()` from checking for and removing padding. [`decipher.final()`][] from checking for and removing padding.
Turning auto padding off will only work if the input data's length is a Turning auto padding off will only work if the input data's length is a
multiple of the ciphers block size. multiple of the ciphers block size.
The `decipher.setAutoPadding()` method must be called before The `decipher.setAutoPadding()` method must be called before
`decipher.update()`. [`decipher.update()`][].
### decipher.update(data[, input_encoding][, output_encoding]) ### decipher.update(data[, input_encoding][, output_encoding])
@ -309,8 +309,8 @@ is specified, a string using the specified encoding is returned. If no
`output_encoding` is provided, a [`Buffer`][] is returned. `output_encoding` is provided, a [`Buffer`][] is returned.
The `decipher.update()` method can be called multiple times with new data until The `decipher.update()` method can be called multiple times with new data until
`decipher.final()` is called. Calling `decipher.update()` after [`decipher.final()`][] is called. Calling `decipher.update()` after
`decipher.final()` will result in an error being thrown. [`decipher.final()`][] will result in an error being thrown.
## Class: DiffieHellman ## Class: DiffieHellman
@ -318,7 +318,7 @@ The `DiffieHellman` class is a utility for creating Diffie-Hellman key
exchanges. exchanges.
Instances of the `DiffieHellman` class can be created using the Instances of the `DiffieHellman` class can be created using the
`crypto.createDiffieHellman()` function. [`crypto.createDiffieHellman()`][] function.
```js ```js
const crypto = require('crypto'); const crypto = require('crypto');
@ -357,7 +357,7 @@ If `output_encoding` is given a string is returned; otherwise, a
Generates private and public Diffie-Hellman key values, and returns Generates private and public Diffie-Hellman key values, and returns
the public key in the specified `encoding`. This key should be the public key in the specified `encoding`. This key should be
transferred to the other party. Encoding can be `'binary'`, `'hex'`, transferred to the other party. Encoding can be `'binary'`, `'hex'`,
or `'base64'`. If `encoding` is provided a string is returned; otherwise a or `'base64'`. If `encoding` is provided a string is returned; otherwise a
[`Buffer`][] is returned. [`Buffer`][] is returned.
### diffieHellman.getGenerator([encoding]) ### diffieHellman.getGenerator([encoding])
@ -417,7 +417,7 @@ The `ECDH` class is a utility for creating Elliptic Curve Diffie-Hellman (ECDH)
key exchanges. key exchanges.
Instances of the `ECDH` class can be created using the Instances of the `ECDH` class can be created using the
`crypto.createECDH()` function. [`crypto.createECDH()`][] function.
```js ```js
const crypto = require('crypto'); const crypto = require('crypto');
@ -439,7 +439,7 @@ assert(alice_secret, bob_secret);
// OK // OK
``` ```
### ECDH.computeSecret(other_public_key[, input_encoding][, output_encoding]) ### ecdh.computeSecret(other_public_key[, input_encoding][, output_encoding])
Computes the shared secret using `other_public_key` as the other Computes the shared secret using `other_public_key` as the other
party's public key and returns the computed shared secret. The supplied party's public key and returns the computed shared secret. The supplied
@ -451,7 +451,7 @@ provided, `other_public_key` is expected to be a [`Buffer`][].
If `output_encoding` is given a string will be returned; otherwise a If `output_encoding` is given a string will be returned; otherwise a
[`Buffer`][] is returned. [`Buffer`][] is returned.
### ECDH.generateKeys([encoding[, format]]) ### ecdh.generateKeys([encoding[, format]])
Generates private and public EC Diffie-Hellman key values, and returns Generates private and public EC Diffie-Hellman key values, and returns
the public key in the specified `format` and `encoding`. This key should be the public key in the specified `format` and `encoding`. This key should be
@ -465,13 +465,13 @@ The `encoding` argument can be `'binary'`, `'hex'`, or `'base64'`. If
`encoding` is provided a string is returned; otherwise a [`Buffer`][] `encoding` is provided a string is returned; otherwise a [`Buffer`][]
is returned. is returned.
### ECDH.getPrivateKey([encoding]) ### ecdh.getPrivateKey([encoding])
Returns the EC Diffie-Hellman private key in the specified `encoding`, Returns the EC Diffie-Hellman private key in the specified `encoding`,
which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided
a string is returned; otherwise a [`Buffer`][] is returned. a string is returned; otherwise a [`Buffer`][] is returned.
### ECDH.getPublicKey([encoding[, format]]) ### ecdh.getPublicKey([encoding[, format]])
Returns the EC Diffie-Hellman public key in the specified `encoding` and Returns the EC Diffie-Hellman public key in the specified `encoding` and
`format`. `format`.
@ -484,7 +484,7 @@ The `encoding` argument can be `'binary'`, `'hex'`, or `'base64'`. If
`encoding` is specified, a string is returned; otherwise a [`Buffer`][] is `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is
returned. returned.
### ECDH.setPrivateKey(private_key[, encoding]) ### ecdh.setPrivateKey(private_key[, encoding])
Sets the EC Diffie-Hellman private key. The `encoding` can be `'binary'`, Sets the EC Diffie-Hellman private key. The `encoding` can be `'binary'`,
`'hex'` or `'base64'`. If `encoding` is provided, `private_key` is expected `'hex'` or `'base64'`. If `encoding` is provided, `private_key` is expected
@ -493,7 +493,7 @@ to be a string; otherwise `private_key` is expected to be a [`Buffer`][]. If
created, an error is thrown. Upon setting the private key, the associated created, an error is thrown. Upon setting the private key, the associated
public point (key) is also generated and set in the ECDH object. public point (key) is also generated and set in the ECDH object.
### ECDH.setPublicKey(public_key[, encoding]) ### ecdh.setPublicKey(public_key[, encoding])
Stability: 0 - Deprecated Stability: 0 - Deprecated
@ -503,9 +503,10 @@ be a string; otherwise a [`Buffer`][] is expected.
Note that there is not normally a reason to call this method because `ECDH` Note that there is not normally a reason to call this method because `ECDH`
only requires a private key and the other party's public key to compute the only requires a private key and the other party's public key to compute the
shared secret. Typically either `ecdh.generateKeys()` or `ecdh.setPrivateKey()` shared secret. Typically either [`ecdh.generateKeys()`][] or
will be called. The `ecdh.setPrivateKey()` method attempts to generate the [`ecdh.setPrivateKey()`][] will be called. The [`ecdh.setPrivateKey()`][] method
public point/key associated with the private key being set. attempts to generate the public point/key associated with the private key being
set.
Example (obtaining a shared secret): Example (obtaining a shared secret):
@ -538,10 +539,10 @@ used in one of two ways:
- As a [stream][] that is both readable and writable, where data is written - As a [stream][] that is both readable and writable, where data is written
to produce a computed hash digest on the readable side, or to produce a computed hash digest on the readable side, or
- Using the `hash.update()` and `hash.digest()` methods to produce the - Using the [`hash.update()`][] and [`hash.digest()`][] methods to produce the
computed hash. computed hash.
The `crypto.createHash()` method is used to create `Hash` instances. `Hash` The [`crypto.createHash()`][] method is used to create `Hash` instances. `Hash`
objects are not to be created directly using the `new` keyword. objects are not to be created directly using the `new` keyword.
Example: Using `Hash` objects as streams: Example: Using `Hash` objects as streams:
@ -573,7 +574,7 @@ const input = fs.createReadStream('test.js');
input.pipe(hash).pipe(process.stdout); input.pipe(hash).pipe(process.stdout);
``` ```
Example: Using the `hash.update()` and `hash.digest()` methods: Example: Using the [`hash.update()`][] and [`hash.digest()`][] methods:
```js ```js
const crypto = require('crypto'); const crypto = require('crypto');
@ -588,8 +589,8 @@ console.log(hash.digest('hex'));
### hash.digest([encoding]) ### hash.digest([encoding])
Calculates the digest of all of the data passed to be hashed (using the Calculates the digest of all of the data passed to be hashed (using the
`hash.update()` method). The `encoding` can be `'hex'`, `'binary'` or [`hash.update()`][] method). The `encoding` can be `'hex'`, `'binary'` or
`'base64'`. If `encoding` is provided a string will be returned; otherwise `'base64'`. If `encoding` is provided a string will be returned; otherwise
a [`Buffer`][] is returned. a [`Buffer`][] is returned.
The `Hash` object can not be used again after `hash.digest()` method has been The `Hash` object can not be used again after `hash.digest()` method has been
@ -599,7 +600,7 @@ called. Multiple calls will cause an error to be thrown.
Updates the hash content with the given `data`, the encoding of which Updates the hash content with the given `data`, the encoding of which
is given in `input_encoding` and can be `'utf8'`, `'ascii'` or is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
`'binary'`. If `encoding` is not provided, and the `data` is a string, an `'binary'`. If `encoding` is not provided, and the `data` is a string, an
encoding of `'binary'` is enforced. If `data` is a [`Buffer`][] then encoding of `'binary'` is enforced. If `data` is a [`Buffer`][] then
`input_encoding` is ignored. `input_encoding` is ignored.
@ -612,10 +613,10 @@ be used in one of two ways:
- As a [stream][] that is both readable and writable, where data is written - As a [stream][] that is both readable and writable, where data is written
to produce a computed HMAC digest on the readable side, or to produce a computed HMAC digest on the readable side, or
- Using the `hmac.update()` and `hmac.final()` methods to produce the - Using the [`hmac.update()`][] and [`hmac.digest()`][] methods to produce the
computed HMAC digest. computed HMAC digest.
The `crypto.createHmac()` method is used to create `Hmac` instances. `Hmac` The [`crypto.createHmac()`][] method is used to create `Hmac` instances. `Hmac`
objects are not to be created directly using the `new` keyword. objects are not to be created directly using the `new` keyword.
Example: Using `Hmac` objects as streams: Example: Using `Hmac` objects as streams:
@ -647,7 +648,7 @@ const input = fs.createReadStream('test.js');
input.pipe(hmac).pipe(process.stdout); input.pipe(hmac).pipe(process.stdout);
``` ```
Example: Using the `hmac.update()` and `hmac.digest()` methods: Example: Using the [`hmac.update()`][] and [`hmac.digest()`][] methods:
```js ```js
const crypto = require('crypto'); const crypto = require('crypto');
@ -661,16 +662,16 @@ console.log(hmac.digest('hex'));
### hmac.digest([encoding]) ### hmac.digest([encoding])
Calculates the HMAC digest of all of the data passed using `hmac.update()`. The Calculates the HMAC digest of all of the data passed using [`hmac.update()`][].
`encoding` can be `'hex'`, `'binary'` or `'base64'`. If `encoding` is provided The `encoding` can be `'hex'`, `'binary'` or `'base64'`. If `encoding` is
a string is returned; otherwise a [`Buffer`][] is returned; provided a string is returned; otherwise a [`Buffer`][] is returned;
The `Hmac` object can not be used again after `hmac.digest()` has been The `Hmac` object can not be used again after `hmac.digest()` has been
called. Multiple calls to `hmac.digest()` will result in an error being thrown. called. Multiple calls to `hmac.digest()` will result in an error being thrown.
### hmac.update(data) ### hmac.update(data)
Update the `Hmac` content with the given `data`. This can be called Update the `Hmac` content with the given `data`. This can be called
many times with new data as it is streamed. many times with new data as it is streamed.
## Class: Sign ## Class: Sign
@ -679,11 +680,11 @@ The `Sign` Class is a utility for generating signatures. It can be used in one
of two ways: of two ways:
- As a writable [stream][], where data to be signed is written and the - As a writable [stream][], where data to be signed is written and the
`sign.sign()` method is used to generate and return the signature, or [`sign.sign()`][] method is used to generate and return the signature, or
- Using the `sign.update()` and `sign.sign()` methods to produce the - Using the [`sign.update()`][] and [`sign.sign()`][] methods to produce the
signature. signature.
The `crypto.createSign()` method is used to create `Sign` instances. `Sign` The [`crypto.createSign()`][] method is used to create `Sign` instances. `Sign`
objects are not to be created directly using the `new` keyword. objects are not to be created directly using the `new` keyword.
Example: Using `Sign` objects as streams: Example: Using `Sign` objects as streams:
@ -700,7 +701,7 @@ console.log(sign.sign(private_key, 'hex'));
// Prints the calculated signature // Prints the calculated signature
``` ```
Example: Using the `sign.update()` and `sign.sign()` methods: Example: Using the [`sign.update()`][] and [`sign.sign()`][] methods:
```js ```js
const crypto = require('crypto'); const crypto = require('crypto');
@ -716,7 +717,7 @@ console.log(sign.sign(private_key, 'hex'));
### sign.sign(private_key[, output_format]) ### sign.sign(private_key[, output_format])
Calculates the signature on all the data passed through using either Calculates the signature on all the data passed through using either
`sign.update()` or `sign.write()`. [`sign.update()`][] or [`sign.write()`][stream-writable-write].
The `private_key` argument can be an object or a string. If `private_key` is a The `private_key` argument can be an object or a string. If `private_key` is a
string, it is treated as a raw key with no passphrase. If `private_key` is an string, it is treated as a raw key with no passphrase. If `private_key` is an
@ -734,7 +735,7 @@ called. Multiple calls to `sign.sign()` will result in an error being thrown.
### sign.update(data) ### sign.update(data)
Updates the sign object with the given `data`. This can be called many times Updates the sign object with the given `data`. This can be called many times
with new data as it is streamed. with new data as it is streamed.
## Class: Verify ## Class: Verify
@ -744,11 +745,11 @@ of two ways:
- As a writable [stream][] where written data is used to validate against the - As a writable [stream][] where written data is used to validate against the
supplied signature, or supplied signature, or
- Using the `verify.update()` and `verify.verify()` methods to verify the - Using the [`verify.update()`][] and [`verify.verify()`][] methods to verify
signature. the signature.
The `crypto.createSign()` method is used to create `Sign` instances. `Sign` The [`crypto.createSign()`][] method is used to create `Sign` instances.
objects are not to be created directly using the `new` keyword. `Sign` objects are not to be created directly using the `new` keyword.
Example: Using `Verify` objects as streams: Example: Using `Verify` objects as streams:
@ -765,7 +766,7 @@ console.log(sign.verify(public_key, signature));
// Prints true or false // Prints true or false
``` ```
Example: Using the `verify.update()` and `verify.verify()` methods: Example: Using the [`verify.update()`][] and [`verify.verify()`][] methods:
```js ```js
const crypto = require('crypto'); const crypto = require('crypto');
@ -781,7 +782,7 @@ console.log(verify.verify(public_key, signature));
### verifier.update(data) ### verifier.update(data)
Updates the verifier object with the given `data`. This can be called many Updates the verifier object with the given `data`. This can be called many
times with new data as it is streamed. times with new data as it is streamed.
### verifier.verify(object, signature[, signature_format]) ### verifier.verify(object, signature[, signature_format])
@ -806,8 +807,8 @@ thrown.
### crypto.DEFAULT_ENCODING ### crypto.DEFAULT_ENCODING
The default encoding to use for functions that can take either strings The default encoding to use for functions that can take either strings
or [buffers][]. The default value is `'buffer'`, which makes methods default or [buffers][`Buffer`]. The default value is `'buffer'`, which makes methods
to [`Buffer`][] objects. default to [`Buffer`][] objects.
The `crypto.DEFAULT_ENCODING` mechanism is provided for backwards compatibility The `crypto.DEFAULT_ENCODING` mechanism is provided for backwards compatibility
with legacy programs that expect `'binary'` to be the default encoding. with legacy programs that expect `'binary'` to be the default encoding.
@ -825,7 +826,7 @@ currently in use. Setting to true requires a FIPS build of Node.js.
Creates and returns a `Cipher` object that uses the given `algorithm` and Creates and returns a `Cipher` object that uses the given `algorithm` and
`password`. `password`.
The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
recent OpenSSL releases, `openssl list-cipher-algorithms` will display the recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
available cipher algorithms. available cipher algorithms.
@ -841,7 +842,7 @@ rapidly.
In line with OpenSSL's recommendation to use pbkdf2 instead of In line with OpenSSL's recommendation to use pbkdf2 instead of
[`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on [`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on
their own using [`crypto.pbkdf2`][] and to use [`crypto.createCipheriv()`][] their own using [`crypto.pbkdf2()`][] and to use [`crypto.createCipheriv()`][]
to create the `Cipher` object. to create the `Cipher` object.
### crypto.createCipheriv(algorithm, key, iv) ### crypto.createCipheriv(algorithm, key, iv)
@ -849,13 +850,13 @@ to create the `Cipher` object.
Creates and returns a `Cipher` object, with the given `algorithm`, `key` and Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
initialization vector (`iv`). initialization vector (`iv`).
The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
recent OpenSSL releases, `openssl list-cipher-algorithms` will display the recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
available cipher algorithms. available cipher algorithms.
The `key` is the raw key used by the `algorithm` and `iv` is an The `key` is the raw key used by the `algorithm` and `iv` is an
[initialization vector][]. Both arguments must be `'binary'` encoded strings or [initialization vector][]. Both arguments must be `'binary'` encoded strings or
[buffers][]. [buffers][`Buffer`].
### crypto.createCredentials(details) ### crypto.createCredentials(details)
@ -896,7 +897,7 @@ rapidly.
In line with OpenSSL's recommendation to use pbkdf2 instead of In line with OpenSSL's recommendation to use pbkdf2 instead of
[`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on [`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on
their own using [`crypto.pbkdf2`][] and to use [`crypto.createDecipheriv()`][] their own using [`crypto.pbkdf2()`][] and to use [`crypto.createDecipheriv()`][]
to create the `Decipher` object. to create the `Decipher` object.
### crypto.createDecipheriv(algorithm, key, iv) ### crypto.createDecipheriv(algorithm, key, iv)
@ -904,13 +905,13 @@ to create the `Decipher` object.
Creates and returns a `Decipher` object that uses the given `algorithm`, `key` Creates and returns a `Decipher` object that uses the given `algorithm`, `key`
and initialization vector (`iv`). and initialization vector (`iv`).
The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
recent OpenSSL releases, `openssl list-cipher-algorithms` will display the recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
available cipher algorithms. available cipher algorithms.
The `key` is the raw key used by the `algorithm` and `iv` is an The `key` is the raw key used by the `algorithm` and `iv` is an
[initialization vector][]. Both arguments must be `'binary'` encoded strings or [initialization vector][]. Both arguments must be `'binary'` encoded strings or
[buffers][]. [buffers][`Buffer`].
### crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding]) ### crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding])
@ -1040,7 +1041,7 @@ console.log(curves); // ['secp256k1', 'secp384r1', ...]
### crypto.getDiffieHellman(group_name) ### crypto.getDiffieHellman(group_name)
Creates a predefined `DiffieHellman` key exchange object. The Creates a predefined `DiffieHellman` key exchange object. The
supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in
[RFC 2412][], but see [Caveats][]) and `'modp14'`, `'modp15'`, [RFC 2412][], but see [Caveats][]) and `'modp14'`, `'modp15'`,
`'modp16'`, `'modp17'`, `'modp18'` (defined in [RFC 3526][]). The `'modp16'`, `'modp17'`, `'modp18'` (defined in [RFC 3526][]). The
@ -1082,7 +1083,7 @@ console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
### crypto.pbkdf2(password, salt, iterations, keylen, digest, callback) ### crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)
Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2) Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2)
implementation. A selected HMAC digest algorithm specified by `digest` is implementation. A selected HMAC digest algorithm specified by `digest` is
applied to derive a key of the requested byte length (`keylen`) from the applied to derive a key of the requested byte length (`keylen`) from the
`password`, `salt` and `iterations`. `password`, `salt` and `iterations`.
@ -1114,7 +1115,7 @@ An array of supported digest functions can be retrieved using
### crypto.pbkdf2Sync(password, salt, iterations, keylen, digest) ### crypto.pbkdf2Sync(password, salt, iterations, keylen, digest)
Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2) Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2)
implementation. A selected HMAC digest algorithm specified by `digest` is implementation. A selected HMAC digest algorithm specified by `digest` is
applied to derive a key of the requested byte length (`keylen`) from the applied to derive a key of the requested byte length (`keylen`) from the
`password`, `salt` and `iterations`. `password`, `salt` and `iterations`.
@ -1284,26 +1285,26 @@ is a bit field taking one of or a mix of the following flags (defined in the
The Crypto module was added to Node.js 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 unified Stream API, and before there were [`Buffer`][] objects for handling
binary data. As such, the many of the `crypto` defined classes have methods not binary data. As such, the many of the `crypto` defined classes have methods not
typically found on other Node.js classes that implement the [streams][] typically found on other Node.js classes that implement the [streams][stream]
API (e.g. `update()`, `final()`, or `digest()`). Also, many methods accepted API (e.g. `update()`, `final()`, or `digest()`). Also, many methods accepted
and returned `'binary'` encoded strings by default rather than Buffers. This and returned `'binary'` encoded strings by default rather than Buffers. This
default was changed after Node.js v0.8 to use [`Buffer`][] objects by default default was changed after Node.js v0.8 to use [`Buffer`][] objects by default
instead. instead.
### Recent ECDH Changes ### Recent ECDH Changes
Usage of `ECDH` with non-dynamically generated key pairs has been simplified. Usage of `ECDH` with non-dynamically generated key pairs has been simplified.
Now, `ecdh.setPrivateKey()` can be called with a preselected private key and the Now, [`ecdh.setPrivateKey()`][] can be called with a preselected private key
associated public point (key) will be computed and stored in the object. and the associated public point (key) will be computed and stored in the object.
This allows code to only store and provide the private part of the EC key pair. This allows code to only store and provide the private part of the EC key pair.
`ecdh.setPrivateKey()` now also validates that the private key is valid for the [`ecdh.setPrivateKey()`][] now also validates that the private key is valid for
selected curve. the selected curve.
The `ecdh.setPublicKey()` method is now deprecated as its inclusion in the API The [`ecdh.setPublicKey()`][] method is now deprecated as its inclusion in the
is not useful. Either a previously stored private key should be set, which API is not useful. Either a previously stored private key should be set, which
automatically generates the associated public key, or `ecdh.generateKeys()` automatically generates the associated public key, or [`ecdh.generateKeys()`][]
should be called. The main drawback of using `ecdh.setPublicKey()` is that it should be called. The main drawback of using [`ecdh.setPublicKey()`][] is that
can be used to put the ECDH key pair into an inconsistent state. it can be used to put the ECDH key pair into an inconsistent state.
### Support for weak or compromised algorithms ### Support for weak or compromised algorithms
@ -1327,30 +1328,46 @@ Based on the recommendations of [NIST SP 800-131A][]:
See the reference for other recommendations and details. See the reference for other recommendations and details.
[HTML5's `keygen` element]: http://www.w3.org/TR/html5/forms.html#the-keygen-element
[OpenSSL's SPKAC implementation]: https://www.openssl.org/docs/apps/spkac.html
[`createCipher()`]: #crypto_crypto_createcipher_algorithm_password
[`createCipheriv()`]: #crypto_crypto_createcipheriv_algorithm_key_iv
[`createHash()`]: #crypto_crypto_createhash_algorithm
[`crypto.createDecipher`]: #crypto_crypto_createdecipher_algorithm_password
[`crypto.createDecipheriv`]: #crypto_crypto_createdecipheriv_algorithm_key_iv
[`crypto.createDiffieHellman()`]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_encoding
[`crypto.getHashes()`]: #crypto_crypto_gethashes
[`crypto.pbkdf2`]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
[`decipher.update`]: #crypto_decipher_update_data_input_encoding_output_encoding
[`diffieHellman.setPublicKey()`]: #crypto_diffiehellman_setpublickey_public_key_encoding
[`EVP_BytesToKey`]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html
[`getCurves()`]: #crypto_crypto_getcurves
[`tls.createSecureContext()`]: tls.html#tls_tls_createsecurecontext_details
[`Buffer`]: buffer.html [`Buffer`]: buffer.html
[buffers]: buffer.html [`cipher.final()`]: #crypto_cipher_final_output_encoding
[`cipher.update()`]: #crypto_cipher_update_data_input_encoding_output_encoding
[`crypto.createCipher()`]: #crypto_crypto_createcipher_algorithm_password
[`crypto.createCipheriv()`]: #crypto_crypto_createcipheriv_algorithm_key_iv
[`crypto.createDecipher()`]: #crypto_crypto_createdecipher_algorithm_password
[`crypto.createDecipheriv()`]: #crypto_crypto_createdecipheriv_algorithm_key_iv
[`crypto.createDiffieHellman()`]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_encoding
[`crypto.createECDH()`]: #crypto_crypto_createecdh_curve_name
[`crypto.createHash()`]: #crypto_crypto_createhash_algorithm
[`crypto.createHmac()`]: #crypto_crypto_createhmac_algorithm_key
[`crypto.createSign()`]: #crypto_crypto_createsign_algorithm
[`crypto.getCurves()`]: #crypto_crypto_getcurves
[`crypto.getHashes()`]: #crypto_crypto_gethashes
[`crypto.pbkdf2()`]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
[`decipher.final()`]: #crypto_decipher_final_output_encoding
[`decipher.update()`]: #crypto_decipher_update_data_input_encoding_output_encoding
[`diffieHellman.setPublicKey()`]: #crypto_diffiehellman_setpublickey_public_key_encoding
[`ecdh.generateKeys()`]: #crypto_ecdh_generatekeys_encoding_format
[`ecdh.setPrivateKey()`]: #crypto_ecdh_setprivatekey_private_key_encoding
[`ecdh.setPublicKey()`]: #crypto_ecdh_setpublickey_public_key_encoding
[`EVP_BytesToKey`]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html
[`hash.digest()`]: #crypto_hash_digest_encoding
[`hash.update()`]: #crypto_hash_update_data_input_encoding
[`hmac.digest()`]: #crypto_hmac_digest_encoding
[`hmac.update()`]: #crypto_hmac_update_data
[`sign.sign()`]: #crypto_sign_sign_private_key_output_format
[`sign.update()`]: #crypto_sign_update_data
[`tls.createSecureContext()`]: tls.html#tls_tls_createsecurecontext_details
[`verify.update()`]: #crypto_verifier_update_data
[`verify.verify()`]: #crypto_verifier_verify_object_signature_signature_format
[Caveats]: #crypto_support_for_weak_or_compromised_algorithms [Caveats]: #crypto_support_for_weak_or_compromised_algorithms
[HTML5's `keygen` element]: http://www.w3.org/TR/html5/forms.html#the-keygen-element
[initialization vector]: https://en.wikipedia.org/wiki/Initialization_vector [initialization vector]: https://en.wikipedia.org/wiki/Initialization_vector
[NIST SP 800-131A]: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar1.pdf [NIST SP 800-131A]: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar1.pdf
[NIST SP 800-132]: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf [NIST SP 800-132]: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf
[OpenSSL cipher list format]: https://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT
[OpenSSL's SPKAC implementation]: https://www.openssl.org/docs/apps/spkac.html
[publicly trusted list of CAs]: https://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
[RFC 2412]: https://www.rfc-editor.org/rfc/rfc2412.txt [RFC 2412]: https://www.rfc-editor.org/rfc/rfc2412.txt
[RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
[stream]: stream.html [stream]: stream.html
[streams]: stream.html [stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback
[OpenSSL cipher list format]: https://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT
[publicly trusted list of CAs]: https://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt