iDoc.dev

한국어

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
Русский
العربية

한국어

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
Русский
العربية

테마

TLS (SSL) ​

[Stable: 2 - 안정]

Stable: 2 안정성: 2 - 안정

소스 코드: lib/tls.js

node:tls 모듈은 OpenSSL을 기반으로 구축된 전송 계층 보안(TLS) 및 보안 소켓 계층(SSL) 프로토콜 구현을 제공합니다. 모듈은 다음을 사용하여 액세스할 수 있습니다.

js
import tls from 'node:tls'
js
const tls = require('node:tls')

암호화 지원이 불가능한지 확인 ​

Node.js는 node:crypto 모듈에 대한 지원을 포함하지 않고 빌드될 수 있습니다. 이러한 경우 tls에서 import를 시도하거나 require('node:tls')를 호출하면 오류가 발생합니다.

CommonJS를 사용하는 경우 try/catch를 사용하여 throw된 오류를 포착할 수 있습니다.

js
let tls
try {
  tls = require('node:tls')
} catch (err) {
  console.error('tls 지원이 비활성화되었습니다!')
}

어휘적 ESM import 키워드를 사용하는 경우 모듈 로드 시도 전에 process.on('uncaughtException')에 대한 핸들러가 등록된 경우에만 오류를 포착할 수 있습니다(예: 프리로드 모듈 사용).

ESM을 사용하는 경우, 암호화 지원이 활성화되지 않은 Node.js 빌드에서 코드가 실행될 가능성이 있는 경우 어휘적 import 키워드 대신 import() 함수를 사용하는 것을 고려해 보세요.

js
let tls
try {
  tls = await import('node:tls')
} catch (err) {
  console.error('tls 지원이 비활성화되었습니다!')
}

TLS/SSL 개념 ​

TLS/SSL은 클라이언트와 서버 간의 보안 통신을 활성화하기 위해 공개 키 인프라(PKI)에 의존하는 일련의 프로토콜입니다. 가장 일반적인 경우 각 서버는 개인 키를 가져야 합니다.

개인 키는 여러 가지 방법으로 생성할 수 있습니다. 아래 예는 2048비트 RSA 개인 키를 생성하기 위해 OpenSSL 명령줄 인터페이스를 사용하는 방법을 보여줍니다.

bash
openssl genrsa -out ryans-key.pem 2048

TLS/SSL을 사용하면 모든 서버(및 일부 클라이언트)는 인증서를 가져야 합니다. 인증서는 개인 키에 해당하는 공개 키이며 인증 기관 또는 개인 키 소유자가 디지털 서명합니다(이러한 인증서를 "자체 서명"이라고 함). 인증서를 얻기 위한 첫 번째 단계는 인증서 서명 요청(CSR) 파일을 만드는 것입니다.

OpenSSL 명령줄 인터페이스를 사용하여 개인 키에 대한 CSR을 생성할 수 있습니다.

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

CSR 파일이 생성되면 인증 기관에 서명을 위해 전송하거나 자체 서명된 인증서를 생성하는 데 사용할 수 있습니다.

다음 예에서는 OpenSSL 명령줄 인터페이스를 사용하여 자체 서명된 인증서를 만드는 방법을 보여줍니다.

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

인증서가 생성되면 .pfx 또는 .p12 파일을 생성하는 데 사용할 수 있습니다.

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

여기서:

  • in: 서명된 인증서입니다.
  • inkey: 연결된 개인 키입니다.
  • certfile: 모든 인증 기관(CA) 인증서가 단일 파일로 연결된 것입니다. 예: cat ca1-cert.pem ca2-cert.pem \> ca-cert.pem

완전 순방향 비밀성 ​

순방향 비밀성 또는 완전 순방향 비밀성이라는 용어는 키 합의(즉, 키 교환) 방법의 기능을 설명합니다. 즉, 서버와 클라이언트 키는 현재 통신 세션에만 사용되는 새로운 임시 키를 협상하는 데 사용됩니다. 실제로 이는 서버의 개인 키가 손상된 경우에도 공격자가 세션을 위해 특별히 생성된 키 쌍을 획득한 경우에만 도청자가 통신을 해독할 수 있음을 의미합니다.

완전 순방향 비밀성은 모든 TLS/SSL 핸드셰이크에서 키 합의를 위해 임의로 키 쌍을 생성하여 달성됩니다(모든 세션에 동일한 키를 사용하는 것과 대조적으로). 이 기술을 구현하는 방법을 "임시"라고 합니다.

현재 완전 순방향 비밀성을 달성하기 위해 일반적으로 두 가지 방법이 사용됩니다(기존 약어에 추가된 문자 "E"에 유의).

  • ECDHE: 타원 곡선 Diffie-Hellman 키 합의 프로토콜의 임시 버전입니다.
  • DHE: Diffie-Hellman 키 합의 프로토콜의 임시 버전입니다.

ECDHE를 사용하는 완전 순방향 비밀성은 기본적으로 활성화되어 있습니다. TLS 서버를 생성할 때 ecdhCurve 옵션을 사용하여 사용할 지원되는 ECDH 곡선 목록을 사용자 지정할 수 있습니다. 자세한 내용은 tls.createServer()를 참조하십시오.

DHE는 기본적으로 비활성화되어 있지만 dhparam 옵션을 'auto'로 설정하여 ECDHE와 함께 활성화할 수 있습니다. 사용자 지정 DHE 매개변수도 지원되지만 자동 선택되고 잘 알려진 매개변수를 사용하는 것이 좋습니다.

완전 순방향 비밀성은 TLSv1.2까지 선택 사항이었습니다. TLSv1.3부터 (EC)DHE는 항상 사용됩니다(PSK 전용 연결은 제외).

ALPN 및 SNI ​

ALPN(Application-Layer Protocol Negotiation Extension)과 SNI(Server Name Indication)는 TLS 핸드셰이크 확장입니다.

  • ALPN: 여러 프로토콜(HTTP, HTTP/2)에 하나의 TLS 서버를 사용할 수 있습니다.
  • SNI: 서로 다른 인증서로 여러 호스트 이름에 하나의 TLS 서버를 사용할 수 있습니다.

사전 공유 키 ​

TLS-PSK 지원은 일반적인 인증서 기반 인증의 대안으로 제공됩니다. TLS 연결을 인증하기 위해 인증서 대신 사전 공유 키를 사용하며, 상호 인증을 제공합니다. TLS-PSK와 공개 키 인프라는 상호 배타적이지 않습니다. 클라이언트와 서버는 둘 다 수용할 수 있으며, 일반적인 암호 협상 단계에서 둘 중 하나를 선택할 수 있습니다.

TLS-PSK는 모든 연결 머신과 키를 안전하게 공유할 수 있는 수단이 존재하는 경우에만 좋은 선택이므로, 대부분의 TLS 사용 사례에서 공개 키 인프라(PKI)를 대체하지 않습니다. OpenSSL의 TLS-PSK 구현은 최근 몇 년 동안 많은 보안 결함을 보였는데, 이는 주로 소수의 애플리케이션에서만 사용되기 때문입니다. PSK 암호로 전환하기 전에 모든 대체 솔루션을 고려하십시오. PSK를 생성할 때는 RFC 4086에 설명된 대로 충분한 엔트로피를 사용하는 것이 매우 중요합니다. 비밀번호나 기타 낮은 엔트로피 소스에서 공유 비밀을 파생시키는 것은 안전하지 않습니다.

PSK 암호는 기본적으로 비활성화되어 있으므로 TLS-PSK를 사용하려면 ciphers 옵션으로 암호 스위트를 명시적으로 지정해야 합니다. 사용 가능한 암호 목록은 openssl ciphers -v 'PSK'를 통해 검색할 수 있습니다. 모든 TLS 1.3 암호는 PSK에 적합하며 openssl ciphers -v -s -tls1_3 -psk를 통해 검색할 수 있습니다. 클라이언트 연결에서는 인증서가 없는 경우 기본값이 실패하므로 사용자 지정 checkServerIdentity를 전달해야 합니다.

RFC 4279에 따르면 최대 128바이트 길이의 PSK 식별자와 최대 64바이트 길이의 PSK가 지원되어야 합니다. OpenSSL 1.1.0 현재 최대 식별자 크기는 128바이트이고, 최대 PSK 길이는 256바이트입니다.

현재 구현은 기본 OpenSSL API의 제한으로 인해 비동기 PSK 콜백을 지원하지 않습니다.

TLS-PSK를 사용하려면 클라이언트와 서버가 모두 pskCallback 옵션을 지정해야 하며, 이는 사용할 PSK를 반환하는 함수입니다(선택한 암호의 다이제스트와 호환되어야 함).

클라이언트에서 먼저 호출됩니다.

  • hint: <string> 협상 중에 클라이언트가 사용할 식별자를 결정하는 데 도움이 되도록 서버에서 보낸 선택적 메시지입니다. TLS 1.3을 사용하면 항상 null입니다.
  • 반환: { psk: \<Buffer|TypedArray|DataView\>, identity: \<string\> } 형식의 <Object> 또는 null입니다.

그런 다음 서버에서 다음과 같이 호출됩니다.

null 반환 값은 협상 프로세스를 중단하고 상대방에게 unknown_psk_identity 경고 메시지를 보냅니다. 서버가 PSK 식별자를 알 수 없었다는 사실을 숨기려면 콜백이 협상이 완료되기 전에 연결이 decrypt_error로 실패하도록 psk로 임의 데이터를 제공해야 합니다.

클라이언트 시작 재협상 공격 완화 ​

TLS 프로토콜은 클라이언트가 TLS 세션의 특정 측면을 재협상할 수 있도록 합니다. 안타깝게도 세션 재협상에는 불균형적으로 많은 서버 측 리소스가 필요하므로 서비스 거부 공격의 잠재적인 벡터가 됩니다.

이러한 위험을 완화하기 위해 재협상은 10분마다 3회로 제한됩니다. 이 임계값을 초과하면 tls.TLSSocket 인스턴스에서 'error' 이벤트가 발생합니다. 제한은 구성 가능합니다.

  • tls.CLIENT_RENEG_LIMIT <number> 재협상 요청 횟수를 지정합니다. 기본값: 3.
  • tls.CLIENT_RENEG_WINDOW <number> 재협상 시간 창을 초 단위로 지정합니다. 기본값: 600(10분).

기본 재협상 제한은 의미와 위험을 완전히 이해하지 않고는 수정해서는 안 됩니다.

TLSv1.3은 재협상을 지원하지 않습니다.

세션 재개 ​

TLS 세션을 설정하는 데 시간이 오래 걸릴 수 있습니다. 세션 상태를 저장하고 나중에 재사용하여 프로세스 속도를 높일 수 있습니다. 이를 수행하는 몇 가지 메커니즘이 있으며, 가장 오래된 것부터 최신(및 선호되는) 순서로 여기에서 논의합니다.

세션 식별자 ​

서버는 새 연결에 대한 고유 ID를 생성하여 클라이언트에 보냅니다. 클라이언트와 서버는 세션 상태를 저장합니다. 재연결 시 클라이언트는 저장된 세션 상태의 ID를 보내고 서버도 해당 ID에 대한 상태를 가지고 있으면 해당 상태를 사용하기로 동의할 수 있습니다. 그렇지 않으면 서버는 새 세션을 만듭니다. 자세한 내용은 RFC 2246 23페이지와 30페이지를 참조하세요.

세션 식별자를 사용한 재개는 HTTPS 요청을 할 때 대부분의 웹 브라우저에서 지원됩니다.

Node.js의 경우 클라이언트는 'session' 이벤트가 발생하여 세션 데이터를 가져올 때까지 기다린 후 후속 tls.connect()의 session 옵션에 데이터를 제공하여 세션을 재사용합니다. 서버는 'newSession' 및 'resumeSession' 이벤트에 대한 핸들러를 구현하여 세션 ID를 조회 키로 사용하여 세션 데이터를 저장하고 복원하여 세션을 재사용해야 합니다. 로드 밸런서 또는 클러스터 작업자 간에 세션을 재사용하려면 서버는 세션 핸들러에서 공유 세션 캐시(예: Redis)를 사용해야 합니다.

