KMIP 시크릿 엔진

Enterprise 기능 — 적절한 Vault Enterprise 라이선스 또는 HCP Vault Dedicated 클러스터가 필요해요. KMIP 시크릿 엔진은 Advanced Data Protection(ADP) 모듈이 포함된 Vault Enterprise가 필요해요.

KMIP 시크릿 엔진은 Vault가 KMIP(Key Management Interoperability Protocol) 서버 공급자 역할을 하고 자신의 KMIP 관리 객체(managed object)의 수명주기를 처리하게 해요. KMIP는 서비스와 애플리케이션이 암호화 자료(관리 객체)를 직접 관리하지 않고도 암호화 작업을 수행할 수 있게 하는 표준화된 프로토콜이에요. 그 저장과 수명주기를 키 관리 서버에 위임하는 방식이죠.

Vault의 KMIP 시크릿 엔진은 표준 Vault 리스너와는 별도의 포트에서 수신해요. KMIP 시크릿 엔진이 구성된 Vault 클러스터의 각 Vault 서버는 같은 리스너 구성을 사용해요. KMIP 리스너는 기본적으로 포트 5696을 사용하며, 예를 들어 KMIP 시크릿 엔진 마운트가 여러 개 구성됐다면 다른 포트로 변경할 수 있어요. KMIP 클라이언트는 생성된 TLS 인증서를 사용해 이 KMIP 시크릿 엔진 리스너 포트에 연결하고 인증해요. KMIP 클라이언트는 구성된 KMIP 포트에서 Vault 활성 서버나 Vault 성능 대기(performance standby) 서버 중 아무 곳에나 직접 연결할 수 있어요. Vault 서버의 KMIP 포트 앞에는 레이어 4 TCP 로드 밸런서를 둘 수 있어요. 로드 밸런서는 장기 연결을 지원해야 하며, 필요하면 Vault 서버가 primary Vault 서버로 전달하므로 라운드 로빈 라우팅 알고리즘을 사용할 수 있어요.

출처: 문서

본문

KMIP 적합성(KMIP conformance)

Vault는 다음 Key Management Interoperability Protocol 프로파일의 버전 1.4를 구현해요.

Baseline Server — Key Value Location을 제외한 모든 프로파일 속성을 지원해요. Check를 제외한 모든 프로파일 작업을 지원해요. Locate 작업은 Key Value Location을 제외한 모든 프로파일 속성을 지원해요.
Symmetric Key Lifecycle Server — 암호화 알고리즘 AES를 지원해요(3DES는 지원하지 않아요). Raw 키 형식 유형만 지원해요(Transparent Symmetric Key는 지원하지 않아요).
Basic Cryptographic Server — 블록 암호 모드 CBC, CFB, CTR, ECB, GCM, OFB를 지원해요. 멀티파트(스트리밍) 작업에서는 블록 암호 모드 GCM이 지원되지 않아요. 지원되는 패딩 방법은 None과 PKCS5예요.
Asymmetric Key Lifecycle Server — Public Key와 Private Key 객체를 지원해요. RSA 암호화 알고리즘을 지원하고, PKCS#1, PKCS#8, X.509, Transparent RSA Public Key, Transparent RSA Private Key 키 형식 유형을 지원해요.
Advanced Cryptographic Server — Encrypt, Decrypt, Sign, Signature Verify, MAC, MAC Verify, RNG Retrieve, RNG Seed 클라이언트-서버 작업을 지원해요. Sign과 Signature Verify 작업에서 지원되는 해싱 알고리즘은 PSS 패딩 방식의 SHA224, SHA256, SHA384, SHA512, RIPEMD160, SHA512_224, SHA512_256, SHA3_224, SHA3_256, SHA3_384, SHA3_512이고, PKCS1v15 패딩 방식의 SHA224, SHA256, SHA384, SHA512, RIPEMD160이에요. MAC과 MAC Verify 작업에서 지원되는 해싱 알고리즘은 SHA224, SHA256, SHA384, SHA512, RIPEMD160, SHA512_224, SHA512_256, SHA3_224, SHA3_256, SHA3_384, SHA3_512예요(MD4, MD5, SHA1은 지원하지 않아요).

자세한 내용은 KMIP - Profiles Support 페이지를 참고하세요.

설정(Setup)

KMIP 시크릿 엔진은 KMIP 요청을 받기 시작하기 전에 구성해야 해요.

KMIP 시크릿 엔진을 활성화해요.

$ vault secrets enable kmip
Success! Enabled the kmip secrets engine at: kmip/

시크릿 엔진에 사용할 리스너 주소와 TLS 파라미터를 구성하거나, 기본값을 사용하려면 쓰지 않은 채로 두어요.
```
$ vault write kmip/config listen_addrs=0.0.0.0:5696
```

