Определение отсутствия поддержки криптографии

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 без поддержки криптографии, рассмотрите возможность использования функции 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 «современная криптография» ('modern cryptography'), а также шифрам 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; каждый следующий уровень предъявляет более строгие требования. Уровень безопасности по умолчанию — 1, что обычно подходит для большинства современных приложений. Однако для работы некоторых устаревших функций и протоколов, таких как 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': Недействительный сертификат центра сертификации.
• '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. Эта подсказка помогает разработчикам выбрать безопасное решение и избежать небезопасных обходных путей.

Класс: tls.SecurePair

Возвращается функцией tls.createSecurePair().

Класс: 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 реализуют интерфейс дуплексного потока.

Методы, возвращающие метаданные 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> Массив строк, Buffers, TypedArrays или DataViews либо один Buffer, TypedArray или DataView, содержащий поддерживаемые протоколы ALPN. Buffers должны иметь формат [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>. Если servername и cert прошли проверку, метод должен вернуть undefined.
  • session <Buffer> Экземпляр Buffer, содержащий сеанс TLS.
  • minDHSize <number> Минимальный размер параметра DH в битах, допустимый для TLS-соединения. Если сервер предлагает параметр DH размером менее minDHSize, TLS-соединение будет уничтожено и возникнет ошибка. По умолчанию: 1024.
  • highWaterMark <number> Соответствует параметру highWaterMark читаемого потока. По умолчанию: 16 * 1024.
  • 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.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])

• context <Object> Объект безопасного контекста, возвращаемый tls.createSecureContext()
• isServer <boolean> true, чтобы указать, что это TLS-соединение следует открыть в качестве сервера.
• requestCert <boolean> true, чтобы указать, должен ли сервер запрашивать сертификат у подключающегося клиента. Применяется только если isServer равно true.
• rejectUnauthorized <boolean> Если значение не false, сервер автоматически отклоняет клиентов с недействительными сертификатами. Применяется только если isServer равно true.
• options
  • enableTrace: См. tls.createServer()
  • secureContext: Объект контекста TLS из tls.createSecureContext()
  • isServer: Если true, сокет TLS будет создан в режиме сервера. По умолчанию: false.
  • server <net.Server> Экземпляр net.Server
  • requestCert: См. tls.createServer()
  • rejectUnauthorized: См. tls.createServer()
  • ALPNProtocols: См. tls.createServer()
  • SNICallback: См. tls.createServer()
  • session <Buffer> Экземпляр Buffer, содержащий сеанс TLS.
  • requestOCSP <boolean> Если true, расширение запроса статуса OCSP будет добавлено в ClientHello, а перед установлением защищенного соединения для сокета будет создано событие 'OCSPResponse'.

Создает новый объект защищенной пары с двумя потоками: один из них читает и записывает зашифрованные данные, а другой — открытые данные. Как правило, зашифрованный поток подключается к входящему потоку зашифрованных данных, а также от него, а открытый поток используется вместо исходного зашифрованного потока.

tls.createSecurePair() возвращает объект tls.SecurePair со свойствами потоков cleartext и encrypted.

Использование cleartext предоставляет тот же API, что и tls.TLSSocket.

Метод tls.createSecurePair() теперь устарел; вместо него следует использовать tls.TLSSocket(). Например, следующий код:

pair = tls.createSecurePair(/* ... */);
pair.encrypted.pipe(socket);
socket.pipe(pair.encrypted); copy

можно заменить на:

secureSocket = tls.TLSSocket(socket, options); copy

где secureSocket предоставляет тот же API, что и pair.cleartext.

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

• options <Object>
  • ALPNProtocols <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Массив строк, Buffers, TypedArrays или DataViews либо одиночное значение Buffer, TypedArray или DataView, содержащее поддерживаемые протоколы ALPN. Buffers должны иметь формат [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 не указан, будет использована функция обратного вызова по умолчанию с высокоуровневым API (см. ниже).
  • ticketKeys <Buffer> 48 байт криптографически стойких псевдослучайных данных. Дополнительные сведения см. в разделе Возобновление сеанса.
  • pskCallback <Function> Согласование TLS-PSK описано в разделе Предварительно установленные ключи.
  • pskIdentityHint <string> Необязательная подсказка, отправляемая клиенту для помощи в выборе идентификатора при согласовании TLS-PSK. В TLS 1.3 игнорируется. Если не удалось задать pskIdentityHint, будет создано событие 'tlsClientError' с кодом 'ERR_TLS_PSK_SET_IDENTIY_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[]> Массив сертификатов CA в формате PEM.

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

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

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

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

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

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

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

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

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

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

Чтобы получить фактические сертификаты CA, используемые текущим экземпляром 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.