tls

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

import tls from 'node:tls';

Использование в Deno

import * as mod from "node:tls";

class Server

extends net.Server

Использование в Deno

import { Server } from "node:tls";

Принимает зашифрованные соединения с использованием TLS или SSL.

Конструкторы

Server(secureConnectionListener?: (socket: TLSSocket) => void)

new

Server(

options: TlsOptions,

secureConnectionListener?: (socket: TLSSocket) => void,
)

new

Методы

addContext(

hostname: string,

context: SecureContextOptions,
): void

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

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

addListener(

event: string,

listener: (...args: any[]) => void,
): this

events.EventEmitter

tlsClientError
newSession
OCSPRequest
resumeSession
secureConnection
keylog

addListener(

event: "tlsClientError",

listener: (

err: Error,

tlsSocket: TLSSocket,
) => void,
): this

addListener(

event: "newSession",

listener: (

sessionId: Buffer,

sessionData: Buffer,

callback: () => void,
) => void,
): this

addListener(

event: "OCSPRequest",

listener: (

certificate: Buffer,

issuer: Buffer,

callback: (

err: Error | null,

resp: Buffer,
) => void,
) => void,
): this

addListener(

event: "resumeSession",

listener: (

sessionId: Buffer,

callback: (

err: Error | null,

sessionData: Buffer | null,
) => void,
) => void,
): this

addListener(

event: "secureConnection",

listener: (tlsSocket: TLSSocket) => void,
): this

addListener(

event: "keylog",

listener: (

line: Buffer,

tlsSocket: TLSSocket,
) => void,
): this

emit(

event: string | symbol,

...args: any[],
): boolean

emit(

event: "tlsClientError",

err: Error,

tlsSocket: TLSSocket,
): boolean

emit(

event: "newSession",

sessionId: Buffer,

sessionData: Buffer,

callback: () => void,
): boolean

emit(

event: "OCSPRequest",

certificate: Buffer,

issuer: Buffer,

callback: (

err: Error | null,

resp: Buffer,
) => void,
): boolean

emit(

event: "resumeSession",

sessionId: Buffer,

callback: (

err: Error | null,

sessionData: Buffer | null,
) => void,
): boolean

emit(

event: "secureConnection",

tlsSocket: TLSSocket,
): boolean

emit(

event: "keylog",

line: Buffer,

tlsSocket: TLSSocket,
): boolean

getTicketKeys(): Buffer

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

Дополнительную информацию см. в Session Resumption.

on(

event: string,

listener: (...args: any[]) => void,
): this

on(

event: "tlsClientError",

listener: (

err: Error,

tlsSocket: TLSSocket,
) => void,
): this

on(

event: "newSession",

listener: (

sessionId: Buffer,

sessionData: Buffer,

callback: () => void,
) => void,
): this

on(

event: "OCSPRequest",

listener: (

certificate: Buffer,

issuer: Buffer,

callback: (

err: Error | null,

resp: Buffer,
) => void,
) => void,
): this

on(

event: "resumeSession",

listener: (

sessionId: Buffer,

callback: (

err: Error | null,

sessionData: Buffer | null,
) => void,
) => void,
): this

on(

event: "secureConnection",

listener: (tlsSocket: TLSSocket) => void,
): this

on(

event: "keylog",

listener: (

line: Buffer,

tlsSocket: TLSSocket,
) => void,
): this

once(

event: string,

listener: (...args: any[]) => void,
): this

once(

event: "tlsClientError",

listener: (

err: Error,

tlsSocket: TLSSocket,
) => void,
): this

once(

event: "newSession",

listener: (

sessionId: Buffer,

sessionData: Buffer,

callback: () => void,
) => void,
): this

once(

event: "OCSPRequest",

listener: (

certificate: Buffer,

issuer: Buffer,

callback: (

err: Error | null,

resp: Buffer,
) => void,
) => void,
): this

once(

event: "resumeSession",

listener: (

sessionId: Buffer,

callback: (

err: Error | null,

sessionData: Buffer | null,
) => void,
) => void,
): this

once(

event: "secureConnection",

listener: (tlsSocket: TLSSocket) => void,
): this

once(

event: "keylog",

listener: (

line: Buffer,

tlsSocket: TLSSocket,
) => void,
): this

prependListener(

event: string,

listener: (...args: any[]) => void,
): this