KMIP 인증 기관(Certificate Authorities)

Vault 2.0부터 KMIP 시크릿 엔진은 여러 인증 기관(CA)을 관리할 수 있어요.

클라이언트 인증서용 레거시 CA — KMIP 시크릿 엔진을 처음 구성하면 Vault가 레거시 KMIP CA를 생성해요. Vault는 기본적으로 이 CA를 사용해 클라이언트 인증서와 서버 TLS 인증서를 발급해요. 이 CA는 자동으로 생성되며 외부 소스에서 가져올 수 없어요.

서버·클라이언트 인증서용 명명된 CA(Named CAs) — 레거시 CA 외에도 다음 용도로 사용할 수 있는 명명된 CA를 만들고 관리할 수 있어요.

서버 인증서: KMIP 리스너 엔드포인트용 TLS 인증서 생성
클라이언트 인증서: mTLS 인증을 위한 클라이언트 인증서 검증

명명된 CA는 두 종류가 될 수 있어요.

생성된 CA(Generated CAs) — Vault가 지정된 키 유형과 비트로 생성
가져온 CA(Imported CAs) — 외부 소스에서 가져옴. 클라이언트 인증서 검증에만 사용할 수 있고, 클라이언트나 서버 인증서 생성에는 사용할 수 없어요.

생성된 CA를 만들려면:

$ vault write kmip/ca/my-ca/generate \
    key_type=rsa \
    key_bits=2048 \
    ttl=8760h

클라이언트 검증용 외부 CA를 가져오려면:

$ vault write kmip/ca/my-imported-ca/import \
    [email protected] \
    scope_name=my-service \
    role_name=admin

또는 인증서 필드로 scope와 role을 추출할 수도 있어요.

$ vault write kmip/ca/my-imported-ca/import \
    [email protected] \
    scope_field=OU \
    role_field=CN

구성된 CA를 모두 나열할 수 있어요.

$ vault list kmip/ca

그리고 CA 세부 정보를 읽을 수 있어요.

$ vault read kmip/ca/my-ca

명명된 리스너(Named Listeners)

KMIP 시크릿 엔진은 이제 명명된 리스너를 지원해요. 서로 다른 설정으로 여러 KMIP 서버 엔드포인트를 구성할 수 있게 해주죠. 각 리스너는 서버 인증서 생성에 사용되는 특정 CA와 연결되며, 클라이언트 인증서 검증을 위해 추가 CA를 신뢰할 수 있어요.

명명된 리스너를 만들려면:

$ vault write kmip/listener/my-listener \
    ca=my-ca \
    address=0.0.0.0:5697 \
    server_hostnames=kmip.example.com \
    server_ips=192.168.1.100 \
    additional_client_cas=my-imported-ca \
    tls_min_version=tls12

파라미터:

ca(필수) — 서버 인증서 생성에 사용할 CA 이름
address(필수) — 리스너의 Host:port 주소
server_hostnames — 서버 인증서에 포함할 DNS SAN
server_ips — 서버 인증서에 포함할 IP SAN
additional_client_cas — 클라이언트 인증서 검증을 위해 추가로 신뢰할 CA
also_use_legacy_ca — 클라이언트 인증서에 레거시 CA도 신뢰할지 여부
tls_min_version — 최소 TLS 버전(tls12 또는 tls13)
tls_max_version — 최대 TLS 버전(tls12 또는 tls13)
tls_cipher_suites — 허용된 TLS 암호 스위트(TLS 1.2에만 해당)

구성된 리스너를 나열해요.

$ vault list kmip/listener

리스너 구성을 읽어요.

$ vault read kmip/listener/my-listener

리스너를 삭제해요.

$ vault delete kmip/listener/my-listener

참고: 명명된 리스너는 /kmip/config의 레거시 listen_addrs 구성보다 더 큰 유연성을 제공해요. 레거시 구성과 함께 또는 대신 명명된 리스너를 사용할 수 있어요.

사용법(Usage)

스코프와 역할(Scopes and roles)

KMIP 시크릿 엔진은 스코프(scope) 개념을 사용해 KMIP 관리 객체 저장소를 여러 명명된 버킷으로 분할해요. 스코프 안에서 역할을 만들 수 있으며, 역할은 특정 역할이 수행할 수 있는 허용 작업 집합을 규정해요. 역할에 대해 TLS 클라이언트 인증서를 생성할 수 있고, 서비스와 애플리케이션은 Vault의 KMIP 시크릿 엔진에 KMIP 요청을 보낼 때 그 인증서를 사용해요.

KMIP 클라이언트가 Vault의 KMIP 서버와 상호작용할 수 있게 클라이언트 인증서를 생성하려면 먼저 스코프와 역할을 만들고 원하는 허용 작업 집합을 지정해야 해요.

