Определение того, что поддержка crypto недоступна

Node.js может быть собран без поддержки модуля node:crypto. В таких случаях попытка import из tls или вызов require('node:tls') приведёт к выбрасыванию ошибки.

При использовании CommonJS выброшенную ошибку можно перехватить с помощью try/catch:

let tls;
try {
  tls = require('node:tls');
} catch (err) {
  console.error('tls support is disabled!');
} copy

При использовании лексического ключевого слова ESM import ошибку можно перехватить, только если обработчик для process.on('uncaughtException') зарегистрирован до любой попытки загрузить модуль (например, с помощью модуля предварительной загрузки).

При использовании ESM, если код может выполняться в сборке Node.js, в которой поддержка crypto не включена, рассмотрите возможность использования функции import() вместо лексического ключевого слова import:

let tls;
try {
  tls = await import('node:tls');
} catch (err) {
  console.error('tls support is disabled!');
} copy

Понятия TLS/SSL

TLS/SSL — это набор протоколов, использующих инфраструктуру открытых ключей (PKI) для обеспечения безопасной связи между клиентом и сервером. В большинстве распространённых случаев у каждого сервера должен быть закрытый ключ.

Закрытые ключи можно генерировать разными способами. В примере ниже показано, как с помощью интерфейса командной строки OpenSSL сгенерировать закрытый ключ RSA длиной 2048 бит:

openssl genrsa -out ryans-key.pem 2048 copy

Для работы с TLS/SSL все серверы (и некоторые клиенты) должны иметь сертификат. Сертификаты — это открытые ключи, соответствующие закрытому ключу и имеющие цифровую подпись центра сертификации либо владельца закрытого ключа (такие сертификаты называют «самоподписанными»). Первый шаг к получению сертификата — создание файла запроса на подпись сертификата (CSR).

Для генерации CSR для закрытого ключа можно использовать интерфейс командной строки OpenSSL:

openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem copy

После создания файла CSR его можно отправить в центр сертификации для подписания или использовать для создания самоподписанного сертификата.

В примере ниже показано, как создать самоподписанный сертификат с помощью интерфейса командной строки OpenSSL:

openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem copy

После создания сертификата его можно использовать для создания файла .pfx или .p12:

openssl pkcs12 -export -in ryans-cert.pem -inkey ryans-key.pem \
      -certfile ca-cert.pem -out ryans.pfx copy

Где:

• in: подписанный сертификат
• inkey: соответствующий закрытый ключ
• certfile: объединение сертификатов всех центров сертификации (CA) в один файл, например cat ca1-cert.pem ca2-cert.pem > ca-cert.pem

openssl s_client -connect localhost:443 -reconnect copy

New, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256 copy

Reused, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256 copy

Изменение набора шифров TLS по умолчанию

Node.js поставляется с набором включённых и отключённых шифров TLS по умолчанию. Этот список шифров по умолчанию можно настроить при сборке Node.js, чтобы дистрибутивы могли использовать собственный список по умолчанию.

Чтобы просмотреть набор шифров по умолчанию, можно использовать следующую команду:

node -p crypto.constants.defaultCoreCipherList | tr ':' '\n'
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-GCM-SHA384
DHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256
DHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-SHA384
DHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA256
DHE-RSA-AES256-SHA256
HIGH
!aNULL
!eNULL
!EXPORT
!DES
!RC4
!MD5
!PSK
!SRP
!CAMELLIA copy

Этот набор можно полностью заменить с помощью переключателя командной строки --tls-cipher-list (напрямую или через переменную среды NODE_OPTIONS). Например, следующая команда задаёт ECDHE-RSA-AES128-GCM-SHA256:!RC4 в качестве набора шифров TLS по умолчанию:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' server.js

export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4'
node server.js copy

Для проверки используйте следующую команду, чтобы вывести заданный список шифров. Обратите внимание на разницу между defaultCoreCipherList и defaultCipherList:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n'
ECDHE-RSA-AES128-GCM-SHA256
!RC4 copy

То есть список defaultCoreCipherList задаётся во время компиляции, а defaultCipherList — во время выполнения.

Чтобы изменить набор шифров по умолчанию во время выполнения, измените переменную tls.DEFAULT_CIPHERS. Это необходимо сделать до начала прослушивания любых сокетов; на уже открытые сокеты изменение не повлияет. Например:

// Remove Obsolete CBC Ciphers and RSA Key Exchange based Ciphers as they don't provide Forward Secrecy
tls.DEFAULT_CIPHERS +=
  ':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' +
  ':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' +
  ':!kRSA'; copy

Значение по умолчанию также можно заменить отдельно для клиента или сервера с помощью параметра ciphers из tls.createSecureContext(), который также доступен в tls.createServer(), tls.connect() и при создании новых tls.TLSSocket.

