金鑰管理
這一頁解決什麼
Section titled “這一頁解決什麼”落庫的敏感資料採分層信封加密：資料以資料金鑰加密，資料金鑰再由主金鑰包裹。 這一頁說明主金鑰放在哪、清冊怎麼看、要換鑰時走哪一條程序。 全部輪替都是手動操作，系統不會自己換鑰。
主金鑰與資料金鑰怎麼保護1 / 5
- 密碼由資料金鑰（DEK）封成密文。磁碟上看不到明文。
- 資料金鑰自己再被主金鑰（KEK）包住。這是兩層信封。
- 主金鑰不寫進資料庫。它在解封頁、環境檔、或雲端金鑰服務。
- 要用密碼時，後端先用主金鑰解開外層，才拿得到資料金鑰。
- 換主金鑰只重包外層。裡面的密文不用重寫。
連線時密碼怎麼走，見 SSH 終端
委託憑證，在解封時交付4 / 4
- 委託模式的服務啟動時處於封存狀態，等待管理員完成解封流程。
- 管理員先驗證帳密，再核對保管者目的地。
- 管理員在解封步驟輸入保管者憑證；系統在本次解封世代的記憶體中持有它。
- 服務完成解封後提供業務功能。委託憑證不寫入部署檔案或磁碟，封存時清理，重啟後重新供給。
主金鑰的三種模式
Section titled “主金鑰的三種模式”模式由 .env 的 KEK_PROVIDER 決定。
env：材料放在環境設定檔
Section titled “env：材料放在環境設定檔”ENCRYPTION_KEY 填一把 32 位元組的金鑰，三種寫法都收：32 個英數字元、64 個十六進位字元，
或解碼後恰為 32 位元組的 base64。生成方式擇一：
openssl rand -hex 32openssl rand -base64 32ui：材料只在記憶體（出貨預設）
Section titled “ui：材料只在記憶體（出貨預設）”啟動後系統處於封印狀態，除健康檢查與封印端點外的路由都回 503， 要在解封頁交齊材料才開始服務。材料在瀏覽器本地生成，不落磁碟。 解封頁任何模式都先驗證本地管理員帳密，通過後才出現材料欄或保管者憑證欄。 連續失敗會指數退避，冷卻期滿再讓下一次嘗試，不必重啟。 初始化逾時的時候，用第一次輸入的那把金鑰重試，不要換一把新的。
建議設 SEAL_UNSEAL_BIND_ADDR 讓解封端點走獨立監聽，
並以 SEAL_UNSEAL_ALLOWED_CIDRS 限定可以解封的來源網段。
kms：委託雲端金鑰服務
Section titled “kms：委託雲端金鑰服務”.env 只留 KEK_PROVIDER=kms 與 KEK_KMS_PROVIDER（aws、vault 或 gcp）。
保管處位址、Transit 鍵名、角色識別、區域與金鑰引用在金鑰管理頁與重包精靈寫入資料庫，
不再生效的舊環境變數鍵名會在首次啟動寫進庫一次並記到日誌（不記值）。
委託憑證（雲端金鑰服務的存取密、服務帳號金鑰內容、Vault secret 或 token）只在解封頁輸入，
只活在該次解封，封印即清，不進部署檔與磁碟。
委託模式重啟或封存後停在解封頁，由管理員核對拓撲再當場交保管者憑證。
資料金鑰的包裹與解包由保管處處理，資料與資產密碼不送出。Vault 用 AppRole 或 token （未封印期間續約）。金鑰版本在保管處轉；換鑰與本地↔委託走重包精靈。 多區域金鑰的主副本視為兩把金鑰，切到副本屬於換鑰，要先重包。
全新安裝可在開始服務前走委託初始化，在解封頁四步交齊管理員、拓撲與保管者憑證，再包裹存鍵。
管理端「金鑰管理」頁列出全部金鑰及其指紋。指紋的計算方式統一，可以自己核對：
echo -n <JWT_SECRET> | sha256sum # 取前 16 個十六進位字元環境變數側的金鑰只呈現指紋與管理方。委託模式以正規化後的外部金鑰引用取代材料指紋。
ui 模式另外呈現封印狀態。政策鍵「金鑰使用期限提醒天數」設為大於 0 時，
超齡的金鑰會在清冊上顯示提醒。
管理員可從金鑰管理把執行中的系統封存：停止新的金鑰使用、讓持有者做完、清快取。
封存會中止仍在使用金鑰的連線。回來路徑依模式：ui 再輸入材料、env 讀部署環境、
委託模式在解封頁核對拓撲並交保管者憑證。
資料金鑰在記憶體多久
Section titled “資料金鑰在記憶體多久”政策鍵「資料金鑰快取存活秒數」在金鑰管理政策。空值是所有模式的出廠值，表示保留到封存或重啟；
0 表示每次向保管處取、不留；正整數是自解封成功起的固定秒數，不因再用延長。
稽核蓋章鑰與簽署私鑰不受此項。封存立即清快取。量測見 保留、清除與觀測。
在金鑰管理頁開重包精靈，把資料金鑰改由新的主金鑰包裹。退役是軟退役， 舊材料保留到顯式清理為止，清理是唯一的材料銷毀點。
完成切換的方式依模式而定：
env：把新值寫進.env的ENCRYPTION_KEY後重啟。ui：重啟後在解封頁輸入新的主金鑰，不要寫進.env。kms：在重包精靈選保管者（AWS KMS、Vault Transit 或 Google Cloud KMS）並寫拓撲， 清冊的管理方為 kms、金鑰引用為該保管處的正規名稱（ARN、Transit 鍵名或 CryptoKey 資源名）。 保管者密只在解封頁提供。
從本地材料遷移到委託保管處：在重包精靈選目標保管者並寫拓撲，改 KEK_PROVIDER=kms，
移除本地材料後重啟。重啟後停在解封頁核對拓撲、交保管者憑證，再確認清冊。遠端同鑰版本輪替由保管處管理員操作。
資料金鑰與稽核蓋章鑰
Section titled “資料金鑰與稽核蓋章鑰”在金鑰管理頁選對象輪替，生效即時，不需要重啟，也不中斷既有連線。 舊密文由對應版本的金鑰解開，版本鏈保留。 有金鑰操作在進行、有未切換的重包在途、或行程內金鑰快取過期時，系統會擋下這次操作。
JWT 密鑰
Section titled “JWT 密鑰”改 .env 的 JWT_SECRET 後重啟，長度至少 32 位元組。換完之後全員需要重新登入。
匯出簽章鑰用於證據包的整包簽章，檢查點簽章鑰用於稽核鏈，兩者刻意分立。 公鑰可以在金鑰管理頁複製或下載，也有各自的端點供外部驗證者取用。 換過匯出簽章鑰之後，記得主動把新公鑰發給外部驗證者。
通知通道密鑰
Section titled “通知通道密鑰”在告警頁的通知通道編輯該通道、填新密鑰、儲存，同步更新接收端的驗證密鑰， 再按一次「測試發送」確認接收端收得到而且驗章通過。生效即時，不需要重啟。
輪替後的共同確認
Section titled “輪替後的共同確認”- 指紋如預期變化，並更新自己的紀錄。
- 每個啟用中的通知通道各按一次測試發送，確認接收端真的收到。
- 稽核裡查得到這次輪替。
- 環境變數側的金鑰，重啟後啟動日誌沒有拒絕啟動的訊息。
稽核看得到什麼
Section titled “稽核看得到什麼”- 金鑰的建立、輪替、重包與退役材料清理都留紀錄，清理另記清理筆數與各版本指紋。
- 清冊本身就是控制證據：哪些金鑰存在、由誰管理、指紋是什麼、上次輪替在何時。
- 主金鑰模式為
ui時，清冊呈現封印狀態，可以佐證服務不是以未受保護的材料在跑。 - 保管處拓撲變更記前後值並發安全告警；解封頁的管理員驗證與委託憑證輸入留痕。