donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka 58515ab0f3 feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00

12 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title

source_type

url

archive_url

related_branches

related_projects

official-doc / Apache Kafka — Client Security Configuration (SSL / SASL)

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

source_type 허용값

official-doc — Apache Kafka 프로젝트가 직접 배포하는 공식 레퍼런스 문서.

Parent / 활용 branch (필수, 최소 1개+)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-kafka-producer-runtime-contract	ca-skeleton 의 Kafka producer 가 TLS/SASL 설정 키를 어떤 이름으로 갖는지, 그리고 어떤 값이 secret 분류 대상(keystore/truststore 비밀번호, SASL 자격증명)인지를 registry 등록 전에 공식 키 이름으로 확정한다

출처

원본 URL (사용자 요청): https://kafka.apache.org/documentation/#security_configclients
URL 리다이렉트 확인 사항: 위 URL 은 client-side JS 리다이렉트 stub(window.location.replace(...)) 이다. curl 로 raw HTML 을 직접 받아 확인한 결과, 과거 단일 대형 페이지(documentation.html)의 "Configuring Kafka Clients" 앵커는 Kafka 4.3 문서 재구성(Hugo/Docsy 기반) 이후 다음 3개 세부 페이지로 분리되어 있다. 이 raw 문서의 인용은 모두 이 3개 페이지에서 발췌했다:
- https://kafka.apache.org/43/security/listener-configuration/ (security.protocol 값 목록)
- https://kafka.apache.org/43/security/encryption-and-authentication-using-ssl/ (SSL client Configuring Kafka Clients 섹션)
- https://kafka.apache.org/43/security/authentication-using-sasl/ (SASL client Configuring Kafka Clients 섹션 + mechanism 목록)
아카이브 URL: (미생성)
저자 / 조직: Apache Software Foundation — Apache Kafka 프로젝트
발행일: 각 페이지 하단 "Last modified May 22, 2026: MINOR: Add 4.3 docs and javadoc (#853) (dde051e342)" — Kafka 4.3 문서 빌드 기준
마지막 확인일: 2026-07-28

Fetch 방법에 대한 투명성 메모: WebFetch 툴을 원본 URL 과 /43/documentation.html(구조 추정) 두 형태로 3회 시도했으나, 매번 페이지 본문이 로드되기 전의 "Redirecting..." stub 만 반환됐다(JS 리다이렉트를 실행하지 않는 fetcher 한계). curl 로 raw HTML 을 직접 받아 리다이렉트 목적지(t="43", Hugo 사이드바 nav)를 역추적해 위 3개 실제 문서 페이지를 특정했고, 각 페이지 HTML 을 태그 제거 후 평문으로 저장했다(/tmp/source-fetch-20260728-170505.txt, 3개 페이지 연결본). 아래 모든 인용은 이 평문에 대해 grep -nF 로 self-grep 검증했다(에이전트 최종 리포트 참조). Confluent fallback(docs.confluent.io/platform/current/kafka/authentication_ssl.html)은 사용하지 않았다 — Apache 공식 페이지 원문을 실제로 확보했기 때문.

왜 저장했는지

ca-skeleton Kafka producer 의 TLS/SASL 설정을 구현하기 전에, Kafka 공식 문서가 실제로 정의하는 설정 키 이름(security.protocol, ssl.truststore.*, ssl.keystore.*, sasl.mechanism, sasl.jaas.config)과 값 집합을 근거로 고정해 두기 위함. 특히 keystore/truststore 비밀번호와 SASL 자격증명이 어떤 키에 담기는지를 공식 문서로 확정해야 secret 분류(예: env-driven config registry 에서 마스킹 대상 지정)를 임의로 하지 않을 수 있다.

핵심 인용

[§Listener Configuration] "Possible options (case-insensitive) for the security protocol are given below: PLAINTEXT SSL SASL_PLAINTEXT SASL_SSL The plaintext protocol provides no security and does not require any additional configuration."

[§Encryption and Authentication using SSL → Configuring Kafka Clients] "If client authentication is not required in the broker, then the following is a minimal configuration example: security.protocol=SSL ssl.truststore.location=/var/private/ssl/client.truststore.jks ssl.truststore.password=test1234"

