Skip to content

Commit

Permalink
doc: add esm examples to node:tls
Browse files Browse the repository at this point in the history
PR-URL: #56229
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
  • Loading branch information
mfdebian authored and ruyadorno committed Dec 21, 2024
1 parent 3742b75 commit eafbb9f
Showing 1 changed file with 125 additions and 19 deletions.
144 changes: 125 additions & 19 deletions doc/api/tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -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');
```

Expand Down Expand Up @@ -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' });
});
```

Expand Down Expand Up @@ -1783,24 +1801,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);
Expand All @@ -1815,6 +1866,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])`

<!-- YAML
Expand Down Expand Up @@ -2220,22 +2285,22 @@ workers.

The following illustrates a simple echo server:

```js
const tls = require('node:tls');
const fs = require('node:fs');
```mjs
import { createServer } from 'node:tls';
import { readFileSync } from 'node:fs';

const options = {
key: fs.readFileSync('server-key.pem'),
cert: fs.readFileSync('server-cert.pem'),
key: readFileSync('server-key.pem'),
cert: readFileSync('server-cert.pem'),

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

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

const server = tls.createServer(options, (socket) => {
const server = createServer(options, (socket) => {
console.log('server connected',
socket.authorized ? 'authorized' : 'unauthorized');
socket.write('welcome!\n');
Expand All @@ -2247,6 +2312,47 @@ server.listen(8000, () => {
});
```

```cjs
const { createServer } = require('node:tls');
const { readFileSync } = require('node:fs');

const options = {
key: readFileSync('server-key.pem'),
cert: readFileSync('server-cert.pem'),

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

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

const server = createServer(options, (socket) => {
console.log('server connected',
socket.authorized ? 'authorized' : 'unauthorized');
socket.write('welcome!\n');
socket.setEncoding('utf8');
socket.pipe(socket);
});
server.listen(8000, () => {
console.log('server bound');
});
```

To generate the certificate and key for this example, run:

```bash
openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
-keyout server-key.pem -out server-cert.pem
```

Then, to generate the `client-cert.pem` certificate for this example, run:

```bash
openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \
-inkey server-key.pem -in server-cert.pem
```

The server can be tested by connecting to it using the example client from
[`tls.connect()`][].

Expand Down

0 comments on commit eafbb9f

Please sign in to comment.