TCP listener 구성

TCP listener는 Vault가 TCP 주소/포트에서 수신하도록 구성합니다.

출처: 문서

본문

IPv6 준수 Vault Enterprise는 특정 운영 체제와 storage backend에 대해 OMB Mandate M-21-07 및 Federal IPv6 policy requirements를 준수합니다.

listener "tcp" {
  address = "127.0.0.1:8200"
}

listener 스탠자는 여러 번 지정하여 Vault가 여러 인터페이스에서 수신하도록 할 수 있습니다. 여러 listener를 구성한다면 Vault가 다른 노드에 올바른 주소를 알릴 수 있도록 api_addr와 cluster_addr도 지정해야 합니다.

인증되지 않은 엔드포인트의 민감한 데이터 편집(redaction)

인증되지 않은 API 엔드포인트는 다음과 같은 민감한 정보를 반환할 수 있습니다:

Vault 버전 번호
Vault 바이너리 빌드 날짜
Vault 클러스터 이름
클러스터 내 노드의 IP 주소

Vault는 각 tcp listener 스탠자를 구성해 적절할 때 이러한 값을 응답에서 편집할 수 있는 기능을 제공합니다.

다음 API 엔드포인트는 listener 스탠자 구성에 기반한 편집을 지원합니다:

/sys/health
/sys/leader
/sys/seal-status

Vault는 편집된 정보를 빈 문자열("")로 대체합니다. 일부 Vault API는 해당 값이 비어 있을 때("") 응답에서 키를 생략하기도 합니다.

값 편집은 모든 API 클라이언트의 응답에 영향을 줍니다 Vault CLI와 UI는 Vault API 응답을 소비합니다. 결과적으로 편집 설정은 직접 API 호출뿐 아니라 CLI와 UI 출력에도 적용됩니다.

기본 TLS 구성

기본적으로 Vault TCP listener는 TLS 1.2 또는 1.3 연결만 허용하며, TLS 1.0 또는 1.1을 사용하는 클라이언트의 연결 요청은 버립니다.

Vault는 기본적으로 다음 ciphersuite를 사용합니다:

TLS 1.3 - TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, 또는 TLS_CHACHA20_POLY1305_SHA256.
TLS 1.2 - RSA 또는 ECDSA 인증서로 Vault를 구성했는지에 따라 달라집니다.

tls 및 tlsutil Go 패키지가 지원하는 모든 암호로 Vault를 구성할 수 있습니다. Vault는 tlsutil 패키지를 사용해 ciphersuite 구성을 해석합니다.

Sweet32 및 3DES Go 팀과 HashiCorp는 tls와 tlsutil이 지원하는 암호 집합이 현대적이고 안전한 사용에 적합하다고 믿습니다. 그러나 일부 취약성 스캐너는 구성의 문제를 지적할 수 있습니다. 특히 Sweet32(CVE-2016-2183)는 3DES를 포함한 64비트 블록 크기 암호에 대한 공격으로, 공격자가 장기 연결의 암호화를 깨뜨릴 수 있습니다. 취약성 공개에 따르면 Sweet32는 암호화를 깨뜨리는 데 785 GB 트래픽의 단일 HTTPS 세션을 필요로 했습니다. 2024년 5월 기준으로 Go 팀은 3DES 지원을 폐기해 기존 클라이언트 호환성을 제거할 만큼 Sweet32의 위험이 충분하지 않다고 믿지만, AES 기반 암호를 선호하도록 3DES의 우선 순위를 낮췄습니다. Vault 기본값을 재정의하기 전에 ciphersuite 선택에 특히 주의하며 권장되는 Go 팀의 TLS 구성 접근 방식을 검토할 것을 권장합니다.

토큰 헤더 크기

