diff --git a/doc/api/tls.md b/doc/api/tls.md index 2c433fd50d3fec..867681d1d2a626 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -334,6 +334,34 @@ added: v0.3.2 The `tls.Server` class is a subclass of `net.Server` that accepts encrypted connections using TLS or SSL. +### 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 to this server (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 +const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' }); +// ... +server.on('keylog', (line, tlsSocket) => { + if (tlsSocket.remoteAddress !== '...') + return; // Only log keys for a particular IP + logFile.write(line); +}); +``` + ### Event: 'newSession' + +* `line` {Buffer} Line of ASCII text, in NSS `SSLKEYLOGFILE` format. + +The `keylog` event is emitted on a client `tls.TLSSocket` when key material +is generated or received by the socket. This keying material can be stored +for debugging, as it allows captured TLS traffic to be decrypted. It may +be emitted multiple times, before or after the handshake completes. + +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 +const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' }); +// ... +tlsSocket.on('keylog', (line) => logFile.write(line)); +``` + ### Event: 'OCSPResponse'