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:...
- 기존 암호문을 최신 키로 재암호화
- 평문을 꺼내지 않고 갱신 가능
출처