1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 |
|
11 |
|
12 |
|
13 |
|
14 |
|
15 |
|
16 |
|
17 |
|
18 | declare module 'crypto' {
|
19 | import * as stream from 'node:stream';
|
20 | import { PeerCertificate } from 'node:tls';
|
21 | interface Certificate {
|
22 | |
23 |
|
24 |
|
25 |
|
26 |
|
27 |
|
28 | exportChallenge(spkac: BinaryLike): Buffer;
|
29 | |
30 |
|
31 |
|
32 |
|
33 |
|
34 |
|
35 |
|
36 | exportPublicKey(spkac: BinaryLike, encoding?: string): Buffer;
|
37 | |
38 |
|
39 |
|
40 |
|
41 |
|
42 |
|
43 | verifySpkac(spkac: NodeJS.ArrayBufferView): boolean;
|
44 | }
|
45 | const Certificate: Certificate & {
|
46 |
|
47 | new (): Certificate;
|
48 |
|
49 | (): Certificate;
|
50 | |
51 |
|
52 |
|
53 |
|
54 |
|
55 | exportChallenge(spkac: BinaryLike): Buffer;
|
56 | |
57 |
|
58 |
|
59 |
|
60 |
|
61 |
|
62 | exportPublicKey(spkac: BinaryLike, encoding?: string): Buffer;
|
63 | |
64 |
|
65 |
|
66 |
|
67 |
|
68 | verifySpkac(spkac: NodeJS.ArrayBufferView): boolean;
|
69 | };
|
70 | namespace constants {
|
71 |
|
72 | const OPENSSL_VERSION_NUMBER: number;
|
73 |
|
74 | const SSL_OP_ALL: number;
|
75 |
|
76 | const SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION: number;
|
77 |
|
78 | const SSL_OP_CIPHER_SERVER_PREFERENCE: number;
|
79 |
|
80 | const SSL_OP_CISCO_ANYCONNECT: number;
|
81 |
|
82 | const SSL_OP_COOKIE_EXCHANGE: number;
|
83 |
|
84 | const SSL_OP_CRYPTOPRO_TLSEXT_BUG: number;
|
85 |
|
86 | const SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS: number;
|
87 |
|
88 | const SSL_OP_EPHEMERAL_RSA: number;
|
89 |
|
90 | const SSL_OP_LEGACY_SERVER_CONNECT: number;
|
91 | const SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER: number;
|
92 | const SSL_OP_MICROSOFT_SESS_ID_BUG: number;
|
93 |
|
94 | const SSL_OP_MSIE_SSLV2_RSA_PADDING: number;
|
95 | const SSL_OP_NETSCAPE_CA_DN_BUG: number;
|
96 | const SSL_OP_NETSCAPE_CHALLENGE_BUG: number;
|
97 | const SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG: number;
|
98 | const SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG: number;
|
99 |
|
100 | const SSL_OP_NO_COMPRESSION: number;
|
101 | const SSL_OP_NO_QUERY_MTU: number;
|
102 |
|
103 | const SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION: number;
|
104 | const SSL_OP_NO_SSLv2: number;
|
105 | const SSL_OP_NO_SSLv3: number;
|
106 | const SSL_OP_NO_TICKET: number;
|
107 | const SSL_OP_NO_TLSv1: number;
|
108 | const SSL_OP_NO_TLSv1_1: number;
|
109 | const SSL_OP_NO_TLSv1_2: number;
|
110 | const SSL_OP_PKCS1_CHECK_1: number;
|
111 | const SSL_OP_PKCS1_CHECK_2: number;
|
112 |
|
113 | const SSL_OP_SINGLE_DH_USE: number;
|
114 |
|
115 | const SSL_OP_SINGLE_ECDH_USE: number;
|
116 | const SSL_OP_SSLEAY_080_CLIENT_DH_BUG: number;
|
117 | const SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG: number;
|
118 | const SSL_OP_TLS_BLOCK_PADDING_BUG: number;
|
119 | const SSL_OP_TLS_D5_BUG: number;
|
120 |
|
121 | const SSL_OP_TLS_ROLLBACK_BUG: number;
|
122 | const ENGINE_METHOD_RSA: number;
|
123 | const ENGINE_METHOD_DSA: number;
|
124 | const ENGINE_METHOD_DH: number;
|
125 | const ENGINE_METHOD_RAND: number;
|
126 | const ENGINE_METHOD_EC: number;
|
127 | const ENGINE_METHOD_CIPHERS: number;
|
128 | const ENGINE_METHOD_DIGESTS: number;
|
129 | const ENGINE_METHOD_PKEY_METHS: number;
|
130 | const ENGINE_METHOD_PKEY_ASN1_METHS: number;
|
131 | const ENGINE_METHOD_ALL: number;
|
132 | const ENGINE_METHOD_NONE: number;
|
133 | const DH_CHECK_P_NOT_SAFE_PRIME: number;
|
134 | const DH_CHECK_P_NOT_PRIME: number;
|
135 | const DH_UNABLE_TO_CHECK_GENERATOR: number;
|
136 | const DH_NOT_SUITABLE_GENERATOR: number;
|
137 | const ALPN_ENABLED: number;
|
138 | const RSA_PKCS1_PADDING: number;
|
139 | const RSA_SSLV23_PADDING: number;
|
140 | const RSA_NO_PADDING: number;
|
141 | const RSA_PKCS1_OAEP_PADDING: number;
|
142 | const RSA_X931_PADDING: number;
|
143 | const RSA_PKCS1_PSS_PADDING: number;
|
144 |
|
145 | const RSA_PSS_SALTLEN_DIGEST: number;
|
146 |
|
147 | const RSA_PSS_SALTLEN_MAX_SIGN: number;
|
148 |
|
149 | const RSA_PSS_SALTLEN_AUTO: number;
|
150 | const POINT_CONVERSION_COMPRESSED: number;
|
151 | const POINT_CONVERSION_UNCOMPRESSED: number;
|
152 | const POINT_CONVERSION_HYBRID: number;
|
153 |
|
154 | const defaultCoreCipherList: string;
|
155 |
|
156 | const defaultCipherList: string;
|
157 | }
|
158 | interface HashOptions extends stream.TransformOptions {
|
159 | |
160 |
|
161 |
|
162 |
|
163 | outputLength?: number | undefined;
|
164 | }
|
165 |
|
166 | const fips: boolean;
|
167 | |
168 |
|
169 |
|
170 |
|
171 |
|
172 |
|
173 |
|
174 |
|
175 |
|
176 |
|
177 |
|
178 |
|
179 |
|
180 |
|
181 |
|
182 |
|
183 |
|
184 |
|
185 |
|
186 |
|
187 |
|
188 |
|
189 |
|
190 |
|
191 |
|
192 |
|
193 |
|
194 |
|
195 |
|
196 |
|
197 |
|
198 |
|
199 |
|
200 |
|
201 |
|
202 |
|
203 |
|
204 |
|
205 |
|
206 |
|
207 |
|
208 | function createHash(algorithm: string, options?: HashOptions): Hash;
|
209 | |
210 |
|
211 |
|
212 |
|
213 |
|
214 |
|
215 |
|
216 |
|
217 |
|
218 |
|
219 |
|
220 |
|
221 |
|
222 |
|
223 |
|
224 |
|
225 |
|
226 |
|
227 |
|
228 |
|
229 |
|
230 |
|
231 |
|
232 |
|
233 |
|
234 |
|
235 |
|
236 |
|
237 |
|
238 |
|
239 |
|
240 |
|
241 |
|
242 |
|
243 |
|
244 |
|
245 |
|
246 |
|
247 |
|
248 |
|
249 |
|
250 |
|
251 | function createHmac(algorithm: string, key: BinaryLike | KeyObject, options?: stream.TransformOptions): Hmac;
|
252 |
|
253 | type BinaryToTextEncoding = 'base64' | 'hex';
|
254 | type CharacterEncoding = 'utf8' | 'utf-8' | 'utf16le' | 'latin1';
|
255 | type LegacyCharacterEncoding = 'ascii' | 'binary' | 'ucs2' | 'ucs-2';
|
256 | type Encoding = BinaryToTextEncoding | CharacterEncoding | LegacyCharacterEncoding;
|
257 | type ECDHKeyFormat = 'compressed' | 'uncompressed' | 'hybrid';
|
258 | |
259 |
|
260 |
|
261 |
|
262 |
|
263 |
|
264 |
|
265 |
|
266 |
|
267 |
|
268 |
|
269 |
|
270 |
|
271 |
|
272 |
|
273 |
|
274 |
|
275 |
|
276 |
|
277 |
|
278 |
|
279 |
|
280 |
|
281 |
|
282 |
|
283 |
|
284 |
|
285 |
|
286 |
|
287 |
|
288 |
|
289 |
|
290 |
|
291 |
|
292 |
|
293 |
|
294 |
|
295 |
|
296 |
|
297 |
|
298 |
|
299 |
|
300 |
|
301 |
|
302 |
|
303 |
|
304 |
|
305 |
|
306 |
|
307 |
|
308 |
|
309 |
|
310 |
|
311 |
|
312 |
|
313 |
|
314 |
|
315 |
|
316 |
|
317 |
|
318 |
|
319 |
|
320 |
|
321 |
|
322 | class Hash extends stream.Transform {
|
323 | private constructor();
|
324 | /**
|
325 | * Creates a new `Hash` object that contains a deep copy of the internal state
|
326 | * of the current `Hash` object.
|
327 | *
|
328 | * The optional `options` argument controls stream behavior. For XOF hash
|
329 | * functions such as `'shake256'`, the `outputLength` option can be used to
|
330 | * specify the desired output length in bytes.
|
331 | *
|
332 | * An error is thrown when an attempt is made to copy the `Hash` object after
|
333 | * its `hash.digest()` method has been called.
|
334 | *
|
335 | * ```js
|
336 | * // Calculate a rolling hash.
|
337 | * const {
|
338 | * createHash
|
339 | * } = await import('crypto');
|
340 | *
|
341 | * const hash = createHash('sha256');
|
342 | *
|
343 | * hash.update('one');
|
344 | * console.log(hash.copy().digest('hex'));
|
345 | *
|
346 | * hash.update('two');
|
347 | * console.log(hash.copy().digest('hex'));
|
348 | *
|
349 | * hash.update('three');
|
350 | * console.log(hash.copy().digest('hex'));
|
351 | *
|
352 | *
|
353 | * ```
|
354 | * @since v13.1.0
|
355 | * @param options `stream.transform` options
|
356 | */
|
357 | copy(options?: stream.TransformOptions): Hash;
|
358 | /**
|
359 | * Updates the hash content with the given `data`, the encoding of which
|
360 | * is given in `inputEncoding`.
|
361 | * If `encoding` is not provided, and the `data` is a string, an
|
362 | * encoding of `'utf8'` is enforced. If `data` is a `Buffer`, `TypedArray`, or`DataView`, then `inputEncoding` is ignored.
|
363 | *
|
364 | * This can be called many times with new data as it is streamed.
|
365 | * @since v0.1.92
|
366 | * @param inputEncoding The `encoding` of the `data` string.
|
367 | */
|
368 | update(data: BinaryLike): Hash;
|
369 | update(data: string, inputEncoding: Encoding): Hash;
|
370 | /**
|
371 | * Calculates the digest of all of the data passed to be hashed (using the `hash.update()` method).
|
372 | * If `encoding` is provided a string will be returned; otherwise
|
373 | * a `Buffer` is returned.
|
374 | *
|
375 | * The `Hash` object can not be used again after `hash.digest()` method has been
|
376 | * called. Multiple calls will cause an error to be thrown.
|
377 | * @since v0.1.92
|
378 | * @param encoding The `encoding` of the return value.
|
379 | */
|
380 | digest(): Buffer;
|
381 | digest(encoding: BinaryToTextEncoding): string;
|
382 | }
|
383 | /**
|
384 | * The `Hmac` class is a utility for creating cryptographic HMAC digests. It can
|
385 | * be used in one of two ways:
|
386 | *
|
387 | * * As a `stream` that is both readable and writable, where data is written
|
388 | * to produce a computed HMAC digest on the readable side, or
|
389 | * * Using the `hmac.update()` and `hmac.digest()` methods to produce the
|
390 | * computed HMAC digest.
|
391 | *
|
392 | * The {@link createHmac} method is used to create `Hmac` instances. `Hmac`objects are not to be created directly using the `new` keyword.
|
393 | *
|
394 | * Example: Using `Hmac` objects as streams:
|
395 | *
|
396 | * ```js
|
397 | * const {
|
398 | * createHmac
|
399 | * } = await import('crypto');
|
400 | *
|
401 | * const hmac = createHmac('sha256', 'a secret');
|
402 | *
|
403 | * hmac.on('readable', () => {
|
404 | *
|
405 | *
|
406 | * const data = hmac.read();
|
407 | * if (data) {
|
408 | * console.log(data.toString('hex'));
|
409 | *
|
410 | *
|
411 | * }
|
412 | * });
|
413 | *
|
414 | * hmac.write('some data to hash');
|
415 | * hmac.end();
|
416 | * ```
|
417 | *
|
418 | * Example: Using `Hmac` and piped streams:
|
419 | *
|
420 | * ```js
|
421 | * import { createReadStream } from 'fs';
|
422 | * import { stdout } from 'process';
|
423 | * const {
|
424 | * createHmac
|
425 | * } = await import('crypto');
|
426 | *
|
427 | * const hmac = createHmac('sha256', 'a secret');
|
428 | *
|
429 | * const input = createReadStream('test.js');
|
430 | * input.pipe(hmac).pipe(stdout);
|
431 | * ```
|
432 | *
|
433 | * Example: Using the `hmac.update()` and `hmac.digest()` methods:
|
434 | *
|
435 | * ```js
|
436 | * const {
|
437 | * createHmac
|
438 | * } = await import('crypto');
|
439 | *
|
440 | * const hmac = createHmac('sha256', 'a secret');
|
441 | *
|
442 | * hmac.update('some data to hash');
|
443 | * console.log(hmac.digest('hex'));
|
444 | *
|
445 | *
|
446 | * ```
|
447 | * @since v0.1.94
|
448 | */
|
449 | class Hmac extends stream.Transform {
|
450 | private constructor();
|
451 | /**
|
452 | * Updates the `Hmac` content with the given `data`, the encoding of which
|
453 | * is given in `inputEncoding`.
|
454 | * If `encoding` is not provided, and the `data` is a string, an
|
455 | * encoding of `'utf8'` is enforced. If `data` is a `Buffer`, `TypedArray`, or`DataView`, then `inputEncoding` is ignored.
|
456 | *
|
457 | * This can be called many times with new data as it is streamed.
|
458 | * @since v0.1.94
|
459 | * @param inputEncoding The `encoding` of the `data` string.
|
460 | */
|
461 | update(data: BinaryLike): Hmac;
|
462 | update(data: string, inputEncoding: Encoding): Hmac;
|
463 | /**
|
464 | * Calculates the HMAC digest of all of the data passed using `hmac.update()`.
|
465 | * If `encoding` is
|
466 | * provided a string is returned; otherwise a `Buffer` is returned;
|
467 | *
|
468 | * The `Hmac` object can not be used again after `hmac.digest()` has been
|
469 | * called. Multiple calls to `hmac.digest()` will result in an error being thrown.
|
470 | * @since v0.1.94
|
471 | * @param encoding The `encoding` of the return value.
|
472 | */
|
473 | digest(): Buffer;
|
474 | digest(encoding: BinaryToTextEncoding): string;
|
475 | }
|
476 | type KeyObjectType = 'secret' | 'public' | 'private';
|
477 | interface KeyExportOptions<T extends KeyFormat> {
|
478 | type: 'pkcs1' | 'spki' | 'pkcs8' | 'sec1';
|
479 | format: T;
|
480 | cipher?: string | undefined;
|
481 | passphrase?: string | Buffer | undefined;
|
482 | }
|
483 | interface JwkKeyExportOptions {
|
484 | format: 'jwk';
|
485 | }
|
486 | interface JsonWebKey {
|
487 | crv?: string | undefined;
|
488 | d?: string | undefined;
|
489 | dp?: string | undefined;
|
490 | dq?: string | undefined;
|
491 | e?: string | undefined;
|
492 | k?: string | undefined;
|
493 | kty?: string | undefined;
|
494 | n?: string | undefined;
|
495 | p?: string | undefined;
|
496 | q?: string | undefined;
|
497 | qi?: string | undefined;
|
498 | x?: string | undefined;
|
499 | y?: string | undefined;
|
500 | [key: string]: unknown;
|
501 | }
|
502 | interface AsymmetricKeyDetails {
|
503 | /**
|
504 | * Key size in bits (RSA, DSA).
|
505 | */
|
506 | modulusLength?: number | undefined;
|
507 | /**
|
508 | * Public exponent (RSA).
|
509 | */
|
510 | publicExponent?: bigint | undefined;
|
511 | /**
|
512 | * Size of q in bits (DSA).
|
513 | */
|
514 | divisorLength?: number | undefined;
|
515 | /**
|
516 | * Name of the curve (EC).
|
517 | */
|
518 | namedCurve?: string | undefined;
|
519 | }
|
520 | interface JwkKeyExportOptions {
|
521 | format: 'jwk';
|
522 | }
|
523 | /**
|
524 | * Node.js uses a `KeyObject` class to represent a symmetric or asymmetric key,
|
525 | * and each kind of key exposes different functions. The {@link createSecretKey}, {@link createPublicKey} and {@link createPrivateKey} methods are used to create `KeyObject`instances. `KeyObject`
|
526 | * objects are not to be created directly using the `new`keyword.
|
527 | *
|
528 | * Most applications should consider using the new `KeyObject` API instead of
|
529 | * passing keys as strings or `Buffer`s due to improved security features.
|
530 | *
|
531 | * `KeyObject` instances can be passed to other threads via `postMessage()`.
|
532 | * The receiver obtains a cloned `KeyObject`, and the `KeyObject` does not need to
|
533 | * be listed in the `transferList` argument.
|
534 | * @since v11.6.0
|
535 | */
|
536 | class KeyObject {
|
537 | private constructor();
|
538 | /**
|
539 | * For asymmetric keys, this property represents the type of the key. Supported key
|
540 | * types are:
|
541 | *
|
542 | * * `'rsa'` (OID 1.2.840.113549.1.1.1)
|
543 | * * `'rsa-pss'` (OID 1.2.840.113549.1.1.10)
|
544 | * * `'dsa'` (OID 1.2.840.10040.4.1)
|
545 | * * `'ec'` (OID 1.2.840.10045.2.1)
|
546 | * * `'x25519'` (OID 1.3.101.110)
|
547 | * * `'x448'` (OID 1.3.101.111)
|
548 | * * `'ed25519'` (OID 1.3.101.112)
|
549 | * * `'ed448'` (OID 1.3.101.113)
|
550 | * * `'dh'` (OID 1.2.840.113549.1.3.1)
|
551 | *
|
552 | * This property is `undefined` for unrecognized `KeyObject` types and symmetric
|
553 | * keys.
|
554 | * @since v11.6.0
|
555 | */
|
556 | asymmetricKeyType?: KeyType | undefined;
|
557 | /**
|
558 | * For asymmetric keys, this property represents the size of the embedded key in
|
559 | * bytes. This property is `undefined` for symmetric keys.
|
560 | */
|
561 | asymmetricKeySize?: number | undefined;
|
562 | /**
|
563 | * This property exists only on asymmetric keys. Depending on the type of the key,
|
564 | * this object contains information about the key. None of the information obtained
|
565 | * through this property can be used to uniquely identify a key or to compromise
|
566 | * the security of the key.
|
567 | *
|
568 | * RSA-PSS parameters, DH, or any future key type details might be exposed via this
|
569 | * API using additional attributes.
|
570 | * @since v15.7.0
|
571 | */
|
572 | asymmetricKeyDetails?: AsymmetricKeyDetails | undefined;
|
573 | /**
|
574 | * For symmetric keys, the following encoding options can be used:
|
575 | *
|
576 | * For public keys, the following encoding options can be used:
|
577 | *
|
578 | * For private keys, the following encoding options can be used:
|
579 | *
|
580 | * The result type depends on the selected encoding format, when PEM the
|
581 | * result is a string, when DER it will be a buffer containing the data
|
582 | * encoded as DER, when [JWK](https://tools.ietf.org/html/rfc7517) it will be an object.
|
583 | *
|
584 | * When [JWK](https://tools.ietf.org/html/rfc7517) encoding format was selected, all other encoding options are
|
585 | * ignored.
|
586 | *
|
587 | * PKCS#1, SEC1, and PKCS#8 type keys can be encrypted by using a combination of
|
588 | * the `cipher` and `format` options. The PKCS#8 `type` can be used with any`format` to encrypt any key algorithm (RSA, EC, or DH) by specifying a`cipher`. PKCS#1 and SEC1 can only be
|
589 | * encrypted by specifying a `cipher`when the PEM `format` is used. For maximum compatibility, use PKCS#8 for
|
590 | * encrypted private keys. Since PKCS#8 defines its own
|
591 | * encryption mechanism, PEM-level encryption is not supported when encrypting
|
592 | * a PKCS#8 key. See [RFC 5208](https://www.rfc-editor.org/rfc/rfc5208.txt) for PKCS#8 encryption and [RFC 1421](https://www.rfc-editor.org/rfc/rfc1421.txt) for
|
593 | * PKCS#1 and SEC1 encryption.
|
594 | * @since v11.6.0
|
595 | */
|
596 | export(options: KeyExportOptions<'pem'>): string | Buffer;
|
597 | export(options?: KeyExportOptions<'der'>): Buffer;
|
598 | export(options?: JwkKeyExportOptions): JsonWebKey;
|
599 | /**
|
600 | * For secret keys, this property represents the size of the key in bytes. This
|
601 | * property is `undefined` for asymmetric keys.
|
602 | * @since v11.6.0
|
603 | */
|
604 | symmetricKeySize?: number | undefined;
|
605 | /**
|
606 | * Depending on the type of this `KeyObject`, this property is either`'secret'` for secret (symmetric) keys, `'public'` for public (asymmetric) keys
|
607 | * or `'private'` for private (asymmetric) keys.
|
608 | * @since v11.6.0
|
609 | */
|
610 | type: KeyObjectType;
|
611 | }
|
612 | type CipherCCMTypes = 'aes-128-ccm' | 'aes-192-ccm' | 'aes-256-ccm' | 'chacha20-poly1305';
|
613 | type CipherGCMTypes = 'aes-128-gcm' | 'aes-192-gcm' | 'aes-256-gcm';
|
614 | type BinaryLike = string | NodeJS.ArrayBufferView;
|
615 | type CipherKey = BinaryLike | KeyObject;
|
616 | interface CipherCCMOptions extends stream.TransformOptions {
|
617 | authTagLength: number;
|
618 | }
|
619 | interface CipherGCMOptions extends stream.TransformOptions {
|
620 | authTagLength?: number | undefined;
|
621 | }
|
622 | /**
|
623 | * Creates and returns a `Cipher` object that uses the given `algorithm` and`password`.
|
624 | *
|
625 | * The `options` argument controls stream behavior and is optional except when a
|
626 | * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the
|
627 | * authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication
|
628 | * tag that will be returned by `getAuthTag()` and defaults to 16 bytes.
|
629 | *
|
630 | * The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
|
631 | * recent OpenSSL releases, `openssl list -cipher-algorithms`(`openssl list-cipher-algorithms` for older versions of OpenSSL) will
|
632 | * display the available cipher algorithms.
|
633 | *
|
634 | * The `password` is used to derive the cipher key and initialization vector (IV).
|
635 | * The value must be either a `'latin1'` encoded string, a `Buffer`, a`TypedArray`, or a `DataView`.
|
636 | *
|
637 | * The implementation of `crypto.createCipher()` derives keys using the OpenSSL
|
638 | * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) with the digest algorithm set to MD5, one
|
639 | * iteration, and no salt. The lack of salt allows dictionary attacks as the same
|
640 | * password always creates the same key. The low iteration count and
|
641 | * non-cryptographically secure hash algorithm allow passwords to be tested very
|
642 | * rapidly.
|
643 | *
|
644 | * In line with OpenSSL's recommendation to use a more modern algorithm instead of[`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) it is recommended that
|
645 | * developers derive a key and IV on
|
646 | * their own using {@link scrypt} and to use {@link createCipheriv} to create the `Cipher` object. Users should not use ciphers with counter mode
|
647 | * (e.g. CTR, GCM, or CCM) in `crypto.createCipher()`. A warning is emitted when
|
648 | * they are used in order to avoid the risk of IV reuse that causes
|
649 | * vulnerabilities. For the case when IV is reused in GCM, see [Nonce-Disrespecting Adversaries](https://github.com/nonce-disrespect/nonce-disrespect) for details.
|
650 | * @since v0.1.94
|
651 | * @deprecated Since v10.0.0 - Use {@link createCipheriv} instead.
|
652 | * @param options `stream.transform` options
|
653 | */
|
654 | function createCipher(algorithm: CipherCCMTypes, password: BinaryLike, options: CipherCCMOptions): CipherCCM;
|
655 | /** @deprecated since v10.0.0 use `createCipheriv()` */
|
656 | function createCipher(algorithm: CipherGCMTypes, password: BinaryLike, options?: CipherGCMOptions): CipherGCM;
|
657 | /** @deprecated since v10.0.0 use `createCipheriv()` */
|
658 | function createCipher(algorithm: string, password: BinaryLike, options?: stream.TransformOptions): Cipher;
|
659 | /**
|
660 | * Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
|
661 | * initialization vector (`iv`).
|
662 | *
|
663 | * The `options` argument controls stream behavior and is optional except when a
|
664 | * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the
|
665 | * authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication
|
666 | * tag that will be returned by `getAuthTag()` and defaults to 16 bytes.
|
667 | *
|
668 | * The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
|
669 | * recent OpenSSL releases, `openssl list -cipher-algorithms`(`openssl list-cipher-algorithms` for older versions of OpenSSL) will
|
670 | * display the available cipher algorithms.
|
671 | *
|
672 | * The `key` is the raw key used by the `algorithm` and `iv` is an[initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
|
673 | * strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
|
674 | * a `KeyObject` of type `secret`. If the cipher does not need
|
675 | * an initialization vector, `iv` may be `null`.
|
676 | *
|
677 | * When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.
|
678 | *
|
679 | * Initialization vectors should be unpredictable and unique; ideally, they will be
|
680 | * cryptographically random. They do not have to be secret: IVs are typically just
|
681 | * added to ciphertext messages unencrypted. It may sound contradictory that
|
682 | * something has to be unpredictable and unique, but does not have to be secret;
|
683 | * remember that an attacker must not be able to predict ahead of time what a
|
684 | * given IV will be.
|
685 | * @since v0.1.94
|
686 | * @param options `stream.transform` options
|
687 | */
|
688 | function createCipheriv(algorithm: CipherCCMTypes, key: CipherKey, iv: BinaryLike | null, options: CipherCCMOptions): CipherCCM;
|
689 | function createCipheriv(algorithm: CipherGCMTypes, key: CipherKey, iv: BinaryLike | null, options?: CipherGCMOptions): CipherGCM;
|
690 | function createCipheriv(algorithm: string, key: CipherKey, iv: BinaryLike | null, options?: stream.TransformOptions): Cipher;
|
691 | /**
|
692 | * Instances of the `Cipher` class are used to encrypt data. The class can be
|
693 | * used in one of two ways:
|
694 | *
|
695 | * * As a `stream` that is both readable and writable, where plain unencrypted
|
696 | * data is written to produce encrypted data on the readable side, or
|
697 | * * Using the `cipher.update()` and `cipher.final()` methods to produce
|
698 | * the encrypted data.
|
699 | *
|
700 | * The {@link createCipher} or {@link createCipheriv} methods are
|
701 | * used to create `Cipher` instances. `Cipher` objects are not to be created
|
702 | * directly using the `new` keyword.
|
703 | *
|
704 | * Example: Using `Cipher` objects as streams:
|
705 | *
|
706 | * ```js
|
707 | * const {
|
708 | * scrypt,
|
709 | * randomFill,
|
710 | * createCipheriv
|
711 | * } = await import('crypto');
|
712 | *
|
713 | * const algorithm = 'aes-192-cbc';
|
714 | * const password = 'Password used to generate key';
|
715 | *
|
716 | *
|
717 | *
|
718 | * scrypt(password, 'salt', 24, (err, key) => {
|
719 | * if (err) throw err;
|
720 | *
|
721 | * randomFill(new Uint8Array(16), (err, iv) => {
|
722 | * if (err) throw err;
|
723 | *
|
724 | *
|
725 | * const cipher = createCipheriv(algorithm, key, iv);
|
726 | *
|
727 | * let encrypted = '';
|
728 | * cipher.setEncoding('hex');
|
729 | *
|
730 | * cipher.on('data', (chunk) => encrypted += chunk);
|
731 | * cipher.on('end', () => console.log(encrypted));
|
732 | *
|
733 | * cipher.write('some clear text data');
|
734 | * cipher.end();
|
735 | * });
|
736 | * });
|
737 | * ```
|
738 | *
|
739 | * Example: Using `Cipher` and piped streams:
|
740 | *
|
741 | * ```js
|
742 | * import {
|
743 | * createReadStream,
|
744 | * createWriteStream,
|
745 | * } from 'fs';
|
746 | *
|
747 | * import {
|
748 | * pipeline
|
749 | * } from 'stream';
|
750 | *
|
751 | * const {
|
752 | * scrypt,
|
753 | * randomFill,
|
754 | * createCipheriv
|
755 | * } = await import('crypto');
|
756 | *
|
757 | * const algorithm = 'aes-192-cbc';
|
758 | * const password = 'Password used to generate key';
|
759 | *
|
760 | *
|
761 | *
|
762 | * scrypt(password, 'salt', 24, (err, key) => {
|
763 | * if (err) throw err;
|
764 | *
|
765 | * randomFill(new Uint8Array(16), (err, iv) => {
|
766 | * if (err) throw err;
|
767 | *
|
768 | * const cipher = createCipheriv(algorithm, key, iv);
|
769 | *
|
770 | * const input = createReadStream('test.js');
|
771 | * const output = createWriteStream('test.enc');
|
772 | *
|
773 | * pipeline(input, cipher, output, (err) => {
|
774 | * if (err) throw err;
|
775 | * });
|
776 | * });
|
777 | * });
|
778 | * ```
|
779 | *
|
780 | * Example: Using the `cipher.update()` and `cipher.final()` methods:
|
781 | *
|
782 | * ```js
|
783 | * const {
|
784 | * scrypt,
|
785 | * randomFill,
|
786 | * createCipheriv
|
787 | * } = await import('crypto');
|
788 | *
|
789 | * const algorithm = 'aes-192-cbc';
|
790 | * const password = 'Password used to generate key';
|
791 | *
|
792 | *
|
793 | *
|
794 | * scrypt(password, 'salt', 24, (err, key) => {
|
795 | * if (err) throw err;
|
796 | *
|
797 | * randomFill(new Uint8Array(16), (err, iv) => {
|
798 | * if (err) throw err;
|
799 | *
|
800 | * const cipher = createCipheriv(algorithm, key, iv);
|
801 | *
|
802 | * let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
|
803 | * encrypted += cipher.final('hex');
|
804 | * console.log(encrypted);
|
805 | * });
|
806 | * });
|
807 | * ```
|
808 | * @since v0.1.94
|
809 | */
|
810 | class Cipher extends stream.Transform {
|
811 | private constructor();
|
812 | /**
|
813 | * Updates the cipher with `data`. If the `inputEncoding` argument is given,
|
814 | * the `data`argument is a string using the specified encoding. If the `inputEncoding`argument is not given, `data` must be a `Buffer`, `TypedArray`, or`DataView`. If `data` is a `Buffer`,
|
815 | * `TypedArray`, or `DataView`, then`inputEncoding` is ignored.
|
816 | *
|
817 | * The `outputEncoding` specifies the output format of the enciphered
|
818 | * data. If the `outputEncoding`is specified, a string using the specified encoding is returned. If no`outputEncoding` is provided, a `Buffer` is returned.
|
819 | *
|
820 | * The `cipher.update()` method can be called multiple times with new data until `cipher.final()` is called. Calling `cipher.update()` after `cipher.final()` will result in an error being
|
821 | * thrown.
|
822 | * @since v0.1.94
|
823 | * @param inputEncoding The `encoding` of the data.
|
824 | * @param outputEncoding The `encoding` of the return value.
|
825 | */
|
826 | update(data: BinaryLike): Buffer;
|
827 | update(data: string, inputEncoding: Encoding): Buffer;
|
828 | update(data: NodeJS.ArrayBufferView, inputEncoding: undefined, outputEncoding: Encoding): string;
|
829 | update(data: string, inputEncoding: Encoding | undefined, outputEncoding: Encoding): string;
|
830 | /**
|
831 | * Once the `cipher.final()` method has been called, the `Cipher` object can no
|
832 | * longer be used to encrypt data. Attempts to call `cipher.final()` more than
|
833 | * once will result in an error being thrown.
|
834 | * @since v0.1.94
|
835 | * @param outputEncoding The `encoding` of the return value.
|
836 | * @return Any remaining enciphered contents. If `outputEncoding` is specified, a string is returned. If an `outputEncoding` is not provided, a {@link Buffer} is returned.
|
837 | */
|
838 | final(): Buffer;
|
839 | final(outputEncoding: BufferEncoding): string;
|
840 | /**
|
841 | * When using block encryption algorithms, the `Cipher` class will automatically
|
842 | * add padding to the input data to the appropriate block size. To disable the
|
843 | * default padding call `cipher.setAutoPadding(false)`.
|
844 | *
|
845 | * When `autoPadding` is `false`, the length of the entire input data must be a
|
846 | * multiple of the cipher's block size or `cipher.final()` will throw an error.
|
847 | * Disabling automatic padding is useful for non-standard padding, for instance
|
848 | * using `0x0` instead of PKCS padding.
|
849 | *
|
850 | * The `cipher.setAutoPadding()` method must be called before `cipher.final()`.
|
851 | * @since v0.7.1
|
852 | * @param [autoPadding=true]
|
853 | * @return for method chaining.
|
854 | */
|
855 | setAutoPadding(autoPadding?: boolean): this;
|
856 | }
|
857 | interface CipherCCM extends Cipher {
|
858 | setAAD(
|
859 | buffer: NodeJS.ArrayBufferView,
|
860 | options: {
|
861 | plaintextLength: number;
|
862 | }
|
863 | ): this;
|
864 | getAuthTag(): Buffer;
|
865 | }
|
866 | interface CipherGCM extends Cipher {
|
867 | setAAD(
|
868 | buffer: NodeJS.ArrayBufferView,
|
869 | options?: {
|
870 | plaintextLength: number;
|
871 | }
|
872 | ): this;
|
873 | getAuthTag(): Buffer;
|
874 | }
|
875 | /**
|
876 | * Creates and returns a `Decipher` object that uses the given `algorithm` and`password` (key).
|
877 | *
|
878 | * The `options` argument controls stream behavior and is optional except when a
|
879 | * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the
|
880 | * authentication tag in bytes, see `CCM mode`.
|
881 | *
|
882 | * The implementation of `crypto.createDecipher()` derives keys using the OpenSSL
|
883 | * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) with the digest algorithm set to MD5, one
|
884 | * iteration, and no salt. The lack of salt allows dictionary attacks as the same
|
885 | * password always creates the same key. The low iteration count and
|
886 | * non-cryptographically secure hash algorithm allow passwords to be tested very
|
887 | * rapidly.
|
888 | *
|
889 | * In line with OpenSSL's recommendation to use a more modern algorithm instead of[`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) it is recommended that
|
890 | * developers derive a key and IV on
|
891 | * their own using {@link scrypt} and to use {@link createDecipheriv} to create the `Decipher` object.
|
892 | * @since v0.1.94
|
893 | * @deprecated Since v10.0.0 - Use {@link createDecipheriv} instead.
|
894 | * @param options `stream.transform` options
|
895 | */
|
896 | function createDecipher(algorithm: CipherCCMTypes, password: BinaryLike, options: CipherCCMOptions): DecipherCCM;
|
897 | /** @deprecated since v10.0.0 use `createDecipheriv()` */
|
898 | function createDecipher(algorithm: CipherGCMTypes, password: BinaryLike, options?: CipherGCMOptions): DecipherGCM;
|
899 | /** @deprecated since v10.0.0 use `createDecipheriv()` */
|
900 | function createDecipher(algorithm: string, password: BinaryLike, options?: stream.TransformOptions): Decipher;
|
901 | /**
|
902 | * Creates and returns a `Decipher` object that uses the given `algorithm`, `key`and initialization vector (`iv`).
|
903 | *
|
904 | * The `options` argument controls stream behavior and is optional except when a
|
905 | * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the
|
906 | * authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to restrict accepted authentication tags
|
907 | * to those with the specified length.
|
908 | *
|
909 | * The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
|
910 | * recent OpenSSL releases, `openssl list -cipher-algorithms`(`openssl list-cipher-algorithms` for older versions of OpenSSL) will
|
911 | * display the available cipher algorithms.
|
912 | *
|
913 | * The `key` is the raw key used by the `algorithm` and `iv` is an[initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
|
914 | * strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
|
915 | * a `KeyObject` of type `secret`. If the cipher does not need
|
916 | * an initialization vector, `iv` may be `null`.
|
917 | *
|
918 | * When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.
|
919 | *
|
920 | * Initialization vectors should be unpredictable and unique; ideally, they will be
|
921 | * cryptographically random. They do not have to be secret: IVs are typically just
|
922 | * added to ciphertext messages unencrypted. It may sound contradictory that
|
923 | * something has to be unpredictable and unique, but does not have to be secret;
|
924 | * remember that an attacker must not be able to predict ahead of time what a given
|
925 | * IV will be.
|
926 | * @since v0.1.94
|
927 | * @param options `stream.transform` options
|
928 | */
|
929 | function createDecipheriv(algorithm: CipherCCMTypes, key: CipherKey, iv: BinaryLike | null, options: CipherCCMOptions): DecipherCCM;
|
930 | function createDecipheriv(algorithm: CipherGCMTypes, key: CipherKey, iv: BinaryLike | null, options?: CipherGCMOptions): DecipherGCM;
|
931 | function createDecipheriv(algorithm: string, key: CipherKey, iv: BinaryLike | null, options?: stream.TransformOptions): Decipher;
|
932 | /**
|
933 | * Instances of the `Decipher` class are used to decrypt data. The class can be
|
934 | * used in one of two ways:
|
935 | *
|
936 | * * As a `stream` that is both readable and writable, where plain encrypted
|
937 | * data is written to produce unencrypted data on the readable side, or
|
938 | * * Using the `decipher.update()` and `decipher.final()` methods to
|
939 | * produce the unencrypted data.
|
940 | *
|
941 | * The {@link createDecipher} or {@link createDecipheriv} methods are
|
942 | * used to create `Decipher` instances. `Decipher` objects are not to be created
|
943 | * directly using the `new` keyword.
|
944 | *
|
945 | * Example: Using `Decipher` objects as streams:
|
946 | *
|
947 | * ```js
|
948 | * import { Buffer } from 'buffer';
|
949 | * const {
|
950 | * scryptSync,
|
951 | * createDecipheriv
|
952 | * } = await import('crypto');
|
953 | *
|
954 | * const algorithm = 'aes-192-cbc';
|
955 | * const password = 'Password used to generate key';
|
956 | *
|
957 | *
|
958 | *
|
959 | * const key = scryptSync(password, 'salt', 24);
|
960 | *
|
961 | * const iv = Buffer.alloc(16, 0);
|
962 | *
|
963 | * const decipher = createDecipheriv(algorithm, key, iv);
|
964 | *
|
965 | * let decrypted = '';
|
966 | * decipher.on('readable', () => {
|
967 | * while (null !== (chunk = decipher.read())) {
|
968 | * decrypted += chunk.toString('utf8');
|
969 | * }
|
970 | * });
|
971 | * decipher.on('end', () => {
|
972 | * console.log(decrypted);
|
973 | *
|
974 | * });
|
975 | *
|
976 | *
|
977 | * const encrypted =
|
978 | * 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
|
979 | * decipher.write(encrypted, 'hex');
|
980 | * decipher.end();
|
981 | * ```
|
982 | *
|
983 | * Example: Using `Decipher` and piped streams:
|
984 | *
|
985 | * ```js
|
986 | * import {
|
987 | * createReadStream,
|
988 | * createWriteStream,
|
989 | * } from 'fs';
|
990 | * import { Buffer } from 'buffer';
|
991 | * const {
|
992 | * scryptSync,
|
993 | * createDecipheriv
|
994 | * } = await import('crypto');
|
995 | *
|
996 | * const algorithm = 'aes-192-cbc';
|
997 | * const password = 'Password used to generate key';
|
998 | *
|
999 | * const key = scryptSync(password, 'salt', 24);
|
1000 | *
|
1001 | * const iv = Buffer.alloc(16, 0);
|
1002 | *
|
1003 | * const decipher = createDecipheriv(algorithm, key, iv);
|
1004 | *
|
1005 | * const input = createReadStream('test.enc');
|
1006 | * const output = createWriteStream('test.js');
|
1007 | *
|
1008 | * input.pipe(decipher).pipe(output);
|
1009 | * ```
|
1010 | *
|
1011 | * Example: Using the `decipher.update()` and `decipher.final()` methods:
|
1012 | *
|
1013 | * ```js
|
1014 | * import { Buffer } from 'buffer';
|
1015 | * const {
|
1016 | * scryptSync,
|
1017 | * createDecipheriv
|
1018 | * } = await import('crypto');
|
1019 | *
|
1020 | * const algorithm = 'aes-192-cbc';
|
1021 | * const password = 'Password used to generate key';
|
1022 | *
|
1023 | * const key = scryptSync(password, 'salt', 24);
|
1024 | *
|
1025 | * const iv = Buffer.alloc(16, 0);
|
1026 | *
|
1027 | * const decipher = createDecipheriv(algorithm, key, iv);
|
1028 | *
|
1029 | *
|
1030 | * const encrypted =
|
1031 | * 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
|
1032 | * let decrypted = decipher.update(encrypted, 'hex', 'utf8');
|
1033 | * decrypted += decipher.final('utf8');
|
1034 | * console.log(decrypted);
|
1035 | *
|
1036 | * ```
|
1037 | * @since v0.1.94
|
1038 | */
|
1039 | class Decipher extends stream.Transform {
|
1040 | private constructor();
|
1041 | /**
|
1042 | * Updates the decipher with `data`. If the `inputEncoding` argument is given,
|
1043 | * the `data`argument is a string using the specified encoding. If the `inputEncoding`argument is not given, `data` must be a `Buffer`. If `data` is a `Buffer` then `inputEncoding` is
|
1044 | * ignored.
|
1045 | *
|
1046 | * The `outputEncoding` specifies the output format of the enciphered
|
1047 | * data. If the `outputEncoding`is specified, a string using the specified encoding is returned. If no`outputEncoding` is provided, a `Buffer` is returned.
|
1048 | *
|
1049 | * The `decipher.update()` method can be called multiple times with new data until `decipher.final()` is called. Calling `decipher.update()` after `decipher.final()` will result in an error
|
1050 | * being thrown.
|
1051 | * @since v0.1.94
|
1052 | * @param inputEncoding The `encoding` of the `data` string.
|
1053 | * @param outputEncoding The `encoding` of the return value.
|
1054 | */
|
1055 | update(data: NodeJS.ArrayBufferView): Buffer;
|
1056 | update(data: string, inputEncoding: Encoding): Buffer;
|
1057 | update(data: NodeJS.ArrayBufferView, inputEncoding: undefined, outputEncoding: Encoding): string;
|
1058 | update(data: string, inputEncoding: Encoding | undefined, outputEncoding: Encoding): string;
|
1059 | /**
|
1060 | * Once the `decipher.final()` method has been called, the `Decipher` object can
|
1061 | * no longer be used to decrypt data. Attempts to call `decipher.final()` more
|
1062 | * than once will result in an error being thrown.
|
1063 | * @since v0.1.94
|
1064 | * @param outputEncoding The `encoding` of the return value.
|
1065 | * @return Any remaining deciphered contents. If `outputEncoding` is specified, a string is returned. If an `outputEncoding` is not provided, a {@link Buffer} is returned.
|
1066 | */
|
1067 | final(): Buffer;
|
1068 | final(outputEncoding: BufferEncoding): string;
|
1069 | /**
|
1070 | * When data has been encrypted without standard block padding, calling`decipher.setAutoPadding(false)` will disable automatic padding to prevent `decipher.final()` from checking for and
|
1071 | * removing padding.
|
1072 | *
|
1073 | * Turning auto padding off will only work if the input data's length is a
|
1074 | * multiple of the ciphers block size.
|
1075 | *
|
1076 | * The `decipher.setAutoPadding()` method must be called before `decipher.final()`.
|
1077 | * @since v0.7.1
|
1078 | * @param [autoPadding=true]
|
1079 | * @return for method chaining.
|
1080 | */
|
1081 | setAutoPadding(auto_padding?: boolean): this;
|
1082 | }
|
1083 | interface DecipherCCM extends Decipher {
|
1084 | setAuthTag(buffer: NodeJS.ArrayBufferView): this;
|
1085 | setAAD(
|
1086 | buffer: NodeJS.ArrayBufferView,
|
1087 | options: {
|
1088 | plaintextLength: number;
|
1089 | }
|
1090 | ): this;
|
1091 | }
|
1092 | interface DecipherGCM extends Decipher {
|
1093 | setAuthTag(buffer: NodeJS.ArrayBufferView): this;
|
1094 | setAAD(
|
1095 | buffer: NodeJS.ArrayBufferView,
|
1096 | options?: {
|
1097 | plaintextLength: number;
|
1098 | }
|
1099 | ): this;
|
1100 | }
|
1101 | interface PrivateKeyInput {
|
1102 | key: string | Buffer;
|
1103 | format?: KeyFormat | undefined;
|
1104 | type?: 'pkcs1' | 'pkcs8' | 'sec1' | undefined;
|
1105 | passphrase?: string | Buffer | undefined;
|
1106 | }
|
1107 | interface PublicKeyInput {
|
1108 | key: string | Buffer;
|
1109 | format?: KeyFormat | undefined;
|
1110 | type?: 'pkcs1' | 'spki' | undefined;
|
1111 | }
|
1112 | /**
|
1113 | * Asynchronously generates a new random secret key of the given `length`. The`type` will determine which validations will be performed on the `length`.
|
1114 | *
|
1115 | * ```js
|
1116 | * const {
|
1117 | * generateKey
|
1118 | * } = await import('crypto');
|
1119 | *
|
1120 | * generateKey('hmac', { length: 64 }, (err, key) => {
|
1121 | * if (err) throw err;
|
1122 | * console.log(key.export().toString('hex'));
|
1123 | * });
|
1124 | * ```
|
1125 | * @since v15.0.0
|
1126 | * @param type The intended use of the generated secret key. Currently accepted values are `'hmac'` and `'aes'`.
|
1127 | */
|
1128 | function generateKey(
|
1129 | type: 'hmac' | 'aes',
|
1130 | options: {
|
1131 | length: number;
|
1132 | },
|
1133 | callback: (err: Error | null, key: KeyObject) => void
|
1134 | ): void;
|
1135 | interface JsonWebKeyInput {
|
1136 | key: JsonWebKey;
|
1137 | format: 'jwk';
|
1138 | }
|
1139 | /**
|
1140 | * Creates and returns a new key object containing a private key. If `key` is a
|
1141 | * string or `Buffer`, `format` is assumed to be `'pem'`; otherwise, `key`must be an object with the properties described above.
|
1142 | *
|
1143 | * If the private key is encrypted, a `passphrase` must be specified. The length
|
1144 | * of the passphrase is limited to 1024 bytes.
|
1145 | * @since v11.6.0
|
1146 | */
|
1147 | function createPrivateKey(key: PrivateKeyInput | string | Buffer | JsonWebKeyInput): KeyObject;
|
1148 | /**
|
1149 | * Creates and returns a new key object containing a public key. If `key` is a
|
1150 | * string or `Buffer`, `format` is assumed to be `'pem'`; if `key` is a `KeyObject`with type `'private'`, the public key is derived from the given private key;
|
1151 | * otherwise, `key` must be an object with the properties described above.
|
1152 | *
|
1153 | * If the format is `'pem'`, the `'key'` may also be an X.509 certificate.
|
1154 | *
|
1155 | * Because public keys can be derived from private keys, a private key may be
|
1156 | * passed instead of a public key. In that case, this function behaves as if {@link createPrivateKey} had been called, except that the type of the
|
1157 | * returned `KeyObject` will be `'public'` and that the private key cannot be
|
1158 | * extracted from the returned `KeyObject`. Similarly, if a `KeyObject` with type`'private'` is given, a new `KeyObject` with type `'public'` will be returned
|
1159 | * and it will be impossible to extract the private key from the returned object.
|
1160 | * @since v11.6.0
|
1161 | */
|
1162 | function createPublicKey(key: PublicKeyInput | string | Buffer | KeyObject | JsonWebKeyInput): KeyObject;
|
1163 | /**
|
1164 | * Creates and returns a new key object containing a secret key for symmetric
|
1165 | * encryption or `Hmac`.
|
1166 | * @since v11.6.0
|
1167 | * @param encoding The string encoding when `key` is a string.
|
1168 | */
|
1169 | function createSecretKey(key: NodeJS.ArrayBufferView): KeyObject;
|
1170 | function createSecretKey(key: string, encoding: BufferEncoding): KeyObject;
|
1171 | /**
|
1172 | * Creates and returns a `Sign` object that uses the given `algorithm`. Use {@link getHashes} to obtain the names of the available digest algorithms.
|
1173 | * Optional `options` argument controls the `stream.Writable` behavior.
|
1174 | *
|
1175 | * In some cases, a `Sign` instance can be created using the name of a signature
|
1176 | * algorithm, such as `'RSA-SHA256'`, instead of a digest algorithm. This will use
|
1177 | * the corresponding digest algorithm. This does not work for all signature
|
1178 | * algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest
|
1179 | * algorithm names.
|
1180 | * @since v0.1.92
|
1181 | * @param options `stream.Writable` options
|
1182 | */
|
1183 | function createSign(algorithm: string, options?: stream.WritableOptions): Sign;
|
1184 | type DSAEncoding = 'der' | 'ieee-p1363';
|
1185 | interface SigningOptions {
|
1186 | /**
|
1187 | * @See crypto.constants.RSA_PKCS1_PADDING
|
1188 | */
|
1189 | padding?: number | undefined;
|
1190 | saltLength?: number | undefined;
|
1191 | dsaEncoding?: DSAEncoding | undefined;
|
1192 | }
|
1193 | interface SignPrivateKeyInput extends PrivateKeyInput, SigningOptions {}
|
1194 | interface SignKeyObjectInput extends SigningOptions {
|
1195 | key: KeyObject;
|
1196 | }
|
1197 | interface VerifyPublicKeyInput extends PublicKeyInput, SigningOptions {}
|
1198 | interface VerifyKeyObjectInput extends SigningOptions {
|
1199 | key: KeyObject;
|
1200 | }
|
1201 | type KeyLike = string | Buffer | KeyObject;
|
1202 | /**
|
1203 | * The `Sign` class is a utility for generating signatures. It can be used in one
|
1204 | * of two ways:
|
1205 | *
|
1206 | * * As a writable `stream`, where data to be signed is written and the `sign.sign()` method is used to generate and return the signature, or
|
1207 | * * Using the `sign.update()` and `sign.sign()` methods to produce the
|
1208 | * signature.
|
1209 | *
|
1210 | * The {@link createSign} method is used to create `Sign` instances. The
|
1211 | * argument is the string name of the hash function to use. `Sign` objects are not
|
1212 | * to be created directly using the `new` keyword.
|
1213 | *
|
1214 | * Example: Using `Sign` and `Verify` objects as streams:
|
1215 | *
|
1216 | * ```js
|
1217 | * const {
|
1218 | * generateKeyPairSync,
|
1219 | * createSign,
|
1220 | * createVerify
|
1221 | * } = await import('crypto');
|
1222 | *
|
1223 | * const { privateKey, publicKey } = generateKeyPairSync('ec', {
|
1224 | * namedCurve: 'sect239k1'
|
1225 | * });
|
1226 | *
|
1227 | * const sign = createSign('SHA256');
|
1228 | * sign.write('some data to sign');
|
1229 | * sign.end();
|
1230 | * const signature = sign.sign(privateKey, 'hex');
|
1231 | *
|
1232 | * const verify = createVerify('SHA256');
|
1233 | * verify.write('some data to sign');
|
1234 | * verify.end();
|
1235 | * console.log(verify.verify(publicKey, signature, 'hex'));
|
1236 | *
|
1237 | * ```
|
1238 | *
|
1239 | * Example: Using the `sign.update()` and `verify.update()` methods:
|
1240 | *
|
1241 | * ```js
|
1242 | * const {
|
1243 | * generateKeyPairSync,
|
1244 | * createSign,
|
1245 | * createVerify
|
1246 | * } = await import('crypto');
|
1247 | *
|
1248 | * const { privateKey, publicKey } = generateKeyPairSync('rsa', {
|
1249 | * modulusLength: 2048,
|
1250 | * });
|
1251 | *
|
1252 | * const sign = createSign('SHA256');
|
1253 | * sign.update('some data to sign');
|
1254 | * sign.end();
|
1255 | * const signature = sign.sign(privateKey);
|
1256 | *
|
1257 | * const verify = createVerify('SHA256');
|
1258 | * verify.update('some data to sign');
|
1259 | * verify.end();
|
1260 | * console.log(verify.verify(publicKey, signature));
|
1261 | *
|
1262 | * ```
|
1263 | * @since v0.1.92
|
1264 | */
|
1265 | class Sign extends stream.Writable {
|
1266 | private constructor();
|
1267 | /**
|
1268 | * Updates the `Sign` content with the given `data`, the encoding of which
|
1269 | * is given in `inputEncoding`.
|
1270 | * If `encoding` is not provided, and the `data` is a string, an
|
1271 | * encoding of `'utf8'` is enforced. If `data` is a `Buffer`, `TypedArray`, or`DataView`, then `inputEncoding` is ignored.
|
1272 | *
|
1273 | * This can be called many times with new data as it is streamed.
|
1274 | * @since v0.1.92
|
1275 | * @param inputEncoding The `encoding` of the `data` string.
|
1276 | */
|
1277 | update(data: BinaryLike): this;
|
1278 | update(data: string, inputEncoding: Encoding): this;
|
1279 | /**
|
1280 | * Calculates the signature on all the data passed through using either `sign.update()` or `sign.write()`.
|
1281 | *
|
1282 | * If `privateKey` is not a `KeyObject`, this function behaves as if`privateKey` had been passed to {@link createPrivateKey}. If it is an
|
1283 | * object, the following additional properties can be passed:
|
1284 | *
|
1285 | * If `outputEncoding` is provided a string is returned; otherwise a `Buffer` is returned.
|
1286 | *
|
1287 | * The `Sign` object can not be again used after `sign.sign()` method has been
|
1288 | * called. Multiple calls to `sign.sign()` will result in an error being thrown.
|
1289 | * @since v0.1.92
|
1290 | */
|
1291 | sign(privateKey: KeyLike | SignKeyObjectInput | SignPrivateKeyInput): Buffer;
|
1292 | sign(privateKey: KeyLike | SignKeyObjectInput | SignPrivateKeyInput, outputFormat: BinaryToTextEncoding): string;
|
1293 | }
|
1294 | /**
|
1295 | * Creates and returns a `Verify` object that uses the given algorithm.
|
1296 | * Use {@link getHashes} to obtain an array of names of the available
|
1297 | * signing algorithms. Optional `options` argument controls the`stream.Writable` behavior.
|
1298 | *
|
1299 | * In some cases, a `Verify` instance can be created using the name of a signature
|
1300 | * algorithm, such as `'RSA-SHA256'`, instead of a digest algorithm. This will use
|
1301 | * the corresponding digest algorithm. This does not work for all signature
|
1302 | * algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest
|
1303 | * algorithm names.
|
1304 | * @since v0.1.92
|
1305 | * @param options `stream.Writable` options
|
1306 | */
|
1307 | function createVerify(algorithm: string, options?: stream.WritableOptions): Verify;
|
1308 | /**
|
1309 | * The `Verify` class is a utility for verifying signatures. It can be used in one
|
1310 | * of two ways:
|
1311 | *
|
1312 | * * As a writable `stream` where written data is used to validate against the
|
1313 | * supplied signature, or
|
1314 | * * Using the `verify.update()` and `verify.verify()` methods to verify
|
1315 | * the signature.
|
1316 | *
|
1317 | * The {@link createVerify} method is used to create `Verify` instances.`Verify` objects are not to be created directly using the `new` keyword.
|
1318 | *
|
1319 | * See `Sign` for examples.
|
1320 | * @since v0.1.92
|
1321 | */
|
1322 | class Verify extends stream.Writable {
|
1323 | private constructor();
|
1324 | /**
|
1325 | * Updates the `Verify` content with the given `data`, the encoding of which
|
1326 | * is given in `inputEncoding`.
|
1327 | * If `inputEncoding` is not provided, and the `data` is a string, an
|
1328 | * encoding of `'utf8'` is enforced. If `data` is a `Buffer`, `TypedArray`, or`DataView`, then `inputEncoding` is ignored.
|
1329 | *
|
1330 | * This can be called many times with new data as it is streamed.
|
1331 | * @since v0.1.92
|
1332 | * @param inputEncoding The `encoding` of the `data` string.
|
1333 | */
|
1334 | update(data: BinaryLike): Verify;
|
1335 | update(data: string, inputEncoding: Encoding): Verify;
|
1336 | /**
|
1337 | * Verifies the provided data using the given `object` and `signature`.
|
1338 | *
|
1339 | * If `object` is not a `KeyObject`, this function behaves as if`object` had been passed to {@link createPublicKey}. If it is an
|
1340 | * object, the following additional properties can be passed:
|
1341 | *
|
1342 | * The `signature` argument is the previously calculated signature for the data, in
|
1343 | * the `signatureEncoding`.
|
1344 | * If a `signatureEncoding` is specified, the `signature` is expected to be a
|
1345 | * string; otherwise `signature` is expected to be a `Buffer`,`TypedArray`, or `DataView`.
|
1346 | *
|
1347 | * The `verify` object can not be used again after `verify.verify()` has been
|
1348 | * called. Multiple calls to `verify.verify()` will result in an error being
|
1349 | * thrown.
|
1350 | *
|
1351 | * Because public keys can be derived from private keys, a private key may
|
1352 | * be passed instead of a public key.
|
1353 | * @since v0.1.92
|
1354 | */
|
1355 | verify(object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, signature: NodeJS.ArrayBufferView): boolean;
|
1356 | verify(object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, signature: string, signature_format?: BinaryToTextEncoding): boolean;
|
1357 | }
|
1358 | /**
|
1359 | * Creates a `DiffieHellman` key exchange object using the supplied `prime` and an
|
1360 | * optional specific `generator`.
|
1361 | *
|
1362 | * The `generator` argument can be a number, string, or `Buffer`. If`generator` is not specified, the value `2` is used.
|
1363 | *
|
1364 | * If `primeEncoding` is specified, `prime` is expected to be a string; otherwise
|
1365 | * a `Buffer`, `TypedArray`, or `DataView` is expected.
|
1366 | *
|
1367 | * If `generatorEncoding` is specified, `generator` is expected to be a string;
|
1368 | * otherwise a number, `Buffer`, `TypedArray`, or `DataView` is expected.
|
1369 | * @since v0.11.12
|
1370 | * @param primeEncoding The `encoding` of the `prime` string.
|
1371 | * @param [generator=2]
|
1372 | * @param generatorEncoding The `encoding` of the `generator` string.
|
1373 | */
|
1374 | function createDiffieHellman(primeLength: number, generator?: number | NodeJS.ArrayBufferView): DiffieHellman;
|
1375 | function createDiffieHellman(prime: NodeJS.ArrayBufferView): DiffieHellman;
|
1376 | function createDiffieHellman(prime: string, primeEncoding: BinaryToTextEncoding): DiffieHellman;
|
1377 | function createDiffieHellman(prime: string, primeEncoding: BinaryToTextEncoding, generator: number | NodeJS.ArrayBufferView): DiffieHellman;
|
1378 | function createDiffieHellman(prime: string, primeEncoding: BinaryToTextEncoding, generator: string, generatorEncoding: BinaryToTextEncoding): DiffieHellman;
|
1379 | /**
|
1380 | * The `DiffieHellman` class is a utility for creating Diffie-Hellman key
|
1381 | * exchanges.
|
1382 | *
|
1383 | * Instances of the `DiffieHellman` class can be created using the {@link createDiffieHellman} function.
|
1384 | *
|
1385 | * ```js
|
1386 | * import assert from 'assert';
|
1387 | *
|
1388 | * const {
|
1389 | * createDiffieHellman
|
1390 | * } = await import('crypto');
|
1391 | *
|
1392 | *
|
1393 | * const alice = createDiffieHellman(2048);
|
1394 | * const aliceKey = alice.generateKeys();
|
1395 | *
|
1396 | *
|
1397 | * const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
|
1398 | * const bobKey = bob.generateKeys();
|
1399 | *
|
1400 | *
|
1401 | * const aliceSecret = alice.computeSecret(bobKey);
|
1402 | * const bobSecret = bob.computeSecret(aliceKey);
|
1403 | *
|
1404 | *
|
1405 | * assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
|
1406 | * ```
|
1407 | * @since v0.5.0
|
1408 | */
|
1409 | class DiffieHellman {
|
1410 | private constructor();
|
1411 | /**
|
1412 | * Generates private and public Diffie-Hellman key values, and returns
|
1413 | * the public key in the specified `encoding`. This key should be
|
1414 | * transferred to the other party.
|
1415 | * If `encoding` is provided a string is returned; otherwise a `Buffer` is returned.
|
1416 | * @since v0.5.0
|
1417 | * @param encoding The `encoding` of the return value.
|
1418 | */
|
1419 | generateKeys(): Buffer;
|
1420 | generateKeys(encoding: BinaryToTextEncoding): string;
|
1421 | /**
|
1422 | * Computes the shared secret using `otherPublicKey` as the other
|
1423 | * party's public key and returns the computed shared secret. The supplied
|
1424 | * key is interpreted using the specified `inputEncoding`, and secret is
|
1425 | * encoded using specified `outputEncoding`.
|
1426 | * If the `inputEncoding` is not
|
1427 | * provided, `otherPublicKey` is expected to be a `Buffer`,`TypedArray`, or `DataView`.
|
1428 | *
|
1429 | * If `outputEncoding` is given a string is returned; otherwise, a `Buffer` is returned.
|
1430 | * @since v0.5.0
|
1431 | * @param inputEncoding The `encoding` of an `otherPublicKey` string.
|
1432 | * @param outputEncoding The `encoding` of the return value.
|
1433 | */
|
1434 | computeSecret(otherPublicKey: NodeJS.ArrayBufferView): Buffer;
|
1435 | computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding): Buffer;
|
1436 | computeSecret(otherPublicKey: NodeJS.ArrayBufferView, outputEncoding: BinaryToTextEncoding): string;
|
1437 | computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding, outputEncoding: BinaryToTextEncoding): string;
|
1438 | /**
|
1439 | * Returns the Diffie-Hellman prime in the specified `encoding`.
|
1440 | * If `encoding` is provided a string is
|
1441 | * returned; otherwise a `Buffer` is returned.
|
1442 | * @since v0.5.0
|
1443 | * @param encoding The `encoding` of the return value.
|
1444 | */
|
1445 | getPrime(): Buffer;
|
1446 | getPrime(encoding: BinaryToTextEncoding): string;
|
1447 | /**
|
1448 | * Returns the Diffie-Hellman generator in the specified `encoding`.
|
1449 | * If `encoding` is provided a string is
|
1450 | * returned; otherwise a `Buffer` is returned.
|
1451 | * @since v0.5.0
|
1452 | * @param encoding The `encoding` of the return value.
|
1453 | */
|
1454 | getGenerator(): Buffer;
|
1455 | getGenerator(encoding: BinaryToTextEncoding): string;
|
1456 | /**
|
1457 | * Returns the Diffie-Hellman public key in the specified `encoding`.
|
1458 | * If `encoding` is provided a
|
1459 | * string is returned; otherwise a `Buffer` is returned.
|
1460 | * @since v0.5.0
|
1461 | * @param encoding The `encoding` of the return value.
|
1462 | */
|
1463 | getPublicKey(): Buffer;
|
1464 | getPublicKey(encoding: BinaryToTextEncoding): string;
|
1465 | /**
|
1466 | * Returns the Diffie-Hellman private key in the specified `encoding`.
|
1467 | * If `encoding` is provided a
|
1468 | * string is returned; otherwise a `Buffer` is returned.
|
1469 | * @since v0.5.0
|
1470 | * @param encoding The `encoding` of the return value.
|
1471 | */
|
1472 | getPrivateKey(): Buffer;
|
1473 | getPrivateKey(encoding: BinaryToTextEncoding): string;
|
1474 | /**
|
1475 | * Sets the Diffie-Hellman public key. If the `encoding` argument is provided,`publicKey` is expected
|
1476 | * to be a string. If no `encoding` is provided, `publicKey` is expected
|
1477 | * to be a `Buffer`, `TypedArray`, or `DataView`.
|
1478 | * @since v0.5.0
|
1479 | * @param encoding The `encoding` of the `publicKey` string.
|
1480 | */
|
1481 | setPublicKey(publicKey: NodeJS.ArrayBufferView): void;
|
1482 | setPublicKey(publicKey: string, encoding: BufferEncoding): void;
|
1483 | /**
|
1484 | * Sets the Diffie-Hellman private key. If the `encoding` argument is provided,`privateKey` is expected
|
1485 | * to be a string. If no `encoding` is provided, `privateKey` is expected
|
1486 | * to be a `Buffer`, `TypedArray`, or `DataView`.
|
1487 | * @since v0.5.0
|
1488 | * @param encoding The `encoding` of the `privateKey` string.
|
1489 | */
|
1490 | setPrivateKey(privateKey: NodeJS.ArrayBufferView): void;
|
1491 | setPrivateKey(privateKey: string, encoding: BufferEncoding): void;
|
1492 | /**
|
1493 | * A bit field containing any warnings and/or errors resulting from a check
|
1494 | * performed during initialization of the `DiffieHellman` object.
|
1495 | *
|
1496 | * The following values are valid for this property (as defined in `constants`module):
|
1497 | *
|
1498 | * * `DH_CHECK_P_NOT_SAFE_PRIME`
|
1499 | * * `DH_CHECK_P_NOT_PRIME`
|
1500 | * * `DH_UNABLE_TO_CHECK_GENERATOR`
|
1501 | * * `DH_NOT_SUITABLE_GENERATOR`
|
1502 | * @since v0.11.12
|
1503 | */
|
1504 | verifyError: number;
|
1505 | }
|
1506 | /**
|
1507 | * Creates a predefined `DiffieHellmanGroup` key exchange object. The
|
1508 | * supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in[RFC 2412](https://www.rfc-editor.org/rfc/rfc2412.txt), but see `Caveats`) and `'modp14'`, `'modp15'`,`'modp16'`, `'modp17'`,
|
1509 | * `'modp18'` (defined in [RFC 3526](https://www.rfc-editor.org/rfc/rfc3526.txt)). The
|
1510 | * returned object mimics the interface of objects created by {@link createDiffieHellman}, but will not allow changing
|
1511 | * the keys (with `diffieHellman.setPublicKey()`, for example). The
|
1512 | * advantage of using this method is that the parties do not have to
|
1513 | * generate nor exchange a group modulus beforehand, saving both processor
|
1514 | * and communication time.
|
1515 | *
|
1516 | * Example (obtaining a shared secret):
|
1517 | *
|
1518 | * ```js
|
1519 | * const {
|
1520 | * getDiffieHellman
|
1521 | * } = await import('crypto');
|
1522 | * const alice = getDiffieHellman('modp14');
|
1523 | * const bob = getDiffieHellman('modp14');
|
1524 | *
|
1525 | * alice.generateKeys();
|
1526 | * bob.generateKeys();
|
1527 | *
|
1528 | * const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
|
1529 | * const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
|
1530 | *
|
1531 | *
|
1532 | * console.log(aliceSecret === bobSecret);
|
1533 | * ```
|
1534 | * @since v0.7.5
|
1535 | */
|
1536 | function getDiffieHellman(groupName: string): DiffieHellman;
|
1537 | /**
|
1538 | * Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2)
|
1539 | * implementation. A selected HMAC digest algorithm specified by `digest` is
|
1540 | * applied to derive a key of the requested byte length (`keylen`) from the`password`, `salt` and `iterations`.
|
1541 | *
|
1542 | * The supplied `callback` function is called with two arguments: `err` and`derivedKey`. If an error occurs while deriving the key, `err` will be set;
|
1543 | * otherwise `err` will be `null`. By default, the successfully generated`derivedKey` will be passed to the callback as a `Buffer`. An error will be
|
1544 | * thrown if any of the input arguments specify invalid values or types.
|
1545 | *
|
1546 | * If `digest` is `null`, `'sha1'` will be used. This behavior is deprecated,
|
1547 | * please specify a `digest` explicitly.
|
1548 | *
|
1549 | * The `iterations` argument must be a number set as high as possible. The
|
1550 | * higher the number of iterations, the more secure the derived key will be,
|
1551 | * but will take a longer amount of time to complete.
|
1552 | *
|
1553 | * The `salt` should be as unique as possible. It is recommended that a salt is
|
1554 | * random and at least 16 bytes long. See [NIST SP 800-132](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf) for details.
|
1555 | *
|
1556 | * When passing strings for `password` or `salt`, please consider `caveats when using strings as inputs to cryptographic APIs`.
|
1557 | *
|
1558 | * ```js
|
1559 | * const {
|
1560 | * pbkdf2
|
1561 | * } = await import('crypto');
|
1562 | *
|
1563 | * pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
|
1564 | * if (err) throw err;
|
1565 | * console.log(derivedKey.toString('hex'));
|
1566 | * });
|
1567 | * ```
|
1568 | *
|
1569 | * The `crypto.DEFAULT_ENCODING` property can be used to change the way the`derivedKey` is passed to the callback. This property, however, has been
|
1570 | * deprecated and use should be avoided.
|
1571 | *
|
1572 | * ```js
|
1573 | * import crypto from 'crypto';
|
1574 | * crypto.DEFAULT_ENCODING = 'hex';
|
1575 | * crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => {
|
1576 | * if (err) throw err;
|
1577 | * console.log(derivedKey);
|
1578 | * });
|
1579 | * ```
|
1580 | *
|
1581 | * An array of supported digest functions can be retrieved using {@link getHashes}.
|
1582 | *
|
1583 | * This API uses libuv's threadpool, which can have surprising and
|
1584 | * negative performance implications for some applications; see the `UV_THREADPOOL_SIZE` documentation for more information.
|
1585 | * @since v0.5.5
|
1586 | */
|
1587 | function pbkdf2(password: BinaryLike, salt: BinaryLike, iterations: number, keylen: number, digest: string, callback: (err: Error | null, derivedKey: Buffer) => void): void;
|
1588 | /**
|
1589 | * Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2)
|
1590 | * implementation. A selected HMAC digest algorithm specified by `digest` is
|
1591 | * applied to derive a key of the requested byte length (`keylen`) from the`password`, `salt` and `iterations`.
|
1592 | *
|
1593 | * If an error occurs an `Error` will be thrown, otherwise the derived key will be
|
1594 | * returned as a `Buffer`.
|
1595 | *
|
1596 | * If `digest` is `null`, `'sha1'` will be used. This behavior is deprecated,
|
1597 | * please specify a `digest` explicitly.
|
1598 | *
|
1599 | * The `iterations` argument must be a number set as high as possible. The
|
1600 | * higher the number of iterations, the more secure the derived key will be,
|
1601 | * but will take a longer amount of time to complete.
|
1602 | *
|
1603 | * The `salt` should be as unique as possible. It is recommended that a salt is
|
1604 | * random and at least 16 bytes long. See [NIST SP 800-132](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf) for details.
|
1605 | *
|
1606 | * When passing strings for `password` or `salt`, please consider `caveats when using strings as inputs to cryptographic APIs`.
|
1607 | *
|
1608 | * ```js
|
1609 | * const {
|
1610 | * pbkdf2Sync
|
1611 | * } = await import('crypto');
|
1612 | *
|
1613 | * const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
|
1614 | * console.log(key.toString('hex'));
|
1615 | * ```
|
1616 | *
|
1617 | * The `crypto.DEFAULT_ENCODING` property may be used to change the way the`derivedKey` is returned. This property, however, is deprecated and use
|
1618 | * should be avoided.
|
1619 | *
|
1620 | * ```js
|
1621 | * import crypto from 'crypto';
|
1622 | * crypto.DEFAULT_ENCODING = 'hex';
|
1623 | * const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 512, 'sha512');
|
1624 | * console.log(key);
|
1625 | * ```
|
1626 | *
|
1627 | * An array of supported digest functions can be retrieved using {@link getHashes}.
|
1628 | * @since v0.9.3
|
1629 | */
|
1630 | function pbkdf2Sync(password: BinaryLike, salt: BinaryLike, iterations: number, keylen: number, digest: string): Buffer;
|
1631 | /**
|
1632 | * Generates cryptographically strong pseudorandom data. The `size` argument
|
1633 | * is a number indicating the number of bytes to generate.
|
1634 | *
|
1635 | * If a `callback` function is provided, the bytes are generated asynchronously
|
1636 | * and the `callback` function is invoked with two arguments: `err` and `buf`.
|
1637 | * If an error occurs, `err` will be an `Error` object; otherwise it is `null`. The`buf` argument is a `Buffer` containing the generated bytes.
|
1638 | *
|
1639 | * ```js
|
1640 | *
|
1641 | * const {
|
1642 | * randomBytes
|
1643 | * } = await import('crypto');
|
1644 | *
|
1645 | * randomBytes(256, (err, buf) => {
|
1646 | * if (err) throw err;
|
1647 | * console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
|
1648 | * });
|
1649 | * ```
|
1650 | *
|
1651 | * If the `callback` function is not provided, the random bytes are generated
|
1652 | * synchronously and returned as a `Buffer`. An error will be thrown if
|
1653 | * there is a problem generating the bytes.
|
1654 | *
|
1655 | * ```js
|
1656 | *
|
1657 | * const {
|
1658 | * randomBytes
|
1659 | * } = await import('crypto');
|
1660 | *
|
1661 | * const buf = randomBytes(256);
|
1662 | * console.log(
|
1663 | * `${buf.length} bytes of random data: ${buf.toString('hex')}`);
|
1664 | * ```
|
1665 | *
|
1666 | * The `crypto.randomBytes()` method will not complete until there is
|
1667 | * sufficient entropy available.
|
1668 | * This should normally never take longer than a few milliseconds. The only time
|
1669 | * when generating the random bytes may conceivably block for a longer period of
|
1670 | * time is right after boot, when the whole system is still low on entropy.
|
1671 | *
|
1672 | * This API uses libuv's threadpool, which can have surprising and
|
1673 | * negative performance implications for some applications; see the `UV_THREADPOOL_SIZE` documentation for more information.
|
1674 | *
|
1675 | * The asynchronous version of `crypto.randomBytes()` is carried out in a single
|
1676 | * threadpool request. To minimize threadpool task length variation, partition
|
1677 | * large `randomBytes` requests when doing so as part of fulfilling a client
|
1678 | * request.
|
1679 | * @since v0.5.8
|
1680 | * @param size The number of bytes to generate. The `size` must not be larger than `2**31 - 1`.
|
1681 | * @return if the `callback` function is not provided.
|
1682 | */
|
1683 | function randomBytes(size: number): Buffer;
|
1684 | function randomBytes(size: number, callback: (err: Error | null, buf: Buffer) => void): void;
|
1685 | function pseudoRandomBytes(size: number): Buffer;
|
1686 | function pseudoRandomBytes(size: number, callback: (err: Error | null, buf: Buffer) => void): void;
|
1687 | /**
|
1688 | * Return a random integer `n` such that `min <= n < max`. This
|
1689 | * implementation avoids [modulo bias](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#Modulo_bias).
|
1690 | *
|
1691 | * The range (`max - min`) must be less than 248. `min` and `max` must
|
1692 | * be [safe integers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).
|
1693 | *
|
1694 | * If the `callback` function is not provided, the random integer is
|
1695 | * generated synchronously.
|
1696 | *
|
1697 | * ```js
|
1698 | *
|
1699 | * const {
|
1700 | * randomInt
|
1701 | * } = await import('crypto');
|
1702 | *
|
1703 | * randomInt(3, (err, n) => {
|
1704 | * if (err) throw err;
|
1705 | * console.log(`Random number chosen from (0, 1, 2): ${n}`);
|
1706 | * });
|
1707 | * ```
|
1708 | *
|
1709 | * ```js
|
1710 | *
|
1711 | * const {
|
1712 | * randomInt
|
1713 | * } = await import('crypto');
|
1714 | *
|
1715 | * const n = randomInt(3);
|
1716 | * console.log(`Random number chosen from (0, 1, 2): ${n}`);
|
1717 | * ```
|
1718 | *
|
1719 | * ```js
|
1720 | *
|
1721 | * const {
|
1722 | * randomInt
|
1723 | * } = await import('crypto');
|
1724 | *
|
1725 | * const n = randomInt(1, 7);
|
1726 | * console.log(`The dice rolled: ${n}`);
|
1727 | * ```
|
1728 | * @since v14.10.0, v12.19.0
|
1729 | * @param [min=0] Start of random range (inclusive).
|
1730 | * @param max End of random range (exclusive).
|
1731 | * @param callback `function(err, n) {}`.
|
1732 | */
|
1733 | function randomInt(max: number): number;
|
1734 | function randomInt(min: number, max: number): number;
|
1735 | function randomInt(max: number, callback: (err: Error | null, value: number) => void): void;
|
1736 | function randomInt(min: number, max: number, callback: (err: Error | null, value: number) => void): void;
|
1737 | /**
|
1738 | * Synchronous version of {@link randomFill}.
|
1739 | *
|
1740 | * ```js
|
1741 | * import { Buffer } from 'buffer';
|
1742 | * const { randomFillSync } = await import('crypto');
|
1743 | *
|
1744 | * const buf = Buffer.alloc(10);
|
1745 | * console.log(randomFillSync(buf).toString('hex'));
|
1746 | *
|
1747 | * randomFillSync(buf, 5);
|
1748 | * console.log(buf.toString('hex'));
|
1749 | *
|
1750 | *
|
1751 | * randomFillSync(buf, 5, 5);
|
1752 | * console.log(buf.toString('hex'));
|
1753 | * ```
|
1754 | *
|
1755 | * Any `ArrayBuffer`, `TypedArray` or `DataView` instance may be passed as`buffer`.
|
1756 | *
|
1757 | * ```js
|
1758 | * import { Buffer } from 'buffer';
|
1759 | * const { randomFillSync } = await import('crypto');
|
1760 | *
|
1761 | * const a = new Uint32Array(10);
|
1762 | * console.log(Buffer.from(randomFillSync(a).buffer,
|
1763 | * a.byteOffset, a.byteLength).toString('hex'));
|
1764 | *
|
1765 | * const b = new DataView(new ArrayBuffer(10));
|
1766 | * console.log(Buffer.from(randomFillSync(b).buffer,
|
1767 | * b.byteOffset, b.byteLength).toString('hex'));
|
1768 | *
|
1769 | * const c = new ArrayBuffer(10);
|
1770 | * console.log(Buffer.from(randomFillSync(c)).toString('hex'));
|
1771 | * ```
|
1772 | * @since v7.10.0, v6.13.0
|
1773 | * @param buffer Must be supplied. The size of the provided `buffer` must not be larger than `2**31 - 1`.
|
1774 | * @param [offset=0]
|
1775 | * @param [size=buffer.length - offset]
|
1776 | * @return The object passed as `buffer` argument.
|
1777 | */
|
1778 | function randomFillSync<T extends NodeJS.ArrayBufferView>(buffer: T, offset?: number, size?: number): T;
|
1779 | /**
|
1780 | * This function is similar to {@link randomBytes} but requires the first
|
1781 | * argument to be a `Buffer` that will be filled. It also
|
1782 | * requires that a callback is passed in.
|
1783 | *
|
1784 | * If the `callback` function is not provided, an error will be thrown.
|
1785 | *
|
1786 | * ```js
|
1787 | * import { Buffer } from 'buffer';
|
1788 | * const { randomFill } = await import('crypto');
|
1789 | *
|
1790 | * const buf = Buffer.alloc(10);
|
1791 | * randomFill(buf, (err, buf) => {
|
1792 | * if (err) throw err;
|
1793 | * console.log(buf.toString('hex'));
|
1794 | * });
|
1795 | *
|
1796 | * randomFill(buf, 5, (err, buf) => {
|
1797 | * if (err) throw err;
|
1798 | * console.log(buf.toString('hex'));
|
1799 | * });
|
1800 | *
|
1801 | *
|
1802 | * randomFill(buf, 5, 5, (err, buf) => {
|
1803 | * if (err) throw err;
|
1804 | * console.log(buf.toString('hex'));
|
1805 | * });
|
1806 | * ```
|
1807 | *
|
1808 | * Any `ArrayBuffer`, `TypedArray`, or `DataView` instance may be passed as`buffer`.
|
1809 | *
|
1810 | * While this includes instances of `Float32Array` and `Float64Array`, this
|
1811 | * function should not be used to generate random floating-point numbers. The
|
1812 | * result may contain `+Infinity`, `-Infinity`, and `NaN`, and even if the array
|
1813 | * contains finite numbers only, they are not drawn from a uniform random
|
1814 | * distribution and have no meaningful lower or upper bounds.
|
1815 | *
|
1816 | * ```js
|
1817 | * import { Buffer } from 'buffer';
|
1818 | * const { randomFill } = await import('crypto');
|
1819 | *
|
1820 | * const a = new Uint32Array(10);
|
1821 | * randomFill(a, (err, buf) => {
|
1822 | * if (err) throw err;
|
1823 | * console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
|
1824 | * .toString('hex'));
|
1825 | * });
|
1826 | *
|
1827 | * const b = new DataView(new ArrayBuffer(10));
|
1828 | * randomFill(b, (err, buf) => {
|
1829 | * if (err) throw err;
|
1830 | * console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
|
1831 | * .toString('hex'));
|
1832 | * });
|
1833 | *
|
1834 | * const c = new ArrayBuffer(10);
|
1835 | * randomFill(c, (err, buf) => {
|
1836 | * if (err) throw err;
|
1837 | * console.log(Buffer.from(buf).toString('hex'));
|
1838 | * });
|
1839 | * ```
|
1840 | *
|
1841 | * This API uses libuv's threadpool, which can have surprising and
|
1842 | * negative performance implications for some applications; see the `UV_THREADPOOL_SIZE` documentation for more information.
|
1843 | *
|
1844 | * The asynchronous version of `crypto.randomFill()` is carried out in a single
|
1845 | * threadpool request. To minimize threadpool task length variation, partition
|
1846 | * large `randomFill` requests when doing so as part of fulfilling a client
|
1847 | * request.
|
1848 | * @since v7.10.0, v6.13.0
|
1849 | * @param buffer Must be supplied. The size of the provided `buffer` must not be larger than `2**31 - 1`.
|
1850 | * @param [offset=0]
|
1851 | * @param [size=buffer.length - offset]
|
1852 | * @param callback `function(err, buf) {}`.
|
1853 | */
|
1854 | function randomFill<T extends NodeJS.ArrayBufferView>(buffer: T, callback: (err: Error | null, buf: T) => void): void;
|
1855 | function randomFill<T extends NodeJS.ArrayBufferView>(buffer: T, offset: number, callback: (err: Error | null, buf: T) => void): void;
|
1856 | function randomFill<T extends NodeJS.ArrayBufferView>(buffer: T, offset: number, size: number, callback: (err: Error | null, buf: T) => void): void;
|
1857 | interface ScryptOptions {
|
1858 | cost?: number | undefined;
|
1859 | blockSize?: number | undefined;
|
1860 | parallelization?: number | undefined;
|
1861 | N?: number | undefined;
|
1862 | r?: number | undefined;
|
1863 | p?: number | undefined;
|
1864 | maxmem?: number | undefined;
|
1865 | }
|
1866 | /**
|
1867 | * Provides an asynchronous [scrypt](https://en.wikipedia.org/wiki/Scrypt) implementation. Scrypt is a password-based
|
1868 | * key derivation function that is designed to be expensive computationally and
|
1869 | * memory-wise in order to make brute-force attacks unrewarding.
|
1870 | *
|
1871 | * The `salt` should be as unique as possible. It is recommended that a salt is
|
1872 | * random and at least 16 bytes long. See [NIST SP 800-132](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf) for details.
|
1873 | *
|
1874 | * When passing strings for `password` or `salt`, please consider `caveats when using strings as inputs to cryptographic APIs`.
|
1875 | *
|
1876 | * The `callback` function is called with two arguments: `err` and `derivedKey`.`err` is an exception object when key derivation fails, otherwise `err` is`null`. `derivedKey` is passed to the
|
1877 | * callback as a `Buffer`.
|
1878 | *
|
1879 | * An exception is thrown when any of the input arguments specify invalid values
|
1880 | * or types.
|
1881 | *
|
1882 | * ```js
|
1883 | * const {
|
1884 | * scrypt
|
1885 | * } = await import('crypto');
|
1886 | *
|
1887 | *
|
1888 | * scrypt('password', 'salt', 64, (err, derivedKey) => {
|
1889 | * if (err) throw err;
|
1890 | * console.log(derivedKey.toString('hex'));
|
1891 | * });
|
1892 | *
|
1893 | * scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
|
1894 | * if (err) throw err;
|
1895 | * console.log(derivedKey.toString('hex'));
|
1896 | * });
|
1897 | * ```
|
1898 | * @since v10.5.0
|
1899 | */
|
1900 | function scrypt(password: BinaryLike, salt: BinaryLike, keylen: number, callback: (err: Error | null, derivedKey: Buffer) => void): void;
|
1901 | function scrypt(password: BinaryLike, salt: BinaryLike, keylen: number, options: ScryptOptions, callback: (err: Error | null, derivedKey: Buffer) => void): void;
|
1902 | /**
|
1903 | * Provides a synchronous [scrypt](https://en.wikipedia.org/wiki/Scrypt) implementation. Scrypt is a password-based
|
1904 | * key derivation function that is designed to be expensive computationally and
|
1905 | * memory-wise in order to make brute-force attacks unrewarding.
|
1906 | *
|
1907 | * The `salt` should be as unique as possible. It is recommended that a salt is
|
1908 | * random and at least 16 bytes long. See [NIST SP 800-132](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf) for details.
|
1909 | *
|
1910 | * When passing strings for `password` or `salt`, please consider `caveats when using strings as inputs to cryptographic APIs`.
|
1911 | *
|
1912 | * An exception is thrown when key derivation fails, otherwise the derived key is
|
1913 | * returned as a `Buffer`.
|
1914 | *
|
1915 | * An exception is thrown when any of the input arguments specify invalid values
|
1916 | * or types.
|
1917 | *
|
1918 | * ```js
|
1919 | * const {
|
1920 | * scryptSync
|
1921 | * } = await import('crypto');
|
1922 | *
|
1923 | *
|
1924 | * const key1 = scryptSync('password', 'salt', 64);
|
1925 | * console.log(key1.toString('hex'));
|
1926 | *
|
1927 | * const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
|
1928 | * console.log(key2.toString('hex'));
|
1929 | * ```
|
1930 | * @since v10.5.0
|
1931 | */
|
1932 | function scryptSync(password: BinaryLike, salt: BinaryLike, keylen: number, options?: ScryptOptions): Buffer;
|
1933 | interface RsaPublicKey {
|
1934 | key: KeyLike;
|
1935 | padding?: number | undefined;
|
1936 | }
|
1937 | interface RsaPrivateKey {
|
1938 | key: KeyLike;
|
1939 | passphrase?: string | undefined;
|
1940 | /**
|
1941 | * @default 'sha1'
|
1942 | */
|
1943 | oaepHash?: string | undefined;
|
1944 | oaepLabel?: NodeJS.TypedArray | undefined;
|
1945 | padding?: number | undefined;
|
1946 | }
|
1947 | /**
|
1948 | * Encrypts the content of `buffer` with `key` and returns a new `Buffer` with encrypted content. The returned data can be decrypted using
|
1949 | * the corresponding private key, for example using {@link privateDecrypt}.
|
1950 | *
|
1951 | * If `key` is not a `KeyObject`, this function behaves as if`key` had been passed to {@link createPublicKey}. If it is an
|
1952 | * object, the `padding` property can be passed. Otherwise, this function uses`RSA_PKCS1_OAEP_PADDING`.
|
1953 | *
|
1954 | * Because RSA public keys can be derived from private keys, a private key may
|
1955 | * be passed instead of a public key.
|
1956 | * @since v0.11.14
|
1957 | */
|
1958 | function publicEncrypt(key: RsaPublicKey | RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView): Buffer;
|
1959 | /**
|
1960 | * Decrypts `buffer` with `key`.`buffer` was previously encrypted using
|
1961 | * the corresponding private key, for example using {@link privateEncrypt}.
|
1962 | *
|
1963 | * If `key` is not a `KeyObject`, this function behaves as if`key` had been passed to {@link createPublicKey}. If it is an
|
1964 | * object, the `padding` property can be passed. Otherwise, this function uses`RSA_PKCS1_PADDING`.
|
1965 | *
|
1966 | * Because RSA public keys can be derived from private keys, a private key may
|
1967 | * be passed instead of a public key.
|
1968 | * @since v1.1.0
|
1969 | */
|
1970 | function publicDecrypt(key: RsaPublicKey | RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView): Buffer;
|
1971 | /**
|
1972 | * Decrypts `buffer` with `privateKey`. `buffer` was previously encrypted using
|
1973 | * the corresponding public key, for example using {@link publicEncrypt}.
|
1974 | *
|
1975 | * If `privateKey` is not a `KeyObject`, this function behaves as if`privateKey` had been passed to {@link createPrivateKey}. If it is an
|
1976 | * object, the `padding` property can be passed. Otherwise, this function uses`RSA_PKCS1_OAEP_PADDING`.
|
1977 | * @since v0.11.14
|
1978 | */
|
1979 | function privateDecrypt(privateKey: RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView): Buffer;
|
1980 | /**
|
1981 | * Encrypts `buffer` with `privateKey`. The returned data can be decrypted using
|
1982 | * the corresponding public key, for example using {@link publicDecrypt}.
|
1983 | *
|
1984 | * If `privateKey` is not a `KeyObject`, this function behaves as if`privateKey` had been passed to {@link createPrivateKey}. If it is an
|
1985 | * object, the `padding` property can be passed. Otherwise, this function uses`RSA_PKCS1_PADDING`.
|
1986 | * @since v1.1.0
|
1987 | */
|
1988 | function privateEncrypt(privateKey: RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView): Buffer;
|
1989 | /**
|
1990 | * ```js
|
1991 | * const {
|
1992 | * getCiphers
|
1993 | * } = await import('crypto');
|
1994 | *
|
1995 | * console.log(getCiphers());
|
1996 | * ```
|
1997 | * @since v0.9.3
|
1998 | * @return An array with the names of the supported cipher algorithms.
|
1999 | */
|
2000 | function getCiphers(): string[];
|
2001 | /**
|
2002 | * ```js
|
2003 | * const {
|
2004 | * getCurves
|
2005 | * } = await import('crypto');
|
2006 | *
|
2007 | * console.log(getCurves());
|
2008 | * ```
|
2009 | * @since v2.3.0
|
2010 | * @return An array with the names of the supported elliptic curves.
|
2011 | */
|
2012 | function getCurves(): string[];
|
2013 | /**
|
2014 | * @since v10.0.0
|
2015 | * @return `1` if and only if a FIPS compliant crypto provider is currently in use, `0` otherwise. A future semver-major release may change the return type of this API to a {boolean}.
|
2016 | */
|
2017 | function getFips(): 1 | 0;
|
2018 | /**
|
2019 | * ```js
|
2020 | * const {
|
2021 | * getHashes
|
2022 | * } = await import('crypto');
|
2023 | *
|
2024 | * console.log(getHashes());
|
2025 | * ```
|
2026 | * @since v0.9.3
|
2027 | * @return An array of the names of the supported hash algorithms, such as `'RSA-SHA256'`. Hash algorithms are also called "digest" algorithms.
|
2028 | */
|
2029 | function getHashes(): string[];
|
2030 | /**
|
2031 | * The `ECDH` class is a utility for creating Elliptic Curve Diffie-Hellman (ECDH)
|
2032 | * key exchanges.
|
2033 | *
|
2034 | * Instances of the `ECDH` class can be created using the {@link createECDH} function.
|
2035 | *
|
2036 | * ```js
|
2037 | * import assert from 'assert';
|
2038 | *
|
2039 | * const {
|
2040 | * createECDH
|
2041 | * } = await import('crypto');
|
2042 | *
|
2043 | *
|
2044 | * const alice = createECDH('secp521r1');
|
2045 | * const aliceKey = alice.generateKeys();
|
2046 | *
|
2047 | *
|
2048 | * const bob = createECDH('secp521r1');
|
2049 | * const bobKey = bob.generateKeys();
|
2050 | *
|
2051 | *
|
2052 | * const aliceSecret = alice.computeSecret(bobKey);
|
2053 | * const bobSecret = bob.computeSecret(aliceKey);
|
2054 | *
|
2055 | * assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
|
2056 | *
|
2057 | * ```
|
2058 | * @since v0.11.14
|
2059 | */
|
2060 | class ECDH {
|
2061 | private constructor();
|
2062 | /**
|
2063 | * Converts the EC Diffie-Hellman public key specified by `key` and `curve` to the
|
2064 | * format specified by `format`. The `format` argument specifies point encoding
|
2065 | * and can be `'compressed'`, `'uncompressed'` or `'hybrid'`. The supplied key is
|
2066 | * interpreted using the specified `inputEncoding`, and the returned key is encoded
|
2067 | * using the specified `outputEncoding`.
|
2068 | *
|
2069 | * Use {@link getCurves} to obtain a list of available curve names.
|
2070 | * On recent OpenSSL releases, `openssl ecparam -list_curves` will also display
|
2071 | * the name and description of each available elliptic curve.
|
2072 | *
|
2073 | * If `format` is not specified the point will be returned in `'uncompressed'`format.
|
2074 | *
|
2075 | * If the `inputEncoding` is not provided, `key` is expected to be a `Buffer`,`TypedArray`, or `DataView`.
|
2076 | *
|
2077 | * Example (uncompressing a key):
|
2078 | *
|
2079 | * ```js
|
2080 | * const {
|
2081 | * createECDH,
|
2082 | * ECDH
|
2083 | * } = await import('crypto');
|
2084 | *
|
2085 | * const ecdh = createECDH('secp256k1');
|
2086 | * ecdh.generateKeys();
|
2087 | *
|
2088 | * const compressedKey = ecdh.getPublicKey('hex', 'compressed');
|
2089 | *
|
2090 | * const uncompressedKey = ECDH.convertKey(compressedKey,
|
2091 | * 'secp256k1',
|
2092 | * 'hex',
|
2093 | * 'hex',
|
2094 | * 'uncompressed');
|
2095 | *
|
2096 | *
|
2097 | * console.log(uncompressedKey === ecdh.getPublicKey('hex'));
|
2098 | * ```
|
2099 | * @since v10.0.0
|
2100 | * @param inputEncoding The `encoding` of the `key` string.
|
2101 | * @param outputEncoding The `encoding` of the return value.
|
2102 | * @param [format='uncompressed']
|
2103 | */
|
2104 | static convertKey(
|
2105 | key: BinaryLike,
|
2106 | curve: string,
|
2107 | inputEncoding?: BinaryToTextEncoding,
|
2108 | outputEncoding?: 'latin1' | 'hex' | 'base64',
|
2109 | format?: 'uncompressed' | 'compressed' | 'hybrid'
|
2110 | ): Buffer | string;
|
2111 | /**
|
2112 | * Generates private and public EC Diffie-Hellman key values, and returns
|
2113 | * the public key in the specified `format` and `encoding`. This key should be
|
2114 | * transferred to the other party.
|
2115 | *
|
2116 | * The `format` argument specifies point encoding and can be `'compressed'` or`'uncompressed'`. If `format` is not specified, the point will be returned in`'uncompressed'` format.
|
2117 | *
|
2118 | * If `encoding` is provided a string is returned; otherwise a `Buffer` is returned.
|
2119 | * @since v0.11.14
|
2120 | * @param encoding The `encoding` of the return value.
|
2121 | * @param [format='uncompressed']
|
2122 | */
|
2123 | generateKeys(): Buffer;
|
2124 | generateKeys(encoding: BinaryToTextEncoding, format?: ECDHKeyFormat): string;
|
2125 | /**
|
2126 | * Computes the shared secret using `otherPublicKey` as the other
|
2127 | * party's public key and returns the computed shared secret. The supplied
|
2128 | * key is interpreted using specified `inputEncoding`, and the returned secret
|
2129 | * is encoded using the specified `outputEncoding`.
|
2130 | * If the `inputEncoding` is not
|
2131 | * provided, `otherPublicKey` is expected to be a `Buffer`, `TypedArray`, or`DataView`.
|
2132 | *
|
2133 | * If `outputEncoding` is given a string will be returned; otherwise a `Buffer` is returned.
|
2134 | *
|
2135 | * `ecdh.computeSecret` will throw an`ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY` error when `otherPublicKey`lies outside of the elliptic curve. Since `otherPublicKey` is
|
2136 | * usually supplied from a remote user over an insecure network,
|
2137 | * be sure to handle this exception accordingly.
|
2138 | * @since v0.11.14
|
2139 | * @param inputEncoding The `encoding` of the `otherPublicKey` string.
|
2140 | * @param outputEncoding The `encoding` of the return value.
|
2141 | */
|
2142 | computeSecret(otherPublicKey: NodeJS.ArrayBufferView): Buffer;
|
2143 | computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding): Buffer;
|
2144 | computeSecret(otherPublicKey: NodeJS.ArrayBufferView, outputEncoding: BinaryToTextEncoding): string;
|
2145 | computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding, outputEncoding: BinaryToTextEncoding): string;
|
2146 | /**
|
2147 | * If `encoding` is specified, a string is returned; otherwise a `Buffer` is
|
2148 | * returned.
|
2149 | * @since v0.11.14
|
2150 | * @param encoding The `encoding` of the return value.
|
2151 | * @return The EC Diffie-Hellman in the specified `encoding`.
|
2152 | */
|
2153 | getPrivateKey(): Buffer;
|
2154 | getPrivateKey(encoding: BinaryToTextEncoding): string;
|
2155 | /**
|
2156 | * The `format` argument specifies point encoding and can be `'compressed'` or`'uncompressed'`. If `format` is not specified the point will be returned in`'uncompressed'` format.
|
2157 | *
|
2158 | * If `encoding` is specified, a string is returned; otherwise a `Buffer` is
|
2159 | * returned.
|
2160 | * @since v0.11.14
|
2161 | * @param encoding The `encoding` of the return value.
|
2162 | * @param [format='uncompressed']
|
2163 | * @return The EC Diffie-Hellman public key in the specified `encoding` and `format`.
|
2164 | */
|
2165 | getPublicKey(): Buffer;
|
2166 | getPublicKey(encoding: BinaryToTextEncoding, format?: ECDHKeyFormat): string;
|
2167 | /**
|
2168 | * Sets the EC Diffie-Hellman private key.
|
2169 | * If `encoding` is provided, `privateKey` is expected
|
2170 | * to be a string; otherwise `privateKey` is expected to be a `Buffer`,`TypedArray`, or `DataView`.
|
2171 | *
|
2172 | * If `privateKey` is not valid for the curve specified when the `ECDH` object was
|
2173 | * created, an error is thrown. Upon setting the private key, the associated
|
2174 | * public point (key) is also generated and set in the `ECDH` object.
|
2175 | * @since v0.11.14
|
2176 | * @param encoding The `encoding` of the `privateKey` string.
|
2177 | */
|
2178 | setPrivateKey(privateKey: NodeJS.ArrayBufferView): void;
|
2179 | setPrivateKey(privateKey: string, encoding: BinaryToTextEncoding): void;
|
2180 | }
|
2181 | /**
|
2182 | * Creates an Elliptic Curve Diffie-Hellman (`ECDH`) key exchange object using a
|
2183 | * predefined curve specified by the `curveName` string. Use {@link getCurves} to obtain a list of available curve names. On recent
|
2184 | * OpenSSL releases, `openssl ecparam -list_curves` will also display the name
|
2185 | * and description of each available elliptic curve.
|
2186 | * @since v0.11.14
|
2187 | */
|
2188 | function createECDH(curveName: string): ECDH;
|
2189 | /**
|
2190 | * This function is based on a constant-time algorithm.
|
2191 | * Returns true if `a` is equal to `b`, without leaking timing information that
|
2192 | * would allow an attacker to guess one of the values. This is suitable for
|
2193 | * comparing HMAC digests or secret values like authentication cookies or[capability urls](https://www.w3.org/TR/capability-urls/).
|
2194 | *
|
2195 | * `a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they
|
2196 | * must have the same byte length.
|
2197 | *
|
2198 | * If at least one of `a` and `b` is a `TypedArray` with more than one byte per
|
2199 | * entry, such as `Uint16Array`, the result will be computed using the platform
|
2200 | * byte order.
|
2201 | *
|
2202 | * Use of `crypto.timingSafeEqual` does not guarantee that the _surrounding_ code
|
2203 | * is timing-safe. Care should be taken to ensure that the surrounding code does
|
2204 | * not introduce timing vulnerabilities.
|
2205 | * @since v6.6.0
|
2206 | */
|
2207 | function timingSafeEqual(a: NodeJS.ArrayBufferView, b: NodeJS.ArrayBufferView): boolean;
|
2208 | /** @deprecated since v10.0.0 */
|
2209 | const DEFAULT_ENCODING: BufferEncoding;
|
2210 | type KeyType = 'rsa' | 'dsa' | 'ec' | 'ed25519' | 'ed448' | 'x25519' | 'x448';
|
2211 | type KeyFormat = 'pem' | 'der';
|
2212 | interface BasePrivateKeyEncodingOptions<T extends KeyFormat> {
|
2213 | format: T;
|
2214 | cipher?: string | undefined;
|
2215 | passphrase?: string | undefined;
|
2216 | }
|
2217 | interface KeyPairKeyObjectResult {
|
2218 | publicKey: KeyObject;
|
2219 | privateKey: KeyObject;
|
2220 | }
|
2221 | interface ED25519KeyPairKeyObjectOptions {}
|
2222 | interface ED448KeyPairKeyObjectOptions {}
|
2223 | interface X25519KeyPairKeyObjectOptions {}
|
2224 | interface X448KeyPairKeyObjectOptions {}
|
2225 | interface ECKeyPairKeyObjectOptions {
|
2226 | /**
|
2227 | * Name of the curve to use.
|
2228 | */
|
2229 | namedCurve: string;
|
2230 | }
|
2231 | interface RSAKeyPairKeyObjectOptions {
|
2232 | /**
|
2233 | * Key size in bits
|
2234 | */
|
2235 | modulusLength: number;
|
2236 | /**
|
2237 | * @default 0x10001
|
2238 | */
|
2239 | publicExponent?: number | undefined;
|
2240 | }
|
2241 | interface DSAKeyPairKeyObjectOptions {
|
2242 | /**
|
2243 | * Key size in bits
|
2244 | */
|
2245 | modulusLength: number;
|
2246 | /**
|
2247 | * Size of q in bits
|
2248 | */
|
2249 | divisorLength: number;
|
2250 | }
|
2251 | interface RSAKeyPairOptions<PubF extends KeyFormat, PrivF extends KeyFormat> {
|
2252 | /**
|
2253 | * Key size in bits
|
2254 | */
|
2255 | modulusLength: number;
|
2256 | /**
|
2257 | * @default 0x10001
|
2258 | */
|
2259 | publicExponent?: number | undefined;
|
2260 | publicKeyEncoding: {
|
2261 | type: 'pkcs1' | 'spki';
|
2262 | format: PubF;
|
2263 | };
|
2264 | privateKeyEncoding: BasePrivateKeyEncodingOptions<PrivF> & {
|
2265 | type: 'pkcs1' | 'pkcs8';
|
2266 | };
|
2267 | }
|
2268 | interface DSAKeyPairOptions<PubF extends KeyFormat, PrivF extends KeyFormat> {
|
2269 | /**
|
2270 | * Key size in bits
|
2271 | */
|
2272 | modulusLength: number;
|
2273 | /**
|
2274 | * Size of q in bits
|
2275 | */
|
2276 | divisorLength: number;
|
2277 | publicKeyEncoding: {
|
2278 | type: 'spki';
|
2279 | format: PubF;
|
2280 | };
|
2281 | privateKeyEncoding: BasePrivateKeyEncodingOptions<PrivF> & {
|
2282 | type: 'pkcs8';
|
2283 | };
|
2284 | }
|
2285 | interface ECKeyPairOptions<PubF extends KeyFormat, PrivF extends KeyFormat> {
|
2286 | /**
|
2287 | * Name of the curve to use.
|
2288 | */
|
2289 | namedCurve: string;
|
2290 | publicKeyEncoding: {
|
2291 | type: 'pkcs1' | 'spki';
|
2292 | format: PubF;
|
2293 | };
|
2294 | privateKeyEncoding: BasePrivateKeyEncodingOptions<PrivF> & {
|
2295 | type: 'sec1' | 'pkcs8';
|
2296 | };
|
2297 | }
|
2298 | interface ED25519KeyPairOptions<PubF extends KeyFormat, PrivF extends KeyFormat> {
|
2299 | publicKeyEncoding: {
|
2300 | type: 'spki';
|
2301 | format: PubF;
|
2302 | };
|
2303 | privateKeyEncoding: BasePrivateKeyEncodingOptions<PrivF> & {
|
2304 | type: 'pkcs8';
|
2305 | };
|
2306 | }
|
2307 | interface ED448KeyPairOptions<PubF extends KeyFormat, PrivF extends KeyFormat> {
|
2308 | publicKeyEncoding: {
|
2309 | type: 'spki';
|
2310 | format: PubF;
|
2311 | };
|
2312 | privateKeyEncoding: BasePrivateKeyEncodingOptions<PrivF> & {
|
2313 | type: 'pkcs8';
|
2314 | };
|
2315 | }
|
2316 | interface X25519KeyPairOptions<PubF extends KeyFormat, PrivF extends KeyFormat> {
|
2317 | publicKeyEncoding: {
|
2318 | type: 'spki';
|
2319 | format: PubF;
|
2320 | };
|
2321 | privateKeyEncoding: BasePrivateKeyEncodingOptions<PrivF> & {
|
2322 | type: 'pkcs8';
|
2323 | };
|
2324 | }
|
2325 | interface X448KeyPairOptions<PubF extends KeyFormat, PrivF extends KeyFormat> {
|
2326 | publicKeyEncoding: {
|
2327 | type: 'spki';
|
2328 | format: PubF;
|
2329 | };
|
2330 | privateKeyEncoding: BasePrivateKeyEncodingOptions<PrivF> & {
|
2331 | type: 'pkcs8';
|
2332 | };
|
2333 | }
|
2334 | interface KeyPairSyncResult<T1 extends string | Buffer, T2 extends string | Buffer> {
|
2335 | publicKey: T1;
|
2336 | privateKey: T2;
|
2337 | }
|
2338 | /**
|
2339 | * Generates a new asymmetric key pair of the given `type`. RSA, DSA, EC, Ed25519,
|
2340 | * Ed448, X25519, X448, and DH are currently supported.
|
2341 | *
|
2342 | * If a `publicKeyEncoding` or `privateKeyEncoding` was specified, this function
|
2343 | * behaves as if `keyObject.export()` had been called on its result. Otherwise,
|
2344 | * the respective part of the key is returned as a `KeyObject`.
|
2345 | *
|
2346 | * When encoding public keys, it is recommended to use `'spki'`. When encoding
|
2347 | * private keys, it is recommended to use `'pkcs8'` with a strong passphrase,
|
2348 | * and to keep the passphrase confidential.
|
2349 | *
|
2350 | * ```js
|
2351 | * const {
|
2352 | * generateKeyPairSync
|
2353 | * } = await import('crypto');
|
2354 | *
|
2355 | * const {
|
2356 | * publicKey,
|
2357 | * privateKey,
|
2358 | * } = generateKeyPairSync('rsa', {
|
2359 | * modulusLength: 4096,
|
2360 | * publicKeyEncoding: {
|
2361 | * type: 'spki',
|
2362 | * format: 'pem'
|
2363 | * },
|
2364 | * privateKeyEncoding: {
|
2365 | * type: 'pkcs8',
|
2366 | * format: 'pem',
|
2367 | * cipher: 'aes-256-cbc',
|
2368 | * passphrase: 'top secret'
|
2369 | * }
|
2370 | * });
|
2371 | * ```
|
2372 | *
|
2373 | * The return value `{ publicKey, privateKey }` represents the generated key pair.
|
2374 | * When PEM encoding was selected, the respective key will be a string, otherwise
|
2375 | * it will be a buffer containing the data encoded as DER.
|
2376 | * @since v10.12.0
|
2377 | * @param type Must be `'rsa'`, `'dsa'`, `'ec'`, `'ed25519'`, `'ed448'`, `'x25519'`, `'x448'`, or `'dh'`.
|
2378 | */
|
2379 | function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult<string, string>;
|
2380 | function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'pem', 'der'>): KeyPairSyncResult<string, Buffer>;
|
2381 | function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'der', 'pem'>): KeyPairSyncResult<Buffer, string>;
|
2382 | function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'der', 'der'>): KeyPairSyncResult<Buffer, Buffer>;
|
2383 | function generateKeyPairSync(type: 'rsa', options: RSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult;
|
2384 | function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult<string, string>;
|
2385 | function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'pem', 'der'>): KeyPairSyncResult<string, Buffer>;
|
2386 | function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'der', 'pem'>): KeyPairSyncResult<Buffer, string>;
|
2387 | function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'der', 'der'>): KeyPairSyncResult<Buffer, Buffer>;
|
2388 | function generateKeyPairSync(type: 'dsa', options: DSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult;
|
2389 | function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult<string, string>;
|
2390 | function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'pem', 'der'>): KeyPairSyncResult<string, Buffer>;
|
2391 | function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'der', 'pem'>): KeyPairSyncResult<Buffer, string>;
|
2392 | function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'der', 'der'>): KeyPairSyncResult<Buffer, Buffer>;
|
2393 | function generateKeyPairSync(type: 'ec', options: ECKeyPairKeyObjectOptions): KeyPairKeyObjectResult;
|
2394 | function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult<string, string>;
|
2395 | function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'der'>): KeyPairSyncResult<string, Buffer>;
|
2396 | function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'pem'>): KeyPairSyncResult<Buffer, string>;
|
2397 | function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'der'>): KeyPairSyncResult<Buffer, Buffer>;
|
2398 | function generateKeyPairSync(type: 'ed25519', options?: ED25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult;
|
2399 | function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult<string, string>;
|
2400 | function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'pem', 'der'>): KeyPairSyncResult<string, Buffer>;
|
2401 | function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'der', 'pem'>): KeyPairSyncResult<Buffer, string>;
|
2402 | function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'der', 'der'>): KeyPairSyncResult<Buffer, Buffer>;
|
2403 | function generateKeyPairSync(type: 'ed448', options?: ED448KeyPairKeyObjectOptions): KeyPairKeyObjectResult;
|
2404 | function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult<string, string>;
|
2405 | function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'pem', 'der'>): KeyPairSyncResult<string, Buffer>;
|
2406 | function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'der', 'pem'>): KeyPairSyncResult<Buffer, string>;
|
2407 | function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'der', 'der'>): KeyPairSyncResult<Buffer, Buffer>;
|
2408 | function generateKeyPairSync(type: 'x25519', options?: X25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult;
|
2409 | function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult<string, string>;
|
2410 | function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'pem', 'der'>): KeyPairSyncResult<string, Buffer>;
|
2411 | function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'der', 'pem'>): KeyPairSyncResult<Buffer, string>;
|
2412 | function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'der', 'der'>): KeyPairSyncResult<Buffer, Buffer>;
|
2413 | function generateKeyPairSync(type: 'x448', options?: X448KeyPairKeyObjectOptions): KeyPairKeyObjectResult;
|
2414 | /**
|
2415 | * Generates a new asymmetric key pair of the given `type`. RSA, DSA, EC, Ed25519,
|
2416 | * Ed448, X25519, X448, and DH are currently supported.
|
2417 | *
|
2418 | * If a `publicKeyEncoding` or `privateKeyEncoding` was specified, this function
|
2419 | * behaves as if `keyObject.export()` had been called on its result. Otherwise,
|
2420 | * the respective part of the key is returned as a `KeyObject`.
|
2421 | *
|
2422 | * It is recommended to encode public keys as `'spki'` and private keys as`'pkcs8'` with encryption for long-term storage:
|
2423 | *
|
2424 | * ```js
|
2425 | * const {
|
2426 | * generateKeyPair
|
2427 | * } = await import('crypto');
|
2428 | *
|
2429 | * generateKeyPair('rsa', {
|
2430 | * modulusLength: 4096,
|
2431 | * publicKeyEncoding: {
|
2432 | * type: 'spki',
|
2433 | * format: 'pem'
|
2434 | * },
|
2435 | * privateKeyEncoding: {
|
2436 | * type: 'pkcs8',
|
2437 | * format: 'pem',
|
2438 | * cipher: 'aes-256-cbc',
|
2439 | * passphrase: 'top secret'
|
2440 | * }
|
2441 | * }, (err, publicKey, privateKey) => {
|
2442 | *
|
2443 | * });
|
2444 | * ```
|
2445 | *
|
2446 | * On completion, `callback` will be called with `err` set to `undefined` and`publicKey` / `privateKey` representing the generated key pair.
|
2447 | *
|
2448 | * If this method is invoked as its `util.promisify()` ed version, it returns
|
2449 | * a `Promise` for an `Object` with `publicKey` and `privateKey` properties.
|
2450 | * @since v10.12.0
|
2451 | * @param type Must be `'rsa'`, `'dsa'`, `'ec'`, `'ed25519'`, `'ed448'`, `'x25519'`, `'x448'`, or `'dh'`.
|
2452 | */
|
2453 | function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void;
|
2454 | function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void;
|
2455 | function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void;
|
2456 | function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void;
|
2457 | function generateKeyPair(type: 'rsa', options: RSAKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void;
|
2458 | function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void;
|
2459 | function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void;
|
2460 | function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void;
|
2461 | function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void;
|
2462 | function generateKeyPair(type: 'dsa', options: DSAKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void;
|
2463 | function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void;
|
2464 | function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void;
|
2465 | function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void;
|
2466 | function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void;
|
2467 | function generateKeyPair(type: 'ec', options: ECKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void;
|
2468 | function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void;
|
2469 | function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void;
|
2470 | function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void;
|
2471 | function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void;
|
2472 | function generateKeyPair(type: 'ed25519', options: ED25519KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void;
|
2473 | function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void;
|
2474 | function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void;
|
2475 | function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void;
|
2476 | function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void;
|
2477 | function generateKeyPair(type: 'ed448', options: ED448KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void;
|
2478 | function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void;
|
2479 | function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void;
|
2480 | function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void;
|
2481 | function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void;
|
2482 | function generateKeyPair(type: 'x25519', options: X25519KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void;
|
2483 | function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void;
|
2484 | function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void;
|
2485 | function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void;
|
2486 | function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void;
|
2487 | function generateKeyPair(type: 'x448', options: X448KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void;
|
2488 | namespace generateKeyPair {
|
2489 | function __promisify__(
|
2490 | type: 'rsa',
|
2491 | options: RSAKeyPairOptions<'pem', 'pem'>
|
2492 | ): Promise<{
|
2493 | publicKey: string;
|
2494 | privateKey: string;
|
2495 | }>;
|
2496 | function __promisify__(
|
2497 | type: 'rsa',
|
2498 | options: RSAKeyPairOptions<'pem', 'der'>
|
2499 | ): Promise<{
|
2500 | publicKey: string;
|
2501 | privateKey: Buffer;
|
2502 | }>;
|
2503 | function __promisify__(
|
2504 | type: 'rsa',
|
2505 | options: RSAKeyPairOptions<'der', 'pem'>
|
2506 | ): Promise<{
|
2507 | publicKey: Buffer;
|
2508 | privateKey: string;
|
2509 | }>;
|
2510 | function __promisify__(
|
2511 | type: 'rsa',
|
2512 | options: RSAKeyPairOptions<'der', 'der'>
|
2513 | ): Promise<{
|
2514 | publicKey: Buffer;
|
2515 | privateKey: Buffer;
|
2516 | }>;
|
2517 | function __promisify__(type: 'rsa', options: RSAKeyPairKeyObjectOptions): Promise<KeyPairKeyObjectResult>;
|
2518 | function __promisify__(
|
2519 | type: 'dsa',
|
2520 | options: DSAKeyPairOptions<'pem', 'pem'>
|
2521 | ): Promise<{
|
2522 | publicKey: string;
|
2523 | privateKey: string;
|
2524 | }>;
|
2525 | function __promisify__(
|
2526 | type: 'dsa',
|
2527 | options: DSAKeyPairOptions<'pem', 'der'>
|
2528 | ): Promise<{
|
2529 | publicKey: string;
|
2530 | privateKey: Buffer;
|
2531 | }>;
|
2532 | function __promisify__(
|
2533 | type: 'dsa',
|
2534 | options: DSAKeyPairOptions<'der', 'pem'>
|
2535 | ): Promise<{
|
2536 | publicKey: Buffer;
|
2537 | privateKey: string;
|
2538 | }>;
|
2539 | function __promisify__(
|
2540 | type: 'dsa',
|
2541 | options: DSAKeyPairOptions<'der', 'der'>
|
2542 | ): Promise<{
|
2543 | publicKey: Buffer;
|
2544 | privateKey: Buffer;
|
2545 | }>;
|
2546 | function __promisify__(type: 'dsa', options: DSAKeyPairKeyObjectOptions): Promise<KeyPairKeyObjectResult>;
|
2547 | function __promisify__(
|
2548 | type: 'ec',
|
2549 | options: ECKeyPairOptions<'pem', 'pem'>
|
2550 | ): Promise<{
|
2551 | publicKey: string;
|
2552 | privateKey: string;
|
2553 | }>;
|
2554 | function __promisify__(
|
2555 | type: 'ec',
|
2556 | options: ECKeyPairOptions<'pem', 'der'>
|
2557 | ): Promise<{
|
2558 | publicKey: string;
|
2559 | privateKey: Buffer;
|
2560 | }>;
|
2561 | function __promisify__(
|
2562 | type: 'ec',
|
2563 | options: ECKeyPairOptions<'der', 'pem'>
|
2564 | ): Promise<{
|
2565 | publicKey: Buffer;
|
2566 | privateKey: string;
|
2567 | }>;
|
2568 | function __promisify__(
|
2569 | type: 'ec',
|
2570 | options: ECKeyPairOptions<'der', 'der'>
|
2571 | ): Promise<{
|
2572 | publicKey: Buffer;
|
2573 | privateKey: Buffer;
|
2574 | }>;
|
2575 | function __promisify__(type: 'ec', options: ECKeyPairKeyObjectOptions): Promise<KeyPairKeyObjectResult>;
|
2576 | function __promisify__(
|
2577 | type: 'ed25519',
|
2578 | options: ED25519KeyPairOptions<'pem', 'pem'>
|
2579 | ): Promise<{
|
2580 | publicKey: string;
|
2581 | privateKey: string;
|
2582 | }>;
|
2583 | function __promisify__(
|
2584 | type: 'ed25519',
|
2585 | options: ED25519KeyPairOptions<'pem', 'der'>
|
2586 | ): Promise<{
|
2587 | publicKey: string;
|
2588 | privateKey: Buffer;
|
2589 | }>;
|
2590 | function __promisify__(
|
2591 | type: 'ed25519',
|
2592 | options: ED25519KeyPairOptions<'der', 'pem'>
|
2593 | ): Promise<{
|
2594 | publicKey: Buffer;
|
2595 | privateKey: string;
|
2596 | }>;
|
2597 | function __promisify__(
|
2598 | type: 'ed25519',
|
2599 | options: ED25519KeyPairOptions<'der', 'der'>
|
2600 | ): Promise<{
|
2601 | publicKey: Buffer;
|
2602 | privateKey: Buffer;
|
2603 | }>;
|
2604 | function __promisify__(type: 'ed25519', options?: ED25519KeyPairKeyObjectOptions): Promise<KeyPairKeyObjectResult>;
|
2605 | function __promisify__(
|
2606 | type: 'ed448',
|
2607 | options: ED448KeyPairOptions<'pem', 'pem'>
|
2608 | ): Promise<{
|
2609 | publicKey: string;
|
2610 | privateKey: string;
|
2611 | }>;
|
2612 | function __promisify__(
|
2613 | type: 'ed448',
|
2614 | options: ED448KeyPairOptions<'pem', 'der'>
|
2615 | ): Promise<{
|
2616 | publicKey: string;
|
2617 | privateKey: Buffer;
|
2618 | }>;
|
2619 | function __promisify__(
|
2620 | type: 'ed448',
|
2621 | options: ED448KeyPairOptions<'der', 'pem'>
|
2622 | ): Promise<{
|
2623 | publicKey: Buffer;
|
2624 | privateKey: string;
|
2625 | }>;
|
2626 | function __promisify__(
|
2627 | type: 'ed448',
|
2628 | options: ED448KeyPairOptions<'der', 'der'>
|
2629 | ): Promise<{
|
2630 | publicKey: Buffer;
|
2631 | privateKey: Buffer;
|
2632 | }>;
|
2633 | function __promisify__(type: 'ed448', options?: ED448KeyPairKeyObjectOptions): Promise<KeyPairKeyObjectResult>;
|
2634 | function __promisify__(
|
2635 | type: 'x25519',
|
2636 | options: X25519KeyPairOptions<'pem', 'pem'>
|
2637 | ): Promise<{
|
2638 | publicKey: string;
|
2639 | privateKey: string;
|
2640 | }>;
|
2641 | function __promisify__(
|
2642 | type: 'x25519',
|
2643 | options: X25519KeyPairOptions<'pem', 'der'>
|
2644 | ): Promise<{
|
2645 | publicKey: string;
|
2646 | privateKey: Buffer;
|
2647 | }>;
|
2648 | function __promisify__(
|
2649 | type: 'x25519',
|
2650 | options: X25519KeyPairOptions<'der', 'pem'>
|
2651 | ): Promise<{
|
2652 | publicKey: Buffer;
|
2653 | privateKey: string;
|
2654 | }>;
|
2655 | function __promisify__(
|
2656 | type: 'x25519',
|
2657 | options: X25519KeyPairOptions<'der', 'der'>
|
2658 | ): Promise<{
|
2659 | publicKey: Buffer;
|
2660 | privateKey: Buffer;
|
2661 | }>;
|
2662 | function __promisify__(type: 'x25519', options?: X25519KeyPairKeyObjectOptions): Promise<KeyPairKeyObjectResult>;
|
2663 | function __promisify__(
|
2664 | type: 'x448',
|
2665 | options: X448KeyPairOptions<'pem', 'pem'>
|
2666 | ): Promise<{
|
2667 | publicKey: string;
|
2668 | privateKey: string;
|
2669 | }>;
|
2670 | function __promisify__(
|
2671 | type: 'x448',
|
2672 | options: X448KeyPairOptions<'pem', 'der'>
|
2673 | ): Promise<{
|
2674 | publicKey: string;
|
2675 | privateKey: Buffer;
|
2676 | }>;
|
2677 | function __promisify__(
|
2678 | type: 'x448',
|
2679 | options: X448KeyPairOptions<'der', 'pem'>
|
2680 | ): Promise<{
|
2681 | publicKey: Buffer;
|
2682 | privateKey: string;
|
2683 | }>;
|
2684 | function __promisify__(
|
2685 | type: 'x448',
|
2686 | options: X448KeyPairOptions<'der', 'der'>
|
2687 | ): Promise<{
|
2688 | publicKey: Buffer;
|
2689 | privateKey: Buffer;
|
2690 | }>;
|
2691 | function __promisify__(type: 'x448', options?: X448KeyPairKeyObjectOptions): Promise<KeyPairKeyObjectResult>;
|
2692 | }
|
2693 | /**
|
2694 | * Calculates and returns the signature for `data` using the given private key and
|
2695 | * algorithm. If `algorithm` is `null` or `undefined`, then the algorithm is
|
2696 | * dependent upon the key type (especially Ed25519 and Ed448).
|
2697 | *
|
2698 | * If `key` is not a `KeyObject`, this function behaves as if `key` had been
|
2699 | * passed to {@link createPrivateKey}. If it is an object, the following
|
2700 | * additional properties can be passed:
|
2701 | *
|
2702 | * If the `callback` function is provided this function uses libuv's threadpool.
|
2703 | * @since v12.0.0
|
2704 | */
|
2705 | function sign(algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, key: KeyLike | SignKeyObjectInput | SignPrivateKeyInput): Buffer;
|
2706 | function sign(
|
2707 | algorithm: string | null | undefined,
|
2708 | data: NodeJS.ArrayBufferView,
|
2709 | key: KeyLike | SignKeyObjectInput | SignPrivateKeyInput,
|
2710 | callback: (error: Error | null, data: Buffer) => void
|
2711 | ): void;
|
2712 | /**
|
2713 | * Verifies the given signature for `data` using the given key and algorithm. If`algorithm` is `null` or `undefined`, then the algorithm is dependent upon the
|
2714 | * key type (especially Ed25519 and Ed448).
|
2715 | *
|
2716 | * If `key` is not a `KeyObject`, this function behaves as if `key` had been
|
2717 | * passed to {@link createPublicKey}. If it is an object, the following
|
2718 | * additional properties can be passed:
|
2719 | *
|
2720 | * The `signature` argument is the previously calculated signature for the `data`.
|
2721 | *
|
2722 | * Because public keys can be derived from private keys, a private key or a public
|
2723 | * key may be passed for `key`.
|
2724 | *
|
2725 | * If the `callback` function is provided this function uses libuv's threadpool.
|
2726 | * @since v12.0.0
|
2727 | */
|
2728 | function verify(algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, signature: NodeJS.ArrayBufferView): boolean;
|
2729 | function verify(
|
2730 | algorithm: string | null | undefined,
|
2731 | data: NodeJS.ArrayBufferView,
|
2732 | key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput,
|
2733 | signature: NodeJS.ArrayBufferView,
|
2734 | callback: (error: Error | null, result: boolean) => void
|
2735 | ): void;
|
2736 | /**
|
2737 | * Computes the Diffie-Hellman secret based on a `privateKey` and a `publicKey`.
|
2738 | * Both keys must have the same `asymmetricKeyType`, which must be one of `'dh'`(for Diffie-Hellman), `'ec'` (for ECDH), `'x448'`, or `'x25519'` (for ECDH-ES).
|
2739 | * @since v13.9.0, v12.17.0
|
2740 | */
|
2741 | function diffieHellman(options: { privateKey: KeyObject; publicKey: KeyObject }): Buffer;
|
2742 | type CipherMode = 'cbc' | 'ccm' | 'cfb' | 'ctr' | 'ecb' | 'gcm' | 'ocb' | 'ofb' | 'stream' | 'wrap' | 'xts';
|
2743 | interface CipherInfoOptions {
|
2744 | /**
|
2745 | * A test key length.
|
2746 | */
|
2747 | keyLength?: number | undefined;
|
2748 | /**
|
2749 | * A test IV length.
|
2750 | */
|
2751 | ivLength?: number | undefined;
|
2752 | }
|
2753 | interface CipherInfo {
|
2754 | /**
|
2755 | * The name of the cipher.
|
2756 | */
|
2757 | name: string;
|
2758 | /**
|
2759 | * The nid of the cipher.
|
2760 | */
|
2761 | nid: number;
|
2762 | /**
|
2763 | * The block size of the cipher in bytes.
|
2764 | * This property is omitted when mode is 'stream'.
|
2765 | */
|
2766 | blockSize?: number | undefined;
|
2767 | /**
|
2768 | * The expected or default initialization vector length in bytes.
|
2769 | * This property is omitted if the cipher does not use an initialization vector.
|
2770 | */
|
2771 | ivLength?: number | undefined;
|
2772 | /**
|
2773 | * The expected or default key length in bytes.
|
2774 | */
|
2775 | keyLength: number;
|
2776 | /**
|
2777 | * The cipher mode.
|
2778 | */
|
2779 | mode: CipherMode;
|
2780 | }
|
2781 | /**
|
2782 | * Returns information about a given cipher.
|
2783 | *
|
2784 | * Some ciphers accept variable length keys and initialization vectors. By default,
|
2785 | * the `crypto.getCipherInfo()` method will return the default values for these
|
2786 | * ciphers. To test if a given key length or iv length is acceptable for given
|
2787 | * cipher, use the `keyLength` and `ivLength` options. If the given values are
|
2788 | * unacceptable, `undefined` will be returned.
|
2789 | * @since v15.0.0
|
2790 | * @param nameOrNid The name or nid of the cipher to query.
|
2791 | */
|
2792 | function getCipherInfo(nameOrNid: string | number, options?: CipherInfoOptions): CipherInfo | undefined;
|
2793 | /**
|
2794 | * HKDF is a simple key derivation function defined in RFC 5869\. The given `key`,`salt` and `info` are used with the `digest` to derive a key of `keylen` bytes.
|
2795 | *
|
2796 | * The supplied `callback` function is called with two arguments: `err` and`derivedKey`. If an errors occurs while deriving the key, `err` will be set;
|
2797 | * otherwise `err` will be `null`. The successfully generated `derivedKey` will
|
2798 | * be passed to the callback as an [<ArrayBuffer>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer). An error will be thrown if any
|
2799 | * of the input arguments specify invalid values or types.
|
2800 | *
|
2801 | * ```js
|
2802 | * import { Buffer } from 'buffer';
|
2803 | * const {
|
2804 | * hkdf
|
2805 | * } = await import('crypto');
|
2806 | *
|
2807 | * hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
|
2808 | * if (err) throw err;
|
2809 | * console.log(Buffer.from(derivedKey).toString('hex'));
|
2810 | * });
|
2811 | * ```
|
2812 | * @since v15.0.0
|
2813 | * @param digest The digest algorithm to use.
|
2814 | * @param key The secret key. It must be at least one byte in length.
|
2815 | * @param salt The salt value. Must be provided but can be zero-length.
|
2816 | * @param info Additional info value. Must be provided but can be zero-length, and cannot be more than 1024 bytes.
|
2817 | * @param keylen The length of the key to generate. Must be greater than 0. The maximum allowable value is `255` times the number of bytes produced by the selected digest function (e.g. `sha512`
|
2818 | * generates 64-byte hashes, making the maximum HKDF output 16320 bytes).
|
2819 | */
|
2820 | function hkdf(digest: string, key: BinaryLike | KeyObject, salt: BinaryLike, info: BinaryLike, keylen: number, callback: (err: Error | null, derivedKey: ArrayBuffer) => void): void;
|
2821 | /**
|
2822 | * Provides a synchronous HKDF key derivation function as defined in RFC 5869\. The
|
2823 | * given `key`, `salt` and `info` are used with the `digest` to derive a key of`keylen` bytes.
|
2824 | *
|
2825 | * The successfully generated `derivedKey` will be returned as an [<ArrayBuffer>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer).
|
2826 | *
|
2827 | * An error will be thrown if any of the input arguments specify invalid values or
|
2828 | * types, or if the derived key cannot be generated.
|
2829 | *
|
2830 | * ```js
|
2831 | * import { Buffer } from 'buffer';
|
2832 | * const {
|
2833 | * hkdfSync
|
2834 | * } = await import('crypto');
|
2835 | *
|
2836 | * const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
|
2837 | * console.log(Buffer.from(derivedKey).toString('hex'));
|
2838 | * ```
|
2839 | * @since v15.0.0
|
2840 | * @param digest The digest algorithm to use.
|
2841 | * @param key The secret key. It must be at least one byte in length.
|
2842 | * @param salt The salt value. Must be provided but can be zero-length.
|
2843 | * @param info Additional info value. Must be provided but can be zero-length, and cannot be more than 1024 bytes.
|
2844 | * @param keylen The length of the key to generate. Must be greater than 0. The maximum allowable value is `255` times the number of bytes produced by the selected digest function (e.g. `sha512`
|
2845 | * generates 64-byte hashes, making the maximum HKDF output 16320 bytes).
|
2846 | */
|
2847 | function hkdfSync(digest: string, key: BinaryLike | KeyObject, salt: BinaryLike, info: BinaryLike, keylen: number): ArrayBuffer;
|
2848 | interface SecureHeapUsage {
|
2849 | /**
|
2850 | * The total allocated secure heap size as specified using the `--secure-heap=n` command-line flag.
|
2851 | */
|
2852 | total: number;
|
2853 | /**
|
2854 | * The minimum allocation from the secure heap as specified using the `--secure-heap-min` command-line flag.
|
2855 | */
|
2856 | min: number;
|
2857 | /**
|
2858 | * The total number of bytes currently allocated from the secure heap.
|
2859 | */
|
2860 | used: number;
|
2861 | /**
|
2862 | * The calculated ratio of `used` to `total` allocated bytes.
|
2863 | */
|
2864 | utilization: number;
|
2865 | }
|
2866 | /**
|
2867 | * @since v15.6.0
|
2868 | */
|
2869 | function secureHeapUsed(): SecureHeapUsage;
|
2870 | interface RandomUUIDOptions {
|
2871 | /**
|
2872 | * By default, to improve performance,
|
2873 | * Node.js will pre-emptively generate and persistently cache enough
|
2874 | * random data to generate up to 128 random UUIDs. To generate a UUID
|
2875 | * without using the cache, set `disableEntropyCache` to `true`.
|
2876 | *
|
2877 | * @default `false`
|
2878 | */
|
2879 | disableEntropyCache?: boolean | undefined;
|
2880 | }
|
2881 | /**
|
2882 | * Generates a random [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122.txt) Version 4 UUID. The UUID is generated using a
|
2883 | * cryptographic pseudorandom number generator.
|
2884 | * @since v15.6.0
|
2885 | */
|
2886 | function randomUUID(options?: RandomUUIDOptions): string;
|
2887 | interface X509CheckOptions {
|
2888 | /**
|
2889 | * @default 'always'
|
2890 | */
|
2891 | subject: 'always' | 'never';
|
2892 | /**
|
2893 | * @default true
|
2894 | */
|
2895 | wildcards: boolean;
|
2896 | /**
|
2897 | * @default true
|
2898 | */
|
2899 | partialWildcards: boolean;
|
2900 | /**
|
2901 | * @default false
|
2902 | */
|
2903 | multiLabelWildcards: boolean;
|
2904 | /**
|
2905 | * @default false
|
2906 | */
|
2907 | singleLabelSubdomains: boolean;
|
2908 | }
|
2909 | /**
|
2910 | * Encapsulates an X509 certificate and provides read-only access to
|
2911 | * its information.
|
2912 | *
|
2913 | * ```js
|
2914 | * const { X509Certificate } = await import('crypto');
|
2915 | *
|
2916 | * const x509 = new X509Certificate('{... pem encoded cert ...}');
|
2917 | *
|
2918 | * console.log(x509.subject);
|
2919 | * ```
|
2920 | * @since v15.6.0
|
2921 | */
|
2922 | class X509Certificate {
|
2923 | /**
|
2924 | * Will be \`true\` if this is a Certificate Authority (ca) certificate.
|
2925 | * @since v15.6.0
|
2926 | */
|
2927 | readonly ca: boolean;
|
2928 | /**
|
2929 | * The SHA-1 fingerprint of this certificate.
|
2930 | * @since v15.6.0
|
2931 | */
|
2932 | readonly fingerprint: string;
|
2933 | /**
|
2934 | * The SHA-256 fingerprint of this certificate.
|
2935 | * @since v15.6.0
|
2936 | */
|
2937 | readonly fingerprint256: string;
|
2938 | /**
|
2939 | * The complete subject of this certificate.
|
2940 | * @since v15.6.0
|
2941 | */
|
2942 | readonly subject: string;
|
2943 | /**
|
2944 | * The subject alternative name specified for this certificate.
|
2945 | * @since v15.6.0
|
2946 | */
|
2947 | readonly subjectAltName: string;
|
2948 | /**
|
2949 | * The information access content of this certificate.
|
2950 | * @since v15.6.0
|
2951 | */
|
2952 | readonly infoAccess: string;
|
2953 | /**
|
2954 | * An array detailing the key usages for this certificate.
|
2955 | * @since v15.6.0
|
2956 | */
|
2957 | readonly keyUsage: string[];
|
2958 | /**
|
2959 | * The issuer identification included in this certificate.
|
2960 | * @since v15.6.0
|
2961 | */
|
2962 | readonly issuer: string;
|
2963 | /**
|
2964 | * The issuer certificate or `undefined` if the issuer certificate is not
|
2965 | * available.
|
2966 | * @since v15.9.0
|
2967 | */
|
2968 | readonly issuerCertificate?: X509Certificate | undefined;
|
2969 | /**
|
2970 | * The public key `<KeyObject>` for this certificate.
|
2971 | * @since v15.6.0
|
2972 | */
|
2973 | readonly publicKey: KeyObject;
|
2974 | /**
|
2975 | * A `Buffer` containing the DER encoding of this certificate.
|
2976 | * @since v15.6.0
|
2977 | */
|
2978 | readonly raw: Buffer;
|
2979 | /**
|
2980 | * The serial number of this certificate.
|
2981 | * @since v15.6.0
|
2982 | */
|
2983 | readonly serialNumber: string;
|
2984 | /**
|
2985 | * The date/time from which this certificate is considered valid.
|
2986 | * @since v15.6.0
|
2987 | */
|
2988 | readonly validFrom: string;
|
2989 | /**
|
2990 | * The date/time until which this certificate is considered valid.
|
2991 | * @since v15.6.0
|
2992 | */
|
2993 | readonly validTo: string;
|
2994 | constructor(buffer: BinaryLike);
|
2995 | /**
|
2996 | * Checks whether the certificate matches the given email address.
|
2997 | * @since v15.6.0
|
2998 | * @return Returns `email` if the certificate matches, `undefined` if it does not.
|
2999 | */
|
3000 | checkEmail(email: string, options?: X509CheckOptions): string | undefined;
|
3001 | /**
|
3002 | * Checks whether the certificate matches the given host name.
|
3003 | * @since v15.6.0
|
3004 | * @return Returns `name` if the certificate matches, `undefined` if it does not.
|
3005 | */
|
3006 | checkHost(name: string, options?: X509CheckOptions): string | undefined;
|
3007 | /**
|
3008 | * Checks whether the certificate matches the given IP address (IPv4 or IPv6).
|
3009 | * @since v15.6.0
|
3010 | * @return Returns `ip` if the certificate matches, `undefined` if it does not.
|
3011 | */
|
3012 | checkIP(ip: string, options?: X509CheckOptions): string | undefined;
|
3013 | /**
|
3014 | * Checks whether this certificate was issued by the given `otherCert`.
|
3015 | * @since v15.6.0
|
3016 | */
|
3017 | checkIssued(otherCert: X509Certificate): boolean;
|
3018 | /**
|
3019 | * Checks whether the public key for this certificate is consistent with
|
3020 | * the given private key.
|
3021 | * @since v15.6.0
|
3022 | * @param privateKey A private key.
|
3023 | */
|
3024 | checkPrivateKey(privateKey: KeyObject): boolean;
|
3025 | /**
|
3026 | * There is no standard JSON encoding for X509 certificates. The`toJSON()` method returns a string containing the PEM encoded
|
3027 | * certificate.
|
3028 | * @since v15.6.0
|
3029 | */
|
3030 | toJSON(): string;
|
3031 | /**
|
3032 | * Returns information about this certificate using the legacy `certificate object` encoding.
|
3033 | * @since v15.6.0
|
3034 | */
|
3035 | toLegacyObject(): PeerCertificate;
|
3036 | /**
|
3037 | * Returns the PEM-encoded certificate.
|
3038 | * @since v15.6.0
|
3039 | */
|
3040 | toString(): string;
|
3041 | /**
|
3042 | * Verifies that this certificate was signed by the given public key.
|
3043 | * Does not perform any other validation checks on the certificate.
|
3044 | * @since v15.6.0
|
3045 | * @param publicKey A public key.
|
3046 | */
|
3047 | verify(publicKey: KeyObject): boolean;
|
3048 | }
|
3049 | type LargeNumberLike = NodeJS.ArrayBufferView | SharedArrayBuffer | ArrayBuffer | bigint;
|
3050 | interface GeneratePrimeOptions {
|
3051 | add?: LargeNumberLike | undefined;
|
3052 | rem?: LargeNumberLike | undefined;
|
3053 | /**
|
3054 | * @default false
|
3055 | */
|
3056 | safe?: boolean | undefined;
|
3057 | bigint?: boolean | undefined;
|
3058 | }
|
3059 | interface GeneratePrimeOptionsBigInt extends GeneratePrimeOptions {
|
3060 | bigint: true;
|
3061 | }
|
3062 | interface GeneratePrimeOptionsArrayBuffer extends GeneratePrimeOptions {
|
3063 | bigint?: false | undefined;
|
3064 | }
|
3065 | /**
|
3066 | * Generates a pseudorandom prime of `size` bits.
|
3067 | *
|
3068 | * If `options.safe` is `true`, the prime will be a safe prime -- that is,`(prime - 1) / 2` will also be a prime.
|
3069 | *
|
3070 | * The `options.add` and `options.rem` parameters can be used to enforce additional
|
3071 | * requirements, e.g., for Diffie-Hellman:
|
3072 | *
|
3073 | * * If `options.add` and `options.rem` are both set, the prime will satisfy the
|
3074 | * condition that `prime % add = rem`.
|
3075 | * * If only `options.add` is set and `options.safe` is not `true`, the prime will
|
3076 | * satisfy the condition that `prime % add = 1`.
|
3077 | * * If only `options.add` is set and `options.safe` is set to `true`, the prime
|
3078 | * will instead satisfy the condition that `prime % add = 3`. This is necessary
|
3079 | * because `prime % add = 1` for `options.add > 2` would contradict the condition
|
3080 | * enforced by `options.safe`.
|
3081 | * * `options.rem` is ignored if `options.add` is not given.
|
3082 | *
|
3083 | * Both `options.add` and `options.rem` must be encoded as big-endian sequences
|
3084 | * if given as an `ArrayBuffer`, `SharedArrayBuffer`, `TypedArray`, `Buffer`, or`DataView`.
|
3085 | *
|
3086 | * By default, the prime is encoded as a big-endian sequence of octets
|
3087 | * in an [<ArrayBuffer>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer). If the `bigint` option is `true`, then a
|
3088 | * [<bigint>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)is provided.
|
3089 | * @since v15.8.0
|
3090 | * @param size The size (in bits) of the prime to generate.
|
3091 | */
|
3092 | function generatePrime(size: number, callback: (err: Error | null, prime: ArrayBuffer) => void): void;
|
3093 | function generatePrime(size: number, options: GeneratePrimeOptionsBigInt, callback: (err: Error | null, prime: bigint) => void): void;
|
3094 | function generatePrime(size: number, options: GeneratePrimeOptionsArrayBuffer, callback: (err: Error | null, prime: ArrayBuffer) => void): void;
|
3095 | function generatePrime(size: number, options: GeneratePrimeOptions, callback: (err: Error | null, prime: ArrayBuffer | bigint) => void): void;
|
3096 | /**
|
3097 | * Generates a pseudorandom prime of `size` bits.
|
3098 | *
|
3099 | * If `options.safe` is `true`, the prime will be a safe prime -- that is,`(prime - 1) / 2` will also be a prime.
|
3100 | *
|
3101 | * The `options.add` and `options.rem` parameters can be used to enforce additional
|
3102 | * requirements, e.g., for Diffie-Hellman:
|
3103 | *
|
3104 | * * If `options.add` and `options.rem` are both set, the prime will satisfy the
|
3105 | * condition that `prime % add = rem`.
|
3106 | * * If only `options.add` is set and `options.safe` is not `true`, the prime will
|
3107 | * satisfy the condition that `prime % add = 1`.
|
3108 | * * If only `options.add` is set and `options.safe` is set to `true`, the prime
|
3109 | * will instead satisfy the condition that `prime % add = 3`. This is necessary
|
3110 | * because `prime % add = 1` for `options.add > 2` would contradict the condition
|
3111 | * enforced by `options.safe`.
|
3112 | * * `options.rem` is ignored if `options.add` is not given.
|
3113 | *
|
3114 | * Both `options.add` and `options.rem` must be encoded as big-endian sequences
|
3115 | * if given as an `ArrayBuffer`, `SharedArrayBuffer`, `TypedArray`, `Buffer`, or`DataView`.
|
3116 | *
|
3117 | * By default, the prime is encoded as a big-endian sequence of octets
|
3118 | * in an [<ArrayBuffer>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer). If the `bigint` option is `true`, then a
|
3119 | * [<bigint>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)is provided.
|
3120 | * @since v15.8.0
|
3121 | * @param size The size (in bits) of the prime to generate.
|
3122 | */
|
3123 | function generatePrimeSync(size: number): ArrayBuffer;
|
3124 | function generatePrimeSync(size: number, options: GeneratePrimeOptionsBigInt): bigint;
|
3125 | function generatePrimeSync(size: number, options: GeneratePrimeOptionsArrayBuffer): ArrayBuffer;
|
3126 | function generatePrimeSync(size: number, options: GeneratePrimeOptions): ArrayBuffer | bigint;
|
3127 | interface CheckPrimeOptions {
|
3128 | /**
|
3129 | * The number of Miller-Rabin probabilistic primality iterations to perform.
|
3130 | * When the value is 0 (zero), a number of checks is used that yields a false positive rate of at most 2-64 for random input.
|
3131 | * Care must be used when selecting a number of checks.
|
3132 | * Refer to the OpenSSL documentation for the BN_is_prime_ex function nchecks options for more details.
|
3133 | *
|
3134 | * @default 0
|
3135 | */
|
3136 | checks?: number | undefined;
|
3137 | }
|
3138 | /**
|
3139 | * Checks the primality of the `candidate`.
|
3140 | * @since v15.8.0
|
3141 | * @param candidate A possible prime encoded as a sequence of big endian octets of arbitrary length.
|
3142 | */
|
3143 | function checkPrime(value: LargeNumberLike, callback: (err: Error | null, result: boolean) => void): void;
|
3144 | function checkPrime(value: LargeNumberLike, options: CheckPrimeOptions, callback: (err: Error | null, result: boolean) => void): void;
|
3145 | /**
|
3146 | * Checks the primality of the `candidate`.
|
3147 | * @since v15.8.0
|
3148 | * @param candidate A possible prime encoded as a sequence of big endian octets of arbitrary length.
|
3149 | * @return `true` if the candidate is a prime with an error probability less than `0.25 ** options.checks`.
|
3150 | */
|
3151 | function checkPrimeSync(candidate: LargeNumberLike, options?: CheckPrimeOptions): boolean;
|
3152 | namespace webcrypto {
|
3153 | class CryptoKey {} // placeholder
|
3154 | }
|
3155 | }
|
3156 | declare module 'node:crypto' {
|
3157 | export * from 'crypto';
|
3158 | }
|
3159 |
|
\ | No newline at end of file |