Skip to content

Commit 71c38a2

Browse files
mfdebianaduh95
mfdebian
authored and
aduh95
committed
doc: add esm examples to node:tls
PR-URL: #56229 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>
1 parent f883bed commit 71c38a2

File tree

1 file changed

+125
-19
lines changed

1 file changed

+125
-19
lines changed

‎doc/api/tls.md

+125-19
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,11 @@ The `node:tls` module provides an implementation of the Transport Layer Security
1010
(TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL.
1111
The module can be accessed using:
1212

13-
```js
13+
```mjs
14+
import tls from 'node:tls';
15+
```
16+
17+
```cjs
1418
const tls = require('node:tls');
1519
```
1620

@@ -461,17 +465,31 @@ To adjust the security level in your Node.js application, you can include `@SECL
461465
within a cipher string, where `X` is the desired security level. For example,
462466
to set the security level to 0 while using the default OpenSSL cipher list, you could use:
463467

464-
```js
465-
const tls = require('node:tls');
468+
```mjs
469+
import { createServer, connect } from 'node:tls';
470+
const port = 443;
471+
472+
createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) {
473+
console.log('Client connected with protocol:', socket.getProtocol());
474+
socket.end();
475+
this.close();
476+
})
477+
.listen(port, () => {
478+
connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' });
479+
});
480+
```
481+
482+
```cjs
483+
const { createServer, connect } = require('node:tls');
466484
const port = 443;
467485

468-
tls.createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) {
486+
createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) {
469487
console.log('Client connected with protocol:', socket.getProtocol());
470488
socket.end();
471489
this.close();
472490
})
473491
.listen(port, () => {
474-
tls.connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' });
492+
connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' });
475493
});
476494
```
477495

@@ -1785,24 +1803,57 @@ to `host`.
17851803
The following illustrates a client for the echo server example from
17861804
[`tls.createServer()`][]:
17871805

1788-
```js
1806+
```mjs
17891807
// Assumes an echo server that is listening on port 8000.
1790-
const tls = require('node:tls');
1791-
const fs = require('node:fs');
1808+
import { connect } from 'node:tls';
1809+
import { readFileSync } from 'node:fs';
1810+
import { stdin } from 'node:process';
1811+
1812+
const options = {
1813+
// Necessary only if the server requires client certificate authentication.
1814+
key: readFileSync('client-key.pem'),
1815+
cert: readFileSync('client-cert.pem'),
1816+
1817+
// Necessary only if the server uses a self-signed certificate.
1818+
ca: [ readFileSync('server-cert.pem') ],
1819+
1820+
// Necessary only if the server's cert isn't for "localhost".
1821+
checkServerIdentity: () => { return null; },
1822+
};
1823+
1824+
const socket = connect(8000, options, () => {
1825+
console.log('client connected',
1826+
socket.authorized ? 'authorized' : 'unauthorized');
1827+
stdin.pipe(socket);
1828+
stdin.resume();
1829+
});
1830+
socket.setEncoding('utf8');
1831+
socket.on('data', (data) => {
1832+
console.log(data);
1833+
});
1834+
socket.on('end', () => {
1835+
console.log('server ends connection');
1836+
});
1837+
```
1838+
1839+
```cjs
1840+
// Assumes an echo server that is listening on port 8000.
1841+
const { connect } = require('node:tls');
1842+
const { readFileSync } = require('node:fs');
17921843

17931844
const options = {
17941845
// Necessary only if the server requires client certificate authentication.
1795-
key: fs.readFileSync('client-key.pem'),
1796-
cert: fs.readFileSync('client-cert.pem'),
1846+
key: readFileSync('client-key.pem'),
1847+
cert: readFileSync('client-cert.pem'),
17971848

17981849
// Necessary only if the server uses a self-signed certificate.
1799-
ca: [ fs.readFileSync('server-cert.pem') ],
1850+
ca: [ readFileSync('server-cert.pem') ],
18001851

18011852
// Necessary only if the server's cert isn't for "localhost".
18021853
checkServerIdentity: () => { return null; },
18031854
};
18041855

1805-
const socket = tls.connect(8000, options, () => {
1856+
const socket = connect(8000, options, () => {
18061857
console.log('client connected',
18071858
socket.authorized ? 'authorized' : 'unauthorized');
18081859
process.stdin.pipe(socket);
@@ -1817,6 +1868,20 @@ socket.on('end', () => {
18171868
});
18181869
```
18191870

