TLS (SSL)

Используйте require('tls') для доступа к этому модулю.

Модуль tls использует OpenSSL для обеспечения безопасности транспортного уровня (TLS) и/или уровня защищённых сокетов (SSL): шифрованной потоковой связи.

TLS/SSL использует инфраструктуру открытых/закрытых ключей. Каждый клиент и каждый сервер должны иметь закрытый ключ. Закрытый ключ создаётся так:

openssl genrsa -out ryans-key.pem 2048

Все серверы и некоторые клиенты должны иметь сертификат. Сертификаты — это открытые ключи, подписанные центром сертификации или самоподписанные. Первый шаг для получения сертификата — создание файла "Заявка на подписание сертификата" (CSR). Это делается так:

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

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

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

В качестве альтернативы вы можете отправить CSR в центр сертификации для подписания.

Для обеспечения совершенной прямой секретности необходимо сгенерировать параметры Диффи-Хеллмана:

openssl dhparam -outform PEM -out dhparam.pem 2048

Для создания .pfx или .p12 выполните следующие действия:

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

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

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

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

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

• tls.CLIENT_RENEG_LIMIT: ограничение переподключений, по умолчанию 3.

• tls.CLIENT_RENEG_WINDOW: окно переподключения в секундах, по умолчанию 10 минут.

Не изменяйте значения по умолчанию, если вы не знаете, что делаете.

Для проверки сервера подключитесь к нему с помощью openssl s_client -connect address:port и наберите R<CR> (это буква R, за которой следует возврат каретки) несколько раз.

Изменение набора шифров 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. Например, следующая команда устанавливает ECDHE-RSA-AES128-GCM-SHA256:!RC4 в качестве набора шифров TLS по умолчанию:

node --tls-cipher-list="ECDHE-RSA-AES128-GCM-SHA256:!RC4"

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

ALPN, NPN и SNI

Расширения рукопожатия TLS ALPN (Расширение переговоров на уровне приложения), NPN (Переговоры о следующем протоколе) и SNI (Указание имени сервера) позволяют:

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

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

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

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

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

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

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

Класс: CryptoStream

Это зашифрованный поток.

cryptoStream.bytesWritten

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

Класс: SecurePair

Возвращается tls.createSecurePair.

Событие: 'secure'

Это событие испускается из SecurePair, когда пара успешно установила защищённое соединение.

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

Класс: tls.Server

Этот класс является подклассом net.Server и имеет те же методы. Вместо приема обычных TCP-соединений, он принимает зашифрованные соединения с использованием TLS или SSL.

Событие: 'clientError'

function (exception, tlsSocket) { }

Когда соединение клиента испускает событие 'error' до установления защищённого соединения, оно перенаправляется сюда.

tlsSocket — это tls.TLSSocket, откуда исходит ошибка.

Событие: 'newSession'

function (sessionId, sessionData, callback) { }

Испопускается при создании сессии TLS. Может использоваться для хранения сессий во внешнем хранилище. callback должен быть вызван в конечном итоге, иначе данные не будут отправляться или приниматься по защищённому соединению.

ПРИМЕЧАНИЕ: добавление обработчика этого события повлияет только на подключения, созданные после добавления обработчика.

Событие: 'OCSPRequest'

function (certificate, issuer, callback) { }

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

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

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

Типичный поток:

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

ПРИМЕЧАНИЕ: issuer может быть null, если сертификат самоподписанный или издатель отсутствует в списке корневых сертификатов. (Вы можете предоставить издателя через опцию ca).

ПРИМЕЧАНИЕ: добавление обработчика этого события повлияет только на подключения, созданные после добавления обработчика.

ПРИМЕЧАНИЕ: вы можете использовать модуль npm, такой как asn1.js, для разбора сертификатов.

Событие: 'resumeSession'

function (sessionId, callback) { }

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

ПРИМЕЧАНИЕ: добавление обработчика этого события повлияет только на подключения, созданные после добавления обработчика.

Вот пример использования возобновления сессии TLS:

var 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'

function (tlsSocket) {}

Это событие испускается после успешного рукопожатия нового соединения. Аргументом является экземпляр tls.TLSSocket. Он имеет все обычные методы и события потока.

socket.authorized — логическое значение, указывающее, проверил ли клиент один из предоставленных центров сертификации сервера. Если socket.authorized равно false, то socket.authorizationError содержит описание того, как произошёл отказ в авторизации. Подразумевается, но стоит упомянуть: в зависимости от настроек TLS-сервера, неоправданные соединения могут быть приняты.

