diff --git a/doc/api/tls.md b/doc/api/tls.md index 3436ba6697950f..8c52daf294bc1f 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -10,7 +10,11 @@ The `node:tls` module provides an implementation of the Transport Layer Security (TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL. The module can be accessed using: -```js +```mjs +import tls from 'node:tls'; +``` + +```cjs const tls = require('node:tls'); ``` @@ -461,17 +465,31 @@ To adjust the security level in your Node.js application, you can include `@SECL within a cipher string, where `X` is the desired security level. For example, to set the security level to 0 while using the default OpenSSL cipher list, you could use: -```js -const tls = require('node:tls'); +```mjs +import { createServer, connect } from 'node:tls'; +const port = 443; + +createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) { + console.log('Client connected with protocol:', socket.getProtocol()); + socket.end(); + this.close(); +}) +.listen(port, () => { + connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' }); +}); +``` + +```cjs +const { createServer, connect } = require('node:tls'); const port = 443; -tls.createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) { +createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) { console.log('Client connected with protocol:', socket.getProtocol()); socket.end(); this.close(); }) .listen(port, () => { - tls.connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' }); + connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' }); }); ``` @@ -1785,24 +1803,57 @@ to `host`. The following illustrates a client for the echo server example from [`tls.createServer()`][]: -```js +```mjs // Assumes an echo server that is listening on port 8000. -const tls = require('node:tls'); -const fs = require('node:fs'); +import { connect } from 'node:tls'; +import { readFileSync } from 'node:fs'; +import { stdin } from 'node:process'; + +const options = { + // Necessary only if the server requires client certificate authentication. + key: readFileSync('client-key.pem'), + cert: readFileSync('client-cert.pem'), + + // Necessary only if the server uses a self-signed certificate. + ca: [ readFileSync('server-cert.pem') ], + + // Necessary only if the server's cert isn't for "localhost". + checkServerIdentity: () => { return null; }, +}; + +const socket = connect(8000, options, () => { + console.log('client connected', + socket.authorized ? 'authorized' : 'unauthorized'); + stdin.pipe(socket); + stdin.resume(); +}); +socket.setEncoding('utf8'); +socket.on('data', (data) => { + console.log(data); +}); +socket.on('end', () => { + console.log('server ends connection'); +}); +``` + +```cjs +// Assumes an echo server that is listening on port 8000. +const { connect } = require('node:tls'); +const { readFileSync } = require('node:fs'); const options = { // Necessary only if the server requires client certificate authentication. - key: fs.readFileSync('client-key.pem'), - cert: fs.readFileSync('client-cert.pem'), + key: readFileSync('client-key.pem'), + cert: readFileSync('client-cert.pem'), // Necessary only if the server uses a self-signed certificate. - ca: [ fs.readFileSync('server-cert.pem') ], + ca: [ readFileSync('server-cert.pem') ], // Necessary only if the server's cert isn't for "localhost". checkServerIdentity: () => { return null; }, }; -const socket = tls.connect(8000, options, () => { +const socket = connect(8000, options, () => { console.log('client connected', socket.authorized ? 'authorized' : 'unauthorized'); process.stdin.pipe(socket); @@ -1817,6 +1868,20 @@ socket.on('end', () => { }); ``` +To generate the certificate and key for this example, run: + +```bash +openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \ + -keyout client-key.pem -out client-cert.pem +``` + +Then, to generate the `server-cert.pem` certificate for this example, run: + +```bash +openssl pkcs12 -certpbe AES-256-CBC -export -out server-cert.pem \ + -inkey client-key.pem -in client-cert.pem +``` + ## `tls.connect(path[, options][, callback])`