TLS (SSL)

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

const tls = require('tls');

Концепции 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 (в отличие от использования одного и того же ключа для всех сессий). Методы, реализующие эту технику, называются «эпизодическими».

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

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

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

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

openssl dhparam -outform PEM -out dhparam.pem 2048

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

ALPN и SNI

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

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

Предотвращение атак на переустановку соединения, инициированных клиентом

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

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

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

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

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

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

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

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

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

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

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

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

Серверам в одном процессе не нужна специальная реализация для использования билетов сессий. Для использования билетов сессий через перезапуск сервера или балансировщики нагрузки все серверы должны использовать те же ключи билетов. Внутри используется три 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 может быть использована для проверки того, что серверы возобновляют сессии. Используйте параметр -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. В настоящее время набор шифров по умолчанию:

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.

Для получения подробной информации о формате обратитесь к документации OpenSSL cipher list format.

Набор шифров по умолчанию, включённый в Node.js, был тщательно выбран для отражения современных рекомендаций по безопасности и минимизации рисков. Изменение набора шифров по умолчанию может существенно повлиять на безопасность приложения. Переключатель --tls-cipher-list и опция ciphers должны использоваться только в случае крайней необходимости.

Набор шифров по умолчанию отдаёт предпочтение шифрам GCM для настройки «современной криптографии» в Chrome, а также отдаёт предпочтение шифрам ECDHE и DHE для обеспечения Perfect Forward Secrecy, предлагая некоторую обратную совместимость.

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

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

Класс: tls.Server

Класс tls.Server является подклассом net.Server, который принимает защищённые соединения с использованием TLS или SSL.

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

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

Событие: 'OCSPRequest'

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

• certificate <Buffer> Сертификат сервера
• issuer <Buffer> Сертификат издателя
• callback <Функция> Функция обратного вызова, которая должна быть вызвана для предоставления результатов запроса 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 к ЦС.
4. Сервер получает ответ 'OCSPResponse' от ЦС и отправляет его обратно клиенту через аргумент callback
5. Клиент проверяет ответ и либо закрывает сокет, либо выполняет рукопожатие.

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

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

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

Событие: 'resumeSession'

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

• sessionId <Buffer> Идентификатор TLS-сессии

• callback <Функция> Функция обратного вызова, вызываемая при восстановлении предыдущей сессии: callback([err[, sessionData]])

  • err <Ошибка>
  • 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 — 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()[src]

• Returns: <Object>

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

server.close([callback])[src]

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

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

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

server.connections

• <number>

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

server.getTicketKeys()

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

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

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

server.listen()[src]

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

server.setTicketKeys(keys)

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

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

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

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

Класс: tls.TLSSocket

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>

  • 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 — это цифровой подпись объекта от сертификационного центра сервера, который содержит информацию о статусе отзыва сертификата сервера.

Событие: 'secureConnect'

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

tlsSocket.address()

• Returns: <Object>

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

tlsSocket.authorizationError

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

tlsSocket.authorized

• Returns: <boolean>

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

tlsSocket.disableRenegotiation()

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

tlsSocket.encrypted

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

tlsSocket.getCipher()

• Returns: <Object>

Возвращает объект, представляющий имя шифра. Ключ version — это устаревшее поле, которое всегда содержит значение 'TLSv1/SSLv3'.

Например: { name: 'AES256-SHA', version: 'TLSv1/SSLv3' }.

Для получения дополнительной информации см. SSL_CIPHER_get_name() в https://www.openssl.org/docs/man1.1.0/ssl/SSL_CIPHER_get_name.html.

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

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

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

{ subject:
   { C: 'UK',
     ST: 'Acknack Ltd',
     L: 'Rhys Jones',
     O: 'node.js',
     OU: 'Test TLS Certificate',
     CN: 'localhost' },
  issuer:
   { C: 'UK',
     ST: 'Acknack Ltd',
     L: 'Rhys Jones',
     O: 'node.js',
     OU: 'Test TLS Certificate',
     CN: 'localhost' },
  issuerCertificate:
   { ... another certificate, possibly with an .issuerCertificate ... },
  raw: < RAW DER buffer >,
  pubkey: < RAW DER buffer >,
  valid_from: 'Nov 11 09:52:22 2009 GMT',
  valid_to: 'Nov 6 09:52:22 2029 GMT',
  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF',
  fingerprint256: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF:00:11:22:33:44:55:66:77:88:99:AA:BB',
  serialNumber: 'B9B0D332A1AA5635' }

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

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 будет возвращено для сокетов сервера или отключенных сокетов клиента.

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

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

Для получения дополнительной информации см. https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_version.html.

tlsSocket.getSession()

• <Буфер>

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

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

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

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

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

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

tlsSocket.setMaxSendFragment(size)

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

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

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

