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

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

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

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

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

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

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

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

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

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

openssl genrsa -out ryans-key.pem 2048 copy

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

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

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

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

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

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

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

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

Где:

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

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

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

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

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

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

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

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

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

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. При подключении клиента необходимо передать пользовательский checkServerIdentity, так как по умолчанию он будет отклоняться при отсутствии сертификата.

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

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

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

Она вызывается сначала на клиенте:

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

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

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

Возврат значения null останавливает процесс согласования и отправляет сообщение unknown_psk_identity alert другому участнику. Если сервер хочет скрыть тот факт, что идентификатор 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 copy

Прочитайте вывод отладки. Первое подключение должно указывать «New», например:

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

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

Событие: 'OCSPRequest'

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

• certificate <Buffer> Сертификат сервера
• issuer <Buffer> Сертификат издателя
• callback <Function> Обработчик, который должен быть вызван для предоставления результатов запроса OCSP.

Текущий сертификат сервера можно разобрать для получения URL OCSP и идентификатора сертификата; после получения ответа 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 к центру сертификации.
4. Сервер получает ответ 'OCSPResponse' от центра сертификации и отправляет его обратно клиенту через аргумент callback
5. Клиент проверяет ответ и либо уничтожает сокет, либо выполняет рукопожатие.

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

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

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

Событие: 'resumeSession'

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

• sessionId <Buffer> Идентификатор TLS-сессии
• callback <Function> Обработчик, вызываемый при восстановлении предыдущей сессии: callback([err[, sessionData]])
  • err <Error>
  • sessionData <Buffer>

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

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

Следующий пример иллюстрирует возобновление TLS-сессии:

const tlsSessionStore = {};
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data;
  cb();
});
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null);
}); copy

Событие: 'secureConnection'

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

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

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

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

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

Событие: 'tlsClientError'

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

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

server.addContext(hostname, context)

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

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

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

server.address()

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

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

server.close([callback])

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

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

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

server.getTicketKeys()

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

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

Дополнительную информацию см. в Возобновлении сеанса.

server.listen()

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

server.setSecureContext(options)

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

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

server.setTicketKeys(keys)

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

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

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

Дополнительную информацию см. в Возобновлении сеанса.

Класс: tls.TLSSocket

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

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

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

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

new tls.TLSSocket(socket[, options])

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

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

Событие: 'keylog'

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

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

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

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

Событие: 'OCSPResponse'

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

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

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

Событие: 'secureConnect'

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

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

Событие: 'session'

• session <Buffer>

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

На клиенте можно указать session в опцию session tls.connect() для возобновления подключения.

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

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

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

tlsSocket.address()

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

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

tlsSocket.authorizationError

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

tlsSocket.authorized

• <boolean>

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

tlsSocket.disableRenegotiation()

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

tlsSocket.enableTrace()

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

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

tlsSocket.encrypted

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

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

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

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

• context <Buffer> необязательно, передать контекст.

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

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

Пример

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

/*
 Example return value of keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
*/ copy

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

tlsSocket.getCertificate()

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

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

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

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

tlsSocket.getCipher()

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

Возвращает объект, содержащий информацию о согласованном наборе шифров.

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

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

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

tlsSocket.getEphemeralKeyInfo()

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

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

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

tlsSocket.getFinished()

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

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

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

tlsSocket.getPeerCertificate([detailed])

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

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

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

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

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

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

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

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

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

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

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

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

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

tlsSocket.getPeerFinished()

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

Поскольку сообщения 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, коллбэк добавляется один раз к событию 'secure'. Если renegotiate() возвращает false, callback будет вызван в следующем цикле с ошибкой, если tlsSocket не уничтожен, в противном случае callback не будет вызван вообще.

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

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

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

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

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

tlsSocket.setMaxSendFragment(size)

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

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

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

tls.checkServerIdentity(hostname, cert)

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

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

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

Данная функция предназначена для использования в сочетании с опцией checkServerIdentity, которая может быть передана в tls.connect(), и как таковая работает с объектом сертификата tls.connect(). Для других целей рассмотрите использование x509.checkHost() вместо этого.

Эту функцию можно переопределить, предоставив альтернативную функцию в качестве опции options.checkServerIdentity, которая передаётся в tls.connect(). Функция переопределения может вызывать tls.checkServerIdentity(), конечно, чтобы дополнить проверки дополнительной проверкой.

Эта функция вызывается только в том случае, если сертификат прошёл все остальные проверки, такие как проверка на выдачу от доверенного ЦС (options.ca).

В более ранних версиях Node.js сертификаты для заданного hostname принимались неправильно, если присутствовало соответствующее альтернативное имя субъекта uniformResourceIdentifier (см. CVE-2021-44531). Приложения, которые хотят принять uniformResourceIdentifier альтернативные имена субъекта, могут использовать пользовательскую функцию options.checkServerIdentity, реализующую желаемое поведение.

