419 lines
21 KiB
TypeScript
419 lines
21 KiB
TypeScript
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;
|
|
}
|
|
|
|
export interface TLSSocketOptions extends SecureContextOptions, CommonConnectionOptions {
|
|
/**
|
|
* If true the TLS socket will be instantiated in server-mode.
|
|
* Defaults to false.
|
|
*/
|
|
isServer?: boolean;
|
|
/**
|
|
* An optional net.Server instance.
|
|
*/
|
|
server?: net.Server;
|
|
|
|
/**
|
|
* 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;
|
|
}
|
|
|
|
class TLSSocket extends net.Socket {
|
|
/**
|
|
* Construct a new tls.TLSSocket object from an existing TCP socket.
|
|
*/
|
|
constructor(socket: net.Socket, options?: TLSSocketOptions);
|
|
|
|
/**
|
|
* 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;
|
|
|
|
/**
|
|
* When enabled, TLS packet trace information is written to `stderr`. This can be
|
|
* used to debug TLS connection problems.
|
|
*
|
|
* Note: The format of the output is identical to the output of `openssl s_client
|
|
* -trace` or `openssl s_server -trace`. While it is produced by OpenSSL's
|
|
* `SSL_trace()` function, the format is undocumented, can change without notice,
|
|
* and should not be relied on.
|
|
*/
|
|
enableTrace(): void;
|
|
|
|
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;
|
|
addListener(event: "keylog", listener: (line: 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;
|
|
emit(event: "keylog", line: 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;
|
|
on(event: "keylog", listener: (line: 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;
|
|
once(event: "keylog", listener: (line: 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;
|
|
prependListener(event: "keylog", listener: (line: 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;
|
|
prependOnceListener(event: "keylog", listener: (line: Buffer) => void): this;
|
|
}
|
|
|
|
interface CommonConnectionOptions {
|
|
/**
|
|
* An optional TLS context object from tls.createSecureContext()
|
|
*/
|
|
secureContext?: SecureContext;
|
|
|
|
/**
|
|
* When enabled, TLS packet trace information is written to `stderr`. This can be
|
|
* used to debug TLS connection problems.
|
|
* @default false
|
|
*/
|
|
enableTrace?: boolean;
|
|
/**
|
|
* If true the server will request a certificate from clients that
|
|
* connect and attempt to verify that certificate. Defaults to
|
|
* false.
|
|
*/
|
|
requestCert?: boolean;
|
|
/**
|
|
* An array of strings or a Buffer naming possible ALPN protocols.
|
|
* (Protocols should be ordered by their priority.)
|
|
*/
|
|
ALPNProtocols?: string[] | Uint8Array[] | 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;
|
|
/**
|
|
* 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.
|
|
* @default true
|
|
*/
|
|
rejectUnauthorized?: boolean;
|
|
}
|
|
|
|
interface TlsOptions extends SecureContextOptions, CommonConnectionOptions {
|
|
handshakeTimeout?: number;
|
|
sessionTimeout?: number;
|
|
ticketKeys?: Buffer;
|
|
}
|
|
|
|
interface ConnectionOptions extends SecureContextOptions, CommonConnectionOptions {
|
|
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
|
|
checkServerIdentity?: typeof checkServerIdentity;
|
|
servername?: string; // SNI TLS Extension
|
|
session?: Buffer;
|
|
minDHSize?: number;
|
|
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;
|
|
addListener(event: "keylog", listener: (line: Buffer, 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;
|
|
emit(event: "keylog", line: Buffer, 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;
|
|
on(event: "keylog", listener: (line: Buffer, 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;
|
|
once(event: "keylog", listener: (line: Buffer, 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;
|
|
prependListener(event: "keylog", listener: (line: Buffer, 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;
|
|
prependOnceListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this;
|
|
}
|
|
|
|
interface SecurePair {
|
|
encrypted: TLSSocket;
|
|
cleartext: TLSSocket;
|
|
}
|
|
|
|
type SecureVersion = 'TLSv1.3' | '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.3'`, `'TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified along with the
|
|
* `secureProtocol` option, use one or the other.
|
|
* **Default:** `'TLSv1.3'`, unless changed using CLI options. Using
|
|
* `--tls-max-v1.2` sets the default to `'TLSv1.2'`. Using `--tls-max-v1.3` sets the default to
|
|
* `'TLSv1.3'`. If multiple of the options are provided, the highest maximum is used.
|
|
*/
|
|
maxVersion?: SecureVersion;
|
|
/**
|
|
* Optionally set the minimum TLS version to allow. One
|
|
* of `'TLSv1.3'`, `'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` sets the default to `'TLSv1'`. Using `--tls-v1.1` sets the default to
|
|
* `'TLSv1.1'`. Using `--tls-min-v1.3` sets the default to
|
|
* 'TLSv1.3'. If multiple of the options are provided, the lowest minimum is used.
|
|
*/
|
|
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;
|
|
|
|
const rootCertificates: ReadonlyArray<string>;
|
|
}
|