TLS (SSL)

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Исходный код: lib/tls.js

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

ESM

import tls from 'node:tls'

CJS

const tls = require('node:tls')

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

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

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

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

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

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

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

Концепции TLS/SSL

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

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

openssl genrsa -out ryans-key.pem 2048

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

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

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

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

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

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

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

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

Где:

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

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

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

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

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

• ECDHE: Эпизодическая версия протокола согласования ключей Diffie-Hellman на эллиптических кривых.
• DHE: Эпизодическая версия протокола согласования ключей Diffie-Hellman.

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

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

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

ALPN и SNI

ALPN (Application-Layer Protocol Negotiation Extension) и SNI (Server Name Indication) — это расширения рукопожатия 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. При подключении клиента следует передать пользовательскую функцию 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. К сожалению, повторное согласование сеанса требует непропорционально большого количества ресурсов на стороне сервера, что делает его потенциальным вектором для атак типа «отказ в обслуживании».

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

Просмотрите вывод отладки. Первое соединение должно содержать "New", например:

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

Последующие соединения должны содержать "Reused", например:

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

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

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

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

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

т.е. список defaultCoreCipherList устанавливается во время компиляции, а defaultCipherList — во время выполнения.

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

// Удаление устаревших шифров CBC и шифров на основе обмена ключами RSA, поскольку они не обеспечивают прямую секретность
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'

Параметр по умолчанию также можно заменить для каждого клиента или сервера, используя параметр 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 могут предложить совместимый набор шифров. Для получения дополнительной информации о формате см. документацию OpenSSL по формату списка шифров.

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

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

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

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

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

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

Чтобы изменить уровень безопасности в вашем приложении Node.js, вы можете включить @SECLEVEL=X в строку шифра, где X — желаемый уровень безопасности. Например, чтобы установить уровень безопасности на 0, используя список шифров OpenSSL по умолчанию, вы можете использовать:

ESM

import { createServer, connect } from 'node:tls'
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Client connected with protocol:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

CJS

const { createServer, connect } = require('node:tls')
const port = 443

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=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': Несоответствие имени хоста.

Класс: tls.CryptoStream

Добавлено в: v0.3.4

Устарело с: v0.11.3

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело: Используйте tls.TLSSocket вместо этого.

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

cryptoStream.bytesWritten

Добавлено в: v0.3.4

Устарело с: v0.11.3

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

Класс: tls.SecurePair

Добавлено в: v0.3.2

Устарело с: v0.11.3

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело: Используйте tls.TLSSocket вместо этого.

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

Событие: 'secure'

Добавлено в: v0.3.2

Устарело с: v0.11.3

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

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

Класс: tls.Server

Добавлено в: v0.3.2

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

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

Событие: 'connection'

Добавлено в: v0.3.2

• socket <stream.Duplex>

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

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

Событие: 'keylog'

Добавлено в: v12.3.0, v10.20.0

• 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 // Логировать ключи только для определенного IP
  logFile.write(line)
})

Событие: 'newSession'

[История]

Версия	Изменения
v0.11.12	Теперь поддерживается аргумент callback.
v0.9.2	Добавлено в: v0.9.2

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

Обратный вызов прослушивателя получает три аргумента при вызове:

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

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

Событие: 'OCSPRequest'

Добавлено в: v0.11.13

Событие '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 выглядит следующим образом:

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

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

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

Событие: 'resumeSession'

Добавлено в: v0.9.2

Событие '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)
})

Событие: 'secureConnection'

Добавлено в: v0.3.2

Событие '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'

Добавлено в: v6.0.0

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

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

server.addContext(hostname, context)

Добавлено в: v0.5.3

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

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

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

server.address()

Добавлено в: v0.6.0

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

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

server.close([callback])

Добавлено в: v0.3.2

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

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

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

server.getTicketKeys()

Добавлено в: v3.0.0

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

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

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

server.listen()

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

server.setSecureContext(options)

Добавлено в: v11.0.0

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

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

server.setTicketKeys(keys)

Добавлено в: v3.0.0

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

Устанавливает ключи билетов сеанса.

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

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

Класс: tls.TLSSocket

Добавлено в: v0.11.4

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

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

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

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

new tls.TLSSocket(socket[, options])

[История]

Версия	Изменения
v12.2.0	Теперь поддерживается параметр enableTrace.
v5.0.0	Теперь поддерживаются параметры ALPN.
v0.11.4	Добавлено в: v0.11.4

• 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 будет добавлено к client hello, и событие 'OCSPResponse' будет отправлено в сокет перед установлением защищенного соединения.
  • secureContext: Объект контекста TLS, созданный с помощью tls.createSecureContext(). Если secureContext не предоставлен, он будет создан путем передачи всего объекта options в tls.createSecureContext().
  • ...: параметры tls.createSecureContext(), которые используются, если параметр secureContext отсутствует. В противном случае они игнорируются.

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

Событие: 'keylog'

Добавлено в: v12.3.0, v10.20.0

• 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))

Событие: 'OCSPResponse'

Добавлено в: v0.11.13

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

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

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

Событие: 'secureConnect'

Добавлено в: v0.11.4

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

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

Событие: 'session'

Добавлено в: v11.10.0

• 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 => {
  // Сеанс может быть использован немедленно или позже.
  tls.connect({
    session: session,
    // Другие параметры подключения...
  })
})

tlsSocket.address()

[История]

Версия	Изменения
v18.4.0	Свойство family теперь возвращает строку вместо числа.
v18.0.0	Свойство family теперь возвращает число вместо строки.
v0.11.4	Добавлено в: v0.11.4

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

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

tlsSocket.authorizationError

Добавлено в: v0.11.4

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

tlsSocket.authorized

Добавлено в: v0.11.4

• <boolean>

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

tlsSocket.disableRenegotiation()

Добавлено в: v8.4.0

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

tlsSocket.enableTrace()

Добавлено в: v12.2.0

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

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

tlsSocket.encrypted

Добавлено в: v0.11.4

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

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

Добавлено в: v13.10.0, v12.17.0

• length <number> количество байтов для извлечения из материала ключей
• label <string> метка, специфичная для приложения, обычно это будет значение из реестра меток экспортера IANA.
• context <Buffer> Необязательно указать контекст.
• Возвращает: <Buffer> запрашиваемые байты материала ключей

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

Пример

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

/*
 Пример возвращаемого значения 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>
*/

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

tlsSocket.getCertificate()

Добавлено в: v11.2.0

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

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

См. tls.TLSSocket.getPeerCertificate() для примера структуры сертификата.

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

tlsSocket.getCipher()

[История]

Версия	Изменения
v13.4.0, v12.16.0	Возвращает имя шифра IETF как standardName.
v12.0.0	Возвращает минимальную версию шифра, а не фиксированную строку ('TLSv1/SSLv3').
v0.11.4	Добавлено в: v0.11.4

• Возвращает: <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"
}

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

tlsSocket.getEphemeralKeyInfo()

Добавлено в: v5.0.0

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

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

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

tlsSocket.getFinished()

Добавлено в: v9.9.0

• Возвращает: <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])

Добавлено в: v0.11.4

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

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

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

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

[История]

Версия	Изменения
v19.1.0, v18.13.0	Добавлено свойство "ca".
v17.2.0, v16.14.0	Добавлено fingerprint512.
v11.4.0	Поддержка информации об открытом ключе эллиптической кривой.

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

• ca <boolean> true, если Центр сертификации (ЦС), false в противном случае.
• raw <Buffer> Закодированные в DER данные сертификата X.509.
• 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 <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 ... > }

tlsSocket.getPeerFinished()

Добавлено в: v9.9.0

• Возвращает: <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()

Добавлено в: v15.9.0

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

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

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

tlsSocket.getProtocol()

Добавлено в: v5.7.0

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

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

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

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

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

tlsSocket.getSession()

Добавлено в: v0.11.4

• <Buffer>

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

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

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

tlsSocket.getSharedSigalgs()

Добавлено в: v12.11.0

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

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

tlsSocket.getTLSTicket()

Добавлено в: v0.11.4

• <Buffer>

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

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

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

tlsSocket.getX509Certificate()

Добавлено в: v15.9.0

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

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

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

tlsSocket.isSessionReused()

Добавлено в: v0.5.6

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

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

tlsSocket.localAddress

Добавлено в: v0.11.4

• <string>

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

tlsSocket.localPort

Добавлено в: v0.11.4

• <integer>

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

tlsSocket.remoteAddress

Добавлено в: v0.11.4

• <string>

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

tlsSocket.remoteFamily

Добавлено в: v0.11.4

• <строка>

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

tlsSocket.remotePort

Добавлено в: v0.11.4

• <целое число>

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

tlsSocket.renegotiate(options, callback)

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.11.8	Добавлено в: v0.11.8

• options <Объект>

  • rejectUnauthorized <булево> Если не false, сертификат сервера проверяется на соответствие списку предоставленных ЦС. Событие '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.setKeyCert(context)

Добавлено в: v22.5.0, v20.17.0

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

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

tlsSocket.setMaxSendFragment(size)

Добавлено в: v0.11.11

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

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

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

tls.checkServerIdentity(hostname, cert)

[История]

Версия	Изменения
v17.3.1, v16.13.2, v14.18.3, v12.22.9	Поддержка альтернативных имен субъекта uniformResourceIdentifier отключена в ответ на CVE-2021-44531.
v0.8.4	Добавлено в: v0.8.4

• 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])

[История]

Версия	Изменения
v15.1.0, v14.18.0	Добавлен параметр onread.
v14.1.0, v13.14.0	Теперь принимается параметр highWaterMark.
v13.6.0, v12.16.0	Теперь поддерживается параметр pskCallback.
v12.9.0	Поддержка параметра allowHalfOpen.
v12.4.0	Теперь поддерживается параметр hints.
v12.2.0	Теперь поддерживается параметр enableTrace.
v11.8.0, v10.16.0	Теперь поддерживается параметр timeout.
v8.0.0	Теперь поддерживается параметр lookup.
v8.0.0	Параметр ALPNProtocols теперь может быть TypedArray или DataView.
v5.0.0	Теперь поддерживаются параметры ALPN.
v5.3.0, v4.7.0	Теперь поддерживается параметр secureContext.
v0.11.3	Добавлено в: v0.11.3

• 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> Массив строк, 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: <string> Имя сервера для расширения SNI (Server Name Indication) TLS. Это имя хоста, к которому осуществляется подключение, и оно должно быть именем хоста, а не IP-адресом. Оно может использоваться многодоменным сервером для выбора правильного сертификата для предоставления клиенту, см. параметр SNICallback для tls.createServer().
  • checkServerIdentity(servername, cert) <Function> Функция обратного вызова, которая используется (вместо встроенной функции tls.checkServerIdentity()) при проверке имени хоста сервера (или предоставленного servername, если он явно установлен) на соответствие сертификату. Она должна возвращать <Error>, если проверка завершается неудачей. Метод должен возвращать undefined, если servername и cert проверены.
  • session <Buffer> Экземпляр Buffer, содержащий сеанс TLS.
  • minDHSize <number> Минимальный размер параметра DH в битах для принятия TLS-соединения. Когда сервер предлагает параметр DH размером меньше, чем minDHSize, TLS-соединение разрывается, и возникает ошибка. По умолчанию: 1024.
  • highWaterMark: <number> Соответствует параметру highWaterMark потока чтения. По умолчанию: 16 * 1024.
  • secureContext: Объект контекста TLS, созданный с помощью tls.createSecureContext(). Если secureContext не предоставлен, он будет создан путем передачи всего объекта options в tls.createSecureContext().
  • onread <Object> Если параметр socket отсутствует, входящие данные хранятся в одном buffer и передаются в предоставленный callback, когда данные поступают в сокет; в противном случае параметр игнорируется. Подробнее см. параметр onread для net.Socket.
  • ...: параметры tls.createSecureContext(), которые используются, если параметр secureContext отсутствует; в противном случае они игнорируются.
  • ...: Любой параметр socket.connect(), который еще не указан.

• callback <Function>

• Возвращает: <tls.TLSSocket>

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

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

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

Следующий пример демонстрирует клиента для примера сервера эхо из tls.createServer():

ESM

// Предполагается, что сервер эхо прослушивает порт 8000.
import { connect } from 'node:tls'
import { readFileSync } from 'node:fs'
import { stdin } from 'node:process'

const options = {
  // Необходимо только в том случае, если сервер требует аутентификацию клиентского сертификата.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Необходимо только в том случае, если сервер использует самоподписанный сертификат.
  ca: [readFileSync('server-cert.pem')],

  // Необходимо только в том случае, если сертификат сервера не для "localhost".
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('client connected', socket.authorized ? 'authorized' : 'unauthorized')
  stdin.pipe(socket)
  stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('server ends connection')
})

CJS

// Предполагается, что сервер эхо прослушивает порт 8000.
const { connect } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  // Необходимо только в том случае, если сервер требует аутентификацию клиентского сертификата.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Необходимо только в том случае, если сервер использует самоподписанный сертификат.
  ca: [readFileSync('server-cert.pem')],

  // Необходимо только в том случае, если сертификат сервера не для "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

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

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

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

Добавлено в: v0.11.3

• 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])

Добавлено в: v0.11.3

• 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])

[История]

Версия	Изменения
v22.9.0, v20.18.0	Добавлен параметр allowPartialTrustChain.
v22.4.0, v20.16.0	Параметры clientCertEngine, privateKeyEngine и privateKeyIdentifier зависят от поддержки пользовательских механизмов в OpenSSL, которая устарела в OpenSSL 3.
v19.8.0, v18.16.0	Параметр dhparam теперь может быть установлен в 'auto' для включения DHE с соответствующими известными параметрами.
v12.12.0	Добавлены параметры privateKeyIdentifier и privateKeyEngine для получения закрытого ключа из механизма OpenSSL.
v12.11.0	Добавлен параметр sigalgs для переопределения поддерживаемых алгоритмов подписи.
v12.0.0	Добавлена поддержка TLSv1.3.
v11.5.0	Параметр ca: теперь поддерживает BEGIN TRUSTED CERTIFICATE.
v11.4.0, v10.16.0	minVersion и maxVersion могут использоваться для ограничения разрешенных версий протокола TLS.
v10.0.0	ecdhCurve больше нельзя установить в false из-за изменений в OpenSSL.
v9.3.0	Параметр options теперь может включать clientCertEngine.
v9.0.0	Параметр ecdhCurve теперь может быть несколькими именами кривых, разделенными двоеточием, или 'auto'.
v7.3.0	Если параметр key является массивом, отдельные записи больше не нуждаются в свойстве passphrase. Записи Array теперь могут быть просто строками или Buffer.
v5.2.0	Параметр ca теперь может быть одной строкой, содержащей несколько сертификатов CA.
v0.11.13	Добавлено в: v0.11.13

• options <Object>
  • allowPartialTrustChain <boolean> Рассматривать промежуточные (не самоподписанные) сертификаты в списке доверенных сертификатов CA как доверенные.
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> Дополнительно переопределяет доверенные сертификаты CA. По умолчанию доверяет известным ЦС, отобранным Mozilla. ЦС Mozilla полностью заменяются, когда ЦС явно указаны с помощью этого параметра. Значение может быть строкой или Buffer, или Array строк и/или Buffer. Любая строка или Buffer может содержать несколько объединенных вместе PEM-сертификатов ЦС. Сертификат узла должен быть цепочкой к ЦС, которому доверяет сервер, чтобы соединение было аутентифицировано. При использовании сертификатов, которые не являются цепочкой к известному ЦС, ЦС сертификата должен быть явно указан как доверенный, иначе соединение не будет аутентифицировано. Если узел использует сертификат, который не соответствует или не является цепочкой к одному из ЦС по умолчанию, используйте параметр ca, чтобы предоставить сертификат ЦС, которому может соответствовать или к которому может быть цепочкой сертификат узла. Для самоподписанных сертификатов сертификат является его собственным ЦС и должен быть предоставлен. Для сертификатов с кодировкой PEM поддерживаются типы "TRUSTED CERTIFICATE", "X509 CERTIFICATE" и "CERTIFICATE". См. также tls.rootCertificates.
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> Цепочки сертификатов в формате PEM. Одна цепочка сертификатов должна быть предоставлена для каждого закрытого ключа. Каждая цепочка сертификатов должна состоять из сертификата в формате PEM для предоставленного закрытого key, за которым следуют промежуточные сертификаты (если таковые имеются) в порядке следования и без корневого ЦС (корневой ЦС должен быть заранее известен узлу, см. 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' или пользовательские параметры Diffie-Hellman, необходимые для не-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() использует 128-битное усеченное хэш-значение SHA1, сгенерированное из process.argv, в качестве значения параметра sessionIdContext по умолчанию, другие 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])

[История]

Версия	Изменения
v5.0.0	Теперь поддерживаются параметры ALPN.
v0.11.3	Устарело начиная с версии: v0.11.3
v0.3.2	Добавлено в: v0.3.2

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело: Используйте tls.TLSSocket вместо этого.

• 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 будет добавлено к client hello, и событие '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)

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

secureSocket = tls.TLSSocket(socket, options)

где secureSocket имеет тот же API, что и pair.cleartext.

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

[История]

Версия	Изменения
v22.4.0, v20.16.0	Опция clientCertEngine зависит от поддержки пользовательского механизма в OpenSSL, которая устарела в OpenSSL 3.
v19.0.0	Если установлен ALPNProtocols, входящие соединения, отправляющие расширение ALPN без поддерживаемых протоколов, завершаются с фатальным предупреждением no_application_protocol.
v20.4.0, v18.19.0	Параметр options теперь может включать ALPNCallback.
v12.3.0	Параметр options теперь поддерживает опции net.createServer().
v9.3.0	Параметр options теперь может включать clientCertEngine.
v8.0.0	Опция ALPNProtocols теперь может быть TypedArray или DataView.
v5.0.0	Теперь поддерживаются опции ALPN.
v0.3.2	Добавлено в: v0.3.2

• options <Object>

  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Массив строк, Buffer-ов, TypedArray-ов или DataView-ов, или единственный Buffer, TypedArray или DataView, содержащий поддерживаемые протоколы ALPN. Buffer-ы должны иметь формат [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()](/ru/api/tls#tlssocketenabletrace) будет вызываться для новых соединений. Трассировку можно включить после установления защищенного соединения, но этот параметр должен использоваться для трассировки настройки защищенного соединения. По умолчанию: false.
  • handshakeTimeout <number> Прервать соединение, если рукопожатие SSL/TLS не завершится за указанное количество миллисекунд. Событие 'tlsClientError' генерируется в объекте tls.Server всякий раз, когда происходит тайм-аут рукопожатия. По умолчанию: 120000 (120 секунд).
  • rejectUnauthorized <boolean> Если не false, сервер отклонит любое соединение, которое не авторизовано с предоставленным списком ЦС. Этот параметр имеет эффект только в том случае, если requestCert имеет значение true. По умолчанию: true.
  • requestCert <boolean> Если true, сервер запросит сертификат у подключающихся клиентов и попытается проверить этот сертификат. По умолчанию: false.
  • sessionTimeout <number> Количество секунд, после которого сеанс TLS, созданный сервером, больше не будет возобновляем. Для получения дополнительной информации см. Возобновление сеанса. По умолчанию: 300.
  • SNICallback(servername, callback) <Function> Функция, которая будет вызываться, если клиент поддерживает расширение SNI TLS. При вызове будут переданы два аргумента: servername и callback. callback — это функция обратного вызова с ошибкой вначале, которая принимает два необязательных аргумента: error и ctx. ctx, если предоставлен, представляет собой экземпляр SecureContext. tls.createSecureContext() может использоваться для получения подходящего SecureContext. Если callback вызывается с ложным аргументом ctx, будет использоваться контекст безопасности по умолчанию сервера. Если SNICallback не был предоставлен, будет использоваться функция обратного вызова по умолчанию с высокоуровневым API (см. ниже).
  • 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.

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

ESM

import { createServer } from 'node:tls'
import { readFileSync } from 'node:fs'

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

  // Это необходимо только при использовании проверки подлинности сертификата клиента.
  requestCert: true,

  // Это необходимо только в том случае, если клиент использует самоподписанный сертификат.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('сервер подключен', socket.authorized ? 'авторизован' : 'не авторизован')
  socket.write('welcome!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('сервер привязан')
})

CJS

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

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

  // Это необходимо только при использовании проверки подлинности сертификата клиента.
  requestCert: true,

  // Это необходимо только в том случае, если клиент использует самоподписанный сертификат.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('сервер подключен', socket.authorized ? 'авторизован' : 'не авторизован')
  socket.write('welcome!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('сервер привязан')
})

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

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

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

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

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

tls.getCiphers()

Добавлено в: v0.10.2

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

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

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

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

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

tls.rootCertificates

Добавлено в: v12.3.0

• <string[]>

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

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

tls.DEFAULT_ECDH_CURVE

[История]

Версия	Изменения
v10.0.0	Значение по умолчанию изменено на 'auto'.
v0.11.13	Добавлено в: v0.11.13

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

tls.DEFAULT_MAX_VERSION

Добавлено в: v11.4.0

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

tls.DEFAULT_MIN_VERSION

Добавлено в: v11.4.0

• <строка> Значение по умолчанию параметра 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

Добавлено в: v19.8.0, v18.16.0

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