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

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 для создания 2048-битного закрытого ключа RSA:

openssl genrsa -out ryans-key.pem 2048 copy

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

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

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 (за исключением подключений, использующих только PSK).

ALPN и SNI

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Поддержка возобновления сеанса с использованием билетов становится всё более распространённой в веб-браузерах при выполнении HTTPS-запросов.

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

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

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

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

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

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

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

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

openssl s_client -connect localhost:443 -reconnect 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 может быть указан совместимый набор шифров. Подробнее о формате см. в документации 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, но не получает события, в отличие от сокета, созданного в результате события 'connection' net.Server. Обычно пользователям не требуется обращаться к этому событию.

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

Событие: 'keylog'

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

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

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

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' });
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...')
    return; // Only log keys for a particular IP
  logFile.write(line);
}); copy

Событие: 'newSession'

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

При вызове обработчику события передаются три аргумента:

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

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

Событие: 'OCSPRequest'

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

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

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

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

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

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

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

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

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

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

Событие: 'resumeSession'

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

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

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

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

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

const tlsSessionStore = {};
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data;
  cb();
});
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null);
}); 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> Объект с любыми возможными свойствами из аргументов options метода tls.createSecureContext() (например, key, cert, ca и т. д.) либо объект контекста TLS, созданный непосредственно с помощью tls.createSecureContext().

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

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

server.address()

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

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

server.close([callback])

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

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

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

server.getTicketKeys()

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

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

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

server.listen()

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

server.setSecureContext(options)

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

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

server.setTicketKeys(keys)

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

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

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

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

Класс: tls.TLSSocket

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

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

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

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

new tls.TLSSocket(socket[, options])

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

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

Событие: 'keylog'

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

Событие 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' генерируется, если при создании tls.TLSSocket был задан параметр requestOCSP и получен ответ OCSP. При вызове обработчику события передаётся один аргумент:

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

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

Событие: 'secureConnect'

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

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

Событие: 'session'

• session <Buffer>

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

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

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

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

tlsSocket.once('session', (session) => {
  // The session can be used immediately or later.
  tls.connect({
    session: session,
    // Other connect options...
  });
}); 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, если сертификат удалённой стороны подписан одним из центров сертификации, указанных при создании экземпляра tls.TLSSocket; в противном случае оно имеет значение false.

tlsSocket.disableRenegotiation()

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

tlsSocket.enableTrace()

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

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

tlsSocket.encrypted

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

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

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

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

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

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

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

Пример

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

/*
 Example return value of keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
*/ 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, если это центр сертификации (CA), и false в противном случае.
• raw <Buffer> Данные сертификата X.509 в кодировке DER.
• subject <Object> Субъект сертификата, описанный с помощью полей Country (C), StateOrProvince (ST), Locality (L), Organization (O), OrganizationalUnit (OU) и CommonName (CN). В сертификатах TLS CommonName обычно представляет собой имя DNS. Пример: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}.
• issuer <Object> Издатель сертификата, описанный с помощью тех же полей, что и subject.
• valid_from <string> Дата и время начала действия сертификата.
• valid_to <string> Дата и время окончания действия сертификата.
• serialNumber <string> Серийный номер сертификата в виде шестнадцатеричной строки. Пример: 'B9B0D332A1AA5635'.
• fingerprint <string> Дайджест SHA-1 сертификата в кодировке DER. Возвращается в виде шестнадцатеричной строки с разделителями :. Пример: '2A:7A:C2:DD:...'.
• fingerprint256 <string> Дайджест SHA-256 сертификата в кодировке DER. Возвращается в виде шестнадцатеричной строки с разделителями :. Пример: '2A:7A:C2:DD:...'.
• fingerprint512 <string> Дайджест SHA-512 сертификата в кодировке DER. Возвращается в виде шестнадцатеричной строки с разделителями :. Пример: '2A:7A:C2:DD:...'.
• ext_key_usage <Array> (Необязательно) Расширенное использование ключа — набор OID.
• subjectaltname <string> (Необязательно) Строка с объединёнными именами субъекта; альтернатива именам subject.
• infoAccess <Array> (Необязательно) Массив с описанием AuthorityInfoAccess, используемый с OCSP.
• issuerCertificate <Object> (Необязательно) Объект сертификата издателя. Для самоподписанных сертификатов это может быть циклическая ссылка.

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

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

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

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

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

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

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

tlsSocket.getPeerFinished()

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

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

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

tlsSocket.getPeerX509Certificate()

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

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

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

tlsSocket.getProtocol()

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

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

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

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

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

tlsSocket.getSession()

• <Buffer>

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

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

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

tlsSocket.getSharedSigalgs()

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

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

tlsSocket.getTLSTicket()

• <Buffer>

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

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

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

tlsSocket.getX509Certificate()

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

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

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

tlsSocket.isSessionReused()

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

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

tlsSocket.localAddress

• <string>

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

tlsSocket.localPort

• <integer>

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

tlsSocket.remoteAddress

• <string>

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

tlsSocket.remoteFamily

• <string>

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

tlsSocket.remotePort

• <integer>

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

tlsSocket.renegotiate(options, callback)

• options <Object>

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

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

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

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

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

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

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

tlsSocket.setKeyCert(context)

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

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

tlsSocket.setMaxSendFragment(size)

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

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

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

tls.checkServerIdentity(hostname, cert)

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

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

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

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

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

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

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

tls.connect(options[, callback])

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

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

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