세션 티켓 ​

서버는 전체 세션 상태를 암호화하여 클라이언트에게 "티켓"으로 보냅니다. 다시 연결할 때 초기 연결 시 상태가 서버로 전송됩니다. 이 메커니즘은 서버 측 세션 캐시의 필요성을 피합니다. 서버가 어떤 이유로든 티켓을 사용하지 않으면(암호 해독 실패, 너무 오래됨 등) 새 세션을 만들고 새 티켓을 보냅니다. 자세한 내용은 RFC 5077을 참조하십시오.

세션 티켓을 사용한 재개는 HTTPS 요청 시 많은 웹 브라우저에서 일반적으로 지원되고 있습니다.

Node.js의 경우 클라이언트는 세션 식별자를 사용한 재개와 세션 티켓을 사용한 재개에 동일한 API를 사용합니다. 디버깅의 경우 tls.TLSSocket.getTLSTicket()이 값을 반환하면 세션 데이터에 티켓이 포함되고, 그렇지 않으면 클라이언트 측 세션 상태가 포함됩니다.

TLSv1.3에서는 서버에서 여러 티켓을 보낼 수 있으며, 이로 인해 여러 'session' 이벤트가 발생할 수 있습니다. 자세한 내용은 'session'을 참조하십시오.

단일 프로세스 서버는 세션 티켓을 사용하기 위한 특정 구현이 필요하지 않습니다. 서버 재시작 또는 로드 밸런서에서 세션 티켓을 사용하려면 모든 서버가 동일한 티켓 키를 가져야 합니다. 내부적으로는 16바이트 키가 3개 있지만 tls API에서는 편의를 위해 단일 48바이트 버퍼로 노출합니다.

하나의 서버 인스턴스에서 server.getTicketKeys()를 호출하여 티켓 키를 가져와 배포할 수 있지만, 48바이트의 안전한 임의 데이터를 안전하게 생성하고 tls.createServer()의 ticketKeys 옵션으로 설정하는 것이 더 합리적입니다. 키는 정기적으로 재생성해야 하며 서버 키는 server.setTicketKeys()로 재설정할 수 있습니다.

세션 티켓 키는 암호화 키이므로 안전하게 저장해야 합니다. TLS 1.2 이하의 경우 손상되면 해당 키로 암호화된 티켓을 사용한 모든 세션의 암호를 해독할 수 있습니다. 디스크에 저장해서는 안 되며 정기적으로 재생성해야 합니다.

클라이언트가 티켓 지원을 알리면 서버에서 티켓을 보냅니다. 서버는 secureOptions에서 require('node:constants').SSL_OP_NO_TICKET을 제공하여 티켓을 비활성화할 수 있습니다.

세션 식별자와 세션 티켓 모두 시간이 초과되어 서버에서 새 세션을 만듭니다. 시간 초과는 tls.createServer()의 sessionTimeout 옵션으로 구성할 수 있습니다.

모든 메커니즘에서 재개가 실패하면 서버에서 새 세션을 만듭니다. 세션 재개 실패는 TLS/HTTPS 연결 실패를 유발하지 않으므로 불필요하게 좋지 않은 TLS 성능을 알아차리지 못하기 쉽습니다. OpenSSL CLI를 사용하여 서버가 세션을 재개하고 있는지 확인할 수 있습니다. 예를 들어 openssl s_client에 -reconnect 옵션을 사용합니다.

bash
openssl s_client -connect localhost:443 -reconnect

디버그 출력을 읽어보십시오. 첫 번째 연결은 다음과 같이 "New"라고 표시되어야 합니다.

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

이후 연결은 다음과 같이 "Reused"라고 표시되어야 합니다.

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

기본 TLS 암호 스위트 수정 ​

Node.js는 활성화 및 비활성화된 TLS 암호의 기본 스위트를 사용하여 빌드됩니다. 이 기본 암호 목록은 Node.js를 빌드할 때 구성하여 배포에서 자체 기본 목록을 제공할 수 있도록 할 수 있습니다.

다음 명령을 사용하여 기본 암호 스위트를 표시할 수 있습니다.

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

이 기본값은 --tls-cipher-list 명령줄 스위치(직접 또는 NODE_OPTIONS 환경 변수를 통해)를 사용하여 전체적으로 대체할 수 있습니다. 예를 들어, 다음은 ECDHE-RSA-AES128-GCM-SHA256:!RC4를 기본 TLS 암호 스위트로 만듭니다.

bash
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

확인하려면 다음 명령을 사용하여 설정된 암호 목록을 표시하고 defaultCoreCipherList와 defaultCipherList의 차이점을 확인하십시오.

bash
node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n'
ECDHE-RSA-AES128-GCM-SHA256
!RC4

즉, defaultCoreCipherList 목록은 컴파일 시간에 설정되고 defaultCipherList는 런타임에 설정됩니다.

런타임 내에서 기본 암호 스위트를 수정하려면 tls.DEFAULT_CIPHERS 변수를 수정해야 하며, 이는 소켓을 수신하기 전에 수행해야 하며 이미 열린 소켓에는 영향을 미치지 않습니다. 예를 들어:

js
// 순방향 보안을 제공하지 않으므로 더 이상 사용되지 않는 CBC 암호 및 RSA 키 교환 기반 암호 제거
tls.DEFAULT_CIPHERS +=
  ':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' +
  ':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' +
  ':!kRSA'

기본값은 tls.createSecureContext()의 ciphers 옵션을 사용하여 클라이언트 또는 서버별로 대체할 수도 있습니다. 이 옵션은 tls.createServer(), tls.connect() 및 새로운 tls.TLSSocket을 생성할 때도 사용할 수 있습니다.

암호 목록에는 'TLS_'로 시작하는 TLSv1.3 암호 스위트 이름과 TLSv1.2 이하 암호 스위트에 대한 사양이 혼합되어 있을 수 있습니다. TLSv1.2 암호는 레거시 사양 형식을 지원하며, 자세한 내용은 OpenSSL 암호 목록 형식 설명서를 참조하십시오. 그러나 이러한 사양은 TLSv1.3 암호에는 적용되지 않습니다. TLSv1.3 스위트는 암호 목록에 전체 이름을 포함해야만 활성화할 수 있습니다. 예를 들어 레거시 TLSv1.2 'EECDH' 또는 '!EECDH' 사양을 사용하여 활성화하거나 비활성화할 수 없습니다.

TLSv1.3과 TLSv1.2 암호 스위트의 상대적 순서에도 불구하고 TLSv1.3 프로토콜은 TLSv1.2보다 훨씬 더 안전하며, 핸드셰이크에서 지원됨을 나타내고 TLSv1.3 암호 스위트가 활성화된 경우 항상 TLSv1.2보다 우선적으로 선택됩니다.

Node.js에 포함된 기본 암호 스위트는 현재 보안 모범 사례 및 위험 완화를 반영하도록 신중하게 선택되었습니다. 기본 암호 스위트를 변경하면 응용 프로그램의 보안에 상당한 영향을 미칠 수 있습니다. --tls-cipher-list 스위치와 ciphers 옵션은 절대적으로 필요한 경우에만 사용해야 합니다.

기본 암호 스위트는 Chrome의 '최신 암호화' 설정에 대해 GCM 암호를 선호하고, 완벽한 순방향 보안을 위해 ECDHE 및 DHE 암호를 선호하며, 일부 이전 버전과의 호환성을 제공합니다.

안전하지 않고 더 이상 사용되지 않는 RC4 또는 DES 기반 암호(예: Internet Explorer 6)에 의존하는 이전 클라이언트는 기본 구성으로 핸드셰이크 프로세스를 완료할 수 없습니다. 이러한 클라이언트를 반드시 지원해야 하는 경우 TLS 권장 사항에서 호환되는 암호 스위트를 제공할 수 있습니다. 형식에 대한 자세한 내용은 OpenSSL 암호 목록 형식 설명서를 참조하십시오.

TLSv1.3 암호 스위트는 5개뿐입니다.

  • 'TLS_AES_256_GCM_SHA384'
  • 'TLS_CHACHA20_POLY1305_SHA256'
  • 'TLS_AES_128_GCM_SHA256'
  • 'TLS_AES_128_CCM_SHA256'
  • 'TLS_AES_128_CCM_8_SHA256'

처음 세 개는 기본적으로 활성화되어 있습니다. 두 개의 CCM 기반 스위트는 제약된 시스템에서 더 나은 성능을 제공할 수 있으므로 TLSv1.3에서 지원되지만 보안성이 떨어지기 때문에 기본적으로 활성화되어 있지 않습니다.

OpenSSL 보안 수준 ​

OpenSSL 라이브러리는 암호화 작업에 대한 최소 허용 보안 수준을 제어하기 위해 보안 수준을 적용합니다. OpenSSL의 보안 수준은 0에서 5까지이며, 각 수준은 더 엄격한 보안 요구 사항을 부과합니다. 기본 보안 수준은 1이며, 이는 일반적으로 대부분의 최신 응용 프로그램에 적합합니다. 그러나 TLSv1과 같은 일부 레거시 기능 및 프로토콜은 제대로 작동하려면 더 낮은 보안 수준(SECLEVEL=0)이 필요합니다. 자세한 내용은 보안 수준에 대한 OpenSSL 문서를 참조하십시오.

보안 수준 설정 ​

Node.js 애플리케이션에서 보안 수준을 조정하려면 암호 문자열 내에 @SECLEVEL=X를 포함할 수 있습니다. 여기서 X는 원하는 보안 수준입니다. 예를 들어 기본 OpenSSL 암호 목록을 사용하는 동안 보안 수준을 0으로 설정하려면 다음을 사용할 수 있습니다.

