123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397 |
- declare module "tls" {
- import * as crypto from "crypto";
- import * as dns from "dns";
- import * as net from "net";
- import * as stream from "stream";
-
- const CLIENT_RENEG_LIMIT: number;
- const CLIENT_RENEG_WINDOW: number;
-
- interface Certificate {
- /**
- * Country code.
- */
- C: string;
- /**
- * Street.
- */
- ST: string;
- /**
- * Locality.
- */
- L: string;
- /**
- * Organization.
- */
- O: string;
- /**
- * Organizational unit.
- */
- OU: string;
- /**
- * Common name.
- */
- CN: string;
- }
-
- interface PeerCertificate {
- subject: Certificate;
- issuer: Certificate;
- subjectaltname: string;
- infoAccess: { [index: string]: string[] | undefined };
- modulus: string;
- exponent: string;
- valid_from: string;
- valid_to: string;
- fingerprint: string;
- ext_key_usage: string[];
- serialNumber: string;
- raw: Buffer;
- }
-
- interface DetailedPeerCertificate extends PeerCertificate {
- issuerCertificate: DetailedPeerCertificate;
- }
-
- interface CipherNameAndProtocol {
- /**
- * The cipher name.
- */
- name: string;
- /**
- * SSL/TLS protocol version.
- */
- version: string;
- }
-
- class TLSSocket extends net.Socket {
- /**
- * Construct a new tls.TLSSocket object from an existing TCP socket.
- */
- constructor(socket: net.Socket, options?: {
- /**
- * An optional TLS context object from tls.createSecureContext()
- */
- secureContext?: SecureContext,
- /**
- * If true the TLS socket will be instantiated in server-mode.
- * Defaults to false.
- */
- isServer?: boolean,
- /**
- * An optional net.Server instance.
- */
- server?: net.Server,
- /**
- * If true the server will request a certificate from clients that
- * connect and attempt to verify that certificate. Defaults to
- * false.
- */
- requestCert?: boolean,
- /**
- * If true the server will reject any connection which is not
- * authorized with the list of supplied CAs. This option only has an
- * effect if requestCert is true. Defaults to false.
- */
- rejectUnauthorized?: boolean,
- /**
- * An array of strings or a Buffer naming possible NPN protocols.
- * (Protocols should be ordered by their priority.)
- */
- NPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array,
- /**
- * An array of strings or a Buffer naming possible ALPN protocols.
- * (Protocols should be ordered by their priority.) When the server
- * receives both NPN and ALPN extensions from the client, ALPN takes
- * precedence over NPN and the server does not send an NPN extension
- * to the client.
- */
- ALPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array,
- /**
- * SNICallback(servername, cb) <Function> A function that will be
- * called if the client supports SNI TLS extension. Two arguments
- * will be passed when called: servername and cb. SNICallback should
- * invoke cb(null, ctx), where ctx is a SecureContext instance.
- * (tls.createSecureContext(...) can be used to get a proper
- * SecureContext.) If SNICallback wasn't provided the default callback
- * with high-level API will be used (see below).
- */
- SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext) => void) => void,
- /**
- * An optional Buffer instance containing a TLS session.
- */
- session?: Buffer,
- /**
- * If true, specifies that the OCSP status request extension will be
- * added to the client hello and an 'OCSPResponse' event will be
- * emitted on the socket before establishing a secure communication
- */
- requestOCSP?: boolean
- });
-
- /**
- * A boolean that is true if the peer certificate was signed by one of the specified CAs, otherwise false.
- */
- authorized: boolean;
- /**
- * The reason why the peer's certificate has not been verified.
- * This property becomes available only when tlsSocket.authorized === false.
- */
- authorizationError: Error;
- /**
- * Static boolean value, always true.
- * May be used to distinguish TLS sockets from regular ones.
- */
- encrypted: boolean;
-
- /**
- * String containing the selected ALPN protocol.
- * When ALPN has no selected protocol, tlsSocket.alpnProtocol equals false.
- */
- alpnProtocol?: string;
-
- /**
- * Returns an object representing the cipher name and the SSL/TLS protocol version of the current connection.
- * @returns Returns an object representing the cipher name
- * and the SSL/TLS protocol version of the current connection.
- */
- getCipher(): CipherNameAndProtocol;
- /**
- * Returns an object representing the peer's certificate.
- * The returned object has some properties corresponding to the field of the certificate.
- * If detailed argument is true the full chain with issuer property will be returned,
- * if false only the top certificate without issuer property.
- * If the peer does not provide a certificate, it returns null or an empty object.
- * @param detailed - If true; the full chain with issuer property will be returned.
- * @returns An object representing the peer's certificate.
- */
- getPeerCertificate(detailed: true): DetailedPeerCertificate;
- getPeerCertificate(detailed?: false): PeerCertificate;
- getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate;
- /**
- * Returns a string containing the negotiated SSL/TLS protocol version of the current connection.
- * The value `'unknown'` will be returned for connected sockets that have not completed the handshaking process.
- * The value `null` will be returned for server sockets or disconnected client sockets.
- * See https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_version.html for more information.
- * @returns negotiated SSL/TLS protocol version of the current connection
- */
- getProtocol(): string | null;
- /**
- * Could be used to speed up handshake establishment when reconnecting to the server.
- * @returns ASN.1 encoded TLS session or undefined if none was negotiated.
- */
- getSession(): Buffer | undefined;
- /**
- * NOTE: Works only with client TLS sockets.
- * Useful only for debugging, for session reuse provide session option to tls.connect().
- * @returns TLS session ticket or undefined if none was negotiated.
- */
- getTLSTicket(): Buffer | undefined;
- /**
- * Initiate TLS renegotiation process.
- *
- * NOTE: Can be used to request peer's certificate after the secure connection has been established.
- * ANOTHER NOTE: When running as the server, socket will be destroyed with an error after handshakeTimeout timeout.
- * @param options - The options may contain the following fields: rejectUnauthorized,
- * requestCert (See tls.createServer() for details).
- * @param callback - callback(err) will be executed with null as err, once the renegotiation
- * is successfully completed.
- * @return `undefined` when socket is destroy, `false` if negotiaion can't be initiated.
- */
- renegotiate(options: { rejectUnauthorized?: boolean, requestCert?: boolean }, callback: (err: Error | null) => void): undefined | boolean;
- /**
- * Set maximum TLS fragment size (default and maximum value is: 16384, minimum is: 512).
- * Smaller fragment size decreases buffering latency on the client: large fragments are buffered by
- * the TLS layer until the entire fragment is received and its integrity is verified;
- * large fragments can span multiple roundtrips, and their processing can be delayed due to packet
- * loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead,
- * which may decrease overall server throughput.
- * @param size - TLS fragment size (default and maximum value is: 16384, minimum is: 512).
- * @returns Returns true on success, false otherwise.
- */
- setMaxSendFragment(size: number): boolean;
-
- /**
- * events.EventEmitter
- * 1. OCSPResponse
- * 2. secureConnect
- */
- addListener(event: string, listener: (...args: any[]) => void): this;
- addListener(event: "OCSPResponse", listener: (response: Buffer) => void): this;
- addListener(event: "secureConnect", listener: () => void): this;
- addListener(event: "session", listener: (session: Buffer) => void): this;
-
- emit(event: string | symbol, ...args: any[]): boolean;
- emit(event: "OCSPResponse", response: Buffer): boolean;
- emit(event: "secureConnect"): boolean;
- emit(event: "session", session: Buffer): boolean;
-
- on(event: string, listener: (...args: any[]) => void): this;
- on(event: "OCSPResponse", listener: (response: Buffer) => void): this;
- on(event: "secureConnect", listener: () => void): this;
- on(event: "session", listener: (session: Buffer) => void): this;
-
- once(event: string, listener: (...args: any[]) => void): this;
- once(event: "OCSPResponse", listener: (response: Buffer) => void): this;
- once(event: "secureConnect", listener: () => void): this;
- once(event: "session", listener: (session: Buffer) => void): this;
-
- prependListener(event: string, listener: (...args: any[]) => void): this;
- prependListener(event: "OCSPResponse", listener: (response: Buffer) => void): this;
- prependListener(event: "secureConnect", listener: () => void): this;
- prependListener(event: "session", listener: (session: Buffer) => void): this;
-
- prependOnceListener(event: string, listener: (...args: any[]) => void): this;
- prependOnceListener(event: "OCSPResponse", listener: (response: Buffer) => void): this;
- prependOnceListener(event: "secureConnect", listener: () => void): this;
- prependOnceListener(event: "session", listener: (session: Buffer) => void): this;
- }
-
- interface TlsOptions extends SecureContextOptions {
- handshakeTimeout?: number;
- requestCert?: boolean;
- rejectUnauthorized?: boolean;
- NPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array;
- ALPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array;
- SNICallback?: (servername: string, cb: (err: Error | null, ctx: SecureContext) => void) => void;
- sessionTimeout?: number;
- ticketKeys?: Buffer;
- }
-
- interface ConnectionOptions extends SecureContextOptions {
- host?: string;
- port?: number;
- path?: string; // Creates unix socket connection to path. If this option is specified, `host` and `port` are ignored.
- socket?: net.Socket; // Establish secure connection on a given socket rather than creating a new socket
- rejectUnauthorized?: boolean; // Defaults to true
- NPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array;
- ALPNProtocols?: string[] | Buffer[] | Uint8Array[] | Buffer | Uint8Array;
- checkServerIdentity?: typeof checkServerIdentity;
- servername?: string; // SNI TLS Extension
- session?: Buffer;
- minDHSize?: number;
- secureContext?: SecureContext; // If not provided, the entire ConnectionOptions object will be passed to tls.createSecureContext()
- lookup?: net.LookupFunction;
- timeout?: number;
- }
-
- class Server extends net.Server {
- addContext(hostName: string, credentials: SecureContextOptions): void;
-
- /**
- * events.EventEmitter
- * 1. tlsClientError
- * 2. newSession
- * 3. OCSPRequest
- * 4. resumeSession
- * 5. secureConnection
- */
- addListener(event: string, listener: (...args: any[]) => void): this;
- addListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
- addListener(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
- addListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
- addListener(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
- addListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
-
- emit(event: string | symbol, ...args: any[]): boolean;
- emit(event: "tlsClientError", err: Error, tlsSocket: TLSSocket): boolean;
- emit(event: "newSession", sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void): boolean;
- emit(event: "OCSPRequest", certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void): boolean;
- emit(event: "resumeSession", sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void): boolean;
- emit(event: "secureConnection", tlsSocket: TLSSocket): boolean;
-
- on(event: string, listener: (...args: any[]) => void): this;
- on(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
- on(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
- on(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
- on(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
- on(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
-
- once(event: string, listener: (...args: any[]) => void): this;
- once(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
- once(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
- once(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
- once(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
- once(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
-
- prependListener(event: string, listener: (...args: any[]) => void): this;
- prependListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
- prependListener(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
- prependListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
- prependListener(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
- prependListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
-
- prependOnceListener(event: string, listener: (...args: any[]) => void): this;
- prependOnceListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this;
- prependOnceListener(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void): this;
- prependOnceListener(event: "OCSPRequest", listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this;
- prependOnceListener(event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void): this;
- prependOnceListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this;
- }
-
- interface SecurePair {
- encrypted: TLSSocket;
- cleartext: TLSSocket;
- }
-
- type SecureVersion = 'TLSv1.2' | 'TLSv1.1' | 'TLSv1';
-
- interface SecureContextOptions {
- pfx?: string | Buffer | Array<string | Buffer | Object>;
- key?: string | Buffer | Array<Buffer | Object>;
- passphrase?: string;
- cert?: string | Buffer | Array<string | Buffer>;
- ca?: string | Buffer | Array<string | Buffer>;
- ciphers?: string;
- honorCipherOrder?: boolean;
- ecdhCurve?: string;
- clientCertEngine?: string;
- crl?: string | Buffer | Array<string | Buffer>;
- dhparam?: string | Buffer;
- secureOptions?: number; // Value is a numeric bitmask of the `SSL_OP_*` options
- secureProtocol?: string; // SSL Method, e.g. SSLv23_method
- sessionIdContext?: string;
- /**
- * Optionally set the maximum TLS version to allow. One
- * of `TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified along with the
- * `secureProtocol` option, use one or the other. **Default:** `'TLSv1.2'`.
- */
- maxVersion?: SecureVersion;
- /**
- * Optionally set the minimum TLS version to allow. One
- * of `TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified along with the
- * `secureProtocol` option, use one or the other. It is not recommended to use
- * less than TLSv1.2, but it may be required for interoperability.
- * **Default:** `'TLSv1.2'`, unless changed using CLI options. Using
- * `--tls-v1.0` changes the default to `'TLSv1'`. Using `--tls-v1.1` changes
- * the default to `'TLSv1.1'`.
- */
- minVersion?: SecureVersion;
- }
-
- interface SecureContext {
- context: any;
- }
-
- /*
- * Verifies the certificate `cert` is issued to host `host`.
- * @host The hostname to verify the certificate against
- * @cert PeerCertificate representing the peer's certificate
- *
- * Returns Error object, populating it with the reason, host and cert on failure. On success, returns undefined.
- */
- function checkServerIdentity(host: string, cert: PeerCertificate): Error | undefined;
- function createServer(secureConnectionListener?: (socket: TLSSocket) => void): Server;
- function createServer(options: TlsOptions, secureConnectionListener?: (socket: TLSSocket) => void): Server;
- function connect(options: ConnectionOptions, secureConnectListener?: () => void): TLSSocket;
- function connect(port: number, host?: string, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket;
- function connect(port: number, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket;
- /**
- * @deprecated
- */
- function createSecurePair(credentials?: SecureContext, isServer?: boolean, requestCert?: boolean, rejectUnauthorized?: boolean): SecurePair;
- function createSecureContext(details: SecureContextOptions): SecureContext;
- function getCiphers(): string[];
-
- const DEFAULT_ECDH_CURVE: string;
- }
|