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

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

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

openssl genrsa -out ryans-key.pem 2048

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

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

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

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

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

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

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

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

Где:

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

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

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

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

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

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

Эфемерные методы могут иметь некоторые недостатки производительности, так как генерация ключей является ресурсоемкой операцией.

Для использования совершенной прямой секретности с DHE с модулем tls, необходимо сгенерировать параметры Диффи-Хеллмана и указать их с параметром dhparam для tls.createSecureContext(). Следующий пример демонстрирует использование командной строки OpenSSL для генерации таких параметров:

openssl dhparam -outform PEM -out dhparam.pem 2048

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

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

ALPN и SNI

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

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

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

Поддержка 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, но в настоящее время поддерживаются только те, которые используют хэш-функцию SHA256; их можно получить с помощью openssl ciphers -v -s -tls1_3 -psk.

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

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

Смягчение атак на переподключение по инициативе клиента

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

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

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

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

TLSv1.3 не поддерживает переподключение.

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

Установление TLS-сессии может быть относительно медленным. Этот процесс можно ускорить, сохранив и повторно использовав состояние сессии. Здесь обсуждаются несколько механизмов, от старейших к новым (и предпочтительным).

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

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

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

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

Билеты сессии

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

Возобновление с использованием билетов сессий становится все более распространенным в веб-браузерах при запросах HTTPS.

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

В TLSv1.3 следует учитывать, что сервер может отправить несколько билетов, что приведет к нескольким событиям 'session'. См. 'session' для получения дополнительной информации.

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

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

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

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

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

Для всех механизмов, когда возобновление сеанса не удаётся, серверы создают новые сеансы. Поскольку неудачное возобновление сеанса не приводит к ошибкам подключения TLS/HTTPS, легко упустить из виду ненужную плохую производительность TLS. Можно использовать OpenSSL CLI для проверки того, что серверы возобновляют сеансы. Используйте параметр -reconnect для openssl s_client, например:

$ openssl s_client -connect localhost:443 -reconnect

Просмотрите вывод отладки. Первое подключение должно сказать "Новый", например:

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

Последующие подключения должны сказать "Использован повторно", например:

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

Изменение стандартного набора шифров TLS

Node.js построен с предустановленным набором включённых и отключённых шифров TLS. Этот стандартный список шифров можно настроить при построении Node.js, чтобы дистрибутивы могли предоставлять свой собственный стандартный список.

Следующая команда может быть использована для отображения стандартного набора шифров:

node -p crypto.constants.defaultCoreCipherList | tr ':' '\n'
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-GCM-SHA384
DHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256
DHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-SHA384
DHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA256
DHE-RSA-AES256-SHA256
HIGH
!aNULL
!eNULL
!EXPORT
!DES
!RC4
!MD5
!PSK
!SRP
!CAMELLIA

Этот стандарт можно полностью заменить с помощью командной строки --tls-cipher-list (непосредственно или через переменную окружения NODE_OPTIONS). Например, следующее устанавливает ECDHE-RSA-AES128-GCM-SHA256:!RC4 в качестве стандартного набора шифров TLS:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' server.js

export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4'
node server.js

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

128-битный AES предпочтительнее 192 и 256-битного AES в свете специфических атак, затрагивающих более крупные размеры ключей AES.

Старые клиенты, которые полагаются на небезопасные и устаревшие шифры RC4 или DES (например, Internet Explorer 6), не могут завершить процесс рукопожатия с предустановленной конфигурацией. Если необходимо поддерживать этих клиентов, рекомендации TLS могут предложить совместимый набор шифров. Для получения более подробной информации см. документацию OpenSSL по формату списка шифров.

Существует только 5 наборов шифров 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'

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

Класс: 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. Обычно пользователям не нужно обращаться к этому событию.

Это событие также может быть явно сгенерировано пользователями для ввода соединений в сервер 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);
});

Событие: 'newSession'

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

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

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

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

Событие: 'OCSPRequest'

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

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

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

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

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

Типичный процесс запроса OCSP:

1. Клиент подключается к серверу и отправляет запрос 'OCSPRequest' (через расширение информации о статусе в ClientHello).
2. Сервер получает запрос и генерирует событие 'OCSPRequest', вызывая обработчик, если он зарегистрирован.
3. Сервер извлекает OCSP-URL из certificate или issuer и выполняет запрос OCSP к CA.
4. Сервер получает ответ 'OCSPResponse' от CA и отправляет его обратно клиенту через аргумент 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);
});

Событие: 'secureConnection'

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

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

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