Список шифров может содержать сочетание названий наборов шифров TLSv1.3, начинающихся с 'TLS_', и спецификаций наборов шифров TLSv1.2 и более ранних версий. Для шифров TLSv1.2 поддерживается устаревший формат спецификаций. Подробности см. в документации OpenSSL о формате списка шифров, однако эти спецификации не применяются к шифрам TLSv1.3. Наборы TLSv1.3 можно включить, только указав их полное имя в списке шифров. Например, их нельзя включить или отключить с помощью спецификаций 'EECDH' или '!EECDH' устаревшего формата TLSv1.2.

Независимо от взаимного порядка наборов шифров TLSv1.3 и TLSv1.2, протокол TLSv1.3 значительно безопаснее TLSv1.2. Если в ходе рукопожатия выясняется, что он поддерживается, и включён хотя бы один набор шифров TLSv1.3, всегда будет выбран TLSv1.3.

Набор шифров, включённый в Node.js по умолчанию, тщательно подобран с учётом современных рекомендаций по безопасности и снижению рисков. Изменение набора шифров по умолчанию может существенно повлиять на безопасность приложения. Переключатель --tls-cipher-list и параметр ciphers следует использовать только в случае крайней необходимости.

В наборе шифров по умолчанию отдаются предпочтение шифрам GCM для настройки «современная криптография» Chrome, а также шифрам ECDHE и DHE, обеспечивающим совершенную прямую секретность, при этом сохраняется некоторая обратная совместимость.

Старые клиенты, использующие небезопасные и устаревшие шифры RC4 или на основе DES (например, Internet Explorer 6), не смогут завершить процесс рукопожатия с конфигурацией по умолчанию. Если поддержку этих клиентов необходимо обеспечить, совместимый набор шифров можно подобрать по рекомендациям по TLS. Подробное описание формата см. в документации OpenSSL о формате списка шифров.

Существует всего пять наборов шифров TLSv1.3:

• 'TLS_AES_256_GCM_SHA384'
• 'TLS_CHACHA20_POLY1305_SHA256'
• 'TLS_AES_128_GCM_SHA256'
• 'TLS_AES_128_CCM_SHA256'
• 'TLS_AES_128_CCM_8_SHA256'

Первые три включены по умолчанию. Два набора на основе CCM поддерживаются в TLSv1.3, поскольку на системах с ограниченными ресурсами они могут работать быстрее, однако по умолчанию они отключены, так как обеспечивают меньшую безопасность.

Уровень безопасности OpenSSL

Библиотека OpenSSL применяет уровни безопасности, чтобы контролировать минимально допустимый уровень безопасности криптографических операций. Уровни безопасности OpenSSL варьируются от 0 до 5, причём на каждом следующем уровне требования безопасности становятся строже. Уровень безопасности по умолчанию — 2, что обычно подходит для большинства современных приложений. Однако для правильной работы некоторых устаревших функций и протоколов, таких как TLSv1, требуется более низкий уровень безопасности (SECLEVEL=0). Дополнительную информацию см. в документации OpenSSL об уровнях безопасности.

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

const { createServer, connect } = require('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' });
});

Коды ошибок сертификатов X509

Несколько функций могут завершиться с ошибкой из-за ошибок сертификатов, о которых сообщает OpenSSL. В этом случае функция передаёт через свой обратный вызов объект <Error> со свойством code, которое может принимать одно из следующих значений:

• 'UNABLE_TO_GET_ISSUER_CERT': Не удалось получить сертификат издателя.
• 'UNABLE_TO_GET_CRL': Не удалось получить список отозванных сертификатов (CRL).
• 'UNABLE_TO_DECRYPT_CERT_SIGNATURE': Не удалось расшифровать подпись сертификата.
• 'UNABLE_TO_DECRYPT_CRL_SIGNATURE': Не удалось расшифровать подпись CRL.
• 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY': Не удалось декодировать открытый ключ издателя.
• 'CERT_SIGNATURE_FAILURE': Ошибка подписи сертификата.
• 'CRL_SIGNATURE_FAILURE': Ошибка подписи CRL.
• 'CERT_NOT_YET_VALID': Срок действия сертификата ещё не начался.
• 'CERT_HAS_EXPIRED': Срок действия сертификата истёк.
• 'CRL_NOT_YET_VALID': Срок действия CRL ещё не начался.
• 'CRL_HAS_EXPIRED': Срок действия CRL истёк.
• 'ERROR_IN_CERT_NOT_BEFORE_FIELD': Ошибка формата поля notBefore сертификата.
• 'ERROR_IN_CERT_NOT_AFTER_FIELD': Ошибка формата поля notAfter сертификата.
• 'ERROR_IN_CRL_LAST_UPDATE_FIELD': Ошибка формата поля lastUpdate CRL.
• 'ERROR_IN_CRL_NEXT_UPDATE_FIELD': Ошибка формата поля nextUpdate CRL.
• 'OUT_OF_MEM': Недостаточно памяти.
• 'DEPTH_ZERO_SELF_SIGNED_CERT': Самоподписанный сертификат.
• 'SELF_SIGNED_CERT_IN_CHAIN': Самоподписанный сертификат в цепочке сертификатов.
• 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY': Не удалось получить локальный сертификат издателя.
• 'UNABLE_TO_VERIFY_LEAF_SIGNATURE': Не удалось проверить первый сертификат.
• 'CERT_CHAIN_TOO_LONG': Цепочка сертификатов слишком длинная.
• 'CERT_REVOKED': Сертификат отозван.
• 'INVALID_CA': Недействительный сертификат CA.
• 'PATH_LENGTH_EXCEEDED': Превышено ограничение длины пути.
• 'INVALID_PURPOSE': Неподдерживаемое назначение сертификата.
• 'CERT_UNTRUSTED': Сертификат не является доверенным.
• 'CERT_REJECTED': Сертификат отклонён.
• 'HOSTNAME_MISMATCH': Имя хоста не совпадает.

