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 io.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. Can 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. On recent releases,
 543 `openssl ecparam -list_curves` will display the name and description of each
 544 available elliptic curve.
 545
 546 ## Class: ECDH
 547
 548 The class for creating EC Diffie-Hellman key exchanges.
 549
 550 Returned by `crypto.createECDH`.
 551
 552 ### ECDH.generateKeys([encoding[, format]])
 553
 554 Generates private and public EC Diffie-Hellman key values, and returns
 555 the public key in the specified format and encoding. This key should be
 556 transferred to the other party.
 557
 558 Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
 559 `'hybrid'`. If no format is provided - the point will be returned in
 560 `'uncompressed'` format.
 561
 562 Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 563 then a buffer is returned.
 564
 565 ### ECDH.computeSecret(other_public_key[, input_encoding][, output_encoding])
 566
 567 Computes the shared secret using `other_public_key` as the other
 568 party's public key and returns the computed shared secret. Supplied
 569 key is interpreted using specified `input_encoding`, and secret is
 570 encoded using specified `output_encoding`. Encodings can be
 571 `'binary'`, `'hex'`, or `'base64'`. If the input encoding is not
 572 provided, then a buffer is expected.
 573
 574 If no output encoding is given, then a buffer is returned.
 575
 576 ### ECDH.getPublicKey([encoding[, format]])
 577
 578 Returns the EC Diffie-Hellman public key in the specified encoding and format.
 579
 580 Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
 581 `'hybrid'`. If no format is provided - the point will be returned in
 582 `'uncompressed'` format.
 583
 584 Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 585 then a buffer is returned.
 586
 587 ### ECDH.getPrivateKey([encoding])
 588
 589 Returns the EC Diffie-Hellman private key in the specified encoding,
 590 which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is
 591 provided, then a buffer is returned.
 592
 593 ### ECDH.setPublicKey(public_key[, encoding])
 594
 595 Sets the EC Diffie-Hellman public key. Key encoding can be `'binary'`,
 596 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 597 expected.
 598
 599 ### ECDH.setPrivateKey(private_key[, encoding])
 600
 601 Sets the EC Diffie-Hellman private key. Key encoding can be `'binary'`,
 602 `'hex'` or `'base64'`. If no encoding is provided, then a buffer is
 603 expected.
 604
 605 Example (obtaining a shared secret):
 606
 607     var crypto = require('crypto');
 608     var alice = crypto.createECDH('secp256k1');
 609     var bob = crypto.createECDH('secp256k1');
 610
 611     alice.generateKeys();
 612     bob.generateKeys();
 613
 614     var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
 615     var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
 616
 617     /* alice_secret and bob_secret should be the same */
 618     console.log(alice_secret == bob_secret);
 619
 620 ## crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback)
 621
 622 Asynchronous PBKDF2 function.  Applies the selected HMAC digest function
 623 (default: SHA1) to derive a key of the requested length from the password,
 624 salt and number of iterations.  The callback gets two arguments:
 625 `(err, derivedKey)`.
 626
 627 Example:
 628
 629     crypto.pbkdf2('secret', 'salt', 4096, 512, 'sha256', function(err, key) {
 630       if (err)
 631         throw err;
 632       console.log(key.toString('hex'));  // 'c5e478d...1469e50'
 633     });
 634
 635 You can get a list of supported digest functions with
 636 [crypto.getHashes()](#crypto_crypto_gethashes).
 637
 638 ## crypto.pbkdf2Sync(password, salt, iterations, keylen[, digest])
 639
 640 Synchronous PBKDF2 function.  Returns derivedKey or throws error.
 641
 642 ## crypto.randomBytes(size[, callback])
 643
 644 Generates cryptographically strong pseudo-random data. Usage:
 645
 646     // async
 647     crypto.randomBytes(256, function(ex, buf) {
 648       if (ex) throw ex;
 649       console.log('Have %d bytes of random data: %s', buf.length, buf);
 650     });
 651
 652     // sync
 653     try {
 654       var buf = crypto.randomBytes(256);
 655       console.log('Have %d bytes of random data: %s', buf.length, buf);
 656     } catch (ex) {
 657       // handle error
 658       // most likely, entropy sources are drained
 659     }
 660
 661 NOTE: This will block if there is insufficient entropy, although it should
 662 normally never take longer than a few milliseconds. The only time when this
 663 may conceivably block is right after boot, when the whole system is still
 664 low on entropy.
 665
 666 ## Class: Certificate
 667
 668 The class used for working with signed public key & challenges. The most
 669 common usage for this series of functions is when dealing with the `<keygen>`
 670 element. http://www.openssl.org/docs/apps/spkac.html
 671
 672 Returned by `crypto.Certificate`.
 673
 674 ### Certificate.verifySpkac(spkac)
 675
 676 Returns true of false based on the validity of the SPKAC.
 677
 678 ### Certificate.exportChallenge(spkac)
 679
 680 Exports the encoded public key from the supplied SPKAC.
 681
 682 ### Certificate.exportPublicKey(spkac)
 683
 684 Exports the encoded challenge associated with the SPKAC.
 685
 686 ## crypto.publicEncrypt(public_key, buffer)
 687
 688 Encrypts `buffer` with `public_key`. Only RSA is currently supported.
 689
 690 `public_key` can be an object or a string. If `public_key` is a string, it is
 691 treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
 692 Since RSA public keys may be derived from private keys you may pass a private
 693 key to this method.
 694
 695 `public_key`:
 696
 697 * `key` : A string holding the PEM encoded private key
 698 * `passphrase` : An optional string of passphrase for the private key
 699 * `padding` : An optional padding value, one of the following:
 700   * `constants.RSA_NO_PADDING`
 701   * `constants.RSA_PKCS1_PADDING`
 702   * `constants.RSA_PKCS1_OAEP_PADDING`
 703
 704 NOTE: All paddings are defined in `constants` module.
 705
 706 ## crypto.publicDecrypt(public_key, buffer)
 707
 708 See above for details. Has the same API as `crypto.publicEncrypt`. Default
 709 padding is `RSA_PKCS1_PADDING`.
 710
 711 ## crypto.privateDecrypt(private_key, buffer)
 712
 713 Decrypts `buffer` with `private_key`.
 714
 715 `private_key` can be an object or a string. If `private_key` is a string, it is
 716 treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
 717
 718 `private_key`:
 719
 720 * `key` : A string holding the PEM encoded private key
 721 * `passphrase` : An optional string of passphrase for the private key
 722 * `padding` : An optional padding value, one of the following:
 723   * `constants.RSA_NO_PADDING`
 724   * `constants.RSA_PKCS1_PADDING`
 725   * `constants.RSA_PKCS1_OAEP_PADDING`
 726
 727 NOTE: All paddings are defined in `constants` module.
 728
 729 ## crypto.privateEncrypt(private_key, buffer)
 730
 731 See above for details. Has the same API as `crypto.privateDecrypt`.
 732 Default padding is `RSA_PKCS1_PADDING`.
 733
 734 ## crypto.DEFAULT_ENCODING
 735
 736 The default encoding to use for functions that can take either strings
 737 or buffers.  The default value is `'buffer'`, which makes it default
 738 to using Buffer objects.  This is here to make the crypto module more
 739 easily compatible with legacy programs that expected `'binary'` to be
 740 the default encoding.
 741
 742 Note that new programs will probably expect buffers, so only use this
 743 as a temporary measure.
 744
 745 ## Recent API Changes
 746
 747 The Crypto module was added to Node.js before there was the concept of a
 748 unified Stream API, and before there were Buffer objects for handling
 749 binary data.
 750
 751 As such, the streaming classes don't have the typical methods found on
 752 other io.js classes, and many methods accepted and returned
 753 Binary-encoded strings by default rather than Buffers.  This was
 754 changed to use Buffers by default instead.
 755
 756 This is a breaking change for some use cases, but not all.
 757
 758 For example, if you currently use the default arguments to the Sign
 759 class, and then pass the results to the Verify class, without ever
 760 inspecting the data, then it will continue to work as before.  Where
 761 you once got a binary string and then presented the binary string to
 762 the Verify object, you'll now get a Buffer, and present the Buffer to
 763 the Verify object.
 764
 765 However, if you were doing things with the string data that will not
 766 work properly on Buffers (such as, concatenating them, storing in
 767 databases, etc.), or you are passing binary strings to the crypto
 768 functions without an encoding argument, then you will need to start
 769 providing encoding arguments to specify which encoding you'd like to
 770 use.  To switch to the previous style of using binary strings by
 771 default, set the `crypto.DEFAULT_ENCODING` field to 'binary'.  Note
 772 that new programs will probably expect buffers, so only use this as a
 773 temporary measure.
 774
 775
 776 [createCipher()]: #crypto_crypto_createcipher_algorithm_password
 777 [createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv
 778 [crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_encoding
 779 [tls.createSecureContext]: tls.html#tls_tls_createsecurecontext_details
 780 [diffieHellman.setPublicKey()]: #crypto_diffiehellman_setpublickey_public_key_encoding
 781 [RFC 2412]: http://www.rfc-editor.org/rfc/rfc2412.txt
 782 [RFC 3526]: http://www.rfc-editor.org/rfc/rfc3526.txt
 783 [crypto.pbkdf2]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
 784 [EVP_BytesToKey]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html