Свойство tlsSocket.alpnProtocol – это строка, содержащая выбранный протокол 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.createSecureContext() аргументов (например, key, cert, ca, и т.д.).

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

server.address()

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

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

server.close([callback])

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

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

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

server.connections

• <число>

Возвращает текущее количество одновременных подключений на сервере.

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 <Буфер> Буфер длиной 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));

Событие: 'OCSPResponse'

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

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

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

Событие: 'secureConnect'

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

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

tlsSocket.address()

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

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

tlsSocket.authorizationError

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

tlsSocket.authorized

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

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

tlsSocket.disableRenegotiation()

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

tlsSocket.enableTrace()

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

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

tlsSocket.encrypted

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

tlsSocket.getCertificate()

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

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

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

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

tlsSocket.getCipher()

• Возвращает: <Объект>
  • name <строка> Имя OpenSSL для набора шифров.
  • standardName <строка> Имя IETF для набора шифров.
  • version <строка> Минимальная версия протокола TLS, поддерживаемая этим набором шифров.

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

Например:

{
    "name": "AES128-SHA256",
    "standardName": "TLS_RSA_WITH_AES_128_CBC_SHA256",
    "version": "TLSv1.2"
}

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

tlsSocket.getEphemeralKeyInfo()

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

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

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

tlsSocket.getFinished()

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

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

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

tlsSocket.getPeerCertificate([detailed])

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

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

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

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

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

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

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

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

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

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

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

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

{ subject:
   { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
     CN: '*.nodejs.org' },
  issuer:
   { C: 'GB',
     ST: 'Greater Manchester',
     L: 'Salford',
     O: 'COMODO CA Limited',
     CN: 'COMODO RSA Domain Validation Secure Server CA' },
  subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
  infoAccess:
   { 'CA Issuers - URI':
      [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
     'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
  modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  exponent: '0x10001',
  pubkey: <Buffer ... >,
  valid_from: 'Aug 14 00:00:00 2017 GMT',
  valid_to: 'Nov 20 23:59:59 2019 GMT',
  fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
  fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
  serialNumber: '66593D57F20CBC573E433381B5FEC280',
  raw: <Buffer ... > }

tlsSocket.getPeerFinished()

• Возвращает: <Буфер> | <неопределено> Последнее сообщение 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.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.exportKeyingMaterial(length, label[, context])

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

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

• context <Буфер> Необязательно укажите контекст.

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

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

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

tlsSocket.getTLSTicket()

• <Буфер>

Для клиента возвращает билет сессии TLS, если он доступен, или undefined. Для сервера всегда возвращает 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 при ошибке. При успехе возвращает <неопределено>.

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

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

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 <булево> Если опция socket отсутствует, указывает, разрешено ли создание внутреннего сокета в полуоткрытом состоянии, в противном случае опция игнорируется. Подробнее см. опцию allowHalfOpen класса net.Socket. По умолчанию: false.
  • rejectUnauthorized <булево> Если не false, сертификат сервера проверяется по списку предоставленных центров сертификации. При ошибке проверки генерируется событие 'error'; err.code содержит код ошибки OpenSSL. По умолчанию: true.
  • pskCallback <Функция>
    • подсказка: <строка> необязательное сообщение, отправленное сервером, чтобы помочь клиенту решить, какую личность использовать во время согласования. Всегда null при использовании TLS 1.3.
    • Возвращает: <Объект> в формате { psk: <Buffer|TypedArray|DataView>, identity: <string> } или null для остановки процесса согласования. psk должна быть совместима с выбранным алгоритмом хэширования. identity должна использовать кодировку UTF-8.
    При согласовании TLS-PSK (предварительно установленных ключей) эта функция вызывается с необязательной идентификацией hint, предоставленной сервером, или null в случае TLS 1.3, где hint была удалена. Необходимо предоставить пользовательскую функцию tls.checkServerIdentity() для соединения, так как по умолчанию будет проверка имени хоста/IP сервера по сертификату, но это не применимо для PSK, т.к. сертификат отсутствует. Дополнительную информацию можно найти в RFC 4279.
  • ALPNProtocols: <строковый массив> | <Буферный массив> | <Массив типов данных> | <DataView> | <Буфер> | <Тип данных> | <DataView> Массив строк, Buffer или TypedArray или DataView, или одиночный Buffer или TypedArray или DataView, содержащие поддерживаемые протоколы ALPN. Buffer должны иметь формат [len][name][len][name]..., например, '\x08http/1.1\x08http/1.0', где байт len - длина следующего имени протокола. Передача массива обычно намного проще, например, ['http/1.1', 'http/1.0']. Протоколы в начале списка имеют более высокий приоритет, чем те, что находятся в конце.
  • servername: <строка> Имя сервера для расширения SNI (Server Name Indication) TLS. Это имя хоста, к которому происходит подключение, а не IP-адрес. Может использоваться многоадресным сервером для выбора правильного сертификата для представления клиенту. Подробнее см. опцию SNICallback в tls.createServer().
  • checkServerIdentity(servername, cert) <Функция> Функция обратного вызова, которая используется (вместо встроенной функции tls.checkServerIdentity()) для проверки имени хоста сервера (или предоставленного servername при явном указании) по сертификату. Если проверка завершится неудачно, функция должна вернуть объект <Ошибка>. Функция должна вернуть undefined если servername и cert проверены.
  • session <Буфер> Экземпляр Buffer, содержащий сеанс TLS.
  • minDHSize <число> Минимальный размер параметра DH в битах для принятия TLS-соединения. Если сервер предложит параметр DH с размером меньше minDHSize, TLS-соединение будет разрушено, и будет выброшено исключение. По умолчанию: 1024.
  • highWaterMark: <число> Совместимо с параметром highWaterMark читаемого потока. По умолчанию: 16 * 1024.
  • secureContext: Объект контекста TLS, созданный с помощью tls.createSecureContext(). Если secureContext не указан, будет создан объект, передавая весь объект options в tls.createSecureContext().
  • ...: 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('tls');
const fs = require('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');
});

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

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

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

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

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

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

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

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

