TLS (SSL)

Модуль node:tls предоставляет реализацию протоколов Transport Layer Security (TLS) и Secure Socket Layer (SSL), построенную на основе OpenSSL. Доступ к модулю можно получить с помощью:

import tls from 'node:tls';

const tls = require('node:tls');

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

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

При использовании лексического ключевого слова 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!');
}
mjscopy

Основные понятия TLS/SSL

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

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

openssl genrsa -out ryans-key.pem 2048
bashcopy

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

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

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

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

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

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

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

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

Где:

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

Совершенная прямая секретность

Термин прямая секретность или совершенная прямая секретность описывает свойство методов согласования ключей (то есть обмена ключами). Это означает, что ключи сервера и клиента используются для согласования новых временных ключей, предназначенных исключительно для текущего сеанса связи. На практике это означает, что даже если закрытый ключ сервера будет скомпрометирован, перехваченную связь можно будет расшифровать только в том случае, если злоумышленнику удастся получить пару ключей, сгенерированную специально для данного сеанса.

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

В настоящее время для обеспечения совершенной прямой секретности обычно используются два метода (обратите внимание на букву «E», добавленную к традиционным сокращениям):

• ECDHE: эфемерная версия протокола согласования ключей Диффи — Хеллмана на эллиптических кривых.
• DHE: эфемерная версия протокола согласования ключей Диффи — Хеллмана.

Совершенная прямая секретность с использованием ECDHE включена по умолчанию. Параметр ecdhCurve можно использовать при создании TLS-сервера, чтобы настроить список поддерживаемых кривых ECDH. Подробнее см. в разделе tls.createServer().

DHE по умолчанию отключён, но его можно включить вместе с ECDHE, установив параметр dhparam в значение 'auto'. Также поддерживаются пользовательские параметры DHE, однако вместо них рекомендуется использовать автоматически выбираемые известные параметры.

До TLSv1.2 совершенная прямая секретность была необязательной. Начиная с TLSv1.3, (EC)DHE используется всегда (за исключением соединений только с PSK).

ALPN и SNI

ALPN (расширение согласования протокола прикладного уровня) и SNI (индикация имени сервера) — это расширения TLS-рукопожатия:

• ALPN: позволяет использовать один TLS-сервер для нескольких протоколов (HTTP, HTTP/2)
• SNI: позволяет использовать один TLS-сервер для нескольких имён хостов с разными сертификатами.

Предварительно распределённые ключи

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

TLS-PSK подходит только в тех случаях, когда ключ можно безопасно передать каждой подключающейся машине, поэтому для большинства сценариев использования TLS он не заменяет инфраструктуру открытых ключей (PKI). В реализации TLS-PSK в OpenSSL за последние годы обнаружено множество уязвимостей, главным образом потому, что она используется лишь небольшим числом приложений. Перед переходом на шифры PSK рассмотрите все альтернативные решения. При генерации PSK крайне важно использовать достаточную энтропию, как описано в RFC 4086. Получение общего секрета из пароля или других источников с низкой энтропией небезопасно.

Шифры PSK по умолчанию отключены, поэтому для использования TLS-PSK необходимо явно указать набор шифров с помощью параметра ciphers. Список доступных шифров можно получить через openssl ciphers -v 'PSK'. Все шифры TLS 1.3 подходят для PSK; их можно получить через openssl ciphers -v -s -tls1_3 -psk. Для клиентского соединения необходимо передать пользовательский checkServerIdentity, поскольку значение по умолчанию не сработает при отсутствии сертификата.

Согласно RFC 4279, должна поддерживаться длина идентификаторов PSK до 128 байт, а длина PSK — до 64 байт. Начиная с OpenSSL 1.1.0 максимальный размер идентификатора составляет 128 байт, а максимальная длина PSK — 256 байт.

Текущая реализация не поддерживает асинхронные обратные вызовы PSK из-за ограничений нижележащего API OpenSSL.

Для использования TLS-PSK клиент и сервер должны указать параметр pskCallback — функцию, возвращающую используемый PSK (он должен быть совместим с дайджестом выбранного шифра).

Сначала функция вызывается на клиенте:

• hint <string> необязательное сообщение, отправленное сервером, которое помогает клиенту определить, какой идентификатор использовать при согласовании. Всегда null, если используется TLS 1.3.
• Возвращает: <Object> в форме { psk: <Buffer|TypedArray|DataView>, identity: <string> } или null.

Затем — на сервере:

• socket <tls.TLSSocket> экземпляр сокета сервера, эквивалентный this.
• identity <string> идентификатор, переданный клиентом.
• Возвращает: <Buffer> | <TypedArray> | <DataView> PSK (или null).

Возвращаемое значение null останавливает процесс согласования и отправляет другой стороне предупреждение unknown_psk_identity. Если сервер хочет скрыть факт неизвестности идентификатора PSK, обратный вызов должен передать случайные данные в качестве psk, чтобы соединение завершилось с ошибкой decrypt_error до окончания согласования.

Защита от атак с повторным согласованием, инициированным клиентом

