Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

chore: do not cache ALPN entries in client-certificates (#36553)

Max Schmitt8a2a3429bf8c
diff --git a/packages/playwright-core/src/server/socksClientCertificatesInterceptor.ts b/packages/playwright-core/src/server/socksClientCertificatesInterceptor.ts
index f31a810253..9f06d1e5bd 100644
--- a/packages/playwright-core/src/server/socksClientCertificatesInterceptor.ts
+++ b/packages/playwright-core/src/server/socksClientCertificatesInterceptor.ts
@@ -21,11 +21,11 @@ import stream from 'stream';
import tls from 'tls';
import { SocksProxy } from './utils/socksProxy';
-import { ManualPromise, escapeHTML, generateSelfSignedCertificate, rewriteErrorMessage } from '../utils';
+import { escapeHTML, generateSelfSignedCertificate, rewriteErrorMessage } from '../utils';
import { verifyClientCertificates } from './browserContext';
import { createProxyAgent } from './utils/network';
import { debugLogger } from './utils/debugLogger';
-import { createSocket, createTLSSocket } from './utils/happyEyeballs';
+import { createSocket } from './utils/happyEyeballs';
import { getProxyForUrl } from '../utilsBundle';
import type * as types from './types';
@@ -41,37 +41,55 @@ function loadDummyServerCertsIfNeeded() {
dummyServerTlsOptions = { key, cert };
}
-class ALPNCache {
- private _cache = new Map<string, ManualPromise<string>>();
-
- get(host: string, port: number, success: (protocol: string) => void) {
- const cacheKey = `${host}:${port}`;
- {
- const result = this._cache.get(cacheKey);
- if (result) {
- result.then(success);
- return;
- }
- }
- const result = new ManualPromise<string>();
- this._cache.set(cacheKey, result);
- result.then(success);
- createTLSSocket({
- host,
- port,
- servername: net.isIP(host) ? undefined : host,
- ALPNProtocols: ['h2', 'http/1.1'],
- rejectUnauthorized: false,
- }).then(socket => {
- // The server may not respond with ALPN, in which case we default to http/1.1.
- result.resolve(socket.alpnProtocol || 'http/1.1');
- socket.end();
- }).catch(error => {
- debugLogger.log('client-certificates', `ALPN error: ${error.message}`);
- result.resolve('http/1.1');
- });
- }
-}
+// Client Certificates in Playwright are implemented as a SOCKS5 proxy that injects client certificates into the TLS handshake.
+// We do that to avoid patching the browsers TLS stack and expose the certificates there.
+// The following shows two flow diagrams, one for http:// and one for https://.
+// Key Decision Point: First byte check (0x16 = TLS handshake)
+
+// HTTP FLOW (Plain text):
+// BROWSER PROXY SERVER
+// │ │ │
+// │ SOCKS5 Connect │ │
+// │───────────────────────►│ │
+// │ │ TCP Connect │
+// │ │────────────────────────►│
+// │ │ │
+// │ HTTP Request │ │
+// │───────────────────────►│ │
+// │ │ Check: not 0x16 │
+// │ │ → Direct pipe │
+// │ │ │
+// │ │ HTTP Request │
+// │ │────────────────────────►│
+// │ │ │
+// │◄═══════════════════════│════════════════════════►│
+// │ Plain HTTP │ Plain HTTP │
+
+// HTTPS FLOW (TLS with client certificates):
+// BROWSER PROXY SERVER
+// │ │ │
+// │ SOCKS5 Connect │ │
+// │───────────────────────►│ │
+// │ │ TCP Connect │
+// │ │────────────────────────►│
+// │ │ │
+// │ TLS ClientHello │ │
+// │ (with ALPN) │ │
+// │───────────────────────►│ │
+// │ │ Check: 0x16 = TLS │
+// │ │ Parse ALPN protocols │
+// │ │ Create dual TLS conns │
+// │ │ │
+// │ │ TLS ClientHello │
+// │ │ (with client cert) │
+// │ │────────────────────────►│
+// │ │ │
+// │ │◄───── TLS Handshake ────│
+// │◄──── TLS Handshake ────│ │
+// │ │ │
+// │◄═══════════════════════│════════════════════════►│
+// │ Encrypted Data │ Encrypted Data │
+// │ (HTTP/1.1 or H2) │ (with client auth) │
class SocksProxyConnection {
private readonly socksProxy: ClientCertificatesProxy;
@@ -79,11 +97,10 @@ class SocksProxyConnection {
private readonly host: string;
private readonly port: number;
private _firstPackageReceived = false;
- private _target!: net.Socket;
- private _internal: stream.Duplex;
- private _internalTLS: tls.TLSSocket | undefined;
- private _targetCloseEventListener: () => void;
- private _dummyServer: tls.Server | undefined;
+ private _serverEncrypted!: net.Socket;
+ private _browserEncrypted: stream.Duplex;
+ private _brorwserDecrypted: Promise<tls.TLSSocket> | undefined;
+ private _serverCloseEventListener: () => void;
private _closed = false;
constructor(socksProxy: ClientCertificatesProxy, uid: string, host: string, port: number) {
@@ -91,46 +108,49 @@ class SocksProxyConnection {
this.uid = uid;
this.host = host;
this.port = port;
- this._targetCloseEventListener = () => {
- // Close the other end and cleanup TLS resources.
- this.socksProxy._socksProxy.sendSocketEnd({ uid: this.uid });
- this._internalTLS?.destroy();
- this._dummyServer?.close();
+ this._serverCloseEventListener = () => {
+ this._browserEncrypted.destroy();
};
- this._internal = new stream.Duplex({
+ this._browserEncrypted = new stream.Duplex({
read: () => { },
write: (data, encoding, callback) => {
this.socksProxy._socksProxy.sendSocketData({ uid: this.uid, data });
callback();
- }
+ },
+ destroy: (error, callback) => {
+ if (error)
+ socksProxy._socksProxy.sendSocketError({ uid: this.uid, error: error.message });
+ else
+ socksProxy._socksProxy.sendSocketEnd({ uid: this.uid });
+ callback();
+ },
});
}
async connect() {
const proxyAgent = this.socksProxy.getProxyAgent(this.host, this.port);
if (proxyAgent)
- this._target = await proxyAgent.callback(new EventEmitter() as any, { host: rewriteToLocalhostIfNeeded(this.host), port: this.port, secureEndpoint: false });
+ this._serverEncrypted = await proxyAgent.callback(new EventEmitter() as any, { host: rewriteToLocalhostIfNeeded(this.host), port: this.port, secureEndpoint: false });
else
- this._target = await createSocket(rewriteToLocalhostIfNeeded(this.host), this.port);
+ this._serverEncrypted = await createSocket(rewriteToLocalhostIfNeeded(this.host), this.port);
- this._target.once('close', this._targetCloseEventListener);
- this._target.once('error', error => this.socksProxy._socksProxy.sendSocketError({ uid: this.uid, error: error.message }));
+ this._serverEncrypted.once('close', this._serverCloseEventListener);
+ this._serverEncrypted.once('error', error => this._browserEncrypted.destroy(error));
if (this._closed) {
- this._target.destroy();
+ this._serverEncrypted.destroy();
return;
}
this.socksProxy._socksProxy.socketConnected({
uid: this.uid,
- host: this._target.localAddress!,
- port: this._target.localPort!,
+ host: this._serverEncrypted.localAddress!,
+ port: this._serverEncrypted.localPort!,
});
}
public onClose() {
// Close the other end and cleanup TLS resources.
- this._target.destroy();
- this._internalTLS?.destroy();
- this._dummyServer?.close();
+ this._serverEncrypted.destroy();
+ this._browserEncrypted.destroy();
this._closed = true;
}
@@ -141,104 +161,117 @@ class SocksProxyConnection {
this._firstPackageReceived = true;
// 0x16 is SSLv3/TLS "handshake" content type: https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_record
if (data[0] === 0x16)
- this._establishTlsTunnel(this._internal, data);
+ this._establishTlsTunnel(this._browserEncrypted, data);
else
- this._establishPlaintextTunnel(this._internal);
+ this._establishPlaintextTunnel(this._browserEncrypted);
}
- this._internal.push(data);
+ this._browserEncrypted.push(data);
}
- private _establishPlaintextTunnel(internal: stream.Duplex) {
- internal.pipe(this._target);
- this._target.pipe(internal);
+ private _establishPlaintextTunnel(browserEncrypted: stream.Duplex) {
+ browserEncrypted.pipe(this._serverEncrypted);
+ this._serverEncrypted.pipe(browserEncrypted);
}
- private _establishTlsTunnel(internal: stream, clientHello: Buffer) {
- this.socksProxy.alpnCache.get(rewriteToLocalhostIfNeeded(this.host), this.port, alpnProtocolChosenByServer => {
- debugLogger.log('client-certificates', `Proxy->Target ${this.host}:${this.port} chooses ALPN ${alpnProtocolChosenByServer}`);
+ private _establishTlsTunnel(browserEncrypted: stream.Duplex, clientHello: Buffer) {
+ const browserALPNProtocols = parseALPNFromClientHello(clientHello) || ['http/1.1'];
+ debugLogger.log('client-certificates', `Browser->Proxy ${this.host}:${this.port} offers ALPN ${browserALPNProtocols}`);
+
+ const serverDecrypted = tls.connect({
+ socket: this._serverEncrypted,
+ host: this.host,
+ port: this.port,
+ rejectUnauthorized: !this.socksProxy.ignoreHTTPSErrors,
+ ALPNProtocols: browserALPNProtocols,
+ servername: !net.isIP(this.host) ? this.host : undefined,
+ secureContext: this.socksProxy.secureContextMap.get(new URL(`https://${this.host}:${this.port}`).origin),
+ }, async () => {
+ const browserDecrypted = await this._upgradeToTLSIfNeeded(browserEncrypted, serverDecrypted.alpnProtocol);
+ debugLogger.log('client-certificates', `Proxy->Server ${this.host}:${this.port} chooses ALPN ${browserDecrypted.alpnProtocol}`);
+ browserDecrypted.pipe(serverDecrypted);
+ serverDecrypted.pipe(browserDecrypted);
+
+ const cleanup = (error: Error | undefined) => this._serverEncrypted.destroy(error);
+
+ browserDecrypted.once('error', cleanup);
+ serverDecrypted.once('error', cleanup);
+ browserDecrypted.once('close', cleanup);
+ serverDecrypted.once('close', cleanup);
+
if (this._closed)
- return;
- this._dummyServer = tls.createServer({
- ...dummyServerTlsOptions,
- ALPNProtocols: alpnProtocolChosenByServer === 'h2' ? ['h2', 'http/1.1'] : ['http/1.1'],
- });
- this._dummyServer.emit('connection', this._internal);
- this._dummyServer.once('secureConnection', internalTLS => {
- this._internalTLS = internalTLS;
- debugLogger.log('client-certificates', `Browser->Proxy ${this.host}:${this.port} chooses ALPN ${internalTLS.alpnProtocol}`);
-
- let targetTLS: tls.TLSSocket | undefined = undefined;
-
- const handleError = (error: Error) => {
- debugLogger.log('client-certificates', `error when connecting to target: ${error.message.replaceAll('\n', ' ')}`);
- const responseBody = escapeHTML('Playwright client-certificate error: ' + error.message)
- .replaceAll('\n', ' <br>');
- if (internalTLS?.alpnProtocol === 'h2') {
- // This method is available only in Node.js 20+
- if ('performServerHandshake' in http2) {
- // In case of an 'error' event on the target connection, we still need to perform the http2 handshake on the browser side.
- // This is an async operation, so we need to remove the listener to prevent the socket from being closed too early.
- // This means we call this._targetCloseEventListener manually.
- this._target.removeListener('close', this._targetCloseEventListener);
- // @ts-expect-error
- const session: http2.ServerHttp2Session = http2.performServerHandshake(internalTLS);
- session.on('error', () => {
- this._target.destroy();
- this._targetCloseEventListener();
- });
- session.once('stream', (stream: http2.ServerHttp2Stream) => {
- stream.respond({
- 'content-type': 'text/html',
- [http2.constants.HTTP2_HEADER_STATUS]: 503,
- });
- const cleanup = () => {
- session.close();
- this._target.destroy();
- this._targetCloseEventListener();
- };
- stream.end(responseBody, cleanup);
- stream.once('error', cleanup);
- });
- } else {
- this._target.destroy();
- }
- } else {
- internalTLS.end([
- 'HTTP/1.1 503 Internal Server Error',
- 'Content-Type: text/html; charset=utf-8',
- 'Content-Length: ' + Buffer.byteLength(responseBody),
- '',
- responseBody,
- ].join('\r\n'));
- this._target.destroy();
- }
- };
-
- if (this._closed) {
- internalTLS.destroy();
- return;
+ serverDecrypted.destroy();
+ });
+ serverDecrypted.once('error', async (error: Error) => {
+ debugLogger.log('client-certificates', `error when connecting to server: ${error.message.replaceAll('\n', ' ')}`);
+
+ // Once we receive an error, we manually close the server connection.
+ // In case of an 'error' event on the server connection, we still need to perform the http2 handshake on the browser side.
+ // This is an async operation, so we need to remove the listener to prevent the socket from being closed too early.
+ // This means we call this._serverCloseEventListener manually.
+ this._serverEncrypted.removeListener('close', this._serverCloseEventListener);
+ this._serverEncrypted.destroy();
+
+ const browserDecrypted = await this._upgradeToTLSIfNeeded(this._browserEncrypted, serverDecrypted.alpnProtocol);
+ const responseBody = escapeHTML('Playwright client-certificate error: ' + error.message)
+ .replaceAll('\n', ' <br>');
+ if (browserDecrypted.alpnProtocol === 'h2') {
+ // This method is available only in Node.js 20+
+ if ('performServerHandshake' in http2) {
+ // @ts-expect-error
+ const session: http2.ServerHttp2Session = http2.performServerHandshake(browserDecrypted);
+ session.on('error', error => {
+ this._browserEncrypted.destroy(error);
+ });
+ session.once('stream', (stream: http2.ServerHttp2Stream) => {
+ const cleanup = (error?: Error) => {
+ session.close();
+ this._browserEncrypted.destroy(error);
+ };
+ stream.once('end', cleanup);
+ stream.once('error', cleanup);
+ stream.respond({
+ [http2.constants.HTTP2_HEADER_CONTENT_TYPE]: 'text/html',
+ [http2.constants.HTTP2_HEADER_STATUS]: 503,
+ });
+ stream.end(responseBody);
+ });
+ } else {
+ this._browserEncrypted.destroy(error);
}
- targetTLS = tls.connect({
- socket: this._target,
- host: this.host,
- port: this.port,
- rejectUnauthorized: !this.socksProxy.ignoreHTTPSErrors,
- ALPNProtocols: [internalTLS.alpnProtocol || 'http/1.1'],
- servername: !net.isIP(this.host) ? this.host : undefined,
- secureContext: this.socksProxy.secureContextMap.get(new URL(`https://${this.host}:${this.port}`).origin),
- });
-
- targetTLS.once('secureConnect', () => {
- internalTLS.pipe(targetTLS);
- targetTLS.pipe(internalTLS);
+ } else {
+ browserDecrypted.end([
+ 'HTTP/1.1 503 Internal Server Error',
+ 'Content-Type: text/html; charset=utf-8',
+ 'Content-Length: ' + Buffer.byteLength(responseBody),
+ '',
+ responseBody,
+ ].join('\r\n'), () => {
+ this._browserEncrypted.destroy();
});
+ }
+ });
+ }
- internalTLS.once('error', () => this._target.destroy());
- targetTLS.once('error', handleError);
+ private async _upgradeToTLSIfNeeded(socket: stream.Duplex, alpnProtocol: string | false | null): Promise<tls.TLSSocket> {
+ // TLS errors can happen after secureConnect event from the server. In this case the socket is already upgraded to TLS.
+ this._brorwserDecrypted ??= new Promise<tls.TLSSocket>((resolve, reject) => {
+ const dummyServer = tls.createServer({
+ ...dummyServerTlsOptions,
+ ALPNProtocols: [alpnProtocol || 'http/1.1'],
+ });
+ dummyServer.emit('connection', socket);
+ dummyServer.once('secureConnection', tlsSocket => {
+ dummyServer.close();
+ resolve(tlsSocket);
+ });
+ dummyServer.once('error', error => {
+ dummyServer.close();
+ reject(error);
});
});
+ return this._brorwserDecrypted;
}
}
@@ -247,14 +280,12 @@ export class ClientCertificatesProxy {
private _connections: Map<string, SocksProxyConnection> = new Map();
ignoreHTTPSErrors: boolean | undefined;
secureContextMap: Map<string, tls.SecureContext> = new Map();
- alpnCache: ALPNCache;
private _proxy: types.ProxySettings | undefined;
private constructor(
contextOptions: Pick<types.BrowserContextOptions, 'clientCertificates' | 'ignoreHTTPSErrors' | 'proxy'>
) {
verifyClientCertificates(contextOptions.clientCertificates);
- this.alpnCache = new ALPNCache();
this.ignoreHTTPSErrors = contextOptions.ignoreHTTPSErrors;
this._proxy = contextOptions.proxy;
this._initSecureContexts(contextOptions.clientCertificates);
@@ -383,3 +414,124 @@ export function rewriteOpenSSLErrorIfNeeded(error: Error): Error {
'You could probably modernize the certificate by following the steps at https://github.com/nodejs/node/issues/40672#issuecomment-1243648223',
].join('\n'));
}
+
+
+/**
+ * Parses the ALPN (Application-Layer Protocol Negotiation) extension from a TLS ClientHello.
+ * Based on RFC 8446 (TLS 1.3): https://datatracker.ietf.org/doc/html/rfc8446
+ */
+function parseALPNFromClientHello(buffer: Buffer): string[] | null {
+ if (buffer.length < 6)
+ return null;
+
+ // --- TLS Record Header (RFC 8446 §5.1) ---
+ // https://datatracker.ietf.org/doc/html/rfc8446#section-5.1
+ // TLSPlaintext.type (1 byte): 0x16 = TLS handshake
+ if (buffer[0] !== 0x16)
+ return null;
+
+ let offset = 5; // TLS record header is 5 bytes
+
+ // --- Handshake Header (RFC 8446 §4.1) ---
+ // HandshakeType (1 byte): 0x01 = ClientHello
+ // https://datatracker.ietf.org/doc/html/rfc8446#section-4
+ if (buffer[offset] !== 0x01)
+ return null;
+
+ offset += 4; // Handshake header: type (1) + length (3)
+
+ // --- ClientHello (RFC 8446 §4.1.2) ---
+ // https://datatracker.ietf.org/doc/html/rfc8446#section-4.1.2
+
+ // legacy_version (2 bytes) — always 0x0303 (TLS 1.2 for compatibility)
+ offset += 2;
+ // random (32 bytes)
+ offset += 32;
+
+ // legacy_session_id<0..32> (preceded by 1-byte length)
+ if (offset >= buffer.length)
+ return null;
+ const sessionIdLength = buffer[offset];
+ offset += 1 + sessionIdLength;
+
+ // cipher_suites<2..2^16-2> (preceded by 2-byte length)
+ if (offset + 2 > buffer.length)
+ return null;
+ const cipherSuitesLength = buffer.readUInt16BE(offset);
+ offset += 2 + cipherSuitesLength;
+
+ // legacy_compression_methods<1..2^8-1> (preceded by 1-byte length)
+ if (offset >= buffer.length)
+ return null;
+ const compressionMethodsLength = buffer[offset];
+ offset += 1 + compressionMethodsLength;
+
+ // extensions<8..2^16-1> (preceded by 2-byte length)
+ if (offset + 2 > buffer.length)
+ return null;
+ const extensionsLength = buffer.readUInt16BE(offset);
+ offset += 2;
+
+ const extensionsEnd = offset + extensionsLength;
+ if (extensionsEnd > buffer.length)
+ return null;
+
+ // --- Extensions (RFC 8446 §4.2) ---
+ // https://datatracker.ietf.org/doc/html/rfc8446#section-4.2
+ // Each extension is structured as:
+ // - extension_type (2 bytes)
+ // - extension_data length (2 bytes)
+ // - extension_data (variable)
+ while (offset + 4 <= extensionsEnd) {
+ const extensionType = buffer.readUInt16BE(offset);
+ offset += 2;
+ const extensionLength = buffer.readUInt16BE(offset);
+ offset += 2;
+
+ if (offset + extensionLength > extensionsEnd)
+ return null;
+
+ // ALPN extension (RFC 8446 §4.2.11): extension_type = 16
+ // https://datatracker.ietf.org/doc/html/rfc8446#section-4.2
+ if (extensionType === 16)
+ return parseALPNExtension(buffer.subarray(offset, offset + extensionLength));
+
+ offset += extensionLength;
+ }
+
+ return null; // No ALPN extension found
+}
+
+/**
+ * Parses the ALPN extension data from a ClientHello extension block.
+ *
+ * The ALPN structure is defined in:
+ * - RFC 7301 §3.1: https://datatracker.ietf.org/doc/html/rfc7301#section-3.1
+ */
+function parseALPNExtension(buffer: Buffer): string[] | null {
+ if (buffer.length < 2)
+ return null;
+
+ // protocol_name_list<2..2^16-1> (preceded by 2-byte length)
+ const listLength = buffer.readUInt16BE(0);
+ if (listLength !== buffer.length - 2)
+ return null;
+
+ const protocols: string[] = [];
+ let offset = 2;
+
+ while (offset < buffer.length) {
+ // ProtocolName<1..2^8-1> (preceded by 1-byte length)
+ const protocolLength = buffer[offset];
+ offset += 1;
+
+ if (offset + protocolLength > buffer.length)
+ break;
+
+ const protocol = buffer.subarray(offset, offset + protocolLength).toString('utf8');
+ protocols.push(protocol);
+ offset += protocolLength;
+ }
+
+ return protocols.length > 0 ? protocols : null;
+}