tls.connect(options[, callback])

• options <Объект>
  • enableTrace: См. tls.createServer()
  • host <строка> Хост, к которому должен подключиться клиент. По умолчанию: 'localhost'.
  • port <число> Порт, к которому должен подключиться клиент.
  • path <строка> Создаёт подключение к сокету Unix по указанному пути. Если этот параметр указан, host и port игнорируются.
  • socket <stream.Duplex> Устанавливает защищённое соединение на данном сокете вместо создания нового сокета. Обычно это экземпляр net.Socket, но допускается любой Duplex поток. Если этот параметр указан, path, host и port игнорируются, за исключением проверки сертификатов. Обычно сокет уже подключён, когда он передаётся в tls.connect(), но он может быть подключён позже. Ответственность пользователя за подключение/отключение/разрушение socket; вызов tls.connect() не вызовет net.connect().
  • allowHalfOpen <логическое> Если установлено в значение false, то сокет автоматически завершит запись, когда завершится чтение. Если установлен параметр socket, этот параметр не имеет эффекта. Подробнее см. параметр allowHalfOpen net.Socket. По умолчанию: false.
  • rejectUnauthorized <логическое> Если не false, то серверный сертификат проверяется по списку предоставленных удостоверяющих центров. Если проверка не пройдена, генерируется событие 'error'; err.code содержит код ошибки OpenSSL. По умолчанию: true.
  • pskCallback <Функция> Для TLS-PSK-переговоров см. Предварительно объявленные ключи.
  • ALPNProtocols: <массив строк> | <массив буферов> | <массив типов данных> | <массив данных> | <буфер> | <тип данных> | <данные> Массив строк, Buffer, TypedArray или DataView, или один Buffer, TypedArray или DataView, содержащий поддерживаемые протоколы ALPN. Buffer должны иметь формат [len][name][len][name]..., например, '\x08http/1.1\x08http/1.0', где len — длина следующего имени протокола. Передача массива обычно намного проще, например, ['http/1.1', 'http/1.0']. Протоколы в начале списка имеют более высокий приоритет, чем те, что в конце.
  • servername: <строка> Имя сервера для расширения TLS SNI (Server Name Indication). Это имя хоста, к которому происходит подключение, и должно быть именем хоста, а не IP-адресом. Может использоваться многохостовым сервером для выбора правильного сертификата для представления клиенту, см. параметр SNICallback в tls.createServer().
  • checkServerIdentity(servername, cert) <Функция> Функция обратного вызова, которая используется (вместо встроенной функции tls.checkServerIdentity()) при проверке имени хоста сервера (или предоставленного servername, если он явно задан) по сертификату. Должна возвращать <ошибку>, если проверка не пройдена. Метод должен возвращать undefined, если servername и cert проверены.
  • session <буфер> Экземпляр Buffer, содержащий TLS-сессию.
  • minDHSize <число> Минимальный размер параметра DH в битах для принятия TLS-соединения. Если сервер предлагает параметр DH с размером меньше, чем minDHSize, TLS-соединение разрушается и возникает ошибка. По умолчанию: 1024.
  • highWaterMark: <число> Совместимо с параметром потока чтения highWaterMark. По умолчанию: 16 * 1024.
  • secureContext: Объект контекста TLS, созданный с помощью tls.createSecureContext(). Если secureContext не предоставлен, он будет создан путём передачи всего объекта options в tls.createSecureContext().
  • onread <Объект> Если параметр socket отсутствует, входящие данные хранятся в одном buffer и передаются в предоставленную функцию callback при поступлении данных на сокет; в противном случае этот параметр игнорируется. Подробности см. в параметре onread net.Socket.
  • ...: tls.createSecureContext() параметры, которые используются, если параметр secureContext отсутствует, в противном случае они игнорируются.
  • ...: Любой параметр socket.connect(), который ещё не указан.
• callback <Функция>
• Возвращает: <tls.TLSSocket>

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

Функция tls.connect() возвращает объект tls.TLSSocket.

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

Ниже приведён пример клиента для сервера эха из примера tls.createServer():

// Assumes an echo server that is listening on port 8000.
const tls = require('node:tls');
const fs = require('node:fs');

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

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

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

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

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

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

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

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

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

• port <number> Значение по умолчанию для options.port.
• host <string> Значение по умолчанию для options.host.
• options <Object> См. tls.connect().
• callback <Function> См. tls.connect().
• Возвращает: <tls.TLSSocket>

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

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

tls.createSecureContext([options])

• options <Object>

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

