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