Протокол TLS позволяет клиентам повторно согласовывать некоторые параметры сеанса TLS. К сожалению, повторное согласование сеанса требует непропорционально больших ресурсов сервера, что может использоваться для атак типа «отказ в обслуживании».

Для снижения риска повторное согласование ограничено тремя запросами за каждые десять минут. При превышении этого порога для экземпляра tls.TLSSocket генерируется событие 'error'. Ограничения можно настроить:

• tls.CLIENT_RENEG_LIMIT <number> задаёт количество запросов на повторное согласование. По умолчанию: 3.
• tls.CLIENT_RENEG_WINDOW <number> задаёт длительность окна повторного согласования в секундах. По умолчанию: 600 (10 минут).

Не следует изменять ограничения повторного согласования по умолчанию, не понимая в полной мере связанных с этим последствий и рисков.

TLSv1.3 не поддерживает повторное согласование.

Возобновление сеанса

Установка TLS-сеанса может занимать сравнительно много времени. Процесс можно ускорить, сохранив состояние сеанса и повторно использовав его позднее. Существует несколько механизмов для этого; ниже они рассмотрены от самого старого к самому новому (и предпочтительному).

Идентификаторы сеанса

Серверы генерируют уникальный идентификатор для новых соединений и отправляют его клиенту. Клиенты и серверы сохраняют состояние сеанса. При повторном подключении клиенты отправляют идентификатор сохранённого состояния сеанса; если сервер также хранит состояние для этого идентификатора, он может согласиться использовать его. В противном случае сервер создаст новый сеанс. Подробнее см. в RFC 2246, стр. 23 и 30.

Возобновление с использованием идентификаторов сеанса поддерживается большинством веб-браузеров при выполнении HTTPS-запросов.

В Node.js клиенты ожидают событие 'session', чтобы получить данные сеанса, а затем передают эти данные параметру session последующего вызова tls.connect() для повторного использования сеанса. Серверы должны реализовать обработчики событий 'newSession' и 'resumeSession', чтобы сохранять и восстанавливать данные сеанса, используя идентификатор сеанса в качестве ключа поиска для повторного использования сеансов. Чтобы повторно использовать сеансы между балансировщиками нагрузки или рабочими процессами кластера, серверы должны применять общий кеш сеансов (например, Redis) в обработчиках сеансов.

Билеты сеанса

Серверы шифруют всё состояние сеанса и отправляют его клиенту в виде «билета». При повторном подключении состояние передаётся серверу в начальном запросе на соединение. Этот механизм позволяет обойтись без серверного кеша сеансов. Если сервер по какой-либо причине не использует билет (например, не может его расшифровать или билет слишком старый), он создаёт новый сеанс и отправляет новый билет. Подробнее см. в RFC 5077.

Возобновление с использованием билетов сеанса получает всё более широкую поддержку в веб-браузерах при выполнении HTTPS-запросов.

В Node.js клиенты используют те же API для возобновления сеанса с помощью идентификаторов сеанса и билетов сеанса. Для отладки: если tls.TLSSocket.getTLSTicket() возвращает значение, данные сеанса содержат билет; в противном случае они содержат состояние сеанса на стороне клиента.

При использовании TLSv1.3 учитывайте, что сервер может отправить несколько билетов, что приведёт к нескольким событиям 'session'. Подробнее см. в разделе 'session'.

Для использования билетов сеанса на одном серверном процессе не требуется специальная реализация. Чтобы использовать билеты сеанса после перезапуска сервера или между балансировщиками нагрузки, все серверы должны иметь одинаковые ключи билетов. Внутри используются три 16-байтовых ключа, но для удобства API tls предоставляет их в виде одного 48-байтового буфера.

Ключи билетов можно получить, вызвав server.getTicketKeys() для экземпляра сервера и затем распространив их, однако разумнее безопасно сгенерировать 48 байт случайных данных и задать их с помощью параметра ticketKeys метода tls.createServer(). Ключи следует регулярно обновлять; ключи сервера можно сбросить с помощью server.setTicketKeys().

Ключи билетов сеанса — это криптографические ключи, и их необходимо хранить в безопасном месте. При использовании TLS 1.2 и более ранних версий, если ключи скомпрометированы, можно расшифровать все сеансы, в которых использовались зашифрованные ими билеты. Ключи не следует хранить на диске; их необходимо регулярно обновлять.

Если клиенты объявляют о поддержке билетов, сервер отправляет их. Сервер может отключить билеты, передав require('node:constants').SSL_OP_NO_TICKET в secureOptions.

Идентификаторы и билеты сеанса имеют срок действия, по истечении которого сервер создаёт новые сеансы. Время ожидания можно настроить с помощью параметра sessionTimeout метода tls.createServer().

При использовании любого из этих механизмов серверы создают новые сеансы, если возобновить сеанс не удаётся. Поскольку неудачная попытка возобновления не приводит к сбою TLS/HTTPS-соединения, легко не заметить неоправданно низкую производительность TLS. Чтобы проверить, возобновляют ли серверы сеансы, можно использовать интерфейс командной строки OpenSSL. Используйте параметр -reconnect с командой openssl s_client, например:

openssl s_client -connect localhost:443 -reconnect
bashcopy

Изучите отладочный вывод. Для первого соединения должно быть указано «New», например:

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

Для последующих соединений должно быть указано «Reused», например:

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

Изменение набора шифров 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
consolecopy

Значение по умолчанию можно полностью заменить с помощью параметра командной строки --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
bashcopy

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

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

То есть список 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';
jscopy

Значение по умолчанию также можно переопределить для отдельного клиента или сервера с помощью параметра 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 «современная криптография» (Chrome's 'modern cryptography' setting), а также шифрам 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 об уровнях безопасности.

Установка уровней безопасности

Чтобы изменить уровень безопасности в приложении Node.js, можно включить @SECLEVEL=X в строку шифров, где X — требуемый уровень безопасности. Например, чтобы установить уровень безопасности 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' });
});

Такой подход устанавливает уровень безопасности 0, позволяя использовать устаревшие функции и при этом задействовать шифры OpenSSL по умолчанию.

Использование --tls-cipher-list

Также можно задать уровень безопасности и шифры из командной строки с помощью --tls-cipher-list=DEFAULT@SECLEVEL=X, как описано в разделе «Изменение набора шифров TLS по умолчанию». Однако обычно не рекомендуется задавать шифры через параметр командной строки. Предпочтительнее настраивать шифры для отдельных контекстов в коде приложения: такой подход обеспечивает более точный контроль и снижает риск глобального понижения уровня безопасности.

Коды ошибок сертификатов 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 добавляет подсказку: если корневой CA установлен локально, попробуйте запустить приложение с флагом --use-system-ca. Эта подсказка направляет разработчиков к безопасному решению и помогает избежать небезопасных обходных путей.

Класс: tls.Server

• Наследует: <net.Server>

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

Событие: 'connection'

• socket <stream.Duplex>

Это событие генерируется при установлении нового потока TCP, до начала TLS-рукопожатия. Обычно socket — это объект типа net.Socket, но он не будет получать события, в отличие от сокета, созданного событием 'connection' класса net.Server. Обычно пользователям не требуется обращаться к этому событию.

Пользователи также могут явно сгенерировать это событие, чтобы передать соединения на TLS-сервер. В этом случае можно передать любой поток Duplex.

Событие: 'keylog'

• line <Buffer> строка текста ASCII в формате SSLKEYLOGFILE NSS.
• tlsSocket <tls.TLSSocket> экземпляр tls.TLSSocket, для которого он был сгенерирован.

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

Обычный сценарий использования — добавление полученных строк в общий текстовый файл, который затем используется программами (например, Wireshark) для расшифровки трафика:

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

Событие: 'newSession'

Событие 'newSession' генерируется при создании нового сеанса TLS. Его можно использовать для сохранения сеансов во внешнем хранилище. Эти данные следует передавать обратному вызову 'resumeSession'.

При вызове обработчик получает три аргумента:

• sessionId <Buffer> идентификатор сеанса TLS
• sessionData <Buffer> данные сеанса TLS
• callback <Function> функция обратного вызова без аргументов, которую необходимо вызвать, чтобы обеспечить отправку или получение данных через защищённое соединение.

Прослушивание этого события влияет только на соединения, установленные после добавления его обработчика.

Событие: 'OCSPRequest'

Событие 'OCSPRequest' возникает, когда клиент отправляет запрос статуса сертификата. При вызове обработчику передаются три аргумента:

• certificate <Buffer> Сертификат сервера
• issuer <Buffer> Сертификат издателя
• callback <Function> Функция обратного вызова, которую необходимо вызвать для предоставления результатов OCSP-запроса.

Текущий сертификат сервера можно разобрать, чтобы получить URL-адрес OCSP и идентификатор сертификата; после получения ответа OCSP вызывается callback(null, resp), где resp — экземпляр Buffer, содержащий ответ OCSP. И certificate, и issuer представляют собой DER-представления основного сертификата и сертификата издателя (Buffer). Их можно использовать для получения идентификатора сертификата OCSP и URL-адреса конечной точки OCSP.

Кроме того, можно вызвать callback(null, null), указав тем самым, что ответ OCSP отсутствует.

Вызов callback(err) приведёт к вызову socket.destroy(err).

Типичный процесс выполнения OCSP-запроса выглядит следующим образом:

1. Клиент подключается к серверу и отправляет 'OCSPRequest' (через расширение информации о статусе в ClientHello).
2. Сервер получает запрос и создаёт событие 'OCSPRequest', вызывая обработчик, если он зарегистрирован.
3. Сервер извлекает URL-адрес OCSP из certificate или issuer и выполняет OCSP-запрос к центру сертификации.
4. Сервер получает от центра сертификации 'OCSPResponse' и отправляет его клиенту через аргумент callback
5. Клиент проверяет ответ и либо уничтожает сокет, либо выполняет рукопожатие.

