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

Возможна ситуация, когда 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') зарегистрирован до любой попытки загрузки модуля (например, с помощью модуля preload).

При использовании 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).

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

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: конкатенация всех сертификатов центра сертификации (ЦС) в один файл, например cat ca1-cert.pem ca2-cert.pem > ca-cert.pem

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

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

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

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

• 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 — это хороший выбор только в тех случаях, когда есть способы безопасно поделиться ключом с каждым подключающимся устройством, поэтому он не заменяет инфраструктуру открытых ключей (PKI) в большинстве случаев использования TLS. Реализация 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.

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

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

Предотвращение атак с переустановкой сеанса, инициированных клиентом

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

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

• tls.CLIENT_RENEG_LIMIT <число> Указывает количество запросов переустановки. По умолчанию: 3.
• tls.CLIENT_RENEG_WINDOW <число> Указывает время окна переустановки в секундах. По умолчанию: 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 CLI для проверки того, что серверы возобновляют сеансы. Используйте опцию -reconnect для openssl s_client, например:

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 могут быть включены только путём добавления их полного имени в список шифров. Они не могут, например, быть включены или отключены, используя устаревший формат спецификации TLSv1.2 'EECDH' или '!EECDH'.

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

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

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

Старые клиенты, которые полагаются на небезопасные и устаревшие шифры RC4 или DES (например, Internet Explorer 6), не могут завершить процесс рукопожатия с помощью стандартной конфигурации. Если необходимо поддерживать таких клиентов, рекомендации по TLS рекомендации по 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, так как они могут быть более производительными на ограниченных системах, но они не включены по умолчанию, так как предлагают меньшую безопасность.

Коды ошибок сертификата 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': Несовпадение имени хоста.

Класс: tls.CryptoStream

Класс tls.CryptoStream представляет поток зашифрованных данных. Этот класс устарел и больше не должен использоваться.

cryptoStream.bytesWritten

Свойство cryptoStream.bytesWritten возвращает общее количество байтов, записанных в подлежащий сокет, включая байты, необходимые для реализации протокола TLS.

Класс: tls.SecurePair

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

Событие: 'secure'

Событие 'secure' генерируется объектом SecurePair после установления защищённого соединения.

Как и при проверке события сервера 'secureConnection', следует проверить pair.cleartext.authorized, чтобы убедиться, что используемый сертификат должным образом авторизован.

Класс: tls.Server

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

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

Событие: 'connection'

• socket <stream.Duplex>

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

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

Событие: 'keylog'

• line <Buffer> Строка ASCII-текста в формате NSS SSLKEYLOGFILE.
• 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);
}); copy

Событие: '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-представления первичного и сертификата издателя. Их можно использовать для получения идентификатора сертификата OCSP и URL-адреса конечной точки OCSP.

В качестве альтернативы, может быть вызвано callback(null, null), указывая, что ответа OCSP не было.

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

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

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

Запрос OCSP может не получиться issuer, если сертификат самоподписанный или издатель не входит в список корневых сертификатов. (Издатель может быть предоставлен через опцию 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);
}); copy

Событие: '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> Объект, содержащий любые из возможных свойств из tls.createSecureContext() options аргументов (например, key, cert, ca и т. д.), или объект TLS-контекста, созданный с помощью tls.createSecureContext() непосредственно.

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

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

server.address()

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

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

server.close([callback])

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

Метод server.close() останавливает сервер от приема новых подключений.

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

server.getTicketKeys()

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

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

См. Возобновление сеанса для получения дополнительной информации.

server.listen()

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

server.setSecureContext(options)

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

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

server.setTicketKeys(keys)

• keys <Буфер> | <Массив типов> | <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 асимметричен, TLSSockets должны знать, будут ли они работать как сервер или клиент. Если true, сокет TLS будет создан как сервер. По умолчанию: false.
  • server <net.Server> Экземпляр net.Server.
  • requestCert: Требовать аутентификацию удаленного узла, запрашивая сертификат. Клиенты всегда запрашивают сертификат сервера. Серверы (isServer имеет значение true) могут установить requestCert в true, чтобы запросить сертификат клиента.
  • rejectUnauthorized: См. tls.createServer()
  • ALPNProtocols: См. tls.createServer()
  • SNICallback: См. tls.createServer()
  • session <Buffer> Экземпляр Buffer, содержащий сеанс TLS.
  • requestOCSP <boolean> Если true, указывает, что расширение запроса состояния 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)); copy

Событие: 'OCSPResponse'

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

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

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

Событие: 'secureConnect'

Событие 'secureConnect' излучается после успешного завершения процесса рукопожатия для нового подключения. Обработчик события будет вызван независимо от того, был ли авторизован сертификат сервера. Клиент отвечает за проверку свойства tlsSocket.authorized, чтобы определить, был ли сертификат сервера подписан одним из указанных CA. Если 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...
  });
}); copy

tlsSocket.address()

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

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

tlsSocket.authorizationError

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

tlsSocket.authorized

• <boolean>

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

tlsSocket.disableRenegotiation()

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

tlsSocket.enableTrace()

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

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

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

См. документацию 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"
} copy

См. 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, если это сертификат удостоверяющего центра (ЦУ), false в противном случае.
• raw <Buffer> Данные сертификата X.509 в кодировке DER.
• subject <Object> Субъект сертификата, описанный в терминах страны (C), региона (ST), города (L), организации (O), подразделения организации (OU) и общего имени (CN). Общее имя обычно является именем DNS с сертификатами TLS. Пример: {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 <число> Размер ключа RSA в битах. Пример: 1024.
• exponent <строка> Экспонента RSA в шестнадцатеричном формате. Пример: '0x010001'.
• modulus <строка> Модуль RSA в шестнадцатеричном формате. Пример: 'B56CE45CB7...'.
• pubkey <Буфер> Открытый ключ.

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

• pubkey <Буфер> Открытый ключ.
• bits <число> Размер ключа в битах. Пример: 256.
• asn1Curve <строка> (Необязательно) Имя кривой в формате ASN.1 (OID). Известные кривые идентифицируются по OID. Хотя это необычно, кривая может быть идентифицирована по своим математическим свойствам, в этом случае у неё не будет OID. Пример: 'prime256v1'.
• nistCurve <строка> (Необязательно) Имя кривой 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 ... > } copy

tlsSocket.getPeerFinished()

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

Так как сообщения рукопожатия — это дайджесты всего рукопожатия (с 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()

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

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

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

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

См. документацию OpenSSL по SSL_get_version для дополнительной информации.

tlsSocket.getSession()

• <Буфер>

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

См. Возобновление сессии для дополнительной информации.

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

tlsSocket.getSharedSigalgs()

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

См. SSL_get_shared_sigalgs для дополнительной информации.

tlsSocket.getTLSTicket()

• <Буфер>

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

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

См. Возобновление сессии для дополнительной информации.

tlsSocket.getX509Certificate()

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

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

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

tlsSocket.isSessionReused()

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

См. Возобновление сессии для дополнительной информации.

tlsSocket.localAddress

• <строка>

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

tlsSocket.localPort

• <целое>

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

tlsSocket.remoteAddress

• <строка>

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

tlsSocket.remoteFamily

• <строка>

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

tlsSocket.remotePort

• <целое>

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

tlsSocket.renegotiate(options, callback)

• options <Объект>

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

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

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

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

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

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

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

tlsSocket.setMaxSendFragment(size)

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

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

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

tls.checkServerIdentity(hostname, cert)

• hostname <строка> Имя хоста или IP-адрес для проверки сертификата.
• cert <объект> Объект сертификата, представляющий сертификат удалённого узла.
• Возвращает: <ошибка> | <неопределено>

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

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

Эта функция предназначена для использования в сочетании с параметром checkServerIdentity, который может быть передан в tls.connect(), и поэтому работает с объектом сертификата 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 <Объект>

  • enableTrace: Смотрите tls.createServer()

  • host <строка> Хост, к которому должен подключиться клиент. По умолчанию: 'localhost'.

  • port <число> Порт, к которому должен подключиться клиент.

  • path <строка> Создаёт подключение к сокету Unix по указанному пути. Если этот параметр указан, host и port игнорируются.

  • socket <stream.Duplex> Устанавливает защищённое соединение на заданном сокете вместо создания нового сокета. Обычно это экземпляр net.Socket, но допускается любой Duplex поток. Если этот параметр указан, path, host и port игнорируются, за исключением проверки сертификатов. Обычно сокет уже подключен, когда он передаётся в tls.connect(), но он может быть подключён позже. Подключение/отключение/разрушение socket — ответственность пользователя; вызов tls.connect() не вызовет net.connect().

  • allowHalfOpen <логическое значение> Если установлено в false, сокет автоматически завершит запись, когда закончится чтение. Если установлен параметр socket, этот параметр не имеет эффекта. Смотрите параметр allowHalfOpen в net.Socket для получения подробностей. По умолчанию: false.

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

  • pskCallback <Функция>

    • подсказка: <строка> необязательное сообщение, отправляемое сервером, чтобы помочь клиенту решить, какой идентификатор использовать во время переговоров. Всегда null, если используется TLS 1.3.
    • Возвращает: <Объект> Объект в форме { psk: <Buffer|TypedArray|DataView>, identity: <string> } или null для остановки процесса переговоров. psk должен быть совместим с выбранным алгоритмом дайджеста. identity должен использовать кодировку UTF-8.

    При установлении TLS-PSK (предопределённые ключи) эта функция вызывается с необязательным идентификатором hint, предоставленным сервером, или null в случае TLS 1.3, где hint был удалён. Необходимо предоставить настраиваемую tls.checkServerIdentity() для соединения, так как по умолчанию будет попытка проверки имени хоста/IP сервера по сертификату, но это не применимо для PSK, так как сертификат отсутствует. Дополнительную информацию можно найти в RFC 4279.

  • ALPNProtocols: <строковый массив> | <Буферный массив> | <Массив типов данных> | <Массив DataView> | <Буфер> | <Тип данных> | <DataView> Массив строк, Buffer, TypedArray или DataView, или один Buffer, TypedArray или DataView, содержащий поддерживаемые протоколы ALPN. Buffer должны иметь формат [len][name][len][name]..., например, '\x08http/1.1\x08http/1.0', где байт len — длина следующего имени протокола. Передача массива обычно намного проще, например, ['http/1.1', 'http/1.0']. Протоколы в начале списка имеют больший приоритет, чем те, что в конце.

  • servername: <строка> Имя сервера для расширения TLS SNI (Server Name Indication). Это имя хоста, к которому происходит подключение, и должно быть именем хоста, а не IP-адресом. Может использоваться многоадресным сервером для выбора правильного сертификата для предоставления клиенту, см. параметр SNICallback в tls.createServer().

  • checkServerIdentity(servername, cert) <Функция> Функция обратного вызова, которая используется (вместо встроенной функции tls.checkServerIdentity()) для проверки имени хоста сервера (или предоставленного servername, если он явно задан) по сертификату. Должна возвращать <Ошибка>, если проверка завершится неудачно. Метод должен возвращать undefined, если servername и cert проверены.

  • session <Буфер> Экземпляр Buffer, содержащий сеанс TLS.

  • minDHSize <число> Минимальный размер параметра DH в битах для принятия подключения TLS. Когда сервер предлагает параметр DH с размером меньше minDHSize, подключение TLS уничтожается и генерируется ошибка. По умолчанию: 1024.

  • highWaterMark: <число> Соответствует параметру highWaterMark для потока чтения. По умолчанию: 16 * 1024.

  • secureContext: Объект контекста TLS, созданный с помощью tls.createSecureContext(). Если secureContext не предоставлен, он будет создан путём передачи всего объекта options в tls.createSecureContext().

  • onread <Объект> Если параметр socket отсутствует, входящие данные хранятся в единственном buffer и передаются в предоставленную callback при поступлении данных в сокет. В противном случае параметр игнорируется. Смотрите параметр onread в net.Socket для получения подробностей.

  • ...: tls.createSecureContext() параметры, которые используются, если параметр secureContext отсутствует, в противном случае они игнорируются.

  • ...: Любой параметр socket.connect(), который ещё не перечислен.

• callback <Функция>
• Возвращает: <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.
const tls = require('node:tls');
const fs = require('node:fs');

const options = {
  // Necessary only if the server requires client certificate authentication.
  key: fs.readFileSync('client-key.pem'),
  cert: fs.readFileSync('client-cert.pem'),

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

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

const socket = tls.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');
}); copy

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

• path <строка> Значение по умолчанию для options.path.
• options <Объект> См. tls.connect().
• callback <Функция> См. tls.connect().
• Возвращает: <tls.TLSSocket>

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

Если указан параметр пути, он будет иметь приоритет над аргументом пути.

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

• port <число> Значение по умолчанию для options.port.
• host <строка> Значение по умолчанию для options.host.
• options <Объект> См. tls.connect().
• callback <Функция> См. tls.connect().
• Возвращает: <tls.TLSSocket>

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

Если указан параметр порта или хоста, он будет иметь приоритет над любым аргументом порта или хоста.

tls.createSecureContext([options])

• options <Объект>

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

  • ALPNProtocols: <строковый массив> | <Буферный массив> | <Массив TypedArray> | <Массив DataView> | <Буфер> | <TypedArray> | <DataView> Массив строк, Buffer, TypedArray, или DataView, или один Buffer, TypedArray, или DataView, содержащий поддерживаемые протоколы ALPN. Buffer должны иметь формат [len][name][len][name]..., например, 0x05hello0x05world, где первый байт — длина следующего имени протокола. Передача массива обычно намного проще, например, ['hello', 'world']. (Протоколы должны быть упорядочены по приоритету.)

  • ALPNCallback: <Функция> Если установлено, это будет вызываться, когда клиент открывает соединение с помощью расширения ALPN. В качестве аргумента в обратный вызов будет передан объект, содержащий поля servername и protocols, соответственно содержащие имя сервера из расширения SNI (если таковое имеется) и массив строк имен протоколов ALPN. Обратный вызов должен вернуть одну из строк, перечисленных в protocols, которая будет возвращена клиенту в качестве выбранного протокола ALPN, или undefined, чтобы отклонить подключение с помощью фатального предупреждения. Если возвращена строка, не совпадающая с одним из протоколов ALPN клиента, будет выброшено исключение. Этот параметр не может использоваться с параметром ALPNProtocols, а установка обоих параметров вызовет ошибку.

  • clientCertEngine <строка> Имя модуля OpenSSL, который может предоставить сертификат клиента.

  • enableTrace <логическое значение> Если true, tls.TLSSocket.enableTrace() будет вызываться при новых подключениях. Отслеживание можно включить после установления защищённого соединения, но для отслеживания процесса настройки защищённого соединения этот параметр обязателен. По умолчанию: false.

  • handshakeTimeout <число> Прервать соединение, если рукопожатие SSL/TLS не завершится в течение указанного количества миллисекунд. Событие 'tlsClientError' генерируется на объекте tls.Server всякий раз, когда рукопожатие истекает. По умолчанию: 120000 (120 секунд).

  • rejectUnauthorized <логическое значение> Если не false, сервер будет отклонять любые подключения, которые не авторизованы предоставленным списком CA. Этот параметр имеет эффект только если requestCert равно true. По умолчанию: true.

  • requestCert <логическое значение> Если true сервер запросит сертификат у подключающихся клиентов и попытается проверить этот сертификат. По умолчанию: false.

  • sessionTimeout <число> Количество секунд, по истечении которых созданная сервером сессия TLS больше не будет возобновляемой. Подробнее см. Возобновление сессии. По умолчанию: 300.

  • SNICallback(servername, callback) <Функция> Функция, которая будет вызвана, если клиент поддерживает расширение SNI TLS. При вызове ей будут переданы два аргумента: servername и callback. callback — обратный вызов с обработкой ошибок, принимающий два необязательных аргумента: error и ctx. ctx, если предоставлен, является экземпляром SecureContext. tls.createSecureContext() можно использовать для получения надлежащего SecureContext. Если callback вызывается с ложным аргументом ctx, будет использоваться стандартный контекст безопасности сервера. Если SNICallback не был предоставлен, будет использоваться стандартный обратный вызов с высокоуровневым API (см. ниже).

  • ticketKeys: <Буфер> 48 байт криптографически сильных псевдослучайных данных. Подробнее см. Возобновление сессии.

  • pskCallback <Функция>

    • socket: <tls.TLSSocket> экземпляр серверного tls.TLSSocket для этого подключения.
    • identity: <строка> параметр идентификации, отправленный клиентом.
    • Возвращаемое значение: <Буфер> | <TypedArray> | <DataView> предварительно согласованный ключ, который должен быть буфером или null, чтобы остановить процесс переговоров. Возвращаемый PSK должен быть совместим с выбранным типом шифрования.

    При переговорах TLS-PSK (предварительно согласованных ключей) эта функция вызывается с идентификатором, предоставленным клиентом. Если возвращаемое значение null, процесс переговоров остановится, и клиенту будет отправлено сообщение "unknown_psk_identity". Если сервер хочет скрыть тот факт, что идентификатор PSK не был известен, обратный вызов должен предоставить некоторые случайные данные в качестве psk, чтобы подключение завершилось ошибкой "decrypt_error" до завершения переговоров. PSK-шифрование отключено по умолчанию, и для использования TLS-PSK необходимо явно указать набор шифрования с параметром ciphers. Дополнительную информацию можно найти в RFC 4279.

  • pskIdentityHint <строка> необязательный подсказка, которая отправляется клиенту, чтобы помочь в выборе идентификатора во время переговоров TLS-PSK. Будет проигнорирована в TLS 1.3. При ошибочной установке pskIdentityHint будет сгенерировано событие 'tlsClientError' с кодом 'ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED'.

  • ...: Любой параметр tls.createSecureContext() может быть предоставлен. Для серверов обычно требуются параметры идентификации (pfx, key/cert или pskCallback).

  • ...: Любой параметр net.createServer() может быть предоставлен.

• secureConnectionListener <Функция>
• Возвращаемое значение: <tls.Сервер>

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

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

Пример простого сервера эха:

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

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

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

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

const server = tls.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');
}); copy

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

tls.getCiphers()

• Возвращаемое значение: <массив строк>

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

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

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

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

tls.rootCertificates

• <string[]>

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

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

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