prependListener(

event: "tlsClientError",

listener: (

err: Error,

tlsSocket: TLSSocket,
) => void,
): this

prependListener(

event: "newSession",

listener: (

sessionId: Buffer,

sessionData: Buffer,

callback: () => void,
) => void,
): this

prependListener(

event: "OCSPRequest",

listener: (

certificate: Buffer,

issuer: Buffer,

callback: (

err: Error | null,

resp: Buffer,
) => void,
) => void,
): this

prependListener(

event: "resumeSession",

listener: (

sessionId: Buffer,

callback: (

err: Error | null,

sessionData: Buffer | null,
) => void,
) => void,
): this

prependListener(

event: "secureConnection",

listener: (tlsSocket: TLSSocket) => void,
): this

prependListener(

event: "keylog",

listener: (

line: Buffer,

tlsSocket: TLSSocket,
) => void,
): this

prependOnceListener(

event: string,

listener: (...args: any[]) => void,
): this

prependOnceListener(

event: "tlsClientError",

listener: (

err: Error,

tlsSocket: TLSSocket,
) => void,
): this

prependOnceListener(

event: "newSession",

listener: (

sessionId: Buffer,

sessionData: Buffer,

callback: () => void,
) => void,
): this

prependOnceListener(

event: "OCSPRequest",

listener: (

certificate: Buffer,

issuer: Buffer,

callback: (

err: Error | null,

resp: Buffer,
) => void,
) => void,
): this

prependOnceListener(

event: "resumeSession",

listener: (

sessionId: Buffer,

callback: (

err: Error | null,

sessionData: Buffer | null,
) => void,
) => void,
): this

prependOnceListener(

event: "secureConnection",

listener: (tlsSocket: TLSSocket) => void,
): this

prependOnceListener(

event: "keylog",

listener: (

line: Buffer,

tlsSocket: TLSSocket,
) => void,
): this

setSecureContext(options: SecureContextOptions): void

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

setTicketKeys(keys: Buffer): void

Задаёт ключи билетов сеанса.

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

Дополнительную информацию см. в Session Resumption.

class TLSSocket

extends net.Socket

Использование в Deno

import { TLSSocket } from "node:tls";

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

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

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

Конструкторы

TLSSocket(

socket: net.Socket | stream.Duplex,

options?: TLSSocketOptions,
)

new

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

Свойства

alpnProtocol: 
string
 | false
 | null

Строка с выбранным протоколом ALPN. До завершения рукопожатия это значение всегда равно null. Если рукопожатие завершено, но протокол ALPN не выбран, значение tlsSocket.alpnProtocol равно false.

authorizationError: Error

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

authorized: boolean

Это свойство равно true, если сертификат узла подписан одним из центров сертификации, указанных при создании экземпляра tls.TLSSocket; в противном случае оно равно false.

encrypted: true

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

Методы

addListener(

event: string,

listener: (...args: any[]) => void,
): this

addListener(

event: "OCSPResponse",

listener: (response: Buffer) => void,
): this

addListener(

event: "secureConnect",

listener: () => void,
): this

addListener(

event: "session",

listener: (session: Buffer) => void,
): this

addListener(

event: "keylog",

listener: (line: Buffer) => void,
): this

disableRenegotiation(): void

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

emit(

event: string | symbol,

...args: any[],
): boolean

emit(

event: "OCSPResponse",

response: Buffer,
): boolean

emit(event: "secureConnect"): boolean

emit(

event: "session",

session: Buffer,
): boolean

emit(

event: "keylog",

line: Buffer,
): boolean

enableTrace(): void

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

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