[§Encryption and Authentication using SSL → Configuring Kafka Clients] "If client authentication is required, then a keystore must be created like in step 1 and the following must also be configured: ssl.keystore.location=/var/private/ssl/client.keystore.jks ssl.keystore.password=test1234 ssl.key.password=test1234"

[§Authentication using SASL/PLAIN → Configuring Kafka Clients] "The following is an example configuration for a client for the PLAIN mechanism: sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required
username="alice"
password="alice-secret";"

[§Authentication using SASL/PLAIN → Use of SASL/PLAIN in production] "SASL/PLAIN should be used only with SSL as transport layer to ensure that clear passwords are not transmitted on the wire without encryption. The default implementation of SASL/PLAIN in Kafka specifies usernames and passwords in the JAAS configuration file as shown here. From Kafka version 2.0 onwards, you can avoid storing clear passwords on disk by configuring your own callback handlers that obtain username and password from an external source using the configuration options sasl.server.callback.handler.class and sasl.client.callback.handler.class."

Claims Extracted

이 자료가 직접 말하는 것만 claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

Claim ID	Claim	Evidence quote	Strength	Applies to	Does not prove
KAFKA-SEC-C1	Kafka 의 `security.protocol` 은 정확히 4개 값(`PLAINTEXT`/`SSL`/`SASL_PLAINTEXT`/`SASL_SSL`) 중 하나이며, `PLAINTEXT` 는 보안을 제공하지 않는다	[§Listener Configuration] "Possible options (case-insensitive) for the security protocol are given below: PLAINTEXT SSL SASL_PLAINTEXT SASL_SSL The plaintext protocol provides no security..."	`official-vendor-doc`	producer/consumer/broker 공통 `security.protocol` 값 선택	Spring Boot `spring.kafka.*` 바인딩 프로퍼티 이름이 이와 동일하다는 것 — 이 문서는 native Kafka client config 이지 Spring Kafka autoconfiguration 문서가 아님
KAFKA-SEC-C2	client 인증(mTLS) 이 불필요한 경우 SSL client 최소 설정은 `security.protocol=SSL` + `ssl.truststore.location` + `ssl.truststore.password` 3개 키다	[§SSL → Configuring Kafka Clients] "the following is a minimal configuration example: security.protocol=SSL ssl.truststore.location=... ssl.truststore.password=..."	`official-vendor-doc`	단방향 TLS(서버 인증만) client 설정	`ssl.truststore.password` 가 필수라는 것 — 문서 다른 곳(SSL 페이지)에서 "technically optional but highly recommended" 라고 명시. mTLS 여부는 별도 결정
KAFKA-SEC-C3	client 인증(mTLS) 이 필요한 경우 추가로 `ssl.keystore.location` + `ssl.keystore.password` + `ssl.key.password` 3개 키가 필요하다	[§SSL → Configuring Kafka Clients] "If client authentication is required... ssl.keystore.location=... ssl.keystore.password=... ssl.key.password=..."	`official-vendor-doc`	mTLS(양방향 TLS) client 설정	ca-skeleton 이 실제로 mTLS 를 요구하는지 — 이는 배포 환경/브랜치 결정이지 이 문서가 증명하는 것이 아님
KAFKA-SEC-C4	SASL/PLAIN client 설정은 `sasl.jaas.config` 값 문자열 안에 `username`/`password` 를 리터럴로 직접 기입한다	[§SASL/PLAIN → Configuring Kafka Clients] "sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \ username="alice" \ password="alice-secret";"	`official-vendor-doc`	SASL/PLAIN mechanism 의 client-side JAAS 설정	이것이 유일한 방법이라는 것 — 같은 문서가 바로 이어서(KAFKA-SEC-C6) callback handler 대안을 언급함
KAFKA-SEC-C5	Kafka 가 공식 지원하는 SASL mechanism 은 정확히 5개: `GSSAPI (Kerberos)`, `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`, `OAUTHBEARER`	[§SASL mechanisms] "Kafka supports the following SASL mechanisms: GSSAPI (Kerberos) PLAIN SCRAM-SHA-256 SCRAM-SHA-512 OAUTHBEARER"	`official-vendor-doc`	`sasl.mechanism` 값 선택 범위	각 mechanism 이 프로덕션에 동등하게 권장된다는 것 — 문서는 기본 OAUTHBEARER 구현이 non-production 전용이라고 별도 경고함(이 raw 문서 범위 밖 세부사항)
KAFKA-SEC-C6	SASL/PLAIN 기본 구현은 자격증명을 JAAS 설정 파일/프로퍼티에 평문으로 저장하며, SSL 전송 없이는 자격증명이 평문으로 네트워크에 전송된다. Kafka 2.0+ 부터는 커스텀 callback handler 로 디스크 평문 저장을 피할 수 있다	[§SASL/PLAIN → Use of SASL/PLAIN in production] "SASL/PLAIN should be used only with SSL as transport layer to ensure that clear passwords are not transmitted on the wire without encryption. The default implementation... specifies usernames and passwords in the JAAS configuration file..."	`official-vendor-doc`	`sasl.jaas.config` 값(및 그 안의 `username`/`password`)을 secret 으로 분류해야 하는 근거	구체적인 vault/secret-manager 연동 방법 — Kafka 문서는 "커스텀 callback handler 로 회피 가능"까지만 말하고 구현체를 권고하지 않음