js
import { createServer, connect } from 'node:tls'
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('클라이언트가 다음 프로토콜로 연결됨:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})
js
const { createServer, connect } = require('node:tls')
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('클라이언트가 다음 프로토콜로 연결됨:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

이 방법은 보안 수준을 0으로 설정하여 레거시 기능을 사용하면서도 기본 OpenSSL 암호를 활용할 수 있도록 합니다.

사용법 ​

기본 TLS 암호 스위트 수정에 설명된 대로 --tls-cipher-list=DEFAULT@SECLEVEL=X를 사용하여 명령줄에서 보안 수준과 암호를 설정할 수도 있습니다. 그러나 일반적으로 명령줄 옵션을 사용하여 암호를 설정하는 것은 권장되지 않으며, 응용 프로그램 코드 내에서 개별 컨텍스트에 대한 암호를 구성하는 것이 바람직합니다. 이 방법이 더 나은 제어를 제공하고 보안 수준을 전역적으로 낮추는 위험을 줄이기 때문입니다.

X509 인증서 오류 코드 ​

OpenSSL에서 보고하는 인증서 오류로 인해 여러 함수가 실패할 수 있습니다. 이러한 경우, 함수는 code 속성이 다음 값 중 하나를 가질 수 있는 <Error>를 콜백을 통해 제공합니다.

  • 'UNABLE_TO_GET_ISSUER_CERT': 발급자 인증서를 가져올 수 없습니다.
  • 'UNABLE_TO_GET_CRL': 인증서 CRL을 가져올 수 없습니다.
  • 'UNABLE_TO_DECRYPT_CERT_SIGNATURE': 인증서의 서명을 해독할 수 없습니다.
  • 'UNABLE_TO_DECRYPT_CRL_SIGNATURE': CRL의 서명을 해독할 수 없습니다.
  • 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY': 발급자 공개 키를 디코딩할 수 없습니다.
  • 'CERT_SIGNATURE_FAILURE': 인증서 서명 실패.
  • 'CRL_SIGNATURE_FAILURE': CRL 서명 실패.
  • 'CERT_NOT_YET_VALID': 인증서가 아직 유효하지 않습니다.
  • 'CERT_HAS_EXPIRED': 인증서가 만료되었습니다.
  • 'CRL_NOT_YET_VALID': CRL이 아직 유효하지 않습니다.
  • 'CRL_HAS_EXPIRED': CRL이 만료되었습니다.
  • 'ERROR_IN_CERT_NOT_BEFORE_FIELD': 인증서의 notBefore 필드에 형식 오류가 있습니다.
  • 'ERROR_IN_CERT_NOT_AFTER_FIELD': 인증서의 notAfter 필드에 형식 오류가 있습니다.
  • 'ERROR_IN_CRL_LAST_UPDATE_FIELD': CRL의 lastUpdate 필드에 형식 오류가 있습니다.
  • 'ERROR_IN_CRL_NEXT_UPDATE_FIELD': CRL의 nextUpdate 필드에 형식 오류가 있습니다.
  • 'OUT_OF_MEM': 메모리 부족.
  • 'DEPTH_ZERO_SELF_SIGNED_CERT': 자체 서명된 인증서.
  • 'SELF_SIGNED_CERT_IN_CHAIN': 인증서 체인에 자체 서명된 인증서가 있습니다.
  • 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY': 로컬 발급자 인증서를 가져올 수 없습니다.
  • 'UNABLE_TO_VERIFY_LEAF_SIGNATURE': 첫 번째 인증서를 확인할 수 없습니다.
  • 'CERT_CHAIN_TOO_LONG': 인증서 체인이 너무 깁니다.
  • 'CERT_REVOKED': 인증서가 취소되었습니다.
  • 'INVALID_CA': 잘못된 CA 인증서.
  • 'PATH_LENGTH_EXCEEDED': 경로 길이 제약 조건을 초과했습니다.
  • 'INVALID_PURPOSE': 지원되지 않는 인증서 목적.
  • 'CERT_UNTRUSTED': 신뢰할 수 없는 인증서.
  • 'CERT_REJECTED': 인증서가 거부되었습니다.
  • 'HOSTNAME_MISMATCH': 호스트 이름 불일치.

클래스: tls.CryptoStream ​

추가된 버전: v0.3.4

더 이상 사용되지 않음: v0.11.3

[안정성: 0 - 더 이상 사용되지 않음]

안정성: 0 안정성: 0 - 더 이상 사용되지 않음: 대신 tls.TLSSocket을 사용하세요.

tls.CryptoStream 클래스는 암호화된 데이터 스트림을 나타냅니다. 이 클래스는 더 이상 사용되지 않으며 사용해서는 안 됩니다.

cryptoStream.bytesWritten ​

추가된 버전: v0.3.4

더 이상 사용되지 않음: v0.11.3

cryptoStream.bytesWritten 속성은 TLS 프로토콜 구현에 필요한 바이트를 포함하여 기본 소켓에 쓰여진 총 바이트 수를 반환합니다.

클래스: tls.SecurePair ​

추가된 버전: v0.3.2

더 이상 사용되지 않음: v0.11.3

[안정성: 0 - 더 이상 사용되지 않음]

안정성: 0 안정성: 0 - 더 이상 사용되지 않음: 대신 tls.TLSSocket을 사용하세요.

tls.createSecurePair()에서 반환됩니다.

이벤트: 'secure' ​

추가된 버전: v0.3.2

더 이상 사용되지 않음: v0.11.3

보안 연결이 설정되면 'secure' 이벤트가 SecurePair 객체에서 발생합니다.

서버 'secureConnection' 이벤트 확인과 마찬가지로, 사용된 인증서가 올바르게 인증되었는지 확인하기 위해 pair.cleartext.authorized를 검사해야 합니다.

클래스: tls.Server ​

추가된 버전: v0.3.2

TLS 또는 SSL을 사용하여 암호화된 연결을 수락합니다.

이벤트: 'connection' ​

추가된 버전: v0.3.2

이 이벤트는 TLS 핸드셰이크가 시작되기 전에 새 TCP 스트림이 설정될 때 발생합니다. socket은 일반적으로 net.Socket 유형의 객체이지만 net.Server 'connection' 이벤트에서 생성된 소켓과는 달리 이벤트를 수신하지 않습니다. 일반적으로 사용자는 이 이벤트에 액세스하고 싶지 않을 것입니다.

이 이벤트는 사용자가 TLS 서버에 연결을 삽입하기 위해 명시적으로 발생시킬 수도 있습니다. 이 경우, 임의의 Duplex 스트림을 전달할 수 있습니다.

이벤트: 'keylog' ​

추가된 버전: v12.3.0, v10.20.0

  • line <Buffer> NSS SSLKEYLOGFILE 형식의 ASCII 텍스트 줄입니다.
  • tlsSocket <tls.TLSSocket> 이벤트가 생성된 tls.TLSSocket 인스턴스입니다.

keylog 이벤트는 이 서버에 대한 연결에 의해 키 자료가 생성되거나 수신될 때(일반적으로 핸드셰이크가 완료되기 전이지만 필수는 아님) 발생합니다. 이 키 자료는 캡처된 TLS 트래픽을 해독할 수 있으므로 디버깅을 위해 저장할 수 있습니다. 각 소켓에 대해 여러 번 발생할 수 있습니다.

일반적인 사용 사례는 수신된 줄을 공통 텍스트 파일에 추가하는 것입니다. 이 파일은 나중에 소프트웨어(예: Wireshark)에서 트래픽을 해독하는 데 사용됩니다.

js
const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...') return // 특정 IP에 대한 키만 로깅
  logFile.write(line)
})

이벤트: 'newSession' ​

[기록]

버전변경 사항
v0.11.12callback 인수가 이제 지원됩니다.
v0.9.2추가된 버전: v0.9.2

'newSession' 이벤트는 새 TLS 세션이 생성될 때 발생합니다. 이는 세션을 외부 저장소에 저장하는 데 사용할 수 있습니다. 데이터는 'resumeSession' 콜백에 제공되어야 합니다.

리스너 콜백은 호출될 때 세 개의 인수를 전달받습니다.

  • sessionId <Buffer> TLS 세션 식별자
  • sessionData <Buffer> TLS 세션 데이터
  • callback <Function> 보안 연결을 통해 데이터를 보내거나 받으려면 호출해야 하는 인수가 없는 콜백 함수

이 이벤트에 대한 리스닝은 이벤트 리스너를 추가한 후에 설정된 연결에만 영향을 미칩니다.

이벤트: 'OCSPRequest' ​

추가된 버전: v0.11.13

'OCSPRequest' 이벤트는 클라이언트가 인증서 상태 요청을 보낼 때 발생합니다. 리스너 콜백은 호출될 때 세 개의 인수를 전달받습니다.

  • certificate <Buffer> 서버 인증서
  • issuer <Buffer> 발급자의 인증서
  • callback <Function> OCSP 요청 결과를 제공하기 위해 호출해야 하는 콜백 함수

서버의 현재 인증서를 파싱하여 OCSP URL 및 인증서 ID를 얻을 수 있습니다. OCSP 응답을 얻은 후 callback(null, resp)가 호출됩니다. 여기서 resp는 OCSP 응답을 포함하는 Buffer 인스턴스입니다. certificate와 issuer 모두 기본 인증서와 발급자의 인증서의 Buffer DER 표현입니다. 이는 OCSP 인증서 ID 및 OCSP 엔드포인트 URL을 얻는 데 사용할 수 있습니다.

또는 callback(null, null)을 호출하여 OCSP 응답이 없음을 나타낼 수도 있습니다.

callback(err)를 호출하면 socket.destroy(err) 호출이 발생합니다.

OCSP 요청의 일반적인 흐름은 다음과 같습니다.

인증서가 자체 서명되었거나 발급자가 루트 인증서 목록에 없는 경우 issuer는 null일 수 있습니다. (TLS 연결을 설정할 때 ca 옵션을 통해 발급자를 제공할 수 있습니다.)

이 이벤트에 대한 리스닝은 이벤트 리스너를 추가한 후에 설정된 연결에만 영향을 미칩니다.

asn1.js와 같은 npm 모듈을 사용하여 인증서를 파싱할 수 있습니다.

이벤트: 'resumeSession' ​

추가된 버전: v0.9.2

클라이언트가 이전 TLS 세션을 재개하려고 요청할 때 'resumeSession' 이벤트가 발생합니다. 리스너 콜백이 호출될 때 두 개의 인수가 전달됩니다:

  • sessionId <Buffer> TLS 세션 식별자
  • callback <Function> 이전 세션이 복구되었을 때 호출되는 콜백 함수: callback([err[, sessionData]])

이벤트 리스너는 주어진 sessionId를 사용하여 'newSession' 이벤트 핸들러에 의해 저장된 sessionData에 대한 외부 저장소 조회를 수행해야 합니다. 찾았다면 세션을 재개하기 위해 callback(null, sessionData)를 호출합니다. 찾지 못했다면 세션을 재개할 수 없습니다. 핸드셰이크가 계속되고 새 세션이 생성될 수 있도록 sessionData 없이 callback()을 호출해야 합니다. 들어오는 연결을 종료하고 소켓을 파괴하기 위해 callback(err)를 호출할 수 있습니다.

이 이벤트에 대한 리스닝은 이벤트 리스너가 추가된 후에 설정된 연결에만 영향을 미칩니다.

다음은 TLS 세션 재개를 보여줍니다:

js
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' ​

추가된 버전: v0.3.2

새 연결에 대한 핸드셰이킹 프로세스가 성공적으로 완료된 후 'secureConnection' 이벤트가 발생합니다. 리스너 콜백이 호출될 때 단일 인수가 전달됩니다:

tlsSocket.authorized 속성은 클라이언트가 서버에 제공된 인증 기관 중 하나에 의해 검증되었는지 여부를 나타내는 boolean 값입니다. tlsSocket.authorized가 false이면 socket.authorizationError가 인증 실패 방법을 설명하도록 설정됩니다. TLS 서버 설정에 따라 인증되지 않은 연결도 허용될 수 있습니다.

tlsSocket.alpnProtocol 속성은 선택된 ALPN 프로토콜을 포함하는 문자열입니다. 클라이언트 또는 서버가 ALPN 확장을 보내지 않아 ALPN에 선택된 프로토콜이 없는 경우 tlsSocket.alpnProtocol은 false와 같습니다.

tlsSocket.servername 속성은 SNI를 통해 요청된 서버 이름을 포함하는 문자열입니다.

이벤트: 'tlsClientError' ​

추가된 버전: v6.0.0

'tlsClientError' 이벤트는 보안 연결이 설정되기 전에 오류가 발생했을 때 발생합니다. 리스너 콜백은 호출될 때 두 개의 인수를 전달받습니다.

  • exception <Error> 오류를 설명하는 Error 객체
  • tlsSocket <tls.TLSSocket> 오류가 발생한 tls.TLSSocket 인스턴스

server.addContext(hostname, context) ​

추가된 버전: v0.5.3

server.addContext() 메서드는 클라이언트 요청의 SNI 이름이 제공된 hostname(또는 와일드카드)과 일치하는 경우에 사용될 보안 컨텍스트를 추가합니다.

여러 개의 일치하는 컨텍스트가 있는 경우, 가장 최근에 추가된 컨텍스트가 사용됩니다.

server.address() ​

추가된 버전: v0.6.0

운영 체제에서 보고한 바인딩된 주소, 주소 패밀리 이름 및 서버 포트를 반환합니다. 자세한 내용은 net.Server.address()를 참조하십시오.

server.close([callback]) ​

추가된 버전: v0.3.2

  • callback <Function> 서버 인스턴스의 'close' 이벤트를 수신하기 위해 등록될 리스너 콜백.
  • 반환 값: <tls.Server>

server.close() 메서드는 서버가 새 연결을 수락하는 것을 중지합니다.

이 함수는 비동기적으로 작동합니다. 서버에 더 이상 열린 연결이 없으면 'close' 이벤트가 발생합니다.

server.getTicketKeys() ​

추가된 버전: v3.0.0

  • 반환값: <Buffer> 세션 티켓 키를 포함하는 48바이트 버퍼입니다.

세션 티켓 키를 반환합니다.

자세한 내용은 세션 재개를 참조하십시오.

server.listen() ​

암호화된 연결을 수신하기 위해 서버를 시작합니다. 이 메서드는 net.Server의 server.listen()과 동일합니다.