В отличие от API https, tls.connect() по умолчанию не включает расширение SNI (индикация имени сервера), из-за чего некоторые серверы могут вернуть неправильный сертификат или вовсе отклонить соединение. Чтобы включить 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 <string> Значение по умолчанию для options.path.
• options <Object> См. tls.connect().
• callback <Function> См. tls.connect().
• Возвращает: <tls.TLSSocket>

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

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

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

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

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

Если заданы параметры port или host, они имеют приоритет над соответствующими аргументами port или host.

tls.createSecureContext([options])

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

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

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

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

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

Если параметр ca не указан, Node.js по умолчанию использует общедоступный список доверенных центров сертификации Mozilla.

Использовать пользовательские параметры DHE не рекомендуется; вместо них следует использовать новый параметр dhparam: 'auto'. Если задано значение 'auto', автоматически выбираются общеизвестные параметры DHE достаточной стойкости. В противном случае при необходимости можно использовать openssl dhparam для создания пользовательских параметров. Длина ключа должна быть не менее 1024 бит, иначе будет вызвана ошибка. Хотя длина 1024 бита допустима, для более надежной защиты используйте 2048 бит или больше.

tls.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, в ClientHello добавляется расширение запроса состояния 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 <Object>
  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Массив строк, Buffer, TypedArray или DataView либо отдельный Buffer, TypedArray или DataView с поддерживаемыми протоколами ALPN. Buffer должны иметь формат [len][name][len][name]..., например 0x05hello0x05world, где первый байт содержит длину следующего имени протокола. Обычно гораздо проще передать массив, например ['hello', 'world']. (Протоколы следует расположить в порядке приоритета.)
  • ALPNCallback: <Function> Если задан, этот обработчик вызывается, когда клиент устанавливает соединение с помощью расширения ALPN. В функцию обратного вызова передается один аргумент — объект с полями servername и protocols, содержащими соответственно имя сервера из расширения SNI (если оно есть) и массив строк с именами протоколов ALPN. Обработчик должен вернуть одну из строк, перечисленных в protocols; она будет передана клиенту как выбранный протокол ALPN. Чтобы отклонить соединение с фатальным оповещением, обработчик должен вернуть undefined. Если возвращенная строка не совпадает ни с одним протоколом ALPN клиента, будет вызвана ошибка. Этот параметр нельзя использовать вместе с параметром ALPNProtocols; при задании обоих параметров будет вызвана ошибка.
  • clientCertEngine <string> Имя движка OpenSSL, который может предоставить сертификат клиента. Устарел.
  • enableTrace <boolean> Если значение равно true, при создании новых соединений будет вызван tls.TLSSocket.enableTrace(). Трассировку можно включить и после установления безопасного соединения, однако для трассировки процесса установления соединения необходимо использовать этот параметр. По умолчанию: false.
  • handshakeTimeout <number> Прерывает соединение, если рукопожатие SSL/TLS не завершается в течение указанного количества миллисекунд. При истечении времени ожидания рукопожатия для объекта tls.Server генерируется событие 'tlsClientError'. По умолчанию: 120000 (120 секунд).
  • rejectUnauthorized <boolean> Если значение не равно false, сервер отклоняет все соединения, не авторизованные с помощью предоставленного списка CA. Этот параметр действует, только если requestCert имеет значение true. По умолчанию: true.
  • requestCert <boolean> Если значение равно true, сервер запрашивает сертификат у подключающихся клиентов и пытается проверить его. По умолчанию: false.
  • sessionTimeout <number> Число секунд, по истечении которых сеанс TLS, созданный сервером, больше нельзя будет возобновить. Дополнительные сведения см. в разделе Возобновление сеанса. По умолчанию: 300.
  • SNICallback(servername, callback) <Function> Функция, которая вызывается, если клиент поддерживает расширение SNI для TLS. При вызове ей передаются два аргумента: servername и callback. callback — функция обратного вызова в стиле error-first, принимающая два необязательных аргумента: error и ctx. Если указан ctx, он является экземпляром SecureContext. Чтобы получить подходящий SecureContext, можно использовать tls.createSecureContext(). Если callback вызывается с ложным аргументом ctx, используется безопасный контекст сервера по умолчанию. Если SNICallback не указан, будет использоваться функция обратного вызова по умолчанию с высокоуровневым API (см. ниже).
  • ticketKeys: <Buffer> 48 байт криптографически стойких псевдослучайных данных. Дополнительные сведения см. в разделе Возобновление сеанса.
  • pskCallback <Function> Для согласования TLS-PSK см. раздел Предварительно согласованные ключи.
  • pskIdentityHint <string> Необязательная подсказка, отправляемая клиенту для помощи в выборе идентификатора при согласовании TLS-PSK. В TLS 1.3 игнорируется. Если установить pskIdentityHint не удалось, будет создано событие 'tlsClientError' с кодом 'ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED'.
  • ...: Можно указать любой параметр tls.createSecureContext(). Для серверов обычно требуются параметры идентификации (pfx, key/cert или pskCallback).
  • ...: Можно указать любой параметр net.createServer().
• secureConnectionListener <Function>
• Возвращает: <tls.Server>

Создает новый объект 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()

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

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

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

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

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

tls.rootCertificates

• <string[]>

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

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

tls.DEFAULT_ECDH_CURVE

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

tls.DEFAULT_MAX_VERSION

• <string> Значение по умолчанию параметра maxVersion объекта tls.createSecureContext(). Ему можно присвоить любую из поддерживаемых версий протокола TLS: 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' или 'TLSv1'. По умолчанию: 'TLSv1.3', если значение не изменено с помощью параметров CLI. Использование --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', если значение не изменено с помощью параметров CLI. Использование --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, если значение не изменено параметрами CLI с помощью --tls-default-ciphers.