tls.createSecureContext([options])

• options <Объект>
  • ca <строка> | <массив строк> | <Буфер> | <Массив буферов> Выберите доверенные сертификаты CA. По умолчанию доверяются известные CA, прошедшие проверку Mozilla. При явно указанных CA сертификаты Mozilla полностью заменяются. Значение может быть строкой или 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 man страницы для получения дополнительной информации.
  • ciphers <строка> Спецификация набора шифров OpenSSL, заменяющая стандартный. Для получения дополнительной информации, см. изменение стандартного набора шифров TLS. Разрешенные шифры можно получить через tls.getCiphers(). Имена шифров должны быть в верхнем регистре для их корректного использования OpenSSL.
  • clientCertEngine <строка> Имя движка OpenSSL, который может предоставить сертификат клиента.
  • crl <строка> | <массив строк> | <Буфер> | <Массив буферов> CRL (списки отзыва сертификатов) в формате PEM.
  • dhparam <строка> | <Буфер> Параметры Diffie-Hellman, необходимые для идеального прямого секрета. Для создания параметров используйте openssl dhparam. Длина ключа должна быть не менее 1024 бит, иначе будет выброшено исключение. Хотя 1024 бита допустимы, для большей безопасности используйте 2048 бит или больше. Если опущено или неверно, параметры будут молча проигнорированы, и шифры DHE не будут доступны.
  • ecdhCurve <строка> Строка, описывающая заданную кривую или список кривых NID или имён, разделённых двоеточием, например 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 <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() использует значение хэша SHA1 длиной 128 бит, усечённого из process.argv, в качестве значения по умолчанию параметра sessionIdContext. В других API, создающих защищённые контексты, значения по умолчанию отсутствуют.

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

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

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

tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])

• context <Объект> Объект защищённого контекста, возвращённый tls.createSecureContext()
• isServer <логическое значение> true для указания, что это подключение TLS должно быть открыто в качестве сервера.
• requestCert <логическое значение> true для указания, должен ли сервер запросить сертификат у подключающегося клиента. Применимо только тогда, когда isServer имеет значение true.
• rejectUnauthorized <логическое значение> Если не 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, содержащий сеанс TLS.
  • requestOCSP <логическое значение> Если true, указывает, что расширение запроса статуса OCSP будет добавлено к клиенту hello и событие 'OCSPResponse' будет излучено в сокете перед установлением защищённого соединения.

Создаёт новый объект защищённой пары с двумя потоками, один из которых читает и записывает зашифрованные данные, а другой — читает и записывает данные в открытом виде. Как правило, зашифрованный поток подаётся на вход/выход потоку с зашифрованными данными, а поток в открытом виде используется в качестве замены начальному зашифрованному потоку.

tls.createSecurePair() возвращает объект tls.SecurePair с потоками cleartext и encrypted.

Использование cleartext имеет тот же API, что и tls.TLSSocket.

Метод tls.createSecurePair() теперь устарел в пользу tls.TLSSocket(). Например, код:

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

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

secureSocket = tls.TLSSocket(socket, options);

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

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