server.setSecureContext(options) ​

추가된 버전: v11.0.0

server.setSecureContext() 메서드는 기존 서버의 보안 컨텍스트를 대체합니다. 서버에 대한 기존 연결은 중단되지 않습니다.

server.setTicketKeys(keys) ​

추가된 버전: v3.0.0

세션 티켓 키를 설정합니다.

티켓 키 변경 사항은 향후 서버 연결에만 적용됩니다. 기존 또는 현재 보류 중인 서버 연결은 이전 키를 사용합니다.

자세한 내용은 세션 재개를 참조하십시오.

클래스: tls.TLSSocket ​

추가된 버전: v0.11.4

기록된 데이터의 투명한 암호화 및 필요한 모든 TLS 협상을 수행합니다.

tls.TLSSocket의 인스턴스는 이중 Stream 인터페이스를 구현합니다.

TLS 연결 메타데이터를 반환하는 메서드(예: tls.TLSSocket.getPeerCertificate())는 연결이 열려 있는 동안에만 데이터를 반환합니다.

new tls.TLSSocket(socket[, options]) ​

[History]

버전변경 사항
v12.2.0enableTrace 옵션이 이제 지원됩니다.
v5.0.0ALPN 옵션이 이제 지원됩니다.
v0.11.4v0.11.4에서 추가됨
  • socket <net.Socket> | <stream.Duplex> 서버 측에서는 모든 Duplex 스트림. 클라이언트 측에서는 net.Socket의 모든 인스턴스(클라이언트 측에서 일반 Duplex 스트림 지원의 경우 tls.connect()를 사용해야 함).
  • options <Object>
    • enableTrace: tls.createServer() 참조
    • isServer: SSL/TLS 프로토콜은 비대칭적이며, TLSSocket은 서버 또는 클라이언트로 동작해야 하는지 알아야 합니다. true인 경우 TLS 소켓은 서버로 인스턴스화됩니다. 기본값: false.
    • server <net.Server> net.Server 인스턴스.
    • requestCert: 원격 피어에게 인증서를 요청하여 인증할지 여부. 클라이언트는 항상 서버 인증서를 요청합니다. 서버(isServer가 true)는 클라이언트 인증서를 요청하기 위해 requestCert를 true로 설정할 수 있습니다.
    • rejectUnauthorized: tls.createServer() 참조
    • ALPNProtocols: tls.createServer() 참조
    • SNICallback: tls.createServer() 참조
    • session <Buffer> TLS 세션을 포함하는 Buffer 인스턴스.
    • requestOCSP <boolean> true인 경우 OCSP 상태 요청 확장이 클라이언트 hello에 추가되고 보안 통신을 설정하기 전에 소켓에서 'OCSPResponse' 이벤트가 발생하도록 지정합니다.
    • secureContext: tls.createSecureContext()로 생성된 TLS 컨텍스트 객체. secureContext가 제공되지 않은 경우 전체 options 객체를 tls.createSecureContext()에 전달하여 하나가 생성됩니다.
    • ...: secureContext 옵션이 누락된 경우 사용되는 tls.createSecureContext() 옵션입니다. 그렇지 않으면 무시됩니다.

기존 TCP 소켓에서 새 tls.TLSSocket 객체를 생성합니다.

이벤트: 'keylog' ​

추가된 버전: v12.3.0, v10.20.0

  • line <Buffer> NSS SSLKEYLOGFILE 형식의 ASCII 텍스트 줄입니다.

keylog 이벤트는 키 자료가 소켓에 의해 생성되거나 수신될 때 tls.TLSSocket에서 발생합니다. 이 키 자료는 캡처된 TLS 트래픽을 해독할 수 있으므로 디버깅을 위해 저장할 수 있습니다. 핸드셰이크가 완료되기 전후에 여러 번 발생할 수 있습니다.

일반적인 사용 사례는 수신된 줄을 일반 텍스트 파일에 추가하는 것입니다. 이 파일은 나중에 (Wireshark와 같은) 소프트웨어에서 트래픽을 해독하는 데 사용됩니다.

js
const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
tlsSocket.on('keylog', line => logFile.write(line))

이벤트: 'OCSPResponse' ​

추가된 버전: v0.11.13

tls.TLSSocket이 생성될 때 requestOCSP 옵션이 설정되고 OCSP 응답이 수신된 경우 'OCSPResponse' 이벤트가 발생합니다. 리스너 콜백은 호출될 때 단일 인수를 전달받습니다.

  • response <Buffer> 서버의 OCSP 응답입니다.

일반적으로 response는 서버의 인증서 해지 상태에 대한 정보를 포함하는 서버 CA의 디지털 서명된 객체입니다.

이벤트: 'secureConnect' ​

추가된 버전: v0.11.4

새 연결에 대한 핸드셰이킹 프로세스가 성공적으로 완료된 후 'secureConnect' 이벤트가 발생합니다. 리스너 콜백은 서버 인증서가 승인되었는지 여부에 관계없이 호출됩니다. 서버 인증서가 지정된 CA 중 하나에서 서명되었는지 여부를 확인하는 것은 클라이언트의 책임입니다. tlsSocket.authorized === false인 경우 tlsSocket.authorizationError 속성을 검사하여 오류를 찾을 수 있습니다. ALPN이 사용된 경우 tlsSocket.alpnProtocol 속성을 검사하여 협상된 프로토콜을 확인할 수 있습니다.

new tls.TLSSocket() 생성자를 사용하여 <tls.TLSSocket>이 생성되면 'secureConnect' 이벤트가 발생하지 않습니다.

Event: 'session' ​

Added in: v11.10.0

'session' 이벤트는 새 세션 또는 TLS 티켓이 사용 가능할 때 클라이언트 tls.TLSSocket에서 발생합니다. 이는 협상된 TLS 프로토콜 버전에 따라 핸드셰이크가 완료되기 전일 수도 있고 아닐 수도 있습니다. 서버에서는 이벤트가 발생하지 않거나, 연결이 재개된 경우와 같이 새 세션이 생성되지 않은 경우에는 발생하지 않습니다. 일부 TLS 프로토콜 버전의 경우 이벤트가 여러 번 발생할 수 있으며, 이 경우 모든 세션을 재개에 사용할 수 있습니다.

클라이언트에서 session은 tls.connect()의 session 옵션에 제공하여 연결을 재개할 수 있습니다.

자세한 내용은 세션 재개를 참조하십시오.

TLSv1.2 이하의 경우 핸드셰이크가 완료되면 tls.TLSSocket.getSession()을 호출할 수 있습니다. TLSv1.3의 경우 프로토콜에서 티켓 기반 재개만 허용되며, 여러 티켓이 전송되고 핸드셰이크가 완료될 때까지 티켓이 전송되지 않습니다. 따라서 재개 가능한 세션을 얻으려면 'session' 이벤트를 기다려야 합니다. 애플리케이션은 모든 TLS 버전에서 작동하도록 getSession() 대신 'session' 이벤트를 사용해야 합니다. 세션을 하나만 얻거나 사용할 것으로 예상하는 애플리케이션은 이 이벤트를 한 번만 수신해야 합니다.

js
tlsSocket.once('session', session => {
  // 세션은 즉시 또는 나중에 사용할 수 있습니다.
  tls.connect({
    session: session,
    // 기타 연결 옵션...
  })
})

tlsSocket.address() ​

[History]

VersionChanges
v18.4.0이제 family 속성이 숫자 대신 문자열을 반환합니다.
v18.0.0이제 family 속성이 문자열 대신 숫자를 반환합니다.
v0.11.4추가됨: v0.11.4

운영 체제에서 보고하는 기본 소켓의 바인딩된 address, 주소 family 이름 및 port를 반환합니다: { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

tlsSocket.authorizationError ​

추가된 버전: v0.11.4

피어의 인증서가 확인되지 않은 이유를 반환합니다. 이 속성은 tlsSocket.authorized === false일 때만 설정됩니다.

tlsSocket.authorized ​

추가된 버전: v0.11.4

이 속성은 피어 인증서가 tls.TLSSocket 인스턴스를 생성할 때 지정된 CA 중 하나에 의해 서명된 경우 true이고, 그렇지 않으면 false입니다.

tlsSocket.disableRenegotiation() ​

추가된 버전: v8.4.0

이 TLSSocket 인스턴스에 대한 TLS 재협상을 비활성화합니다. 호출되면 재협상을 시도하면 TLSSocket에서 'error' 이벤트가 트리거됩니다.

tlsSocket.enableTrace() ​

추가된 버전: v12.2.0

활성화되면 TLS 패킷 추적 정보가 stderr에 기록됩니다. 이는 TLS 연결 문제를 디버깅하는 데 사용할 수 있습니다.

출력 형식은 openssl s_client -trace 또는 openssl s_server -trace의 출력과 동일합니다. OpenSSL의 SSL_trace() 함수에서 생성되지만 형식은 문서화되지 않았으며 예고 없이 변경될 수 있으므로 의존해서는 안 됩니다.

tlsSocket.encrypted ​

추가된 버전: v0.11.4

항상 true를 반환합니다. 이는 TLS 소켓과 일반 net.Socket 인스턴스를 구별하는 데 사용할 수 있습니다.

tlsSocket.exportKeyingMaterial(length, label[, context]) ​

추가된 버전: v13.10.0, v12.17.0

키 자료는 IEEE 802.1X 사양에서와 같이 네트워크 프로토콜에서 다양한 종류의 공격을 방지하기 위한 검증에 사용됩니다.

예시

js
const keyingMaterial = tlsSocket.exportKeyingMaterial(128, 'client finished')

/*
 Example return value of keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
*/

자세한 내용은 OpenSSL SSL_export_keying_material 문서를 참조하십시오.

tlsSocket.getCertificate() ​

Added in: v11.2.0

로컬 인증서를 나타내는 객체를 반환합니다. 반환된 객체에는 인증서의 필드에 해당하는 일부 속성이 있습니다.

인증서 구조의 예는 tls.TLSSocket.getPeerCertificate()를 참조하세요.

로컬 인증서가 없으면 빈 객체가 반환됩니다. 소켓이 파괴된 경우 null이 반환됩니다.

tlsSocket.getCipher() ​

[기록]

버전변경 사항
v13.4.0, v12.16.0IETF 암호 이름을 standardName으로 반환합니다.
v12.0.0고정 문자열 ('TLSv1/SSLv3') 대신 최소 암호 버전을 반환합니다.
v0.11.4v0.11.4에 추가됨
  • 반환값: <Object>
    • name <string> 암호화 스위트에 대한 OpenSSL 이름입니다.
    • standardName <string> 암호화 스위트에 대한 IETF 이름입니다.
    • version <string> 이 암호화 스위트에서 지원하는 최소 TLS 프로토콜 버전입니다. 실제 협상된 프로토콜은 tls.TLSSocket.getProtocol()을 참조하세요.

협상된 암호화 스위트에 대한 정보가 포함된 객체를 반환합니다.

예를 들어, AES256-SHA 암호를 사용하는 TLSv1.2 프로토콜:

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

자세한 내용은 SSL_CIPHER_get_name을 참조하세요.

tlsSocket.getEphemeralKeyInfo() ​

Added in: v5.0.0

클라이언트 연결에서 완전 순방향 비밀의 임시 키 교환 매개변수의 유형, 이름 및 크기를 나타내는 객체를 반환합니다. 키 교환이 임시가 아닌 경우 빈 객체를 반환합니다. 이는 클라이언트 소켓에서만 지원되므로 서버 소켓에서 호출하면 null이 반환됩니다. 지원되는 유형은 'DH' 및 'ECDH'입니다. name 속성은 유형이 'ECDH'인 경우에만 사용할 수 있습니다.

예를 들어: { type: 'ECDH', name: 'prime256v1', size: 256 }와 같습니다.

tlsSocket.getFinished() ​

Added in: v9.9.0

  • 반환값: <Buffer> | <undefined> SSL/TLS 핸드셰이크의 일부로 소켓으로 전송된 최신 Finished 메시지 또는 아직 Finished 메시지가 전송되지 않은 경우 undefined를 반환합니다.

Finished 메시지는 전체 핸드셰이크의 메시지 다이제스트이므로(TLS 1.0의 경우 총 192비트이고 SSL 3.0의 경우 더 많음) SSL/TLS에서 제공하는 인증이 필요하지 않거나 충분하지 않은 경우 외부 인증 절차에 사용할 수 있습니다.

OpenSSL의 SSL_get_finished 루틴에 해당하며 RFC 5929의 tls-unique 채널 바인딩을 구현하는 데 사용할 수 있습니다.

tlsSocket.getPeerCertificate([detailed]) ​

Added in: v0.11.4

  • detailed <boolean> true이면 전체 인증서 체인을 포함하고, 그렇지 않으면 피어의 인증서만 포함합니다.
  • 반환값: <Object> 인증서 객체입니다.

피어의 인증서를 나타내는 객체를 반환합니다. 피어가 인증서를 제공하지 않으면 빈 객체가 반환됩니다. 소켓이 파괴된 경우 null이 반환됩니다.

전체 인증서 체인이 요청된 경우 각 인증서에는 해당 발급자의 인증서를 나타내는 객체를 포함하는 issuerCertificate 속성이 포함됩니다.

인증서 객체 ​

[기록]

버전변경 사항
v19.1.0, v18.13.0"ca" 속성 추가.
v17.2.0, v16.14.0fingerprint512 추가.
v11.4.0타원 곡선 공개 키 정보 지원.

인증서 객체에는 인증서의 필드에 해당하는 속성이 있습니다.

  • ca <boolean> 인증 기관(CA)인 경우 true, 그렇지 않으면 false입니다.
  • raw <Buffer> DER 인코딩된 X.509 인증서 데이터입니다.
  • subject <Object> 국가(C), 시/도(ST), 지역(L), 조직(O), 조직 단위(OU) 및 일반 이름(CN)으로 설명된 인증서 주체입니다. 일반 이름은 일반적으로 TLS 인증서를 사용하는 DNS 이름입니다. 예: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}.
  • issuer <Object> subject와 동일한 용어로 설명된 인증서 발급자입니다.
  • valid_from <string> 인증서가 유효한 시작 날짜 및 시간입니다.
  • valid_to <string> 인증서가 유효한 종료 날짜 및 시간입니다.
  • serialNumber <string> 인증서 일련 번호(16진수 문자열)입니다. 예: 'B9B0D332A1AA5635'.
  • fingerprint <string> DER 인코딩된 인증서의 SHA-1 다이제스트입니다. :로 구분된 16진수 문자열로 반환됩니다. 예: '2A:7A:C2:DD:...'.
  • fingerprint256 <string> DER 인코딩된 인증서의 SHA-256 다이제스트입니다. :로 구분된 16진수 문자열로 반환됩니다. 예: '2A:7A:C2:DD:...'.
  • fingerprint512 <string> DER 인코딩된 인증서의 SHA-512 다이제스트입니다. :로 구분된 16진수 문자열로 반환됩니다. 예: '2A:7A:C2:DD:...'.
  • ext_key_usage <Array> (선택 사항) 확장 키 사용량, 즉 OID 집합입니다.
  • subjectaltname <string> (선택 사항) 주체에 대한 연결된 이름이 포함된 문자열(주체 이름의 대안)입니다.
  • infoAccess <Array> (선택 사항) OCSP와 함께 사용되는 AuthorityInfoAccess를 설명하는 배열입니다.
  • issuerCertificate <Object> (선택 사항) 발급자 인증서 객체입니다. 자체 서명된 인증서의 경우 순환 참조일 수 있습니다.

