Browse Source

doc: improvements to crypto.markdown copy

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>
process-exit-stdio-flushing
Alexander Makarenko 9 years ago
committed by Roman Reiss
parent
commit
f0c06147b3
  1. 191
      doc/api/crypto.markdown

191
doc/api/crypto.markdown

@ -55,7 +55,7 @@ console.log(challenge.toString('utf8'));
// 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
`certificate.exportPublicKey()` returns the public key component in the
@ -70,7 +70,7 @@ console.log(publicKey);
// Prints the public key as <Buffer ...>
```
### Certificate.verifySpkac(spkac)
### certificate.verifySpkac(spkac)
Returns `true` if the given `spkac` data structure is valid, `false` otherwise.
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
data is written to produce encrypted data on the readable side, or
- Using the `cipher.update()` and `cipher.final()` methods to produce the
encrypted data.
- Using the [`cipher.update()`][] and [`cipher.final()`][] methods to produce
the encrypted data.
The `crypto.createCipher()` or `crypto.createCipheriv()` methods are used to
create `Cipher` instances. `Cipher` objects are not to be created directly
using the `new` keyword.
The [`crypto.createCipher()`][] or [`crypto.createCipheriv()`][] methods are
used to create `Cipher` instances. `Cipher` objects are not to be created
directly using the `new` keyword.
Example: Using `Cipher` objects as streams:
@ -130,7 +130,7 @@ const output = fs.createWriteStream('test.enc');
input.pipe(cipher).pipe(output);
```
Example: Using the `cipher.update()` and `cipher.final()` methods:
Example: Using the [`cipher.update()`][] and [`cipher.final()`][] methods:
```js
const crypto = require('crypto');
@ -155,7 +155,7 @@ once will result in an error being thrown.
### cipher.setAAD(buffer)
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.
### 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 `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)
@ -174,11 +174,11 @@ add padding to the input data to the appropriate block size. To disable the
default padding call `cipher.setAutoPadding(false)`.
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
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])
@ -194,8 +194,8 @@ is specified, a string using the specified encoding is returned. If no
`output_encoding` is provided, a [`Buffer`][] is returned.
The `cipher.update()` method can be called multiple times with new data until
`cipher.final()` is called. Calling `cipher.update()` after `cipher.final()`
will result in an error being thrown.
[`cipher.final()`][] is called. Calling `cipher.update()` after
[`cipher.final()`][] will result in an error being thrown.
## Class: Decipher
@ -204,11 +204,11 @@ used in one of two ways:
- As a [stream][] that is both readable and writable, where plain encrypted
data is written to produce unencrypted data on the readable side, or
- Using the `decipher.update()` and `decipher.final()` methods to produce the
unencrypted data.
- Using the [`decipher.update()`][] and [`decipher.final()`][] methods to
produce the unencrypted data.
The `crypto.createDecipher()` or `crypto.createDecipheriv()` methods are used
to create `Decipher` instances. `Decipher` objects are not to be created
The [`crypto.createDecipher()`][] or [`crypto.createDecipheriv()`][] methods are
used to create `Decipher` instances. `Decipher` objects are not to be created
directly using the `new` keyword.
Example: Using `Decipher` objects as streams:
@ -246,7 +246,7 @@ const output = fs.createWriteStream('test.js');
input.pipe(decipher).pipe(output);
```
Example: Using the `decipher.update()` and `decipher.final()` methods:
Example: Using the [`decipher.update()`][] and [`decipher.final()`][] methods:
```js
const crypto = require('crypto');
@ -272,7 +272,7 @@ than once will result in an error being thrown.
### decipher.setAAD(buffer)
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.
### decipher.setAuthTag(buffer)
@ -280,20 +280,20 @@ _additional authenticated data_ (AAD) input parameter.
When using an authenticated encryption mode (only `GCM` is currently
supported), the `decipher.setAuthTag()` method is used to pass in the
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
cipher text should be discarded due to failed authentication.
### decipher.setAutoPadding(auto_padding=true)
When data has been encrypted without standard block padding, calling
`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
multiple of the ciphers block size.
The `decipher.setAutoPadding()` method must be called before
`decipher.update()`.
[`decipher.update()`][].
### 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.
The `decipher.update()` method can be called multiple times with new data until
`decipher.final()` is called. Calling `decipher.update()` after
`decipher.final()` will result in an error being thrown.
[`decipher.final()`][] is called. Calling `decipher.update()` after
[`decipher.final()`][] will result in an error being thrown.
## Class: DiffieHellman
@ -318,7 +318,7 @@ The `DiffieHellman` class is a utility for creating Diffie-Hellman key
exchanges.
Instances of the `DiffieHellman` class can be created using the
`crypto.createDiffieHellman()` function.
[`crypto.createDiffieHellman()`][] function.
```js
const crypto = require('crypto');
@ -417,7 +417,7 @@ The `ECDH` class is a utility for creating Elliptic Curve Diffie-Hellman (ECDH)
key exchanges.
Instances of the `ECDH` class can be created using the
`crypto.createECDH()` function.
[`crypto.createECDH()`][] function.
```js
const crypto = require('crypto');
@ -439,7 +439,7 @@ assert(alice_secret, bob_secret);
// 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
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
[`Buffer`][] is returned.
### ECDH.generateKeys([encoding[, format]])
### 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
@ -465,13 +465,13 @@ The `encoding` argument can be `'binary'`, `'hex'`, or `'base64'`. If
`encoding` is provided a string is returned; otherwise a [`Buffer`][]
is returned.
### ECDH.getPrivateKey([encoding])
### ecdh.getPrivateKey([encoding])
Returns the EC Diffie-Hellman private key in the specified `encoding`,
which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided
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
`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
returned.
### ECDH.setPrivateKey(private_key[, encoding])
### ecdh.setPrivateKey(private_key[, encoding])
Sets the EC Diffie-Hellman private key. The `encoding` can be `'binary'`,
`'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
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
@ -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`
only requires a private key and the other party's public key to compute the
shared secret. Typically either `ecdh.generateKeys()` or `ecdh.setPrivateKey()`
will be called. The `ecdh.setPrivateKey()` method attempts to generate the
public point/key associated with the private key being set.
shared secret. Typically either [`ecdh.generateKeys()`][] or
[`ecdh.setPrivateKey()`][] will be called. The [`ecdh.setPrivateKey()`][] method
attempts to generate the public point/key associated with the private key being
set.
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
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.
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.
Example: Using `Hash` objects as streams:
@ -573,7 +574,7 @@ const input = fs.createReadStream('test.js');
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
const crypto = require('crypto');
@ -588,7 +589,7 @@ console.log(hash.digest('hex'));
### hash.digest([encoding])
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
a [`Buffer`][] is returned.
@ -612,10 +613,10 @@ be used in one of two ways:
- As a [stream][] that is both readable and writable, where data is written
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.
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.
Example: Using `Hmac` objects as streams:
@ -647,7 +648,7 @@ const input = fs.createReadStream('test.js');
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
const crypto = require('crypto');
@ -661,9 +662,9 @@ console.log(hmac.digest('hex'));
### hmac.digest([encoding])
Calculates the HMAC digest of all of the data passed using `hmac.update()`. The
`encoding` can be `'hex'`, `'binary'` or `'base64'`. If `encoding` is provided
a string is returned; otherwise a [`Buffer`][] is returned;
Calculates the HMAC digest of all of the data passed using [`hmac.update()`][].
The `encoding` can be `'hex'`, `'binary'` or `'base64'`. If `encoding` is
provided a string is returned; otherwise a [`Buffer`][] is returned;
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.
@ -679,11 +680,11 @@ The `Sign` Class is a utility for generating signatures. It can be used in one
of two ways:
- 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
- Using the `sign.update()` and `sign.sign()` methods to produce the
[`sign.sign()`][] method is used to generate and return the signature, or
- Using the [`sign.update()`][] and [`sign.sign()`][] methods to produce the
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.
Example: Using `Sign` objects as streams:
@ -700,7 +701,7 @@ console.log(sign.sign(private_key, 'hex'));
// Prints the calculated signature
```
Example: Using the `sign.update()` and `sign.sign()` methods:
Example: Using the [`sign.update()`][] and [`sign.sign()`][] methods:
```js
const crypto = require('crypto');
@ -716,7 +717,7 @@ console.log(sign.sign(private_key, 'hex'));
### sign.sign(private_key[, output_format])
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
string, it is treated as a raw key with no passphrase. If `private_key` is an
@ -744,11 +745,11 @@ of two ways:
- As a writable [stream][] where written data is used to validate against the
supplied signature, or
- Using the `verify.update()` and `verify.verify()` methods to verify the
signature.
- Using the [`verify.update()`][] and [`verify.verify()`][] methods to verify
the signature.
The `crypto.createSign()` method is used to create `Sign` instances. `Sign`
objects are not to be created directly using the `new` keyword.
The [`crypto.createSign()`][] method is used to create `Sign` instances.
`Sign` objects are not to be created directly using the `new` keyword.
Example: Using `Verify` objects as streams:
@ -765,7 +766,7 @@ console.log(sign.verify(public_key, signature));
// Prints true or false
```
Example: Using the `verify.update()` and `verify.verify()` methods:
Example: Using the [`verify.update()`][] and [`verify.verify()`][] methods:
```js
const crypto = require('crypto');
@ -806,8 +807,8 @@ thrown.
### crypto.DEFAULT_ENCODING
The default encoding to use for functions that can take either strings
or [buffers][]. The default value is `'buffer'`, which makes methods default
to [`Buffer`][] objects.
or [buffers][`Buffer`]. The default value is `'buffer'`, which makes methods
default to [`Buffer`][] objects.
The `crypto.DEFAULT_ENCODING` mechanism is provided for backwards compatibility
with legacy programs that expect `'binary'` to be the default encoding.
@ -841,7 +842,7 @@ rapidly.
In line with OpenSSL's recommendation to use pbkdf2 instead of
[`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.
### crypto.createCipheriv(algorithm, key, iv)
@ -855,7 +856,7 @@ available cipher algorithms.
The `key` is the raw key used by the `algorithm` and `iv` is an
[initialization vector][]. Both arguments must be `'binary'` encoded strings or
[buffers][].
[buffers][`Buffer`].
### crypto.createCredentials(details)
@ -896,7 +897,7 @@ rapidly.
In line with OpenSSL's recommendation to use pbkdf2 instead of
[`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.
### crypto.createDecipheriv(algorithm, key, iv)
@ -910,7 +911,7 @@ available cipher algorithms.
The `key` is the raw key used by the `algorithm` and `iv` is an
[initialization vector][]. Both arguments must be `'binary'` encoded strings or
[buffers][].
[buffers][`Buffer`].
### crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding])
@ -1284,7 +1285,7 @@ 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
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
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
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
@ -1293,17 +1294,17 @@ instead.
### Recent ECDH Changes
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
associated public point (key) will be computed and stored in the object.
Now, [`ecdh.setPrivateKey()`][] can be called with a preselected private key
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.
`ecdh.setPrivateKey()` now also validates that the private key is valid for the
selected curve.
[`ecdh.setPrivateKey()`][] now also validates that the private key is valid for
the selected curve.
The `ecdh.setPublicKey()` method is now deprecated as its inclusion in the API
is not useful. Either a previously stored private key should be set, which
automatically generates the associated public key, or `ecdh.generateKeys()`
should be called. The main drawback of using `ecdh.setPublicKey()` is that it
can be used to put the ECDH key pair into an inconsistent state.
The [`ecdh.setPublicKey()`][] method is now deprecated as its inclusion in the
API is not useful. Either a previously stored private key should be set, which
automatically generates the associated public key, or [`ecdh.generateKeys()`][]
should be called. The main drawback of using [`ecdh.setPublicKey()`][] is that
it can be used to put the ECDH key pair into an inconsistent state.
### 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.
[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
[`Buffer`]: 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.update`]: #crypto_decipher_update_data_input_encoding_output_encoding
[`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
[`getCurves()`]: #crypto_crypto_getcurves
[`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
[`Buffer`]: buffer.html
[buffers]: buffer.html
[`verify.update()`]: #crypto_verifier_update_data
[`verify.verify()`]: #crypto_verifier_verify_object_signature_signature_format
[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
[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
[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 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
[stream]: stream.html
[streams]: stream.html
[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
[stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback

Loading…
Cancel
Save