doc: show keylen in pbkdf2 as a byte length

[platform/upstream/nodejs.git] / doc / api / crypto.markdown

diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown
index df5f28e..04d7af6 100644 (file)
--- a/doc/api/crypto.markdown
+++ b/doc/api/crypto.markdown
@@ -42,7 +42,7 @@ 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', ...]
+    console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
 
 
 ## crypto.getHashes()
@@ -55,9 +55,19 @@ Example:
     console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
 
 
+## crypto.getCurves()
+
+Returns an array with the names of the supported elliptic curves.
+
+Example:
+
+    var curves = crypto.getCurves();
+    console.log(curves); // ['secp256k1', 'secp384r1', ...]
+
+
 ## crypto.createCredentials(details)
 
-    Stability: 0 - Deprecated. Use [tls.createSecureContext][] instead.
+    Stability: 0 - Deprecated: Use [tls.createSecureContext][] instead.
 
 Creates a credentials object, with the optional details being a
 dictionary with keys:
@@ -76,7 +86,7 @@ dictionary with keys:
   <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>
   for details on the format.
 
-If no 'ca' details are given, then io.js will use the default
+If no 'ca' details are given, then Node.js will use the default
 publicly trusted list of CAs as given in
 <http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
 
@@ -125,7 +135,7 @@ Returned by `crypto.createHash`.
 
 Updates the hash content with the given `data`, the encoding of which
 is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
-`'binary'`.  If no encoding is provided and the input is a string an
+`'binary'`.  If no encoding is provided, and the input is a string, an
 encoding of `'binary'` is enforced. If `data` is a `Buffer` then
 `input_encoding` is ignored.
 
@@ -313,7 +323,7 @@ called.
 
 You can disable auto padding if the data has been encrypted without
 standard block padding to prevent `decipher.final` from checking and
-removing it. Can only work if the input data's length is a multiple of
+removing it. This will only work if the input data's length is a multiple of
 the ciphers block size. You must call this before streaming data to
 `decipher.update`.
 
@@ -529,9 +539,10 @@ Example (obtaining a shared 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. On recent releases,
-`openssl ecparam -list_curves` will display the name and description of each
-available elliptic curve.
+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
 
@@ -610,13 +621,13 @@ Example (obtaining a shared secret):
 ## crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback)
 
 Asynchronous PBKDF2 function.  Applies the selected HMAC digest function
-(default: SHA1) to derive a key of the requested length from the password,
+(default: SHA1) to derive a key of the requested byte length from the password,
 salt and number of iterations.  The callback gets two arguments:
 `(err, derivedKey)`.
 
 Example:
 
-    crypto.pbkdf2('secret', 'salt', 4096, 512, 'sha256', function(err, key) {
+    crypto.pbkdf2('secret', 'salt', 4096, 64, 'sha256', function(err, key) {
       if (err)
         throw err;
       console.log(key.toString('hex'));  // 'c5e478d...1469e50'
@@ -640,13 +651,8 @@ Generates cryptographically strong pseudo-random data. Usage:
     });
 
     // sync
-    try {
-      var buf = crypto.randomBytes(256);
-      console.log('Have %d bytes of random data: %s', buf.length, buf);
-    } catch (ex) {
-      // handle error
-      // most likely, entropy sources are drained
-    }
+    const buf = crypto.randomBytes(256);
+    console.log('Have %d bytes of random data: %s', buf.length, buf);
 
 NOTE: This will block if there is insufficient entropy, although it should
 normally never take longer than a few milliseconds. The only time when this
@@ -739,7 +745,7 @@ 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 io.js classes, and many methods accepted and returned
+other Node.js classes, and many methods accepted and returned
 Binary-encoded strings by default rather than Buffers.  This was
 changed to use Buffers by default instead.
 
@@ -765,6 +771,7 @@ temporary measure.
 
 [createCipher()]: #crypto_crypto_createcipher_algorithm_password
 [createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv
+[getCurves()]: #crypto_crypto_getcurves
 [crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_encoding
 [tls.createSecureContext]: tls.html#tls_tls_createsecurecontext_details
 [diffieHellman.setPublicKey()]: #crypto_diffiehellman_setpublickey_public_key_encoding