인증서에는 키 유형에 따라 공개 키에 대한 정보가 포함될 수 있습니다.

RSA 키의 경우 다음 속성을 정의할 수 있습니다.

  • bits <number> RSA 비트 크기입니다. 예: 1024.
  • exponent <string> 16진수 표기법의 문자열로 표시되는 RSA 지수입니다. 예: '0x010001'.
  • modulus <string> 16진수 문자열로 표시되는 RSA 모듈러스입니다. 예: 'B56CE45CB7...'.
  • pubkey <Buffer> 공개 키입니다.

EC 키의 경우 다음 속성을 정의할 수 있습니다.

  • pubkey <Buffer> 공개 키입니다.
  • bits <number> 비트 단위의 키 크기입니다. 예: 256.
  • asn1Curve <string> (선택 사항) 타원 곡선의 OID의 ASN.1 이름입니다. 잘 알려진 곡선은 OID로 식별됩니다. 특이한 경우이지만 곡선이 수학적 속성으로 식별될 수 있으며, 이 경우 OID가 없습니다. 예: 'prime256v1'.
  • nistCurve <string> (선택 사항) 타원 곡선에 대한 NIST 이름(있는 경우)(모든 잘 알려진 곡선에 NIST에서 이름이 할당된 것은 아님). 예: 'P-256'.

인증서 예시:

js
{ 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',
  fingerprint512: '19:2B:3E:C3:B3:5B:32:E8:AE:BB:78:97:27:E4:BA:6C:39:C9:92:79:4F:31:46:39:E2:70:E5:5F:89:42:17:C9:E8:64:CA:FF:BB:72:56:73:6E:28:8A:92:7E:A3:2A:15:8B:C2:E0:45:CA:C3:BC:EA:40:52:EC:CA:A2:68:CB:32',
  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
  serialNumber: '66593D57F20CBC573E433381B5FEC280',
  raw: <Buffer ... > }

tlsSocket.getPeerFinished() ​

Added in: v9.9.0

  • 반환 값: <Buffer> | <undefined> SSL/TLS 핸드셰이크의 일부로 소켓에서 예상하거나 실제로 수신된 최신 Finished 메시지 또는 지금까지 Finished 메시지가 없으면 undefined를 반환합니다.

Finished 메시지는 전체 핸드셰이크의 메시지 다이제스트(TLS 1.0의 경우 총 192비트, SSL 3.0의 경우 더 많음)이므로 SSL/TLS에서 제공하는 인증이 바람직하지 않거나 충분하지 않은 경우 외부 인증 절차에 사용할 수 있습니다.

OpenSSL의 SSL_get_peer_finished 루틴에 해당하며 RFC 5929의 tls-unique 채널 바인딩을 구현하는 데 사용할 수 있습니다.

tlsSocket.getPeerX509Certificate() ​

Added in: v15.9.0

피어 인증서를 <X509Certificate> 객체로 반환합니다.

피어 인증서가 없거나 소켓이 파괴된 경우 undefined가 반환됩니다.

tlsSocket.getProtocol() ​

Added in: v5.7.0

현재 연결의 협상된 SSL/TLS 프로토콜 버전을 포함하는 문자열을 반환합니다. 핸드셰이킹 프로세스를 완료하지 않은 연결된 소켓의 경우 'unknown' 값이 반환됩니다. 서버 소켓 또는 연결이 끊긴 클라이언트 소켓의 경우 null 값이 반환됩니다.

프로토콜 버전은 다음과 같습니다.

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

자세한 내용은 OpenSSL SSL_get_version 문서를 참조하십시오.

tlsSocket.getSession() ​

Added in: v0.11.4

TLS 세션 데이터를 반환하거나 세션이 협상되지 않은 경우 undefined를 반환합니다. 클라이언트에서 데이터는 연결을 재개하기 위해 tls.connect()의 session 옵션에 제공될 수 있습니다. 서버에서는 디버깅에 유용할 수 있습니다.

자세한 내용은 세션 재개를 참조하십시오.

참고: getSession()은 TLSv1.2 이하에서만 작동합니다. TLSv1.3의 경우 애플리케이션은 'session' 이벤트를 사용해야 합니다(TLSv1.2 이하에서도 작동함).

tlsSocket.getSharedSigalgs() ​

추가된 버전: v12.11.0

  • 반환 값: <Array> 서버와 클라이언트 간에 공유되는 서명 알고리즘 목록이며, 선호도 순서대로 내림차순 정렬됩니다.

자세한 내용은 SSL_get_shared_sigalgs를 참조하십시오.

tlsSocket.getTLSTicket() ​

추가된 버전: v0.11.4

클라이언트의 경우, 사용 가능한 TLS 세션 티켓을 반환하거나 undefined를 반환합니다. 서버의 경우, 항상 undefined를 반환합니다.

디버깅에 유용할 수 있습니다.

자세한 내용은 세션 재개를 참조하십시오.

tlsSocket.getX509Certificate() ​

추가된 버전: v15.9.0

로컬 인증서를 <X509Certificate> 객체로 반환합니다.

로컬 인증서가 없거나 소켓이 파괴된 경우, undefined가 반환됩니다.

tlsSocket.isSessionReused() ​

추가된 버전: v0.5.6

  • 반환 값: <boolean> 세션이 재사용된 경우 true, 그렇지 않으면 false입니다.

자세한 내용은 세션 재개를 참조하십시오.

tlsSocket.localAddress ​

추가된 버전: v0.11.4

로컬 IP 주소의 문자열 표현을 반환합니다.

tlsSocket.localPort ​

추가된 버전: v0.11.4

로컬 포트의 숫자 표현을 반환합니다.

tlsSocket.remoteAddress ​

추가된 버전: v0.11.4

원격 IP 주소의 문자열 표현을 반환합니다. 예를 들어, '74.125.127.100' 또는 '2001:4860:a005::68'입니다.

tlsSocket.remoteFamily ​

추가된 버전: v0.11.4

원격 IP 패밀리의 문자열 표현을 반환합니다. 'IPv4' 또는 'IPv6'.

tlsSocket.remotePort ​

추가된 버전: v0.11.4

원격 포트의 숫자 표현을 반환합니다. 예를 들어, 443.

tlsSocket.renegotiate(options, callback) ​

[기록]

버전변경 사항
v18.0.0callback 인수에 유효하지 않은 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE이 발생합니다.
v0.11.8추가된 버전: v0.11.8
  • options <Object>
    • rejectUnauthorized <boolean> false가 아닌 경우 서버 인증서가 제공된 CA 목록에 대해 확인됩니다. 확인에 실패하면 'error' 이벤트가 발생합니다. err.code에는 OpenSSL 오류 코드가 포함됩니다. 기본값: true.
    • requestCert
  • callback <Function> renegotiate()가 true를 반환하면 콜백이 'secure' 이벤트에 한 번 첨부됩니다. renegotiate()가 false를 반환하면 tlsSocket이 파괴되지 않은 경우 오류와 함께 다음 틱에서 callback이 호출됩니다. 그렇지 않으면 callback이 전혀 호출되지 않습니다.
  • 반환 값: <boolean> 재협상이 시작되면 true, 그렇지 않으면 false.

tlsSocket.renegotiate() 메서드는 TLS 재협상 프로세스를 시작합니다. 완료되면 callback 함수에 요청이 실패한 경우 Error 또는 null인 단일 인수가 전달됩니다.

이 메서드를 사용하여 보안 연결이 설정된 후 피어의 인증서를 요청할 수 있습니다.

서버로 실행 중인 경우 handshakeTimeout 시간 초과 후 소켓이 오류와 함께 파괴됩니다.

TLSv1.3의 경우 재협상을 시작할 수 없으며 프로토콜에서 지원하지 않습니다.

tlsSocket.setKeyCert(context) ​

추가된 버전: v22.5.0, v20.17.0

tlsSocket.setKeyCert() 메서드는 소켓에 사용할 개인 키와 인증서를 설정합니다. 이는 주로 TLS 서버의 ALPNCallback에서 서버 인증서를 선택하려는 경우에 유용합니다.

tlsSocket.setMaxSendFragment(size) ​

추가된 버전: v0.11.11

  • size <number> 최대 TLS 조각 크기입니다. 최대 값은 16384입니다. 기본값: 16384.
  • 반환값: <boolean>

tlsSocket.setMaxSendFragment() 메서드는 최대 TLS 조각 크기를 설정합니다. 제한 설정에 성공하면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