socket.npnProtocol — строка, содержащая выбранный протокол NPN, и socket.alpnProtocol — строка, содержащая выбранный протокол ALPN. Когда получены оба расширения NPN и ALPN, ALPN имеет приоритет над NPN, и следующий протокол выбирается по ALPN. Если ALPN не выбрал протокол, это возвращает false.

socket.servername — строка, содержащая имя сервера, запрошенное с помощью SNI.

server.addContext(hostname, context)

Добавляет контекст безопасности, который будет использоваться, если имя хоста запроса клиента SNI совпадает с переданным hostname (могут использоваться подстановочные знаки). context может содержать key, cert, ca и/или любые другие свойства из tls.createSecureContext() аргумента options.

server.address()

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

server.close([callback])

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

server.connections

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

server.getTicketKeys()

Возвращает экземпляр Buffer, содержащий ключи, которые в настоящее время используются для шифрования/расшифрования TLS Session Tickets.

server.listen(port[, hostname][, callback])

Начинает принимать подключения на указанный port и hostname. Если hostname опущено, сервер будет принимать подключения на любой IPv6-адрес (::) при наличии IPv6 или на любой IPv4-адрес (0.0.0.0) в противном случае. Значение порта 0 назначит случайный порт.

Эта функция асинхронная. Последний параметр callback будет вызван, когда сервер будет связан.

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

server.maxConnections

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

server.setTicketKeys(keys)

Обновляет ключи для шифрования/расшифрования TLS Session Tickets.

ПРИМЕЧАНИЕ: буфер должен иметь длину 48 байт. См. опцию сервера ticketKeys для получения дополнительной информации о том, как она будет использоваться.

ПРИМЕЧАНИЕ: изменение вступает в силу только для будущих подключений к серверу. Существующие или ожидающие подключения к серверу будут использовать предыдущие ключи.

Класс: tls.TLSSocket

Это обернутая версия net.Socket, которая выполняет прозрачное шифрование записанных данных и всю необходимую TLS-негациацию.

Этот экземпляр реализует интерфейсы дуплексного потока Stream. Он имеет все общие методы и события потока.

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

new tls.TLSSocket(socket[, options])

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

socket — экземпляр net.Socket.

options — необъект, который может содержать следующие свойства:

• secureContext: Необязательный объект контекста TLS из tls.createSecureContext()

• isServer: Если true, TLS-сокет будет создан в режиме сервера. По умолчанию: false

• server: Необязательный экземпляр net.Server

• requestCert: Необязательно, см. tls.createSecurePair()

• rejectUnauthorized: Необязательно, см. tls.createSecurePair()

• NPNProtocols: Необязательно, см. tls.createServer()

• ALPNProtocols: Необязательно, см. [tls.createServer][]

• SNICallback: Необязательно, см. tls.createServer()

• session: Необязательно, экземпляр Buffer, содержащий TLS-сессию

• requestOCSP: Необязательно, если true, расширение запроса статуса OCSP будет добавлено в приветствие клиента, и событие 'OCSPResponse' будет излучено в сокете перед установлением защищенного соединения

Событие: 'OCSPResponse'

function (response) { }

Это событие будет излучено, если опция requestOCSP была установлена. response — объект буфера, содержащий ответ OCSP сервера.

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

Событие: 'secureConnect'

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

tlsSocket.address()

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

tlsSocket.authorized

Булево значение, которое true если сертификат подтвержденного субъекта был подписан одним из указанных CA, в противном случае false

tlsSocket.authorizationError

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

tlsSocket.encrypted

Статическое булево значение, всегда true. Может быть использовано для различения TLS-сокетов от обычных.

tlsSocket.getCipher()

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

Пример: <name: 'AES256-SHA', version: 'TLSv1/SSLv3'>

См. SSL_CIPHER_get_name() и SSL_CIPHER_get_version() в https://www.openssl.org/docs/man1.0.2/ssl/ssl.html#DEALING-WITH-CIPHERS для получения дополнительной информации.

tlsSocket.getPeerCertificate([ detailed ])

Возвращает объект, представляющий сертификат подтвержденного субъекта. Возвращаемый объект имеет некоторые свойства, соответствующие полю сертификата. Если аргумент detailed равен true, будет возвращена полная цепочка с свойством issuer, если false, только верхний сертификат без свойства issuer.

