Home Original page

doc: add esm examples to node:tls · nodejs/node@71c38a2

@@ -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:

121213-

```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:

463467464-

```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;

467485468-

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()`][]:

178718051788-

```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');

1792184317931844

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'),

1797184817981849

// Necessary only if the server uses a self-signed certificate.

1799-

ca: [ fs.readFileSync('server-cert.pem') ],

1850+

ca: [ readFileSync('server-cert.pem') ],

1800185118011852

// Necessary only if the server's cert isn't for "localhost".

18021853

checkServerIdentity: () => { return null; },

18031854

};

180418551805-

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

```

181918701871+

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])`

1821188618221887

<!-- YAML

@@ -2228,22 +2293,22 @@ workers.

2228229322292294

The following illustrates a simple echo server:

223022952231-

```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';

2234229922352300

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'),

2238230322392304

// This is necessary only if using client certificate authentication.

22402305

requestCert: true,

2241230622422307

// 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

};

224523102246-

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

```

225723222323+

```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