doc: fix markdown links
[platform/upstream/nodejs.git] / 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.setAuthPadding(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(11);
329 const alice_key = alice.generateKeys();
330
331 // Generate Bob's keys...
332 const bob = crypto.createDiffieHellman(11);
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 assert(alice_secret, bob_secret);
340   // OK
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)
673
674 Update the `Hmac` content with the given `data`. This can be called
675 many times with new data as it is streamed.
676
677 ## Class: Sign
678
679 The `Sign` Class is a utility for generating signatures. It can be used in one
680 of two ways:
681
682 - As a writable [stream][], where data to be signed is written and the
683   [`sign.sign()`][] method is used to generate and return the signature, or
684 - Using the [`sign.update()`][] and [`sign.sign()`][] methods to produce the
685   signature.
686
687 The [`crypto.createSign()`][] method is used to create `Sign` instances. `Sign`
688 objects are not to be created directly using the `new` keyword.
689
690 Example: Using `Sign` objects as streams:
691
692 ```js
693 const crypto = require('crypto');
694 const sign = crypto.createSign('RSA-SHA256');
695
696 sign.write('some data to sign');
697 sign.end();
698
699 const private_key = getPrivateKeySomehow();
700 console.log(sign.sign(private_key, 'hex'));
701   // Prints the calculated signature
702 ```
703
704 Example: Using the [`sign.update()`][] and [`sign.sign()`][] methods:
705
706 ```js
707 const crypto = require('crypto');
708 const sign = crypto.createSign('RSA-SHA256');
709
710 sign.update('some data to sign');
711
712 const private_key = getPrivateKeySomehow();
713 console.log(sign.sign(private_key, 'hex'));
714   // Prints the calculated signature
715 ```
716
717 ### sign.sign(private_key[, output_format])
718
719 Calculates the signature on all the data passed through using either
720 [`sign.update()`][] or [`sign.write()`][stream-writable-write].
721
722 The `private_key` argument can be an object or a string. If `private_key` is a
723 string, it is treated as a raw key with no passphrase. If `private_key` is an
724 object, it is interpreted as a hash containing two properties:
725
726 * `key` : {String} - PEM encoded private key
727 * `passphrase` : {String} - passphrase for the private key
728
729 The `output_format` can specify one of `'binary'`, `'hex'` or `'base64'`. If
730 `output_format` is provided a string is returned; otherwise a [`Buffer`][] is
731 returned.
732
733 The `Sign` object can not be again used after `sign.sign()` method has been
734 called. Multiple calls to `sign.sign()` will result in an error being thrown.
735
736 ### sign.update(data)
737
738 Updates the sign object with the given `data`. This can be called many times
739 with new data as it is streamed.
740
741 ## Class: Verify
742
743 The `Verify` class is a utility for verifying signatures. It can be used in one
744 of two ways:
745
746 - As a writable [stream][] where written data is used to validate against the
747   supplied signature, or
748 - Using the [`verify.update()`][] and [`verify.verify()`][] methods to verify
749   the signature.
750
751   The [`crypto.createSign()`][] method is used to create `Sign` instances.
752   `Sign` objects are not to be created directly using the `new` keyword.
753
754 Example: Using `Verify` objects as streams:
755
756 ```js
757 const crypto = require('crypto');
758 const verify = crypto.createVerify('RSA-SHA256');
759
760 verify.write('some data to sign');
761 verify.end();
762
763 const public_key = getPublicKeySomehow();
764 const signature = getSignatureToVerify();
765 console.log(sign.verify(public_key, signature));
766   // Prints true or false
767 ```
768
769 Example: Using the [`verify.update()`][] and [`verify.verify()`][] methods:
770
771 ```js
772 const crypto = require('crypto');
773 const verify = crypto.createVerify('RSA-SHA256');
774
775 verify.update('some data to sign');
776
777 const public_key = getPublicKeySomehow();
778 const signature = getSignatureToVerify();
779 console.log(verify.verify(public_key, signature));
780   // Prints true or false
781 ```
782
783 ### verifier.update(data)
784
785 Updates the verifier object with the given `data`. This can be called many
786 times with new data as it is streamed.
787
788 ### verifier.verify(object, signature[, signature_format])
789
790 Verifies the provided data using the given `object` and `signature`.
791 The `object` argument is a string containing a PEM encoded object, which can be
792 one an RSA public key, a DSA public key, or an X.509 certificate.
793 The `signature` argument is the previously calculated signature for the data, in
794 the `signature_format` which can be `'binary'`, `'hex'` or `'base64'`.
795 If a `signature_format` is specified, the `signature` is expected to be a
796 string; otherwise `signature` is expected to be a [`Buffer`][].
797
798 Returns `true` or `false` depending on the validity of the signature for
799 the data and public key.
800
801 The `verifier` object can not be used again after `verify.verify()` has been
802 called. Multiple calls to `verify.verify()` will result in an error being
803 thrown.
804
805 ## `crypto` module methods and properties
806
807 ### crypto.DEFAULT_ENCODING
808
809 The default encoding to use for functions that can take either strings
810 or [buffers][`Buffer`]. The default value is `'buffer'`, which makes methods
811 default to [`Buffer`][] objects.
812
813 The `crypto.DEFAULT_ENCODING` mechanism is provided for backwards compatibility
814 with legacy programs that expect `'binary'` to be the default encoding.
815
816 New applications should expect the default to be `'buffer'`. This property may
817 become deprecated in a future Node.js release.
818
819 ### crypto.createCipher(algorithm, password)
820
821 Creates and returns a `Cipher` object that uses the given `algorithm` and
822 `password`.
823
824 The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
825 recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
826 available cipher algorithms.
827
828 The `password` is used to derive the cipher key and initialization vector (IV).
829 The value must be either a `'binary'` encoded string or a [`Buffer`][].
830
831 The implementation of `crypto.createCipher()` derives keys using the OpenSSL
832 function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one
833 iteration, and no salt. The lack of salt allows dictionary attacks as the same
834 password always creates the same key. The low iteration count and
835 non-cryptographically secure hash algorithm allow passwords to be tested very
836 rapidly.
837
838 In line with OpenSSL's recommendation to use pbkdf2 instead of
839 [`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on
840 their own using [`crypto.pbkdf2()`][] and to use [`crypto.createCipheriv()`][]
841 to create the `Cipher` object.
842
843 ### crypto.createCipheriv(algorithm, key, iv)
844
845 Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
846 initialization vector (`iv`).
847
848 The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
849 recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
850 available cipher algorithms.
851
852 The `key` is the raw key used by the `algorithm` and `iv` is an
853 [initialization vector][]. Both arguments must be `'binary'` encoded strings or
854 [buffers][`Buffer`].
855
856 ### crypto.createCredentials(details)
857
858     Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead.
859
860 The `crypto.createCredentials()` method is a deprecated alias for creating
861 and returning a `tls.SecureContext` object. The `crypto.createCredentials()`
862 method should not be used.
863
864 The optional `details` argument is a hash object with keys:
865
866 * `pfx` : {String|Buffer} - PFX or PKCS12 encoded private
867   key, certificate and CA certificates
868 * `key` : {String} - PEM encoded private key
869 * `passphrase` : {String} - passphrase for the private key or PFX
870 * `cert` : {String} - PEM encoded certificate
871 * `ca` : {String|Array} - Either a string or array of strings of PEM encoded CA
872   certificates to trust.
873 * `crl` : {String|Array} - Either a string or array of strings of PEM encoded CRLs
874   (Certificate Revocation List)
875 * `ciphers`: {String} using the [OpenSSL cipher list format][] describing the
876   cipher algorithms to use or exclude.
877
878 If no 'ca' details are given, Node.js will use Mozilla's default
879 [publicly trusted list of CAs][].
880
881 ### crypto.createDecipher(algorithm, password)
882
883 Creates and returns a `Decipher` object that uses the given `algorithm` and
884 `password` (key).
885
886 The implementation of `crypto.createDecipher()` derives keys using the OpenSSL
887 function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one
888 iteration, and no salt. The lack of salt allows dictionary attacks as the same
889 password always creates the same key. The low iteration count and
890 non-cryptographically secure hash algorithm allow passwords to be tested very
891 rapidly.
892
893 In line with OpenSSL's recommendation to use pbkdf2 instead of
894 [`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on
895 their own using [`crypto.pbkdf2()`][] and to use [`crypto.createDecipheriv()`][]
896 to create the `Decipher` object.
897
898 ### crypto.createDecipheriv(algorithm, key, iv)
899
900 Creates and returns a `Decipher` object that uses the given `algorithm`, `key`
901 and initialization vector (`iv`).
902
903 The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
904 recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
905 available cipher algorithms.
906
907 The `key` is the raw key used by the `algorithm` and `iv` is an
908 [initialization vector][]. Both arguments must be `'binary'` encoded strings or
909 [buffers][`Buffer`].
910
911 ### crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding])
912
913 Creates a `DiffieHellman` key exchange object using the supplied `prime` and an
914 optional specific `generator`.
915
916 The `generator` argument can be a number, string, or [`Buffer`][]. If
917 `generator` is not specified, the value `2` is used.
918
919 The `prime_encoding` and `generator_encoding` arguments can be `'binary'`,
920 `'hex'`, or `'base64'`.
921
922 If `prime_encoding` is specified, `prime` is expected to be a string; otherwise
923 a [`Buffer`][] is expected.
924
925 If `generator_encoding` is specified, `generator` is expected to be a string;
926 otherwise either a number or [`Buffer`][] is expected.
927
928 ### crypto.createDiffieHellman(prime_length[, generator])
929
930 Creates a `DiffieHellman` key exchange object and generates a prime of
931 `prime_length` bits using an optional specific numeric `generator`.
932 If `generator` is not specified, the value `2` is used.
933
934 ### crypto.createECDH(curve_name)
935
936 Creates an Elliptic Curve Diffie-Hellman (`ECDH`) key exchange object using a
937 predefined curve specified by the `curve_name` string. Use
938 [`crypto.getCurves()`][] to obtain a list of available curve names. On recent
939 OpenSSL releases, `openssl ecparam -list_curves` will also display the name
940 and description of each available elliptic curve.
941
942 ### crypto.createHash(algorithm)
943
944 Creates and returns a `Hash` object that can be used to generate hash digests
945 using the given `algorithm`.
946
947 The `algorithm` is dependent on the available algorithms supported by the
948 version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc.
949 On recent releases of OpenSSL, `openssl list-message-digest-algorithms` will
950 display the available digest algorithms.
951
952 Example: generating the sha256 sum of a file
953
954 ```js
955 const filename = process.argv[2];
956 const crypto = require('crypto');
957 const fs = require('fs');
958
959 const hash = crypto.createHash('sha256');
960
961 const input = fs.createReadStream(filename);
962 input.on('readable', () => {
963   var data = input.read();
964   if (data)
965     hash.update(data);
966   else {
967     console.log(`${hash.digest('hex')} ${filename}`);
968   }
969 });
970 ```
971
972 ### crypto.createHmac(algorithm, key)
973
974 Creates and returns an `Hmac` object that uses the given `algorithm` and `key`.
975
976 The `algorithm` is dependent on the available algorithms supported by the
977 version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc.
978 On recent releases of OpenSSL, `openssl list-message-digest-algorithms` will
979 display the available digest algorithms.
980
981 The `key` is the HMAC key used to generate the cryptographic HMAC hash.
982
983 Example: generating the sha256 HMAC of a file
984
985 ```js
986 const filename = process.argv[2];
987 const crypto = require('crypto');
988 const fs = require('fs');
989
990 const hmac = crypto.createHmac('sha256', 'a secret');
991
992 const input = fs.createReadStream(filename);
993 input.on('readable', () => {
994   var data = input.read();
995   if (data)
996     hmac.update(data);
997   else {
998     console.log(`${hmac.digest('hex')} ${filename}`);
999   }
1000 });
1001 ```
1002
1003 ### crypto.createSign(algorithm)
1004
1005 Creates and returns a `Sign` object that uses the given `algorithm`. On
1006 recent OpenSSL releases, `openssl list-public-key-algorithms` will
1007 display the available signing algorithms. One example is `'RSA-SHA256'`.
1008
1009 ### crypto.createVerify(algorithm)
1010
1011 Creates and returns a `Verify` object that uses the given algorithm. On
1012 recent OpenSSL releases, `openssl list-public-key-algorithms` will
1013 display the available signing algorithms. One example is `'RSA-SHA256'`.
1014
1015 ### crypto.getCiphers()
1016
1017 Returns an array with the names of the supported cipher algorithms.
1018
1019 Example:
1020
1021 ```js
1022 const ciphers = crypto.getCiphers();
1023 console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
1024 ```
1025
1026 ### crypto.getCurves()
1027
1028 Returns an array with the names of the supported elliptic curves.
1029
1030 Example:
1031
1032 ```js
1033 const curves = crypto.getCurves();
1034 console.log(curves); // ['secp256k1', 'secp384r1', ...]
1035 ```
1036
1037 ### crypto.getDiffieHellman(group_name)
1038
1039 Creates a predefined `DiffieHellman` key exchange object. The
1040 supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in
1041 [RFC 2412][], but see [Caveats][]) and `'modp14'`, `'modp15'`,
1042 `'modp16'`, `'modp17'`, `'modp18'` (defined in [RFC 3526][]). The
1043 returned object mimics the interface of objects created by
1044 [`crypto.createDiffieHellman()`][], but will not allow changing
1045 the keys (with [`diffieHellman.setPublicKey()`][] for example). The
1046 advantage of using this method is that the parties do not have to
1047 generate nor exchange a group modulus beforehand, saving both processor
1048 and communication time.
1049
1050 Example (obtaining a shared secret):
1051
1052 ```js
1053 const crypto = require('crypto');
1054 const alice = crypto.getDiffieHellman('modp14');
1055 const bob = crypto.getDiffieHellman('modp14');
1056
1057 alice.generateKeys();
1058 bob.generateKeys();
1059
1060 const alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
1061 const bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
1062
1063 /* alice_secret and bob_secret should be the same */
1064 console.log(alice_secret == bob_secret);
1065 ```
1066
1067 ### crypto.getHashes()
1068
1069 Returns an array with the names of the supported hash algorithms.
1070
1071 Example:
1072
1073 ```js
1074 const hashes = crypto.getHashes();
1075 console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...]
1076 ```
1077
1078 ### crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback)
1079
1080 Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2)
1081 implementation. A selected HMAC digest algorithm specified by `digest` is
1082 applied to derive a key of the requested byte length (`keylen`) from the
1083 `password`, `salt` and `iterations`. If the `digest` algorithm is not specified,
1084 a default of `'sha1'` is used.
1085
1086 The supplied `callback` function is called with two arguments: `err` and
1087 `derivedKey`. If an error occurs, `err` will be set; otherwise `err` will be
1088 null. The successfully generated `derivedKey` will be passed as a [`Buffer`][].
1089
1090 The `iterations` argument must be a number set as high as possible. The
1091 higher the number of iterations, the more secure the derived key will be,
1092 but will take a longer amount of time to complete.
1093
1094 The `salt` should also be as unique as possible. It is recommended that the
1095 salts are random and their lengths are greater than 16 bytes. See
1096 [NIST SP 800-132][] for details.
1097
1098 Example:
1099
1100 ```js
1101 const crypto = require('crypto');
1102 crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, key) => {
1103   if (err) throw err;
1104   console.log(key.toString('hex'));  // 'c5e478d...1469e50'
1105 });
1106 ```
1107
1108 An array of supported digest functions can be retrieved using
1109 [`crypto.getHashes()`][].
1110
1111 ### crypto.pbkdf2Sync(password, salt, iterations, keylen[, digest])
1112
1113 Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2)
1114 implementation. A selected HMAC digest algorithm specified by `digest` is
1115 applied to derive a key of the requested byte length (`keylen`) from the
1116 `password`, `salt` and `iterations`. If the `digest` algorithm is not specified,
1117 a default of `'sha1'` is used.
1118
1119 If an error occurs an Error will be thrown, otherwise the derived key will be
1120 returned as a [`Buffer`][].
1121
1122 The `iterations` argument must be a number set as high as possible. The
1123 higher the number of iterations, the more secure the derived key will be,
1124 but will take a longer amount of time to complete.
1125
1126 The `salt` should also be as unique as possible. It is recommended that the
1127 salts are random and their lengths are greater than 16 bytes. See
1128 [NIST SP 800-132][] for details.
1129
1130 Example:
1131
1132 ```js
1133 const crypto = require('crypto');
1134 const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 512, 'sha512');
1135 console.log(key.toString('hex'));  // 'c5e478d...1469e50'
1136 ```
1137
1138 An array of supported digest functions can be retrieved using
1139 [`crypto.getHashes()`][].
1140
1141 ### crypto.privateDecrypt(private_key, buffer)
1142
1143 Decrypts `buffer` with `private_key`.
1144
1145 `private_key` can be an object or a string. If `private_key` is a string, it is
1146 treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
1147 If `private_key` is an object, it is interpreted as a hash object with the
1148 keys:
1149
1150 * `key` : {String} - PEM encoded private key
1151 * `passphrase` : {String} - Optional passphrase for the private key
1152 * `padding` : An optional padding value, one of the following:
1153   * `constants.RSA_NO_PADDING`
1154   * `constants.RSA_PKCS1_PADDING`
1155   * `constants.RSA_PKCS1_OAEP_PADDING`
1156
1157 All paddings are defined in the `constants` module.
1158
1159 ### crypto.privateEncrypt(private_key, buffer)
1160
1161 Encrypts `buffer` with `private_key`.
1162
1163 `private_key` can be an object or a string. If `private_key` is a string, it is
1164 treated as the key with no passphrase and will use `RSA_PKCS1_PADDING`.
1165 If `private_key` is an object, it is interpreted as a hash object with the
1166 keys:
1167
1168 * `key` : {String} - PEM encoded private key
1169 * `passphrase` : {String} - Optional passphrase for the private key
1170 * `padding` : An optional padding value, one of the following:
1171   * `constants.RSA_NO_PADDING`
1172   * `constants.RSA_PKCS1_PADDING`
1173   * `constants.RSA_PKCS1_OAEP_PADDING`
1174
1175 All paddings are defined in the `constants` module.
1176
1177 ### crypto.publicDecrypt(public_key, buffer)
1178
1179 Decrypts `buffer` with `public_key`.
1180
1181 `public_key` can be an object or a string. If `public_key` is a string, it is
1182 treated as the key with no passphrase and will use `RSA_PKCS1_PADDING`.
1183 If `public_key` is an object, it is interpreted as a hash object with the
1184 keys:
1185
1186 * `key` : {String} - PEM encoded public key
1187 * `passphrase` : {String} - Optional passphrase for the private key
1188 * `padding` : An optional padding value, one of the following:
1189   * `constants.RSA_NO_PADDING`
1190   * `constants.RSA_PKCS1_PADDING`
1191   * `constants.RSA_PKCS1_OAEP_PADDING`
1192
1193 Because RSA public keys can be derived from private keys, a private key may
1194 be passed instead of a public key.
1195
1196 All paddings are defined in the `constants` module.
1197
1198 ### crypto.publicEncrypt(public_key, buffer)
1199
1200 Encrypts `buffer` with `public_key`.
1201
1202 `public_key` can be an object or a string. If `public_key` is a string, it is
1203 treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
1204 If `public_key` is an object, it is interpreted as a hash object with the
1205 keys:
1206
1207 * `key` : {String} - PEM encoded public key
1208 * `passphrase` : {String} - Optional passphrase for the private key
1209 * `padding` : An optional padding value, one of the following:
1210   * `constants.RSA_NO_PADDING`
1211   * `constants.RSA_PKCS1_PADDING`
1212   * `constants.RSA_PKCS1_OAEP_PADDING`
1213
1214 Because RSA public keys can be derived from private keys, a private key may
1215 be passed instead of a public key.
1216
1217 All paddings are defined in the `constants` module.
1218
1219 ### crypto.randomBytes(size[, callback])
1220
1221 Generates cryptographically strong pseudo-random data. The `size` argument
1222 is a number indicating the number of bytes to generate.
1223
1224 If a `callback` function is provided, the bytes are generated asynchronously
1225 and the `callback` function is invoked with two arguments: `err` and `buf`.
1226 If an error occurs, `err` will be an Error object; otherwise it is null. The
1227 `buf` argument is a [`Buffer`][] containing the generated bytes.
1228
1229 ```js
1230 // Asynchronous
1231 const crypto = require('crypto');
1232 crypto.randomBytes(256, (err, buf) => {
1233   if (err) throw err;
1234   console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
1235 });
1236 ```
1237
1238 If the `callback` function is not provided, the random bytes are generated
1239 synchronously and returned as a [`Buffer`][]. An error will be thrown if
1240 there is a problem generating the bytes.
1241
1242 ```js
1243 // Synchronous
1244 const buf = crypto.randomBytes(256);
1245 console.log(
1246   `${buf.length}` bytes of random data: ${buf.toString('hex')});
1247 ```
1248
1249 The `crypto.randomBytes()` method will block until there is sufficient entropy.
1250 This should normally never take longer than a few milliseconds. The only time
1251 when generating the random bytes may conceivably block for a longer period of
1252 time is right after boot, when the whole system is still low on entropy.
1253
1254 ### crypto.setEngine(engine[, flags])
1255
1256 Load and set the `engine` for some or all OpenSSL functions (selected by flags).
1257
1258 `engine` could be either an id or a path to the engine's shared library.
1259
1260 The optional `flags` argument uses `ENGINE_METHOD_ALL` by default. The `flags`
1261 is a bit field taking one of or a mix of the following flags (defined in the
1262 `constants` module):
1263
1264 * `ENGINE_METHOD_RSA`
1265 * `ENGINE_METHOD_DSA`
1266 * `ENGINE_METHOD_DH`
1267 * `ENGINE_METHOD_RAND`
1268 * `ENGINE_METHOD_ECDH`
1269 * `ENGINE_METHOD_ECDSA`
1270 * `ENGINE_METHOD_CIPHERS`
1271 * `ENGINE_METHOD_DIGESTS`
1272 * `ENGINE_METHOD_STORE`
1273 * `ENGINE_METHOD_PKEY_METH`
1274 * `ENGINE_METHOD_PKEY_ASN1_METH`
1275 * `ENGINE_METHOD_ALL`
1276 * `ENGINE_METHOD_NONE`
1277
1278 ## Notes
1279
1280 ### Legacy Streams API (pre Node.js v0.10)
1281
1282 The Crypto module was added to Node.js before there was the concept of a
1283 unified Stream API, and before there were [`Buffer`][] objects for handling
1284 binary data. As such, the many of the `crypto` defined classes have methods not
1285 typically found on other Node.js classes that implement the [streams][stream]
1286 API (e.g. `update()`, `final()`, or `digest()`). Also, many methods accepted
1287 and returned `'binary'` encoded strings by default rather than Buffers. This
1288 default was changed after Node.js v0.8 to use [`Buffer`][] objects by default
1289 instead.
1290
1291 ### Recent ECDH Changes
1292
1293 Usage of `ECDH` with non-dynamically generated key pairs has been simplified.
1294 Now, [`ecdh.setPrivateKey()`][] can be called with a preselected private key
1295 and the associated public point (key) will be computed and stored in the object.
1296 This allows code to only store and provide the private part of the EC key pair.
1297 [`ecdh.setPrivateKey()`][] now also validates that the private key is valid for
1298 the selected curve.
1299
1300 The [`ecdh.setPublicKey()`][] method is now deprecated as its inclusion in the
1301 API is not useful. Either a previously stored private key should be set, which
1302 automatically generates the associated public key, or [`ecdh.generateKeys()`][]
1303 should be called. The main drawback of using [`ecdh.setPublicKey()`][] is that
1304 it can be used to put the ECDH key pair into an inconsistent state.
1305
1306 ### Support for weak or compromised algorithms
1307
1308 The `crypto` module still supports some algorithms which are already
1309 compromised and are not currently recommended for use. The API also allows
1310 the use of ciphers and hashes with a small key size that are considered to be
1311 too weak for safe use.
1312
1313 Users should take full responsibility for selecting the crypto
1314 algorithm and key size according to their security requirements.
1315
1316 Based on the recommendations of [NIST SP 800-131A][]:
1317
1318 - MD5 and SHA-1 are no longer acceptable where collision resistance is
1319   required such as digital signatures.
1320 - The key used with RSA, DSA and DH algorithms is recommended to have
1321   at least 2048 bits and that of the curve of ECDSA and ECDH at least
1322   224 bits, to be safe to use for several years.
1323 - The DH groups of `modp1`, `modp2` and `modp5` have a key size
1324   smaller than 2048 bits and are not recommended.
1325
1326 See the reference for other recommendations and details.
1327
1328 [`Buffer`]: buffer.html
1329 [`cipher.final()`]: #crypto_cipher_final_output_encoding
1330 [`cipher.update()`]: #crypto_cipher_update_data_input_encoding_output_encoding
1331 [`crypto.createCipher()`]: #crypto_crypto_createcipher_algorithm_password
1332 [`crypto.createCipheriv()`]: #crypto_crypto_createcipheriv_algorithm_key_iv
1333 [`crypto.createDecipher()`]: #crypto_crypto_createdecipher_algorithm_password
1334 [`crypto.createDecipheriv()`]: #crypto_crypto_createdecipheriv_algorithm_key_iv
1335 [`crypto.createDiffieHellman()`]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_encoding
1336 [`crypto.createECDH()`]: #crypto_crypto_createecdh_curve_name
1337 [`crypto.createHash()`]: #crypto_crypto_createhash_algorithm
1338 [`crypto.createHmac()`]: #crypto_crypto_createhmac_algorithm_key
1339 [`crypto.createSign()`]: #crypto_crypto_createsign_algorithm
1340 [`crypto.getCurves()`]: #crypto_crypto_getcurves
1341 [`crypto.getHashes()`]: #crypto_crypto_gethashes
1342 [`crypto.pbkdf2()`]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
1343 [`decipher.final()`]: #crypto_decipher_final_output_encoding
1344 [`decipher.update()`]: #crypto_decipher_update_data_input_encoding_output_encoding
1345 [`diffieHellman.setPublicKey()`]: #crypto_diffiehellman_setpublickey_public_key_encoding
1346 [`ecdh.generateKeys()`]: #crypto_ecdh_generatekeys_encoding_format
1347 [`ecdh.setPrivateKey()`]: #crypto_ecdh_setprivatekey_private_key_encoding
1348 [`ecdh.setPublicKey()`]: #crypto_ecdh_setpublickey_public_key_encoding
1349 [`EVP_BytesToKey`]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html
1350 [`hash.digest()`]: #crypto_hash_digest_encoding
1351 [`hash.update()`]: #crypto_hash_update_data_input_encoding
1352 [`hmac.digest()`]: #crypto_hmac_digest_encoding
1353 [`hmac.update()`]: #crypto_hmac_update_data
1354 [`sign.sign()`]: #crypto_sign_sign_private_key_output_format
1355 [`sign.update()`]: #crypto_sign_update_data
1356 [`tls.createSecureContext()`]: tls.html#tls_tls_createsecurecontext_details
1357 [`verify.update()`]: #crypto_verifier_update_data
1358 [`verify.verify()`]: #crypto_verifier_verify_object_signature_signature_format
1359 [Caveats]: #crypto_support_for_weak_or_compromised_algorithms
1360 [HTML5's `keygen` element]: http://www.w3.org/TR/html5/forms.html#the-keygen-element
1361 [initialization vector]: https://en.wikipedia.org/wiki/Initialization_vector
1362 [NIST SP 800-131A]: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar1.pdf
1363 [NIST SP 800-132]: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf
1364 [OpenSSL cipher list format]: https://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT
1365 [OpenSSL's SPKAC implementation]: https://www.openssl.org/docs/apps/spkac.html
1366 [publicly trusted list of CAs]: https://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
1367 [RFC 2412]: https://www.rfc-editor.org/rfc/rfc2412.txt
1368 [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
1369 [stream]: stream.html
1370 [stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback