Skip to content

Commit 74e5d13

Browse files
Great-StoneGreat-Stone
committed
feat: 설명 오류 수정
1 parent 2fa0458 commit 74e5d13

1 file changed

Lines changed: 180 additions & 46 deletions

File tree

‎docs/04-HashiCorp/06-Vault/01-Information/vault-seal-unseal.md‎

Lines changed: 180 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,17 @@ tag: ["vault", "token"]
77

88
## 1. 개요
99

10-
HashiCorp Vault는 시작 시 **sealed(봉인된)** 상태로 시작합니다. 이 상태에서는 물리적 스토리지에 접근할 수 있지만, 저장된 데이터를 복호화할 수 없습니다. **Unsealing(봉인 해제)**은 Vault가 데이터를 복호화하기 위해 필요한 root key에 접근하는 과정입니다.
10+
HashiCorp Vault는 시작 시 `Sealed(봉인된)` 상태로 시작합니다. 이 상태에서는 물리적 스토리지에 접근할 수 있지만, 저장된 데이터를 복호화할 수 없습니다. `Unsealing(봉인해제)`은 Vault가 데이터를 복호화하기 위해 필요한 root key에 접근하는 과정입니다.
1111

1212
## 2. 암호화 계층 구조
1313

14-
Vault는 **3단계 암호화 계층 구조**를 사용하여 데이터를 보호합니다:
14+
Vault는 ==3단계 암호화 계층 구조==를 사용하여 데이터를 보호합니다:
1515

1616
```mermaid
17-
flowchart TD
18-
A[Vault 데이터] -->|암호화| B[Encryption Key<br/>Keyring에 저장]
19-
B -->|암호화| C[Root Key]
20-
C -->|암호화| D[Unseal Key]
17+
flowchart LR
18+
D[Unseal Key] -->|보호| C[Root Key]
19+
C -->|보호| B[Encryption Key<br/>Keyring에 저장]
20+
B -->|보호| A[Vault 데이터]
2121
2222
style A fill:#e1f5ff
2323
style B fill:#fff4e1
@@ -76,21 +76,8 @@ Vault의 암호화 계층 구조는 다음과 같이 구현되어 있습니다:
7676

7777
3. **Encryption Key로 데이터 복호화**: 복호화된 Encryption Key를 사용하여 실제 Vault 데이터를 암호화/복호화합니다.
7878

79-
**저장 경로 (코드 상수):**
80-
```go:vault/seal.go
81-
const (
82-
barrierSealConfigPath = "core/seal-config"
83-
recoverySealConfigPath = "core/recovery-seal-config"
84-
recoverySealConfigPlaintextPath = "core/recovery-config"
85-
recoveryKeyPath = "core/recovery-key"
86-
StoredBarrierKeysPath = "core/hsm/barrier-unseal-keys"
87-
hsmStoredIVPath = "core/hsm/iv"
88-
SealGenInfoPath = "core/seal-gen-info"
89-
SealInitializationFlagPath = "core/seal-initialization-flag"
90-
)
91-
```
79+
#### 코드 내 주요 저장 경로
9280

93-
**주요 저장 경로 설명:**
9481
- **Root Key (Barrier Keys)**: `StoredBarrierKeysPath = "core/hsm/barrier-unseal-keys"` - HSM 사용 시 암호화된 Root Key 저장
9582
- **Recovery Key**: `recoveryKeyPath = "core/recovery-key"` - Recovery Key 저장 (암호화됨)
9683
- **Seal Config**: `barrierSealConfigPath = "core/seal-config"` - **평문 저장** (Vault가 sealed 상태에서도 읽을 수 있어야 하므로)
@@ -100,11 +87,146 @@ const (
10087

10188
### 3.1 Vault 시작 시 (Sealed 상태)
10289

103-
Vault 서버가 시작되면:
104-
- 물리적 스토리지에 접근 가능
105-
- 하지만 **Root Key가 메모리에 없음**
106-
- 따라서 Encryption Key를 복호화할 수 없어 데이터 접근 불가
107-
- 이 상태를 **Sealed(봉인된)** 상태라고 함
90+
#### 3.1.1 Vault 프로세스 시작만 한 상태
91+
92+
Vault 서버 프로세스를 시작만 한 상태에서는:
93+
94+
- **초기화되지 않은 상태**: Storage backend가 아직 준비되지 않음
95+
- **초기화 전**: `vault operator init` 명령을 실행하기 전 상태
96+
- **가능한 작업**: 초기화 상태 확인 (`vault operator init -status`)만 가능
97+
- **불가능한 작업**: 모든 Vault 작업 불가 (초기화 필요)
98+
99+
::: tip 초기화 상태 확인
100+
```bash
101+
# 초기화 상태 확인
102+
vault operator init -status
103+
104+
# Exit code 0: 이미 초기화됨
105+
# Exit code 1: 오류 발생
106+
# Exit code 2: 초기화되지 않음
107+
```
108+
:::
109+
110+
#### 3.1.2 Vault 초기화
111+
112+
`vault operator init` 명령을 실행하면 Vault의 storage backend가 초기화되고 다음이 발생합니다:
113+
114+
1. **Root Key 생성**
115+
- Vault가 Root Key를 생성
116+
- Root Key는 Encryption Key를 보호하는 데 사용됨
117+
- Root Key는 암호화되어 storage backend에 저장됨
118+
119+
2. **Root Key 보호**
120+
121+
- **Unseal Key 생성 및 분할**
122+
- 기본적으로 Shamir's Secret Sharing 알고리즘 사용
123+
- Unseal Key가 여러 share로 분할됨 (기본값: 5개 share)
124+
- Threshold 설정 (기본값: 3개 share 필요)
125+
- 각 share는 운영자에게 분산 보관
126+
127+
- **외부 KMS 연동**
128+
- KMS(Key Management Service)를 사용하여 Root Key를 보호할 수 있음
129+
- HSM, AWS KMS, Azure Key Vault, GCP Cloud KMS, Vault Transit 등 다양한 KMS 서비스 지원
130+
131+
3. **Storage Backend 준비**
132+
- Storage backend가 데이터를 받을 수 있도록 준비됨
133+
- Root Key가 암호화되어 저장됨
134+
- Seal 설정 정보가 평문으로 저장됨 (sealed 상태에서도 읽을 수 있어야 함)
135+
136+
4. **Root Token 생성**
137+
- 초기 관리자 토큰 생성
138+
- PGP 키로 암호화 가능 (선택사항)
139+
140+
**초기화 후 상태:**
141+
- Storage backend는 초기화되었지만, Vault는 여전히 **Sealed 상태**
142+
- Root Key가 storage에 암호화되어 저장되어 있음
143+
- Unseal Key share / HSM / KMS 를 사용하여 Unseal Key를 재구성하여 Root Key를 복호화하여 Encryption Key를 얻어야 데이터 접근 가능
144+
145+
::: tip HA 모드에서의 초기화
146+
HA(High Availability) 모드에서는 여러 Vault 서버가 같은 storage backend를 공유합니다. 이 경우 **하나의 Vault 서버만 초기화**하면 됩니다. 다른 노드들은 같은 storage backend를 사용하므로 자동으로 초기화된 상태를 인식합니다.
147+
:::
148+
149+
#### 3.1.3 초기화 예제
150+
151+
**Shamir Seal 사용 시 (기본):**
152+
```bash
153+
# 기본 초기화 (5개 share, 3개 threshold)
154+
vault operator init
155+
156+
# 커스텀 설정으로 초기화
157+
vault operator init \
158+
-key-shares=3 \
159+
-key-threshold=2
160+
161+
# PGP 키로 Unseal Key 암호화
162+
vault operator init \
163+
-key-shares=3 \
164+
-key-threshold=2 \
165+
-pgp-keys="keybase:hashicorp,keybase:jefferai,keybase:sethvargo"
166+
```
167+
168+
**HSM/KMS 사용 시 (Auto Unseal):**
169+
```bash
170+
# HSM 사용 시 Recovery Key 생성
171+
vault operator init \
172+
-recovery-shares=5 \
173+
-recovery-threshold=3
174+
175+
# HSM 사용 시 (간단한 예제)
176+
vault operator init \
177+
-recovery-shares=1 \
178+
-recovery-threshold=1
179+
180+
# Recovery Key를 PGP 키로 암호화
181+
vault operator init \
182+
-recovery-shares=3 \
183+
-recovery-threshold=2 \
184+
-recovery-pgp-keys="keybase:hashicorp,keybase:jefferai,keybase:sethvargo"
185+
```
186+
187+
::: tip HSM/KMS 사용 시 주의사항
188+
HSM 또는 KMS를 사용하는 경우 (Auto Unseal):
189+
- **Unseal Key가 생성되지 않음** - HSM/KMS가 자동으로 unseal 처리
190+
- **Recovery Key가 생성됨** - `-recovery-shares`와 `-recovery-threshold` 옵션 사용
191+
- Recovery Key는 복구 작업(Root Token 생성, Rekeying 등)에만 사용됨
192+
- Vault는 시작 시 HSM/KMS를 통해 자동으로 unseal됨
193+
:::
194+
195+
::: tip 초기화 후 출력 예시
196+
197+
**Shamir Seal 사용 시:**
198+
```
199+
Unseal Key 1: abc123...
200+
Unseal Key 2: def456...
201+
Unseal Key 3: ghi789...
202+
Unseal Key 4: jkl012...
203+
Unseal Key 5: mno345...
204+
205+
Initial Root Token: s.xyz789...
206+
207+
Vault is initialized with 5 key shares and a key threshold of 3.
208+
```
209+
210+
**HSM/KMS 사용 시:**
211+
```
212+
Recovery Key 1: xyz789...
213+
214+
Initial Root Token: s.abc123...
215+
216+
Vault is initialized with 1 recovery key shares and a recovery key threshold of 1.
217+
Please securely distribute the key shares printed above.
218+
```
219+
220+
:::
221+
222+
::: warning 중요
223+
- **Unseal Key와 Root Token을 안전하게 보관**해야 합니다
224+
- Unseal Key share를 잃어버리면 threshold 미달로 Vault를 unseal할 수 없습니다
225+
- Root Token을 잃어버리면 초기 관리자 권한을 잃게 됩니다
226+
- 초기화는 **한 번만** 수행할 수 있습니다 (이미 초기화된 Vault에서는 실행 불가)
227+
:::
228+
229+
108230

109231
### 3.2 Unsealing 과정
110232

@@ -129,6 +251,10 @@ Unsealing은 다음 단계로 진행됩니다:
129251

130252
Shamir Seal을 사용할 때, Unseal Key는 여러 share로 분할되어 여러 운영자에게 분산 보관됩니다. Threshold 이상의 share가 모여야 Unseal Key를 재구성할 수 있습니다.
131253

254+
::: warning HA에서의 Unseal
255+
HA(High Availability) 모드에서 Vault는 다수개의 서버 프로세스로 구성됩니다. `init`은 한번만 수행되나, `unseal`은 각 서버 프로세스에서 수행되어야 합니다.
256+
:::
257+
132258
```mermaid
133259
flowchart TD
134260
subgraph Operators["운영자들 (Key Share 보유)"]
@@ -179,7 +305,7 @@ flowchart TD
179305
- **순서 무관**: Share는 어떤 순서로 제공해도 상관없음
180306
- **상태 유지**: Unseal 과정은 상태를 유지하므로 여러 클라이언트에서 순차적으로 share 제공 가능
181307

182-
#### 코드 구현 예제
308+
::: details 코드 구성 설명
183309

184310
Vault 소스코드에서 Root Key(Barrier Key)의 암호화/복호화는 다음과 같이 구현되어 있습니다:
185311

@@ -275,6 +401,8 @@ func UnsealWrapValue(ctx context.Context, access seal.Access, entryKey string, w
275401
3. `decodeBarrierKeys`: `access.Decrypt()`를 호출하여 Unseal Key로 Root Key를 복호화합니다. 이 과정에서 Unseal Key가 필요하며, Shamir Seal의 경우 충분한 share가 모여야 합니다.
276402
4. `UnsealWrapValue`: 일반적인 seal wrapping된 값을 복호화하는 함수로, Encryption Key 복호화 등에도 사용됩니다.
277403

404+
:::
405+
278406
### 3.3 Sealing 과정
279407

280408
Vault는 다음 상황에서 Sealed 상태가 됩니다:
@@ -324,16 +452,27 @@ Seal은 Root Key를 **메모리에서만** 삭제합니다.
324452

325453
### 4.1 Recovery Key란?
326454

327-
**Recovery Key**는 Auto Unseal(자동 봉인 해제) 또는 HSM을 사용할 때 생성되는 별도의 키 세트입니다.
455+
**Recovery Key**는 Auto Unseal(자동 봉인 해제) 또는 HSM을 사용할 때 **초기화 과정에서 명시적으로 생성**되는 별도의 키 세트입니다.
456+
457+
::: warning Recovery Key는 자동 생성되지 않음
458+
Recovery Key는 HSM/KMS를 사용할 때 자동으로 생성되는 것이 아닙니다. `vault operator init` 명령을 실행할 때 `-recovery-shares`와 `-recovery-threshold` 옵션을 사용하여 **명시적으로 생성**해야 합니다.
459+
460+
HSM/KMS를 사용하는 경우:
461+
- Unseal은 HSM/KMS가 자동으로 처리하므로 Unseal Key가 필요 없음
462+
- 대신 Recovery Key를 생성하여 복구 작업에 사용
463+
- 초기화 시 `-recovery-shares`와 `-recovery-threshold` 옵션을 지정해야 함
464+
:::
328465

329466
### 4.2 Recovery Key vs Unseal Key
330467

331468
| 구분 | Unseal Key (Shamir Seal) | Recovery Key (Auto Unseal/HSM) |
332469
|------|-------------------------|-------------------------------|
333470
| 용도 | Vault 봉인 해제 | 복구 작업 인증 |
334-
| 생성 시점 | 초기화 시 | Auto Unseal/HSM 초기화 시 |
471+
| 생성 시점 | `vault operator init` (기본) | `vault operator init -recovery-shares=N -recovery-threshold=M` |
472+
| 초기화 옵션 | `-key-shares`, `-key-threshold` | `-recovery-shares`, `-recovery-threshold` |
335473
| 사용 시나리오 | 수동 unsealing | Root token 생성, rekeying 등 |
336474
| 분할 방식 | Shamir's Secret Sharing | Shamir's Secret Sharing |
475+
| Unseal 역할 | 직접 사용하여 Vault unseal | 사용하지 않음 (HSM/KMS가 자동 처리) |
337476

338477
### 4.3 Recovery Key의 역할
339478

@@ -344,7 +483,7 @@ Recovery Key는 다음 작업을 인증하는 데 사용됩니다:
344483
3. **Recovery Key Rekeying**
345484
4. 기타 고위험 복구 작업
346485

347-
#### 코드 구현 예제
486+
::: details 코드 구성 설명
348487

349488
Recovery Key도 Root Key와 유사하게 Seal Wrapping을 통해 저장됩니다:
350489

@@ -380,10 +519,17 @@ func UnsealWrapRecoveryKey(ctx context.Context, access seal.Access, pe *physical
380519
}
381520
```
382521

522+
:::
523+
383524
**중요한 차이점:**
384525
- Recovery Key는 `recoveryKeyPath` (`"core/recovery-key"`)에 저장됩니다.
385526
- Recovery Key는 Root Key를 복호화할 수 없으며, 복구 작업 인증에만 사용됩니다.
386-
- Auto Unseal 환경에서 Recovery Key는 HSM/KMS를 통해 자동으로 관리되지만, 복구 작업 시에는 수동으로 제공해야 합니다.
527+
- HSM/KMS 사용 시 Vault는 자동으로 unseal되므로 Recovery Key는 unseal에 사용되지 않습니다.
528+
- 복구 작업(Root Token 생성, Rekeying 등) 시에는 Recovery Key share를 수동으로 제공해야 합니다.
529+
530+
::: tip HSM 초기화 참고
531+
Thales ProtectServer 3 HSM과 같은 HSM을 사용할 때는 `vault operator init -recovery-shares=1 -recovery-threshold=1`과 같이 Recovery Key를 생성합니다. 자세한 내용은 [Thales HSM 통합 문서](https://thalesdocs.com/gphsm/ptk/protectserver3/docs/integration_docs/hashicorp_vault/configuring_hashicorp/index.html)를 참고하세요.
532+
:::
387533

388534
### 4.4 중요한 제약사항
389535

@@ -419,10 +565,8 @@ HSM(Hardware Security Module)을 사용할 때:
419565
### 5.2 HSM에서 Recovery Key를 권장하는 이유
420566

421567
#### 1. **운영 분리 (Operational Separation)**
422-
```text
423-
일반적인 작업 (Unseal): HSM이 자동 처리
424-
복구 작업 (Recovery): Recovery Key로 수동 인증 필요
425-
```
568+
- 일반적인 작업 (Unseal): HSM이 자동 처리
569+
- 복구 작업 (Recovery): Recovery Key로 수동 인증 필요
426570

427571
#### 2. **보안 강화**
428572
- Unseal은 자동화되지만, 복구 작업은 여러 운영자의 승인 필요
@@ -436,9 +580,7 @@ HSM(Hardware Security Module)을 사용할 때:
436580
- HSM 장애 시 Recovery Key를 사용한 복구 절차 준비
437581
- Recovery Key를 안전하게 백업하여 재해 복구 계획 수립
438582

439-
### 5.3 HSM 사용 시 주의사항
440-
441-
::: warning HSM 사용 시 필수 사항
583+
::: warning HSM 사용 시 주의 사항
442584
1. **Seal 메커니즘 의존성**
443585
- Vault가 HSM에 완전히 의존
444586
- HSM 키가 삭제되면 복구 불가능
@@ -495,17 +637,9 @@ HSM(Hardware Security Module)을 사용할 때:
495637
3. **Unsealing**: Unseal Key로 Root Key를 복호화하여 데이터 접근 가능
496638
4. **Recovery Key**: Auto Unseal/HSM 환경에서 복구 작업 인증용
497639

498-
### 보안 모범 사례
499-
500-
::: tip 보안 모범 사례
501-
- Unseal Key share를 여러 운영자에게 분산 보관
502-
- Recovery Key를 안전하게 백업 (HSM 사용 시 필수)
503-
- Seal 메커니즘(특히 Cloud KMS) 보호 정책 수립
504-
- Recovery Key와 Unseal Key의 역할 분리 이해
505-
:::
506-
507640
### 참고 자료
508641

509642
- [HashiCorp Vault Seal/Unseal 공식 문서](https://developer.hashicorp.com/vault/docs/concepts/seal)
510643
- [Vault HSM 동작 방식](https://developer.hashicorp.com/vault/docs/enterprise/hsm/behavior)
511644
- [Seal 모범 사례](https://developer.hashicorp.com/vault/docs/configuration/seal/seal-best-practices)
645+
- [Thales HSM 통합 문서](https://thalesdocs.com/gphsm/ptk/protectserver3/docs/integration_docs/hashicorp_vault/configuring_hashicorp/index.html)

0 commit comments

Comments
 (0)