René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"doc: `tls.connect` supports `requestOCSP` option but it is undocumented","articleBody":"### What is the problem?\n\nAccording to the documentation, the `requestOCSP` option is supported by the\n`new tls.TLSSocket()` constructor, but **`tls.connect()` does not list\n`requestOCSP` as a supported option**.\n\nHowever, in practice, `tls.connect()` *does* accept and honor the\n`requestOCSP` option.\n\nThis creates a documentation inconsistency: users relying on `tls.connect()`\ncannot discover that OCSP stapling can be requested, even though it works.\n\n### What is expected?\n\nDocument that `tls.connect()` supports the `requestOCSP` option, and describe its effect, in the same way it is documented for `new tls.TLSSocket()`.\n\n### Affected docs\n\nhttps://nodejs.org/api/tls.html#tlsconnectoptions-callback\n\n---\n\n### Observed behavior\n\nWhen passing `{ requestOCSP: true }` to `tls.connect()`, it causes the client to request\nOCSP stapling during the TLS handshake:\n\n- The server emits an `OCSPRequest` event\n- The client receives an `OCSPResponse` event\n\nWhen `requestOCSP` is `false`, no OCSP request is made and no response\nis received.\n\nThe behavior is reproducible and matches the documented behavior of `new tls.TLSSocket()`.\n\n\u003cdetails\u003e\n\u003csummary\u003eTest code\u003c/summary\u003e\n\n```sh\n# generate server.key\nopenssl genrsa -out server.key 2048\n# generate server.crt\nopenssl req -x509 -new -nodes \\\n  -key server.key \\\n  -sha256 \\\n  -days 1 \\\n  -out server.crt \\\n  -subj \"/CN=ocsp.example.test\" \\\n  -addext \"subjectAltName=DNS:ocsp.example.test\"\n```\n\nAfter that, execute the following typescript in the same directory:\n```ts\nimport * as assert from \"node:assert\";\nimport * as fs from \"node:fs\";\nimport { describe, it } from \"node:test\";\nimport * as tls from \"node:tls\";\n\nconst certPem = fs.readFileSync(\"server.crt\");\nconst keyPem = fs.readFileSync(\"server.key\");\n\nconst domain = \"ocsp.example.test\";\n\ndeclare module \"node:tls\" {\n    interface ConnectionOptions {\n        requestOCSP?: boolean;\n    }\n}\n\nasync function withTlsServer(\n    onListening: (server: tls.Server, port: number) =\u003e Promise\u003cvoid\u003e,\n    options?: tls.TlsOptions,\n) {\n    await using server = tls.createServer({\n        cert: certPem,\n        key: keyPem,\n        minVersion: \"TLSv1.2\",\n        maxVersion: \"TLSv1.2\",\n        ...options,\n    });\n\n    await new Promise\u003cvoid\u003e((resolve, reject) =\u003e {\n        server.once(\"error\", reject);\n        server.listen(0, \"127.0.0.1\", resolve);\n    });\n\n    const address = server.address();\n    assert.ok(address \u0026\u0026 typeof address === \"object\", \"server did not start\");\n\n    server.on(\"secureConnection\", (socket) =\u003e {\n        socket.on(\"OCSPResponse\", () =\u003e {\n            throw new Error(\"Server socket should not receive OCSPResponse events\");\n        });\n    });\n\n    await onListening(server, address.port);\n}\n\nfunction connectWithRequestOCSP(port: number, requestOCSP: boolean) {\n    return new Promise\u003c(Buffer | null)[]\u003e((resolve, reject) =\u003e {\n        const tlsSocket = tls.connect(\n            {\n                port,\n                host: \"127.0.0.1\",\n                servername: domain,\n                minVersion: \"TLSv1.2\",\n                maxVersion: \"TLSv1.2\",\n                rejectUnauthorized: false,\n                requestOCSP,\n            },\n            () =\u003e {\n                tlsSocket.end();\n            },\n        );\n\n        const ocspResponses: Array\u003cBuffer | null\u003e = [];\n        tlsSocket.on(\"OCSPResponse\", response =\u003e ocspResponses.push(response));\n        tlsSocket.once(\"error\", reject);\n        tlsSocket.setTimeout(3_000, () =\u003e tlsSocket.destroy(new Error(\"TLS handshake timeout\")));\n        tlsSocket.once(\"close\", () =\u003e resolve(ocspResponses));\n    });\n}\n\nfunction randomBytes(length: number): Buffer\u003cArrayBuffer\u003e {\n    const buffer = Buffer.alloc(length);\n    crypto.getRandomValues(buffer);\n    return buffer;\n}\nfunction createOcspRequestCounter(server: tls.Server, randomBuffer: Buffer) {\n    let count = 0;\n    server.on(\"OCSPRequest\", (_certificate, _issuer, callback) =\u003e {\n        count += 1;\n        callback(null, randomBuffer);\n    });\n    return () =\u003e count;\n}\n\ndescribe(\"tls OCSP behavior\", () =\u003e {\n    describe(\"connect\", () =\u003e {\n        it(\"requests OCSP stapling when requestOCSP is true\", async () =\u003e\n            await withTlsServer(async (server, port) =\u003e {\n                const randomBuffer = randomBytes(16);\n                const ocspRequestCounter = createOcspRequestCounter(server, randomBuffer);\n                const ocspResponses = await connectWithRequestOCSP(port, true);\n                assert.strictEqual(ocspRequestCounter(), 1);\n                assert.deepEqual(ocspResponses, [randomBuffer]);\n            }));\n\n        it(\"does not request OCSP stapling when requestOCSP is false\", async () =\u003e\n            await withTlsServer(async (server, port) =\u003e {\n                const randomBuffer = randomBytes(16);\n                const ocspRequestCounter = createOcspRequestCounter(server, randomBuffer);\n                const ocspResponses = await connectWithRequestOCSP(port, false);\n                assert.strictEqual(ocspRequestCounter(), 0);\n                assert.deepEqual(ocspResponses, []);\n            }));\n    });\n    describe(\"createServer\", () =\u003e {\n        it(\"requestOCSP option has no effect\", async () =\u003e {\n            for (const requestOCSP of [true, false]) {\n                await withTlsServer(\n                    async (server, port) =\u003e {\n                        const randomBuffer = randomBytes(16);\n                        const ocspRequestCounter = createOcspRequestCounter(server, randomBuffer);\n                        const ocspResponses = await connectWithRequestOCSP(port, true);\n                        assert.strictEqual(ocspRequestCounter(), 1);\n                        assert.deepEqual(ocspResponses, [randomBuffer]);\n                    },\n                    // @ts-expect-error Testing undocumented option\n                    { requestOCSP },\n                );\n            }\n        });\n    });\n});\n```\n\u003c/details\u003e\n","author":{"url":"https://github.com/ikeyan","@type":"Person","name":"ikeyan"},"datePublished":"2025-12-13T06:13:23.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/61042/node/issues/61042"}