더 작은 조각 크기는 클라이언트의 버퍼링 지연 시간을 줄입니다. 더 큰 조각은 전체 조각을 수신하고 무결성이 검증될 때까지 TLS 계층에서 버퍼링됩니다. 큰 조각은 여러 번의 왕복을 거칠 수 있으며 패킷 손실 또는 재정렬로 인해 처리가 지연될 수 있습니다. 그러나 작은 조각은 추가 TLS 프레이밍 바이트와 CPU 오버헤드를 추가하여 전체 서버 처리량을 줄일 수 있습니다.

tls.checkServerIdentity(hostname, cert) ​

[기록]

버전변경 사항
v17.3.1, v16.13.2, v14.18.3, v12.22.9CVE-2021-44531에 대응하여 uniformResourceIdentifier 주체 대체 이름 지원이 비활성화되었습니다.
v0.8.4추가된 버전: v0.8.4

인증서 cert가 hostname에 발급되었는지 확인합니다.

실패 시 reason, host 및 cert로 채워진 <Error> 객체를 반환합니다. 성공 시 <undefined>를 반환합니다.

이 함수는 tls.connect()에 전달할 수 있는 checkServerIdentity 옵션과 함께 사용하기 위한 것이며, 따라서 인증서 객체에서 작동합니다. 다른 용도로는 x509.checkHost()를 대신 사용하는 것을 고려하십시오.

이 함수는 tls.connect()에 전달되는 options.checkServerIdentity 옵션으로 대체 함수를 제공하여 덮어쓸 수 있습니다. 덮어쓰기 함수는 추가 검증으로 수행되는 검사를 보강하기 위해 물론 tls.checkServerIdentity()를 호출할 수 있습니다.

이 함수는 인증서가 신뢰할 수 있는 CA(options.ca)에서 발급된 것과 같은 다른 모든 검사를 통과한 경우에만 호출됩니다.

이전 버전의 Node.js에서는 일치하는 uniformResourceIdentifier 주체 대체 이름이 있는 경우 주어진 hostname에 대한 인증서를 잘못 허용했습니다(CVE-2021-44531 참조). uniformResourceIdentifier 주체 대체 이름을 허용하려는 애플리케이션은 원하는 동작을 구현하는 사용자 정의 options.checkServerIdentity 함수를 사용할 수 있습니다.

tls.connect(options[, callback]) ​

[History]

VersionChanges
v15.1.0, v14.18.0onread 옵션이 추가되었습니다.
v14.1.0, v13.14.0highWaterMark 옵션이 허용됩니다.
v13.6.0, v12.16.0pskCallback 옵션이 이제 지원됩니다.
v12.9.0allowHalfOpen 옵션을 지원합니다.
v12.4.0hints 옵션이 이제 지원됩니다.
v12.2.0enableTrace 옵션이 이제 지원됩니다.
v11.8.0, v10.16.0timeout 옵션이 이제 지원됩니다.
v8.0.0lookup 옵션이 이제 지원됩니다.
v8.0.0ALPNProtocols 옵션은 이제 TypedArray 또는 DataView가 될 수 있습니다.
v5.0.0ALPN 옵션이 이제 지원됩니다.
v5.3.0, v4.7.0secureContext 옵션이 이제 지원됩니다.
v0.11.3v0.11.3에 추가되었습니다.

  • options <Object>

    • enableTrace: tls.createServer()를 참조하십시오.
    • 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()가 호출되지 않습니다.
    • allowHalfOpen <boolean> false로 설정하면 읽기 가능 측면이 끝나면 소켓이 쓰기 가능 측면을 자동으로 종료합니다. socket 옵션이 설정된 경우 이 옵션은 효과가 없습니다. 자세한 내용은 net.Socket의 allowHalfOpen 옵션을 참조하십시오. 기본값: false.
    • rejectUnauthorized <boolean> false가 아니면 서버 인증서가 제공된 CA 목록과 비교하여 확인됩니다. 확인에 실패하면 'error' 이벤트가 발생합니다. err.code에는 OpenSSL 오류 코드가 포함됩니다. 기본값: true.
    • pskCallback <Function> TLS-PSK 협상에 대해서는 사전 공유 키를 참조하십시오.
    • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> 지원되는 ALPN 프로토콜을 포함하는 문자열, Buffer, TypedArray 또는 DataView의 배열 또는 단일 Buffer, TypedArray 또는 DataView입니다. Buffer는 [len][name][len][name]... 형식이어야 합니다. 예를 들어, '\x08http/1.1\x08http/1.0'입니다. 여기서 len 바이트는 다음 프로토콜 이름의 길이입니다. 배열을 전달하는 것이 일반적으로 훨씬 간단합니다. 예를 들어 ['http/1.1', 'http/1.0']입니다. 목록의 앞쪽에 있는 프로토콜이 뒤쪽에 있는 프로토콜보다 우선순위가 높습니다.
    • servername: <string> SNI (Server Name Indication) TLS 확장에 대한 서버 이름입니다. 연결 중인 호스트의 이름이며 IP 주소가 아닌 호스트 이름이어야 합니다. 다중 홈 서버에서 클라이언트에 제공할 올바른 인증서를 선택하는 데 사용할 수 있습니다. tls.createServer()에 대한 SNICallback 옵션을 참조하십시오.
    • checkServerIdentity(servername, cert) <Function> 서버의 호스트 이름(또는 명시적으로 설정된 경우 제공된 servername)을 인증서에 대해 확인할 때 (내장된 tls.checkServerIdentity() 함수 대신) 사용할 콜백 함수입니다. 확인에 실패하면 <Error>를 반환해야 합니다. servername과 cert가 확인되면 메서드가 undefined를 반환해야 합니다.
    • session <Buffer> TLS 세션을 포함하는 Buffer 인스턴스입니다.
    • minDHSize <number> TLS 연결을 수락하기 위한 DH 매개변수의 최소 크기(비트)입니다. 서버에서 minDHSize보다 작은 크기의 DH 매개변수를 제공하면 TLS 연결이 파괴되고 오류가 발생합니다. 기본값: 1024.
    • highWaterMark: <number> 읽기 가능한 스트림 highWaterMark 매개변수와 일치합니다. 기본값: 16 * 1024.
    • secureContext: tls.createSecureContext()로 생성된 TLS 컨텍스트 객체입니다. secureContext가 제공되지 않으면 전체 options 객체를 tls.createSecureContext()에 전달하여 생성됩니다.
    • onread <Object> socket 옵션이 없으면 수신 데이터가 단일 buffer에 저장되고 소켓에서 데이터가 도착하면 제공된 callback에 전달됩니다. 그렇지 않으면 옵션이 무시됩니다. 자세한 내용은 net.Socket의 onread 옵션을 참조하십시오.
    • ...: secureContext 옵션이 없는 경우 사용되는 tls.createSecureContext() 옵션입니다. 그렇지 않으면 무시됩니다.
    • ...: 아직 나열되지 않은 socket.connect() 옵션입니다.

  • callback <Function>

  • 반환값: <tls.TLSSocket>

지정된 경우 callback 함수는 'secureConnect' 이벤트의 리스너로 추가됩니다.

tls.connect()는 tls.TLSSocket 객체를 반환합니다.

https API와 달리 tls.connect()는 기본적으로 SNI(Server Name Indication) 확장을 활성화하지 않으므로 일부 서버가 잘못된 인증서를 반환하거나 연결을 거부할 수 있습니다. SNI를 활성화하려면 host 외에 servername 옵션을 설정하십시오.

다음은 tls.createServer()의 에코 서버 예제에 대한 클라이언트를 보여줍니다.

js
// 포트 8000에서 수신 대기 중인 에코 서버를 가정합니다.
import { connect } from 'node:tls'
import { readFileSync } from 'node:fs'
import { stdin } from 'node:process'

const options = {
  // 서버에서 클라이언트 인증서 인증이 필요한 경우에만 필요합니다.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // 서버에서 자체 서명된 인증서를 사용하는 경우에만 필요합니다.
  ca: [readFileSync('server-cert.pem')],

  // 서버의 인증서가 "localhost"용이 아닌 경우에만 필요합니다.
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('클라이언트 연결됨', socket.authorized ? '인증됨' : '인증되지 않음')
  stdin.pipe(socket)
  stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('서버 연결 종료')
})
js
// 포트 8000에서 수신 대기 중인 에코 서버를 가정합니다.
const { connect } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  // 서버에서 클라이언트 인증서 인증이 필요한 경우에만 필요합니다.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // 서버에서 자체 서명된 인증서를 사용하는 경우에만 필요합니다.
  ca: [readFileSync('server-cert.pem')],

  // 서버의 인증서가 "localhost"용이 아닌 경우에만 필요합니다.
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('클라이언트 연결됨', socket.authorized ? '인증됨' : '인증되지 않음')
  process.stdin.pipe(socket)
  process.stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('서버 연결 종료')
})

이 예제의 인증서와 키를 생성하려면 다음을 실행하십시오.

bash
openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout client-key.pem -out client-cert.pem

그런 다음 이 예제의 server-cert.pem 인증서를 생성하려면 다음을 실행하십시오.

bash
openssl pkcs12 -certpbe AES-256-CBC -export -out server-cert.pem \
  -inkey client-key.pem -in client-cert.pem

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

추가된 버전: v0.11.3

path가 옵션 대신 인자로 제공될 수 있다는 점을 제외하고는 tls.connect()와 동일합니다.

path 옵션이 지정되면 path 인자보다 우선합니다.

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

추가된 버전: v0.11.3

port 및 host가 옵션 대신 인자로 제공될 수 있다는 점을 제외하고는 tls.connect()와 동일합니다.

port 또는 host 옵션이 지정되면 port 또는 host 인자보다 우선합니다.

tls.createSecureContext([options]) ​

[기록]

버전변경 사항
v22.9.0, v20.18.0allowPartialTrustChain 옵션이 추가되었습니다.
v22.4.0, v20.16.0clientCertEngine, privateKeyEngine 및 privateKeyIdentifier 옵션은 OpenSSL 3에서 더 이상 사용되지 않는 OpenSSL의 사용자 정의 엔진 지원에 종속됩니다.
v19.8.0, v18.16.0이제 dhparam 옵션을 'auto'로 설정하여 적절한 잘 알려진 매개변수로 DHE를 활성화할 수 있습니다.
v12.12.0OpenSSL 엔진에서 개인 키를 가져오기 위해 privateKeyIdentifier 및 privateKeyEngine 옵션이 추가되었습니다.
v12.11.0지원되는 서명 알고리즘을 재정의하기 위해 sigalgs 옵션이 추가되었습니다.
v12.0.0TLSv1.3 지원이 추가되었습니다.
v11.5.0ca: 옵션이 이제 BEGIN TRUSTED CERTIFICATE를 지원합니다.
v11.4.0, v10.16.0minVersion 및 maxVersion을 사용하여 허용되는 TLS 프로토콜 버전을 제한할 수 있습니다.
v10.0.0OpenSSL 변경으로 인해 ecdhCurve를 더 이상 false로 설정할 수 없습니다.
v9.3.0이제 options 매개변수에 clientCertEngine을 포함할 수 있습니다.
v9.0.0이제 ecdhCurve 옵션이 여러 개의 ':'로 구분된 곡선 이름 또는 'auto'가 될 수 있습니다.
v7.3.0key 옵션이 배열인 경우 개별 항목에 더 이상 passphrase 속성이 필요하지 않습니다. Array 항목은 이제 string 또는 Buffer가 될 수도 있습니다.
v5.2.0ca 옵션은 이제 여러 개의 CA 인증서를 포함하는 단일 문자열이 될 수 있습니다.
v0.11.13추가된 버전: v0.11.13
  • options <Object>
    • allowPartialTrustChain <boolean> 신뢰 CA 인증서 목록에서 중간(자체 서명되지 않은) 인증서를 신뢰할 수 있는 것으로 처리합니다.
    • ca <string> | <string[]> | <Buffer> | <Buffer[]> 필요에 따라 신뢰할 수 있는 CA 인증서를 재정의합니다. 기본값은 Mozilla에서 선별한 잘 알려진 CA를 신뢰하는 것입니다. 이 옵션을 사용하여 CA를 명시적으로 지정하면 Mozilla의 CA가 완전히 대체됩니다. 값은 문자열 또는 Buffer이거나 문자열 및/또는 Buffer의 Array일 수 있습니다. 문자열 또는 Buffer에는 여러 개의 PEM CA가 연결되어 있을 수 있습니다. 연결을 인증하려면 피어의 인증서가 서버에서 신뢰하는 CA에 연결 가능해야 합니다. 잘 알려진 CA에 연결할 수 없는 인증서를 사용하는 경우 인증서의 CA를 명시적으로 신뢰할 수 있는 것으로 지정해야 합니다. 그렇지 않으면 연결이 인증에 실패합니다. 피어가 기본 CA 중 하나와 일치하거나 연결되지 않는 인증서를 사용하는 경우 ca 옵션을 사용하여 피어의 인증서가 일치하거나 연결될 수 있는 CA 인증서를 제공하십시오. 자체 서명된 인증서의 경우 인증서 자체가 CA이므로 제공해야 합니다. PEM 인코딩된 인증서의 경우 지원되는 유형은 "TRUSTED CERTIFICATE", "X509 CERTIFICATE" 및 "CERTIFICATE"입니다. tls.rootCertificates도 참조하십시오.
    • cert <string> | <string[]> | <Buffer> | <Buffer[]> PEM 형식의 인증서 체인. 개인 키당 하나의 인증서 체인을 제공해야 합니다. 각 인증서 체인은 제공된 개인 key에 대한 PEM 형식의 인증서, 그 다음에는 PEM 형식의 중간 인증서(있는 경우)로 순서대로 구성되어야 하며 루트 CA는 포함하지 않아야 합니다(루트 CA는 피어에 미리 알려져 있어야 합니다. ca 참조). 여러 개의 인증서 체인을 제공하는 경우 key의 개인 키와 동일한 순서일 필요는 없습니다. 중간 인증서를 제공하지 않으면 피어가 인증서를 검증할 수 없으며 핸드셰이크가 실패합니다.
    • sigalgs <string> 지원되는 서명 알고리즘의 콜론으로 구분된 목록. 목록에는 다이제스트 알고리즘(SHA256, MD5 등), 공개 키 알고리즘(RSA-PSS, ECDSA 등), 둘의 조합(예: RSA+SHA384) 또는 TLS v1.3 스키마 이름(예: rsa_pss_pss_sha512)이 포함될 수 있습니다. 자세한 내용은 OpenSSL man pages를 참조하십시오.
    • ciphers <string> 기본값을 대체하는 암호 스위트 사양. 자세한 내용은 기본 TLS 암호 스위트 수정을 참조하십시오. 허용되는 암호는 tls.getCiphers()를 통해 얻을 수 있습니다. OpenSSL에서 허용하려면 암호 이름을 대문자로 표시해야 합니다.
    • clientCertEngine <string> 클라이언트 인증서를 제공할 수 있는 OpenSSL 엔진의 이름. 더 이상 사용되지 않습니다.
    • crl <string> | <string[]> | <Buffer> | <Buffer[]> PEM 형식의 CRL(인증서 해지 목록).
    • dhparam <string> | <Buffer> 'auto' 또는 비 ECDHE에 필요한 사용자 지정 Diffie-Hellman 매개변수 완벽한 순방향 비밀. 생략되거나 유효하지 않으면 매개변수가 자동으로 삭제되고 DHE 암호를 사용할 수 없습니다. ECDHE 기반 완벽한 순방향 비밀은 계속 사용할 수 있습니다.
    • ecdhCurve <string> ECDH 키 협상에 사용할 명명된 곡선 또는 곡선 NID 또는 이름의 콜론으로 구분된 목록(예: P-521:P-384:P-256)을 설명하는 문자열입니다. 곡선을 자동으로 선택하려면 auto로 설정합니다. 사용 가능한 곡선 이름 목록을 얻으려면 crypto.getCurves()를 사용하십시오. 최근 릴리스에서는 openssl ecparam -list_curves도 사용 가능한 각 타원 곡선의 이름과 설명을 표시합니다. 기본값: tls.DEFAULT_ECDH_CURVE.
    • honorCipherOrder <boolean> 클라이언트의 암호 스위트 기본 설정 대신 서버의 암호 스위트 기본 설정을 사용하려고 합니다. true인 경우 secureOptions에서 SSL_OP_CIPHER_SERVER_PREFERENCE가 설정되게 합니다. 자세한 내용은 OpenSSL 옵션을 참조하십시오.
    • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> PEM 형식의 개인 키. PEM은 개인 키를 암호화할 수 있는 옵션을 허용합니다. 암호화된 키는 options.passphrase로 해독됩니다. 암호화되지 않은 키 문자열 또는 버퍼의 배열, 또는 {pem: <string|buffer>[, passphrase: <string>]} 형식의 객체 배열로 다른 알고리즘을 사용하는 여러 키를 제공할 수 있습니다. 객체 형식은 배열에서만 발생할 수 있습니다. object.passphrase는 선택 사항입니다. 암호화된 키는 제공된 경우 object.passphrase 또는 제공되지 않은 경우 options.passphrase로 해독됩니다.
    • privateKeyEngine <string> 개인 키를 가져올 OpenSSL 엔진의 이름. privateKeyIdentifier와 함께 사용해야 합니다. 더 이상 사용되지 않습니다.
    • privateKeyIdentifier <string> OpenSSL 엔진에서 관리하는 개인 키의 식별자. privateKeyEngine과 함께 사용해야 합니다. 두 옵션 모두 다른 방식으로 개인 키를 정의하므로 key와 함께 설정해서는 안 됩니다. 더 이상 사용되지 않습니다.
    • maxVersion <string> 필요에 따라 허용할 최대 TLS 버전을 설정합니다. 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' 또는 'TLSv1' 중 하나입니다. secureProtocol 옵션과 함께 지정할 수 없습니다. 둘 중 하나를 사용하십시오. 기본값: tls.DEFAULT_MAX_VERSION.
    • minVersion <string> 필요에 따라 허용할 최소 TLS 버전을 설정합니다. 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' 또는 'TLSv1' 중 하나입니다. secureProtocol 옵션과 함께 지정할 수 없습니다. 둘 중 하나를 사용하십시오. TLSv1.2보다 낮은 값으로 설정하는 것은 피해야 하지만 상호 운용성을 위해 필요할 수 있습니다. TLSv1.2 이전 버전에서는 OpenSSL 보안 수준을 다운그레이드해야 할 수 있습니다. 기본값: tls.DEFAULT_MIN_VERSION.
    • passphrase <string> 단일 개인 키 및/또는 PFX에 사용되는 공유 암호.
    • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> PFX 또는 PKCS12 인코딩된 개인 키 및 인증서 체인. pfx는 key 및 cert를 개별적으로 제공하는 대안입니다. PFX는 일반적으로 암호화되며, 암호화된 경우 passphrase가 암호 해독하는 데 사용됩니다. 암호화되지 않은 PFX 버퍼의 배열 또는 {buf: <string|buffer>[, passphrase: <string>]} 형식의 객체 배열로 여러 개의 PFX를 제공할 수 있습니다. 객체 형식은 배열에서만 발생할 수 있습니다. object.passphrase는 선택 사항입니다. 암호화된 PFX는 제공된 경우 object.passphrase 또는 제공되지 않은 경우 options.passphrase로 해독됩니다.
    • secureOptions <number> 필요하지 않은 OpenSSL 프로토콜 동작에 선택적으로 영향을 줍니다. 이는 신중하게 사용해야 합니다! 값은 OpenSSL 옵션의 SSL_OP_* 옵션의 숫자 비트마스크입니다.
    • secureProtocol <string> 사용할 TLS 프로토콜 버전을 선택하는 레거시 메커니즘입니다. 최소 및 최대 버전을 독립적으로 제어할 수 없으며 프로토콜을 TLSv1.3으로 제한하는 것을 지원하지 않습니다. 대신 minVersion 및 maxVersion을 사용하십시오. 가능한 값은 SSL_METHODS에 나열되어 있으며 함수 이름을 문자열로 사용하십시오. 예를 들어 TLS 버전 1.1을 강제 적용하려면 'TLSv1_1_method'를 사용하거나 TLSv1.3까지 모든 TLS 프로토콜 버전을 허용하려면 'TLS_method'를 사용하십시오. 1.2 미만의 TLS 버전을 사용하는 것은 권장되지 않지만 상호 운용성을 위해 필요할 수 있습니다. 기본값: 없음, minVersion을 참조하십시오.
    • sessionIdContext <string> 서버에서 애플리케이션 간에 세션 상태가 공유되지 않도록 하는 데 사용되는 불투명 식별자입니다. 클라이언트에서는 사용되지 않습니다.
    • ticketKeys: <Buffer> 암호화상으로 강력한 48바이트의 의사 난수 데이터입니다. 자세한 내용은 세션 재개를 참조하십시오.
    • sessionTimeout <number> 서버에서 만든 TLS 세션을 더 이상 재개할 수 없게 되는 시간(초)입니다. 자세한 내용은 세션 재개를 참조하십시오. 기본값: 300.

tls.createServer()는 honorCipherOrder 옵션의 기본값을 true로 설정하며, 보안 컨텍스트를 만드는 다른 API는 설정하지 않은 상태로 둡니다.

tls.createServer()는 sessionIdContext 옵션의 기본값으로 process.argv에서 생성된 128비트 잘린 SHA1 해시 값을 사용하며, 보안 컨텍스트를 만드는 다른 API에는 기본값이 없습니다.

tls.createSecureContext() 메서드는 SecureContext 객체를 만듭니다. 이 객체는 server.addContext()와 같은 여러 tls API의 인자로 사용할 수 있지만 공개 메서드는 없습니다. tls.Server 생성자와 tls.createServer() 메서드는 secureContext 옵션을 지원하지 않습니다.

인증서를 사용하는 암호에는 키가 필수입니다. key 또는 pfx를 사용하여 키를 제공할 수 있습니다.

ca 옵션을 제공하지 않으면 Node.js는 기본적으로 Mozilla의 공개적으로 신뢰할 수 있는 CA 목록을 사용합니다.

새로운 dhparam: 'auto' 옵션 대신 사용자 지정 DHE 매개변수를 사용하지 않는 것이 좋습니다. 'auto'로 설정하면 충분한 강도의 잘 알려진 DHE 매개변수가 자동으로 선택됩니다. 그렇지 않으면 필요에 따라 openssl dhparam을 사용하여 사용자 지정 매개변수를 만들 수 있습니다. 키 길이는 1024비트 이상이어야 합니다. 그렇지 않으면 오류가 발생합니다. 1024비트가 허용되지만 보안을 강화하려면 2048비트 이상을 사용하십시오.

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

[기록]

버전변경 사항
v5.0.0이제 ALPN 옵션을 지원합니다.
v0.11.3다음 이후로 더 이상 사용되지 않음: v0.11.3
v0.3.2추가된 버전: v0.3.2

[안정성: 0 - 더 이상 사용되지 않음]

안정성: 0 안정성: 0 - 더 이상 사용되지 않음: 대신 tls.TLSSocket을 사용하세요.

  • context <Object> tls.createSecureContext()에서 반환된 보안 컨텍스트 객체입니다.
  • isServer <boolean> 이 TLS 연결이 서버로 열려야 함을 지정하려면 true입니다.
  • requestCert <boolean> 서버가 연결하는 클라이언트로부터 인증서를 요청해야 하는지 여부를 지정하려면 true입니다. isServer가 true인 경우에만 적용됩니다.
  • rejectUnauthorized <boolean> false가 아니면 서버는 자동으로 잘못된 인증서를 가진 클라이언트를 거부합니다. isServer가 true인 경우에만 적용됩니다.
  • options
    • enableTrace: tls.createServer()를 참조하십시오.
    • secureContext: tls.createSecureContext()의 TLS 컨텍스트 객체입니다.
    • isServer: true인 경우 TLS 소켓은 서버 모드로 인스턴스화됩니다. 기본값: false.
    • server <net.Server> net.Server 인스턴스
    • requestCert: tls.createServer()를 참조하십시오.
    • rejectUnauthorized: tls.createServer()를 참조하십시오.
    • ALPNProtocols: tls.createServer()를 참조하십시오.
    • SNICallback: tls.createServer()를 참조하십시오.
    • session <Buffer> TLS 세션을 포함하는 Buffer 인스턴스입니다.
    • requestOCSP <boolean> true인 경우 OCSP 상태 요청 확장이 클라이언트 hello에 추가되고 보안 통신을 설정하기 전에 소켓에서 'OCSPResponse' 이벤트가 발생하도록 지정합니다.

