1declare 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: { [index: string]: string[] | undefined }; 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 interface EphemeralKeyInfo { 69 /** 70 * The supported types are 'DH' and 'ECDH'. 71 */ 72 type: string; 73 /** 74 * The name property is available only when type is 'ECDH'. 75 */ 76 name?: string; 77 /** 78 * The size of parameter of an ephemeral key exchange. 79 */ 80 size: number; 81 } 82 83 class TLSSocket extends net.Socket { 84 /** 85 * Construct a new tls.TLSSocket object from an existing TCP socket. 86 */ 87 constructor(socket: net.Socket, options?: { 88 /** 89 * An optional TLS context object from tls.createSecureContext() 90 */ 91 secureContext?: SecureContext, 92 /** 93 * If true the TLS socket will be instantiated in server-mode. 94 * Defaults to false. 95 */ 96 isServer?: boolean, 97 /** 98 * An optional net.Server instance. 99 */ 100 server?: net.Server, 101 /** 102 * If true the server will request a certificate from clients that 103 * connect and attempt to verify that certificate. Defaults to 104 * false. 105 */ 106 requestCert?: boolean, 107 /** 108 * If true the server will reject any connection which is not 109 * authorized with the list of supplied CAs. This option only has an 110 * effect if requestCert is true. Defaults to false. 111 */ 112 rejectUnauthorized?: boolean, 113 /** 114 * An array of strings or a Buffer naming possible NPN protocols. 115 * (Protocols should be ordered by their priority.) 116 */ 117 NPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array, 118 /** 119 * An array of strings or a Buffer naming possible ALPN protocols. 120 * (Protocols should be ordered by their priority.) When the server 121 * receives both NPN and ALPN extensions from the client, ALPN takes 122 * precedence over NPN and the server does not send an NPN extension 123 * to the client. 124 */ 125 ALPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array, 126 /** 127 * SNICallback(servername, cb) <Function> A function that will be 128 * called if the client supports SNI TLS extension. Two arguments 129 * will be passed when called: servername and cb. SNICallback should 130 * invoke cb(null, ctx), where ctx is a SecureContext instance. 131 * (tls.createSecureContext(...) can be used to get a proper 132 * SecureContext.) If SNICallback wasn't provided the default callback 133 * with high-level API will be used (see below). 134 */ 135 SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext) => void) => void, 136 /** 137 * An optional Buffer instance containing a TLS session. 138 */ 139 session?: Buffer, 140 /** 141 * If true, specifies that the OCSP status request extension will be 142 * added to the client hello and an 'OCSPResponse' event will be 143 * emitted on the socket before establishing a secure communication 144 */ 145 requestOCSP?: boolean 146 }); 147 148 /** 149 * A boolean that is true if the peer certificate was signed by one of the specified CAs, otherwise false. 150 */ 151 authorized: boolean; 152 /** 153 * The reason why the peer's certificate has not been verified. 154 * This property becomes available only when tlsSocket.authorized === false. 155 */ 156 authorizationError: Error; 157 /** 158 * Static boolean value, always true. 159 * May be used to distinguish TLS sockets from regular ones. 160 */ 161 encrypted: boolean; 162 163 /** 164 * String containing the selected ALPN protocol. 165 * When ALPN has no selected protocol, tlsSocket.alpnProtocol equals false. 166 */ 167 alpnProtocol?: string; 168 169 /** 170 * Returns an object representing the cipher name and the SSL/TLS protocol version of the current connection. 171 * @returns Returns an object representing the cipher name 172 * and the SSL/TLS protocol version of the current connection. 173 */ 174 getCipher(): CipherNameAndProtocol; 175 /** 176 * Returns an object representing the type, name, and size of parameter 177 * of an ephemeral key exchange in Perfect Forward Secrecy on a client 178 * connection. It returns an empty object when the key exchange is not 179 * ephemeral. As this is only supported on a client socket; null is 180 * returned if called on a server socket. The supported types are 'DH' 181 * and 'ECDH'. The name property is available only when type is 'ECDH'. 182 * 183 * For example: { type: 'ECDH', name: 'prime256v1', size: 256 }. 184 */ 185 getEphemeralKeyInfo(): EphemeralKeyInfo | object | null; 186 /** 187 * Returns the latest Finished message that has 188 * been sent to the socket as part of a SSL/TLS handshake, or undefined 189 * if no Finished message has been sent yet. 190 * 191 * As the Finished messages are message digests of the complete 192 * handshake (with a total of 192 bits for TLS 1.0 and more for SSL 193 * 3.0), they can be used for external authentication procedures when 194 * the authentication provided by SSL/TLS is not desired or is not 195 * enough. 196 * 197 * Corresponds to the SSL_get_finished routine in OpenSSL and may be 198 * used to implement the tls-unique channel binding from RFC 5929. 199 */ 200 getFinished(): Buffer | undefined; 201 /** 202 * Returns an object representing the peer's certificate. 203 * The returned object has some properties corresponding to the field of the certificate. 204 * If detailed argument is true the full chain with issuer property will be returned, 205 * if false only the top certificate without issuer property. 206 * If the peer does not provide a certificate, it returns null or an empty object. 207 * @param detailed - If true; the full chain with issuer property will be returned. 208 * @returns An object representing the peer's certificate. 209 */ 210 getPeerCertificate(detailed: true): DetailedPeerCertificate; 211 getPeerCertificate(detailed?: false): PeerCertificate; 212 getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate; 213 /** 214 * Returns the latest Finished message that is expected or has actually 215 * been received from the socket as part of a SSL/TLS handshake, or 216 * undefined if there is no Finished message so far. 217 * 218 * As the Finished messages are message digests of the complete 219 * handshake (with a total of 192 bits for TLS 1.0 and more for SSL 220 * 3.0), they can be used for external authentication procedures when 221 * the authentication provided by SSL/TLS is not desired or is not 222 * enough. 223 * 224 * Corresponds to the SSL_get_peer_finished routine in OpenSSL and may 225 * be used to implement the tls-unique channel binding from RFC 5929. 226 */ 227 getPeerFinished(): Buffer | undefined; 228 /** 229 * Returns a string containing the negotiated SSL/TLS protocol version of the current connection. 230 * The value `'unknown'` will be returned for connected sockets that have not completed the handshaking process. 231 * The value `null` will be returned for server sockets or disconnected client sockets. 232 * See https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_version.html for more information. 233 * @returns negotiated SSL/TLS protocol version of the current connection 234 */ 235 getProtocol(): string | null; 236 /** 237 * Could be used to speed up handshake establishment when reconnecting to the server. 238 * @returns ASN.1 encoded TLS session or undefined if none was negotiated. 239 */ 240 getSession(): any; 241 /** 242 * NOTE: Works only with client TLS sockets. 243 * Useful only for debugging, for session reuse provide session option to tls.connect(). 244 * @returns TLS session ticket or undefined if none was negotiated. 245 */ 246 getTLSTicket(): any; 247 /** 248 * Returns true if the session was reused, false otherwise. 249 */ 250 isSessionReused(): boolean; 251 /** 252 * Initiate TLS renegotiation process. 253 * 254 * NOTE: Can be used to request peer's certificate after the secure connection has been established. 255 * ANOTHER NOTE: When running as the server, socket will be destroyed with an error after handshakeTimeout timeout. 256 * @param options - The options may contain the following fields: rejectUnauthorized, 257 * requestCert (See tls.createServer() for details). 258 * @param callback - callback(err) will be executed with null as err, once the renegotiation 259 * is successfully completed. 260 */ 261 renegotiate(options: { rejectUnauthorized?: boolean, requestCert?: boolean }, callback: (err: Error | null) => void): any; 262 /** 263 * Set maximum TLS fragment size (default and maximum value is: 16384, minimum is: 512). 264 * Smaller fragment size decreases buffering latency on the client: large fragments are buffered by 265 * the TLS layer until the entire fragment is received and its integrity is verified; 266 * large fragments can span multiple roundtrips, and their processing can be delayed due to packet 267 * loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, 268 * which may decrease overall server throughput. 269 * @param size - TLS fragment size (default and maximum value is: 16384, minimum is: 512). 270 * @returns Returns true on success, false otherwise. 271 */ 272 setMaxSendFragment(size: number): boolean; 273 274 /** 275 * Disables TLS renegotiation for this TLSSocket instance. Once called, 276 * attempts to renegotiate will trigger an 'error' event on the 277 * TLSSocket. 278 */ 279 disableRenegotiation(): void; 280 281 /** 282 * events.EventEmitter 283 * 1. OCSPResponse 284 * 2. secureConnect 285 */ 286 addListener(event: string, listener: (...args: any[]) => void): this; 287 addListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; 288 addListener(event: "secureConnect", listener: () => void): this; 289 290 emit(event: string | symbol, ...args: any[]): boolean; 291 emit(event: "OCSPResponse", response: Buffer): boolean; 292 emit(event: "secureConnect"): boolean; 293 294 on(event: string, listener: (...args: any[]) => void): this; 295 on(event: "OCSPResponse", listener: (response: Buffer) => void): this; 296 on(event: "secureConnect", listener: () => void): this; 297 298 once(event: string, listener: (...args: any[]) => void): this; 299 once(event: "OCSPResponse", listener: (response: Buffer) => void): this; 300 once(event: "secureConnect", listener: () => void): this; 301 302 prependListener(event: string, listener: (...args: any[]) => void): this; 303 prependListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; 304 prependListener(event: "secureConnect", listener: () => void): this; 305 306 prependOnceListener(event: string, listener: (...args: any[]) => void): this; 307 prependOnceListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; 308 prependOnceListener(event: "secureConnect", listener: () => void): this; 309 } 310 311 interface TlsOptions extends SecureContextOptions { 312 handshakeTimeout?: number; 313 requestCert?: boolean; 314 rejectUnauthorized?: boolean; 315 NPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array; 316 ALPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array; 317 SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext) => void) => void; 318 sessionTimeout?: number; 319 ticketKeys?: Buffer; 320 } 321 322 interface ConnectionOptions extends SecureContextOptions { 323 host?: string; 324 port?: number; 325 path?: string; // Creates unix socket connection to path. If this option is specified, `host` and `port` are ignored. 326 socket?: net.Socket; // Establish secure connection on a given socket rather than creating a new socket 327 rejectUnauthorized?: boolean; // Defaults to true 328 NPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array; 329 ALPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array; 330 checkServerIdentity?: typeof checkServerIdentity; 331 servername?: string; // SNI TLS Extension 332 session?: Buffer; 333 minDHSize?: number; 334 secureContext?: SecureContext; // If not provided, the entire ConnectionOptions object will be passed to tls.createSecureContext() 335 lookup?: net.LookupFunction; 336 } 337 338 class Server extends net.Server { 339 /** 340 * The server.addContext() method adds a secure context that will be 341 * used if the client request's SNI name matches the supplied hostname 342 * (or wildcard). 343 */ 344 addContext(hostName: string, credentials: { 345 key: string; 346 cert: string; 347 ca: string; 348 }): void; 349 /** 350 * Returns the session ticket keys. 351 */ 352 getTicketKeys(): Buffer; 353 /** 354 * The server.setSecureContext() method replaces the secure context of 355 * an existing server. Existing connections to the server are not 356 * interrupted. 357 */ 358 setTicketKeys(keys: Buffer): void; 359 360 /** 361 * events.EventEmitter 362 * 1. tlsClientError 363 * 2. newSession 364 * 3. OCSPRequest 365 * 4. resumeSession 366 * 5. secureConnection 367 */ 368 addListener(event: string, listener: (...args: any[]) => void): this; 369 addListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; 370 addListener(event: "newSession", listener: (sessionId: any, sessionData: any, callback: (err: Error, resp: Buffer) => void) => void): this; 371 addListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: Function) => void): this; 372 addListener(event: "resumeSession", listener: (sessionId: any, callback: (err: Error, sessionData: any) => void) => void): this; 373 addListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; 374 375 emit(event: string | symbol, ...args: any[]): boolean; 376 emit(event: "tlsClientError", err: Error, tlsSocket: TLSSocket): boolean; 377 emit(event: "newSession", sessionId: any, sessionData: any, callback: (err: Error, resp: Buffer) => void): boolean; 378 emit(event: "OCSPRequest", certificate: Buffer, issuer: Buffer, callback: Function): boolean; 379 emit(event: "resumeSession", sessionId: any, callback: (err: Error, sessionData: any) => void): boolean; 380 emit(event: "secureConnection", tlsSocket: TLSSocket): boolean; 381 382 on(event: string, listener: (...args: any[]) => void): this; 383 on(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; 384 on(event: "newSession", listener: (sessionId: any, sessionData: any, callback: (err: Error, resp: Buffer) => void) => void): this; 385 on(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: Function) => void): this; 386 on(event: "resumeSession", listener: (sessionId: any, callback: (err: Error, sessionData: any) => void) => void): this; 387 on(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; 388 389 once(event: string, listener: (...args: any[]) => void): this; 390 once(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; 391 once(event: "newSession", listener: (sessionId: any, sessionData: any, callback: (err: Error, resp: Buffer) => void) => void): this; 392 once(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: Function) => void): this; 393 once(event: "resumeSession", listener: (sessionId: any, callback: (err: Error, sessionData: any) => void) => void): this; 394 once(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; 395 396 prependListener(event: string, listener: (...args: any[]) => void): this; 397 prependListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; 398 prependListener(event: "newSession", listener: (sessionId: any, sessionData: any, callback: (err: Error, resp: Buffer) => void) => void): this; 399 prependListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: Function) => void): this; 400 prependListener(event: "resumeSession", listener: (sessionId: any, callback: (err: Error, sessionData: any) => void) => void): this; 401 prependListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; 402 403 prependOnceListener(event: string, listener: (...args: any[]) => void): this; 404 prependOnceListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; 405 prependOnceListener(event: "newSession", listener: (sessionId: any, sessionData: any, callback: (err: Error, resp: Buffer) => void) => void): this; 406 prependOnceListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: Function) => void): this; 407 prependOnceListener(event: "resumeSession", listener: (sessionId: any, callback: (err: Error, sessionData: any) => void) => void): this; 408 prependOnceListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; 409 } 410 411 interface SecurePair { 412 encrypted: any; 413 cleartext: any; 414 } 415 416 interface SecureContextOptions { 417 pfx?: string | Buffer | Array<string | Buffer | Object>; 418 key?: string | Buffer | Array<Buffer | Object>; 419 passphrase?: string; 420 cert?: string | Buffer | Array<string | Buffer>; 421 ca?: string | Buffer | Array<string | Buffer>; 422 ciphers?: string; 423 honorCipherOrder?: boolean; 424 ecdhCurve?: string; 425 clientCertEngine?: string; 426 crl?: string | Buffer | Array<string | Buffer>; 427 dhparam?: string | Buffer; 428 secureOptions?: number; // Value is a numeric bitmask of the `SSL_OP_*` options 429 secureProtocol?: string; // SSL Method, e.g. SSLv23_method 430 sessionIdContext?: string; 431 } 432 433 interface SecureContext { 434 context: any; 435 } 436 437 /* 438 * Verifies the certificate `cert` is issued to host `host`. 439 * @host The hostname to verify the certificate against 440 * @cert PeerCertificate representing the peer's certificate 441 * 442 * Returns Error object, populating it with the reason, host and cert on failure. On success, returns undefined. 443 */ 444 function checkServerIdentity(host: string, cert: PeerCertificate): Error | undefined; 445 function createServer(options: TlsOptions, secureConnectionListener?: (socket: TLSSocket) => void): Server; 446 function connect(options: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; 447 function connect(port: number, host?: string, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; 448 function connect(port: number, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; 449 function createSecurePair(credentials?: crypto.Credentials, isServer?: boolean, requestCert?: boolean, rejectUnauthorized?: boolean): SecurePair; 450 function createSecureContext(details: SecureContextOptions): SecureContext; 451 function getCiphers(): string[]; 452 453 /** 454 * The default curve name to use for ECDH key agreement in a tls server. 455 * The default value is 'auto'. See tls.createSecureContext() for further 456 * information. 457 */ 458 let DEFAULT_ECDH_CURVE: string; 459} 460