> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 암호화

> 민감한 설정값을 암호화하는 KMS 공급자를 선택하고, 레거시 암호문 재암호화 및 무결성 감사를 수행합니다.

<Info>관리자 › 설정 › 암호화</Info>

Config 시크릿, 데이터베이스 연결, 도구 연결 키, 사용자 API 키 등 **민감한 설정값을 암호화**할 키 관리 백엔드(KMS, Key Management System)를 선택합니다.

<Frame caption="관리자 > 설정 > 암호화 — KMS 공급자 및 마이그레이션">
  <img src="https://mintcdn.com/cloocus/3CYTE_uN2N3A4joq/images/admin/settings-encryption.png?fit=max&auto=format&n=3CYTE_uN2N3A4joq&q=85&s=67a9d7b755df4cf82260f450fccadc9c" alt="암호화 설정" width="2880" height="1800" data-path="images/admin/settings-encryption.png" />
</Frame>

***

## 프로바이더

암호화 백엔드는 **KMS 공급자** 필드에서 선택합니다.

| KMS 공급자                    | 설명                                                                            |
| -------------------------- | ----------------------------------------------------------------------------- |
| **로컬 (Fernet)**            | `WEBUI_SECRET_KEY` 기반 자체 Fernet 암호화. 외부 의존성 없음                                |
| **Azure Key Vault (엔벨로프)** | 데이터를 AES-256-GCM으로 암호화하고, 그 데이터 키(DEK)를 Azure Key Vault의 RSA-OAEP-256 키로 감쌉니다 |

<Note>
  공급자를 전환해도 **기존 데이터는 자동 마이그레이션되지 않습니다.** 레거시 암호문은 fallback으로 계속 복호화되므로 즉시 동작이 깨지지는 않지만, 새 공급자로 통일하려면 아래 마이그레이션을 실행하세요.
</Note>

### Azure Key Vault 설정 항목

**Azure Key Vault (엔벨로프)** 를 고르면 아래 입력란이 펼쳐집니다.

| 설정 항목                       | 설명                                                                |
| --------------------------- | ----------------------------------------------------------------- |
| **KEK URI (기본 티어)**         | 기본으로 사용할 Key Vault 키 URI. `Confidential`·`Internal` 분류 암호화에 사용됩니다 |
| **Restricted KEK URI (선택)** | 더 높은 등급의 데이터를 별도 키로 감쌀 때 지정합니다                                    |

**서비스 주체 (선택)** — 비워 두면 서버의 관리 ID/기본 자격 증명을 사용합니다.

| 설정 항목         | 설명               |
| ------------- | ---------------- |
| **테넌트 ID**    | 디렉터리(테넌트) ID     |
| **클라이언트 ID**  | 애플리케이션(클라이언트) ID |
| **클라이언트 시크릿** | 클라이언트 시크릿 값      |

**연결 테스트**(화면 왼쪽 아래)를 눌러 Key Vault에 접근되는지 먼저 확인하세요. 결과는 `연결됨` / `실패` 배지로 표시됩니다.

***

## 기존 데이터 마이그레이션

**기존 데이터 마이그레이션**을 실행하면 현재 설정된 공급자로 모든 레거시 암호문을 **재암호화**합니다.

* 대상: Config 시크릿 · DbSphere 연결 · 도구 연결 키 · 사용자 API 키
* **멱등성**이 보장되어 재실행해도 안전합니다.
* 실행하면 대상별로 `마이그레이션 N` · `건너뜀 N` · `실패 N` 배지가 표시됩니다.

***

## 자동 회전

**Azure Key Vault** 공급자에서만 나타나는 구획으로, Key Vault의 키가 새 버전으로 바뀌었는지 주기적으로 점검해 재암호화합니다.

| 설정 항목          | 설명                                         | 기본값  |
| -------------- | ------------------------------------------ | ---- |
| **자동 회전 활성화**  | 주기 점검·회전 실행                                | 꺼짐   |
| **Dry-run 모드** | 실제 설정은 건드리지 않고 "회전이 필요하다"는 판단만 감사 로그에 남깁니다 | 꺼짐   |
| **검사 간격 (시간)** | 최소 1. 스케줄러는 간격당 최대 한 번 점검합니다(24 = 하루 한 번)  | `24` |

**Dry-run 검사** 또는 **지금 검사**를 누르면 즉시 점검하고, 결과가 키 등급별로 `최신` · `회전됨` · `회전 예정 (dry-run)` · `오류` 배지로 표시됩니다. 마지막 점검 시각도 함께 표시되며 점검한 적이 없으면 `없음`입니다.

<Warning>
  **기본은 꺼짐입니다.** 먼저 Dry-run으로 무엇이 회전 대상인지 확인한 뒤 켜세요.
</Warning>

***

## 감사 로그 · 무결성 검증

모든 KMS `wrap`·`unwrap`·`rotate`·`health-check` 작업은 **변조 감지용 해시 체인**으로 기록됩니다.

* 과거 기록을 변조하면 검증 시 체인이 깨집니다.

| 동작         | 설명                  |
| ---------- | ------------------- |
| **무결성 검증** | 감사 로그 해시 체인의 무결성 확인 |
| **연결 테스트** | 현재 KMS 공급자 연결 상태 점검 |

전체 감사 기록과 무결성 검증은 [모니터링 › KMS 감사](/ko/monitoring/kms-audit)에서 확인할 수 있습니다.