При возникновении таких ошибок сертификата, как UNABLE_TO_VERIFY_LEAF_SIGNATURE, DEPTH_ZERO_SELF_SIGNED_CERT или UNABLE_TO_GET_ISSUER_CERT, Node.js добавляет подсказку с рекомендацией запустить программу с флагом --use-system-ca, если корневой CA установлен локально. Это помогает разработчикам выбрать безопасное решение и избежать небезопасных обходных путей.

Класс: tls.Server

• Расширяет: <net.Server>

Принимает зашифрованные подключения с использованием TLS или SSL.

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' });
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...')
    return; // Only log keys for a particular IP
  logFile.write(line);
}); copy

const tlsSessionStore = {};
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data;
  cb();
});
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null);
}); copy

Класс: tls.TLSSocket

• Расширяет: <net.Socket>

Выполняет прозрачное шифрование записываемых данных и всю необходимую TLS-согласование.

Экземпляры tls.TLSSocket реализуют двунаправленный интерфейс Stream.

Методы, возвращающие метаданные TLS-соединения (например, tls.TLSSocket.getPeerCertificate()), возвращают данные только при открытом соединении.

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' });
// ...
tlsSocket.on('keylog', (line) => logFile.write(line)); copy

tlsSocket.once('session', (session) => {
  // The session can be used immediately or later.
  tls.connect({
    session: session,
    // Other connect options...
  });
}); copy

const keyingMaterial = tlsSocket.exportKeyingMaterial(
  128,
  'client finished');

/*
 Example return value of keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
*/ copy

{
    "name": "AES256-SHA",
    "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
    "version": "SSLv3"
} copy

tls.checkServerIdentity(hostname, cert)

• hostname <string> Имя хоста или IP-адрес, с которым нужно сверить сертификат.
• cert <Object> Объект сертификата, представляющий сертификат узла.
• Возвращает: <Error> | <undefined>

Проверяет, выдан ли сертификат cert для hostname.

В случае ошибки возвращает объект <Error>, заполняя его полями reason, host и cert. В случае успеха возвращает <undefined>.

Эта функция предназначена для использования совместно с параметром checkServerIdentity, который можно передать в tls.connect(), и поэтому работает с объектом сертификата. В других случаях рассмотрите возможность использования вместо нее x509.checkHost().

Эту функцию можно переопределить, передав альтернативную функцию в качестве параметра options.checkServerIdentity, который передается в tls.connect(). Переопределяющая функция, разумеется, может вызвать tls.checkServerIdentity(), чтобы дополнить выполняемые проверки дополнительной верификацией.

Эта функция вызывается только в том случае, если сертификат прошел все остальные проверки, например проверку на выдачу доверенным центром сертификации (options.ca).

В более ранних версиях Node.js сертификаты для заданного hostname ошибочно принимались при наличии соответствующего альтернативного имени субъекта uniformResourceIdentifier (см. CVE-2021-44531). Приложения, которым необходимо принимать альтернативные имена субъекта uniformResourceIdentifier, могут использовать пользовательскую функцию options.checkServerIdentity, реализующую требуемое поведение.

tls.connect(options[, callback])