Strength 허용값

official-standard — RFC, 표준 사양, 언어/프로토콜 표준
official-vendor-doc — Spring, Keycloak, AWS, Google, Apache 등 공식 벤더/프로젝트 문서
official-reference — 공식 reference/API 문서
company-case-study — 대기업/실무 기술 블로그의 특정 사례
engineering-blog — 개인/팀 블로그의 엔지니어링 해설
tutorial — 튜토리얼/가이드. 일반화 금지
needs-confirmation — 원문만으로는 적용 판단 불가

Usage Boundaries

이 자료가 직접 증명하는 것:
- KAFKA-SEC-C1: security.protocol 4개 값과 PLAINTEXT 의 무보안 의미
- KAFKA-SEC-C2/KAFKA-SEC-C3: SSL client 설정 키 이름 전체 목록(단방향/양방향 각각)
- KAFKA-SEC-C4/KAFKA-SEC-C5/KAFKA-SEC-C6: SASL client 설정 키 이름, 지원 mechanism 목록, 자격증명 평문 저장 위험
이 자료가 증명하지 않는 것:
- Spring Boot / Spring Kafka 의 spring.kafka.* 프로퍼티 바인딩 이름 (native Kafka client config 와 이름이 다를 수 있음 — 별도 Spring Kafka 공식 문서 확인 필요)
- ca-skeleton 이 mTLS 를 쓸지, 어떤 SASL mechanism 을 쓸지에 대한 결정 (branch-local 결정 사항)
- secret 값을 실제로 어떤 방식(Vault/K8s Secret/env)으로 주입할지 (Kafka 문서 범위 밖)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- feature-env-driven-runtime-configuration 의 secret 분류 registry 스키마와 이 키 이름들의 실제 매핑
- Spring Kafka 사용 시 spring.kafka.properties.* prefix 를 통한 raw property 전달 방식(Spring Kafka 공식 문서로 별도 검증)

메모

나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기에 두지 말 것.

WebFetch 툴이 이 URL(및 /43/documentation.html 추정 경로)에서 JS 리다이렉트 stub 만 반환해 3회 실패했다. curl 로 raw HTML 을 받아 리다이렉트 목적지를 역추적한 뒤 실제 3개 세부 페이지를 직접 curl 로 재수집했다 — 이 과정과 최종 텍스트는 /tmp/source-fetch-20260728-170505.txt (listener-configuration + encryption-and-authentication-using-ssl + authentication-using-sasl 3페이지 연결본)에 보존.
추가로 봐야 할 동일 출처 페이지: https://kafka.apache.org/43/security/authorization-and-acls/ (ACL — 이 branch 범위 밖일 가능성 높음), Spring Kafka 공식 문서(spring.kafka.* property reference — 별도 raw 자료 필요)

12 KiB Raw Permalink Blame History