Пример:

{ subject:
   { C: 'UK',
     ST: 'Acknack Ltd',
     L: 'Rhys Jones',
     O: 'node.js',
     OU: 'Test TLS Certificate',
     CN: 'localhost' },
  issuerInfo:
   { C: 'UK',
     ST: 'Acknack Ltd',
     L: 'Rhys Jones',
     O: 'node.js',
     OU: 'Test TLS Certificate',
     CN: 'localhost' },
  issuer:
   { ... another certificate ... },
  raw: < 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',
  serialNumber: 'B9B0D332A1AA5635' }

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

tlsSocket.getSession()

Возвращает закодированную в ASN.1 TLS-сессию или undefined, если она не была согласована. Может использоваться для ускорения установления рукопожатия при повторном подключении к серверу.

tlsSocket.getTLSTicket()

ПРИМЕЧАНИЕ: работает только с клиентами TLS-сокетами. Полезен только для отладки, для повторного использования сессии предоставьте опцию session к tls.connect().

Возвращает TLS-сессионный билет или undefined если он не был согласован.

tlsSocket.localPort

Числовое представление локального порта.

tlsSocket.localAddress

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

tlsSocket.remoteAddress

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

tlsSocket.remoteFamily

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

tlsSocket.remotePort

Числовое представление удаленного порта. Например, 443.

tlsSocket.renegotiate(options, callback)

Инициализирует процесс повторной TLS-переговоров. options может содержать следующие поля: rejectUnauthorized, requestCert (См. tls.createServer() для получения подробной информации). callback(err) будет выполнен с null как err, как только повторные переговоры будут успешно завершены.

ПРИМЕЧАНИЕ: Может использоваться для запроса сертификата подтвержденного субъекта после установления защищенного соединения.

ЕЩЕ ОДНО ПРИМЕЧАНИЕ: При выполнении в качестве сервера сокет будет уничтожен с ошибкой после таймаута handshakeTimeout.

tlsSocket.setMaxSendFragment(size)

Устанавливает максимальный размер TLS-фрагмента (значение по умолчанию и максимальное значение: 16384, минимальное значение: 512). Возвращает true при успехе, false в противном случае.

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

tls.connect(options[, callback])

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

Создаёт новое клиентское подключение к заданному port и host (старый API) или options.port и options.host. (Если host опущено, оно по умолчанию равно localhost.) options должен быть объектом, который определяет:

• host: Хост, к которому должен подключиться клиент

• port: Порт, к которому должен подключиться клиент

• socket: Установить защищённое соединение на заданном сокете вместо создания нового сокета. Если этот параметр указан, host и port игнорируются.

• path: Создать соединение Unix-сокета по указанному пути. Если этот параметр указан, host и port игнорируются.

• pfx: Строка или Buffer содержащая закрытый ключ, сертификат и сертификаты CA клиента в формате PFX или PKCS12.

• key: Строка или Buffer содержащая закрытый ключ клиента в формате PEM. (Может быть массивом ключей).

• passphrase: Строка пароля для закрытого ключа или pfx.

• cert: Строка или Buffer содержащая сертификат ключа клиента в формате PEM. (Может быть массивом сертификатов).

• ca: Строка, Buffer или массив строк или Buffer доверенных сертификатов в формате PEM. Если это опущено, будут использованы несколько известных "корневых" CA, таких как VeriSign. Они используются для авторизации соединений.

• ciphers: Строка, описывающая используемые или исключаемые шифры, разделённые :. Использует те же шифры по умолчанию, что и tls.createServer().

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

• NPNProtocols: Массив строк или Buffer поддерживаемых протоколов NPN. Buffer должны иметь следующий формат: 0x05hello0x05world, где первый байт — длина следующего имени протокола. (Передача массива обычно намного проще: ['hello', 'world'].)

• ALPNProtocols: Массив строк или Buffer поддерживаемых протоколов ALPN. Buffer должны иметь следующий формат: 0x05hello0x05world, где первый байт — длина следующего имени протокола. (Передача массива обычно намного проще: ['hello', 'world'].)

• servername: Имя сервера для расширения SNI (Server Name Indication) TLS.

• checkServerIdentity(servername, cert): Предоставьте замену для проверки имени хоста сервера по сертификату. Должна возвращать ошибку, если проверка завершится неудачно. Возвращает undefined при успешной передаче.