• options <Object>
  • enableTrace: см. tls.createServer()
  • host <string> Узел, к которому должен подключиться клиент. По умолчанию: 'localhost'.
  • port <number> Порт, к которому должен подключиться клиент.
  • path <string> Создает подключение через сокет Unix по указанному пути. Если эта опция задана, host и port игнорируются.
  • socket <stream.Duplex> Устанавливает защищенное соединение через указанный сокет вместо создания нового сокета. Обычно это экземпляр net.Socket, но допускается любой поток Duplex. Если эта опция задана, path, host и port игнорируются, за исключением проверки сертификата. Обычно передаваемый в tls.connect() сокет уже подключен, но подключение может быть выполнено и позже. Подключение, отключение и уничтожение socket являются ответственностью пользователя; вызов tls.connect() не приведет к вызову net.connect().
  • allowHalfOpen <boolean> Если установлено значение false, сокет автоматически завершит записываемую сторону, когда завершится читаемая сторона. Если задана опция socket, эта опция не действует. Подробности см. в описании опции allowHalfOpen для net.Socket. По умолчанию: false.
  • rejectUnauthorized <boolean> Если значение не равно false, сертификат сервера проверяется по списку предоставленных центров сертификации. При ошибке проверки генерируется событие 'error'; err.code содержит код ошибки OpenSSL. По умолчанию: true.
  • pskCallback <Function> О согласовании TLS-PSK см. раздел Предварительно общие ключи.
  • ALPNProtocols <string[]> | <Buffer> | <TypedArray> | <DataView> Массив строк или один объект Buffer, TypedArray либо DataView, содержащий поддерживаемые протоколы ALPN. Буферы должны иметь формат [len][name][len][name]..., например '\x08http/1.1\x08http/1.0', где байт len задает длину следующего имени протокола. Обычно передать массив гораздо проще, например ['http/1.1', 'http/1.0']. Протоколы, стоящие в списке раньше, имеют более высокий приоритет.
  • servername <string> Имя сервера для расширения TLS SNI (Server Name Indication). Это имя узла, к которому выполняется подключение; оно должно быть именем узла, а не IP-адресом. Многосетевой сервер может использовать его для выбора сертификата, который следует предъявить клиенту. См. описание опции SNICallback для tls.createServer().
  • checkServerIdentity(servername, cert) <Function> Функция обратного вызова, которая используется вместо встроенной функции tls.checkServerIdentity() при проверке имени узла сервера (или явно заданного значения servername) по сертификату. При ошибке проверки она должна возвращать <Error>. Метод должен возвращать undefined, если проверка servername и cert прошла успешно.
  • session <Buffer> Экземпляр Buffer, содержащий сеанс TLS.
  • requestOCSP <boolean> Если значение равно true, расширение запроса статуса OCSP добавляется в сообщение ClientHello, а до установления защищенного соединения в сокете генерируется событие 'OCSPResponse'.
  • minDHSize <number> Минимальный размер параметра DH в битах для принятия TLS-подключения. Если сервер предлагает параметр DH размером меньше minDHSize, TLS-подключение уничтожается и генерируется ошибка. По умолчанию: 1024.
  • highWaterMark <number> Соответствует параметру highWaterMark читаемого потока. По умолчанию: 16 * 1024.
  • timeout: <number> Если задано и сокет создается внутри, вызывает socket.setTimeout(timeout) после создания сокета, но до начала подключения.
  • secureContext: Объект контекста TLS, созданный с помощью tls.createSecureContext(). Если secureContext не задан, он будет создан путем передачи всего объекта options в tls.createSecureContext().
  • onread <Object> Если опция socket отсутствует, входящие данные сохраняются в одном buffer и передаются указанному callback при поступлении данных в сокет; в противном случае эта опция игнорируется. Подробности см. в описании опции onread для net.Socket.
  • ...: опции tls.createSecureContext(), используемые, если опция secureContext отсутствует; в противном случае они игнорируются.
  • ...: любая опция socket.connect(), не перечисленная выше.
• callback <Function>
• Возвращает: <tls.TLSSocket>

Указанная функция callback будет добавлена в качестве обработчика события 'secureConnect'.

tls.connect() возвращает объект tls.TLSSocket.

В отличие от API https, tls.connect() по умолчанию не включает расширение SNI (Server Name Indication), из-за чего некоторые серверы могут вернуть неверный сертификат или полностью отклонить подключение. Чтобы включить SNI, задайте опцию servername вместе с host.

Ниже показан клиент для примера эхо-сервера из раздела tls.createServer():

// Assumes an echo server that is listening on port 8000.
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');
});

// 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: 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');
  process.stdin.pipe(socket);
  process.stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
  console.log(data);
});
socket.on('end', () => {
  console.log('server ends connection');
});

Чтобы создать сертификат и ключ для этого примера, выполните команду:

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

Затем, чтобы создать сертификат server-cert.pem для этого примера, выполните команду:

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

tls.connect(path[, options][, callback])

• path <string> Значение по умолчанию для options.path.
• options <Object> См. tls.connect().
• callback <Function> См. tls.connect().
• Возвращает: <tls.TLSSocket>

То же, что и tls.connect(), за исключением того, что path можно передать в качестве аргумента, а не опции.

Если задана опция path, она имеет приоритет над аргументом path.

tls.connect(port[, host][, options][, callback])

• port <number> Значение по умолчанию для options.port.
• host <string> Значение по умолчанию для options.host.
• options <Object> См. tls.connect().
• callback <Function> См. tls.connect().
• Возвращает: <tls.TLSSocket>

То же, что и tls.connect(), за исключением того, что port и host можно передать в качестве аргументов, а не опций.

Если заданы опции port или host, они имеют приоритет над соответствующими аргументами port или host.

tls.createSecureContext([options])