암호화된 데이터를 읽고 쓰는 스트림과 일반 텍스트 데이터를 읽고 쓰는 스트림의 두 개의 스트림을 가진 새 보안 쌍 객체를 만듭니다. 일반적으로 암호화된 스트림은 들어오는 암호화된 데이터 스트림으로/부터 파이프되고 일반 텍스트 스트림은 초기 암호화된 스트림의 대체물로 사용됩니다.

tls.createSecurePair()는 cleartext 및 encrypted 스트림 속성을 가진 tls.SecurePair 객체를 반환합니다.

cleartext를 사용하는 것은 tls.TLSSocket과 동일한 API를 가집니다.

이제 tls.createSecurePair() 메서드는 tls.TLSSocket()을 대신 사용하는 것이 좋습니다. 예를 들어, 다음 코드는 다음과 같습니다.

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

다음으로 대체할 수 있습니다.

js
secureSocket = tls.TLSSocket(socket, options)

여기서 secureSocket은 pair.cleartext와 동일한 API를 가집니다.

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

[기록]

버전변경 사항
v22.4.0, v20.16.0clientCertEngine 옵션은 OpenSSL 3에서 더 이상 사용되지 않는 OpenSSL의 사용자 지정 엔진 지원에 따라 다릅니다.
v19.0.0ALPNProtocols가 설정된 경우 지원되는 프로토콜이 없는 ALPN 확장을 보내는 들어오는 연결은 치명적인 no_application_protocol 경고로 종료됩니다.
v20.4.0, v18.19.0이제 options 매개변수에 ALPNCallback을 포함할 수 있습니다.
v12.3.0이제 options 매개변수가 net.createServer() 옵션을 지원합니다.
v9.3.0이제 options 매개변수에 clientCertEngine을 포함할 수 있습니다.
v8.0.0이제 ALPNProtocols 옵션이 TypedArray 또는 DataView일 수 있습니다.
v5.0.0이제 ALPN 옵션이 지원됩니다.
v0.3.2추가됨: v0.3.2

  • options <Object>

    • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> 지원되는 ALPN 프로토콜을 포함하는 문자열 배열, Buffer 배열, TypedArray 배열 또는 DataView 배열 또는 단일 Buffer, TypedArray 또는 DataView입니다. Buffer는 [len][name][len][name]... 형식이어야 합니다. 예를 들어, 0x05hello0x05world와 같이 첫 번째 바이트는 다음 프로토콜 이름의 길이입니다. 배열을 전달하는 것이 일반적으로 훨씬 간단합니다. 예를 들어, ['hello', 'world']와 같습니다. (프로토콜은 우선순위에 따라 정렬되어야 합니다.)
    • ALPNCallback: <Function> 설정된 경우 클라이언트가 ALPN 확장을 사용하여 연결을 열 때 호출됩니다. 콜백에는 servername 및 protocols 필드를 포함하는 객체라는 하나의 인수가 전달됩니다. 각각 SNI 확장(있는 경우)의 서버 이름과 ALPN 프로토콜 이름 문자열 배열을 포함합니다. 콜백은 클라이언트의 ALPN 프로토콜로 반환되는 protocols에 나열된 문자열 중 하나 또는 연결을 치명적인 경고로 거부하기 위해 undefined를 반환해야 합니다. 클라이언트의 ALPN 프로토콜 중 하나와 일치하지 않는 문자열이 반환되면 오류가 발생합니다. 이 옵션은 ALPNProtocols 옵션과 함께 사용할 수 없으며 두 옵션을 모두 설정하면 오류가 발생합니다.
    • clientCertEngine <string> 클라이언트 인증서를 제공할 수 있는 OpenSSL 엔진의 이름입니다. 더 이상 사용되지 않습니다.
    • enableTrace <boolean> true이면 새 연결에서 tls.TLSSocket.enableTrace()가 호출됩니다. 추적은 보안 연결이 설정된 후 활성화할 수 있지만 보안 연결 설정을 추적하려면 이 옵션을 사용해야 합니다. 기본값: false.
    • handshakeTimeout <number> 지정된 밀리초 내에 SSL/TLS 핸드셰이크가 완료되지 않으면 연결을 중단합니다. 핸드셰이크 시간이 초과될 때마다 tls.Server 객체에 'tlsClientError'가 발생합니다. 기본값: 120000(120초).
    • rejectUnauthorized <boolean> false가 아니면 서버는 제공된 CA 목록으로 승인되지 않은 연결을 거부합니다. 이 옵션은 requestCert가 true인 경우에만 영향을 미칩니다. 기본값: true.
    • requestCert <boolean> true이면 서버는 연결하는 클라이언트로부터 인증서를 요청하고 해당 인증서를 확인하려고 시도합니다. 기본값: false.
    • sessionTimeout <number> 서버에서 생성한 TLS 세션을 더 이상 다시 시작할 수 없는 시간(초)입니다. 자세한 내용은 세션 재개를 참조하세요. 기본값: 300.
    • SNICallback(servername, callback) <Function> 클라이언트가 SNI TLS 확장을 지원하는 경우 호출될 함수입니다. 호출 시 servername과 callback이라는 두 가지 인수가 전달됩니다. callback은 오류 우선 콜백으로, error 및 ctx라는 두 가지 선택적 인수를 사용합니다. ctx가 제공되면 SecureContext 인스턴스입니다. tls.createSecureContext()를 사용하여 적절한 SecureContext를 가져올 수 있습니다. callback이 falsy ctx 인수로 호출되면 서버의 기본 보안 컨텍스트가 사용됩니다. SNICallback이 제공되지 않으면 고급 API를 사용하는 기본 콜백이 사용됩니다(아래 참조).
    • ticketKeys: <Buffer> 48바이트의 암호화적으로 강력한 의사 난수 데이터입니다. 자세한 내용은 세션 재개를 참조하세요.
    • pskCallback <Function> TLS-PSK 협상의 경우 미리 공유된 키를 참조하세요.
    • pskIdentityHint <string> TLS-PSK 협상 중에 ID 선택을 지원하기 위해 클라이언트에 전송할 선택적 힌트입니다. TLS 1.3에서는 무시됩니다. pskIdentityHint를 설정하지 못하면 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED' 코드로 'tlsClientError'가 발생합니다.
    • ...: 모든 tls.createSecureContext() 옵션을 제공할 수 있습니다. 서버의 경우 ID 옵션(pfx, key/cert 또는 pskCallback)이 일반적으로 필요합니다.
    • ...: 모든 net.createServer() 옵션을 제공할 수 있습니다.

  • secureConnectionListener <Function>

  • 반환 값: <tls.Server>

새로운 tls.Server를 생성합니다. 제공된 경우 secureConnectionListener는 'secureConnection' 이벤트에 대한 리스너로 자동 설정됩니다.

ticketKeys 옵션은 node:cluster 모듈 작업자 간에 자동으로 공유됩니다.

다음은 간단한 에코 서버를 보여줍니다.

js
import { createServer } from 'node:tls'
import { readFileSync } from 'node:fs'

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

  // 클라이언트 인증서 인증을 사용하는 경우에만 필요합니다.
  requestCert: true,

  // 클라이언트가 자체 서명된 인증서를 사용하는 경우에만 필요합니다.
  ca: [readFileSync('client-cert.pem')],
}

const server = 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')
})
js
const { createServer } = require('node:tls')
const { readFileSync } = require('node:fs')

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

  // 클라이언트 인증서 인증을 사용하는 경우에만 필요합니다.
  requestCert: true,

  // 클라이언트가 자체 서명된 인증서를 사용하는 경우에만 필요합니다.
  ca: [readFileSync('client-cert.pem')],
}

const server = 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')
})

이 예제에 대한 인증서 및 키를 생성하려면 다음을 실행합니다.

bash
openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout server-key.pem -out server-cert.pem

그런 다음, 이 예제에 대한 client-cert.pem 인증서를 생성하려면 다음을 실행합니다.

bash
openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \
  -inkey server-key.pem -in server-cert.pem

서버는 tls.connect()의 예제 클라이언트를 사용하여 연결하여 테스트할 수 있습니다.

tls.getCiphers() ​

추가된 버전: v0.10.2

지원되는 TLS 암호화 방식의 이름을 담은 배열을 반환합니다. 이름은 과거의 이유로 소문자이지만, tls.createSecureContext()의 ciphers 옵션에 사용하려면 대문자로 변경해야 합니다.

지원되는 모든 암호화 방식이 기본적으로 활성화되는 것은 아닙니다. 기본 TLS 암호화 방식 모음 수정하기를 참조하세요.

'tls_'로 시작하는 암호화 방식 이름은 TLSv1.3용이고, 다른 모든 이름은 TLSv1.2 이하용입니다.

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

tls.rootCertificates ​

추가된 버전: v12.3.0

현재 Node.js 버전에서 제공하는 번들된 Mozilla CA 저장소의 루트 인증서(PEM 형식)를 나타내는 변경 불가능한 문자열 배열입니다.

Node.js에서 제공하는 번들된 CA 저장소는 릴리스 시점에 고정된 Mozilla CA 저장소의 스냅샷입니다. 지원되는 모든 플랫폼에서 동일합니다.

tls.DEFAULT_ECDH_CURVE ​

[기록]

버전변경 사항
v10.0.0기본값이 'auto'로 변경되었습니다.
v0.11.13추가된 버전: v0.11.13

tls 서버에서 ECDH 키 합의에 사용할 기본 곡선 이름입니다. 기본값은 'auto'입니다. 자세한 내용은 tls.createSecureContext()를 참조하세요.

tls.DEFAULT_MAX_VERSION ​

추가된 버전: v11.4.0

  • <string> tls.createSecureContext()의 maxVersion 옵션의 기본값입니다. 지원되는 TLS 프로토콜 버전인 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' 또는 'TLSv1' 중 하나를 할당할 수 있습니다. 기본값: CLI 옵션을 사용하여 변경하지 않는 한 'TLSv1.3'입니다. --tls-max-v1.2를 사용하면 기본값이 'TLSv1.2'로 설정됩니다. --tls-max-v1.3을 사용하면 기본값이 'TLSv1.3'으로 설정됩니다. 여러 옵션을 제공하는 경우 가장 높은 최대값이 사용됩니다.

tls.DEFAULT_MIN_VERSION ​

추가된 버전: v11.4.0

  • <string> tls.createSecureContext()의 minVersion 옵션의 기본값입니다. 지원되는 TLS 프로토콜 버전인 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', 또는 'TLSv1' 중 하나를 할당할 수 있습니다. TLSv1.2 이전 버전에서는 OpenSSL 보안 수준을 낮춰야 할 수 있습니다. 기본값: CLI 옵션을 사용하여 변경하지 않는 한 'TLSv1.2'입니다. --tls-min-v1.0을 사용하면 기본값이 'TLSv1'로 설정됩니다. --tls-min-v1.1을 사용하면 기본값이 'TLSv1.1'로 설정됩니다. --tls-min-v1.3을 사용하면 기본값이 'TLSv1.3'으로 설정됩니다. 여러 옵션이 제공된 경우 가장 낮은 최소값이 사용됩니다.

tls.DEFAULT_CIPHERS ​

추가된 버전: v19.8.0, v18.16.0

  • <string> tls.createSecureContext()의 ciphers 옵션의 기본값입니다. 지원되는 OpenSSL 암호 중 하나를 할당할 수 있습니다. --tls-default-ciphers를 사용하는 CLI 옵션을 사용하여 변경하지 않는 한 기본적으로 crypto.constants.defaultCoreCipherList의 내용으로 설정됩니다.