Значение issuer может быть null, если сертификат самоподписанный или издатель отсутствует в списке корневых сертификатов. (Сертификат издателя можно указать с помощью параметра ca при установлении TLS-соединения.)

Прослушивание этого события влияет только на соединения, установленные после добавления обработчика события.

Для разбора сертификатов можно использовать npm-модуль, например asn1.js.

Событие: 'resumeSession'

Событие 'resumeSession' возникает, когда клиент запрашивает возобновление предыдущего TLS-сеанса. При вызове обработчику передаются два аргумента:

• sessionId <Buffer> Идентификатор TLS-сеанса
• callback <Function> Функция обратного вызова, которую нужно вызвать после восстановления предыдущего сеанса: callback([err[, sessionData]])
  • err <Error>
  • sessionData <Buffer>

Обработчик события должен выполнить поиск во внешнем хранилище, чтобы найти sessionData, сохранённый обработчиком события 'newSession', используя переданный sessionId. Если сеанс найден, вызовите callback(null, sessionData), чтобы возобновить его. Если сеанс не найден, возобновить его нельзя. callback() необходимо вызвать без sessionData, чтобы рукопожатие могло продолжиться и был создан новый сеанс. Можно вызвать callback(err), чтобы завершить входящее соединение и уничтожить сокет.

Прослушивание этого события влияет только на соединения, установленные после добавления обработчика события.

Ниже показано возобновление TLS-сеанса:

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

Событие: 'secureConnection'

Событие 'secureConnection' возникает после успешного завершения процесса рукопожатия для нового соединения. При вызове обработчику передаётся один аргумент:

• tlsSocket <tls.TLSSocket> Установленный TLS-сокет.

Свойство tlsSocket.authorized имеет тип boolean и указывает, прошёл ли клиент проверку одним из центров сертификации, предоставленных для сервера. Если tlsSocket.authorized имеет значение false, то в socket.authorizationError указывается причина сбоя авторизации. В зависимости от настроек TLS-сервера неавторизованные соединения всё ещё могут приниматься.

Свойство tlsSocket.alpnProtocol — это строка, содержащая выбранный протокол ALPN. Если ALPN не выбрал протокол, потому что клиент или сервер не отправил расширение ALPN, tlsSocket.alpnProtocol равно false.

Свойство tlsSocket.servername — это строка, содержащая имя сервера, запрошенное через SNI.

Событие: 'tlsClientError'

Событие 'tlsClientError' возникает при ошибке до установления защищённого соединения. При вызове обработчику передаются два аргумента:

• exception <Error> Объект Error с описанием ошибки
• tlsSocket <tls.TLSSocket> Экземпляр tls.TLSSocket, в котором возникла ошибка.

server.addContext(hostname, context)

• hostname <string> Имя узла SNI или шаблон с подстановочными знаками (например, '*')
• context <Object> | <tls.SecureContext> Объект с любыми возможными свойствами из аргументов options tls.createSecureContext() (например, key, cert, ca и т. д.) или объект контекста TLS, созданный непосредственно с помощью tls.createSecureContext().

Метод server.addContext() добавляет защищённый контекст, который будет использоваться, если имя SNI в запросе клиента совпадает с указанным hostname (или шаблоном с подстановочными знаками).

Если подходит несколько контекстов, используется последний добавленный.

server.address()

• Возвращает: <Object>

Возвращает привязанный адрес, имя семейства адресов и порт сервера, предоставленные операционной системой. Дополнительные сведения см. в разделе net.Server.address().

server.close([callback])

• callback <Function> Обработчик, который будет зарегистрирован для прослушивания события 'close' экземпляра сервера.
• Возвращает: <tls.Server>

Метод server.close() прекращает принимать новые соединения.

Эта функция работает асинхронно. Событие 'close' будет создано, когда у сервера не останется открытых соединений.

server.getTicketKeys()

• Возвращает: <Buffer> Буфер размером 48 байт, содержащий ключи билетов сеанса.

Возвращает ключи билетов сеанса.

Дополнительные сведения см. в разделе Возобновление сеанса.

server.listen()

Запускает прослушивание сервером зашифрованных соединений. Этот метод идентичен методу server.listen() класса net.Server.

server.setSecureContext(options)

• options <Object> Объект с любыми возможными свойствами из аргументов options tls.createSecureContext() (например, key, cert, ca и т. д.).

Метод server.setSecureContext() заменяет защищённый контекст существующего сервера. Существующие соединения с сервером не прерываются.

server.setTicketKeys(keys)

• keys <Buffer> | <TypedArray> | <DataView> Буфер размером 48 байт, содержащий ключи билетов сеанса.

Задаёт ключи билетов сеанса.

Изменения ключей билетов применяются только к будущим соединениям с сервером. Для существующих или находящихся в процессе установки соединений с сервером будут использоваться предыдущие ключи.

Дополнительные сведения см. в разделе Возобновление сеанса.

Класс: tls.TLSSocket

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

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

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

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

new tls.TLSSocket(socket[, options])

• socket <net.Socket> | <stream.Duplex> На стороне сервера — любой поток Duplex. На стороне клиента — любой экземпляр net.Socket (для поддержки универсального потока Duplex на стороне клиента необходимо использовать tls.connect()).
• options <Object>
  • enableTrace: См. tls.createServer()
  • isServer: Протокол SSL/TLS асимметричен, поэтому TLSSocket должен знать, должен ли он работать как сервер или клиент. Если true, TLS-сокет будет создан как сервер. Значение по умолчанию: false.
  • server <net.Server> Экземпляр net.Server.
  • requestCert: Необходимо ли аутентифицировать удалённую сторону, запросив сертификат. Клиенты всегда запрашивают сертификат сервера. Серверы (если isServer имеет значение true) могут задать для requestCert значение true, чтобы запросить сертификат клиента.
  • rejectUnauthorized: См. tls.createServer()
  • ALPNProtocols: См. tls.createServer()
  • SNICallback: См. tls.createServer()
  • ALPNCallback: См. tls.createServer()
  • session <Buffer> Экземпляр Buffer, содержащий TLS-сеанс.
  • requestOCSP <boolean> Если значение true, в ClientHello будет добавлено расширение запроса статуса OCSP, а перед установлением защищённого соединения на сокете возникнет событие 'OCSPResponse'
  • secureContext: Объект контекста TLS, созданный с помощью tls.createSecureContext(). Если secureContext не указан, он будет создан путём передачи всего объекта options в tls.createSecureContext().
  • ...: параметры tls.createSecureContext(), используемые, если параметр secureContext отсутствует. В противном случае они игнорируются.

Создаёт новый объект tls.TLSSocket на основе существующего TCP-сокета.

Событие: 'keylog'

• line <Buffer> Строка ASCII в формате NSS SSLKEYLOGFILE.

Событие keylog возникает на tls.TLSSocket при создании или получении сокетом ключевого материала. Этот ключевой материал можно сохранить для отладки, поскольку он позволяет расшифровать перехваченный TLS-трафик. Событие может возникать несколько раз — до или после завершения рукопожатия.

Типичный пример использования — добавление полученных строк в общий текстовый файл, который затем используется программным обеспечением (например, Wireshark) для расшифровки трафика:

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

Событие: 'OCSPResponse'

Событие 'OCSPResponse' возникает, если при создании tls.TLSSocket был задан параметр requestOCSP и получен ответ OCSP. При вызове обработчику передаётся один аргумент:

• response <Buffer> Ответ OCSP сервера

Обычно response — это цифровой объект с подписью центра сертификации сервера, содержащий сведения о статусе отзыва сертификата сервера.

Событие: 'secure'

Событие 'secure' возникает после успешного завершения TLS-рукопожатия и установления защищённого соединения.

Это событие возникает на экземплярах <tls.TLSSocket> как на стороне клиента, так и на стороне сервера, в том числе на сокетах, созданных с помощью конструктора new tls.TLSSocket().

Событие: 'secureConnect'

Событие 'secureConnect' возникает после успешного завершения процесса рукопожатия для нового соединения. Обработчик будет вызван независимо от того, был ли сертификат сервера авторизован. Клиент должен проверить свойство tlsSocket.authorized, чтобы определить, подписан ли сертификат сервера одним из указанных центров сертификации. Если значение tlsSocket.authorized === false, ошибку можно определить, проверив свойство tlsSocket.authorizationError. Если использовался ALPN, свойство tlsSocket.alpnProtocol можно проверить, чтобы определить согласованный протокол.

Событие 'secureConnect' не возникает, если <tls.TLSSocket> создан с помощью конструктора new tls.TLSSocket().

Событие: 'session'

• session <Buffer>

Событие 'session' возникает на клиентском tls.TLSSocket, когда становится доступен новый сеанс или билет TLS. В зависимости от согласованной версии протокола TLS это может произойти до или после завершения рукопожатия. На сервере событие не возникает; оно также не возникает, если новый сеанс не был создан, например, при возобновлении соединения. Для некоторых версий протокола TLS событие может возникать несколько раз; в таком случае все сеансы можно использовать для возобновления.

На клиенте session можно передать в параметр session метода tls.connect(), чтобы возобновить соединение.

Дополнительные сведения см. в разделе Возобновление сеанса.

Для TLSv1.2 и более ранних версий можно вызвать tls.TLSSocket.getSession() после завершения рукопожатия. В TLSv1.3 протокол допускает только возобновление на основе билетов; отправляется несколько билетов, и они передаются только после завершения рукопожатия. Поэтому для получения сеанса, пригодного для возобновления, необходимо дождаться события 'session'. Приложениям следует использовать событие 'session' вместо getSession(), чтобы обеспечить совместимость со всеми версиями TLS. Приложениям, которым требуется только получить или использовать один сеанс, достаточно прослушать это событие один раз:

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

tlsSocket.address()

• Возвращает: <Object>

Возвращает привязанный address, имя семейства адресов family и port базового сокета, предоставленные операционной системой: { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

tlsSocket.authorizationError

Возвращает причину, по которой сертификат удалённой стороны не прошёл проверку. Это свойство задаётся только при tlsSocket.authorized === false.

tlsSocket.authorized

• Тип: <boolean>

Это свойство имеет значение true, если сертификат удалённой стороны подписан одним из центров сертификации, указанных при создании экземпляра tls.TLSSocket, и false в противном случае.

tlsSocket.disableRenegotiation()

Отключает повторное согласование TLS для этого экземпляра TLSSocket. После вызова попытки повторного согласования будут вызывать событие 'error' на TLSSocket.

tlsSocket.enableTrace()

Если функция включена, сведения трассировки TLS-пакетов записываются в stderr. Это можно использовать для отладки проблем с TLS-соединением.

Формат вывода идентичен выводу openssl s_client -trace или openssl s_server -trace. Хотя он создаётся функцией SSL_trace() из OpenSSL, его формат не документирован, может измениться без предупреждения, и на него не следует полагаться.

tlsSocket.encrypted

Всегда возвращает true. Это свойство можно использовать, чтобы отличать TLS-сокеты от обычных экземпляров net.Socket.

tlsSocket.exportKeyingMaterial(length, label[, context])

• length <number> количество байтов ключевого материала для получения

• label <string> метка, специфичная для приложения; обычно это значение из реестра меток экспортёра IANA.

• context <Buffer> Необязательный контекст.

• Возвращает: <Buffer> запрошенные байты ключевого материала

Ключевой материал используется для проверок, предотвращающих различные виды атак на сетевые протоколы, например в спецификациях IEEE 802.1X.

Пример

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

Дополнительные сведения см. в документации OpenSSL по функции SSL_export_keying_material.

tlsSocket.getCertificate()

• Возвращает: <Object>

Возвращает объект, представляющий локальный сертификат. В возвращаемом объекте есть свойства, соответствующие полям сертификата.

Пример структуры сертификата см. в разделе tls.TLSSocket.getPeerCertificate().

Если локальный сертификат отсутствует, возвращается пустой объект. Если сокет уничтожен, возвращается null.

tlsSocket.getCipher()

• Возвращает: <Object>
  • name <string> Имя набора шифров в OpenSSL.
  • standardName <string> Имя набора шифров в IETF.
  • version <string> Минимальная версия протокола TLS, поддерживаемая этим набором шифров. Фактически согласованный протокол см. в разделе tls.TLSSocket.getProtocol().

Возвращает объект со сведениями о согласованном наборе шифров.

Например, протокол TLSv1.2 с шифром AES256-SHA:

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

Дополнительные сведения см. в разделе SSL_CIPHER_get_name.

tlsSocket.getEphemeralKeyInfo()

• Возвращает: <Object>

Возвращает объект, описывающий тип, имя и размер параметра эфемерного обмена ключами при подключении клиента с совершенной прямой секретностью. Если обмен ключами не является эфемерным, возвращается пустой объект. Так как эта функция поддерживается только для клиентского сокета, при вызове для серверного сокета возвращается null. Поддерживаются типы 'DH' и 'ECDH'. Свойство name доступно только для типа 'ECDH'.

Например: { type: 'ECDH', name: 'prime256v1', size: 256 }.

tlsSocket.getFinished()

• Возвращает: <Buffer> | <undefined> Последнее сообщение Finished, отправленное сокету в рамках SSL/TLS-рукопожатия, либо undefined, если сообщение Finished ещё не отправлялось.

Поскольку сообщения Finished представляют собой дайджесты всего рукопожатия (общим размером 192 бита для TLS 1.0 и более для SSL 3.0), их можно использовать во внешних процедурах аутентификации, когда аутентификация, предоставляемая SSL/TLS, нежелательна или недостаточна.

Соответствует процедуре SSL_get_finished в OpenSSL и может использоваться для реализации привязки канала tls-unique из RFC 5929.

tlsSocket.getPeerCertificate([detailed])

• detailed <boolean> Если значение true, включить полную цепочку сертификатов; в противном случае включить только сертификат удалённой стороны.
• Возвращает: <Object> Объект сертификата.

Возвращает объект, представляющий сертификат удалённой стороны. Если удалённая сторона не предоставила сертификат, возвращается пустой объект. Если сокет уничтожен, возвращается null.

Если запрошена полная цепочка сертификатов, каждый сертификат будет содержать свойство issuerCertificate с объектом, представляющим сертификат издателя.

Объект сертификата

Объект сертификата имеет свойства, соответствующие полям сертификата.

• ca <boolean> true если это центр сертификации (CA), false в противном случае.
• raw <Buffer> Данные сертификата X.509 в кодировке DER.
• subject <Object> Субъект сертификата, описанный через страну (C), штат или провинцию (ST), населённый пункт (L), организацию (O), подразделение организации (OU) и общее имя (CN). Для сертификатов TLS общее имя обычно является именем DNS. Пример: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}.
• issuer <Object> Издатель сертификата, описанный в тех же терминах, что и subject.
• valid_from <string> Дата и время, с которых сертификат действителен.
• valid_to <string> Дата и время, до которых сертификат действителен.
• serialNumber <string> Серийный номер сертификата в виде шестнадцатеричной строки. Пример: 'B9B0D332A1AA5635'.
• fingerprint <string> Дайджест SHA-1 сертификата в кодировке DER. Возвращается в виде шестнадцатеричной строки с разделителями :. Пример: '2A:7A:C2:DD:...'.
• fingerprint256 <string> Дайджест SHA-256 сертификата в кодировке DER. Возвращается в виде шестнадцатеричной строки с разделителями :. Пример: '2A:7A:C2:DD:...'.
• fingerprint512 <string> Дайджест SHA-512 сертификата в кодировке DER. Возвращается в виде шестнадцатеричной строки с разделителями :. Пример: '2A:7A:C2:DD:...'.
• ext_key_usage <Array> (необязательно) Расширенное назначение ключа — набор OID.
• subjectaltname <string> (необязательно) Строка, содержащая объединённые имена субъекта, альтернативная именам subject.
• infoAccess <Array> (необязательно) Массив с описанием AuthorityInfoAccess, используемый с OCSP.
• issuerCertificate <Object> (необязательно) Объект сертификата издателя. Для самоподписанных сертификатов это может быть циклическая ссылка.

Сертификат может содержать сведения об открытом ключе — в зависимости от типа ключа.

Для ключей RSA могут быть определены следующие свойства:

• bits <number> Размер ключа RSA в битах. Пример: 1024.
• exponent <string> Экспонента RSA в виде строки в шестнадцатеричной системе счисления. Пример: '0x010001'.
• modulus <string> Модуль RSA в виде шестнадцатеричной строки. Пример: 'B56CE45CB7...'.
• pubkey <Buffer> Открытый ключ.

Для ключей EC могут быть определены следующие свойства:

• pubkey <Buffer> Открытый ключ.
• bits <number> Размер ключа в битах. Пример: 256.
• asn1Curve <string> (необязательно) Имя ASN.1 для OID эллиптической кривой. Известные кривые идентифицируются по OID. Хотя это и необычно, кривая может быть идентифицирована своими математическими свойствами — в таком случае у неё не будет OID. Пример: 'prime256v1'.
• nistCurve <string> (необязательно) Имя эллиптической кривой по NIST, если оно есть (не всем известным кривым NIST присвоила имена). Пример: 'P-256'.

Пример сертификата:

{ subject:
   { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
     CN: '*.nodejs.org' },
  issuer:
   { C: 'GB',
     ST: 'Greater Manchester',
     L: 'Salford',
     O: 'COMODO CA Limited',
     CN: 'COMODO RSA Domain Validation Secure Server CA' },
  subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
  infoAccess:
   { 'CA Issuers - URI':
      [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
     'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
  modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  exponent: '0x10001',
  pubkey: <Buffer ... >,
  valid_from: 'Aug 14 00:00:00 2017 GMT',
  valid_to: 'Nov 20 23:59:59 2019 GMT',
  fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
  fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
  fingerprint512: '19:2B:3E:C3:B3:5B:32:E8:AE:BB:78:97:27:E4:BA:6C:39:C9:92:79:4F:31:46:39:E2:70:E5:5F:89:42:17:C9:E8:64:CA:FF:BB:72:56:73:6E:28:8A:92:7E:A3:2A:15:8B:C2:E0:45:CA:C3:BC:EA:40:52:EC:CA:A2:68:CB:32',
  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
  serialNumber: '66593D57F20CBC573E433381B5FEC280',
  raw: <Buffer ... > }
jscopy

tlsSocket.getPeerFinished()

• Возвращает: <Buffer> | <undefined> Последнее сообщение Finished, которое ожидается или уже получено от сокета в рамках рукопожатия SSL/TLS, либо undefined, если сообщение Finished ещё не получено.

Поскольку сообщения Finished являются дайджестами сообщений для всего рукопожатия (общим размером 192 бита для TLS 1.0 и больше для SSL 3.0), их можно использовать для внешних процедур аутентификации, когда аутентификация SSL/TLS не требуется или недостаточна.

Соответствует процедуре SSL_get_peer_finished в OpenSSL и может использоваться для реализации связывания каналов tls-unique из RFC 5929.

tlsSocket.getPeerX509Certificate()

• Возвращает: <X509Certificate>

Возвращает сертификат узла-партнёра в виде объекта <X509Certificate>.

Если сертификат узла-партнёра отсутствует или сокет уничтожен, будет возвращено undefined.

tlsSocket.getProtocol()

• Возвращает: <string> | <null>

Возвращает строку с согласованной версией протокола SSL/TLS для текущего соединения. Для подключённых сокетов, в которых процесс рукопожатия ещё не завершён, возвращается значение 'unknown'. Для серверных сокетов или отключённых клиентских сокетов возвращается значение null.

Версии протокола:

• 'SSLv3'
• 'TLSv1'
• 'TLSv1.1'
• 'TLSv1.2'
• 'TLSv1.3'

Дополнительные сведения см. в документации OpenSSL по функции SSL_get_version.

tlsSocket.getSession()

• Тип: <Buffer>

Возвращает данные сеанса TLS или undefined, если сеанс не был согласован. На клиенте эти данные можно передать в параметр session функции tls.connect() для возобновления соединения. На сервере они могут быть полезны для отладки.

Дополнительные сведения см. в разделе Возобновление сеанса.

Примечание: getSession() работает только для TLSv1.2 и более ранних версий. Для TLSv1.3 приложения должны использовать событие 'session' (оно также работает для TLSv1.2 и более ранних версий).

tlsSocket.getSharedSigalgs()

• Возвращает: <Array> Список алгоритмов подписи, общих для сервера и клиента, в порядке убывания предпочтения.

Дополнительные сведения см. в разделе SSL_get_shared_sigalgs.

tlsSocket.getTLSTicket()

• Тип: <Buffer>

На клиенте возвращает билет сеанса TLS, если он доступен, либо undefined. На сервере всегда возвращает undefined.

Это может быть полезно для отладки.

Дополнительные сведения см. в разделе Возобновление сеанса.

tlsSocket.getX509Certificate()

• Возвращает: <X509Certificate>

Возвращает локальный сертификат в виде объекта <X509Certificate>.

Если локальный сертификат отсутствует или сокет уничтожен, будет возвращено undefined.

tlsSocket.isSessionReused()

• Возвращает: <boolean> true, если сеанс был повторно использован, false в противном случае.

Дополнительные сведения см. в разделе Возобновление сеанса.

tlsSocket.localAddress

• Тип: <string>

Возвращает строковое представление локального IP-адреса.

tlsSocket.localPort

• Тип: <integer>

Возвращает числовое представление локального порта.

tlsSocket.remoteAddress

• Тип: <string>

Возвращает строковое представление удалённого IP-адреса. Например, '74.125.127.100' или '2001:4860:a005::68'.

tlsSocket.remoteFamily

• Тип: <string>

Возвращает строковое представление семейства удалённого IP-адреса: 'IPv4' или 'IPv6'.

tlsSocket.remotePort

• Тип: <integer>

Возвращает числовое представление удалённого порта. Например, 443.

tlsSocket.renegotiate(options, callback)

• options <Object>

  • rejectUnauthorized <boolean> Если значение не равно false, сертификат сервера проверяется по списку предоставленных центров сертификации. Если проверка не пройдёт, будет сгенерировано событие 'error'; err.code содержит код ошибки OpenSSL. По умолчанию: true.
  • requestCert

• callback <Function> Если renegotiate() вернуло true, обратный вызов однократно привязывается к событию 'secure'. Если renegotiate() вернуло false, callback будет вызван в следующем цикле с ошибкой, если только tlsSocket не был уничтожен; в этом случае callback вообще не будет вызван.

• Возвращает: <boolean> true, если повторное согласование было инициировано, false в противном случае.

Метод tlsSocket.renegotiate() инициирует процесс повторного согласования TLS. По завершении функции callback будет передан один аргумент: либо Error (если запрос завершился ошибкой), либо null.

Этот метод можно использовать, чтобы запросить сертификат узла-партнёра после установки защищённого соединения.

При работе в качестве сервера сокет будет уничтожен с ошибкой по истечении времени ожидания handshakeTimeout.

Для TLSv1.3 повторное согласование невозможно, поскольку оно не поддерживается протоколом.

tlsSocket.setKeyCert(context)

• context <Object> | <tls.SecureContext> Объект, содержащий как минимум свойства key и cert из options tls.createSecureContext(), либо объект контекста TLS, созданный с помощью tls.createSecureContext().

Метод tlsSocket.setKeyCert() задаёт закрытый ключ и сертификат, используемые сокетом. Это особенно полезно, если требуется выбрать сертификат сервера из ALPNCallback TLS-сервера.

tlsSocket.setMaxSendFragment(size)

• size <number> Максимальный размер фрагмента TLS. Максимальное значение — 16384. По умолчанию: 16384.
• Возвращает: <boolean>

Метод tlsSocket.setMaxSendFragment() задаёт максимальный размер фрагмента TLS. Возвращает true, если ограничение установлено успешно, и false в противном случае.

Меньший размер фрагментов снижает задержку буферизации на клиенте: более крупные фрагменты буферизуются на уровне TLS до получения всего фрагмента и проверки его целостности; крупные фрагменты могут передаваться в течение нескольких циклов обмена данными, а их обработка может задерживаться из-за потери или переупорядочивания пакетов. Однако меньшие фрагменты увеличивают объём дополнительных данных кадрирования TLS и нагрузку на ЦП, что может снизить общую пропускную способность сервера.

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>. Если servername и cert проверены, метод должен возвращать undefined.
  • 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
bashcopy

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

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

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
bashcopy

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

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

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

tls.setDefaultCACertificates(certs)

• certs <string[]> Массив сертификатов центров сертификации в формате 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', ...]
jscopy

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', если оно не изменено параметрами командной строки. Использование --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', если оно не изменено параметрами командной строки. Использование --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, если оно не изменено параметрами командной строки с помощью --tls-default-ciphers.