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 |
|
13 |
|
14 | C: string;
|
15 | |
16 |
|
17 |
|
18 | ST: string;
|
19 | |
20 |
|
21 |
|
22 | L: string;
|
23 | |
24 |
|
25 |
|
26 | O: string;
|
27 | |
28 |
|
29 |
|
30 | OU: string;
|
31 | |
32 |
|
33 |
|
34 | CN: string;
|
35 | }
|
36 |
|
37 | interface PeerCertificate {
|
38 | subject: Certificate;
|
39 | issuer: Certificate;
|
40 | subjectaltname: string;
|
41 | infoAccess: { [index: string]: string[] | undefined };
|
42 | modulus: string;
|
43 | exponent: string;
|
44 | valid_from: string;
|
45 | valid_to: string;
|
46 | fingerprint: string;
|
47 | ext_key_usage: string[];
|
48 | serialNumber: string;
|
49 | raw: Buffer;
|
50 | }
|
51 |
|
52 | interface DetailedPeerCertificate extends PeerCertificate {
|
53 | issuerCertificate: DetailedPeerCertificate;
|
54 | }
|
55 |
|
56 | interface CipherNameAndProtocol {
|
57 | |
58 |
|
59 |
|
60 | name: string;
|
61 | |
62 |
|
63 |
|
64 | version: string;
|
65 | }
|
66 |
|
67 | class TLSSocket extends net.Socket {
|
68 | |
69 |
|
70 |
|
71 | constructor(socket: net.Socket, options?: {
|
72 | |
73 |
|
74 |
|
75 | secureContext?: SecureContext,
|
76 | |
77 |
|
78 |
|
79 |
|
80 | isServer?: boolean,
|
81 | |
82 |
|
83 |
|
84 | server?: net.Server,
|
85 | |
86 |
|
87 |
|
88 |
|
89 |
|
90 | requestCert?: boolean,
|
91 | |
92 |
|
93 |
|
94 |
|
95 |
|
96 | rejectUnauthorized?: boolean,
|
97 | |
98 |
|
99 |
|
100 |
|
101 | NPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array,
|
102 | |
103 |
|
104 |
|
105 |
|
106 |
|
107 |
|
108 |
|
109 | ALPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array,
|
110 | |
111 |
|
112 |
|
113 |
|
114 |
|
115 |
|
116 |
|
117 |
|
118 |
|
119 | SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext) => void) => void,
|
120 | |
121 |
|
122 |
|
123 | session?: Buffer,
|
124 | |
125 |
|
126 |
|
127 |
|
128 |
|
129 | requestOCSP?: boolean
|
130 | });
|
131 |
|
132 | /**
|
133 | * A boolean that is true if the peer certificate was signed by one of the specified CAs, otherwise false.
|
134 | */
|
135 | authorized: boolean;
|
136 | /**
|
137 | * The reason why the peer's certificate has not been verified.
|
138 | * This property becomes available only when tlsSocket.authorized === false.
|
139 | */
|
140 | authorizationError: Error;
|
141 | /**
|
142 | * Static boolean value, always true.
|
143 | * May be used to distinguish TLS sockets from regular ones.
|
144 | */
|
145 | encrypted: boolean;
|
146 |
|
147 | /**
|
148 | * String containing the selected ALPN protocol.
|
149 | * When ALPN has no selected protocol, tlsSocket.alpnProtocol equals false.
|
150 | */
|
151 | alpnProtocol?: string;
|
152 |
|
153 | /**
|
154 | * Returns an object representing the cipher name and the SSL/TLS protocol version of the current connection.
|
155 | * @returns Returns an object representing the cipher name
|
156 | * and the SSL/TLS protocol version of the current connection.
|
157 | */
|
158 | getCipher(): CipherNameAndProtocol;
|
159 | /**
|
160 | * Returns an object representing the peer's certificate.
|
161 | * The returned object has some properties corresponding to the field of the certificate.
|
162 | * If detailed argument is true the full chain with issuer property will be returned,
|
163 | * if false only the top certificate without issuer property.
|
164 | * If the peer does not provide a certificate, it returns null or an empty object.
|
165 | * @param detailed - If true; the full chain with issuer property will be returned.
|
166 | * @returns An object representing the peer's certificate.
|
167 | */
|
168 | getPeerCertificate(detailed: true): DetailedPeerCertificate;
|
169 | getPeerCertificate(detailed?: false): PeerCertificate;
|
170 | getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate;
|
171 | /**
|
172 | * Returns a string containing the negotiated SSL/TLS protocol version of the current connection.
|
173 | * The value `'unknown'` will be returned for connected sockets that have not completed the handshaking process.
|
174 | * The value `null` will be returned for server sockets or disconnected client sockets.
|
175 | * See https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_version.html for more information.
|
176 | * @returns negotiated SSL/TLS protocol version of the current connection
|
177 | */
|
178 | getProtocol(): string | null;
|
179 | /**
|
180 | * Could be used to speed up handshake establishment when reconnecting to the server.
|
181 | * @returns ASN.1 encoded TLS session or undefined if none was negotiated.
|
182 | */
|
183 | getSession(): Buffer | undefined;
|
184 | /**
|
185 | * NOTE: Works only with client TLS sockets.
|
186 | * Useful only for debugging, for session reuse provide session option to tls.connect().
|
187 | * @returns TLS session ticket or undefined if none was negotiated.
|
188 | */
|
189 | getTLSTicket(): Buffer | undefined;
|
190 | /**
|
191 | * Initiate TLS renegotiation process.
|
192 | *
|
193 | * NOTE: Can be used to request peer's certificate after the secure connection has been established.
|
194 | * ANOTHER NOTE: When running as the server, socket will be destroyed with an error after handshakeTimeout timeout.
|
195 | * @param options - The options may contain the following fields: rejectUnauthorized,
|
196 | * requestCert (See tls.createServer() for details).
|
197 | * @param callback - callback(err) will be executed with null as err, once the renegotiation
|
198 | * is successfully completed.
|
199 | * @return `undefined` when socket is destroy, `false` if negotiaion can't be initiated.
|
200 | */
|
201 | renegotiate(options: { rejectUnauthorized?: boolean, requestCert?: boolean }, callback: (err: Error | null) => void): undefined | boolean;
|
202 | /**
|
203 | * Set maximum TLS fragment size (default and maximum value is: 16384, minimum is: 512).
|
204 | * Smaller fragment size decreases buffering latency on the client: large fragments are buffered by
|
205 | * the TLS layer until the entire fragment is received and its integrity is verified;
|
206 | * large fragments can span multiple roundtrips, and their processing can be delayed due to packet
|
207 | * loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead,
|
208 | * which may decrease overall server throughput.
|
209 | * @param size - TLS fragment size (default and maximum value is: 16384, minimum is: 512).
|
210 | * @returns Returns true on success, false otherwise.
|
211 | */
|
212 | setMaxSendFragment(size: number): boolean;
|
213 |
|
214 | /**
|
215 | * events.EventEmitter
|
216 | * 1. OCSPResponse
|
217 | * 2. secureConnect
|
218 | */
|
219 | addListener(event: string, listener: (...args: any[]) => void): this;
|
220 | addListener(event: "OCSPResponse", listener: (response: Buffer) => void): this;
|
221 | addListener(event: "secureConnect", listener: () => void): this;
|
222 | addListener(event: "session", listener: (session: Buffer) => void): this;
|
223 |
|
224 | emit(event: string | symbol, ...args: any[]): boolean;
|
225 | emit(event: "OCSPResponse", response: Buffer): boolean;
|
226 | emit(event: "secureConnect"): boolean;
|
227 | emit(event: "session", session: Buffer): boolean;
|
228 |
|
229 | on(event: string, listener: (...args: any[]) => void): this;
|
230 | on(event: "OCSPResponse", listener: (response: Buffer) => void): this;
|
231 | on(event: "secureConnect", listener: () => void): this;
|
232 | on(event: "session", listener: (session: Buffer) => void): this;
|
233 |
|
234 | once(event: string, listener: (...args: any[]) => void): this;
|
235 | once(event: "OCSPResponse", listener: (response: Buffer) => void): this;
|
236 | once(event: "secureConnect", listener: () => void): this;
|
237 | once(event: "session", listener: (session: Buffer) => void): this;
|
238 |
|
239 | prependListener(event: string, listener: (...args: any[]) => void): this;
|
240 | prependListener(event: "OCSPResponse", listener: (response: Buffer) => void): this;
|
241 | prependListener(event: "secureConnect", listener: () => void): this;
|
242 | prependListener(event: "session", listener: (session: Buffer) => void): this;
|
243 |
|
244 | prependOnceListener(event: string, listener: (...args: any[]) => void): this;
|
245 | prependOnceListener(event: "OCSPResponse", listener: (response: Buffer) => void): this;
|
246 | prependOnceListener(event: "secureConnect", listener: () => void): this;
|
247 | prependOnceListener(event: "session", listener: (session: Buffer) => void): this;
|
248 | }
|
249 |
|
250 | interface TlsOptions extends SecureContextOptions {
|
251 | handshakeTimeout?: number;
|
252 | requestCert?: boolean;
|
253 | rejectUnauthorized?: boolean;
|
254 | NPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array;
|
255 | ALPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array;
|
256 | SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext) => void) => void;
|
257 | sessionTimeout?: number;
|
258 | ticketKeys?: Buffer;
|
259 | }
|
260 |
|
261 | interface ConnectionOptions extends SecureContextOptions {
|
262 | host?: string;
|
263 | port?: number;
|
264 | path?: string;
|
265 | socket?: net.Socket;
|
266 | rejectUnauthorized?: boolean;
|
267 | NPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array;
|
268 | ALPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array;
|
269 | checkServerIdentity?: typeof checkServerIdentity;
|
270 | servername?: string;
|
271 | session?: Buffer;
|
272 | minDHSize?: number;
|
273 | secureContext?: SecureContext;
|
274 | lookup?: net.LookupFunction;
|
275 | timeout?: number;
|
276 | }
|
277 |
|
278 | class Server extends net.Server {
|
279 | addContext(hostName: string, credentials: SecureContextOptions): void;
|
280 |
|
281 | |
282 |
|
283 |
|
284 |
|
285 |
|
286 |
|
287 |
|
288 |
|
289 | addListener(event: string, listener: (...args: any[]) => void): this;
|
290 | addListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
|
291 | addListener(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
292 | addListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
293 | addListener(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
294 | addListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
|
295 |
|
296 | emit(event: string | symbol, ...args: any[]): boolean;
|
297 | emit(event: "tlsClientError", err: Error, tlsSocket: TLSSocket): boolean;
|
298 | emit(event: "newSession", sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void): boolean;
|
299 | emit(event: "OCSPRequest", certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void): boolean;
|
300 | emit(event: "resumeSession", sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void): boolean;
|
301 | emit(event: "secureConnection", tlsSocket: TLSSocket): boolean;
|
302 |
|
303 | on(event: string, listener: (...args: any[]) => void): this;
|
304 | on(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
|
305 | on(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
306 | on(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
307 | on(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
308 | on(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
|
309 |
|
310 | once(event: string, listener: (...args: any[]) => void): this;
|
311 | once(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
|
312 | once(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
313 | once(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
314 | once(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
315 | once(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
|
316 |
|
317 | prependListener(event: string, listener: (...args: any[]) => void): this;
|
318 | prependListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
|
319 | prependListener(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
320 | prependListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
321 | prependListener(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
322 | prependListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
|
323 |
|
324 | prependOnceListener(event: string, listener: (...args: any[]) => void): this;
|
325 | prependOnceListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
|
326 | prependOnceListener(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
|
327 | prependOnceListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
|
328 | prependOnceListener(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
|
329 | prependOnceListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
|
330 | }
|
331 |
|
332 | interface SecurePair {
|
333 | encrypted: TLSSocket;
|
334 | cleartext: TLSSocket;
|
335 | }
|
336 |
|
337 | type SecureVersion = 'TLSv1.2' | 'TLSv1.1' | 'TLSv1';
|
338 |
|
339 | interface SecureContextOptions {
|
340 | pfx?: string | Buffer | Array<string | Buffer | Object>;
|
341 | key?: string | Buffer | Array<Buffer | Object>;
|
342 | passphrase?: string;
|
343 | cert?: string | Buffer | Array<string | Buffer>;
|
344 | ca?: string | Buffer | Array<string | Buffer>;
|
345 | ciphers?: string;
|
346 | honorCipherOrder?: boolean;
|
347 | ecdhCurve?: string;
|
348 | clientCertEngine?: string;
|
349 | crl?: string | Buffer | Array<string | Buffer>;
|
350 | dhparam?: string | Buffer;
|
351 | secureOptions?: number;
|
352 | secureProtocol?: string;
|
353 | sessionIdContext?: string;
|
354 | |
355 |
|
356 |
|
357 |
|
358 |
|
359 | maxVersion?: SecureVersion;
|
360 | |
361 |
|
362 |
|
363 |
|
364 |
|
365 |
|
366 |
|
367 |
|
368 |
|
369 | minVersion?: SecureVersion;
|
370 | }
|
371 |
|
372 | interface SecureContext {
|
373 | context: any;
|
374 | }
|
375 |
|
376 | |
377 |
|
378 |
|
379 |
|
380 |
|
381 |
|
382 |
|
383 | function checkServerIdentity(host: string, cert: PeerCertificate): Error | undefined;
|
384 | function createServer(secureConnectionListener?: (socket: TLSSocket) => void): Server;
|
385 | function createServer(options: TlsOptions, secureConnectionListener?: (socket: TLSSocket) => void): Server;
|
386 | function connect(options: ConnectionOptions, secureConnectListener?: () => void): TLSSocket;
|
387 | function connect(port: number, host?: string, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket;
|
388 | function connect(port: number, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket;
|
389 | |
390 |
|
391 |
|
392 | function createSecurePair(credentials?: SecureContext, isServer?: boolean, requestCert?: boolean, rejectUnauthorized?: boolean): SecurePair;
|
393 | function createSecureContext(details: SecureContextOptions): SecureContext;
|
394 | function getCiphers(): string[];
|
395 |
|
396 | const DEFAULT_ECDH_CURVE: string;
|
397 | }
|