스코프를 만들어요.

$ vault write -f kmip/scope/my-service
Success! Data written to: kmip/scope/my-service

스코프 안에서 역할을 만들고, 허용하거나 거부할 작업 집합을 지정해요. 선택적으로 클라이언트 인증서 서명에 사용할 명명된 CA를 지정할 수 있어요.
```
$ vault write kmip/scope/my-service/role/admin operation_all=true
Success! Data written to: kmip/scope/my-service/role/admin
```
클라이언트 인증서에 특정 명명된 CA를 사용하려면:
```
$ vault write kmip/scope/my-service/role/admin \
    operation_all=true \
    ca=my-ca
```

지원되는 KMIP 작업(Supported KMIP operations)

KMIP 시크릿 엔진은 현재 다음 작업 집합을 지원해요.

operation_activate
operation_add_attribute
operation_create
operation_create_keypair
operation_decrypt
operation_delete_attribute
operation_destroy
operation_discover_versions
operation_encrypt
operation_get
operation_get_attribute_list
operation_get_attributes
operation_import
operation_locate
operation_mac
operation_mac_verify
operation_modify_attribute
operation_query
operation_register
operation_rekey
operation_rekey_keypair
operation_revoke
operation_sign
operation_signature_verify
operation_rng_seed
operation_rng_retrieve

추가로, 역할에 모든 작업 기능을 허용하거나 거부하는 데 사용할 수 있는 두 개의 유사 작업(pseudo-operation)이 있어요. 이 작업들은 다른 모든 작업과 상호 배타적이에요. 즉 역할 생성이나 업데이트 중에 이 작업이 제공되면 다른 작업은 제공할 수 없어요. 마찬가지로 기존 역할에 유사 작업이 포함되어 있고 나중에 지원 작업 집합으로 업데이트하면, 새로 제공된 작업 집합으로 덮어써져요.

유사 작업:

operation_all
operation_none

클라이언트 인증서 생성(Client certificate generation)

스코프와 역할이 생성되면 그 역할에 대한 클라이언트 인증서를 생성할 수 있어요. 그런 다음 클라이언트 인증서를 KMIP을 지원하는 애플리케이션과 서비스에 제공해 Vault의 KMIP 서버와 통신을 설정할 수 있어요. 스코프·역할 식별자는 인증서에 내장되며, KMIP 요청 중 권한 평가에 사용돼요.

클라이언트 인증서를 생성해요. CA 체인, 인증서, 개인 키가 반환돼요.

$ vault write -f kmip/scope/my-service/role/admin/credential/generate
Key              Value
---              -----
ca_chain         [-----BEGIN CERTIFICATE----- MIICNTCCAZigAwIBAgIUKqNFb3Zy..... -----END CERTIFICATE----- ...]
certificate      -----BEGIN CERTIFICATE----- MIICOzCCAZygAwIBAgIUN5V7bLAGu8QIUFxlIugg8fBb+eYw... [truncated]

(실제 출력에는 CA 체인, 인증서, 개인 키가 담긴 완전한 PEM 블록이 반환돼요.)

클라이언트 인증서 서명(Client certificate signing)

위의 클라이언트 인증서 생성 섹션의 대안으로, KMIP 시크릿 엔진은 인증서 서명 요청(CSR) 서명을 지원해요. 보통 위 생성 과정이 더 단순하지만, 일부 KMIP 클라이언트는 자신의 클라이언트 인증서와 연결된 개인 키를 보유하는 것을 선호하거나(또는 그것만 지원해요).

이 워크플로의 첫 단계는 KMIP 클라이언트에 따라 달라요. KMIP 클라이언트의 UI나 CLI로 PEM 형식의 클라이언트 인증서 CSR을 만들어요.

클라이언트 인증서에 서명해요. CA 체인과 인증서는 반환되지만 개인 키는 반환되지 않으며, 개인 키는 KMIP 클라이언트를 떠나지 않아요.

$ vault write kmip/scope/my-service/role/admin/credential/sign csr="$(cat my-csr.pem)"
Key              Value
---              -----
ca_chain         [-----BEGIN CERTIFICATE----- MIICNTCCAZigAwIBAgIUKqNFb3Zy..... -----END CERTIFICATE----- ...]
certificate      -----BEGIN CERTIFICATE----- MIICOzCCAZygAwIBAgIUN5V7bLA... [truncated]

튜토리얼(Tutorial)

단계별 튜토리얼은 KMIP Secrets Engine 가이드를 참고하세요.

더 알아보기 (Learn more)

KMIP - Profiles Support 페이지에서 지원 프로파일을 확인해 보세요.
KMIP Secrets Engine 가이드의 단계별 튜토리얼을 따라 해 보세요.
KMIP 시크릿 엔진 API 문서를 확인해 보세요.