tls.checkServerIdentity(hostname, cert)[src]

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

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

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

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

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

Объект cert содержит разобранный сертификат и будет иметь структуру, похожую на:

{ 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 ... > }

tls.connect(options[, callback])

• options <Object>

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

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

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

Следующий пример демонстрирует клиент для сервера эха из примера 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 <string> Значение по умолчанию для options.path.
• options <Object> См. tls.connect().
• callback <Function> См. tls.connect().
• Возвращает: <tls.TLSSocket>

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

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

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

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

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

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

tls.createSecureContext([options])

• options <Объект>

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

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

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

Метод tls.createSecureContext() создаёт объект аутентификации.

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

Если параметр 'ca' не указан, Node.js использует список общедоступных доверенных CA, указанных в https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt.

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

• options <Объект>

  • ALPNProtocols: <строковый массив> | <Буферный массив> | <Uint8 массив> | <Буфер> | <Uint8 массив> Массив строк, Buffer или Uint8Array или один Buffer или Uint8Array содержащий поддерживаемые протоколы ALPN. Buffer должны иметь формат [len][name][len][name]... например 0x05hello0x05world, где первый байт — длина следующего имени протокола. Передача массива обычно намного проще, например ['hello', 'world']. (Протоколы должны быть упорядочены по приоритету.)
  • clientCertEngine <строка> Имя OpenSSL модуля, который может предоставить сертификат клиента.
  • handshakeTimeout <число> Прервать соединение, если рукопожатие SSL/TLS не завершится в течение указанного количества миллисекунд. Событие 'tlsClientError' генерируется в объекте tls.Server всякий раз, когда рукопожатие отключается по тайм-ауту. По умолчанию: 120000 (120 секунд).
  • rejectUnauthorized <логическое значение> Если не false, сервер отклонит любое подключение, которое не авторизовано с помощью предоставленного списка центров сертификации. Эта опция действует только, если requestCert равно true. По умолчанию: true.
  • requestCert <логическое значение> Если true, сервер запросит сертификат у подключенных клиентов и попытается проверить этот сертификат. По умолчанию: false.
  • sessionTimeout <функция> Функция, которая будет вызвана, если клиент поддерживает расширение SNI TLS. При вызове будут переданы два аргумента: servername и cb. SNICallback должен вызвать cb(null, ctx), где ctx — это экземпляр SecureContext. (tls.createSecureContext(...) может использоваться для получения правильного SecureContext.) Если SNICallback не был предоставлен, будет использоваться функция обратного вызова по умолчанию с API высокого уровня (см. ниже).
  • ticketKeys: <Буфер> 48 байт криптографически сильных псевдослучайных данных. Дополнительную информацию см. в разделе Возобновление сеанса.
  • ...: Любая опция tls.createSecureContext() может быть предоставлена. Для серверов обычно требуются опции идентификации (pfx или key/cert).
• 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()

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

Возвращает массив с именами поддерживаемых шифров SSL.

console.log(tls.getCiphers()); // ['AES128-SHA', 'AES256-SHA', ...]

tls.DEFAULT_ECDH_CURVE

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

tls.DEFAULT_MAX_VERSION

• <строка> Значение по умолчанию опции maxVersion tls.createSecureContext(). Может быть назначено любое из поддерживаемых версий протокола TLS, 'TLSv1.2', 'TLSv1.1', или 'TLSv1'. По умолчанию: 'TLSv1.2'.

tls.DEFAULT_MIN_VERSION

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

Устаревшие API

Класс: CryptoStream

Класс tls.CryptoStream представляет собой поток зашифрованных данных. Этот класс устарел и больше не должен использоваться.

cryptoStream.bytesWritten

Свойство cryptoStream.bytesWritten возвращает общее количество байтов, записанных в основной сокет, включая байты, необходимые для реализации протокола TLS.

Класс: SecurePair

Возвращается методом tls.createSecurePair().

Событие: 'secure'

Событие 'secure' генерируется объектом SecurePair после установления защищенного соединения.

Как и при проверке события серверного 'secureConnection', следует проверить pair.cleartext.authorized для подтверждения того, что используемый сертификат должным образом авторизован.

tls.createSecurePair([context][, isserver][, requestCert][, rejectunauthorized][, options])

• context <Object> Объект защищённого контекста, возвращаемый tls.createSecureContext()
• isServer <boolean> true для указания, что это соединение TLS должно быть открыто как серверное.
• requestCert <boolean> true для указания, должен ли сервер запрашивать сертификат от подключенного клиента. Применяется только, когда isServer равно true.
• rejectUnauthorized <boolean> Если не false, сервер автоматически отклоняет клиентов с невалидными сертификатами. Применяется только, когда isServer равно true.

• options

  • 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.