doc/api/crypto.markdown

   1 # Crypto
   2
   3     Stability: 2 - Stable
   4
   5 Use `require('crypto')` to access this module.
   6
   7 The crypto module offers a way of encapsulating secure credentials to be
   8 used as part of a secure HTTPS net or http connection.
   9
  10 It also offers a set of wrappers for OpenSSL's hash, hmac, cipher,
  11 decipher, sign and verify methods.
  12
  13
  14 ## crypto.setEngine(engine[, flags])
  15
  16 Load and set engine for some/all OpenSSL functions (selected by flags).
  17
  18 `engine` could be either an id or a path to the engine's shared library.
  19
  20 `flags` is optional and has `ENGINE_METHOD_ALL` value by default. It could take
  21 one of or mix of following flags (defined in `constants` module):
  22
  23 * `ENGINE_METHOD_RSA`
  24 * `ENGINE_METHOD_DSA`
  25 * `ENGINE_METHOD_DH`
  26 * `ENGINE_METHOD_RAND`
  27 * `ENGINE_METHOD_ECDH`
  28 * `ENGINE_METHOD_ECDSA`
  29 * `ENGINE_METHOD_CIPHERS`
  30 * `ENGINE_METHOD_DIGESTS`
  31 * `ENGINE_METHOD_STORE`
  32 * `ENGINE_METHOD_PKEY_METH`
  33 * `ENGINE_METHOD_PKEY_ASN1_METH`
  34 * `ENGINE_METHOD_ALL`
  35 * `ENGINE_METHOD_NONE`
  36
  37
  38 ## crypto.getCiphers()
  39
  40 Returns an array with the names of the supported ciphers.
  41
  42 Example:
  43
  44     var ciphers = crypto.getCiphers();
  45     console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
  46
  47
  48 ## crypto.getHashes()
  49
  50 Returns an array with the names of the supported hash algorithms.
  51
  52 Example:
  53
  54     var hashes = crypto.getHashes();
  55     console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
  56
  57
  58 ## crypto.getCurves()
  59
  60 Returns an array with the names of the supported elliptic curves.
  61
  62 Example:
  63
  64     var curves = crypto.getCurves();
  65     console.log(curves); // ['secp256k1', 'secp384r1', ...]
  66
  67
  68 ## crypto.createCredentials(details)
  69
  70     Stability: 0 - Deprecated: Use [tls.createSecureContext][] instead.
  71
  72 Creates a credentials object, with the optional details being a
  73 dictionary with keys:
  74
  75 * `pfx` : A string or buffer holding the PFX or PKCS12 encoded private
  76   key, certificate and CA certificates
  77 * `key` : A string holding the PEM encoded private key
  78 * `passphrase` : A string of passphrase for the private key or pfx
  79 * `cert` : A string holding the PEM encoded certificate
  80 * `ca` : Either a string or list of strings of PEM encoded CA
  81   certificates to trust.
  82 * `crl` : Either a string or list of strings of PEM encoded CRLs
  83   (Certificate Revocation List)
  84 * `ciphers`: A string describing the ciphers to use or exclude.
  85   Consult
  86   <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>
  87   for details on the format.
  88
  89 If no 'ca' details are given, then Node.js will use the default
  90 publicly trusted list of CAs as given in
  91 <http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
  92
  93
  94 ## crypto.createHash(algorithm)
  95
  96 Creates and returns a hash object, a cryptographic hash with the given
  97 algorithm which can be used to generate hash digests.
  98
  99 `algorithm` is dependent on the available algorithms supported by the
 100 version of OpenSSL on the platform. Examples are `'sha1'`, `'md5'`,
 101 `'sha256'`, `'sha512'`, etc.  On recent releases, `openssl
 102 list-message-digest-algorithms` will display the available digest
 103 algorithms.
 104
 105 Example: this program that takes the sha1 sum of a file
 106
 107     var filename = process.argv[2];
 108     var crypto = require('crypto');
 109     var fs = require('fs');
 110
 111     var shasum = crypto.createHash('sha1');
 112
 113     var s = fs.ReadStream(filename);
 114     s.on('data', function(d) {
 115       shasum.update(d);
 116     });
 117
 118     s.on('end', function() {
 119       var d = shasum.digest('hex');
 120       console.log(d + '  ' + filename);
 121     });
 122
 123 ## Class: Hash
 124
 125 The class for creating hash digests of data.
 126
 127 It is a [stream](stream.html) that is both readable and writable.  The
 128 written data is used to compute the hash.  Once the writable side of
 129 the stream is ended, use the `read()` method to get the computed hash
 130 digest.  The legacy `update` and `digest` methods are also supported.
 131
 132 Returned by `crypto.createHash`.
 133
 134 ### hash.update(data[, input_encoding])
 135
 136 Updates the hash content with the given `data`, the encoding of which
 137 is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
 138 `'binary'`.  If no encoding is provided, and the input is a string, an
 139 encoding of `'binary'` is enforced. If `data` is a `Buffer` then
 140 `input_encoding` is ignored.
 141
 142 This can be called many times with new data as it is streamed.
 143
 144 ### hash.digest([encoding])
 145
 146 Calculates the digest of all of the passed data to be hashed.  The
 147 `encoding` can be `'hex'`, `'binary'` or `'base64'`.  If no encoding
 148 is provided, then a buffer is returned.
 149
 150 Note: `hash` object can not be used after `digest()` method has been
 151 called.
 152
 153
 154 ## crypto.createHmac(algorithm, key)
 155
 156 Creates and returns a hmac object, a cryptographic hmac with the given
 157 algorithm and key.
 158
 159 It is a [stream](stream.html) that is both readable and writable.  The
 160 written data is used to compute the hmac.  Once the writable side of
 161 the stream is ended, use the `read()` method to get the computed
 162 digest.  The legacy `update` and `digest` methods are also supported.
 163
 164 `algorithm` is dependent on the available algorithms supported by
 165 OpenSSL - see createHash above.  `key` is the hmac key to be used.
 166
 167 ## Class: Hmac
 168
 169 Class for creating cryptographic hmac content.
 170
 171 Returned by `crypto.createHmac`.
 172
 173 ### hmac.update(data)
 174
 175 Update the hmac content with the given `data`.  This can be called
 176 many times with new data as it is streamed.
 177
 178 ### hmac.digest([encoding])
 179
 180 Calculates the digest of all of the passed data to the hmac.  The
 181 `encoding` can be `'hex'`, `'binary'` or `'base64'`.  If no encoding
 182 is provided, then a buffer is returned.
 183
 184 Note: `hmac` object can not be used after `digest()` method has been
 185 called.
 186
 187
 188 ## crypto.createCipher(algorithm, password)
 189
 190 Creates and returns a cipher object, with the given algorithm and
 191 password.
 192
 193 `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc.  On
 194 recent releases, `openssl list-cipher-algorithms` will display the
 195 available cipher algorithms.  `password` is used to derive key and IV,
 196 which must be a `'binary'` encoded string or a [buffer](buffer.html).
 197
 198 It is a [stream](stream.html) that is both readable and writable.  The
 199 written data is used to compute the hash.  Once the writable side of
 200 the stream is ended, use the `read()` method to get the enciphered
 201 contents.  The legacy `update` and `final` methods are also supported.
 202
 203 Note: `createCipher` derives keys with the OpenSSL function [EVP_BytesToKey][]
 204 with the digest algorithm set to MD5, one iteration, and no salt. The lack of
 205 salt allows dictionary attacks as the same password always creates the same key.
 206 The low iteration count and non-cryptographically secure hash algorithm allow
 207 passwords to be tested very rapidly.
 208
 209 In line with OpenSSL's recommendation to use pbkdf2 instead of EVP_BytesToKey it
 210 is recommended you derive a key and iv yourself with [crypto.pbkdf2][] and to
 211 then use [createCipheriv()][] to create the cipher stream.
 212
 213 ## crypto.createCipheriv(algorithm, key, iv)
 214
 215 Creates and returns a cipher object, with the given algorithm, key and
 216 iv.
 217
 218 `algorithm` is the same as the argument to `createCipher()`.  `key` is
 219 the raw key used by the algorithm.  `iv` is an [initialization
 220 vector](http://en.wikipedia.org/wiki/Initialization_vector).
 221
 222 `key` and `iv` must be `'binary'` encoded strings or
 223 [buffers](buffer.html).
 224
 225 ## Class: Cipher
 226
 227 Class for encrypting data.
 228
 229 Returned by `crypto.createCipher` and `crypto.createCipheriv`.
 230
 231 Cipher objects are [streams](stream.html) that are both readable and
 232 writable.  The written plain text data is used to produce the
 233 encrypted data on the readable side.  The legacy `update` and `final`
 234 methods are also supported.
 235
 236 ### cipher.update(data[, input_encoding][, output_encoding])
 237
 238 Updates the cipher with `data`, the encoding of which is given in
 239 `input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`.  If no
 240 encoding is provided, then a buffer is expected.
 241 If `data` is a `Buffer` then `input_encoding` is ignored.
 242
 243 The `output_encoding` specifies the output format of the enciphered
 244 data, and can be `'binary'`, `'base64'` or `'hex'`.  If no encoding is
 245 provided, then a buffer is returned.
 246
 247 Returns the enciphered contents, and can be called many times with new
 248 data as it is streamed.
 249
 250 ### cipher.final([output_encoding])
 251
 252 Returns any remaining enciphered contents, with `output_encoding`
 253 being one of: `'binary'`, `'base64'` or `'hex'`.  If no encoding is
 254 provided, then a buffer is returned.
 255
 256 Note: `cipher` object can not be used after `final()` method has been
 257 called.
 258
 259 ### cipher.setAutoPadding(auto_padding=true)
 260
 261 You can disable automatic padding of the input data to block size. If
 262 `auto_padding` is false, the length of the entire input data must be a
 263 multiple of the cipher's block size or `final` will fail.  Useful for
 264 non-standard padding, e.g. using `0x0` instead of PKCS padding. You
 265 must call this before `cipher.final`.
 266
 267 ### cipher.getAuthTag()
 268
 269 For authenticated encryption modes (currently supported: GCM), this
 270 method returns a `Buffer` that represents the _authentication tag_ that
 271 has been computed from the given data. Should be called after
 272 encryption has been completed using the `final` method!
 273
 274 ### cipher.setAAD(buffer)
 275
 276 For authenticated encryption modes (currently supported: GCM), this
 277 method sets the value used for the additional authenticated data (AAD) input
 278 parameter.
 279
 280
 281 ## crypto.createDecipher(algorithm, password)
 282
 283 Creates and returns a decipher object, with the given algorithm and
 284 key.  This is the mirror of the [createCipher()][] above.
 285
 286 ## crypto.createDecipheriv(algorithm, key, iv)
 287
 288 Creates and returns a decipher object, with the given algorithm, key
 289 and iv.  This is the mirror of the [createCipheriv()][] above.
 290
 291 ## Class: Decipher
 292
 293 Class for decrypting data.
 294
 295 Returned by `crypto.createDecipher` and `crypto.createDecipheriv`.
 296
 297 Decipher objects are [streams](stream.html) that are both readable and
 298 writable.  The written enciphered data is used to produce the
 299 plain-text data on the the readable side.  The legacy `update` and
 300 `final` methods are also supported.
 301
 302 ### decipher.update(data[, input_encoding][, output_encoding])
 303
 304 Updates the decipher with `data`, which is encoded in `'binary'`,
 305 `'base64'` or `'hex'`.  If no encoding is provided, then a buffer is
 306 expected.
 307 If `data` is a `Buffer` then `input_encoding` is ignored.
 308
 309 The `output_decoding` specifies in what format to return the
 310 deciphered plaintext: `'binary'`, `'ascii'` or `'utf8'`.  If no
 311 encoding is provided, then a buffer is returned.
 312
 313 ### decipher.final([output_encoding])
 314
 315 Returns any remaining plaintext which is deciphered, with
 316 `output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`.  If
 317 no encoding is provided, then a buffer is returned.
 318
 319 Note: `decipher` object can not be used after `final()` method has been
 320 called.
 321
 322 ### decipher.setAutoPadding(auto_padding=true)
 323
 324 You can disable auto padding if the data has been encrypted without
 325 standard block padding to prevent `decipher.final` from checking and
 326 removing it. This will only work if the input data's length is a multiple of
 327 the ciphers block size. You must call this before streaming data to
 328 `decipher.update`.
 329
 330 ### decipher.setAuthTag(buffer)
 331
 332 For authenticated encryption modes (currently supported: GCM), this
 333 method must be used to pass in the received _authentication tag_.
 334 If no tag is provided or if the ciphertext has been tampered with,
 335 `final` will throw, thus indicating that the ciphertext should
 336 be discarded due to failed authentication.
 337
 338 ### decipher.setAAD(buffer)
 339
 340 For authenticated encryption modes (currently supported: GCM), this
 341 method sets the value used for the additional authenticated data (AAD) input
 342 parameter.
 343
 344
 345 ## crypto.createSign(algorithm)
 346
 347 Creates and returns a signing object, with the given algorithm.  On
 348 recent OpenSSL releases, `openssl list-public-key-algorithms` will
 349 display the available signing algorithms. Examples are `'RSA-SHA256'`.
 350
 351 ## Class: Sign
 352
 353 Class for generating signatures.
 354
 355 Returned by `crypto.createSign`.
 356
 357 Sign objects are writable [streams](stream.html).  The written data is
 358 used to generate the signature.  Once all of the data has been
 359 written, the `sign` method will return the signature.  The legacy
 360 `update` method is also supported.
 361
 362 ### sign.update(data)
 363
 364 Updates the sign object with data.  This can be called many times
 365 with new data as it is streamed.
 366
 367 ### sign.sign(private_key[, output_format])
 368
 369 Calculates the signature on all the updated data passed through the
 370 sign.
 371
 372 `private_key` can be an object or a string. If `private_key` is a string, it is
 373 treated as the key with no passphrase.
 374
 375 `private_key`:
 376
 377 * `key` : A string holding the PEM encoded private key
 378 * `passphrase` : A string of passphrase for the private key
 379
 380 Returns the signature in `output_format` which can be `'binary'`,
 381 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 382 returned.
 383
 384 Note: `sign` object can not be used after `sign()` method has been
 385 called.
 386
 387 ## crypto.createVerify(algorithm)
 388
 389 Creates and returns a verification object, with the given algorithm.
 390 This is the mirror of the signing object above.
 391
 392 ## Class: Verify
 393
 394 Class for verifying signatures.
 395
 396 Returned by `crypto.createVerify`.
 397
 398 Verify objects are writable [streams](stream.html).  The written data
 399 is used to validate against the supplied signature.  Once all of the
 400 data has been written, the `verify` method will return true if the
 401 supplied signature is valid.  The legacy `update` method is also
 402 supported.
 403
 404 ### verifier.update(data)
 405
 406 Updates the verifier object with data.  This can be called many times
 407 with new data as it is streamed.
 408
 409 ### verifier.verify(object, signature[, signature_format])
 410
 411 Verifies the signed data by using the `object` and `signature`.
 412 `object` is  a string containing a PEM encoded object, which can be
 413 one of RSA public key, DSA public key, or X.509 certificate.
 414 `signature` is the previously calculated signature for the data, in
 415 the `signature_format` which can be `'binary'`, `'hex'` or `'base64'`.
 416 If no encoding is specified, then a buffer is expected.
 417
 418 Returns true or false depending on the validity of the signature for
 419 the data and public key.
 420
 421 Note: `verifier` object can not be used after `verify()` method has been
 422 called.
 423
 424 ## crypto.createDiffieHellman(prime_length[, generator])
 425
 426 Creates a Diffie-Hellman key exchange object and generates a prime of
 427 `prime_length` bits and using an optional specific numeric `generator`.
 428 If no `generator` is specified, then `2` is used.
 429
 430 ## crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding])
 431
 432 Creates a Diffie-Hellman key exchange object using the supplied `prime` and an
 433 optional specific `generator`.
 434 `generator` can be a number, string, or Buffer.
 435 If no `generator` is specified, then `2` is used.
 436 `prime_encoding` and `generator_encoding` can be `'binary'`, `'hex'`, or `'base64'`.
 437 If no `prime_encoding` is specified, then a Buffer is expected for `prime`.
 438 If no `generator_encoding` is specified, then a Buffer is expected for `generator`.
 439
 440 ## Class: DiffieHellman
 441
 442 The class for creating Diffie-Hellman key exchanges.
 443
 444 Returned by `crypto.createDiffieHellman`.
 445
 446 ### diffieHellman.verifyError
 447
 448 A bit field containing any warnings and/or errors as a result of a check performed
 449 during initialization. The following values are valid for this property
 450 (defined in `constants` module):
 451
 452 * `DH_CHECK_P_NOT_SAFE_PRIME`
 453 * `DH_CHECK_P_NOT_PRIME`
 454 * `DH_UNABLE_TO_CHECK_GENERATOR`
 455 * `DH_NOT_SUITABLE_GENERATOR`
 456
 457 ### diffieHellman.generateKeys([encoding])
 458
 459 Generates private and public Diffie-Hellman key values, and returns
 460 the public key in the specified encoding. This key should be
 461 transferred to the other party. Encoding can be `'binary'`, `'hex'`,
 462 or `'base64'`.  If no encoding is provided, then a buffer is returned.
 463
 464 ### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding])
 465
 466 Computes the shared secret using `other_public_key` as the other
 467 party's public key and returns the computed shared secret. Supplied
 468 key is interpreted using specified `input_encoding`, and secret is
 469 encoded using specified `output_encoding`. Encodings can be
 470 `'binary'`, `'hex'`, or `'base64'`. If the input encoding is not
 471 provided, then a buffer is expected.
 472
 473 If no output encoding is given, then a buffer is returned.
 474
 475 ### diffieHellman.getPrime([encoding])
 476
 477 Returns the Diffie-Hellman prime in the specified encoding, which can
 478 be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 479 then a buffer is returned.
 480
 481 ### diffieHellman.getGenerator([encoding])
 482
 483 Returns the Diffie-Hellman generator in the specified encoding, which can
 484 be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 485 then a buffer is returned.
 486
 487 ### diffieHellman.getPublicKey([encoding])
 488
 489 Returns the Diffie-Hellman public key in the specified encoding, which
 490 can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 491 then a buffer is returned.
 492
 493 ### diffieHellman.getPrivateKey([encoding])
 494
 495 Returns the Diffie-Hellman private key in the specified encoding,
 496 which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is
 497 provided, then a buffer is returned.
 498
 499 ### diffieHellman.setPublicKey(public_key[, encoding])
 500
 501 Sets the Diffie-Hellman public key. Key encoding can be `'binary'`,
 502 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 503 expected.
 504
 505 ### diffieHellman.setPrivateKey(private_key[, encoding])
 506
 507 Sets the Diffie-Hellman private key. Key encoding can be `'binary'`,
 508 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 509 expected.
 510
 511 ## crypto.getDiffieHellman(group_name)
 512
 513 Creates a predefined Diffie-Hellman key exchange object.  The
 514 supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in [RFC
 515 2412][]) and `'modp14'`, `'modp15'`, `'modp16'`, `'modp17'`,
 516 `'modp18'` (defined in [RFC 3526][]).  The returned object mimics the
 517 interface of objects created by [crypto.createDiffieHellman()][]
 518 above, but will not allow to change the keys (with
 519 [diffieHellman.setPublicKey()][] for example).  The advantage of using
 520 this routine is that the parties don't have to generate nor exchange
 521 group modulus beforehand, saving both processor and communication
 522 time.
 523
 524 Example (obtaining a shared secret):
 525
 526     var crypto = require('crypto');
 527     var alice = crypto.getDiffieHellman('modp5');
 528     var bob = crypto.getDiffieHellman('modp5');
 529
 530     alice.generateKeys();
 531     bob.generateKeys();
 532
 533     var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
 534     var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
 535
 536     /* alice_secret and bob_secret should be the same */
 537     console.log(alice_secret == bob_secret);
 538
 539 ## crypto.createECDH(curve_name)
 540
 541 Creates an Elliptic Curve (EC) Diffie-Hellman key exchange object using a
 542 predefined curve specified by the `curve_name` string. Use [getCurves()][] to
 543 obtain a list of available curve names. On recent releases,
 544 `openssl ecparam -list_curves` will also display the name and description of
 545 each available elliptic curve.
 546
 547 ## Class: ECDH
 548
 549 The class for creating EC Diffie-Hellman key exchanges.
 550
 551 Returned by `crypto.createECDH`.
 552
 553 ### ECDH.generateKeys([encoding[, format]])
 554
 555 Generates private and public EC Diffie-Hellman key values, and returns
 556 the public key in the specified format and encoding. This key should be
 557 transferred to the other party.
 558
 559 Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
 560 `'hybrid'`. If no format is provided - the point will be returned in
 561 `'uncompressed'` format.
 562
 563 Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 564 then a buffer is returned.
 565
 566 ### ECDH.computeSecret(other_public_key[, input_encoding][, output_encoding])
 567
 568 Computes the shared secret using `other_public_key` as the other
 569 party's public key and returns the computed shared secret. Supplied
 570 key is interpreted using specified `input_encoding`, and secret is
 571 encoded using specified `output_encoding`. Encodings can be
 572 `'binary'`, `'hex'`, or `'base64'`. If the input encoding is not
 573 provided, then a buffer is expected.
 574
 575 If no output encoding is given, then a buffer is returned.
 576
 577 ### ECDH.getPublicKey([encoding[, format]])
 578
 579 Returns the EC Diffie-Hellman public key in the specified encoding and format.
 580
 581 Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
 582 `'hybrid'`. If no format is provided - the point will be returned in
 583 `'uncompressed'` format.
 584
 585 Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 586 then a buffer is returned.
 587
 588 ### ECDH.getPrivateKey([encoding])
 589
 590 Returns the EC Diffie-Hellman private key in the specified encoding,
 591 which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is
 592 provided, then a buffer is returned.
 593
 594 ### ECDH.setPublicKey(public_key[, encoding])
 595
 596 Sets the EC Diffie-Hellman public key. Key encoding can be `'binary'`,
 597 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 598 expected.
 599
 600 ### ECDH.setPrivateKey(private_key[, encoding])
 601
 602 Sets the EC Diffie-Hellman private key. Key encoding can be `'binary'`,
 603 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 604 expected.
 605
 606 Example (obtaining a shared secret):
 607
 608     var crypto = require('crypto');
 609     var alice = crypto.createECDH('secp256k1');
 610     var bob = crypto.createECDH('secp256k1');
 611
 612     alice.generateKeys();
 613     bob.generateKeys();
 614
 615     var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
 616     var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
 617
 618     /* alice_secret and bob_secret should be the same */
 619     console.log(alice_secret == bob_secret);
 620
 621 ## crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback)
 622
 623 Asynchronous PBKDF2 function.  Applies the selected HMAC digest function
 624 (default: SHA1) to derive a key of the requested byte length from the password,
 625 salt and number of iterations.  The callback gets two arguments:
 626 `(err, derivedKey)`.
 627
 628 Example:
 629
 630     crypto.pbkdf2('secret', 'salt', 4096, 64, 'sha256', function(err, key) {
 631       if (err)
 632         throw err;
 633       console.log(key.toString('hex'));  // 'c5e478d...1469e50'
 634     });
 635
 636 You can get a list of supported digest functions with
 637 [crypto.getHashes()](#crypto_crypto_gethashes).
 638
 639 ## crypto.pbkdf2Sync(password, salt, iterations, keylen[, digest])
 640
 641 Synchronous PBKDF2 function.  Returns derivedKey or throws error.
 642
 643 ## crypto.randomBytes(size[, callback])
 644
 645 Generates cryptographically strong pseudo-random data. Usage:
 646
 647     // async
 648     crypto.randomBytes(256, function(ex, buf) {
 649       if (ex) throw ex;
 650       console.log('Have %d bytes of random data: %s', buf.length, buf);
 651     });
 652
 653     // sync
 654     const buf = crypto.randomBytes(256);
 655     console.log('Have %d bytes of random data: %s', buf.length, buf);
 656
 657 NOTE: This will block if there is insufficient entropy, although it should
 658 normally never take longer than a few milliseconds. The only time when this
 659 may conceivably block is right after boot, when the whole system is still
 660 low on entropy.
 661
 662 ## Class: Certificate
 663
 664 The class used for working with signed public key & challenges. The most
 665 common usage for this series of functions is when dealing with the `<keygen>`
 666 element. http://www.openssl.org/docs/apps/spkac.html
 667
 668 Returned by `crypto.Certificate`.
 669
 670 ### Certificate.verifySpkac(spkac)
 671
 672 Returns true of false based on the validity of the SPKAC.
 673
 674 ### Certificate.exportChallenge(spkac)
 675
 676 Exports the encoded public key from the supplied SPKAC.
 677
 678 ### Certificate.exportPublicKey(spkac)
 679
 680 Exports the encoded challenge associated with the SPKAC.
 681
 682 ## crypto.publicEncrypt(public_key, buffer)
 683
 684 Encrypts `buffer` with `public_key`. Only RSA is currently supported.
 685
 686 `public_key` can be an object or a string. If `public_key` is a string, it is
 687 treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
 688 Since RSA public keys may be derived from private keys you may pass a private
 689 key to this method.
 690
 691 `public_key`:
 692
 693 * `key` : A string holding the PEM encoded private key
 694 * `passphrase` : An optional string of passphrase for the private key
 695 * `padding` : An optional padding value, one of the following:
 696   * `constants.RSA_NO_PADDING`
 697   * `constants.RSA_PKCS1_PADDING`
 698   * `constants.RSA_PKCS1_OAEP_PADDING`
 699
 700 NOTE: All paddings are defined in `constants` module.
 701
 702 ## crypto.publicDecrypt(public_key, buffer)
 703
 704 See above for details. Has the same API as `crypto.publicEncrypt`. Default
 705 padding is `RSA_PKCS1_PADDING`.
 706
 707 ## crypto.privateDecrypt(private_key, buffer)
 708
 709 Decrypts `buffer` with `private_key`.
 710
 711 `private_key` can be an object or a string. If `private_key` is a string, it is
 712 treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
 713
 714 `private_key`:
 715
 716 * `key` : A string holding the PEM encoded private key
 717 * `passphrase` : An optional string of passphrase for the private key
 718 * `padding` : An optional padding value, one of the following:
 719   * `constants.RSA_NO_PADDING`
 720   * `constants.RSA_PKCS1_PADDING`
 721   * `constants.RSA_PKCS1_OAEP_PADDING`
 722
 723 NOTE: All paddings are defined in `constants` module.
 724
 725 ## crypto.privateEncrypt(private_key, buffer)
 726
 727 See above for details. Has the same API as `crypto.privateDecrypt`.
 728 Default padding is `RSA_PKCS1_PADDING`.
 729
 730 ## crypto.DEFAULT_ENCODING
 731
 732 The default encoding to use for functions that can take either strings
 733 or buffers.  The default value is `'buffer'`, which makes it default
 734 to using Buffer objects.  This is here to make the crypto module more
 735 easily compatible with legacy programs that expected `'binary'` to be
 736 the default encoding.
 737
 738 Note that new programs will probably expect buffers, so only use this
 739 as a temporary measure.
 740
 741 ## Recent API Changes
 742
 743 The Crypto module was added to Node.js before there was the concept of a
 744 unified Stream API, and before there were Buffer objects for handling
 745 binary data.
 746
 747 As such, the streaming classes don't have the typical methods found on
 748 other Node.js classes, and many methods accepted and returned
 749 Binary-encoded strings by default rather than Buffers.  This was
 750 changed to use Buffers by default instead.
 751
 752 This is a breaking change for some use cases, but not all.
 753
 754 For example, if you currently use the default arguments to the Sign
 755 class, and then pass the results to the Verify class, without ever
 756 inspecting the data, then it will continue to work as before.  Where
 757 you once got a binary string and then presented the binary string to
 758 the Verify object, you'll now get a Buffer, and present the Buffer to
 759 the Verify object.
 760
 761 However, if you were doing things with the string data that will not
 762 work properly on Buffers (such as, concatenating them, storing in
 763 databases, etc.), or you are passing binary strings to the crypto
 764 functions without an encoding argument, then you will need to start
 765 providing encoding arguments to specify which encoding you'd like to
 766 use.  To switch to the previous style of using binary strings by
 767 default, set the `crypto.DEFAULT_ENCODING` field to 'binary'.  Note
 768 that new programs will probably expect buffers, so only use this as a
 769 temporary measure.
 770
 771
 772 [createCipher()]: #crypto_crypto_createcipher_algorithm_password
 773 [createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv
 774 [getCurves()]: #crypto_crypto_getcurves
 775 [crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_encoding
 776 [tls.createSecureContext]: tls.html#tls_tls_createsecurecontext_details
 777 [diffieHellman.setPublicKey()]: #crypto_diffiehellman_setpublickey_public_key_encoding
 778 [RFC 2412]: http://www.rfc-editor.org/rfc/rfc2412.txt
 779 [RFC 3526]: http://www.rfc-editor.org/rfc/rfc3526.txt
 780 [crypto.pbkdf2]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
 781 [EVP_BytesToKey]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html