• options <Object>
  • allowPartialTrustChain <boolean> Считать промежуточные (не самоподписанные) сертификаты в списке доверенных сертификатов УЦ доверенными.
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> При необходимости переопределяет доверенные сертификаты УЦ. Если параметр не указан, сертификаты УЦ, считающиеся доверенными по умолчанию, совпадают с сертификатами, возвращаемыми tls.getCACertificates() с использованием типа default. Если параметр указан, он полностью заменяет список по умолчанию сертификатами из параметра ca, а не дополняет его. Если нужно добавить дополнительные сертификаты, а не полностью заменить список по умолчанию, пользователям необходимо объединить списки вручную. Значением может быть строка или Buffer либо Array строк и/или Buffer. Любая строка или Buffer может содержать несколько объединённых PEM-сертификатов УЦ. Чтобы соединение прошло аутентификацию, сертификат узла должен иметь цепочку до УЦ, которому доверяет сервер. При использовании сертификатов, не имеющих цепочки до общепризнанного УЦ, сертификат УЦ необходимо явно указать как доверенный, иначе аутентификация соединения завершится неудачно. Если узел использует сертификат, который не совпадает ни с одним из сертификатов УЦ по умолчанию и не имеет до них цепочки, используйте параметр ca, чтобы предоставить сертификат УЦ, которому соответствует сертификат узла или до которого он имеет цепочку. Для самоподписанных сертификатов сам сертификат является собственным УЦ и должен быть предоставлен. Для сертификатов в кодировке PEM поддерживаются типы "TRUSTED CERTIFICATE", "X509 CERTIFICATE" и "CERTIFICATE".
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> Цепочки сертификатов в формате PEM. Для каждого закрытого ключа необходимо предоставить одну цепочку сертификатов. Каждая цепочка сертификатов должна состоять из сертификата в формате PEM для предоставленного закрытого key, за которым в соответствующем порядке следуют промежуточные сертификаты в формате PEM (если они есть); корневой УЦ включать не нужно (корневой УЦ должен быть заранее известен узлу, см. ca). При передаче нескольких цепочек сертификатов их порядок не обязан совпадать с порядком закрытых ключей в key. Если промежуточные сертификаты не предоставлены, узел не сможет проверить сертификат, и согласование завершится неудачно.
  • sigalgs <string> Разделённый двоеточиями список поддерживаемых алгоритмов подписи. Список может содержать алгоритмы дайджеста (SHA256, MD5 и т. д.), алгоритмы открытого ключа (RSA-PSS, ECDSA и т. д.), их комбинации (например, 'RSA+SHA384') или имена схем TLS v1.3 (например, rsa_pss_pss_sha512). Подробнее см. страницы руководства OpenSSL.
  • ciphers <string> Спецификация набора шифров, заменяющая значение по умолчанию. Подробнее см. Изменение набора шифров TLS по умолчанию. Допустимые шифры можно получить с помощью tls.getCiphers(). Имена шифров необходимо указывать в верхнем регистре, чтобы OpenSSL принимал их.
  • clientCertEngine <string> Имя механизма OpenSSL, который может предоставить сертификат клиента. Устарело.
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> Списки отзыва сертификатов (CRL) в формате PEM.
  • dhparam <string> | <Buffer> 'auto' или пользовательские параметры Диффи — Хеллмана, необходимые для совершенной прямой секретности без ECDHE. Если параметр не указан или недопустим, эти параметры будут молча отброшены, а шифры DHE будут недоступны. ECDHE-вариант совершенной прямой секретности останется доступен.
  • ecdhCurve <string> Строка с именем именованной кривой или список разделённых двоеточиями NID либо имён кривых, например P-521:P-384:P-256, для согласования ключей ECDH. Укажите auto, чтобы выбрать кривую автоматически. Используйте crypto.getCurves(), чтобы получить список доступных имён кривых. В последних версиях openssl ecparam -list_curves также отображает имя и описание каждой доступной эллиптической кривой. По умолчанию: tls.DEFAULT_ECDH_CURVE.
  • honorCipherOrder <boolean> Пытаться использовать предпочтения сервера относительно набора шифров вместо предпочтений клиента. Если значение true, приводит к установке SSL_OP_CIPHER_SERVER_PREFERENCE в secureOptions; дополнительную информацию см. в разделе Параметры OpenSSL.
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Закрытые ключи в формате PEM. PEM допускает шифрование закрытых ключей. Зашифрованные ключи будут расшифрованы с помощью options.passphrase. Можно предоставить несколько ключей с разными алгоритмами: в виде массива незашифрованных строк или буферов с ключами либо в виде массива объектов формата {pem: <string|buffer>[, passphrase: <string>]}. Объектный формат допустим только в массиве. Параметр object.passphrase необязателен. Зашифрованные ключи будут расшифрованы с помощью object.passphrase, если он предоставлен, или options.passphrase, если нет.
  • privateKeyEngine <string> Имя механизма OpenSSL, из которого нужно получить закрытый ключ. Следует использовать вместе с privateKeyIdentifier. Устарело.
  • privateKeyIdentifier <string> Идентификатор закрытого ключа, управляемого механизмом OpenSSL. Следует использовать вместе с privateKeyEngine. Не следует задавать вместе с key, поскольку оба параметра задают закрытый ключ разными способами. Устарело.
  • maxVersion <string> При необходимости задаёт максимальную допустимую версию TLS. Одно из значений: 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' или 'TLSv1'. Нельзя указывать вместе с параметром secureProtocol; используйте один из них. По умолчанию: tls.DEFAULT_MAX_VERSION.
  • minVersion <string> При необходимости задаёт минимальную допустимую версию TLS. Одно из значений: 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' или 'TLSv1'. Нельзя указывать вместе с параметром secureProtocol; используйте один из них. Не рекомендуется задавать версию ниже TLSv1.2, однако это может потребоваться для совместимости. Для версий до TLSv1.2 может потребоваться понизить уровень безопасности OpenSSL. По умолчанию: tls.DEFAULT_MIN_VERSION.
  • passphrase <string> Общая парольная фраза для одного закрытого ключа и/или файла PFX.
  • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Закрытый ключ и цепочка сертификатов в кодировке PFX или PKCS12. pfx — альтернатива раздельной передаче key и cert. PFX обычно зашифрован; в этом случае для его расшифровки будет использоваться passphrase. Можно передать несколько файлов PFX: в виде массива незашифрованных буферов PFX либо в виде массива объектов формата {buf: <string|buffer>[, passphrase: <string>]}. Объектный формат допустим только в массиве. Параметр object.passphrase необязателен. Зашифрованные файлы PFX будут расшифрованы с помощью object.passphrase, если он предоставлен, или options.passphrase, если нет.
  • secureOptions <number> При необходимости влияет на поведение протокола OpenSSL, хотя обычно в этом нет необходимости. Используйте этот параметр с осторожностью, если вообще используете! Значение — числовая битовая маска параметров SSL_OP_* из раздела Параметры OpenSSL.
  • secureProtocol <string> Устаревший способ выбора используемой версии протокола TLS; он не позволяет независимо задавать минимальную и максимальную версии и не позволяет ограничить протокол версией TLSv1.3. Вместо него используйте minVersion и maxVersion. Возможные значения перечислены в разделе SSL_METHODS; используйте имена функций в виде строк. Например, используйте 'TLSv1_1_method', чтобы принудительно задать TLS версии 1.1, или 'TLS_method', чтобы разрешить любую версию протокола TLS вплоть до TLSv1.3. Не рекомендуется использовать версии TLS ниже 1.2, однако это может потребоваться для совместимости. По умолчанию: нет, см. minVersion.
  • sessionIdContext <string> Непрозрачный идентификатор, используемый серверами, чтобы гарантировать, что состояние сеанса не используется совместно разными приложениями. Клиенты его не используют.
  • ticketKeys <Buffer> 48 байт криптографически стойких псевдослучайных данных. Подробнее см. раздел Возобновление сеанса.
  • sessionTimeout <number> Количество секунд, по истечении которых сеанс TLS, созданный сервером, больше нельзя будет возобновить. Подробнее см. раздел Возобновление сеанса. По умолчанию: 300.