• secureProtocol: Используемый метод SSL, например, SSLv3_method для принудительного использования версии SSL 3. Возможные значения зависят от вашей установки OpenSSL и определены в константе SSL_METHODS.

• secureContext: Необязательный объект контекста TLS из tls.createSecureContext( ... ). Может использоваться для кэширования сертификатов клиента, ключа и сертификатов CA.

• session: Экземпляр Buffer, содержащий сеанс TLS.

Параметр callback будет добавлен в качестве обработчика события 'secureConnect'.

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

Вот пример клиента эхо-сервера, описанного ранее:

const tls = require('tls');
const fs = require('fs');

const options = {
  // These are necessary only if using the client certificate authentication
  key: fs.readFileSync('client-key.pem'),
  cert: fs.readFileSync('client-cert.pem'),

  // This is necessary only if the server uses the self-signed certificate
  ca: [ fs.readFileSync('server-cert.pem') ]
};

var 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', () => {
  server.close();
});

Или

const tls = require('tls');
const fs = require('fs');

const options = {
  pfx: fs.readFileSync('client.pfx')
};

var 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', () => {
  server.close();
});

tls.createSecureContext(details)

Создаёт объект аутентификации с необязательными деталями, которые представляют собой словарь с ключами:

• pfx : Строка или буфер, содержащий закодированный в PFX или PKCS12 закрытый ключ, сертификат и сертификаты CA
• key: Строка или Buffer, содержащая закрытый ключ сервера в формате PEM. Для поддержки нескольких ключей, использующих различные алгоритмы, можно предоставить массив. Это может быть как обычный массив ключей, так и массив объектов в формате {pem: key, passphrase: passphrase}. (Обязательно)
• passphrase : Строка пароля для закрытого ключа или pfx
• cert : Строка, содержащая закодированный в PEM сертификат
• ca: Строка, Buffer или массив строк или Buffer доверенных сертификатов в формате PEM. Если это опущено, будут использоваться несколько известных "корневых" CA, таких как VeriSign. Они используются для авторизации соединений.
• crl : Строка или список строк с закодированными в PEM CRL (списки отзыва сертификатов)
• ciphers: Строка, описывающая используемые шифры. Для получения подробностей о формате см. https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT.
• honorCipherOrder : При выборе шифра используйте предпочтения сервера вместо предпочтений клиента. Для получения дополнительных сведений см. документацию модуля tls.

Если данные 'ca' не указаны, Node.js будет использовать стандартный общедоступный список доверенных CA, указанный в http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt.

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

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

• credentials: Объект защищённого контекста из tls.createSecureContext( ... )

• isServer: Логическое значение, указывающее, должно ли это TLS-соединение открываться как сервер или клиент.

• requestCert: Логическое значение, указывающее, должен ли сервер запросить сертификат у подключающегося клиента. Применимо только к соединениям сервера.

• rejectUnauthorized: Логическое значение, указывающее, должен ли сервер автоматически отклонять клиентов с недействительными сертификатами. Применимо только к серверам с включённым requestCert.

• options: Объект с общими параметрами SSL. См. tls.TLSSocket.

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

ПРИМЕЧАНИЕ: cleartext имеет те же API, что и tls.TLSSocket

tls.createServer(options[, secureConnectionListener])

Создаёт новый tls.Server. Аргумент connectionListener автоматически устанавливается как обработчик события 'secureConnection'. Объект options имеет следующие возможности:

• pfx: Строка или Buffer, содержащая закрытый ключ, сертификат и сертификаты удостоверяющих центров сервера в формате PFX или PKCS12. (Взаимоисключающие с параметрами key, cert и ca)

• key: Строка или Buffer, содержащая закрытый ключ сервера в формате PEM. Для поддержки нескольких ключей, использующих различные алгоритмы, можно предоставить массив. Это может быть обычный массив ключей или массив объектов в формате {pem: key, passphrase: passphrase}. (Обязательно)

• passphrase: Строка с паролем для закрытого ключа или pfx.

• cert: Строка или Buffer, содержащая ключ сертификата сервера в формате PEM. (Может быть массивом сертификатов). (Обязательно)

• ca: Строка, Buffer или массив строк или Buffer доверенных сертификатов в формате PEM. Если этот параметр опущен, будут использованы несколько известных корневых ЦС, таких как VeriSign. Они используются для авторизации подключений.

• crl: Строка или список строк с кодированными в PEM CRL (списками отзыва сертификатов).

