Configuring TLS certificates
출처: 문서
본문
TLS 인증서 구성
TLS는 opensearch.yml에서 구성해요. 인증서는 트랜스포트 계층 트래픽(클러스터 내 노드 간 통신)과 REST 계층 트래픽(클러스터 내 클라이언트와 노드 간 통신)을 보호하는 데 사용돼요. TLS는 REST 계층에서는 선택 사항이지만 트랜스포트 계층에서는 필수예요.
모든 옵션이 포함된 예제 구성 템플릿은 GitHub에서 확인할 수 있어요. {: .note }
X.509 PEM 인증서 및 PKCS #8 키
다음 표에는 PEM 인증서와 프라이빗 키의 위치를 구성할 때 사용할 수 있는 설정이 정리되어 있어요.
트랜스포트 계층 TLS
| 이름 | 설명 |
|---|---|
plugins.security.ssl.transport.pemkey_filepath |
인증서 키 파일(PKCS #8)의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
plugins.security.ssl.transport.pemkey_password |
키의 비밀번호예요. 키에 비밀번호가 없다면 이 설정은 생략해요. 선택 사항이에요. |
plugins.security.ssl.transport.pemcert_filepath |
X.509 노드 인증서 체인(PEM 형식)의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
plugins.security.ssl.transport.pemtrustedcas_filepath |
루트 인증 기관(CA)(PEM 형식)의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
REST 계층 TLS
| 이름 | 설명 |
|---|---|
plugins.security.ssl.http.enabled |
REST 계층에서 TLS를 활성화할지 여부예요. 활성화하면 HTTPS만 허용돼요. 선택 사항이에요. 기본값은 false예요. |
plugins.security.ssl.http.pemkey_filepath |
인증서 키 파일(PKCS #8)의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
plugins.security.ssl.http.pemkey_password |
키의 비밀번호예요. 키에 비밀번호가 없다면 이 설정은 생략해요. 선택 사항이에요. |
plugins.security.ssl.http.pemcert_filepath |
X.509 노드 인증서 체인(PEM 형식)의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
plugins.security.ssl.http.pemtrustedcas_filepath |
루트 CA(PEM 형식)의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
키스토어 및 트러스트스토어 파일
PEM 형식의 인증서와 프라이빗 키 대신 JKS 또는 PKCS12/PFX 형식의 키스토어 및 트러스트스토어 파일을 사용할 수도 있어요. Security 플러그인이 동작하려면 인증서와 프라이빗 키가 필요해요.
다음 설정으로 키스토어와 트러스트스토어 파일의 위치와 비밀번호를 구성해요. 원한다면 REST 계층과 트랜스포트 계층에 서로 다른 키스토어와 트러스트스토어 파일을 사용할 수 있어요.
트랜스포트 계층 TLS
| 이름 | 설명 |
|---|---|
plugins.security.ssl.transport.keystore_type |
키스토어 파일의 타입(JKS 또는 PKCS12/PFX)이에요. 선택 사항이에요. 기본값은 JKS예요. |
plugins.security.ssl.transport.keystore_filepath |
키스토어 파일의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
plugins.security.ssl.transport.keystore_alias |
키스토어의 별칭 이름이에요. 선택 사항이에요. 기본값은 첫 번째 별칭이에요. |
plugins.security.ssl.transport.keystore_password |
키스토어 파일의 비밀번호예요. 선택 사항이에요. 기본값은 changeit이에요. |
plugins.security.ssl.transport.keystore_keypassword |
키스토어에 있는 프라이빗 키의 비밀번호예요. 설정하지 않으면 keystore_password가 사용돼요. 선택 사항이에요. |
plugins.security.ssl.transport.truststore_type |
트러스트스토어 파일의 타입(JKS 또는 PKCS12/PFX)이에요. 기본값은 JKS예요. |
plugins.security.ssl.transport.truststore_filepath |
트러스트스토어 파일의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
plugins.security.ssl.transport.truststore_alias |
트러스트스토어의 별칭 이름이에요. 선택 사항이에요. 기본값은 모든 인증서예요. |
plugins.security.ssl.transport.truststore_password |
트러스트스토어 비밀번호예요. 기본값은 changeit이에요. |
REST 계층 TLS
| 이름 | 설명 |
|---|---|
plugins.security.ssl.http.enabled |
REST 계층에서 TLS를 활성화할지 여부예요. 활성화하면 HTTPS만 허용돼요. 선택 사항이에요. 기본값은 false예요. |
plugins.security.ssl.http.keystore_type |
키스토어 파일의 타입(JKS 또는 PKCS12/PFX)이에요. 선택 사항이에요. 기본값은 JKS예요. |
plugins.security.ssl.http.keystore_filepath |
키스토어 파일의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
plugins.security.ssl.http.keystore_alias |
키스토어의 별칭 이름이에요. 선택 사항이에요. 기본값은 첫 번째 별칭이에요. |
plugins.security.ssl.http.keystore_password |
키스토어 파일의 비밀번호예요. 선택 사항이에요. 기본값은 changeit이에요. |
plugins.security.ssl.http.keystore_keypassword |
키스토어에 있는 프라이빗 키의 비밀번호예요. 설정하지 않으면 keystore_password가 사용돼요. 선택 사항이에요. |
plugins.security.ssl.http.truststore_type |
트러스트스토어 파일의 타입(JKS 또는 PKCS12/PFX)이에요. 기본값은 JKS예요. |
plugins.security.ssl.http.truststore_filepath |
트러스트스토어 파일의 경로예요. config 디렉터리 아래에 있어야 하며 상대 경로로 지정해요. 필수예요. |
plugins.security.ssl.http.truststore_alias |
트러스트스토어의 별칭 이름이에요. 선택 사항이에요. 기본값은 모든 인증서예요. |
plugins.security.ssl.http.truststore_password |
트러스트스토어의 비밀번호예요. 기본값은 changeit이에요. |
트랜스포트 계층 TLS를 위한 클라이언트/서버 인증서 분리
기본적으로 트랜스포트 계층 TLS 인증서는, TLS 인증서를 사용하는 노드가 내부에서 통신 요청을 제공하고 수신하는 역할을 담당하기 때문에, 인증서의 Extended Key Usage 섹션에서 클라이언트(TLS Web Client Authentication)와 서버(TLS Web Server Authentication) 양쪽에 맞게 구성되어야 해요.
클라이언트와 서버에 별도의 인증서를 사용하려면 opensearch.yml에 plugins.security.ssl.transport.extended_key_usage_enabled: true 설정을 추가해요. 그다음 클라이언트/서버 X.509 PEM 인증서 및 PKCS #8 키 분리 또는 클라이언트/서버 키스토어 및 트러스트스토어 파일 분리 섹션에 설명된 설정을 구성해요.
클라이언트/서버 X.509 PEM 인증서 및 PKCS #8 키 분리
| 이름 | 설명 |
|---|---|
plugins.security.ssl.transport.server.pemkey_filepath |
서버 인증서 키 파일(PKCS #8)의 경로예요. config 디렉터리 아래의 상대 경로로 지정해야 해요. 필수예요. |
plugins.security.ssl.transport.server.pemkey_password |
서버 키의 비밀번호예요. 키에 비밀번호가 없다면 이 설정은 생략해요. 선택 사항이에요. |
plugins.security.ssl.transport.server.pemcert_filepath |
X.509 노드 서버 인증서 체인(PEM 형식)의 경로예요. config 디렉터리 아래의 상대 경로로 지정해야 해요. 필수예요. |
plugins.security.ssl.transport.server.pemtrustedcas_filepath |
루트 CA(PEM 형식)의 경로예요. config 디렉터리 아래의 상대 경로로 지정해야 해요. 필수예요. |
plugins.security.ssl.transport.client.pemkey_filepath |
클라이언트 인증서 키 파일(PKCS #8)의 경로예요. config 디렉터리 아래의 상대 경로로 지정해야 해요. 필수예요. |
plugins.security.ssl.transport.client.pemkey_password |
클라이언트 키의 비밀번호예요. 키에 비밀번호가 없다면 이 설정은 생략해요. 선택 사항이에요. |
plugins.security.ssl.transport.client.pemcert_filepath |
X.509 노드 클라이언트 인증서 체인(PEM 형식)의 경로예요. config 디렉터리 아래의 상대 경로로 지정해야 해요. 필수예요. |
plugins.security.ssl.transport.client.pemtrustedcas_filepath |
루트 CA(PEM 형식)의 경로예요. config 디렉터리 아래의 상대 경로로 지정해야 해요. 필수예요. |
클라이언트/서버 키스토어 및 트러스트스토어 파일 분리
| 이름 | 설명 |
|---|---|
plugins.security.ssl.transport.keystore_type |
키스토어 파일의 타입(JKS 또는 PKCS12/PFX)이에요. 선택 사항이에요. 기본값은 JKS예요. |
plugins.security.ssl.transport.keystore_filepath |
키스토어 파일의 경로예요. config 디렉터리 아래의 상대 경로로 지정해야 해요. 필수예요. |
plugins.security.ssl.transport.keystore_password |
키스토어 파일의 비밀번호예요. 선택 사항이에요. 기본값은 changeit이에요. |
plugins.security.ssl.transport.server.keystore_alias |
서버 키의 별칭 이름이에요. 선택 사항이에요. 기본값은 첫 번째 별칭이에요. |
plugins.security.ssl.transport.client.keystore_alias |
클라이언트 키의 별칭 이름이에요. 선택 사항이에요. 기본값은 첫 번째 별칭이에요. |
plugins.security.ssl.transport.server.keystore_keypassword |
키스토어에 있는 서버 프라이빗 키의 비밀번호예요. 설정하지 않으면 keystore_password가 사용돼요. 선택 사항이에요. 기본값은 changeit이에요. |
plugins.security.ssl.transport.client.keystore_keypassword |
키스토어에 있는 클라이언트 프라이빗 키의 비밀번호예요. 설정하지 않으면 keystore_password가 사용돼요. 선택 사항이에요. 기본값은 changeit이에요. |
plugins.security.ssl.transport.server.truststore_alias |
서버의 별칭 이름이에요. 선택 사항이에요. 기본값은 모든 인증서예요. |
plugins.security.ssl.transport.client.truststore_alias |
클라이언트의 별칭 이름이에요. 선택 사항이에요. 기본값은 모든 인증서예요. |
plugins.security.ssl.transport.truststore_filepath |
truststore 파일의 경로 |
(고급) 클라이언트 인증
TLS 클라이언트 인증이 활성화되면, REST 클라이언트는 HTTP 요청과 함께 TLS 인증서를 전송해서 Security 플러그인에 신원 정보를 제공할 수 있어요. TLS 클라이언트 인증의 주요 사용 시나리오는 세 가지예요:
- REST 관리 API를 사용할 때 어드민 인증서를 제공하기.
- 클라이언트 인증서를 기반으로 역할과 권한을 구성하기.
- OpenSearch Dashboards, Logstash, Beats 같은 도구에 신원 정보를 제공하기.
TLS 클라이언트 인증에는 세 가지 모드가 있어요:
NONE: Security 플러그인이 TLS 클라이언트 인증서를 받아들이지 않아요. 인증서가 전송되면 폐기돼요.OPTIONAL: Security 플러그인은 TLS 클라이언트 인증서가 전송되면 받아들이지만, 필수로 요구하지는 않아요.REQUIRE: 유효한 클라이언트 TLS 인증서가 전송될 때만 Security 플러그인이 REST 요청을 받아들여요.
REST 관리 API를 사용하려면 클라이언트 인증 모드가 최소한 OPTIONAL이어야 해요.
다음 설정을 사용해서 클라이언트 인증 모드를 구성할 수 있어요:
| 이름 | 설명 |
|---|---|
plugins.security.ssl.http.clientauth_mode |
사용할 TLS 클라이언트 인증 모드예요. NONE, OPTIONAL(기본값) 또는 REQUIRE 중 하나를 지정할 수 있어요. 선택 사항이에요. |
(고급) 활성화할 암호 스위트와 프로토콜
REST 레이어에서 허용되는 암호 스위트와 TLS 프로토콜을 제한할 수 있어요. 예를 들어 강력한 암호 스위트만 허용하고 TLS 버전을 최신 버전으로 제한할 수 있죠.
이 설정이 활성화되어 있지 않으면, 암호 스위트와 TLS 버전은 브라우저와 Security 플러그인 사이에서 자동으로 협상돼요. 이 경우 어떤 때는 더 약한 암호 스위트가 사용될 수 있어요. 다음 설정을 사용해서 암호 스위트와 프로토콜을 구성할 수 있어요.
| 이름 | 데이터 타입 | 설명 |
|---|---|---|
plugins.security.ssl.http.enabled_ciphers |
Array | REST 레이어에서 활성화할 TLS 암호 스위트예요. Java 형식만 지원돼요. |
plugins.security.ssl.http.enabled_protocols |
Array | REST 레이어에서 활성화할 TLS 프로토콜이에요. Java 형식만 지원돼요. |
plugins.security.ssl.transport.enabled_ciphers |
Array | 트랜스포트 레이어에서 활성화할 TLS 암호 스위트예요. Java 형식만 지원돼요. |
plugins.security.ssl.transport.enabled_protocols |
Array | 트랜스포트 레이어에서 활성화할 TLS 프로토콜이에요. Java 형식만 지원돼요. |
설정 예시
plugins.security.ssl.http.enabled_ciphers:
- "TLS_DHE_RSA_WITH_AES_256_CBC_SHA"
- "TLS_DHE_DSS_WITH_AES_128_CBC_SHA256"
plugins.security.ssl.http.enabled_protocols:
- "TLSv1.1"
- "TLSv1.2"
TLSv1은 보안상 안전하지 않기 때문에 Security 플러그인은 기본적으로 TLSv1을 비활성화해요. TLSv1을 사용해야 하고 그 위험을 감수할 수 있다면, 여전히 활성화할 수 있어요:
plugins.security.ssl.http.enabled_protocols:
- "TLSv1"
- "TLSv1.1"
- "TLSv1.2"
(고급) Java 8에서 클라이언트 시작 재협상 비활성화하기
기본적으로 활성화되어 있는 클라이언트 시작 보안 재협상(secure client initiated renegotiation)을 비활성화하려면 -Djdk.tls.rejectClientInitiatedRenegotiation=true를 설정해요. 이 값은 config/jvm.options의 OPENSEARCH_JAVA_OPTS를 통해 설정할 수 있어요.
(고급) SSL에 암호화된 비밀번호 설정 사용하기
기본 제공되는 안전하지 않은 SSL 비밀번호 설정은 더 이상 권장되지 않아요(deprecated). 이 설정들의 보안 대체 버전을 사용하려면 대체 형식을 쓰면 돼요. 구체적으로 말하면, SSL 설정 이름에 _secure 접미사를 붙이면 돼요. 그렇게 만들어진 보안 대체 설정은 다음과 같아요:
- plugins.security.ssl.http.pemkey_password_secure
- plugins.security.ssl.http.keystore_password_secure
- plugins.security.ssl.http.keystore_keypassword_secure
- plugins.security.ssl.http.truststore_password_secure
- plugins.security.ssl.transport.pemkey_password_secure
- plugins.security.ssl.transport.server.pemkey_password_secure
- plugins.security.ssl.transport.client.pemkey_password_secure
- plugins.security.ssl.transport.keystore_password_secure
- plugins.security.ssl.transport.keystore_keypassword_secure
- plugins.security.ssl.transport.server.keystore_keypassword_secure
- plugins.security.ssl.transport.client.keystore_keypassword_secure
- plugins.security.ssl.transport.truststore_password_secure
이 설정들을 사용하면 설정에 암호화된 비밀번호를 사용할 수 있어요.
TLS 인증서 핫 리로딩
HTTP 레이어와 트랜스포트 레이어에서 만료되었거나 만료가 임박한 TLS 인증서를 업데이트하는 작업은 클러스터 재시작이 필요하지 않아요. 대신 TLS 인증서 핫 리로딩을 활성화할 수 있어요. 활성화하면 인플레이스(in-place) 핫 리로딩이 5초마다 키스토어 리소스에 업데이트가 있는지 모니터링해요. OpenSearch config 디렉터리에서 인증서, 키 파일, 키스토어 설정을 추가하거나 수정하면, 클러스터의 노드가 변경을 감지하고 키와 인증서를 자동으로 리로드해요.
인플레이스 핫 리로딩을 활성화하려면 opensearch.yml에 다음 줄을 추가하세요:
plugins.security.ssl.certificates_hot_reload.enabled: true
{% include copy.html %}
Reload Certificates API 사용하기
핫 리로딩을 사용하지 않는 경우에는 Reload Certificates API를 사용해서 교체된 인증서를 다시 읽을 수 있어요.
Reload Certificates API를 활성화하려면 opensearch.yml에 다음 줄을 추가하세요:
plugins.security.ssl_cert_reload_enabled: true
{% include copy.html %}
이 설정의 기본값은 false예요.
{: .note }
리로딩을 활성화한 후에는 Reload Certificates API를 사용해서 만료된 인증서를 교체해요. opensearch.yml 파일이 변경되지 않도록 새 인증서는 이전 인증서와 같은 위치에 저장해야 해요.
기본적으로 Reload Certificates API는 기존 인증서가 동일한 Issuer/Subject DN과 SAN으로 발급된 유효한 인증서로 교체되기를 기대해요. opensearch.yml에 다음 설정을 추가하면 이 동작을 비활성화할 수 있어요:
plugins.security.ssl.http.enforce_cert_reload_dn_verification: false
plugins.security.ssl.transport.enforce_cert_reload_dn_verification: false
{% include copy.html %}
슈퍼 어드민만 Reload Certificates API를 사용할 수 있어요. {: .note }
트랜스포트 레이어에서 TLS 인증서 리로드하기
다음 명령어는 Reload Certificates API를 사용해서 트랜스포트 레이어의 TLS 인증서를 리로드해요:
curl --cacert <ca.pem> --cert <admin.pem> --key <admin.key> -XPUT https://localhost:9200/_plugins/_security/api/ssl/transport/reloadcerts
{% include copy.html %}
다음과 같은 응답을 받게 돼요:
{ "message": "successfully updated transport certs"}
HTTP 레이어에서 TLS 인증서 리로드하기
다음 명령어는 Reload Certificates API를 사용해서 HTTP 레이어의 TLS 인증서를 리로드해요:
curl --cacert <ca.pem> --cert <admin.pem> --key <admin.key> -XPUT https://localhost:9200/_plugins/_security/api/ssl/http/reloadcerts
{% include copy.html %}
다음과 같은 응답을 받게 돼요:
{ "message": "successfully updated http certs"}
gRPC용 TLS 인증서 구성하기
opensearch.yml에서 선택 사항인 gRPC 트랜스포트에 TLS를 구성할 수 있어요. gRPC 플러그인 사용 방법에 대한 자세한 내용은 gRPC API 활성화하기를 참고하세요.
PEM 키 설정 (X.509 PEM 인증서 및 PKCS #8 키)
다음 표는 사용 가능한 gRPC PEM 키 설정을 보여줘요.
| 이름 | 설명 |
|---|---|
plugins.security.ssl.aux.secure-transport-grpc.enabled |
gRPC에 TLS를 활성화할지 여부예요. 활성화하면 HTTPS만 허용돼요. 선택 사항이에요. 기본값은 false예요. |
plugins.security.ssl.aux.secure-transport-grpc.pemkey_filepath |
인증서의 키 파일(PKCS #8) 경로예요. config 디렉터리 기준 상대 경로로 지정해요. 파일은 반드시 config 디렉터리 안에 있어야 해요. 필수 값이에요. |
plugins.security.ssl.aux.secure-transport-grpc.pemkey_password |
키 비밀번호예요. 키에 비밀번호가 없다면 이 설정은 생략해도 돼요. 선택 사항이에요. |
plugins.security.ssl.aux.secure-transport-grpc.pemcert_filepath |
X.509 노드 인증서 체인(PEM 형식) 경로예요. config 디렉터리 기준 상대 경로로 지정해요. 파일은 반드시 config 디렉터리 안에 있어야 해요. 필수 값이에요. |
plugins.security.ssl.aux.secure-transport-grpc.pemtrustedcas_filepath |
루트 CA(PEM 형식) 경로예요. config 디렉터리 기준 상대 경로로 지정해요. 파일은 반드시 config 디렉터리 안에 있어야 해요. 필수 값이에요. |
키스토어와 트러스트스토어
다음 표는 사용 가능한 gRPC 키스토어 및 트러스트스토어 설정을 보여줘요.
| 이름 | 설명 |
|---|---|
plugins.security.ssl.aux.secure-transport-grpc.enabled |
gRPC에 TLS를 활성화할지 여부예요. 활성화하면 HTTPS만 허용돼요. 선택 사항이에요. 기본값은 false예요. |
plugins.security.ssl.aux.secure-transport-grpc.keystore_type |
키스토어 파일의 타입이에요. JKS 또는 PKCS12/PFX를 사용할 수 있어요. 선택 사항이에요. 기본값은 JKS예요. |
plugins.security.ssl.aux.secure-transport-grpc.keystore_filepath |
키스토어 파일 경로예요. config 디렉터리 기준 상대 경로로 지정해요. 파일은 반드시 config 디렉터리 안에 있어야 해요. 필수 값이에요. |
plugins.security.ssl.aux.secure-transport-grpc.keystore_alias |
제공된 키스토어에서 사용할 키 쌍의 별칭이에요. 선택 사항이에요. 기본값은 키스토어에 추가된 첫 번째 키 쌍이에요. |
plugins.security.ssl.aux.secure-transport-grpc.keystore_password |
키스토어 비밀번호예요. 기본값은 changeit이에요. |
plugins.security.ssl.aux.secure-transport-grpc.truststore_type |
트러스트스토어 파일의 타입이에요. JKS 또는 PKCS12/PFX를 사용할 수 있어요. 기본값은 JKS예요. |
plugins.security.ssl.aux.secure-transport-grpc.truststore_filepath |
트러스트스토어 파일 경로예요. config 디렉터리 기준 상대 경로로 지정해요. 파일은 반드시 config 디렉터리 안에 있어야 해요. 필수 값이에요. |
plugins.security.ssl.aux.secure-transport-grpc.truststore_alias |
제공된 트러스트스토어에서 사용할 인증서의 별칭이에요. 선택 사항이에요. 기본값은 모든 인증서예요. |
plugins.security.ssl.aux.secure-transport-grpc.truststore_password |
트러스트스토어 비밀번호예요. 기본값은 changeit이에요. |
문제 해결
- 일반적인 TLS 구성 문제의 해결 방법은 TLS 문제 해결을 참고하세요.