FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: add esm examples to node:tls · nodejs/node@7a8071b · GitHub

/ node Public

Commit 7a8071b

Browse files
mfdebian
authored and
ruyadorno
committed
doc: add esm examples to node:tls
PR-URL: #56229 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
1 parent 481770a commit 7a8071b

1 file changed

Lines changed: 125 additions & 19 deletions

File tree

‎doc/api/tls.md‎

Lines changed: 125 additions & 19 deletions
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

@@ -1783,24 +1801,57 @@ to `host`.
17831801
The following illustrates a client for the echo server example from
17841802
[`tls.createServer()`][]:
17851803

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

17911842
const options = {
17921843
// Necessary only if the server requires client certificate authentication.
1793-
key: fs.readFileSync('client-key.pem'),
1794-
cert: fs.readFileSync('client-cert.pem'),
1844+
key: readFileSync('client-key.pem'),
1845+
cert: readFileSync('client-cert.pem'),
17951846

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

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

1803-
const socket = tls.connect(8000, options, () => {
1854+
const socket = connect(8000, options, () => {
18041855
console.log('client connected',
18051856
socket.authorized ? 'authorized' : 'unauthorized');
18061857
process.stdin.pipe(socket);
@@ -1815,6 +1866,20 @@ socket.on('end', () => {
18151866
});
18161867
```
18171868

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

18201885
<!-- YAML
@@ -2220,22 +2285,22 @@ workers.
22202285

22212286
The following illustrates a simple echo server:
22222287

2223-
```js
2224-
const tls = require('node:tls');
2225-
const fs = require('node:fs');
2288+
```mjs
2289+
import { createServer } from 'node:tls';
2290+
import { readFileSync } from 'node:fs';
22262291

22272292
const options = {
2228-
key: fs.readFileSync('server-key.pem'),
2229-
cert: fs.readFileSync('server-cert.pem'),
2293+
key: readFileSync('server-key.pem'),
2294+
cert: readFileSync('server-cert.pem'),
22302295

22312296
// This is necessary only if using client certificate authentication.
22322297
requestCert: true,
22332298

22342299
// This is necessary only if the client uses a self-signed certificate.
2235-
ca: [ fs.readFileSync('client-cert.pem') ],
2300+
ca: [ readFileSync('client-cert.pem') ],
22362301
};
22372302

2238-
const server = tls.createServer(options, (socket) => {
2303+
const server = createServer(options, (socket) => {
22392304
console.log('server connected',
22402305
socket.authorized ? 'authorized' : 'unauthorized');
22412306
socket.write('welcome!\n');
@@ -2247,6 +2312,47 @@ server.listen(8000, () => {
22472312
});
22482313
```
22492314

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

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL