diff options
author | James M Snell <jasnell@gmail.com> | 2020-07-23 22:11:12 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2020-07-27 23:33:14 +0300 |
commit | 1f94b89309bcd56a2883cd1b0eb2db610251095e (patch) | |
tree | f26a6929226f6ff4039c0ea58584821147b26ce4 /doc/api/quic.md | |
parent | 06664298fa07442b5be6dbc891ea999f6c9e7d28 (diff) |
quic: refactor ocsp to use async function rather than event/callback
PR-URL: https://github.com/nodejs/node/pull/34498
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Diffstat (limited to 'doc/api/quic.md')
-rw-r--r-- | doc/api/quic.md | 91 |
1 files changed, 53 insertions, 38 deletions
diff --git a/doc/api/quic.md b/doc/api/quic.md index 64b5f7ff087..9a2d94080cd 100644 --- a/doc/api/quic.md +++ b/doc/api/quic.md @@ -1188,23 +1188,6 @@ added: REPLACEME The `QuicClientSession` class implements the client side of a QUIC connection. Instances are created using the `quicsocket.connect()` method. -#### Event: `'OCSPResponse'` -<!-- YAML -added: REPLACEME ---> - -Emitted when the `QuicClientSession` receives a requested OCSP certificate -status response from the QUIC server peer. - -The callback is invoked with a single argument: - -* `response` {Buffer} - -Node.js does not perform any automatic validation or processing of the -response. - -The `'OCSPResponse'` event will not be emitted more than once. - #### Event: `'sessionTicket'` <!-- YAML added: REPLACEME @@ -1313,24 +1296,6 @@ The callback is invoked with four arguments: The `'clientHello'` event will not be emitted more than once. -#### Event: `'OCSPRequest'` -<!-- YAML -added: REPLACEME ---> - -Emitted when the `QuicServerSession` has received a OCSP certificate status -request as part of the TLS handshake. - -The callback is invoked with three arguments: - -* `servername` {string} -* `context` {tls.SecureContext} -* `callback` {Function} - -The callback *must* be invoked in order for the TLS handshake to continue. - -The `'OCSPRequest'` event will not be emitted more than once. - #### `quicserversession.addContext(servername\[, context\])` <!-- YAML added: REPLACEME @@ -1681,6 +1646,7 @@ added: REPLACEME * `qpackBlockedStreams` {number} * `maxHeaderListSize` {number} * `maxPushes` {number} + * `ocspHandler` {Function} A function for handling [OCSP responses][]. * `passphrase` {string} Shared passphrase used for a single private key and/or a PFX. * `pfx` {string|string[]|Buffer|Buffer[]|Object[]} PFX or PKCS12 encoded @@ -1702,9 +1668,6 @@ added: REPLACEME `QuicClientSession` object. * `qlog` {boolean} Whether to enable ['qlog'][] for this session. Default: `false`. - * `requestOCSP` {boolean} If `true`, specifies that the OCSP status request - extension will be added to the client hello and an `'OCSPResponse'` event - will be emitted before establishing a secure communication. * `secureOptions` {number} Optionally affect the OpenSSL protocol behavior, which is not usually necessary. This should be used carefully if at all! Value is a numeric bitmask of the `SSL_OP_*` options from @@ -1852,6 +1815,7 @@ added: REPLACEME * `maxStreamDataBidiLocal` {number} * `maxStreamDataBidiRemote` {number} * `maxStreamDataUni` {number} + * `ocspHandler` {Function} A function for handling [OCSP requests][]. * `passphrase` {string} Shared passphrase used for a single private key and/or a PFX. * `pfx` {string|string[]|Buffer|Buffer[]|Object[]} PFX or PKCS12 encoded @@ -2466,6 +2430,55 @@ async function myCustomLookup(address, type) { } ``` +### Online Certificate Status Protocol (OCSP) + +The QUIC implementation supports use of OCSP during the TLS 1.3 handshake +of a new QUIC session. + +#### Requests + +A `QuicServerSession` can receive and process OCSP requests by setting the +`ocspHandler` option in the `quicsocket.listen()` function. The value of +the `ocspHandler` is an async function that must return an object with the +OCSP response and, optionally, a new {tls.SecureContext} to use during the +handshake. + +The handler function will be invoked with two arguments: + +* `type`: {string} Will always be `request` for `QuicServerSession`. +* `options`: {Object} + * `servername` {string} The SNI server name. + * `context` {tls.SecureContext} The `SecureContext` currently used. + +```js +async function ocspServerHandler(type, { servername, context }) { + // Process the request... + return { data: Buffer.from('The OCSP response') }; +} + +sock.listen({ ocspHandler: ocspServerHandler }); +``` + +#### Responses + +A `QuicClientSession` can receive and process OCSP responses by setting the +`ocspHandler` option in the `quicsocket.connect()` function. The value of +the `ocspHandler` is an async function with no expected return value. + +The handler function will be invoked with two arguments: + +* `type`: {string} Will always be `response` for `QuicClientSession`. +* `options`: {Object} + * `data`: {Buffer} The OCSP response provided by the server + +```js +async function ocspClientHandler(type, { data }) { + console.log(data.toString()); +} + +sock.connect({ ocspHandler: ocspClientHandler }); +``` + [`crypto.getCurves()`]: crypto.html#crypto_crypto_getcurves [`stream.Readable`]: #stream_class_stream_readable [`tls.DEFAULT_ECDH_CURVE`]: #tls_tls_default_ecdh_curve @@ -2475,6 +2488,8 @@ async function myCustomLookup(address, type) { [Certificate Object]: https://nodejs.org/dist/latest-v12.x/docs/api/tls.html#tls_certificate_object [custom DNS lookup function]: #quic_custom_dns_lookup_functions [modifying the default cipher suite]: tls.html#tls_modifying_the_default_tls_cipher_suite +[OCSP requests]: #quic_online_certificate_status_protocol_ocsp +[OCSP responses]: #quic_online_certificate_status_protocol_ocsp [OpenSSL Options]: crypto.html#crypto_openssl_options [Perfect Forward Secrecy]: #tls_perfect_forward_secrecy [promisified version of `lookup()`]: dns.html#dns_dnspromises_lookup_hostname_options |