diff --git a/doc/api/https.md b/doc/api/https.md index e82ffa2225d934..a7ed44288fd3f3 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -45,6 +45,31 @@ changes: See [`Session Resumption`][] for information about TLS session reuse. +#### Event: `'keylog'` + + +* `line` {Buffer} Line of ASCII text, in NSS `SSLKEYLOGFILE` format. +* `tlsSocket` {tls.TLSSocket} The `tls.TLSSocket` instance on which it was + generated. + +The `keylog` event is emitted when key material is generated or received by a +connection managed by this agent (typically before handshake has completed, but +not necessarily). This keying material can be stored for debugging, as it +allows captured TLS traffic to be decrypted. It may be emitted multiple times +for each socket. + +A typical use case is to append received lines to a common text file, which is +later used by software (such as Wireshark) to decrypt the traffic: + +```js +// ... +https.globalAgent.on('keylog', (line, tlsSocket) => { + fs.appendFileSync('/tmp/ssl-keys.log', line, { mode: 0o600 }); +}); +``` + ## Class: `https.Server`