• • sessionIdContext <string> Непрозрачный идентификатор, используемый серверами для обеспечения того, чтобы состояние сеанса не разделялось между приложениями. Не используется клиентами.
  • ticketKeys: <Buffer> 48 байтов криптографически сильных псевдослучайных данных. Дополнительную информацию см. в разделе Возобновление сеанса.
  • sessionTimeout <number> Количество секунд, по истечении которых созданный сервером сеанс TLS больше не будет возобновляемым. Дополнительную информацию см. в разделе Возобновление сеанса. По умолчанию: 300.

tls.createServer() устанавливает значение по умолчанию параметра honorCipherOrder в true, другие API, создающие защищенные контексты, оставляют его не установленным.

tls.createServer() использует значение по умолчанию параметра sessionIdContext, которое представляет собой усечённое 128-битное значение хеша SHA1, сгенерированное из process.argv. Другие API, создающие защищенные контексты, не имеют значения по умолчанию.

Метод tls.createSecureContext() создаёт объект SecureContext. Он может использоваться в качестве аргумента для нескольких API tls, таких как server.addContext(), но не имеет публичных методов. Конструктор tls.Server и метод tls.createServer() не поддерживают параметр secureContext.

Ключ требуется для шифров, использующих сертификаты. Его можно предоставить с помощью key или pfx.

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

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

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

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

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

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

• options <Объект>
  • ALPNProtocols: <строка[]> | <Буфер[]> | <TypedArray[]> | <DataView[]> | <Буфер> | <TypedArray> | <DataView> Массив строк, Buffer, TypedArray, или DataView, или один Buffer, TypedArray или DataView, содержащий поддерживаемые протоколы ALPN. Buffer должны иметь формат [len][name][len][name]..., например, 0x05hello0x05world, где первый байт — длина следующего имени протокола. Передача массива обычно намного проще, например, ['hello', 'world']. (Протоколы должны быть упорядочены по приоритету.)
  • ALPNCallback: <Функция> Если установлено, эта функция будет вызываться, когда клиент открывает соединение с использованием расширения ALPN. В качестве аргумента обратной функции передаётся объект, содержащий поля servername и protocols, соответственно содержащие имя сервера из расширения SNI (если оно есть) и массив строк имён протоколов ALPN. Обратная функция должна вернуть одну из строк, указанных в protocols, которая будет возвращена клиенту в качестве выбранного протокола ALPN, или undefined, чтобы отклонить соединение с помощью критической тревоги. Если возвращается строка, которая не соответствует одному из протоколов ALPN клиента, будет выброшено исключение. Эта опция не может использоваться с опцией ALPNProtocols, а установка обеих опций приведёт к ошибке.
  • clientCertEngine <строка> Имя OpenSSL-модуля, который может предоставить сертификат клиента.
  • enableTrace <логическое> Если true, tls.TLSSocket.enableTrace() будет вызвана для новых соединений. Отслеживание может быть включено после установления защищённого соединения, но эта опция необходима для отслеживания процесса настройки защищённого соединения. По умолчанию: false.
  • handshakeTimeout <число> Прервать соединение, если рукопожатие SSL/TLS не завершится в течение указанного количества миллисекунд. Событие 'tlsClientError' генерируется для объекта tls.Server при истечении срока действия рукопожатия. По умолчанию: 120000 (120 секунд).
  • rejectUnauthorized <логическое> Если не false, сервер отклонит любое соединение, которое не авторизовано с помощью предоставленного списка центров сертификации. Эта опция действует только если requestCert равно true. По умолчанию: true.
  • requestCert <логическое> Если true сервер запросит сертификат от подключённых клиентов и попытается проверить этот сертификат. По умолчанию: false.
  • sessionTimeout <число> Количество секунд, по истечении которых созданная сервером сессия TLS больше не будет возобновляемой. Дополнительная информация в разделе Возобновление сессии.
  • SNICallback(servername, callback) <Функция> Функция, которая будет вызвана, если клиент поддерживает расширение SNI TLS. При вызове будут переданы два аргумента: servername и callback. callback — обратная функция, принимающая два необязательных аргумента: error и ctx. ctx, если предоставлена, — экземпляр SecureContext. tls.createSecureContext() можно использовать для получения соответствующего SecureContext. Если callback вызывается с ложным аргументом ctx, будет использоваться стандартный контекст безопасности сервера. Если SNICallback не указана, будет использоваться стандартная обратная функция с высокоуровневым API (см. ниже).
  • ticketKeys: <Буфер> 48 байт криптографически стойких псевдослучайных данных. Подробнее в разделе Возобновление сессии.
  • pskCallback <Функция> Для переговоров TLS-PSK, см. Предварительно заданные ключи.
  • 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.DEFAULT_CIPHERS

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