exportKeyingMaterial(

length: number,

label: string,

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.

getCertificate(): 
PeerCertificate
 | object
 | null

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

Пример структуры сертификата см. в TLSSocket.getPeerCertificate.

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

getCipher(): CipherNameAndProtocol

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

Например, протокол TLSv1.2 с шифром AES256-SHA:

{
    "name": "AES256-SHA",
    "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
    "version": "SSLv3"
}

Дополнительную информацию см. в SSL_CIPHER_get_name.

getEphemeralKeyInfo(): 
EphemeralKeyInfo
 | object
 | null

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

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

getFinished(): Buffer | undefined

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

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

getPeerCertificate(detailed: true): DetailedPeerCertificate

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

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

getPeerCertificate(detailed?: false): PeerCertificate

getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate

getPeerFinished(): Buffer | undefined

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

getPeerX509Certificate(): X509Certificate | undefined

Возвращает сертификат узла в виде объекта X509Certificate.

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

getProtocol(): string | null

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

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

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

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

getSession(): Buffer | undefined

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

Дополнительную информацию см. в Session Resumption.

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

getSharedSigalgs(): string[]

Дополнительную информацию см. в SSL_get_shared_sigalgs.

getTLSTicket(): Buffer | undefined

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

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

Дополнительную информацию см. в Session Resumption.

getX509Certificate(): X509Certificate | undefined

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

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

isSessionReused(): boolean

Дополнительную информацию см. в Session Resumption.

on(

event: string,

listener: (...args: any[]) => void,
): this

on(

event: "OCSPResponse",

listener: (response: Buffer) => void,
): this

on(

event: "secureConnect",

listener: () => void,
): this

on(

event: "session",

listener: (session: Buffer) => void,
): this

on(

event: "keylog",

listener: (line: Buffer) => void,
): this

once(

event: string,

listener: (...args: any[]) => void,
): this

once(

event: "OCSPResponse",

listener: (response: Buffer) => void,
): this

once(

event: "secureConnect",

listener: () => void,
): this

once(

event: "session",

listener: (session: Buffer) => void,
): this

once(

event: "keylog",

listener: (line: Buffer) => void,
): this

prependListener(

event: string,

listener: (...args: any[]) => void,
): this

prependListener(

event: "OCSPResponse",

listener: (response: Buffer) => void,
): this

prependListener(

event: "secureConnect",

listener: () => void,
): this

prependListener(

event: "session",

listener: (session: Buffer) => void,
): this

prependListener(

event: "keylog",

listener: (line: Buffer) => void,
): this

prependOnceListener(

event: string,

listener: (...args: any[]) => void,
): this

prependOnceListener(

event: "OCSPResponse",

listener: (response: Buffer) => void,
): this

prependOnceListener(

event: "secureConnect",

listener: () => void,
): this

prependOnceListener(

event: "session",

listener: (session: Buffer) => void,
): this

prependOnceListener(

event: "keylog",

listener: (line: Buffer) => void,
): this

renegotiate(

options: { rejectUnauthorized?: boolean | undefined; requestCert?: boolean | undefined;  },

callback: (err: Error | null) => void,
): undefined | boolean

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

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

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

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

setMaxSendFragment(size: number): boolean

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

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

функция checkServerIdentity

Использование в Deno

import { checkServerIdentity } from "node:tls";

checkServerIdentity(

hostname: string,

cert: PeerCertificate,
): Error | undefined

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

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

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

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

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

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

Параметры

hostname: string

Имя хоста или IP-адрес, с которым следует проверить сертификат.

cert: PeerCertificate

certificate object, представляющий сертификат другой стороны.

Тип возвращаемого значения

Error | undefined

функция connect

Использование в Deno

import { connect } from "node:tls";

Перегрузка 1

connect(

options: ConnectionOptions,

secureConnectListener?: () => void,
): TLSSocket

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

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

В отличие от API https, tls.connect() по умолчанию не включает расширение SNI (Server Name Indication), из-за чего некоторые серверы могут вернуть неправильный сертификат или вовсе отклонить соединение. Чтобы включить SNI, задайте параметр servername в дополнение к host.

В следующем примере показан клиент для эхо-сервера из примера createServer:

// Assumes an echo server that is listening on port 8000.
import tls from 'node:tls';
import fs from 'node:fs';

const options = {
  // Necessary only if the server requires client certificate authentication.
  key: fs.readFileSync('client-key.pem'),
  cert: fs.readFileSync('client-cert.pem'),

  // Necessary only if the server uses a self-signed certificate.
  ca: [ fs.readFileSync('server-cert.pem') ],

  // Necessary only if the server's cert isn't for "localhost".
  checkServerIdentity: () => { return null; },
};

const socket = tls.connect(8000, options, () => {
  console.log('client connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  process.stdin.pipe(socket);
  process.stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
  console.log(data);
});
socket.on('end', () => {
  console.log('server ends connection');
});

Параметры

options: ConnectionOptions

secureConnectListener: () => void

необязательный

Тип возвращаемого значения

TLSSocket

Перегрузка 2

connect(

port: number,

host?: string,

options?: ConnectionOptions,

secureConnectListener?: () => void,
): TLSSocket

Параметры

port: number

host: string

необязательный

options: ConnectionOptions

необязательный

secureConnectListener: () => void

необязательный

Тип возвращаемого значения

TLSSocket

Перегрузка 3

connect(

port: number,

options?: ConnectionOptions,

secureConnectListener?: () => void,
): TLSSocket

Параметры

port: number

options: ConnectionOptions

необязательный

secureConnectListener: () => void

необязательный

Тип возвращаемого значения

TLSSocket

функция createSecureContext

Использование в Deno

import { createSecureContext } from "node:tls";

createSecureContext(options?: SecureContextOptions): SecureContext

[createServer](/api/node/tls/ задает значение по умолчанию параметра honorCipherOrder равным true; в других API, создающих контексты безопасности, этот параметр не задан.

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

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

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

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

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

Параметры

options: SecureContextOptions

необязательный

Тип возвращаемого значения

SecureContext

функция createServer

Использование в Deno

import { createServer } from "node:tls";

Перегрузка 1

createServer(secureConnectionListener?: (socket: TLSSocket) => void): Server

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

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

В следующем примере показан простой эхо-сервер:

import tls from 'node:tls';
import fs from 'node:fs';

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),

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

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

const server = tls.createServer(options, (socket) => {
  console.log('server connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  socket.write('welcome!\n');
  socket.setEncoding('utf8');
  socket.pipe(socket);
});
server.listen(8000, () => {
  console.log('server bound');
});

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

Параметры

secureConnectionListener: (socket: TLSSocket) => void

необязательный

Тип возвращаемого значения

Server

Перегрузка 2

createServer(

options: TlsOptions,

secureConnectionListener?: (socket: TLSSocket) => void,
): Server

Параметры

options: TlsOptions

secureConnectionListener: (socket: TLSSocket) => void

необязательный

Тип возвращаемого значения

Server

функция getCiphers

Использование в Deno

import { getCiphers } from "node:tls";

getCiphers(): string[]

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

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

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

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

Тип возвращаемого значения

string[]

функция createSecurePair

Использование в Deno

import { createSecurePair } from "node:tls";

createSecurePair(

context?: SecureContext,

isServer?: boolean,

requestCert?: boolean,

rejectUnauthorized?: boolean,
): SecurePair

Устарело

Совместимость с Deno

В настоящее время этот символ не поддерживается.

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

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

Использование cleartext предоставляет тот же API, что и 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.

Параметры

context: SecureContext

необязательный

Объект контекста безопасности, возвращаемый функцией tls.createSecureContext()

isServer: boolean

необязательный

true, чтобы указать, что это TLS-соединение следует открыть в качестве сервера.

requestCert: boolean

необязательный

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

rejectUnauthorized: boolean

необязательный

Если не задано false, сервер автоматически отклоняет клиентов с недействительными сертификатами. Применяется только в том случае, если isServer равно true.

Тип возвращаемого значения

SecurePair

интерфейс Certificate

Использование в Deno

import { type Certificate } from "node:tls";

Свойства

C: string

Код страны.

ST: string

Улица.

L: string

Населенный пункт.

O: string

Организация.

OU: string

Подразделение организации.

CN: string

Общее имя.

интерфейс CipherNameAndProtocol

Использование в Deno

import { type CipherNameAndProtocol } from "node:tls";

Свойства

name: string

Имя шифра.

version: string

Версия протокола SSL/TLS.

standardName: string

Имя набора шифров в стандарте IETF.

интерфейс CommonConnectionOptions

Использование в Deno

import { type CommonConnectionOptions } from "node:tls";

Свойства

secureContext: SecureContext | undefined

необязательное

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

enableTrace: boolean | undefined

необязательное

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

requestCert: boolean | undefined

необязательное

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

ALPNProtocols: 
string[]
 | Uint8Array[]
 | Uint8Array
 | undefined

необязательное

Массив строк или Buffer с названиями возможных протоколов ALPN. (Протоколы следует расположить в порядке приоритета.)

SNICallback: ((

servername: string,

cb: (

err: Error | null,

ctx?: SecureContext,
) => void,
) => void) | undefined

необязательное

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

rejectUnauthorized: boolean | undefined

необязательное

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

интерфейс ConnectionOptions

расширяет SecureContextOptionsCommonConnectionOptions

Использование в Deno

import { type ConnectionOptions } from "node:tls";

Свойства

host: string | undefined

необязательное

port: number | undefined

необязательное

path: string | undefined

необязательное

socket: stream.Duplex | undefined

необязательное

checkServerIdentity: checkServerIdentity | undefined

необязательное

servername: string | undefined

необязательное

session: Buffer | undefined

необязательное

minDHSize: number | undefined

необязательное

lookup: net.LookupFunction | undefined

необязательное

timeout: number | undefined

необязательное

Методы

pskCallback(hint: string | null): PSKCallbackNegotation | null

необязательное

При согласовании TLS-PSK (предварительно установленных ключей) эта функция вызывается с необязательным идентификатором hint, предоставленным сервером, или null в случае TLS 1.3, где hint был удалён. Для соединения необходимо предоставить собственный tls.checkServerIdentity(), поскольку реализация по умолчанию попытается проверить имя хоста/IP-адрес сервера по сертификату, что неприменимо к PSK, так как сертификат отсутствует. Дополнительные сведения см. в RFC 4279.

интерфейс DetailedPeerCertificate

расширяет PeerCertificate

Использование в Deno

import { type DetailedPeerCertificate } from "node:tls";

Свойства

issuerCertificate: DetailedPeerCertificate

Объект сертификата издателя. Для самоподписанных сертификатов он может содержать циклическую ссылку.

интерфейс EphemeralKeyInfo

Использование в Deno

import { type EphemeralKeyInfo } from "node:tls";

Свойства

type: string

Поддерживаются типы 'DH' и 'ECDH'.

name: string | undefined

необязательное

Свойство name доступно только при значении 'ECDH' для type.

size: number

Размер параметра обмена эфемерными ключами.

интерфейс KeyObject

Использование в Deno

import { type KeyObject } from "node:tls";

Свойства

pem: string | Buffer

Закрытые ключи в формате PEM.

passphrase: string | undefined

необязательное

Необязательная парольная фраза.

интерфейс PeerCertificate

Использование в Deno

import { type PeerCertificate } from "node:tls";

Свойства

ca: boolean

true, если это центр сертификации (CA), false в противном случае.

raw: Buffer

Данные сертификата X.509 в кодировке DER.

subject: Certificate

Субъект сертификата.

issuer: Certificate

Издатель сертификата, описанный в тех же терминах, что и subject.

valid_from: string

Дата и время начала срока действия сертификата.

valid_to: string

Дата и время окончания срока действия сертификата.

serialNumber: string

Серийный номер сертификата в виде шестнадцатеричной строки.

fingerprint: string

Дайджест SHA-1 сертификата в кодировке DER. Возвращается в виде шестнадцатеричной строки с разделителями :.

fingerprint256: string

Дайджест SHA-256 сертификата в кодировке DER. Возвращается в виде шестнадцатеричной строки с разделителями :.

fingerprint512: string

Дайджест SHA-512 сертификата в кодировке DER. Возвращается в виде шестнадцатеричной строки с разделителями :.

ext_key_usage: string[]

необязательное

Расширенное использование ключа — набор OID.

subjectaltname: string

необязательное

Строка, содержащая объединённые имена субъекта и используемая как альтернатива именам subject.

infoAccess: Dict<string[]>

необязательное

Массив с описанием AuthorityInfoAccess, используемым совместно с OCSP.

bits: number

необязательное

Для ключей RSA: размер ключа RSA в битах.

Для ключей EC: размер ключа в битах.

exponent: string

необязательное

Экспонента RSA в виде строки в шестнадцатеричной системе счисления.

modulus: string

необязательное

Модуль RSA в виде шестнадцатеричной строки.

pubkey: Buffer

необязательное

Открытый ключ.

asn1Curve: string

необязательное

Имя ASN.1 для OID эллиптической кривой. Известные кривые определяются с помощью OID. Хотя это необычно, кривая может быть определена своими математическими свойствами; в таком случае у неё не будет OID.

nistCurve: string

необязательное

Название эллиптической кривой по классификации NIST, если оно существует (названия присвоены не всем известным кривым).

интерфейс PSKCallbackNegotation

Использование в Deno

import { type PSKCallbackNegotation } from "node:tls";

Свойства

psk: DataView | TypedArray

identity: string

интерфейс PxfObject

Использование в Deno

import { type PxfObject } from "node:tls";

Свойства

buf: string | Buffer

Закрытый ключ и цепочка сертификатов в кодировке PFX или PKCS12.

passphrase: string | undefined

необязательное

Необязательная парольная фраза.

интерфейс SecureContext

Использование в Deno

import { type SecureContext } from "node:tls";

Свойства

context: any

интерфейс SecureContextOptions

Использование в Deno

import { type SecureContextOptions } from "node:tls";

Свойства

ALPNCallback: ((arg: { servername: string; protocols: string[]; }) => string | undefined) | undefined

необязательное

Если задано, этот обратный вызов будет вызван, когда клиент установит соединение с использованием расширения ALPN. В обратный вызов будет передан один аргумент: объект, содержащий поля servername и protocols, в которых соответственно находятся имя сервера из расширения SNI (если оно есть) и массив строк с именами протоколов ALPN. Обратный вызов должен вернуть либо одну из строк, перечисленных в protocols, которая будет возвращена клиенту как выбранный протокол ALPN, либо undefined, чтобы отклонить соединение с фатальным оповещением. Если будет возвращена строка, не соответствующая ни одному из протоколов ALPN клиента, возникнет ошибка. Этот параметр нельзя использовать вместе с параметром ALPNProtocols; при задании обоих параметров возникнет ошибка.

allowPartialTrustChain: boolean | undefined

необязательное

Считать промежуточные (не самоподписанные) сертификаты в списке доверенных сертификатов CA доверенными.

ca: 
string
 | Buffer
 | Array<string | Buffer>
 | undefined

необязательное

Позволяет переопределить доверенные сертификаты CA. По умолчанию доверенными считаются известные центры сертификации, отобранные Mozilla. Если центры сертификации явно заданы с помощью этого параметра, сертификаты CA Mozilla полностью заменяются.

cert: 
string
 | Buffer
 | Array<string | Buffer>
 | undefined

необязательное

Цепочки сертификатов в формате PEM. Для каждого закрытого ключа следует предоставить одну цепочку сертификатов. Каждая цепочка должна состоять из сертификата в формате PEM для заданного закрытого ключа, за которым следуют промежуточные сертификаты в формате PEM (если есть), в соответствующем порядке; корневой сертификат CA включать не нужно (корневой сертификат CA должен быть заранее известен другой стороне; см. ca). При передаче нескольких цепочек сертификатов их порядок не обязан совпадать с порядком закрытых ключей в key. Если промежуточные сертификаты не предоставлены, другая сторона не сможет проверить сертификат, и согласование завершится ошибкой.

sigalgs: string | undefined

необязательное

Список поддерживаемых алгоритмов подписи, разделённых двоеточиями. Список может содержать алгоритмы хеширования (SHA256, MD5 и т. д.), алгоритмы открытого ключа (RSA-PSS, ECDSA и т. д.), их комбинации (например, 'RSA+SHA384') или имена схем TLS v1.3 (например, rsa_pss_pss_sha512).

ciphers: string | undefined

необязательное

Спецификация наборов шифров, заменяющая используемую по умолчанию. Дополнительные сведения см. в разделе об изменении набора шифров по умолчанию. Список разрешённых шифров можно получить с помощью tls.getCiphers(). Чтобы OpenSSL принял имена шифров, их необходимо указать в верхнем регистре.

clientCertEngine: string | undefined

устарело

необязательное

Имя движка OpenSSL, который может предоставить сертификат клиента.

crl: 
string
 | Buffer
 | Array<string | Buffer>
 | undefined

необязательное

Списки отзыва сертификатов (CRL) в формате PEM.

dhparam: 
string
 | Buffer
 | undefined

необязательное

'auto' или пользовательские параметры Диффи — Хеллмана, необходимые для прямой секретности без ECDHE. Если параметр не задан или недействителен, параметры будут молча отброшены, а шифры DHE будут недоступны. Прямая секретность на основе ECDHE останется доступной.

ecdhCurve: string | undefined

необязательное

Строка с названием кривой или разделённый двоеточиями список NID или названий кривых, например P-521:P-384:P-256, для использования при согласовании ключей ECDH. Укажите auto, чтобы выбрать кривую автоматически. Список доступных названий кривых можно получить с помощью crypto.getCurves(). В последних выпусках openssl ecparam -list_curves также выводит название и описание каждой доступной эллиптической кривой. По умолчанию: tls.DEFAULT_ECDH_CURVE.

honorCipherOrder: boolean | undefined

необязательное

Пытаться использовать предпочтения сервера относительно набора шифров вместо предпочтений клиента. Если значение равно true, для secureOptions устанавливается SSL_OP_CIPHER_SERVER_PREFERENCE.

key: 
string
 | Buffer
 | Array<
string
 | Buffer
 | KeyObject
>
 | undefined

необязательное

Закрытые ключи в формате PEM. В PEM допускается шифрование закрытых ключей. Зашифрованные ключи расшифровываются с помощью options.passphrase. Несколько ключей с разными алгоритмами можно передать в виде массива незашифрованных строк или буферов с ключами либо массива объектов вида {pem: <string|buffer>[, passphrase: ]}. Объекты можно использовать только в массиве. Поле object.passphrase необязательно. Зашифрованные ключи расшифровываются с помощью object.passphrase, если оно задано, или options.passphrase, если нет.

privateKeyEngine: string | undefined

устарело

необязательное

Имя движка OpenSSL, из которого следует получить закрытый ключ. Следует использовать вместе с privateKeyIdentifier.

privateKeyIdentifier: string | undefined

устарело

необязательное

Идентификатор закрытого ключа, управляемого движком OpenSSL. Следует использовать вместе с privateKeyEngine. Не следует задавать одновременно с key, поскольку оба параметра определяют закрытый ключ разными способами.

maxVersion: SecureVersion | undefined

необязательное

Позволяет задать максимальную допустимую версию TLS. Одно из значений 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' или 'TLSv1'. Нельзя задавать вместе с параметром secureProtocol — используйте только один из них. По умолчанию: 'TLSv1.3', если не изменено с помощью параметров CLI. Использование --tls-max-v1.2 устанавливает значение по умолчанию 'TLSv1.2'. Использование --tls-max-v1.3 устанавливает значение по умолчанию 'TLSv1.3'. Если задано несколько таких параметров, используется наибольшее максимальное значение.

minVersion: SecureVersion | undefined

необязательное

Позволяет задать минимальную допустимую версию TLS. Одно из значений 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' или 'TLSv1'. Нельзя задавать вместе с параметром secureProtocol — используйте только один из них. Не рекомендуется использовать версии ниже TLSv1.2, но это может потребоваться для обеспечения совместимости. По умолчанию: 'TLSv1.2', если не изменено с помощью параметров CLI. Использование --tls-v1.0 устанавливает значение по умолчанию 'TLSv1'. Использование --tls-v1.1 устанавливает значение по умолчанию 'TLSv1.1'. Использование --tls-min-v1.3 устанавливает значение по умолчанию 'TLSv1.3'. Если задано несколько таких параметров, используется наименьшее минимальное значение.

passphrase: string | undefined

необязательное

Общая парольная фраза для одного закрытого ключа и/или файла PFX.

pfx: 
string
 | Buffer
 | Array<
string
 | Buffer
 | PxfObject
>
 | undefined

необязательное

Закрытый ключ и цепочка сертификатов в кодировке PFX или PKCS12. pfx является альтернативой отдельной передаче key и cert. Обычно PFX зашифрован; если это так, для его расшифровки используется парольная фраза. Несколько файлов PFX можно передать в виде массива незашифрованных буферов PFX либо массива объектов вида {buf: <string|buffer>[, passphrase: ]}. Объекты можно использовать только в массиве. Поле object.passphrase необязательно. Зашифрованные файлы PFX расшифровываются с помощью object.passphrase, если оно задано, или options.passphrase, если нет.

secureOptions: number | undefined

необязательное

Позволяет изменить поведение протокола OpenSSL, хотя обычно в этом нет необходимости. Используйте этот параметр с осторожностью, если вообще используете! Значение представляет собой числовую битовую маску параметров SSL_OP_* из OpenSSL Options.

secureProtocol: string | undefined

необязательное

Устаревший способ выбора используемой версии протокола TLS. Он не позволяет независимо управлять минимальной и максимальной версиями и не поддерживает ограничение протокола версией TLSv1.3. Вместо него используйте minVersion и maxVersion. Возможные значения перечислены в SSL_METHODS; используйте имена функций в виде строк. Например, укажите 'TLSv1_1_method', чтобы принудительно использовать TLS версии 1.1, или 'TLS_method', чтобы разрешить любую версию протокола TLS вплоть до TLSv1.3. Не рекомендуется использовать версии TLS ниже 1.2, но это может потребоваться для обеспечения совместимости. По умолчанию: none; см. minVersion.

sessionIdContext: string | undefined

необязательное

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

ticketKeys: Buffer | undefined

необязательное

48 байт криптографически стойких псевдослучайных данных. Дополнительные сведения см. в разделе «Возобновление сеанса».

sessionTimeout: number | undefined

необязательное

Количество секунд, по истечении которых сеанс TLS, созданный сервером, нельзя будет возобновить. Дополнительные сведения см. в разделе «Возобновление сеанса». По умолчанию: 300.

интерфейс TlsOptions

расширяет SecureContextOptionsCommonConnectionOptions[net.ServerOpts],

Использование в Deno

import { type TlsOptions } from "node:tls";

Свойства

handshakeTimeout: number | undefined

необязательное

Прервать соединение, если согласование SSL/TLS не завершится за указанное количество миллисекунд. При каждом истечении времени ожидания согласования на объекте tls.Server генерируется событие 'tlsClientError'. По умолчанию: 120000 (120 секунд).

sessionTimeout: number | undefined

необязательное

ticketKeys: Buffer | undefined

необязательное

48 байт криптографически стойких псевдослучайных данных.

pskIdentityHint: string | undefined

необязательное

Подсказка, отправляемая клиенту, чтобы помочь ему выбрать идентификатор при согласовании TLS-PSK. В TLS 1.3 игнорируется. Если не удастся задать pskIdentityHint, будет сгенерировано tlsClientError с кодом ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED.

Методы

pskCallback(

socket: TLSSocket,

identity: string,
): 
DataView
 | TypedArray
 | null

необязательное

интерфейс TLSSocketOptions

расширяет SecureContextOptionsCommonConnectionOptions

Использование в Deno

import { type TLSSocketOptions } from "node:tls";

Свойства

isServer: boolean | undefined

необязательное

Если значение равно true, TLS-сокет создаётся в режиме сервера. По умолчанию — false.

server: net.Server | undefined

необязательное

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

session: Buffer | undefined

необязательное

Необязательный экземпляр Buffer, содержащий сеанс TLS.

requestOCSP: boolean | undefined

необязательное

Если значение равно true, расширение запроса статуса OCSP добавляется в ClientHello, а до установления защищённого соединения на сокете генерируется событие 'OCSPResponse'.

интерфейс SecurePair

Использование в Deno

import { type SecurePair } from "node:tls";

Устарело

начиная с v0.11.3. Вместо этого используйте tls.TLSSocket.

Свойства

encrypted: TLSSocket

cleartext: TLSSocket

псевдоним типа SecureVersion

Использование в Deno

import { type SecureVersion } from "node:tls";

Определение


"TLSv1.3"
 | "TLSv1.2"
 | "TLSv1.1"
 | "TLSv1"

переменная CLIENT_RENEG_LIMIT

Использование в Deno

import { CLIENT_RENEG_LIMIT } from "node:tls";

Тип

number

переменная CLIENT_RENEG_WINDOW

Использование в Deno

import { CLIENT_RENEG_WINDOW } from "node:tls";

Тип

number

переменная DEFAULT_CIPHERS

Использование в Deno

import { DEFAULT_CIPHERS } from "node:tls";

Значение по умолчанию параметра ciphers в createSecureContext(). Ему можно присвоить любой из поддерживаемых шифров OpenSSL. По умолчанию используется содержимое crypto.constants.defaultCoreCipherList, если оно не изменено с помощью параметров CLI, использующих --tls-default-ciphers.

Тип

string

переменная DEFAULT_ECDH_CURVE

Использование в Deno

import { DEFAULT_ECDH_CURVE } from "node:tls";

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

Тип

string

переменная DEFAULT_MAX_VERSION

Использование в Deno

import { DEFAULT_MAX_VERSION } from "node:tls";

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

Тип

SecureVersion

переменная DEFAULT_MIN_VERSION

Использование в Deno

import { DEFAULT_MIN_VERSION } from "node:tls";

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

Тип

SecureVersion

переменная rootCertificates

Использование в Deno

import { rootCertificates } from "node:tls";

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

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

Тип

readonly string[]