불투명(opaque) Vault 토큰은 고정 크기이며 8 KB보다 훨씬 작으므로 표준 배포에는 기본값이 충분합니다. 큰 authorization_details 페이로드를 운반하는 엔터프라이즈 JWT 토큰이나 OIDC 토큰을 사용하고 토큰 헤더 크기가 8 KB를 초과할 때 max_token_header_size를 높이세요. 가장 큰 토큰 크기를 평가하고 그에 따라 한도를 설정하세요.

listener "tcp" {
  address               = "127.0.0.1:8200"
  max_token_header_size = 16384  # raise to 16 KB for large JWT claims
}

max_token_header_size는 API listener에만 적용됩니다. Vault는 클러스터 노드 간(HA 피어, performance replication 보조)의 포워딩된 요청에 토큰 헤더 크기 검사를 적용하지 않으므로, 발신 노드가 수락한 요청이 다운스트림에서 거부되지 않습니다. HA 또는 performance replication 구성에는 추가 구성이 필요하지 않습니다.

Listener의 사용자 지정 응답 헤더

버전 1.9부터 Vault는 루트 경로(/)와 API 엔드포인트(/v1/*)에 대한 사용자 지정 HTTP 응답 헤더 정의를 지원합니다. 헤더는 반환된 상태 코드에 따라 정의됩니다. 예를 들어 200 상태 코드에 대한 응답 헤더 목록과 307 상태 코드에 대한 다른 응답 헤더 목록을 정의할 수 있습니다. "/sys/config/ui" API 엔드포인트는 사용자가 UI 고유 사용자 지정 헤더를 설정할 수 있게 합니다. 구성 파일에 헤더가 구성되면 "/sys/config/ui" API 엔드포인트를 통해 재구성할 수 없습니다. 사용자 지정 헤더 값을 수정하거나 제거해야 하는 경우 Vault 구성 파일을 그에 맞게 수정하고 Vault 프로세스에 SIGHUP 신호를 보내야 합니다.

구성 파일에 헤더가 정의되고 같은 헤더를 Vault의 내부 프로세스가 사용한다면 구성된 헤더는 허용되지 않습니다. 예를 들어 X-Vault- 접두사가 있는 사용자 지정 헤더는 허용되지 않습니다. 시작 시 X-Vault- 접두사가 있는 헤더가 허용되지 않는다는 메시지가 Vault 로그에 기록됩니다.

우선순위 순서

같은 헤더가 구성 파일과 "/sys/config/ui" API 엔드포인트 양쪽에 구성되면 구성 파일의 헤더가 우선합니다. 예를 들어 "Content-Security-Policy" 헤더는 기본적으로 "/sys/config/ui" API 엔드포인트에 정의되어 있습니다. 그 헤더가 구성 파일에도 정의되어 있다면 구성 파일의 값이 "/sys/config/ui" API 엔드포인트의 기본값 대신 응답 헤더에 설정됩니다.

`tcp` listener 파라미터

address (string: "127.0.0.1:8200") – 수신을 위해 바인딩할 주소를 지정합니다. 런타임에 해석되는 go-sockaddr 템플릿으로 동적으로 정의할 수 있습니다.
cluster_address (string: "127.0.0.1:8201") – 클러스터 서버 간 요청을 위해 바인딩할 주소를 지정합니다. 기본값은 address 값보다 한 포트 높습니다. 보통 설정할 필요는 없지만, Vault 서버들이 TCP 로드 밸런서나 다른 방식을 통해 홉해야 하는 방식으로 서로 격리되어 있는 경우 유용할 수 있습니다. 런타임에 해석되는 go-sockaddr 템플릿으로 동적으로 정의할 수 있습니다.
chroot_namespace (string: "") – listener의 대체 최상위 namespace를 지정합니다. Vault는 X-Vault-Namespace 헤더 또는 CLI 명령의 -namespace 필드에서 제공된 namespaces를 최상위 namespace에 추가해 요청의 전체 namespace 경로를 결정합니다. 예를 들어 chroot_namespace가 admin으로 설정되고 X-Vault-Namespace 헤더가 ns1이면 전체 namespace 경로는 admin/ns1입니다. chroot_namespace에 제공된 최상위 namespace가 존재하지 않으면 listener에 대한 호출은 4XX 오류로 실패합니다.
http_idle_timeout (string: "5m") - keep-alive가 활성화되어 있을 때 다음 요청을 기다리는 최대 시간을 지정합니다. http_idle_timeout이 0이면 http_read_timeout 값이 사용됩니다. 둘 다 0이면 http_read_header_timeout 값이 사용됩니다. "30s"나 "1h" 같은 라벨 접미사로 지정합니다.
http_read_header_timeout (string: "10s") - 요청 헤더를 읽는 데 허용되는 시간을 지정합니다. "30s"나 "1h" 같은 라벨 접미사로 지정합니다.
http_read_timeout (string: "30s") - 본문을 포함한 전체 요청을 읽는 최대 기간을 지정합니다. "30s"나 "1h" 같은 라벨 접미사로 지정합니다.
http_write_timeout string: "0") - 응답 쓰기가 타임아웃되기 전의 최대 기간을 지정하며, 새 요청의 헤더가 읽힐 때마다 재설정됩니다. 기본값 "0"은 무한대를 의미합니다. "30s"나 "1h" 같은 라벨 접미사로 지정합니다.
max_request_size (int: 33554432) – 허용되는 하드 최대 요청 크기(바이트)를 지정합니다. 설정하지 않거나 0으로 설정하면 기본값 32 MB입니다. 0보다 작은 수를 지정하면 제한을 완전히 끕니다.

max_token_header_size (int: 8192) – X-Vault-Token 또는 Authorization과 함께 전달되는 인증 토큰 헤더 값의 최대 허용 크기(바이트)를 지정합니다. 최대 토큰 크기는 큰 authorization_details claim을 가진 과도하게 큰 가변 길이 토큰으로 인한 메모리 고갈로부터 보호하는 defense-in-depth 가드레일입니다. 구성된 한도를 초과하는 요청에 대해 Vault는 431 상태 코드와 authentication token exceeds maximum allowed header size를 포함한 오류 메시지를 반환합니다. 이 값을 언제 변경해야 하는지에 대한 지침은 Authentication token header size를 참고하세요.

값	동작
0 또는 미설정	기본 한도인 8192바이트(8 KB)를 사용합니다.
양의 정수	그 바이트 수만큼 한도를 설정합니다.
-1(또는 음의 정수)	8 KB 애플리케이션 수준 검사를 제거합니다. Vault는 여전히 Go stdlib MaxHeaderBytes 백스톱(~1 MB)에 기반한 요청의 상한을 적용하며, 그 한도를 초과하는 요청에는 431(Request Header Fields Too Large)을 반환합니다.

max_request_duration (string: "90s") – Vault가 요청을 취소하기 전에 허용되는 최대 요청 시간을 지정합니다. 이 값은 이 listener에 대해 default_max_request_duration을 재정의합니다.
proxy_protocol_behavior (string: "") – 지정되면 listener에 대한 PROXY 프로토콜 동작을 활성화합니다(버전 1과 2 모두 지원). 허용되는 값:
- use_always - 클라이언트의 IP 주소가 항상 사용됩니다.
- allow_authorized - 소스 IP 주소가 proxy_protocol_authorized_addrs 목록에 있으면 클라이언트의 IP 주소가 사용됩니다. 소스 IP가 목록에 없으면 소스 IP 주소가 사용됩니다.
- deny_unauthorized - 소스 IP 주소가 proxy_protocol_authorized_addrs 목록에 없으면 트래픽이 거부됩니다.
proxy_protocol_authorized_addrs (string: <required-if-enabled> or array: <required-if-enabled> ) – PROXY 프로토콜과 함께 사용할 허용된 소스 IP 주소 목록을 지정합니다. proxy_protocol_behavior가 use_always로 설정되면 필요하지 않습니다. 문자열로 제공되면 소스 IP는 쉼표로 구분해야 합니다. 최소 하나의 소스 IP가 제공되어야 하며, proxy_protocol_authorized_addrs는 빈 배열이나 문자열일 수 없습니다.
redact_addresses (bool: false) - true일 때 적용 가능한 API 응답의 leader_address 및 cluster_leader_address 값을 편집합니다.
redact_cluster_name (bool: false) - true일 때 적용 가능한 API 응답의 cluster_name 값을 편집합니다.
redact_version (bool: false) - true일 때 적용 가능한 API 응답의 version 및 build_date 값을 편집합니다.
tls_disable (string: "false") – TLS를 비활성화할지 여부를 지정합니다. Vault는 기본적으로 TLS를 가정하므로 안전하지 않은 통신을 선택하려면 명시적으로 TLS를 비활성화해야 합니다. TLS 비활성화는 일부 UI 기능을 비활성화할 수 있습니다. 자세한 내용은 Browser Support 페이지를 참고하세요.
tls_cert_file (string: <required-if-enabled>, reloads-on-SIGHUP) – TLS용 인증서의 경로를 지정합니다. PEM으로 인코딩된 파일이 필요합니다. CA 인증서를 사용하도록 listener를 구성하려면 기본 인증서와 CA 인증서를 함께 연결하세요. 기본 인증서가 결합된 파일에서 먼저 와야 합니다. SIGHUP 시 Vault 시작 시점에 여기 설정된 경로가 인증서를 리로드하는 데 사용됩니다. Vault 실행 중에 이 값을 수정해도 SIGHUP에는 영향을 주지 않습니다.
tls_key_file (string: <required-if-enabled>, reloads-on-SIGHUP) – 인증서의 개인 키 경로를 지정합니다. PEM으로 인코딩된 파일이 필요합니다. 키 파일이 암호화되어 있으면 서버 시작 시 암호 문구를 입력하라는 메시지가 표시됩니다. SIGHUP로 구성을 리로드할 때 키 파일 사이의 암호 문구는 동일해야 합니다. SIGHUP 시 Vault 시작 시점에 여기 설정된 경로가 인증서를 리로드하는 데 사용됩니다. Vault 실행 중에 이 값을 수정해도 SIGHUP에는 영향을 주지 않습니다.
tls_min_version (string: "tls12") – 지원되는 최소 TLS 버전을 지정합니다. 허용되는 값은 "tls10", "tls11", "tls12" 또는 "tls13"입니다.

경고: TLS 1.1 이하(tls_min_version 및 tls_max_version 파라미터의 tls10 및 tls11 값)는 널리 안전하지 않은 것으로 간주됩니다.
tls_max_version (string: "tls13") – 지원되는 최대 TLS 버전을 지정합니다. 허용되는 값은 "tls10", "tls11", "tls12" 또는 "tls13"입니다.

경고: TLS 1.1 이하(tls_min_version 및 tls_max_version 파라미터의 tls10 및 tls11 값)는 널리 안전하지 않은 것으로 간주됩니다.
tls_cipher_suites (string: "") – 지원되는 ciphersuite 목록을 쉼표로 구분된 목록으로 지정합니다. 사용 가능한 모든 ciphersuite 목록은 Golang TLS 문서에서 확인할 수 있습니다.

참고: Go는 TLSv1.2 및 이전 버전에 대해서만 tls_cipher_suites 목록을 참조합니다. 암호의 순서는 중요하지 않습니다. 이 파라미터가 효과를 가지려면 권장되지 않는 TLSv1.3 협상을 방지하기 위해 tls_max_version 속성을 tls12로 설정해야 합니다. 이와 다른 TLS 관련 변경에 대한 자세한 내용은 Go TLS 블로그 게시물을 참고하세요.
tls_prefer_server_cipher_suites (string: "false") – 클라이언트 ciphersuite보다 서버 ciphersuite를 선호하도록 지정합니다.

경고: tls_prefer_server_cipher_suites 파라미터는 더 이상 사용되지 않습니다. 설정해도 효과가 없습니다. 이 변경에 대한 자세한 내용은 위의 Go 블로그 게시물을 참고하세요.
tls_require_and_verify_client_cert (string: "false") – 이 listener에 대한 클라이언트 인증을 켭니다. listener는 시스템 CA에 대해 성공적으로 검증되는 제시된 클라이언트 인증서를 요구합니다.
tls_client_ca_file (string: "") – 클라이언트의 진위를 확인하는 데 사용되는 PEM으로 인코딩된 Certificate Authority 파일입니다.
tls_disable_client_certs (string: "false") – 이 listener에 대한 클라이언트 인증을 끕니다. 기본 동작(false일 때)은 Vault가 사용 가능할 때 클라이언트 인증 인증서를 요청하는 것입니다.

경고: Vault 서버 구성의 listener 스탠자에서 tls_disable_client_certs와 tls_require_and_verify_client_cert 필드는 상호 배타적입니다. 둘 다 true로 설정되지 않도록 주의하세요. TLS 클라이언트 검증은 기본 설정에서 선택 사항으로 유지되며 강제되지 않습니다.
x_forwarded_for_authorized_addrs (string: <required-to-enable>) – X-Forwarded-For 헤더가 신뢰될 소스 IP CIDR 목록을 지정합니다. 쉼표로 구분된 목록 또는 JSON 배열입니다. 이것은 X-Forwarded-For 지원을 켭니다. 예를 들어 Vault가 로드 밸런서 IP 1.2.3.4에서 연결을 받는다면 x_forwarded_for_authorized_addrs에 1.2.3.4를 추가하면 audit 로그의 remote_address 필드가 연결 클라이언트의 IP(예: 3.4.5.6)로 채워집니다. 이는 로드 밸런서가 X-Forwarded-For 헤더에 연결 클라이언트의 IP를 보내야 합니다.
x_forwarded_for_client_cert_header (string: "") – 클라이언트 인증서에 사용될 헤더를 지정합니다. TLS Certificates Auth Method를 사용하고 Vault 서버가 리버스 프록시 뒤에 있다면 필요합니다.
x_forwarded_for_client_cert_header_decoders (string: "") – 클라이언트 인증서를 완전히 디코드하기 위해 적용되는 디코더를 순서대로 지정하는 쉼표로 구분된 목록입니다. TLS Certificates Auth Method를 사용하고 Vault 서버가 리버스 프록시 뒤에 있다면 필요합니다. 결과 인증서는 DER 형식이어야 합니다. 사용 가능한 값:
- BASE64 - Base64 디코드를 실행합니다
- DER - PEM 인증서를 DER로 변환합니다
- URL - URL 디코드를 실행합니다
알려진 값:
- Traefik = "BASE64"
- NGINX = "URL,DER"
경고: "DER"라고 이름 붙여졌지만, DER 디코더는 PEM 번들로부터 DER 인증서를 만듭니다. 항상 마지막에 적용해야 하며, 클라이언트 인증서에 PEM 래핑(예: ----- BEGIN으로 시작)이 포함된 경우에만 사용하는 것이 적절합니다.
x_forwarded_for_hop_skips (string: "0") – hops 집합의 뒤에서 건너뛸 주소 수입니다. 예를 들어 헤더 값이 1.2.3.4, 2.3.4.5, 3.4.5.6, 4.5.6.7일 때 이 값이 "1"로 설정되면 발신 클라이언트 IP로 사용될 주소는 3.4.5.6입니다.
x_forwarded_for_reject_not_authorized (string: "true") – false로 설정하면, 권한 없는 주소의 연결에 X-Forwarded-For 헤더가 있을 때 헤더를 무시하고 클라이언트 연결을 거부하는 대신 그대로 사용합니다.
x_forwarded_for_reject_not_present (string: "true") – false로 설정하면, X-Forwarded-For 헤더가 없거나 비어 있을 때 클라이언트 연결을 거부하는 대신 클라이언트 주소를 그대로 사용합니다.
disable_replication_status_endpoints (bool: false) - true로 설정하면 구성된 listener에 대한 복제 상태 엔드포인트를 비활성화합니다.

JSON 구문 분석 한도(max_json_depth와 max_json_token 등)는 광범위한 사용 사례를 지원하기 위해 의도적으로 관대한 기본값을 가집니다. 구문 분석 한도의 주요 제약 조건은 사용 가능한 RAM과 CPU입니다. JSON 구문 분석 한도를 특정 애플리케이션 요구와 사용 가능한 리소스에 맞도록 기본값에서 낮추는 것을 권장합니다. 구문 분석 한도가 상호 작용하는 방식 때문에 경량 컨테이너 같은 저리소스 환경에서 관대한 기본값으로 실행하면 크고 복잡한 JSON 페이로드가 사용 가능한 리소스를 고갈시킬 위험이 커질 수 있습니다.

max_json_depth (int: 500) – JSON 페이로드의 최대 중첩 깊이를 지정합니다. 객체 깊이 제한은 깊게 중첩된 객체로 인한 스택 고갈 위험을 완화하며, 이는 서비스 거부(DoS)로 이어질 수 있습니다.
max_json_string_value_length (int: 1048576) – JSON 페이로드 내 단일 문자열 값의 최대 허용 길이(바이트)를 정의합니다. 문자열 길이 제한은 클라이언트가 매우 큰 문자열을 보내 서버 메모리를 고갈시키는 과도한 메모리 할당 공격에 대한 중요한 방어를 제공합니다. 기본값은 1MB입니다.
max_json_object_entry_count (int: 10000) – 단일 JSON 객체에서 허용되는 키-값 쌍의 최대 수를 설정합니다. JSON 객체의 항목 수를 제한하면 해시 충돌 서비스 거부(HashDoS) 공격을 완화하고 과도한 수의 항목을 가진 객체로 인한 일반적인 리소스 고갈을 방지합니다.
max_json_array_element_count (int: 10000) – 단일 JSON 배열에서 허용되는 최대 요소 수를 결정합니다. 배열 요소 수를 제한하면 큰 목록 처리 시 단일 요청이 과도한 메모리 소비를 일으키는 것을 방지합니다.
max_json_token (int: 500000) – 단일 JSON 페이로드에서 허용되는 총 토큰(예: 키, 값, 중괄호, 대괄호) 수를 설정합니다. 토큰 수에 대한 제한은 CPU와 메모리를 고갈시키기 위해 엄청난 수의 작은 요소를 사용하는 공격에 대한 방어책으로 전체 복잡성 한도로 작동합니다.

`telemetry` 파라미터

unauthenticated_metrics_access (bool: false) - true로 설정하면 /v1/sys/metrics 엔드포인트에 대한 인증되지 않은 접근을 허용합니다.

`profiling` 파라미터

unauthenticated_pprof_access (bool: false) - true로 설정하면 /v1/sys/pprof 엔드포인트에 대한 인증되지 않은 접근을 허용합니다.

`inflight_requests_logging` 파라미터

unauthenticated_in_flight_requests_access (bool: false) - true로 설정하면 /v1/sys/in-flight-req 엔드포인트에 대한 인증되지 않은 접근을 허용합니다.

`custom_response_headers` 파라미터

default (key-value-map: {}) - 문자열 헤더 이름과 문자열 값 배열의 맵입니다. 기본 헤더는 상태 코드 값과 관계없이 모든 엔드포인트에 설정됩니다. 예시는 "Configuring custom http response headers" 섹션을 참고하세요.
<specific status code> (key-value-map: {}) - 문자열 헤더 이름과 문자열 값 배열의 맵입니다. 이 헤더는 특정 상태 코드가 반환될 때만 설정됩니다. 예를 들어 "200" = {"Header-A": ["Value1", "Value2"]}이면 HTTP 응답 상태 코드가 "200"일 때 "Header-A"가 설정됩니다.
<collective status code> (key-value-map: {}) - 문자열 헤더 이름과 문자열 값 배열의 맵입니다. 이 헤더는 응답 상태 코드가 집계 상태 코드 아래에 속할 때만 설정됩니다. 예를 들어 "2xx" = {"Header-A": ["Value1", "Value2"]}이면 HTTP 응답 상태 코드가 "200", "204" 등일 때 "Header-A"가 설정됩니다.

`tcp` listener 예시

TLS 구성

이 예시는 TLS listener를 활성화하는 방법을 보여줍니다.

listener "tcp" {
  address = "127.0.0.1:8200"
  tls_cert_file = "/etc/certs/vault.crt"
  tls_key_file  = "/etc/certs/vault.key"
}

여러 인터페이스에서 수신

이 예시는 Vault가 개인 인터페이스와 localhost 모두에서 수신하도록 합니다.

listener "tcp" {
  address = "127.0.0.1:8200"
}

listener "tcp" {
  address = "10.0.0.5:8200"
}

# Advertise the non-loopback interface
api_addr = "https://10.0.0.5:8200"
cluster_addr = "https://10.0.0.5:8201"

인증되지 않은 메트릭 접근 구성

이 예시는 인증되지 않은 메트릭 접근을 활성화하는 방법을 보여줍니다.

listener "tcp" {
  telemetry {
    unauthenticated_metrics_access = true
  }
}

인증되지 않은 프로파일링 접근 구성

이 예시는 인증되지 않은 프로파일링 접근을 활성화하는 방법을 보여줍니다.

listener "tcp" {
  profiling {
    unauthenticated_pprof_access = true
    unauthenticated_in_flight_request_access = true
  }
}

사용자 지정 http 응답 헤더 구성

참고: Vault 버전 1.9 이상이 필요합니다. 이 예시는 사용자 지정 http 응답 헤더를 구성하는 방법을 보여줍니다. 운영자는 listener 스탠자에서 "custom_response_headers" 하위 스탠자를 구성해 애플리케이션에 적합한 사용자 지정 http 헤더를 설정할 수 있습니다. "Strict-Transport-Security"와 "Content-Security-Policy"는 알려진 HTTP 헤더의 예시이며, Vault 엔드포인트와 통신하는 애플리케이션의 보안을 강화하도록 구성할 수 있습니다. 취약성 스캔이 종종 이러한 보안 관련 HTTP 헤더를 검사한다는 점에 유의하세요. 또한 애플리케이션 고유의 사용자 지정 헤더도 구성할 수 있습니다. 예를 들어 아래 예시에서 "X-Custom-Header"가 구성되어 있습니다.

listener "tcp" {
  custom_response_headers {
    "default" = {
      "Strict-Transport-Security" = ["max-age=31536000","includeSubDomains"],
      "Content-Security-Policy" = ["connect-src https://clusterA.vault.external/"],
      "X-Custom-Header" = ["Custom Header Default Value"],
    },
    "2xx" = {
      "Content-Security-Policy" = ["connect-src https://clusterB.vault.external/"],
      "X-Custom-Header" = ["Custom Header Value 1", "Custom Header Value 2"],
    },
    "301" = {
      "Strict-Transport-Security" = ["max-age=31536000"],
      "Content-Security-Policy" = ["connect-src https://clusterC.vault.external/"],
    },
  }
}

여러 상태 코드 하위 섹션에 헤더가 정의된 상황에서는 가장 구체적인 응답 코드와 일치하는 헤더가 반환됩니다. 예를 들어 아래 구성 예시에서 307 응답은 307 Custom header value를 반환하고 306은 3xx Custom header value를 반환합니다.

listener "tcp" {
  custom_response_headers {
    "default" = {
       "X-Custom-Header" = ["default Custom header value"]
    },
    "3xx" = {
       "X-Custom-Header" = ["3xx Custom header value"]
    },
    "307" = {
       "X-Custom-Header" = ["307 Custom header value"]
    }
  }
}

모든 IPv6 & IPv4 인터페이스에서 수신

이 예시는 Vault가 localhost를 포함한 모든 IPv4 & IPv6 인터페이스에서 수신하도록 합니다.

listener "tcp" {
  address         = "[::]:8200"
  cluster_address = "[::]:8201"
}

특정 IPv6 주소에서 수신

이 예시는 Vault가 IPv6만 사용하고 IP 주소 2001:1c04:90d:1c00:a00:27ff:fefa:58ec를 가진 인터페이스에 바인딩하도록 합니다.

listener "tcp" {
  address         = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
  cluster_address = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"
}

# Advertise the non-loopback interface
api_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
cluster_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"

편집(Redaction) 예시

각 편집 설정에 대한 자세한 내용은 위의 편집 설정을 참고하세요.

redact_addresses, redact_cluster_name, redact_version을 활성화하는 tcp listener의 예시 구성:

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_1"
}

listener "tcp" {
  address             = "127.0.0.1:8200",
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
  redact_addresses    = "true"
  redact_cluster_name = "true"
  redact_version      = "true"
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}

API: `/sys/health`

다음 /sys/health/ 호출에서 cluster_name과 version이 모두 편집된 것을 볼 수 있습니다. cluster_name 필드는 응답에서 완전히 생략되고 version은 빈 문자열("")입니다.

$ curl -s https://127.0.0.1:8200/v1/sys/health | jq:

{
  "initialized": true,
  "sealed": false,
  "standby": true,
  "performance_standby": false,
  "replication_performance_mode": "disabled",
  "replication_dr_mode": "disabled",
  "server_time_utc": 1696598650,
  "version": "",
  "cluster_id": "a1a7a078-0ae1-7fb9-41ec-2f4f583c773e"
}

API: `sys/leader`

다음 /sys/leader/ 호출에서 leader_address와 leader_cluster_address가 모두 편집되어 빈 문자열("")로 설정된 것을 볼 수 있습니다.

$ curl -s https://127.0.0.1:8200/v1/sys/leader | jq:

{
  "ha_enabled": true,
  "is_self": false,
  "active_time": "0001-01-01T00:00:00Z",
  "leader_address": "",
  "leader_cluster_address": "",
  "performance_standby": false,
  "performance_standby_last_remote_wal": 0,
  "raft_committed_index": 164,
  "raft_applied_index": 164
}

API: `sys/seal-status`

다음 /sys/seal-status/ 호출에서 cluster_name, build_date, version이 모두 편집된 것을 볼 수 있습니다. cluster_name 필드는 응답에서 완전히 생략되고 build_date와 version은 빈 문자열("")입니다.

$ curl -s https://127.0.0.1:8200/v1/sys/seal-status | jq:

{
  "type": "shamir",
  "initialized": true,
  "sealed": false,
  "t": 1,
  "n": 1,
  "progress": 0,
  "nonce": "",
  "version": "",
  "build_date": "",
  "migration": false,
  "cluster_id": "a1a7a078-0ae1-7fb9-41ec-2f4f583c773e",
  "recovery_seal": false,
  "storage_type": "raft"
}

CLI: `vault status`

CLI 명령 vault status는 데이터 편집을 지원하는 엔드포인트를 사용하므로 출력에서 Version, Build Date, HA Cluster, Active Node Address를 편집합니다. Version, Build Date, HA Cluster는 기본 엔드포인트가 빈 문자열을 반환했기 때문에 n/a로 표시되고, Active Node Address는 API 응답에서 생략되었기 때문에 <none>으로 표시됩니다.


$ vault status

Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            5
Threshold               3
Version                 n/a
Build Date              n/a
Storage Type            raft
HA Enabled              true
HA Cluster              n/a
HA Mode                 standby
Active Node Address     <none>
Raft Committed Index    219
Raft Applied Index      219

TCP listener 구성