• ciphers: Строка, описывающая используемые или исключенные шифры, разделенные :. Стандартный набор шифров:

  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
  

  Стандартный набор шифров отдает предпочтение шифрам GCM для настроек "современной криптографии" в Chrome, а также предпочитает шифры ECDHE и DHE для обеспечения совершенной прямой секретности, предлагая некоторую обратную совместимость.

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

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

• ecdhCurve: Строка, описывающая имя кривой для использования в согласовании ключей ECDH, или false для отключения ECDH.

  По умолчанию prime256v1 (NIST P-256). Используйте crypto.getCurves() для получения списка доступных имен кривых. В последних версиях openssl ecparam -list_curves также будет отображать имя и описание каждой доступной эллиптической кривой.

• dhparam: Строка или Buffer, содержащая параметры Diffie Hellman, необходимые для совершенной прямой секретности. Используйте openssl dhparam для их создания. Длина ключа должна быть не меньше 1024 бит, иначе произойдет ошибка. Сильно рекомендуется использовать 2048 бит или более для повышения безопасности. Если этот параметр опущен или некорректен, он будет молча игнорироваться, и шифры DHE не будут доступны.

• handshakeTimeout: Прервать подключение, если рукопожатие SSL/TLS не завершится в течение указанного количества миллисекунд. По умолчанию 120 секунд.

  Сообщение 'clientError' будет отправлено на объект tls.Server при истечении времени ожидания рукопожатия.

• honorCipherOrder: При выборе шифра использовать предпочтения сервера вместо предпочтений клиента. По умолчанию: true.

• requestCert: Если true, сервер запросит сертификат у подключившихся клиентов и попытается проверить этот сертификат. По умолчанию: false.

• rejectUnauthorized: Если true, сервер отклонит любое подключение, которое не авторизовано с помощью предоставленного списка ЦС. Этот параметр действует только в том случае, если requestCert равен true. По умолчанию: false.

• NPNProtocols: Массив или Buffer возможных протоколов NPN. (Протоколы должны быть отсортированы по приоритету).

• ALPNProtocols: Массив или Buffer возможных протоколов ALPN. (Протоколы должны быть отсортированы по приоритету). Когда сервер получает оба расширения NPN и ALPN от клиента, ALPN имеет приоритет над NPN, и сервер не отправляет расширение NPN клиенту.

• SNICallback(servername, cb): Функция, которая будет вызвана, если клиент поддерживает расширение TLS SNI. Будут переданы два аргумента: servername, и cb. SNICallback должен вызвать cb(null, ctx), где ctx - экземпляр SecureContext. (Вы можете использовать tls.createSecureContext(...) для получения подходящего SecureContext). Если SNICallback не указан, будет использована функция обратного вызова по API высокого уровня (см. ниже).

• sessionTimeout: Целое число, определяющее секунды, через которые идентификаторы сеансов TLS и билеты сеансов TLS, созданные сервером, сбрасываются. Смотрите SSL_CTX_set_timeout для получения дополнительной информации.

• ticketKeys: Экземпляр Buffer из 48 байт, состоящий из 16-байтового префикса, 16-байтового ключа hmac и 16-байтового ключа AES. Можно использовать для приема билетов сеансов TLS на нескольких экземплярах сервера TLS.

  ПРИМЕЧАНИЕ: Автоматически разделяется между рабочими процессами модуля cluster.

• sessionIdContext: Строка, содержащая неявный идентификатор для возобновления сеанса. Если requestCert равно true, по умолчанию используется значение MD5, сгенерированное из командной строки. (В режиме FIPS вместо этого используется усеченное значение SHA1). В противном случае значение по умолчанию не предоставляется.

• secureProtocol: Используемый метод SSL, например SSLv3_method для принудительного использования версии SSL 3. Возможные значения зависят от вашей установки OpenSSL и определены в константе SSL_METHODS.

Вот простой пример сервера эхо:

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 the client certificate authentication.
  requestCert: true,

  // This is necessary only if the client uses the self-signed certificate.
  ca: [ fs.readFileSync('client-cert.pem') ]
};

var 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');
});

Или

const tls = require('tls');
const fs = require('fs');

const options = {
  pfx: fs.readFileSync('server.pfx'),

  // This is necessary only if using the client certificate authentication.
  requestCert: true,

};

var 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');
});

Вы можете протестировать этот сервер, подключившись к нему с помощью openssl s_client:

openssl s_client -connect 127.0.0.1:8000

tls.getCiphers()

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

Пример:

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