카테고리 없음

[Vault] Secret Engines

noahkim_ 2025. 8. 30. 23:24

1. Overview

  • 데이터를 저장, 생성, 암복호화하는 컴포넌트

 

Path & Routing

  • Vault 내 특정 경로에 마운트됨
  • 클라이언트 요청이 들어오면, Vault 라우터가 경로 접두어를 보고 해당 엔진으로 라우팅함

 

Lifecycle

동작 요약 주요 영향
enable 엔진을 특정 경로에 활성화 엔진 인스턴스 생성
✅ 경로 대소문자 구분
➡️ 해당 경로로 요청 라우팅 시작
disable 해당 엔진 비활성화 엔진 사용 불가
✅ 저장 데이터 제거
move 엔진의 마운트 경로 변경 기존 경로에서 발급된 모든 리스 무효화
 설정 데이터는 유지
tune 엔진의 전역 설정 예: TTL 등
  • ⚠️ 엔진의 경로가 충돌되어서는 안됨 (서로 접두어 관계가 되면 안됨)

 

예시) 명령어

더보기
vault secrets enable -path=<경로> <엔진타입>
vault secrets disable <경로>
vault secrets move <기존경로> <새경로>
vault secrets tune -default-lease-ttl=<TTL> -max-lease-ttl=<TTL> <경로>

 

Barrier view

  • 각 secret engine은 물리 저장소에 대해 Barrier view를 부여받음
  • ✅ 엔진을 활성화할 때, 무작위 UUID가 부여됨 
  •  해당 엔진의 모든 데이터에 UUID가 프리픽스로 붙음
  • ➡️ UUID가 엔진의 데이터 루트가 됨
  • ➡️ 서로 다른 엔진의 데이터에 접근 불가 (상대 경로 접근 ❌)

 

2. Key/Value

  • 임의의 비밀값을 저장하는 범용 저장소

 

KV v2

  • 버저닝: 키마다 여러 버전 저장 가능 (기본 10버전. 설정 가능)
  • ✅ 과거 버전의 데이터/메타데이터 조회 가능
  • CAS(Check-and-Set) 지원
  • 삭제 정책 지원 (soft delete, undelete, destroy)

 

예시) 명령어

더보기
vault secrets enable -path=secret kv-v2				# KV v2 엔진을 secret/ 경로에 마운트 및 활성화

vault kv put secret/app user="alice" pass="p@ss"	

vault kv get secret/app		
vault kv get -field=user secret/app					# 특정 필드만 뽑기
vault kv get -version=3 -field=user secret/app		# 특정 버전에서만 뽑기

vault kv delete secret/app			                # 소프트 삭제(복구 가능)
vault kv undelete -versions=1 secret/app  			# 버전 1 복구
vault kv destroy -versions=1 secret/app   			# 버전 1 영구 삭제
vault kv metadata delete secret/app       			# 키 전체 이력/메타데이터 삭제
  • Secret Path: secret/data/app  (v2이므로 /data 포함)

 

표) 명령 - API Endpoint

더보기
명령 KV v2 API
vault kv get secret/data/<key_path>
vault kv put secret/data/<key_path>
vault kv list secret/metadata/<key_path>
vault kv delete secret/data/<key_path>
vault kv patch secret/data/<key_path>
vault kv rollback secret/data/<key_path>
vault kv undelete secret/undelete/<key_path>
vault kv destroy secret/destroy/<key_path>
vault kv metadata secret/metadata/<key_path>
  • "secret/" 경로에 마운트된 경우 기준

 

3. PKI (Certificates)

  • 동적으로 X.509 인증서를 발급해주는 기능
  • 자동 발급: 인증서 발급을 자동화해서 곧바로 발급받도록 해줌 (개인키 생성 + CSR 생성 + CA에 제출 + 검증 및 서명 기다리기)
  •  외부 X.509 인증서 사용 가능
  •  Consul CA Provider 연동
  •  짧은 TTL (폐기할 필요 없음. CRL 짧아짐 ➡️ 확장성)

 

