doc/api/crypto.markdown

   1 # Crypto
   2
   3     Stability: 2 - Stable
   4
   5 The `crypto` module provides cryptographic functionality that includes a set of
   6 wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign and verify functions.
   7
   8 Use `require('crypto')` to access this module.
   9
  10 ```js
  11 const crypto = require('crypto');
  12
  13 const secret = 'abcdefg';
  14 const hash = crypto.createHmac('sha256', secret)
  15                    .update('I love cupcakes')
  16                    .digest('hex');
  17 console.log(hash);
  18   // Prints:
  19   //   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e
  20 ```
  21
  22 ## Class: Certificate
  23
  24 SPKAC is a Certificate Signing Request mechanism originally implemented by
  25 Netscape and now specified formally as part of [HTML5's `keygen` element][].
  26
  27 The `crypto` module provides the `Certificate` class for working with SPKAC
  28 data. The most common usage is handling output generated by the HTML5
  29 `<keygen>` element. Node.js uses [OpenSSL's SPKAC implementation][] internally.
  30
  31 ### new crypto.Certificate()
  32
  33 Instances of the `Certificate` class can be created using the `new` keyword
  34 or by calling `crypto.Certificate()` as a function:
  35
  36 ```js
  37 const crypto = require('crypto');
  38
  39 const cert1 = new crypto.Certificate();
  40 const cert2 = crypto.Certificate();
  41 ```
  42
  43 ### certificate.exportChallenge(spkac)
  44
  45 The `spkac` data structure includes a public key and a challenge. The
  46 `certificate.exportChallenge()` returns the challenge component in the
  47 form of a Node.js [`Buffer`][]. The `spkac` argument can be either a string
  48 or a [`Buffer`][].
  49
  50 ```js
  51 const cert = require('crypto').Certificate();
  52 const spkac = getSpkacSomehow();
  53 const challenge = cert.exportChallenge(spkac);
  54 console.log(challenge.toString('utf8'));
  55   // Prints the challenge as a UTF8 string
  56 ```
  57
  58 ### certificate.exportPublicKey(spkac)
  59
  60 The `spkac` data structure includes a public key and a challenge. The
  61 `certificate.exportPublicKey()` returns the public key component in the
  62 form of a Node.js [`Buffer`][]. The `spkac` argument can be either a string
  63 or a [`Buffer`][].
  64
  65 ```js
  66 const cert = require('crypto').Certificate();
  67 const spkac = getSpkacSomehow();
  68 const publicKey = cert.exportPublicKey(spkac);
  69 console.log(publicKey);
  70   // Prints the public key as <Buffer ...>
  71 ```
  72
  73 ### certificate.verifySpkac(spkac)
  74
  75 Returns `true` if the given `spkac` data structure is valid, `false` otherwise.
  76 The `spkac` argument must be a Node.js [`Buffer`][].
  77
  78 ```js
  79 const cert = require('crypto').Certificate();
  80 const spkac = getSpkacSomehow();
  81 console.log(cert.verifySpkac(new Buffer(spkac)));
  82   // Prints true or false
  83 ```
  84
  85 ## Class: Cipher
  86
  87 Instances of the `Cipher` class are used to encrypt data. The class can be
  88 used in one of two ways:
  89
  90 - As a [stream][] that is both readable and writable, where plain unencrypted
  91   data is written to produce encrypted data on the readable side, or
  92 - Using the [`cipher.update()`][] and [`cipher.final()`][] methods to produce
  93   the encrypted data.
  94
  95 The [`crypto.createCipher()`][] or [`crypto.createCipheriv()`][] methods are
  96 used to create `Cipher` instances. `Cipher` objects are not to be created
  97 directly using the `new` keyword.
  98
  99 Example: Using `Cipher` objects as streams:
 100
 101 ```js
 102 const crypto = require('crypto');
 103 const cipher = crypto.createCipher('aes192', 'a password');
 104
 105 var encrypted = '';
 106 cipher.on('readable', () => {
 107   var data = cipher.read();
 108   if (data)
 109     encrypted += data.toString('hex');
 110 });
 111 cipher.on('end', () => {
 112   console.log(encrypted);
 113   // Prints: ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504
 114 });
 115
 116 cipher.write('some clear text data');
 117 cipher.end();
 118 ```
 119
 120 Example: Using `Cipher` and piped streams:
 121
 122 ```js
 123 const crypto = require('crypto');
 124 const fs = require('fs');
 125 const cipher = crypto.createCipher('aes192', 'a password');
 126
 127 const input = fs.createReadStream('test.js');
 128 const output = fs.createWriteStream('test.enc');
 129
 130 input.pipe(cipher).pipe(output);
 131 ```
 132
 133 Example: Using the [`cipher.update()`][] and [`cipher.final()`][] methods:
 134
 135 ```js
 136 const crypto = require('crypto');
 137 const cipher = crypto.createCipher('aes192', 'a password');
 138
 139 var encrypted = cipher.update('some clear text data', 'utf8', 'hex');
 140 encrypted += cipher.final('hex');
 141 console.log(encrypted);
 142   // Prints: ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504
 143 ```
 144
 145 ### cipher.final([output_encoding])
 146
 147 Returns any remaining enciphered contents. If `output_encoding`
 148 parameter is one of `'binary'`, `'base64'` or `'hex'`, a string is returned.
 149 If an `output_encoding` is not provided, a [`Buffer`][] is returned.
 150
 151 Once the `cipher.final()` method has been called, the `Cipher` object can no
 152 longer be used to encrypt data. Attempts to call `cipher.final()` more than
 153 once will result in an error being thrown.
 154
 155 ### cipher.setAAD(buffer)
 156
 157 When using an authenticated encryption mode (only `GCM` is currently
 158 supported), the `cipher.setAAD()` method sets the value used for the
 159 _additional authenticated data_ (AAD) input parameter.
 160
 161 ### cipher.getAuthTag()
 162
 163 When using an authenticated encryption mode (only `GCM` is currently
 164 supported), the `cipher.getAuthTag()` method returns a [`Buffer`][] containing
 165 the _authentication tag_ that has been computed from the given data.
 166
 167 The `cipher.getAuthTag()` method should only be called after encryption has
 168 been completed using the [`cipher.final()`][] method.
 169
 170 ### cipher.setAutoPadding(auto_padding=true)
 171
 172 When using block encryption algorithms, the `Cipher` class will automatically
 173 add padding to the input data to the appropriate block size. To disable the
 174 default padding call `cipher.setAutoPadding(false)`.
 175
 176 When `auto_padding` is `false`, the length of the entire input data must be a
 177 multiple of the cipher's block size or [`cipher.final()`][] will throw an Error.
 178 Disabling automatic padding is useful for non-standard padding, for instance
 179 using `0x0` instead of PKCS padding.
 180
 181 The `cipher.setAutoPadding()` method must be called before [`cipher.final()`][].
 182
 183 ### cipher.update(data[, input_encoding][, output_encoding])
 184
 185 Updates the cipher with `data`. If the `input_encoding` argument is given,
 186 it's value must be one of `'utf8'`, `'ascii'`, or `'binary'` and the `data`
 187 argument is a string using the specified encoding. If the `input_encoding`
 188 argument is not given, `data` must be a [`Buffer`][]. If `data` is a
 189 [`Buffer`][] then `input_encoding` is ignored.
 190
 191 The `output_encoding` specifies the output format of the enciphered
 192 data, and can be `'binary'`, `'base64'` or `'hex'`. If the `output_encoding`
 193 is specified, a string using the specified encoding is returned. If no
 194 `output_encoding` is provided, a [`Buffer`][] is returned.
 195
 196 The `cipher.update()` method can be called multiple times with new data until
 197 [`cipher.final()`][] is called. Calling `cipher.update()` after
 198 [`cipher.final()`][] will result in an error being thrown.
 199
 200 ## Class: Decipher
 201
 202 Instances of the `Decipher` class are used to decrypt data. The class can be
 203 used in one of two ways:
 204
 205 - As a [stream][] that is both readable and writable, where plain encrypted
 206   data is written to produce unencrypted data on the readable side, or
 207 - Using the [`decipher.update()`][] and [`decipher.final()`][] methods to
 208   produce the unencrypted data.
 209
 210 The [`crypto.createDecipher()`][] or [`crypto.createDecipheriv()`][] methods are
 211 used to create `Decipher` instances. `Decipher` objects are not to be created
 212 directly using the `new` keyword.
 213
 214 Example: Using `Decipher` objects as streams:
 215
 216 ```js
 217 const crypto = require('crypto');
 218 const decipher = crypto.createDecipher('aes192', 'a password');
 219
 220 var decrypted = '';
 221 decipher.on('readable', () => {
 222   var data = decipher.read();
 223   if (data)
 224   decrypted += data.toString('utf8');
 225 });
 226 decipher.on('end', () => {
 227   console.log(decrypted);
 228   // Prints: some clear text data
 229 });
 230
 231 var encrypted = 'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
 232 decipher.write(encrypted, 'hex');
 233 decipher.end();
 234 ```
 235
 236 Example: Using `Decipher` and piped streams:
 237
 238 ```js
 239 const crypto = require('crypto');
 240 const fs = require('fs');
 241 const decipher = crypto.createDecipher('aes192', 'a password');
 242
 243 const input = fs.createReadStream('test.enc');
 244 const output = fs.createWriteStream('test.js');
 245
 246 input.pipe(decipher).pipe(output);
 247 ```
 248
 249 Example: Using the [`decipher.update()`][] and [`decipher.final()`][] methods:
 250
 251 ```js
 252 const crypto = require('crypto');
 253 const decipher = crypto.createDecipher('aes192', 'a password');
 254
 255 var encrypted = 'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
 256 var decrypted = decipher.update(encrypted, 'hex', 'utf8');
 257 decrypted += decipher.final('utf8');
 258 console.log(decrypted);
 259   // Prints: some clear text data
 260 ```
 261
 262 ### decipher.final([output_encoding])
 263
 264 Returns any remaining deciphered contents. If `output_encoding`
 265 parameter is one of `'binary'`, `'base64'` or `'hex'`, a string is returned.
 266 If an `output_encoding` is not provided, a [`Buffer`][] is returned.
 267
 268 Once the `decipher.final()` method has been called, the `Decipher` object can
 269 no longer be used to decrypt data. Attempts to call `decipher.final()` more
 270 than once will result in an error being thrown.
 271
 272 ### decipher.setAAD(buffer)
 273
 274 When using an authenticated encryption mode (only `GCM` is currently
 275 supported), the `cipher.setAAD()` method sets the value used for the
 276 _additional authenticated data_ (AAD) input parameter.
 277
 278 ### decipher.setAuthTag(buffer)
 279
 280 When using an authenticated encryption mode (only `GCM` is currently
 281 supported), the `decipher.setAuthTag()` method is used to pass in the
 282 received _authentication tag_. If no tag is provided, or if the cipher text
 283 has been tampered with, [`decipher.final()`][] with throw, indicating that the
 284 cipher text should be discarded due to failed authentication.
 285
 286 ### decipher.setAutoPadding(auto_padding=true)
 287
 288 When data has been encrypted without standard block padding, calling
 289 `decipher.setAutoPadding(false)` will disable automatic padding to prevent
 290 [`decipher.final()`][] from checking for and removing padding.
 291
 292 Turning auto padding off will only work if the input data's length is a
 293 multiple of the ciphers block size.
 294
 295 The `decipher.setAutoPadding()` method must be called before
 296 [`decipher.update()`][].
 297
 298 ### decipher.update(data[, input_encoding][, output_encoding])
 299
 300 Updates the decipher with `data`. If the `input_encoding` argument is given,
 301 it's value must be one of `'binary'`, `'base64'`, or `'hex'` and the `data`
 302 argument is a string using the specified encoding. If the `input_encoding`
 303 argument is not given, `data` must be a [`Buffer`][]. If `data` is a
 304 [`Buffer`][] then `input_encoding` is ignored.
 305
 306 The `output_encoding` specifies the output format of the enciphered
 307 data, and can be `'binary'`, `'ascii'` or `'utf8'`. If the `output_encoding`
 308 is specified, a string using the specified encoding is returned. If no
 309 `output_encoding` is provided, a [`Buffer`][] is returned.
 310
 311 The `decipher.update()` method can be called multiple times with new data until
 312 [`decipher.final()`][] is called. Calling `decipher.update()` after
 313 [`decipher.final()`][] will result in an error being thrown.
 314
 315 ## Class: DiffieHellman
 316
 317 The `DiffieHellman` class is a utility for creating Diffie-Hellman key
 318 exchanges.
 319
 320 Instances of the `DiffieHellman` class can be created using the
 321 [`crypto.createDiffieHellman()`][] function.
 322
 323 ```js
 324 const crypto = require('crypto');
 325 const assert = require('assert');
 326
 327 // Generate Alice's keys...
 328 const alice = crypto.createDiffieHellman(2048);
 329 const alice_key = alice.generateKeys();
 330
 331 // Generate Bob's keys...
 332 const bob = crypto.createDiffieHellman(alice.getPrime(), alice.getGenerator());
 333 const bob_key = bob.generateKeys();
 334
 335 // Exchange and generate the secret...
 336 const alice_secret = alice.computeSecret(bob_key);
 337 const bob_secret = bob.computeSecret(alice_key);
 338
 339 // OK
 340 assert.equal(alice_secret.toString('hex'), bob_secret.toString('hex'));
 341 ```
 342
 343 ### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding])
 344
 345 Computes the shared secret using `other_public_key` as the other
 346 party's public key and returns the computed shared secret. The supplied
 347 key is interpreted using the specified `input_encoding`, and secret is
 348 encoded using specified `output_encoding`. Encodings can be
 349 `'binary'`, `'hex'`, or `'base64'`. If the `input_encoding` is not
 350 provided, `other_public_key` is expected to be a [`Buffer`][].
 351
 352 If `output_encoding` is given a string is returned; otherwise, a
 353 [`Buffer`][] is returned.
 354
 355 ### diffieHellman.generateKeys([encoding])
 356
 357 Generates private and public Diffie-Hellman key values, and returns
 358 the public key in the specified `encoding`. This key should be
 359 transferred to the other party. Encoding can be `'binary'`, `'hex'`,
 360 or `'base64'`. If `encoding` is provided a string is returned; otherwise a
 361 [`Buffer`][] is returned.
 362
 363 ### diffieHellman.getGenerator([encoding])
 364
 365 Returns the Diffie-Hellman generator in the specified `encoding`, which can
 366 be `'binary'`, `'hex'`, or `'base64'`. If  `encoding` is provided a string is
 367 returned; otherwise a [`Buffer`][] is returned.
 368
 369 ### diffieHellman.getPrime([encoding])
 370
 371 Returns the Diffie-Hellman prime in the specified `encoding`, which can
 372 be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is
 373 returned; otherwise a [`Buffer`][] is returned.
 374
 375 ### diffieHellman.getPrivateKey([encoding])
 376
 377 Returns the Diffie-Hellman private key in the specified `encoding`,
 378 which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a
 379 string is returned; otherwise a [`Buffer`][] is returned.
 380
 381 ### diffieHellman.getPublicKey([encoding])
 382
 383 Returns the Diffie-Hellman public key in the specified `encoding`, which
 384 can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a
 385 string is returned; otherwise a [`Buffer`][] is returned.
 386
 387 ### diffieHellman.setPrivateKey(private_key[, encoding])
 388
 389 Sets the Diffie-Hellman private key. If the `encoding` argument is provided
 390 and is either `'binary'`, `'hex'`, or `'base64'`, `private_key` is expected
 391 to be a string. If no `encoding` is provided, `private_key` is expected
 392 to be a [`Buffer`][].
 393
 394 ### diffieHellman.setPublicKey(public_key[, encoding])
 395
 396 Sets the Diffie-Hellman public key. If the `encoding` argument is provided
 397 and is either `'binary'`, `'hex'` or `'base64'`, `public_key` is expected
 398 to be a string. If no `encoding` is provided, `public_key` is expected
 399 to be a [`Buffer`][].
 400
 401 ### diffieHellman.verifyError
 402
 403 A bit field containing any warnings and/or errors resulting from a check
 404 performed during initialization of the `DiffieHellman` object.
 405
 406 The following values are valid for this property (as defined in `constants`
 407 module):
 408
 409 * `DH_CHECK_P_NOT_SAFE_PRIME`
 410 * `DH_CHECK_P_NOT_PRIME`
 411 * `DH_UNABLE_TO_CHECK_GENERATOR`
 412 * `DH_NOT_SUITABLE_GENERATOR`
 413
 414 ## Class: ECDH
 415
 416 The `ECDH` class is a utility for creating Elliptic Curve Diffie-Hellman (ECDH)
 417 key exchanges.
 418
 419 Instances of the `ECDH` class can be created using the
 420 [`crypto.createECDH()`][] function.
 421
 422 ```js
 423 const crypto = require('crypto');
 424 const assert = require('assert');
 425
 426 // Generate Alice's keys...
 427 const alice = crypto.createECDH('secp521r1');
 428 const alice_key = alice.generateKeys();
 429
 430 // Generate Bob's keys...
 431 const bob = crypto.createECDH('secp521r1');
 432 const bob_key = bob.generateKeys();
 433
 434 // Exchange and generate the secret...
 435 const alice_secret = alice.computeSecret(bob_key);
 436 const bob_secret = bob.computeSecret(alice_key);
 437
 438 assert(alice_secret, bob_secret);
 439   // OK
 440 ```
 441
 442 ### ecdh.computeSecret(other_public_key[, input_encoding][, output_encoding])
 443
 444 Computes the shared secret using `other_public_key` as the other
 445 party's public key and returns the computed shared secret. The supplied
 446 key is interpreted using specified `input_encoding`, and the returned secret
 447 is encoded using the specified `output_encoding`. Encodings can be
 448 `'binary'`, `'hex'`, or `'base64'`. If the `input_encoding` is not
 449 provided, `other_public_key` is expected to be a [`Buffer`][].
 450
 451 If `output_encoding` is given a string will be returned; otherwise a
 452 [`Buffer`][] is returned.
 453
 454 ### ecdh.generateKeys([encoding[, format]])
 455
 456 Generates private and public EC Diffie-Hellman key values, and returns
 457 the public key in the specified `format` and `encoding`. This key should be
 458 transferred to the other party.
 459
 460 The `format` arguments specifies point encoding and can be `'compressed'`,
 461 `'uncompressed'`, or `'hybrid'`. If `format` is not specified, the point will
 462 be returned in `'uncompressed'` format.
 463
 464 The `encoding` argument can be `'binary'`, `'hex'`, or `'base64'`. If
 465 `encoding` is provided a string is returned; otherwise a [`Buffer`][]
 466 is returned.
 467
 468 ### ecdh.getPrivateKey([encoding])
 469
 470 Returns the EC Diffie-Hellman private key in the specified `encoding`,
 471 which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided
 472 a string is returned; otherwise a [`Buffer`][] is returned.
 473
 474 ### ecdh.getPublicKey([encoding[, format]])
 475
 476 Returns the EC Diffie-Hellman public key in the specified `encoding` and
 477 `format`.
 478
 479 The `format` argument specifies point encoding and can be `'compressed'`,
 480 `'uncompressed'`, or `'hybrid'`. If `format` is not specified the point will be
 481 returned in `'uncompressed'` format.
 482
 483 The `encoding` argument can be `'binary'`, `'hex'`, or `'base64'`. If
 484 `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is
 485 returned.
 486
 487 ### ecdh.setPrivateKey(private_key[, encoding])
 488
 489 Sets the EC Diffie-Hellman private key. The `encoding` can be `'binary'`,
 490 `'hex'` or `'base64'`. If `encoding` is provided, `private_key` is expected
 491 to be a string; otherwise `private_key` is expected to be a [`Buffer`][]. If
 492 `private_key` is not valid for the curve specified when the `ECDH` object was
 493 created, an error is thrown. Upon setting the private key, the associated
 494 public point (key) is also generated and set in the ECDH object.
 495
 496 ### ecdh.setPublicKey(public_key[, encoding])
 497
 498     Stability: 0 - Deprecated
 499
 500 Sets the EC Diffie-Hellman public key. Key encoding can be `'binary'`,
 501 `'hex'` or `'base64'`. If `encoding` is provided `public_key` is expected to
 502 be a string; otherwise a [`Buffer`][] is expected.
 503
 504 Note that there is not normally a reason to call this method because `ECDH`
 505 only requires a private key and the other party's public key to compute the
 506 shared secret. Typically either [`ecdh.generateKeys()`][] or
 507 [`ecdh.setPrivateKey()`][] will be called. The [`ecdh.setPrivateKey()`][] method
 508 attempts to generate the public point/key associated with the private key being
 509 set.
 510
 511 Example (obtaining a shared secret):
 512
 513 ```js
 514 const crypto = require('crypto');
 515 const alice = crypto.createECDH('secp256k1');
 516 const bob = crypto.createECDH('secp256k1');
 517
 518 // Note: This is a shortcut way to specify one of Alice's previous private
 519 // keys. It would be unwise to use such a predictable private key in a real
 520 // application.
 521 alice.setPrivateKey(
 522   crypto.createHash('sha256').update('alice', 'utf8').digest()
 523 );
 524
 525 // Bob uses a newly generated cryptographically strong
 526 // pseudorandom key pair bob.generateKeys();
 527
 528 const alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
 529 const bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
 530
 531 // alice_secret and bob_secret should be the same shared secret value
 532 console.log(alice_secret === bob_secret);
 533 ```
 534
 535 ## Class: Hash
 536
 537 The `Hash` class is a utility for creating hash digests of data. It can be
 538 used in one of two ways:
 539
 540 - As a [stream][] that is both readable and writable, where data is written
 541   to produce a computed hash digest on the readable side, or
 542 - Using the [`hash.update()`][] and [`hash.digest()`][] methods to produce the
 543   computed hash.
 544
 545 The [`crypto.createHash()`][] method is used to create `Hash` instances. `Hash`
 546 objects are not to be created directly using the `new` keyword.
 547
 548 Example: Using `Hash` objects as streams:
 549
 550 ```js
 551 const crypto = require('crypto');
 552 const hash = crypto.createHash('sha256');
 553
 554 hash.on('readable', () => {
 555   var data = hash.read();
 556   if (data)
 557     console.log(data.toString('hex'));
 558     // Prints:
 559     //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
 560 });
 561
 562 hash.write('some data to hash');
 563 hash.end();
 564 ```
 565
 566 Example: Using `Hash` and piped streams:
 567
 568 ```js
 569 const crypto = require('crypto');
 570 const fs = require('fs');
 571 const hash = crypto.createHash('sha256');
 572
 573 const input = fs.createReadStream('test.js');
 574 input.pipe(hash).pipe(process.stdout);
 575 ```
 576
 577 Example: Using the [`hash.update()`][] and [`hash.digest()`][] methods:
 578
 579 ```js
 580 const crypto = require('crypto');
 581 const hash = crypto.createHash('sha256');
 582
 583 hash.update('some data to hash');
 584 console.log(hash.digest('hex'));
 585   // Prints:
 586   //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
 587 ```
 588
 589 ### hash.digest([encoding])
 590
 591 Calculates the digest of all of the data passed to be hashed (using the
 592 [`hash.update()`][] method). The `encoding` can be `'hex'`, `'binary'` or
 593 `'base64'`. If `encoding` is provided a string will be returned; otherwise
 594 a [`Buffer`][] is returned.
 595
 596 The `Hash` object can not be used again after `hash.digest()` method has been
 597 called. Multiple calls will cause an error to be thrown.
 598
 599 ### hash.update(data[, input_encoding])
 600
 601 Updates the hash content with the given `data`, the encoding of which
 602 is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
 603 `'binary'`. If `encoding` is not provided, and the `data` is a string, an
 604 encoding of `'binary'` is enforced. If `data` is a [`Buffer`][] then
 605 `input_encoding` is ignored.
 606
 607 This can be called many times with new data as it is streamed.
 608
 609 ## Class: Hmac
 610
 611 The `Hmac` Class is a utility for creating cryptographic HMAC digests. It can
 612 be used in one of two ways:
 613
 614 - As a [stream][] that is both readable and writable, where data is written
 615   to produce a computed HMAC digest on the readable side, or
 616 - Using the [`hmac.update()`][] and [`hmac.digest()`][] methods to produce the
 617   computed HMAC digest.
 618
 619 The [`crypto.createHmac()`][] method is used to create `Hmac` instances. `Hmac`
 620 objects are not to be created directly using the `new` keyword.
 621
 622 Example: Using `Hmac` objects as streams:
 623
 624 ```js
 625 const crypto = require('crypto');
 626 const hmac = crypto.createHmac('sha256', 'a secret');
 627
 628 hmac.on('readable', () => {
 629   var data = hmac.read();
 630   if (data)
 631     console.log(data.toString('hex'));
 632     // Prints:
 633     //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
 634 });
 635
 636 hmac.write('some data to hash');
 637 hmac.end();
 638 ```
 639
 640 Example: Using `Hmac` and piped streams:
 641
 642 ```js
 643 const crypto = require('crypto');
 644 const fs = require('fs');
 645 const hmac = crypto.createHmac('sha256', 'a secret');
 646
 647 const input = fs.createReadStream('test.js');
 648 input.pipe(hmac).pipe(process.stdout);
 649 ```
 650
 651 Example: Using the [`hmac.update()`][] and [`hmac.digest()`][] methods:
 652
 653 ```js
 654 const crypto = require('crypto');
 655 const hmac = crypto.createHmac('sha256', 'a secret');
 656
 657 hmac.update('some data to hash');
 658 console.log(hmac.digest('hex'));
 659   // Prints:
 660   //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
 661 ```
 662
 663 ### hmac.digest([encoding])
 664
 665 Calculates the HMAC digest of all of the data passed using [`hmac.update()`][].
 666 The `encoding` can be `'hex'`, `'binary'` or `'base64'`. If `encoding` is
 667 provided a string is returned; otherwise a [`Buffer`][] is returned;
 668
 669 The `Hmac` object can not be used again after `hmac.digest()` has been
 670 called. Multiple calls to `hmac.digest()` will result in an error being thrown.
 671
 672 ### hmac.update(data[, input_encoding])
 673
 674 Updates the `Hmac` content with the given `data`, the encoding of which
 675 is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
 676 `'binary'`. If `encoding` is not provided, and the `data` is a string, an
 677 encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then
 678 `input_encoding` is ignored.
 679
 680 This can be called many times with new data as it is streamed.
 681
 682 ## Class: Sign
 683
 684 The `Sign` Class is a utility for generating signatures. It can be used in one
 685 of two ways:
 686
 687 - As a writable [stream][], where data to be signed is written and the
 688   [`sign.sign()`][] method is used to generate and return the signature, or
 689 - Using the [`sign.update()`][] and [`sign.sign()`][] methods to produce the
 690   signature.
 691
 692 The [`crypto.createSign()`][] method is used to create `Sign` instances. `Sign`
 693 objects are not to be created directly using the `new` keyword.
 694
 695 Example: Using `Sign` objects as streams:
 696
 697 ```js
 698 const crypto = require('crypto');
 699 const sign = crypto.createSign('RSA-SHA256');
 700
 701 sign.write('some data to sign');
 702 sign.end();
 703
 704 const private_key = getPrivateKeySomehow();
 705 console.log(sign.sign(private_key, 'hex'));
 706   // Prints the calculated signature
 707 ```
 708
 709 Example: Using the [`sign.update()`][] and [`sign.sign()`][] methods:
 710
 711 ```js
 712 const crypto = require('crypto');
 713 const sign = crypto.createSign('RSA-SHA256');
 714
 715 sign.update('some data to sign');
 716
 717 const private_key = getPrivateKeySomehow();
 718 console.log(sign.sign(private_key, 'hex'));
 719   // Prints the calculated signature
 720 ```
 721
 722 A [`sign`][] instance can also be created by just passing in the digest
 723 algorithm name, in which case OpenSSL will infer the full signature algorithm
 724 from the type of the PEM-formatted private key, including algorithms that
 725 do not have directly exposed name constants, e.g. 'ecdsa-with-SHA256'.
 726
 727 Example: signing using ECDSA with SHA256
 728
 729 ```js
 730 const crypto = require('crypto');
 731 const sign = crypto.createSign('sha256');
 732
 733 sign.update('some data to sign');
 734
 735 const private_key = '-----BEGIN EC PRIVATE KEY-----\n' +
 736         'MHcCAQEEIF+jnWY1D5kbVYDNvxxo/Y+ku2uJPDwS0r/VuPZQrjjVoAoGCCqGSM49\n' +
 737         'AwEHoUQDQgAEurOxfSxmqIRYzJVagdZfMMSjRNNhB8i3mXyIMq704m2m52FdfKZ2\n' +
 738         'pQhByd5eyj3lgZ7m7jbchtdgyOF8Io/1ng==\n' +
 739         '-----END EC PRIVATE KEY-----\n';
 740
 741 console.log(sign.sign(private_key).toString('hex'));
 742 ```
 743
 744 ### sign.sign(private_key[, output_format])
 745
 746 Calculates the signature on all the data passed through using either
 747 [`sign.update()`][] or [`sign.write()`][stream-writable-write].
 748
 749 The `private_key` argument can be an object or a string. If `private_key` is a
 750 string, it is treated as a raw key with no passphrase. If `private_key` is an
 751 object, it is interpreted as a hash containing two properties:
 752
 753 * `key` : {String} - PEM encoded private key
 754 * `passphrase` : {String} - passphrase for the private key
 755
 756 The `output_format` can specify one of `'binary'`, `'hex'` or `'base64'`. If
 757 `output_format` is provided a string is returned; otherwise a [`Buffer`][] is
 758 returned.
 759
 760 The `Sign` object can not be again used after `sign.sign()` method has been
 761 called. Multiple calls to `sign.sign()` will result in an error being thrown.
 762
 763 ### sign.update(data[, input_encoding])
 764
 765 Updates the `Sign` content with the given `data`, the encoding of which
 766 is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
 767 `'binary'`. If `encoding` is not provided, and the `data` is a string, an
 768 encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then
 769 `input_encoding` is ignored.
 770
 771 This can be called many times with new data as it is streamed.
 772
 773 ## Class: Verify
 774
 775 The `Verify` class is a utility for verifying signatures. It can be used in one
 776 of two ways:
 777
 778 - As a writable [stream][] where written data is used to validate against the
 779   supplied signature, or
 780 - Using the [`verify.update()`][] and [`verify.verify()`][] methods to verify
 781   the signature.
 782
 783   The [`crypto.createSign()`][] method is used to create `Sign` instances.
 784   `Sign` objects are not to be created directly using the `new` keyword.
 785
 786 Example: Using `Verify` objects as streams:
 787
 788 ```js
 789 const crypto = require('crypto');
 790 const verify = crypto.createVerify('RSA-SHA256');
 791
 792 verify.write('some data to sign');
 793 verify.end();
 794
 795 const public_key = getPublicKeySomehow();
 796 const signature = getSignatureToVerify();
 797 console.log(sign.verify(public_key, signature));
 798   // Prints true or false
 799 ```
 800
 801 Example: Using the [`verify.update()`][] and [`verify.verify()`][] methods:
 802
 803 ```js
 804 const crypto = require('crypto');
 805 const verify = crypto.createVerify('RSA-SHA256');
 806
 807 verify.update('some data to sign');
 808
 809 const public_key = getPublicKeySomehow();
 810 const signature = getSignatureToVerify();
 811 console.log(verify.verify(public_key, signature));
 812   // Prints true or false
 813 ```
 814
 815 ### verifier.update(data[, input_encoding])
 816
 817 Updates the `Verify` content with the given `data`, the encoding of which
 818 is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
 819 `'binary'`. If `encoding` is not provided, and the `data` is a string, an
 820 encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then
 821 `input_encoding` is ignored.
 822
 823 This can be called many times with new data as it is streamed.
 824
 825 ### verifier.verify(object, signature[, signature_format])
 826
 827 Verifies the provided data using the given `object` and `signature`.
 828 The `object` argument is a string containing a PEM encoded object, which can be
 829 one an RSA public key, a DSA public key, or an X.509 certificate.
 830 The `signature` argument is the previously calculated signature for the data, in
 831 the `signature_format` which can be `'binary'`, `'hex'` or `'base64'`.
 832 If a `signature_format` is specified, the `signature` is expected to be a
 833 string; otherwise `signature` is expected to be a [`Buffer`][].
 834
 835 Returns `true` or `false` depending on the validity of the signature for
 836 the data and public key.
 837
 838 The `verifier` object can not be used again after `verify.verify()` has been
 839 called. Multiple calls to `verify.verify()` will result in an error being
 840 thrown.
 841
 842 ## `crypto` module methods and properties
 843
 844 ### crypto.DEFAULT_ENCODING
 845
 846 The default encoding to use for functions that can take either strings
 847 or [buffers][`Buffer`]. The default value is `'buffer'`, which makes methods
 848 default to [`Buffer`][] objects.
 849
 850 The `crypto.DEFAULT_ENCODING` mechanism is provided for backwards compatibility
 851 with legacy programs that expect `'binary'` to be the default encoding.
 852
 853 New applications should expect the default to be `'buffer'`. This property may
 854 become deprecated in a future Node.js release.
 855
 856 ### crypto.createCipher(algorithm, password)
 857
 858 Creates and returns a `Cipher` object that uses the given `algorithm` and
 859 `password`.
 860
 861 The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
 862 recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
 863 available cipher algorithms.
 864
 865 The `password` is used to derive the cipher key and initialization vector (IV).
 866 The value must be either a `'binary'` encoded string or a [`Buffer`][].
 867
 868 The implementation of `crypto.createCipher()` derives keys using the OpenSSL
 869 function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one
 870 iteration, and no salt. The lack of salt allows dictionary attacks as the same
 871 password always creates the same key. The low iteration count and
 872 non-cryptographically secure hash algorithm allow passwords to be tested very
 873 rapidly.
 874
 875 In line with OpenSSL's recommendation to use pbkdf2 instead of
 876 [`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on
 877 their own using [`crypto.pbkdf2()`][] and to use [`crypto.createCipheriv()`][]
 878 to create the `Cipher` object.
 879
 880 ### crypto.createCipheriv(algorithm, key, iv)
 881
 882 Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
 883 initialization vector (`iv`).
 884
 885 The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
 886 recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
 887 available cipher algorithms.
 888
 889 The `key` is the raw key used by the `algorithm` and `iv` is an
 890 [initialization vector][]. Both arguments must be `'binary'` encoded strings or
 891 [buffers][`Buffer`].
 892
 893 ### crypto.createCredentials(details)
 894
 895     Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead.
 896
 897 The `crypto.createCredentials()` method is a deprecated alias for creating
 898 and returning a `tls.SecureContext` object. The `crypto.createCredentials()`
 899 method should not be used.
 900
 901 The optional `details` argument is a hash object with keys:
 902
 903 * `pfx` : {String|Buffer} - PFX or PKCS12 encoded private
 904   key, certificate and CA certificates
 905 * `key` : {String} - PEM encoded private key
 906 * `passphrase` : {String} - passphrase for the private key or PFX
 907 * `cert` : {String} - PEM encoded certificate
 908 * `ca` : {String|Array} - Either a string or array of strings of PEM encoded CA
 909   certificates to trust.
 910 * `crl` : {String|Array} - Either a string or array of strings of PEM encoded CRLs
 911   (Certificate Revocation List)
 912 * `ciphers`: {String} using the [OpenSSL cipher list format][] describing the
 913   cipher algorithms to use or exclude.
 914
 915 If no 'ca' details are given, Node.js will use Mozilla's default
 916 [publicly trusted list of CAs][].
 917
 918 ### crypto.createDecipher(algorithm, password)
 919
 920 Creates and returns a `Decipher` object that uses the given `algorithm` and
 921 `password` (key).
 922
 923 The implementation of `crypto.createDecipher()` derives keys using the OpenSSL
 924 function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one
 925 iteration, and no salt. The lack of salt allows dictionary attacks as the same
 926 password always creates the same key. The low iteration count and
 927 non-cryptographically secure hash algorithm allow passwords to be tested very
 928 rapidly.
 929
 930 In line with OpenSSL's recommendation to use pbkdf2 instead of
 931 [`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on
 932 their own using [`crypto.pbkdf2()`][] and to use [`crypto.createDecipheriv()`][]
 933 to create the `Decipher` object.
 934
 935 ### crypto.createDecipheriv(algorithm, key, iv)
 936
 937 Creates and returns a `Decipher` object that uses the given `algorithm`, `key`
 938 and initialization vector (`iv`).
 939
 940 The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
 941 recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
 942 available cipher algorithms.
 943
 944 The `key` is the raw key used by the `algorithm` and `iv` is an
 945 [initialization vector][]. Both arguments must be `'binary'` encoded strings or
 946 [buffers][`Buffer`].
 947
 948 ### crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding])
 949
 950 Creates a `DiffieHellman` key exchange object using the supplied `prime` and an
 951 optional specific `generator`.
 952
 953 The `generator` argument can be a number, string, or [`Buffer`][]. If
 954 `generator` is not specified, the value `2` is used.
 955
 956 The `prime_encoding` and `generator_encoding` arguments can be `'binary'`,
 957 `'hex'`, or `'base64'`.
 958
 959 If `prime_encoding` is specified, `prime` is expected to be a string; otherwise
 960 a [`Buffer`][] is expected.
 961
 962 If `generator_encoding` is specified, `generator` is expected to be a string;
 963 otherwise either a number or [`Buffer`][] is expected.
 964
 965 ### crypto.createDiffieHellman(prime_length[, generator])
 966
 967 Creates a `DiffieHellman` key exchange object and generates a prime of
 968 `prime_length` bits using an optional specific numeric `generator`.
 969 If `generator` is not specified, the value `2` is used.
 970
 971 ### crypto.createECDH(curve_name)
 972
 973 Creates an Elliptic Curve Diffie-Hellman (`ECDH`) key exchange object using a
 974 predefined curve specified by the `curve_name` string. Use
 975 [`crypto.getCurves()`][] to obtain a list of available curve names. On recent
 976 OpenSSL releases, `openssl ecparam -list_curves` will also display the name
 977 and description of each available elliptic curve.
 978
 979 ### crypto.createHash(algorithm)
 980
 981 Creates and returns a `Hash` object that can be used to generate hash digests
 982 using the given `algorithm`.
 983
 984 The `algorithm` is dependent on the available algorithms supported by the
 985 version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc.
 986 On recent releases of OpenSSL, `openssl list-message-digest-algorithms` will
 987 display the available digest algorithms.
 988
 989 Example: generating the sha256 sum of a file
 990
 991 ```js
 992 const filename = process.argv[2];
 993 const crypto = require('crypto');
 994 const fs = require('fs');
 995
 996 const hash = crypto.createHash('sha256');
 997
 998 const input = fs.createReadStream(filename);
 999 input.on('readable', () => {
1000   var data = input.read();
1001   if (data)
1002     hash.update(data);
1003   else {
1004     console.log(`${hash.digest('hex')} ${filename}`);
1005   }
1006 });
1007 ```
1008
1009 ### crypto.createHmac(algorithm, key)
1010
1011 Creates and returns an `Hmac` object that uses the given `algorithm` and `key`.
1012
1013 The `algorithm` is dependent on the available algorithms supported by the
1014 version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc.
1015 On recent releases of OpenSSL, `openssl list-message-digest-algorithms` will
1016 display the available digest algorithms.
1017
1018 The `key` is the HMAC key used to generate the cryptographic HMAC hash.
1019
1020 Example: generating the sha256 HMAC of a file
1021
1022 ```js
1023 const filename = process.argv[2];
1024 const crypto = require('crypto');
1025 const fs = require('fs');
1026
1027 const hmac = crypto.createHmac('sha256', 'a secret');
1028
1029 const input = fs.createReadStream(filename);
1030 input.on('readable', () => {
1031   var data = input.read();
1032   if (data)
1033     hmac.update(data);
1034   else {
1035     console.log(`${hmac.digest('hex')} ${filename}`);
1036   }
1037 });
1038 ```
1039
1040 ### crypto.createSign(algorithm)
1041
1042 Creates and returns a `Sign` object that uses the given `algorithm`. On
1043 recent OpenSSL releases, `openssl list-public-key-algorithms` will
1044 display the available signing algorithms. One example is `'RSA-SHA256'`.
1045
1046 ### crypto.createVerify(algorithm)
1047
1048 Creates and returns a `Verify` object that uses the given algorithm. On
1049 recent OpenSSL releases, `openssl list-public-key-algorithms` will
1050 display the available signing algorithms. One example is `'RSA-SHA256'`.
1051
1052 ### crypto.getCiphers()
1053
1054 Returns an array with the names of the supported cipher algorithms.
1055
1056 Example:
1057
1058 ```js
1059 const ciphers = crypto.getCiphers();
1060 console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
1061 ```
1062
1063 ### crypto.getCurves()
1064
1065 Returns an array with the names of the supported elliptic curves.
1066
1067 Example:
1068
1069 ```js
1070 const curves = crypto.getCurves();
1071 console.log(curves); // ['secp256k1', 'secp384r1', ...]
1072 ```
1073
1074 ### crypto.getDiffieHellman(group_name)
1075
1076 Creates a predefined `DiffieHellman` key exchange object. The
1077 supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in
1078 [RFC 2412][], but see [Caveats][]) and `'modp14'`, `'modp15'`,
1079 `'modp16'`, `'modp17'`, `'modp18'` (defined in [RFC 3526][]). The
1080 returned object mimics the interface of objects created by
1081 [`crypto.createDiffieHellman()`][], but will not allow changing
1082 the keys (with [`diffieHellman.setPublicKey()`][] for example). The
1083 advantage of using this method is that the parties do not have to
1084 generate nor exchange a group modulus beforehand, saving both processor
1085 and communication time.
1086
1087 Example (obtaining a shared secret):
1088
1089 ```js
1090 const crypto = require('crypto');
1091 const alice = crypto.getDiffieHellman('modp14');
1092 const bob = crypto.getDiffieHellman('modp14');
1093
1094 alice.generateKeys();
1095 bob.generateKeys();
1096
1097 const alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
1098 const bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
1099
1100 /* alice_secret and bob_secret should be the same */
1101 console.log(alice_secret == bob_secret);
1102 ```
1103
1104 ### crypto.getHashes()
1105
1106 Returns an array with the names of the supported hash algorithms.
1107
1108 Example:
1109
1110 ```js
1111 const hashes = crypto.getHashes();
1112 console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
1113 ```
1114
1115 ### crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback)
1116
1117 Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2)
1118 implementation. A selected HMAC digest algorithm specified by `digest` is
1119 applied to derive a key of the requested byte length (`keylen`) from the
1120 `password`, `salt` and `iterations`. If the `digest` algorithm is not specified,
1121 a default of `'sha1'` is used.
1122
1123 The supplied `callback` function is called with two arguments: `err` and
1124 `derivedKey`. If an error occurs, `err` will be set; otherwise `err` will be
1125 null. The successfully generated `derivedKey` will be passed as a [`Buffer`][].
1126
1127 The `iterations` argument must be a number set as high as possible. The
1128 higher the number of iterations, the more secure the derived key will be,
1129 but will take a longer amount of time to complete.
1130
1131 The `salt` should also be as unique as possible. It is recommended that the
1132 salts are random and their lengths are greater than 16 bytes. See
1133 [NIST SP 800-132][] for details.
1134
1135 Example:
1136
1137 ```js
1138 const crypto = require('crypto');
1139 crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, key) => {
1140   if (err) throw err;
1141   console.log(key.toString('hex'));  // 'c5e478d...1469e50'
1142 });
1143 ```
1144
1145 An array of supported digest functions can be retrieved using
1146 [`crypto.getHashes()`][].
1147
1148 ### crypto.pbkdf2Sync(password, salt, iterations, keylen[, digest])
1149
1150 Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2)
1151 implementation. A selected HMAC digest algorithm specified by `digest` is
1152 applied to derive a key of the requested byte length (`keylen`) from the
1153 `password`, `salt` and `iterations`. If the `digest` algorithm is not specified,
1154 a default of `'sha1'` is used.
1155
1156 If an error occurs an Error will be thrown, otherwise the derived key will be
1157 returned as a [`Buffer`][].
1158
1159 The `iterations` argument must be a number set as high as possible. The
1160 higher the number of iterations, the more secure the derived key will be,
1161 but will take a longer amount of time to complete.
1162
1163 The `salt` should also be as unique as possible. It is recommended that the
1164 salts are random and their lengths are greater than 16 bytes. See
1165 [NIST SP 800-132][] for details.
1166
1167 Example:
1168
1169 ```js
1170 const crypto = require('crypto');
1171 const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 512, 'sha512');
1172 console.log(key.toString('hex'));  // 'c5e478d...1469e50'
1173 ```
1174
1175 An array of supported digest functions can be retrieved using
1176 [`crypto.getHashes()`][].
1177
1178 ### crypto.privateDecrypt(private_key, buffer)
1179
1180 Decrypts `buffer` with `private_key`.
1181
1182 `private_key` can be an object or a string. If `private_key` is a string, it is
1183 treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
1184 If `private_key` is an object, it is interpreted as a hash object with the
1185 keys:
1186
1187 * `key` : {String} - PEM encoded private key
1188 * `passphrase` : {String} - Optional passphrase for the private key
1189 * `padding` : An optional padding value, one of the following:
1190   * `constants.RSA_NO_PADDING`
1191   * `constants.RSA_PKCS1_PADDING`
1192   * `constants.RSA_PKCS1_OAEP_PADDING`
1193
1194 All paddings are defined in the `constants` module.
1195
1196 ### crypto.privateEncrypt(private_key, buffer)
1197
1198 Encrypts `buffer` with `private_key`.
1199
1200 `private_key` can be an object or a string. If `private_key` is a string, it is
1201 treated as the key with no passphrase and will use `RSA_PKCS1_PADDING`.
1202 If `private_key` is an object, it is interpreted as a hash object with the
1203 keys:
1204
1205 * `key` : {String} - PEM encoded private key
1206 * `passphrase` : {String} - Optional passphrase for the private key
1207 * `padding` : An optional padding value, one of the following:
1208   * `constants.RSA_NO_PADDING`
1209   * `constants.RSA_PKCS1_PADDING`
1210   * `constants.RSA_PKCS1_OAEP_PADDING`
1211
1212 All paddings are defined in the `constants` module.
1213
1214 ### crypto.publicDecrypt(public_key, buffer)
1215
1216 Decrypts `buffer` with `public_key`.
1217
1218 `public_key` can be an object or a string. If `public_key` is a string, it is
1219 treated as the key with no passphrase and will use `RSA_PKCS1_PADDING`.
1220 If `public_key` is an object, it is interpreted as a hash object with the
1221 keys:
1222
1223 * `key` : {String} - PEM encoded public key
1224 * `passphrase` : {String} - Optional passphrase for the private key
1225 * `padding` : An optional padding value, one of the following:
1226   * `constants.RSA_NO_PADDING`
1227   * `constants.RSA_PKCS1_PADDING`
1228   * `constants.RSA_PKCS1_OAEP_PADDING`
1229
1230 Because RSA public keys can be derived from private keys, a private key may
1231 be passed instead of a public key.
1232
1233 All paddings are defined in the `constants` module.
1234
1235 ### crypto.publicEncrypt(public_key, buffer)
1236
1237 Encrypts `buffer` with `public_key`.
1238
1239 `public_key` can be an object or a string. If `public_key` is a string, it is
1240 treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
1241 If `public_key` is an object, it is interpreted as a hash object with the
1242 keys:
1243
1244 * `key` : {String} - PEM encoded public key
1245 * `passphrase` : {String} - Optional passphrase for the private key
1246 * `padding` : An optional padding value, one of the following:
1247   * `constants.RSA_NO_PADDING`
1248   * `constants.RSA_PKCS1_PADDING`
1249   * `constants.RSA_PKCS1_OAEP_PADDING`
1250
1251 Because RSA public keys can be derived from private keys, a private key may
1252 be passed instead of a public key.
1253
1254 All paddings are defined in the `constants` module.
1255
1256 ### crypto.randomBytes(size[, callback])
1257
1258 Generates cryptographically strong pseudo-random data. The `size` argument
1259 is a number indicating the number of bytes to generate.
1260
1261 If a `callback` function is provided, the bytes are generated asynchronously
1262 and the `callback` function is invoked with two arguments: `err` and `buf`.
1263 If an error occurs, `err` will be an Error object; otherwise it is null. The
1264 `buf` argument is a [`Buffer`][] containing the generated bytes.
1265
1266 ```js
1267 // Asynchronous
1268 const crypto = require('crypto');
1269 crypto.randomBytes(256, (err, buf) => {
1270   if (err) throw err;
1271   console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
1272 });
1273 ```
1274
1275 If the `callback` function is not provided, the random bytes are generated
1276 synchronously and returned as a [`Buffer`][]. An error will be thrown if
1277 there is a problem generating the bytes.
1278
1279 ```js
1280 // Synchronous
1281 const buf = crypto.randomBytes(256);
1282 console.log(
1283   `${buf.length} bytes of random data: ${buf.toString('hex')}`);
1284 ```
1285
1286 The `crypto.randomBytes()` method will block until there is sufficient entropy.
1287 This should normally never take longer than a few milliseconds. The only time
1288 when generating the random bytes may conceivably block for a longer period of
1289 time is right after boot, when the whole system is still low on entropy.
1290
1291 ### crypto.setEngine(engine[, flags])
1292
1293 Load and set the `engine` for some or all OpenSSL functions (selected by flags).
1294
1295 `engine` could be either an id or a path to the engine's shared library.
1296
1297 The optional `flags` argument uses `ENGINE_METHOD_ALL` by default. The `flags`
1298 is a bit field taking one of or a mix of the following flags (defined in the
1299 `constants` module):
1300
1301 * `ENGINE_METHOD_RSA`
1302 * `ENGINE_METHOD_DSA`
1303 * `ENGINE_METHOD_DH`
1304 * `ENGINE_METHOD_RAND`
1305 * `ENGINE_METHOD_ECDH`
1306 * `ENGINE_METHOD_ECDSA`
1307 * `ENGINE_METHOD_CIPHERS`
1308 * `ENGINE_METHOD_DIGESTS`
1309 * `ENGINE_METHOD_STORE`
1310 * `ENGINE_METHOD_PKEY_METH`
1311 * `ENGINE_METHOD_PKEY_ASN1_METH`
1312 * `ENGINE_METHOD_ALL`
1313 * `ENGINE_METHOD_NONE`
1314
1315 ## Notes
1316
1317 ### Legacy Streams API (pre Node.js v0.10)
1318
1319 The Crypto module was added to Node.js before there was the concept of a
1320 unified Stream API, and before there were [`Buffer`][] objects for handling
1321 binary data. As such, the many of the `crypto` defined classes have methods not
1322 typically found on other Node.js classes that implement the [streams][stream]
1323 API (e.g. `update()`, `final()`, or `digest()`). Also, many methods accepted
1324 and returned `'binary'` encoded strings by default rather than Buffers. This
1325 default was changed after Node.js v0.8 to use [`Buffer`][] objects by default
1326 instead.
1327
1328 ### Recent ECDH Changes
1329
1330 Usage of `ECDH` with non-dynamically generated key pairs has been simplified.
1331 Now, [`ecdh.setPrivateKey()`][] can be called with a preselected private key
1332 and the associated public point (key) will be computed and stored in the object.
1333 This allows code to only store and provide the private part of the EC key pair.
1334 [`ecdh.setPrivateKey()`][] now also validates that the private key is valid for
1335 the selected curve.
1336
1337 The [`ecdh.setPublicKey()`][] method is now deprecated as its inclusion in the
1338 API is not useful. Either a previously stored private key should be set, which
1339 automatically generates the associated public key, or [`ecdh.generateKeys()`][]
1340 should be called. The main drawback of using [`ecdh.setPublicKey()`][] is that
1341 it can be used to put the ECDH key pair into an inconsistent state.
1342
1343 ### Support for weak or compromised algorithms
1344
1345 The `crypto` module still supports some algorithms which are already
1346 compromised and are not currently recommended for use. The API also allows
1347 the use of ciphers and hashes with a small key size that are considered to be
1348 too weak for safe use.
1349
1350 Users should take full responsibility for selecting the crypto
1351 algorithm and key size according to their security requirements.
1352
1353 Based on the recommendations of [NIST SP 800-131A][]:
1354
1355 - MD5 and SHA-1 are no longer acceptable where collision resistance is
1356   required such as digital signatures.
1357 - The key used with RSA, DSA and DH algorithms is recommended to have
1358   at least 2048 bits and that of the curve of ECDSA and ECDH at least
1359   224 bits, to be safe to use for several years.
1360 - The DH groups of `modp1`, `modp2` and `modp5` have a key size
1361   smaller than 2048 bits and are not recommended.
1362
1363 See the reference for other recommendations and details.
1364
1365 [`Buffer`]: buffer.html
1366 [`cipher.final()`]: #crypto_cipher_final_output_encoding
1367 [`cipher.update()`]: #crypto_cipher_update_data_input_encoding_output_encoding
1368 [`crypto.createCipher()`]: #crypto_crypto_createcipher_algorithm_password
1369 [`crypto.createCipheriv()`]: #crypto_crypto_createcipheriv_algorithm_key_iv
1370 [`crypto.createDecipher()`]: #crypto_crypto_createdecipher_algorithm_password
1371 [`crypto.createDecipheriv()`]: #crypto_crypto_createdecipheriv_algorithm_key_iv
1372 [`crypto.createDiffieHellman()`]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_encoding
1373 [`crypto.createECDH()`]: #crypto_crypto_createecdh_curve_name
1374 [`crypto.createHash()`]: #crypto_crypto_createhash_algorithm
1375 [`crypto.createHmac()`]: #crypto_crypto_createhmac_algorithm_key
1376 [`crypto.createSign()`]: #crypto_crypto_createsign_algorithm
1377 [`crypto.getCurves()`]: #crypto_crypto_getcurves
1378 [`crypto.getHashes()`]: #crypto_crypto_gethashes
1379 [`crypto.pbkdf2()`]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
1380 [`decipher.final()`]: #crypto_decipher_final_output_encoding
1381 [`decipher.update()`]: #crypto_decipher_update_data_input_encoding_output_encoding
1382 [`diffieHellman.setPublicKey()`]: #crypto_diffiehellman_setpublickey_public_key_encoding
1383 [`ecdh.generateKeys()`]: #crypto_ecdh_generatekeys_encoding_format
1384 [`ecdh.setPrivateKey()`]: #crypto_ecdh_setprivatekey_private_key_encoding
1385 [`ecdh.setPublicKey()`]: #crypto_ecdh_setpublickey_public_key_encoding
1386 [`EVP_BytesToKey`]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html
1387 [`hash.digest()`]: #crypto_hash_digest_encoding
1388 [`hash.update()`]: #crypto_hash_update_data_input_encoding
1389 [`hmac.digest()`]: #crypto_hmac_digest_encoding
1390 [`hmac.update()`]: #crypto_hmac_update_data
1391 [`sign.sign()`]: #crypto_sign_sign_private_key_output_format
1392 [`sign.update()`]: #crypto_sign_update_data
1393 [`tls.createSecureContext()`]: tls.html#tls_tls_createsecurecontext_details
1394 [`verify.update()`]: #crypto_verifier_update_data
1395 [`verify.verify()`]: #crypto_verifier_verify_object_signature_signature_format
1396 [Caveats]: #crypto_support_for_weak_or_compromised_algorithms
1397 [HTML5's `keygen` element]: http://www.w3.org/TR/html5/forms.html#the-keygen-element
1398 [initialization vector]: https://en.wikipedia.org/wiki/Initialization_vector
1399 [NIST SP 800-131A]: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar1.pdf
1400 [NIST SP 800-132]: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf
1401 [OpenSSL cipher list format]: https://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT
1402 [OpenSSL's SPKAC implementation]: https://www.openssl.org/docs/apps/spkac.html
1403 [publicly trusted list of CAs]: https://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
1404 [RFC 2412]: https://www.rfc-editor.org/rfc/rfc2412.txt
1405 [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
1406 [stream]: stream.html
1407 [stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback