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

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

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

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

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

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

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

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

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

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

openssl genrsa -out ryans-key.pem 2048 copy

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

Командная строка 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: конкатенация всех сертификатов центра сертификации (CA) в один файл, например, 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 всегда используется (за исключением соединений только с предварительно распределёнными ключами).

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», например:

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 <Функция> Функция обратного вызова, не принимающая аргументов, которая должна быть вызвана для отправки или получения данных по защищенному соединению.

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

Событие: 'OCSPRequest'

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

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

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

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

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

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

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

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

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

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

Событие: 'resumeSession'

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

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

Обработчик события должен выполнить поиск в внешнем хранилище сохраненной sessionData данным обработчиком события 'newSession' по предоставленному идентификатору. Если найдено, вызовите 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 не выбрал протокол, tlsSocket.alpnProtocol равно false.

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

Событие: 'tlsClientError'

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

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

server.addContext(hostname, context)

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

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

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

server.address()

• Возвращает: <Объект>

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

server.close([callback])

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

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

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

server.getTicketKeys()

• Возвращает: <Buffer> Буфер размером 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's 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()

• Возвращает: <Объект>

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

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

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

tlsSocket.getCipher()

• Возвращает: <Объект>
  • name <строка> Имя OpenSSL для набора шифров.
  • standardName <строка> Имя IETF для набора шифров.
  • version <строка> Минимальная версия протокола 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()

• Возвращает: <Объект>

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

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

tlsSocket.getFinished()

• Возвращает: <Буфер> | <неопределено> Последнее сообщение 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 <логическое> Включить полную цепочку сертификатов, если true, иначе включить только сертификат клиента.
• Возвращает: <Объект> Объект сертификата.

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

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

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

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

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

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

Для ключей 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()

• Возвращает: <Буфер> | <неопределено> Последнее 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()

• Возвращает: <СертификатX509>

Возвращает сертификат удалённого узла в виде объекта <СертификатX509>.

Если сертификат отсутствует или сокет был уничтожен, возвращается 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()

• Возвращает: <СертификатX509>

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

Если локальный сертификат отсутствует или сокет был уничтожен, возвращается 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, сертификат сервера проверяется по списку предоставленных центров сертификации. Событие 'error' генерируется при ошибке проверки; err.code содержит код ошибки OpenSSL. По умолчанию: true.
  • requestCert

• callback <Функция> Если renegotiate() возвращает true, callback прикрепляется один раз к событию '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(), и поэтому работает с объектом сертификата. Для других целей используйте 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 <Функция>

    • подсказка: <строка> необязательное сообщение, отправляемое сервером, чтобы помочь клиенту решить, какую личность использовать во время согласования. Всегда используется при использовании 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> Массив строк, Buffers, TypedArrays или DataViews, или один Buffer, TypedArray, или DataView, содержащий поддерживаемые протоколы ALPN. Buffers должны иметь формат [len][name][len][name]..., например, '\x08http/1.1\x08http/1.0', где байт len — длина следующего имени протокола. Передача массива обычно намного проще, например, ['http/1.1', 'http/1.0']. Протоколы, стоящие в списке раньше, имеют больший приоритет, чем те, что позже.

  • servername: <строка> Имя сервера для расширения SNI (Server Name Indication) TLS. Это имя хоста, к которому устанавливается подключение, и должно быть именем хоста, а не 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.

В отличие от https API, 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 может содержать несколько связанных сертификатов CA в формате PEM. Сертификат клиента должен быть прослеживаемым до 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 <строка> | <Буфер> 'auto' или настраиваемые параметры Diffie-Hellman, необходимые для не-ECDHE совершенной прямой секретности. Если параметр отсутствует или некорректен, параметры будут проигнорированы, и шифры DHE не будут доступны. ECDHE-базируемая совершенная прямая секретность по-прежнему будет доступна.
  • ecdhCurve <строка> Строка, описывающая заданную кривую или список кривых, разделённый двоеточиями, или имена, для использования в соглашении об обмене ключами 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 <строка> Непрозрачный идентификатор, используемый серверами для обеспечения того, что состояние сеанса не разделяются между приложениями. Не используется клиентами.

• • 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 по умолчанию будет использовать общедоступный доверенный список сертификатов CA от 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(). Например, код:

<%CODE_BLOCK_810%>

может быть заменён на:

<%CODE_BLOCK_811%>

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

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

• options <Объект>

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

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

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

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

  • rejectUnauthorized <булево> Если не false, сервер отклонит любое подключение, которое не авторизовано с использованием списка предоставленных ЦС. Этот параметр действует только в том случае, если 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: <Buffer> 48 байт криптографически сильных псевдослучайных данных. Дополнительные сведения см. в разделе Возобновление сеанса.

  • pskCallback <Функция>

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

    При переговорах 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

• <строка[]>

Неизменяемый массив строк, представляющий корневые сертификаты (в формате 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.