Setup 

  • 기본적으로 pki 경로에 마운트됨 (-path 옵션으로 지정 가능)

 

CLI) PKI 엔진 활성화

더보기
$ vault secrets enable pki

 

CLI) TTL 조정

더보기
$ vault secrets tune -max-lease-ttl=8760h pki
  • PKI 엔진 전체의 최대 TTL 지정

 

CLI) root CA CSR 생성

더보기
vault write pki/root/generate/internal \
common_name="CoinHeaven Internal Root CA" \
ttl=8760h

 

CLI) intermediate CA CSR 생성

더보기
vault write -field=csr pki_int/intermediate/generate/internal \
common_name="CoinHeaven Internal Intermediate CA" \
ttl=8760h > pki_int.csr

 

CLI) Root로 Intermediate 서명

더보기
vault write -field=certificate pki/root/sign-intermediate \
csr=@pki_int.csr format=pem_bundle ttl=8760h > intermediate.pem

 

CLI) Intermediate 서명 결과 설정

더보기
vault write pki_int/intermediate/set-signed certificate=@intermediate.pem

 

CLI) Intermediate AIA 설정

더보기
vault write pki_int/config/urls \
issuing_certificates="https://vault.internal.coinheaven/v1/pki_int/ca" \
crl_distribution_points="https://vault.internal.coinheaven/v1/pki_int/crl"

 

CLI) Intermediate 발급 Role 만들기 (내부 서비스용)

더보기
vault write pki_int/roles/microservices \
allowed_domains=internal.coinheaven.com \
allow_subdomains=true \
server_flag=true \
clieng_flag=true \
key_type=ec \
key_bits=256 \
max_ttl=72h

 

4. Transit

  • 애플리케이션을 위한 암호 연산 서비스 (Cryptography as a Service)
  • 키 관리 기능
  • ✅ 요청 시점 처리
  • ➡️ 안전성 (애플리케이션의 평문 핸들링이 최소화됨, 안정적인 키 관리)

 

기능

주요 기능
기능 설명 특징
데이터 암호화/복호화 애플리케이션에서 Vault로 요청 ✅ 암호화된 데이터만 DB에 저장.
 복호화가 필요할 때 다시 Vault 호출
서명 & 검증 데이터에 디지털 서명 ✅ 위·변조 방지.
✅ 서명 값 검증으로 데이터 신뢰성 확보.
해시 (Hash) & HMAC 데이터의 고유 해시값 또는 비밀키 기반의 HMAC 생성 ✅ 무결성 검증 가능
메시지 인증
랜덤 바이트 생성 암호학적으로 안전한 난수 생성  세션 키, 토큰, 초기화 벡터(IV) 생성

 

키 관리
기능 설명 보안/성능 효과
버전 관리 min_decryption_version보다 낮은 키 버전은 아카이브 처리되어 기본적으로 복호화 불가  보안성: 오래된 키로 과거 암호문이 무단 복호화되는 것 방지
 성능: 불필요한 구버전 키를 로딩하지 않아 처리 속도 향상
키 회전 주기적으로 새 키를 생성해 기존 키를 교체  보안성: 키 유출 가능성 최소화, 암호 강도 유지

 

고급 기능
기능 설명 활용 예시
Key Derivation (키 파생) 같은 기본 키라도 Context(문맥) 값을 조합하여 여러 용도로 분리된 파생 키 생성
 key1 + "user-data" → 사용자 데이터용 키
 key1 + "log-data" → 로그 데이터용 키
Convergent Encryption 같은 입력값은 항상 같은 암호문을 생성  중복된 파일 탐지
 동일 값 패턴 분석
Datakey Generation Vault가 고품질 난수 키(예: 256bit)를 생성해 평문/암호문으로 반환
 평문 키를 앱에서 즉시 사용
암호문만 받아서 보안 감사 용도에 활용

 

키 타입