• options <Объект>
  • ALPNProtocols: <Массив строк> | <Массив буферов> | <Массив TypedArray> | <Массив DataView> | <Буфер> | <TypedArray> | <DataView> Массив строк, Buffer или TypedArray или DataView или один Buffer или TypedArray или DataView, содержащий поддерживаемые протоколы ALPN. Buffer должны иметь формат [len][name][len][name]... например, 0x05hello0x05world, где первый байт — длина следующего имени протокола. Передача массива обычно намного проще, например, ['hello', 'world']. (Протоколы должны быть упорядочены по приоритету.)
  • clientCertEngine <Строка> Имя OpenSSL-модуля, который может предоставить сертификат клиента.
  • enableTrace <Булево> Если true, tls.TLSSocket.enableTrace() будет вызываться при новых подключениях. Отслеживание можно включить после установления защищённого соединения, но этот параметр необходимо использовать для отслеживания настройки защищённого соединения. По умолчанию: false.
  • handshakeTimeout <Число> Прервать подключение, если рукопожатие SSL/TLS не завершится в указанное количество миллисекунд. 'tlsClientError' издаётся на объекте tls.Server всякий раз, когда рукопожатие истекает по времени. По умолчанию: 120000 (120 секунд).
  • rejectUnauthorized <Булево> Если не false, сервер отклонит любое подключение, которое не авторизовано предоставленным списком центров сертификации. Этот параметр действует только если requestCert является true. По умолчанию: true.
  • requestCert <Булево> Если true, сервер запросит сертификат от подключённых клиентов и попытается проверить этот сертификат. По умолчанию: false.
  • sessionTimeout <Число> Количество секунд после которого сессия TLS, созданная сервером, больше не будет возобновляемой. Подробнее см. Возобновление сессии. По умолчанию: 300.
  • SNICallback(servername, callback) <Функция> Функция, которая будет вызвана, если клиент поддерживает расширение SNI TLS. При вызове будут переданы два аргумента: servername и callback. tls.createSecureContext() — обратный вызов с ошибкой, который принимает два необязательных аргумента: error и ctx. ctx, если предоставлен, это экземпляр SecureContext класса. tls.createSecureContext() можно использовать для получения правильного SecureContext контекста. Если callback вызывается с ложным значением аргумента ctx, будет использован стандартный контекст безопасности сервера. Если SNICallback не был предоставлен, будет использован стандартный обратный вызов с API высокого уровня (см. ниже).
  • ticketKeys: <Буфер> 48 байтов криптографически сильных псевдослучайных данных. Подробнее см. Возобновление сессии.
  • pskCallback <Функция>
    • socket: <tls.TLSSocket> экземпляр серверного tls.TLSSocket для этого соединения.
    • identity: <Строка> параметр идентификатора, переданный клиентом.
    • Возвращает: <Буфер> | <TypedArray> | <DataView> предварительно согласованный ключ, который должен быть буфером или null для остановки процесса переговоров. Возвращаемый предварительно согласованный ключ должен быть совместим с выбранным дайджестом шифра.
    При переговорах TLS-PSK (предварительно согласованных ключей) эта функция вызывается с идентификатором, предоставленным клиентом. Если возвращаемое значение — null, процесс переговоров завершится, и клиенту будет отправлено сообщение об ошибке "unknown_psk_identity". Если сервер хочет скрыть тот факт, что идентификатор предварительно согласованного ключа не известен, обратный вызов должен предоставить какие-либо случайные данные как psk чтобы подключение завершилось ошибкой "decrypt_error" до завершения переговоров. Шифры предварительно согласованных ключей отключены по умолчанию, и использование TLS-PSK требует явного указания набора шифров с параметром ciphers. Более подробная информация представлена в RFC 4279.
  • pskIdentityHint <Строка> необязательный подсказка для отправки клиенту, чтобы помочь с выбором идентификатора во время переговоров TLS-PSK. Будет проигнорировано в TLS 1.3. При неудачной установке pskIdentityHint будет издано событие 'tlsClientError' с кодом 'ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED'.
  • ...: Любой параметр tls.createSecureContext() может быть предоставлен. Для серверов обычно требуются параметры идентификатора (pfx, key/cert или pskCallback).
  • ...: Любой параметр net.createServer() может быть предоставлен.
• secureConnectionListener <Функция>
• Возвращает: <tls.Сервер>

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

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

Ниже приведён пример простого эхо-сервера:

const tls = require('tls');
const fs = require('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');
});

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

tls.getCiphers()

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

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

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

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

tls.rootCertificates

• <Массив строк>

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

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

tls.DEFAULT_ECDH_CURVE

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

tls.DEFAULT_MAX_VERSION

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

tls.DEFAULT_MIN_VERSION

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