tls.createServer() задаёт для параметра honorCipherOrder значение по умолчанию true; в других API, создающих защищённые контексты, этот параметр не задан.

tls.createServer() использует в качестве значения по умолчанию параметра sessionIdContext 128-битное усечённое значение хеша SHA1, сгенерированное из process.argv; в других API, создающих защищённые контексты, значение по умолчанию отсутствует.

Метод tls.createSecureContext() создаёт объект SecureContext. Его можно использовать в качестве аргумента в нескольких API tls, например в server.addContext(), однако у него нет открытых методов. Конструктор tls.Server и метод tls.createServer() не поддерживают параметр secureContext.

Для шифров, использующих сертификаты, требуется ключ. Его можно предоставить с помощью key или pfx.

Если параметр ca не указан, Node.js по умолчанию использует общедоступный список доверенных УЦ Mozilla.

Вместо пользовательских параметров DHE рекомендуется использовать новый параметр dhparam: 'auto'. Если задать значение 'auto', автоматически будут выбраны общепринятые параметры DHE достаточной стойкости. В противном случае при необходимости можно использовать openssl dhparam для создания пользовательских параметров. Длина ключа должна быть не меньше 1024 бит, иначе будет выброшена ошибка. Хотя допустима длина 1024 бита, для большей безопасности используйте 2048 бит или более.

tls.createServer([options][, secureConnectionListener])

