TLS (SSL)

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

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

const tls = require('tls');

Понятия TLS/SSL

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

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

openssl genrsa -out ryans-key.pem 2048

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

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

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

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

Старые клиенты, которые полагаются на небезопасные и устаревшие шифры RC4 или DES (например, Internet Explorer 6), не могут завершить процесс рукопожатия с настройками по умолчанию. Если необходимо поддерживать таких клиентов, рекомендации TLS по рекомендациям 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.

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

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

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

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

Событие: 'resumeSession'

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

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

Обработчик события должен выполнить поиск в внешнем хранилище для сохранённой 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 — это boolean, указывающее, был ли клиент проверен одним из предоставленных центров сертификации для сервера. Если tlsSocket.authorized имеет значение false, то socket.authorizationError описывает, как произошёл отказ в авторизации. В зависимости от настроек TLS-сервера, незащищённые подключения могут быть всё ещё приняты.

Свойство tlsSocket.alpnProtocol — это строка, содержащая выбранный протокол ALPN. Когда у ALPN нет выбранного протокола, tlsSocket.alpnProtocol равно false.

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

Событие: 'tlsClientError'

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

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

server.addContext(hostname, context)

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

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

server.address()

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

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

server.close([callback])

• callback <Функция> Обработчик событий, который будет зарегистрирован для прослушивания события '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 SSL_trace(), формат не документирован, может измениться без предварительного уведомления и на него не следует полагаться.

tlsSocket.encrypted

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

tlsSocket.getCertificate()

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

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

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

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

tlsSocket.getCipher()

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

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

Например:

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

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

tlsSocket.getEphemeralKeyInfo()

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

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

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

tlsSocket.getTLSTicket()

• <Buffer>

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

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

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

tlsSocket.isSessionReused()

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

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

tlsSocket.localAddress

• <string>

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

tlsSocket.localPort

• <number>

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

tlsSocket.remoteAddress

• <string>

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

tlsSocket.remoteFamily

• <string>

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

tlsSocket.remotePort

• <number>

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

tlsSocket.renegotiate(options, callback)

• options <Object>

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

Эта функция может быть переопределена путём предоставления альтернативной функции в качестве части опции 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.Дуплекс> Устанавливает защищённое соединение на заданном сокете вместо создания нового сокета. Как правило, это экземпляр 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: <Массив строк> | <Массив буферов> | <Массив типов данных> | <Массив данных> | <Буфер> | <Тип данных> | <Данные> Массив строк, Buffer или TypedArray или DataView или один Buffer или TypedArray или DataView, содержащий поддерживаемые протоколы ALPN. Buffer должны иметь формат [len][name][len][name]..., например '\x08http/1.1\x08http/1.0', где len байт – длина следующего имени протокола. Передача массива обычно проще, например ['http/1.1', 'http/1.0']. Протоколы в начале списка имеют больший приоритет, чем последующие.
  • servername: <строка> Имя сервера для расширения TLS SNI (Server Name Indication). Это имя хоста, к которому происходит подключение, а не IP-адрес. Может использоваться многоадресным сервером для выбора правильного сертификата, представленного клиенту, см. параметр SNICallback в tls.createServer().
  • checkServerIdentity(servername, cert) <Функция> Функция обратного вызова, которая используется (вместо встроенной функции tls.checkServerIdentity()) при проверке имени хоста сервера (или предоставленного servername, если он явно задан) по отношению к сертификату. Если проверка не пройдена, метод должен вернуть <Ошибка>. Метод должен вернуть undefined, если servername и cert проверены.
  • session <Буфер> Экземпляр Buffer, содержащий сессию TLS.
  • minDHSize <число> Минимальный размер параметра DH в битах для принятия подключения TLS. Если сервер предлагает параметр DH с размером меньше minDHSize, подключение TLS разрушается, и выбрасывается ошибка. По умолчанию: 1024.
  • 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 <string> | <string[]> | <Buffer> | <Buffer[]> Необязательно переопределить доверенные сертификаты CA. По умолчанию доверяются известные CA, собранные Mozilla. Сертификаты CA Mozilla полностью заменяются, когда CA явно указываются с помощью этого параметра. Значение может быть строкой или Buffer, или массивом строк и/или Buffer. Любая строка или Buffer может содержать несколько PEM-CA, соединённых вместе. Сертификат клиента должен быть связан с CA, которому доверяет сервер, для аутентификации соединения. При использовании сертификатов, которые не связаны с известной CA, 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> Спецификация набора шифров OpenSSL, заменяющая стандартный. Для получения дополнительной информации, см. изменение стандартного набора шифров TLS. Допустимые шифры можно получить с помощью tls.getCiphers(). Имена шифров должны быть в верхнем регистре, чтобы OpenSSL их принял.
  • clientCertEngine <string> Имя модуля OpenSSL, который может предоставить сертификат клиента.
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> PEM-форматированные списки отзыва сертификатов (CRL).
  • dhparam <string> | <Buffer> Параметры Diffie-Hellman, необходимые для совершенной прямой секретности. Используйте openssl dhparam для создания параметров. Длина ключа должна быть не меньше 1024 бит, иначе будет выброшено исключение. Хотя 1024 бита допустимы, для большей безопасности используйте 2048 бит или больше. Если параметр опущен или некорректен, параметры будут проигнорированы, и шифры DHE не будут доступны.
  • ecdhCurve <string> Строка, описывающая именованную кривую или список кривых, разделённых двоеточием, например 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, таких как tls.createServer() и server.addContext(), но не имеет публичных методов.

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

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

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

• context <Объект> Объект защищенного контекста, возвращаемый tls.createSecureContext()
• isServer <boolean> true для указания того, что это подключение TLS должно быть открыто как сервер.
• requestCert <boolean> true для указания, должен ли сервер запрашивать сертификат у подключенного клиента. Применяется только когда isServer является true.
• rejectUnauthorized <boolean> Если не false, сервер автоматически отклоняет клиентов с невалидными сертификатами. Применяется только когда isServer является true.
• options
  • enableTrace: См. tls.createServer()
  • secureContext: Объект контекста TLS из tls.createSecureContext()
  • isServer: Если true, сокет TLS будет создан в режиме сервера. По умолчанию: false.
  • server <net.Server> Экземпляр net.Server
  • requestCert: См. tls.createServer()
  • rejectUnauthorized: См. tls.createServer()
  • ALPNProtocols: См. tls.createServer()
  • SNICallback: См. tls.createServer()
  • session <Buffer> Экземпляр Buffer, содержащий сеанс TLS.
  • requestOCSP <boolean> Если true, указывает, что расширение запроса статуса OCSP будет добавлено в клиентское приветствие, и событие 'OCSPResponse' будет выведено в сокете перед установлением защищенного соединения.

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

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

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

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

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

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

secureSocket = tls.TLSSocket(socket, options);

где 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']. (Протоколы должны быть упорядочены по приоритету.)
  • clientCertEngine <string> Имя OpenSSL-движка, который может предоставить сертификат клиента.
  • enableTrace <boolean> Если true, tls.TLSSocket.enableTrace() будет вызываться при новых подключениях. Отслеживание можно включить после установления защищённого соединения, но этот параметр необходим для отслеживания процесса установления защищённого соединения. По умолчанию: false.
  • handshakeTimeout <number> Прервать подключение, если рукопожатие SSL/TLS не завершится в течение указанного количества миллисекунд. Сообщение 'tlsClientError' генерируется для объекта tls.Server при истечении времени ожидания рукопожатия. По умолчанию: 120000 (120 секунд).
  • rejectUnauthorized <boolean> Если не false, сервер будет отклонять любое подключение, которое не авторизовано с помощью предоставленного списка доверенных центров сертификации. Этот параметр действует только если requestCert равно true. По умолчанию: true.
  • requestCert <boolean> Если true, сервер запросит сертификат у подключившихся клиентов и попытается проверить этот сертификат. По умолчанию: false.
  • sessionTimeout <number> Количество секунд, после которого созданная сервером сессия TLS больше не будет возобновляемой. Дополнительную информацию см. в разделе Возобновление сессий. По умолчанию: 300.
  • SNICallback(servername, callback) <Function> Функция, которая будет вызываться, если клиент поддерживает расширение SNI TLS. При вызове будут переданы два аргумента: servername и callback. callback — обратный вызов, принимающий два необязательных аргумента: error и ctx. ctx, если предоставлен, представляет собой экземпляр SecureContext. tls.createSecureContext() может быть использован для получения соответствующего экземпляра SecureContext. Если callback вызван с ложным значением для аргумента ctx, будет использован стандартный контекст безопасности сервера. Если SNICallback не был предоставлен, будет использован стандартный обратный вызов с высокоуровневым API (см. ниже).
  • ticketKeys: <Buffer> 48 байт криптографически сильных псевдослучайных данных. Дополнительную информацию см. в разделе Возобновление сессий.
  • pskCallback <Function>
    • socket: <tls.TLSSocket> экземпляр серверного tls.TLSSocket для данного соединения.
    • identity: <string> параметр идентификации, отправленный клиентом.
    • Возвращает: <Buffer> | <TypedArray> | <DataView> предварительно установленный ключ, который должен быть буфером или null для остановки процесса переговоров. Возвращённый PSK должен быть совместим с выбранным алгоритмом хеширования. При переговорах TLS-PSK (предварительно установленных ключей) эта функция вызывается с идентификатором, предоставленным клиентом. Если возвращаемое значение null, процесс переговоров останавливается, и клиенту отправляется сообщение об ошибке "unknown_psk_identity". Если сервер хочет скрыть тот факт, что идентификатор PSK не был известен, обратный вызов должен предоставить какие-то случайные данные как psk для того, чтобы подключение завершилось ошибкой "decrypt_error", прежде чем завершатся переговоры. PSK-шифры отключены по умолчанию, и использование TLS-PSK требует явного указания набора шифров с опцией ciphers . Дополнительную информацию см. в RFC 4279.
  • 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 автоматически разделяются между рабочими процессами модуля 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()

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

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

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

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

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', если не изменено с помощью командной строки. Использование --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'. Если указано несколько значений, используется наименьшее.