키 타입 설명 지원 기능
aes128-gcm96 128비트 AES 키 + 96비트 nonce를 사용하는 AES-GCM
암호화, 복호화, 키 파생 수렴 암호화
aes256-gcm96 256비트 AES 키 + 96비트 nonce를 사용하는 AES-GCM 암호화, 복호화, 키 파생, 수렴 암호화
chacha20-poly1305 256비트 키를 사용하는 ChaCha20-Poly1305 암호화, 복호화, 키 파생, 수렴 암호화
ed25519 Ed25519 알고리즘 서명, 검증, 키 파생
ecdsa-p256 ECDSA P-256 곡선 사용 서명, 검증
ecdsa-p384 ECDSA P-384 곡선 사용 서명, 검증
ecdsa-p521 ECDSA P-521 곡선 사용 서명, 검증
rsa-2048 2048비트 RSA 키 암호화, 복호화, 서명, 검증
rsa-3072 3072비트 RSA 키 암호화, 복호화, 서명, 검증
rsa-4096 4096비트 RSA 키 암호화, 복호화, 서명, 검증
hmac HMAC 전용 키 HMAC 생성 및 검증
managed_key (Enterprise) 외부 KMS(키 관리 솔루션)과 연동되는 관리형 키 백엔드에 따라 다양한 작업 지원
aes128-cmac (Enterprise) 128비트 AES 키를 사용하는 CMAC CMAC 생성 및 검증
aes192-cmac (Enterprise) 192비트 AES 키를 사용하는 CMAC CMAC 생성 및 검증
aes256-cmac (Enterprise) 256비트 AES 키를 사용하는 CMAC CMAC 생성 및 검증
ml-dsa (Enterprise, 실험적) ML-DSA 서명 알고리즘 서명, 검증
hybrid (Enterprise, 실험적) 두 가지 서명 알고리즘을 조합 서명, 검증

 

Convergent Encryption

  • 동일한 평문 + 컨텍스트 조합이 항상 동일한 암호문으로 변환되는 암호화 방식
  • Key Derivation Function + deterministic Nonce
  • v1: 직접 Nonce 생성
  • v2: 알고리즘을 통해 Nonce 생성
  • v3: PRF를 통해 Nonce 생성 (AES-SIV와 유사)

 

Setup

CLI) 활성화

더보기
$ vault secrets enable transit

 

CLI) 암호화 키 생성

더보기
$ vault write -f transit/keys/my-key

 

Usage

CLI) 데이터 암호화

더보기
$ vault write transit/encrypt/my-key plaintext=$(echo "hello" | base64)
vault:v1:
Pi62vIvOHZCJDz0IEUIpy1UqJRCr8/tFCma4kW5p+LtLD0DNk3CUIRvJOy0z9fSvIWBhTzHxACS5BjwbTXuhWcyt1L+fK6W
Lw/n88hON5jSXnpKlagxG9qwhYPSsww+u5umGDoHvpCFcAEdLAhWM46PzDno126SioPhsU7UV0cdWhjy3RwbHEDmKjI450w
YnU7Wg/chlmS3Wqj+Q717rqBZJc1vVwRd8ZXstv4Kl99uGs7FpDrIpWo0BVcIY0LIeBDF2vknveB2OIBnQgc7nLWl02OCzU
RCYzYYVfNRxyQqnGmFWsieLbFl6d7tmSpptpjCqfUp4S7gbIqb+GUph/A==
  • 모든 평문은 base64로 인코딩해야 함

 

CLI) 데이터 복호화

더보기
$ vault write -field=plaintext transit/decrypt/my-key ciphertext=... | base64 --decode
my secret data

 

CLI) 키 회전

더보기
$ vault write -f transit/keys/my-key/rotate
  • 새 키로 암호화됨
  • 이전 키로 암호화된 데이터도 복호화 가능

 

CLI) 재포장

더보기
$ vault write transit/rewrap/my-key ciphertext=vault:v1:...
  • 기존 암호문을 최신 키로 재암호화
  • 평문을 꺼내지 않고 갱신 가능

 

 

출처