1
|
|
|
declare module "tls" { |
2
|
|
|
import * as crypto from "crypto"; |
3
|
|
|
import * as dns from "dns"; |
4
|
|
|
import * as net from "net"; |
5
|
|
|
import * as stream from "stream"; |
6
|
|
|
|
7
|
|
|
const CLIENT_RENEG_LIMIT: number; |
8
|
|
|
const CLIENT_RENEG_WINDOW: number; |
9
|
|
|
|
10
|
|
|
interface Certificate { |
11
|
|
|
/** |
12
|
|
|
* Country code. |
13
|
|
|
*/ |
14
|
|
|
C: string; |
15
|
|
|
/** |
16
|
|
|
* Street. |
17
|
|
|
*/ |
18
|
|
|
ST: string; |
19
|
|
|
/** |
20
|
|
|
* Locality. |
21
|
|
|
*/ |
22
|
|
|
L: string; |
23
|
|
|
/** |
24
|
|
|
* Organization. |
25
|
|
|
*/ |
26
|
|
|
O: string; |
27
|
|
|
/** |
28
|
|
|
* Organizational unit. |
29
|
|
|
*/ |
30
|
|
|
OU: string; |
31
|
|
|
/** |
32
|
|
|
* Common name. |
33
|
|
|
*/ |
34
|
|
|
CN: string; |
35
|
|
|
} |
36
|
|
|
|
37
|
|
|
interface PeerCertificate { |
38
|
|
|
subject: Certificate; |
39
|
|
|
issuer: Certificate; |
40
|
|
|
subjectaltname: string; |
41
|
|
|
infoAccess: NodeJS.Dict<string[]>; |
42
|
|
|
modulus: string; |
43
|
|
|
exponent: string; |
44
|
|
|
valid_from: string; |
45
|
|
|
valid_to: string; |
46
|
|
|
fingerprint: string; |
47
|
|
|
fingerprint256: string; |
48
|
|
|
ext_key_usage: string[]; |
49
|
|
|
serialNumber: string; |
50
|
|
|
raw: Buffer; |
51
|
|
|
} |
52
|
|
|
|
53
|
|
|
interface DetailedPeerCertificate extends PeerCertificate { |
54
|
|
|
issuerCertificate: DetailedPeerCertificate; |
55
|
|
|
} |
56
|
|
|
|
57
|
|
|
interface CipherNameAndProtocol { |
58
|
|
|
/** |
59
|
|
|
* The cipher name. |
60
|
|
|
*/ |
61
|
|
|
name: string; |
62
|
|
|
/** |
63
|
|
|
* SSL/TLS protocol version. |
64
|
|
|
*/ |
65
|
|
|
version: string; |
66
|
|
|
|
67
|
|
|
/** |
68
|
|
|
* IETF name for the cipher suite. |
69
|
|
|
*/ |
70
|
|
|
standardName: string; |
71
|
|
|
} |
72
|
|
|
|
73
|
|
|
interface EphemeralKeyInfo { |
74
|
|
|
/** |
75
|
|
|
* The supported types are 'DH' and 'ECDH'. |
76
|
|
|
*/ |
77
|
|
|
type: string; |
78
|
|
|
/** |
79
|
|
|
* The name property is available only when type is 'ECDH'. |
80
|
|
|
*/ |
81
|
|
|
name?: string; |
82
|
|
|
/** |
83
|
|
|
* The size of parameter of an ephemeral key exchange. |
84
|
|
|
*/ |
85
|
|
|
size: number; |
86
|
|
|
} |
87
|
|
|
|
88
|
|
|
interface KeyObject { |
89
|
|
|
/** |
90
|
|
|
* Private keys in PEM format. |
91
|
|
|
*/ |
92
|
|
|
pem: string | Buffer; |
93
|
|
|
/** |
94
|
|
|
* Optional passphrase. |
95
|
|
|
*/ |
96
|
|
|
passphrase?: string; |
97
|
|
|
} |
98
|
|
|
|
99
|
|
|
interface PxfObject { |
100
|
|
|
/** |
101
|
|
|
* PFX or PKCS12 encoded private key and certificate chain. |
102
|
|
|
*/ |
103
|
|
|
buf: string | Buffer; |
104
|
|
|
/** |
105
|
|
|
* Optional passphrase. |
106
|
|
|
*/ |
107
|
|
|
passphrase?: string; |
108
|
|
|
} |
109
|
|
|
|
110
|
|
|
interface TLSSocketOptions extends SecureContextOptions, CommonConnectionOptions { |
111
|
|
|
/** |
112
|
|
|
* If true the TLS socket will be instantiated in server-mode. |
113
|
|
|
* Defaults to false. |
114
|
|
|
*/ |
115
|
|
|
isServer?: boolean; |
116
|
|
|
/** |
117
|
|
|
* An optional net.Server instance. |
118
|
|
|
*/ |
119
|
|
|
server?: net.Server; |
120
|
|
|
|
121
|
|
|
/** |
122
|
|
|
* An optional Buffer instance containing a TLS session. |
123
|
|
|
*/ |
124
|
|
|
session?: Buffer; |
125
|
|
|
/** |
126
|
|
|
* If true, specifies that the OCSP status request extension will be |
127
|
|
|
* added to the client hello and an 'OCSPResponse' event will be |
128
|
|
|
* emitted on the socket before establishing a secure communication |
129
|
|
|
*/ |
130
|
|
|
requestOCSP?: boolean; |
131
|
|
|
} |
132
|
|
|
|
133
|
|
|
class TLSSocket extends net.Socket { |
134
|
|
|
/** |
135
|
|
|
* Construct a new tls.TLSSocket object from an existing TCP socket. |
136
|
|
|
*/ |
137
|
|
|
constructor(socket: net.Socket, options?: TLSSocketOptions); |
138
|
|
|
|
139
|
|
|
/** |
140
|
|
|
* A boolean that is true if the peer certificate was signed by one of the specified CAs, otherwise false. |
141
|
|
|
*/ |
142
|
|
|
authorized: boolean; |
143
|
|
|
/** |
144
|
|
|
* The reason why the peer's certificate has not been verified. |
145
|
|
|
* This property becomes available only when tlsSocket.authorized === false. |
146
|
|
|
*/ |
147
|
|
|
authorizationError: Error; |
148
|
|
|
/** |
149
|
|
|
* Static boolean value, always true. |
150
|
|
|
* May be used to distinguish TLS sockets from regular ones. |
151
|
|
|
*/ |
152
|
|
|
encrypted: boolean; |
153
|
|
|
|
154
|
|
|
/** |
155
|
|
|
* String containing the selected ALPN protocol. |
156
|
|
|
* When ALPN has no selected protocol, tlsSocket.alpnProtocol equals false. |
157
|
|
|
*/ |
158
|
|
|
alpnProtocol?: string; |
159
|
|
|
|
160
|
|
|
/** |
161
|
|
|
* Returns an object representing the local certificate. The returned |
162
|
|
|
* object has some properties corresponding to the fields of the |
163
|
|
|
* certificate. |
164
|
|
|
* |
165
|
|
|
* See tls.TLSSocket.getPeerCertificate() for an example of the |
166
|
|
|
* certificate structure. |
167
|
|
|
* |
168
|
|
|
* If there is no local certificate, an empty object will be returned. |
169
|
|
|
* If the socket has been destroyed, null will be returned. |
170
|
|
|
*/ |
171
|
|
|
getCertificate(): PeerCertificate | object | null; |
172
|
|
|
/** |
173
|
|
|
* Returns an object representing the cipher name and the SSL/TLS protocol version of the current connection. |
174
|
|
|
* @returns Returns an object representing the cipher name |
175
|
|
|
* and the SSL/TLS protocol version of the current connection. |
176
|
|
|
*/ |
177
|
|
|
getCipher(): CipherNameAndProtocol; |
178
|
|
|
/** |
179
|
|
|
* Returns an object representing the type, name, and size of parameter |
180
|
|
|
* of an ephemeral key exchange in Perfect Forward Secrecy on a client |
181
|
|
|
* connection. It returns an empty object when the key exchange is not |
182
|
|
|
* ephemeral. As this is only supported on a client socket; null is |
183
|
|
|
* returned if called on a server socket. The supported types are 'DH' |
184
|
|
|
* and 'ECDH'. The name property is available only when type is 'ECDH'. |
185
|
|
|
* |
186
|
|
|
* For example: { type: 'ECDH', name: 'prime256v1', size: 256 }. |
187
|
|
|
*/ |
188
|
|
|
getEphemeralKeyInfo(): EphemeralKeyInfo | object | null; |
189
|
|
|
/** |
190
|
|
|
* Returns the latest Finished message that has |
191
|
|
|
* been sent to the socket as part of a SSL/TLS handshake, or undefined |
192
|
|
|
* if no Finished message has been sent yet. |
193
|
|
|
* |
194
|
|
|
* As the Finished messages are message digests of the complete |
195
|
|
|
* handshake (with a total of 192 bits for TLS 1.0 and more for SSL |
196
|
|
|
* 3.0), they can be used for external authentication procedures when |
197
|
|
|
* the authentication provided by SSL/TLS is not desired or is not |
198
|
|
|
* enough. |
199
|
|
|
* |
200
|
|
|
* Corresponds to the SSL_get_finished routine in OpenSSL and may be |
201
|
|
|
* used to implement the tls-unique channel binding from RFC 5929. |
202
|
|
|
*/ |
203
|
|
|
getFinished(): Buffer | undefined; |
204
|
|
|
/** |
205
|
|
|
* Returns an object representing the peer's certificate. |
206
|
|
|
* The returned object has some properties corresponding to the field of the certificate. |
207
|
|
|
* If detailed argument is true the full chain with issuer property will be returned, |
208
|
|
|
* if false only the top certificate without issuer property. |
209
|
|
|
* If the peer does not provide a certificate, it returns null or an empty object. |
210
|
|
|
* @param detailed - If true; the full chain with issuer property will be returned. |
211
|
|
|
* @returns An object representing the peer's certificate. |
212
|
|
|
*/ |
213
|
|
|
getPeerCertificate(detailed: true): DetailedPeerCertificate; |
214
|
|
|
getPeerCertificate(detailed?: false): PeerCertificate; |
215
|
|
|
getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate; |
216
|
|
|
/** |
217
|
|
|
* Returns the latest Finished message that is expected or has actually |
218
|
|
|
* been received from the socket as part of a SSL/TLS handshake, or |
219
|
|
|
* undefined if there is no Finished message so far. |
220
|
|
|
* |
221
|
|
|
* As the Finished messages are message digests of the complete |
222
|
|
|
* handshake (with a total of 192 bits for TLS 1.0 and more for SSL |
223
|
|
|
* 3.0), they can be used for external authentication procedures when |
224
|
|
|
* the authentication provided by SSL/TLS is not desired or is not |
225
|
|
|
* enough. |
226
|
|
|
* |
227
|
|
|
* Corresponds to the SSL_get_peer_finished routine in OpenSSL and may |
228
|
|
|
* be used to implement the tls-unique channel binding from RFC 5929. |
229
|
|
|
*/ |
230
|
|
|
getPeerFinished(): Buffer | undefined; |
231
|
|
|
/** |
232
|
|
|
* Returns a string containing the negotiated SSL/TLS protocol version of the current connection. |
233
|
|
|
* The value `'unknown'` will be returned for connected sockets that have not completed the handshaking process. |
234
|
|
|
* The value `null` will be returned for server sockets or disconnected client sockets. |
235
|
|
|
* See https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_version.html for more information. |
236
|
|
|
* @returns negotiated SSL/TLS protocol version of the current connection |
237
|
|
|
*/ |
238
|
|
|
getProtocol(): string | null; |
239
|
|
|
/** |
240
|
|
|
* Could be used to speed up handshake establishment when reconnecting to the server. |
241
|
|
|
* @returns ASN.1 encoded TLS session or undefined if none was negotiated. |
242
|
|
|
*/ |
243
|
|
|
getSession(): Buffer | undefined; |
244
|
|
|
/** |
245
|
|
|
* Returns a list of signature algorithms shared between the server and |
246
|
|
|
* the client in the order of decreasing preference. |
247
|
|
|
*/ |
248
|
|
|
getSharedSigalgs(): string[]; |
249
|
|
|
/** |
250
|
|
|
* NOTE: Works only with client TLS sockets. |
251
|
|
|
* Useful only for debugging, for session reuse provide session option to tls.connect(). |
252
|
|
|
* @returns TLS session ticket or undefined if none was negotiated. |
253
|
|
|
*/ |
254
|
|
|
getTLSTicket(): Buffer | undefined; |
255
|
|
|
/** |
256
|
|
|
* Returns true if the session was reused, false otherwise. |
257
|
|
|
*/ |
258
|
|
|
isSessionReused(): boolean; |
259
|
|
|
/** |
260
|
|
|
* Initiate TLS renegotiation process. |
261
|
|
|
* |
262
|
|
|
* NOTE: Can be used to request peer's certificate after the secure connection has been established. |
263
|
|
|
* ANOTHER NOTE: When running as the server, socket will be destroyed with an error after handshakeTimeout timeout. |
264
|
|
|
* @param options - The options may contain the following fields: rejectUnauthorized, |
265
|
|
|
* requestCert (See tls.createServer() for details). |
266
|
|
|
* @param callback - callback(err) will be executed with null as err, once the renegotiation |
267
|
|
|
* is successfully completed. |
268
|
|
|
* @return `undefined` when socket is destroy, `false` if negotiaion can't be initiated. |
269
|
|
|
*/ |
270
|
|
|
renegotiate(options: { rejectUnauthorized?: boolean, requestCert?: boolean }, callback: (err: Error | null) => void): undefined | boolean; |
271
|
|
|
/** |
272
|
|
|
* Set maximum TLS fragment size (default and maximum value is: 16384, minimum is: 512). |
273
|
|
|
* Smaller fragment size decreases buffering latency on the client: large fragments are buffered by |
274
|
|
|
* the TLS layer until the entire fragment is received and its integrity is verified; |
275
|
|
|
* large fragments can span multiple roundtrips, and their processing can be delayed due to packet |
276
|
|
|
* loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, |
277
|
|
|
* which may decrease overall server throughput. |
278
|
|
|
* @param size - TLS fragment size (default and maximum value is: 16384, minimum is: 512). |
279
|
|
|
* @returns Returns true on success, false otherwise. |
280
|
|
|
*/ |
281
|
|
|
setMaxSendFragment(size: number): boolean; |
282
|
|
|
|
283
|
|
|
/** |
284
|
|
|
* Disables TLS renegotiation for this TLSSocket instance. Once called, |
285
|
|
|
* attempts to renegotiate will trigger an 'error' event on the |
286
|
|
|
* TLSSocket. |
287
|
|
|
*/ |
288
|
|
|
disableRenegotiation(): void; |
289
|
|
|
|
290
|
|
|
/** |
291
|
|
|
* When enabled, TLS packet trace information is written to `stderr`. This can be |
292
|
|
|
* used to debug TLS connection problems. |
293
|
|
|
* |
294
|
|
|
* Note: The format of the output is identical to the output of `openssl s_client |
295
|
|
|
* -trace` or `openssl s_server -trace`. While it is produced by OpenSSL's |
296
|
|
|
* `SSL_trace()` function, the format is undocumented, can change without notice, |
297
|
|
|
* and should not be relied on. |
298
|
|
|
*/ |
299
|
|
|
enableTrace(): void; |
300
|
|
|
|
301
|
|
|
/** |
302
|
|
|
* @param length number of bytes to retrieve from keying material |
303
|
|
|
* @param label an application specific label, typically this will be a value from the |
304
|
|
|
* [IANA Exporter Label Registry](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels). |
305
|
|
|
* @param context optionally provide a context. |
306
|
|
|
*/ |
307
|
|
|
exportKeyingMaterial(length: number, label: string, context: Buffer): Buffer; |
308
|
|
|
|
309
|
|
|
addListener(event: string, listener: (...args: any[]) => void): this; |
310
|
|
|
addListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; |
311
|
|
|
addListener(event: "secureConnect", listener: () => void): this; |
312
|
|
|
addListener(event: "session", listener: (session: Buffer) => void): this; |
313
|
|
|
addListener(event: "keylog", listener: (line: Buffer) => void): this; |
314
|
|
|
|
315
|
|
|
emit(event: string | symbol, ...args: any[]): boolean; |
316
|
|
|
emit(event: "OCSPResponse", response: Buffer): boolean; |
317
|
|
|
emit(event: "secureConnect"): boolean; |
318
|
|
|
emit(event: "session", session: Buffer): boolean; |
319
|
|
|
emit(event: "keylog", line: Buffer): boolean; |
320
|
|
|
|
321
|
|
|
on(event: string, listener: (...args: any[]) => void): this; |
322
|
|
|
on(event: "OCSPResponse", listener: (response: Buffer) => void): this; |
323
|
|
|
on(event: "secureConnect", listener: () => void): this; |
324
|
|
|
on(event: "session", listener: (session: Buffer) => void): this; |
325
|
|
|
on(event: "keylog", listener: (line: Buffer) => void): this; |
326
|
|
|
|
327
|
|
|
once(event: string, listener: (...args: any[]) => void): this; |
328
|
|
|
once(event: "OCSPResponse", listener: (response: Buffer) => void): this; |
329
|
|
|
once(event: "secureConnect", listener: () => void): this; |
330
|
|
|
once(event: "session", listener: (session: Buffer) => void): this; |
331
|
|
|
once(event: "keylog", listener: (line: Buffer) => void): this; |
332
|
|
|
|
333
|
|
|
prependListener(event: string, listener: (...args: any[]) => void): this; |
334
|
|
|
prependListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; |
335
|
|
|
prependListener(event: "secureConnect", listener: () => void): this; |
336
|
|
|
prependListener(event: "session", listener: (session: Buffer) => void): this; |
337
|
|
|
prependListener(event: "keylog", listener: (line: Buffer) => void): this; |
338
|
|
|
|
339
|
|
|
prependOnceListener(event: string, listener: (...args: any[]) => void): this; |
340
|
|
|
prependOnceListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; |
341
|
|
|
prependOnceListener(event: "secureConnect", listener: () => void): this; |
342
|
|
|
prependOnceListener(event: "session", listener: (session: Buffer) => void): this; |
343
|
|
|
prependOnceListener(event: "keylog", listener: (line: Buffer) => void): this; |
344
|
|
|
} |
345
|
|
|
|
346
|
|
|
interface CommonConnectionOptions { |
347
|
|
|
/** |
348
|
|
|
* An optional TLS context object from tls.createSecureContext() |
349
|
|
|
*/ |
350
|
|
|
secureContext?: SecureContext; |
351
|
|
|
|
352
|
|
|
/** |
353
|
|
|
* When enabled, TLS packet trace information is written to `stderr`. This can be |
354
|
|
|
* used to debug TLS connection problems. |
355
|
|
|
* @default false |
356
|
|
|
*/ |
357
|
|
|
enableTrace?: boolean; |
358
|
|
|
/** |
359
|
|
|
* If true the server will request a certificate from clients that |
360
|
|
|
* connect and attempt to verify that certificate. Defaults to |
361
|
|
|
* false. |
362
|
|
|
*/ |
363
|
|
|
requestCert?: boolean; |
364
|
|
|
/** |
365
|
|
|
* An array of strings or a Buffer naming possible ALPN protocols. |
366
|
|
|
* (Protocols should be ordered by their priority.) |
367
|
|
|
*/ |
368
|
|
|
ALPNProtocols?: string[] | Uint8Array[] | Uint8Array; |
369
|
|
|
/** |
370
|
|
|
* SNICallback(servername, cb) <Function> A function that will be |
371
|
|
|
* called if the client supports SNI TLS extension. Two arguments |
372
|
|
|
* will be passed when called: servername and cb. SNICallback should |
373
|
|
|
* invoke cb(null, ctx), where ctx is a SecureContext instance. |
374
|
|
|
* (tls.createSecureContext(...) can be used to get a proper |
375
|
|
|
* SecureContext.) If SNICallback wasn't provided the default callback |
376
|
|
|
* with high-level API will be used (see below). |
377
|
|
|
*/ |
378
|
|
|
SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext) => void) => void; |
379
|
|
|
/** |
380
|
|
|
* If true the server will reject any connection which is not |
381
|
|
|
* authorized with the list of supplied CAs. This option only has an |
382
|
|
|
* effect if requestCert is true. |
383
|
|
|
* @default true |
384
|
|
|
*/ |
385
|
|
|
rejectUnauthorized?: boolean; |
386
|
|
|
} |
387
|
|
|
|
388
|
|
|
interface TlsOptions extends SecureContextOptions, CommonConnectionOptions { |
389
|
|
|
/** |
390
|
|
|
* Abort the connection if the SSL/TLS handshake does not finish in the |
391
|
|
|
* specified number of milliseconds. A 'tlsClientError' is emitted on |
392
|
|
|
* the tls.Server object whenever a handshake times out. Default: |
393
|
|
|
* 120000 (120 seconds). |
394
|
|
|
*/ |
395
|
|
|
handshakeTimeout?: number; |
396
|
|
|
/** |
397
|
|
|
* The number of seconds after which a TLS session created by the |
398
|
|
|
* server will no longer be resumable. See Session Resumption for more |
399
|
|
|
* information. Default: 300. |
400
|
|
|
*/ |
401
|
|
|
sessionTimeout?: number; |
402
|
|
|
/** |
403
|
|
|
* 48-bytes of cryptographically strong pseudo-random data. |
404
|
|
|
*/ |
405
|
|
|
ticketKeys?: Buffer; |
406
|
|
|
|
407
|
|
|
/** |
408
|
|
|
* |
409
|
|
|
* @param socket |
410
|
|
|
* @param identity identity parameter sent from the client. |
411
|
|
|
* @return pre-shared key that must either be |
412
|
|
|
* a buffer or `null` to stop the negotiation process. Returned PSK must be |
413
|
|
|
* compatible with the selected cipher's digest. |
414
|
|
|
* |
415
|
|
|
* When negotiating TLS-PSK (pre-shared keys), this function is called |
416
|
|
|
* with the identity provided by the client. |
417
|
|
|
* If the return value is `null` the negotiation process will stop and an |
418
|
|
|
* "unknown_psk_identity" alert message will be sent to the other party. |
419
|
|
|
* If the server wishes to hide the fact that the PSK identity was not known, |
420
|
|
|
* the callback must provide some random data as `psk` to make the connection |
421
|
|
|
* fail with "decrypt_error" before negotiation is finished. |
422
|
|
|
* PSK ciphers are disabled by default, and using TLS-PSK thus |
423
|
|
|
* requires explicitly specifying a cipher suite with the `ciphers` option. |
424
|
|
|
* More information can be found in the RFC 4279. |
425
|
|
|
*/ |
426
|
|
|
|
427
|
|
|
pskCallback?(socket: TLSSocket, identity: string): DataView | NodeJS.TypedArray | null; |
428
|
|
|
/** |
429
|
|
|
* hint to send to a client to help |
430
|
|
|
* with selecting the identity during TLS-PSK negotiation. Will be ignored |
431
|
|
|
* in TLS 1.3. Upon failing to set pskIdentityHint `tlsClientError` will be |
432
|
|
|
* emitted with `ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED` code. |
433
|
|
|
*/ |
434
|
|
|
pskIdentityHint?: string; |
435
|
|
|
} |
436
|
|
|
|
437
|
|
|
interface PSKCallbackNegotation { |
438
|
|
|
psk: DataView | NodeJS.TypedArray; |
439
|
|
|
identitty: string; |
440
|
|
|
} |
441
|
|
|
|
442
|
|
|
interface ConnectionOptions extends SecureContextOptions, CommonConnectionOptions { |
443
|
|
|
host?: string; |
444
|
|
|
port?: number; |
445
|
|
|
path?: string; // Creates unix socket connection to path. If this option is specified, `host` and `port` are ignored. |
446
|
|
|
socket?: net.Socket; // Establish secure connection on a given socket rather than creating a new socket |
447
|
|
|
checkServerIdentity?: typeof checkServerIdentity; |
448
|
|
|
servername?: string; // SNI TLS Extension |
449
|
|
|
session?: Buffer; |
450
|
|
|
minDHSize?: number; |
451
|
|
|
lookup?: net.LookupFunction; |
452
|
|
|
timeout?: number; |
453
|
|
|
/** |
454
|
|
|
* When negotiating TLS-PSK (pre-shared keys), this function is called |
455
|
|
|
* with optional identity `hint` provided by the server or `null` |
456
|
|
|
* in case of TLS 1.3 where `hint` was removed. |
457
|
|
|
* It will be necessary to provide a custom `tls.checkServerIdentity()` |
458
|
|
|
* for the connection as the default one will try to check hostname/IP |
459
|
|
|
* of the server against the certificate but that's not applicable for PSK |
460
|
|
|
* because there won't be a certificate present. |
461
|
|
|
* More information can be found in the RFC 4279. |
462
|
|
|
* |
463
|
|
|
* @param hint message sent from the server to help client |
464
|
|
|
* decide which identity to use during negotiation. |
465
|
|
|
* Always `null` if TLS 1.3 is used. |
466
|
|
|
* @returns Return `null` to stop the negotiation process. `psk` must be |
467
|
|
|
* compatible with the selected cipher's digest. |
468
|
|
|
* `identity` must use UTF-8 encoding. |
469
|
|
|
*/ |
470
|
|
|
pskCallback?(hint: string | null): PSKCallbackNegotation | null; |
471
|
|
|
} |
472
|
|
|
|
473
|
|
|
class Server extends net.Server { |
474
|
|
|
/** |
475
|
|
|
* The server.addContext() method adds a secure context that will be |
476
|
|
|
* used if the client request's SNI name matches the supplied hostname |
477
|
|
|
* (or wildcard). |
478
|
|
|
*/ |
479
|
|
|
addContext(hostName: string, credentials: SecureContextOptions): void; |
480
|
|
|
/** |
481
|
|
|
* Returns the session ticket keys. |
482
|
|
|
*/ |
483
|
|
|
getTicketKeys(): Buffer; |
484
|
|
|
/** |
485
|
|
|
* |
486
|
|
|
* The server.setSecureContext() method replaces the |
487
|
|
|
* secure context of an existing server. Existing connections to the |
488
|
|
|
* server are not interrupted. |
489
|
|
|
*/ |
490
|
|
|
setSecureContext(details: SecureContextOptions): void; |
491
|
|
|
/** |
492
|
|
|
* The server.setSecureContext() method replaces the secure context of |
493
|
|
|
* an existing server. Existing connections to the server are not |
494
|
|
|
* interrupted. |
495
|
|
|
*/ |
496
|
|
|
setTicketKeys(keys: Buffer): void; |
497
|
|
|
|
498
|
|
|
/** |
499
|
|
|
* events.EventEmitter |
500
|
|
|
* 1. tlsClientError |
501
|
|
|
* 2. newSession |
502
|
|
|
* 3. OCSPRequest |
503
|
|
|
* 4. resumeSession |
504
|
|
|
* 5. secureConnection |
505
|
|
|
* 6. keylog |
506
|
|
|
*/ |
507
|
|
|
addListener(event: string, listener: (...args: any[]) => void): this; |
508
|
|
|
addListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; |
509
|
|
|
addListener(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this; |
510
|
|
|
addListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; |
511
|
|
|
addListener(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this; |
512
|
|
|
addListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; |
513
|
|
|
addListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; |
514
|
|
|
|
515
|
|
|
emit(event: string | symbol, ...args: any[]): boolean; |
516
|
|
|
emit(event: "tlsClientError", err: Error, tlsSocket: TLSSocket): boolean; |
517
|
|
|
emit(event: "newSession", sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void): boolean; |
518
|
|
|
emit(event: "OCSPRequest", certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void): boolean; |
519
|
|
|
emit(event: "resumeSession", sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void): boolean; |
520
|
|
|
emit(event: "secureConnection", tlsSocket: TLSSocket): boolean; |
521
|
|
|
emit(event: "keylog", line: Buffer, tlsSocket: TLSSocket): boolean; |
522
|
|
|
|
523
|
|
|
on(event: string, listener: (...args: any[]) => void): this; |
524
|
|
|
on(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; |
525
|
|
|
on(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this; |
526
|
|
|
on(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; |
527
|
|
|
on(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this; |
528
|
|
|
on(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; |
529
|
|
|
on(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; |
530
|
|
|
|
531
|
|
|
once(event: string, listener: (...args: any[]) => void): this; |
532
|
|
|
once(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; |
533
|
|
|
once(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this; |
534
|
|
|
once(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; |
535
|
|
|
once(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this; |
536
|
|
|
once(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; |
537
|
|
|
once(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; |
538
|
|
|
|
539
|
|
|
prependListener(event: string, listener: (...args: any[]) => void): this; |
540
|
|
|
prependListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; |
541
|
|
|
prependListener(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this; |
542
|
|
|
prependListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; |
543
|
|
|
prependListener(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this; |
544
|
|
|
prependListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; |
545
|
|
|
prependListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; |
546
|
|
|
|
547
|
|
|
prependOnceListener(event: string, listener: (...args: any[]) => void): this; |
548
|
|
|
prependOnceListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; |
549
|
|
|
prependOnceListener(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this; |
550
|
|
|
prependOnceListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; |
551
|
|
|
prependOnceListener(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this; |
552
|
|
|
prependOnceListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; |
553
|
|
|
prependOnceListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; |
554
|
|
|
} |
555
|
|
|
|
556
|
|
|
interface SecurePair { |
557
|
|
|
encrypted: TLSSocket; |
558
|
|
|
cleartext: TLSSocket; |
559
|
|
|
} |
560
|
|
|
|
561
|
|
|
type SecureVersion = 'TLSv1.3' | 'TLSv1.2' | 'TLSv1.1' | 'TLSv1'; |
562
|
|
|
|
563
|
|
|
interface SecureContextOptions { |
564
|
|
|
/** |
565
|
|
|
* Optionally override the trusted CA certificates. Default is to trust |
566
|
|
|
* the well-known CAs curated by Mozilla. Mozilla's CAs are completely |
567
|
|
|
* replaced when CAs are explicitly specified using this option. |
568
|
|
|
*/ |
569
|
|
|
ca?: string | Buffer | Array<string | Buffer>; |
570
|
|
|
/** |
571
|
|
|
* Cert chains in PEM format. One cert chain should be provided per |
572
|
|
|
* private key. Each cert chain should consist of the PEM formatted |
573
|
|
|
* certificate for a provided private key, followed by the PEM |
574
|
|
|
* formatted intermediate certificates (if any), in order, and not |
575
|
|
|
* including the root CA (the root CA must be pre-known to the peer, |
576
|
|
|
* see ca). When providing multiple cert chains, they do not have to |
577
|
|
|
* be in the same order as their private keys in key. If the |
578
|
|
|
* intermediate certificates are not provided, the peer will not be |
579
|
|
|
* able to validate the certificate, and the handshake will fail. |
580
|
|
|
*/ |
581
|
|
|
cert?: string | Buffer | Array<string | Buffer>; |
582
|
|
|
/** |
583
|
|
|
* Colon-separated list of supported signature algorithms. The list |
584
|
|
|
* can contain digest algorithms (SHA256, MD5 etc.), public key |
585
|
|
|
* algorithms (RSA-PSS, ECDSA etc.), combination of both (e.g |
586
|
|
|
* 'RSA+SHA384') or TLS v1.3 scheme names (e.g. rsa_pss_pss_sha512). |
587
|
|
|
*/ |
588
|
|
|
sigalgs?: string; |
589
|
|
|
/** |
590
|
|
|
* Cipher suite specification, replacing the default. For more |
591
|
|
|
* information, see modifying the default cipher suite. Permitted |
592
|
|
|
* ciphers can be obtained via tls.getCiphers(). Cipher names must be |
593
|
|
|
* uppercased in order for OpenSSL to accept them. |
594
|
|
|
*/ |
595
|
|
|
ciphers?: string; |
596
|
|
|
/** |
597
|
|
|
* Name of an OpenSSL engine which can provide the client certificate. |
598
|
|
|
*/ |
599
|
|
|
clientCertEngine?: string; |
600
|
|
|
/** |
601
|
|
|
* PEM formatted CRLs (Certificate Revocation Lists). |
602
|
|
|
*/ |
603
|
|
|
crl?: string | Buffer | Array<string | Buffer>; |
604
|
|
|
/** |
605
|
|
|
* Diffie Hellman parameters, required for Perfect Forward Secrecy. Use |
606
|
|
|
* openssl dhparam to create the parameters. The key length must be |
607
|
|
|
* greater than or equal to 1024 bits or else an error will be thrown. |
608
|
|
|
* Although 1024 bits is permissible, use 2048 bits or larger for |
609
|
|
|
* stronger security. If omitted or invalid, the parameters are |
610
|
|
|
* silently discarded and DHE ciphers will not be available. |
611
|
|
|
*/ |
612
|
|
|
dhparam?: string | Buffer; |
613
|
|
|
/** |
614
|
|
|
* A string describing a named curve or a colon separated list of curve |
615
|
|
|
* NIDs or names, for example P-521:P-384:P-256, to use for ECDH key |
616
|
|
|
* agreement. Set to auto to select the curve automatically. Use |
617
|
|
|
* crypto.getCurves() to obtain a list of available curve names. On |
618
|
|
|
* recent releases, openssl ecparam -list_curves will also display the |
619
|
|
|
* name and description of each available elliptic curve. Default: |
620
|
|
|
* tls.DEFAULT_ECDH_CURVE. |
621
|
|
|
*/ |
622
|
|
|
ecdhCurve?: string; |
623
|
|
|
/** |
624
|
|
|
* Attempt to use the server's cipher suite preferences instead of the |
625
|
|
|
* client's. When true, causes SSL_OP_CIPHER_SERVER_PREFERENCE to be |
626
|
|
|
* set in secureOptions |
627
|
|
|
*/ |
628
|
|
|
honorCipherOrder?: boolean; |
629
|
|
|
/** |
630
|
|
|
* Private keys in PEM format. PEM allows the option of private keys |
631
|
|
|
* being encrypted. Encrypted keys will be decrypted with |
632
|
|
|
* options.passphrase. Multiple keys using different algorithms can be |
633
|
|
|
* provided either as an array of unencrypted key strings or buffers, |
634
|
|
|
* or an array of objects in the form {pem: <string|buffer>[, |
635
|
|
|
* passphrase: <string>]}. The object form can only occur in an array. |
636
|
|
|
* object.passphrase is optional. Encrypted keys will be decrypted with |
637
|
|
|
* object.passphrase if provided, or options.passphrase if it is not. |
638
|
|
|
*/ |
639
|
|
|
key?: string | Buffer | Array<Buffer | KeyObject>; |
640
|
|
|
/** |
641
|
|
|
* Name of an OpenSSL engine to get private key from. Should be used |
642
|
|
|
* together with privateKeyIdentifier. |
643
|
|
|
*/ |
644
|
|
|
privateKeyEngine?: string; |
645
|
|
|
/** |
646
|
|
|
* Identifier of a private key managed by an OpenSSL engine. Should be |
647
|
|
|
* used together with privateKeyEngine. Should not be set together with |
648
|
|
|
* key, because both options define a private key in different ways. |
649
|
|
|
*/ |
650
|
|
|
privateKeyIdentifier?: string; |
651
|
|
|
/** |
652
|
|
|
* Optionally set the maximum TLS version to allow. One |
653
|
|
|
* of `'TLSv1.3'`, `'TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified along with the |
654
|
|
|
* `secureProtocol` option, use one or the other. |
655
|
|
|
* **Default:** `'TLSv1.3'`, unless changed using CLI options. Using |
656
|
|
|
* `--tls-max-v1.2` sets the default to `'TLSv1.2'`. Using `--tls-max-v1.3` sets the default to |
657
|
|
|
* `'TLSv1.3'`. If multiple of the options are provided, the highest maximum is used. |
658
|
|
|
*/ |
659
|
|
|
maxVersion?: SecureVersion; |
660
|
|
|
/** |
661
|
|
|
* Optionally set the minimum TLS version to allow. One |
662
|
|
|
* of `'TLSv1.3'`, `'TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified along with the |
663
|
|
|
* `secureProtocol` option, use one or the other. It is not recommended to use |
664
|
|
|
* less than TLSv1.2, but it may be required for interoperability. |
665
|
|
|
* **Default:** `'TLSv1.2'`, unless changed using CLI options. Using |
666
|
|
|
* `--tls-v1.0` sets the default to `'TLSv1'`. Using `--tls-v1.1` sets the default to |
667
|
|
|
* `'TLSv1.1'`. Using `--tls-min-v1.3` sets the default to |
668
|
|
|
* 'TLSv1.3'. If multiple of the options are provided, the lowest minimum is used. |
669
|
|
|
*/ |
670
|
|
|
minVersion?: SecureVersion; |
671
|
|
|
/** |
672
|
|
|
* Shared passphrase used for a single private key and/or a PFX. |
673
|
|
|
*/ |
674
|
|
|
passphrase?: string; |
675
|
|
|
/** |
676
|
|
|
* PFX or PKCS12 encoded private key and certificate chain. pfx is an |
677
|
|
|
* alternative to providing key and cert individually. PFX is usually |
678
|
|
|
* encrypted, if it is, passphrase will be used to decrypt it. Multiple |
679
|
|
|
* PFX can be provided either as an array of unencrypted PFX buffers, |
680
|
|
|
* or an array of objects in the form {buf: <string|buffer>[, |
681
|
|
|
* passphrase: <string>]}. The object form can only occur in an array. |
682
|
|
|
* object.passphrase is optional. Encrypted PFX will be decrypted with |
683
|
|
|
* object.passphrase if provided, or options.passphrase if it is not. |
684
|
|
|
*/ |
685
|
|
|
pfx?: string | Buffer | Array<string | Buffer | PxfObject>; |
686
|
|
|
/** |
687
|
|
|
* Optionally affect the OpenSSL protocol behavior, which is not |
688
|
|
|
* usually necessary. This should be used carefully if at all! Value is |
689
|
|
|
* a numeric bitmask of the SSL_OP_* options from OpenSSL Options |
690
|
|
|
*/ |
691
|
|
|
secureOptions?: number; // Value is a numeric bitmask of the `SSL_OP_*` options |
692
|
|
|
/** |
693
|
|
|
* Legacy mechanism to select the TLS protocol version to use, it does |
694
|
|
|
* not support independent control of the minimum and maximum version, |
695
|
|
|
* and does not support limiting the protocol to TLSv1.3. Use |
696
|
|
|
* minVersion and maxVersion instead. The possible values are listed as |
697
|
|
|
* SSL_METHODS, use the function names as strings. For example, use |
698
|
|
|
* 'TLSv1_1_method' to force TLS version 1.1, or 'TLS_method' to allow |
699
|
|
|
* any TLS protocol version up to TLSv1.3. It is not recommended to use |
700
|
|
|
* TLS versions less than 1.2, but it may be required for |
701
|
|
|
* interoperability. Default: none, see minVersion. |
702
|
|
|
*/ |
703
|
|
|
secureProtocol?: string; |
704
|
|
|
/** |
705
|
|
|
* Opaque identifier used by servers to ensure session state is not |
706
|
|
|
* shared between applications. Unused by clients. |
707
|
|
|
*/ |
708
|
|
|
sessionIdContext?: string; |
709
|
|
|
} |
710
|
|
|
|
711
|
|
|
interface SecureContext { |
712
|
|
|
context: any; |
713
|
|
|
} |
714
|
|
|
|
715
|
|
|
/* |
716
|
|
|
* Verifies the certificate `cert` is issued to host `host`. |
717
|
|
|
* @host The hostname to verify the certificate against |
718
|
|
|
* @cert PeerCertificate representing the peer's certificate |
719
|
|
|
* |
720
|
|
|
* Returns Error object, populating it with the reason, host and cert on failure. On success, returns undefined. |
721
|
|
|
*/ |
722
|
|
|
function checkServerIdentity(host: string, cert: PeerCertificate): Error | undefined; |
723
|
|
|
function createServer(secureConnectionListener?: (socket: TLSSocket) => void): Server; |
724
|
|
|
function createServer(options: TlsOptions, secureConnectionListener?: (socket: TLSSocket) => void): Server; |
725
|
|
|
function connect(options: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; |
726
|
|
|
function connect(port: number, host?: string, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; |
727
|
|
|
function connect(port: number, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; |
728
|
|
|
/** |
729
|
|
|
* @deprecated |
730
|
|
|
*/ |
731
|
|
|
function createSecurePair(credentials?: SecureContext, isServer?: boolean, requestCert?: boolean, rejectUnauthorized?: boolean): SecurePair; |
732
|
|
|
function createSecureContext(details: SecureContextOptions): SecureContext; |
733
|
|
|
function getCiphers(): string[]; |
734
|
|
|
|
735
|
|
|
/** |
736
|
|
|
* The default curve name to use for ECDH key agreement in a tls server. |
737
|
|
|
* The default value is 'auto'. See tls.createSecureContext() for further |
738
|
|
|
* information. |
739
|
|
|
*/ |
740
|
|
|
let DEFAULT_ECDH_CURVE: string; |
741
|
|
|
/** |
742
|
|
|
* The default value of the maxVersion option of |
743
|
|
|
* tls.createSecureContext(). It can be assigned any of the supported TLS |
744
|
|
|
* protocol versions, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', or 'TLSv1'. Default: |
745
|
|
|
* 'TLSv1.3', unless changed using CLI options. Using --tls-max-v1.2 sets |
746
|
|
|
* the default to 'TLSv1.2'. Using --tls-max-v1.3 sets the default to |
747
|
|
|
* 'TLSv1.3'. If multiple of the options are provided, the highest maximum |
748
|
|
|
* is used. |
749
|
|
|
*/ |
750
|
|
|
let DEFAULT_MAX_VERSION: SecureVersion; |
751
|
|
|
/** |
752
|
|
|
* The default value of the minVersion option of tls.createSecureContext(). |
753
|
|
|
* It can be assigned any of the supported TLS protocol versions, |
754
|
|
|
* 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', or 'TLSv1'. Default: 'TLSv1.2', unless |
755
|
|
|
* changed using CLI options. Using --tls-min-v1.0 sets the default to |
756
|
|
|
* 'TLSv1'. Using --tls-min-v1.1 sets the default to 'TLSv1.1'. Using |
757
|
|
|
* --tls-min-v1.3 sets the default to 'TLSv1.3'. If multiple of the options |
758
|
|
|
* are provided, the lowest minimum is used. |
759
|
|
|
*/ |
760
|
|
|
let DEFAULT_MIN_VERSION: SecureVersion; |
761
|
|
|
|
762
|
|
|
/** |
763
|
|
|
* An immutable array of strings representing the root certificates (in PEM |
764
|
|
|
* format) used for verifying peer certificates. This is the default value |
765
|
|
|
* of the ca option to tls.createSecureContext(). |
766
|
|
|
*/ |
767
|
|
|
const rootCertificates: ReadonlyArray<string>; |
768
|
|
|
} |
769
|
|
|
|