• options <Object>
  • ALPNProtocols <string[]> | <Buffer> | <TypedArray> | <DataView> Массив строк или одиночный Buffer, TypedArray или DataView, содержащий поддерживаемые протоколы ALPN. Буферы должны иметь формат [len][name][len][name]..., например 0x05hello0x05world, где первый байт указывает длину следующего имени протокола. Обычно передать массив гораздо проще, например ['hello', 'world']. (Протоколы следует упорядочить по приоритету.)
  • ALPNCallback <Function> Если задан, этот обработчик будет вызван, когда клиент установит соединение с использованием расширения ALPN. В функцию обратного вызова будет передан один аргумент: объект, содержащий поля servername и protocols, в которых находятся имя сервера из расширения SNI (если оно есть) и массив строк с именами протоколов ALPN соответственно. Функция обратного вызова должна вернуть одну из строк, перечисленных в protocols, которая будет передана клиенту как выбранный протокол ALPN, либо undefined, чтобы отклонить соединение с фатальным предупреждением. Если возвращённая строка не совпадает ни с одним протоколом ALPN клиента, будет выброшена ошибка. Этот параметр нельзя использовать вместе с параметром ALPNProtocols; при задании обоих параметров будет выброшена ошибка.
  • clientCertEngine <string> Имя движка OpenSSL, который может предоставить сертификат клиента. Устарело.
  • enableTrace <boolean> Если значение равно true, для новых соединений будет вызван tls.TLSSocket.enableTrace(). Трассировку можно включить после установления защищённого соединения, но для трассировки настройки защищённого соединения необходимо использовать этот параметр. По умолчанию: false.
  • handshakeTimeout <number> Прервать соединение, если согласование SSL/TLS не завершится за указанное количество миллисекунд. При каждом превышении времени ожидания согласования на объекте tls.Server генерируется событие 'tlsClientError'. По умолчанию: 120000 (120 секунд).
  • rejectUnauthorized <boolean> Если значение не равно false, сервер отклонит любое соединение, не авторизованное с помощью списка предоставленных центров сертификации. Этот параметр действует только в том случае, если requestCert имеет значение true. По умолчанию: true.
  • requestCert <boolean> Если значение равно true, сервер запросит сертификат у подключающихся клиентов и попытается проверить его. По умолчанию: false.
  • sessionTimeout <number> Количество секунд, по истечении которых возобновление TLS-сеанса, созданного сервером, станет невозможным. Дополнительные сведения см. в разделе Возобновление сеанса. По умолчанию: 300.
  • SNICallback(servername, callback) <Function> Функция, которая будет вызвана, если клиент поддерживает расширение TLS SNI. При вызове ей будут переданы два аргумента: servername и callback. callback — это функция обратного вызова с обработкой ошибки в качестве первого аргумента, принимающая два необязательных аргумента: error и ctx. ctx, если он указан, является экземпляром SecureContext. Для получения корректного SecureContext можно использовать tls.createSecureContext(). Если callback вызвана с ложным аргументом ctx, будет использован контекст безопасности сервера по умолчанию. Если SNICallback не указан, будет использована функция обратного вызова высокого уровня по умолчанию (см. ниже).
  • ticketKeys <Buffer> 48 байт криптографически стойких псевдослучайных данных. Дополнительные сведения см. в разделе Возобновление сеанса.
  • pskCallback <Function> Для согласования TLS-PSK см. раздел Предварительно установленные ключи.
  • pskIdentityHint <string> Необязательная подсказка, отправляемая клиенту для выбора идентификатора при согласовании TLS-PSK. В TLS 1.3 игнорируется. Если не удаётся задать pskIdentityHint, будет сгенерировано событие 'tlsClientError' с кодом 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED'.
  • ...: Можно указать любой параметр tls.createSecureContext(). Для серверов обычно требуются параметры идентификации (pfx, key/cert или pskCallback).
  • ...: Можно указать любой параметр net.createServer().
• secureConnectionListener <Function>
• Возвращает: <tls.Server>

Создаёт новый tls.Server. Если указан параметр secureConnectionListener, он автоматически устанавливается в качестве обработчика события 'secureConnection'.

Параметры ticketKeys автоматически совместно используются рабочими потоками модуля node:cluster.

Ниже показан простой эхо-сервер:

import { createServer } from 'node:tls';
import { readFileSync } from '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');
});

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

Чтобы сгенерировать сертификат и ключ для этого примера, выполните команду:

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

Затем, чтобы сгенерировать сертификат client-cert.pem для этого примера, выполните команду:

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

Работу сервера можно проверить, подключившись к нему с помощью примера клиента из раздела tls.connect().

tls.setDefaultCACertificates(certs)

• certs <string[]> | <ArrayBufferView[]> Массив сертификатов центров сертификации в формате PEM.

Устанавливает сертификаты центров сертификации по умолчанию, используемые TLS-клиентами Node.js. Если предоставленные сертификаты успешно обработаны, они становятся списком сертификатов центров сертификации по умолчанию, возвращаемым tls.getCACertificates() и используемым последующими TLS-соединениями, для которых не указаны собственные сертификаты центров сертификации. Перед установкой сертификаты будут очищены от дубликатов.

Эта функция влияет только на текущий поток Node.js. Изменение не затрагивает ранее сохранённые сеансы агента HTTPS, поэтому этот метод следует вызывать до установления TLS-соединений, результаты которых не должны кэшироваться.

Чтобы использовать системные сертификаты центров сертификации по умолчанию:

const tls = require('node:tls');
tls.setDefaultCACertificates(tls.getCACertificates('system'));

import tls from 'node:tls';
tls.setDefaultCACertificates(tls.getCACertificates('system'));

Эта функция полностью заменяет список сертификатов центров сертификации по умолчанию. Чтобы добавить сертификаты к уже имеющимся, получите текущие сертификаты и добавьте их к ним:

const tls = require('node:tls');
const currentCerts = tls.getCACertificates('default');
const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);

import tls from 'node:tls';
const currentCerts = tls.getCACertificates('default');
const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);

tls.getCACertificates([type])

• type <string> | <undefined> Тип возвращаемых сертификатов центров сертификации. Допустимые значения: "default", "system", "bundled" и "extra". По умолчанию: "default".
• Возвращает: <string[]> Массив сертификатов в кодировке PEM. Массив может содержать дубликаты, если один и тот же сертификат многократно хранится в нескольких источниках.

Возвращает массив сертификатов центров сертификации из различных источников в зависимости от type:

• "default": возвращает сертификаты центров сертификации, которые TLS-клиенты Node.js будут использовать по умолчанию.
  • Если включён параметр --use-bundled-ca (по умолчанию) или не включён параметр --use-openssl-ca, сюда входят сертификаты центров сертификации из встроенного хранилища Mozilla.
  • Если включён параметр --use-system-ca, сюда также входят сертификаты из доверенного хранилища системы.
  • При использовании NODE_EXTRA_CA_CERTS сюда также входят сертификаты, загруженные из указанного файла.
• "system": возвращает сертификаты центров сертификации, загруженные из доверенного хранилища системы согласно правилам, установленным параметром --use-system-ca. Этот вариант можно использовать для получения сертификатов из системы, когда параметр --use-system-ca не включён.
• "bundled": возвращает сертификаты центров сертификации из встроенного хранилища Mozilla. Это те же сертификаты, что и в tls.rootCertificates.
• "extra": возвращает сертификаты центров сертификации, загруженные из NODE_EXTRA_CA_CERTS. Если параметр NODE_EXTRA_CA_CERTS не задан, возвращается пустой массив.

tls.getCiphers()

• Возвращает: <string[]>

Возвращает массив имён поддерживаемых шифров TLS. По историческим причинам имена указаны в нижнем регистре, но для использования в параметре ciphers метода tls.createSecureContext() их необходимо преобразовать в верхний регистр.

По умолчанию включены не все поддерживаемые шифры. См. раздел Изменение набора шифров TLS по умолчанию.

Имена шифров, начинающиеся с 'tls_', предназначены для TLSv1.3; все остальные — для TLSv1.2 и более ранних версий.

console.log(tls.getCiphers()); // ['aes128-gcm-sha256', 'aes128-sha', ...] copy

tls.rootCertificates

• Тип: <string[]>

Неизменяемый массив строк, представляющих корневые сертификаты (в формате PEM) из встроенного хранилища центров сертификации Mozilla, предоставленного в текущей версии Node.js.

Встроенное хранилище центров сертификации, предоставляемое Node.js, представляет собой снимок хранилища центров сертификации Mozilla, зафиксированный на момент выпуска. Он одинаков на всех поддерживаемых платформах.

Чтобы получить фактические сертификаты центров сертификации, используемые текущим экземпляром Node.js, которые могут включать сертификаты из системного хранилища (если используется --use-system-ca) или из файла, указанного в NODE_EXTRA_CA_CERTS, используйте tls.getCACertificates().

tls.DEFAULT_ECDH_CURVE

Имя кривой по умолчанию для согласования ключей ECDH на TLS-сервере. Значение по умолчанию — 'auto'. Дополнительные сведения см. в разделе tls.createSecureContext().

tls.DEFAULT_MAX_VERSION

• Тип: <string> Значение по умолчанию параметра maxVersion для tls.createSecureContext(). Ему можно присвоить любую из поддерживаемых версий протокола TLS: 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' или 'TLSv1'. По умолчанию: 'TLSv1.3', если значение не изменено с помощью параметров CLI. Использование --tls-max-v1.2 задаёт значение по умолчанию 'TLSv1.2'. Использование --tls-max-v1.3 задаёт значение по умолчанию 'TLSv1.3'. Если указано несколько параметров, используется наибольшее максимальное значение.

tls.DEFAULT_MIN_VERSION

• Тип: <string> Значение по умолчанию параметра minVersion для tls.createSecureContext(). Ему можно присвоить любую из поддерживаемых версий протокола TLS: 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' или 'TLSv1'. Для версий ниже TLSv1.2 может потребоваться понизить уровень безопасности OpenSSL. По умолчанию: 'TLSv1.2', если значение не изменено с помощью параметров CLI. Использование --tls-min-v1.0 задаёт значение по умолчанию 'TLSv1'. Использование --tls-min-v1.1 задаёт значение по умолчанию 'TLSv1.1'. Использование --tls-min-v1.3 задаёт значение по умолчанию 'TLSv1.3'. Если указано несколько параметров, используется наименьшее минимальное значение.

tls.DEFAULT_CIPHERS

• Тип: <string> Значение по умолчанию параметра ciphers для tls.createSecureContext(). Ему можно присвоить любой из поддерживаемых шифров OpenSSL. По умолчанию используется содержимое crypto.constants.defaultCoreCipherList, если оно не изменено с помощью параметров CLI, используя --tls-default-ciphers.