1871+
To generate the certificate and key for this example, run:
1872+
1873+
```bash
1874+
openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
1875+
-keyout client-key.pem -out client-cert.pem
1876+
```
1877+
1878+
Then, to generate the `server-cert.pem` certificate for this example, run:
1879+
1880+
```bash
1881+
openssl pkcs12 -certpbe AES-256-CBC -export -out server-cert.pem \
1882+
-inkey client-key.pem -in client-cert.pem
1883+
```
1884+
18201885
## `tls.connect(path[, options][, callback])`
18211886

18221887
<!-- YAML
@@ -2228,22 +2293,22 @@ workers.
22282293

22292294
The following illustrates a simple echo server:
22302295

2231-
```js
2232-
const tls = require('node:tls');
2233-
const fs = require('node:fs');
2296+
```mjs
2297+
import { createServer } from 'node:tls';
2298+
import { readFileSync } from 'node:fs';
22342299

22352300
const options = {
2236-
key: fs.readFileSync('server-key.pem'),
2237-
cert: fs.readFileSync('server-cert.pem'),
2301+
key: readFileSync('server-key.pem'),
2302+
cert: readFileSync('server-cert.pem'),
22382303

22392304
// This is necessary only if using client certificate authentication.
22402305
requestCert: true,
22412306

22422307
// This is necessary only if the client uses a self-signed certificate.
2243-
ca: [ fs.readFileSync('client-cert.pem') ],
2308+
ca: [ readFileSync('client-cert.pem') ],
22442309
};
22452310

2246-
const server = tls.createServer(options, (socket) => {
2311+
const server = createServer(options, (socket) => {
22472312
console.log('server connected',
22482313
socket.authorized ? 'authorized' : 'unauthorized');
22492314
socket.write('welcome!\n');
@@ -2255,6 +2320,47 @@ server.listen(8000, () => {
22552320
});
22562321
```
22572322

2323+
```cjs
2324+
const { createServer } = require('node:tls');
2325+
const { readFileSync } = require('node:fs');
2326+
2327+
const options = {
2328+
key: readFileSync('server-key.pem'),
2329+
cert: readFileSync('server-cert.pem'),
2330+
2331+
// This is necessary only if using client certificate authentication.
2332+
requestCert: true,
2333+
2334+
// This is necessary only if the client uses a self-signed certificate.
2335+
ca: [ readFileSync('client-cert.pem') ],
2336+
};
2337+
2338+
const server = createServer(options, (socket) => {
2339+
console.log('server connected',
2340+
socket.authorized ? 'authorized' : 'unauthorized');
2341+
socket.write('welcome!\n');
2342+
socket.setEncoding('utf8');
2343+
socket.pipe(socket);
2344+
});
2345+
server.listen(8000, () => {
2346+
console.log('server bound');
2347+
});
2348+
```
2349+
2350+
To generate the certificate and key for this example, run:
2351+
2352+
```bash
2353+
openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
2354+
-keyout server-key.pem -out server-cert.pem
2355+
```
2356+
2357+
Then, to generate the `client-cert.pem` certificate for this example, run:
2358+
2359+
```bash
2360+
openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \
2361+
-inkey server-key.pem -in server-cert.pem
2362+
```
2363+
22582364
The server can be tested by connecting to it using the example client from
22592365
[`tls.connect()`][].
22602366

0 commit comments

Comments
 (0)