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