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

# 定義自定義主要金鑰

> 如何配置和輪換用於加密知行之橋中敏感資料的自定義主要金鑰。

export const siteNameShort = "知行之橋";

export const siteName = "知行之橋";

{siteName} 使用主要金鑰來保護儲存在端口配置中的敏感加密資料，如密碼、API 金鑰和連線憑據。預設情況下，{siteNameShort} 提供內建主要金鑰，但具有嚴格安全要求的組織可以定義自定義主要金鑰，以保持對其加密基礎設施的完全控制。這使你能夠輕鬆輪換使用者定義的主要金鑰。

主要金鑰可以有兩種格式：AES 金鑰檔案中的隨機字串，或帶有可選密碼保護的 PFX (PKCS#12) 憑證檔案。自定義主要金鑰使企業能夠將 {siteNameShort} 的加密實踐與其內部安全策略對齊、符合監管要求，並與現有的金鑰管理系統整合。

<Warning>失去對自定義主要金鑰的存取權限會導致 {siteNameShort} 無法解密儲存的憑據和配置資料。在配置自定義主要金鑰之前，應實施安全的金鑰備份和恢復程式。</Warning>

### 瞭解資料加密金鑰和主要金鑰

加密是使用*金鑰*（一段資料）將明文轉換為密文。當你首次使用應用程式時，{siteNameShort} 會生成一個隨機金鑰，該金鑰不會以明文形式儲存在任何位置。這就是*資料加密金鑰*（DEK）。所有資料都使用此金鑰進行加密。

*主要金鑰*（也稱為金鑰加密金鑰或 KEK）不直接加密資料。相反，它是一個用於加密其他金鑰的包裝器。{siteNameShort} 也提供了內建主要金鑰，但如上所述，你也可以改為定義自己的主要金鑰。本主題的其餘部分介紹如何建立或更新使用者定義的主要金鑰。

## 定義自定義主要金鑰

定義主要金鑰的方式因 {siteNameShort} 版本型別而異。

* \*\*跨平臺版：\*\*在 [arc.properties](./arc-properties-configuration) 配置檔案中使用 [cdata.encryption.key](./arc-properties-configuration#cdata-encryption-key) 屬性定義金鑰。如果要定義 PFX 金鑰且需要密碼，請在 [cdata.encryption.key.password](./arc-properties-configuration#cdata-encryption-key-password) 屬性中進行設定。或者，如果使用 AES 金鑰，可以使用 `APP_KEY` 環境變數來提供金鑰檔案路徑。

* \*\*.NET 版：\*\*如果在 Web.Config 檔案的 `appSettings` 元素中找不到 `AppKey` 設定，則主要金鑰加密處於停用狀態。要啟用它，請在 Web.Config 檔案的 `AppKey` 設定元素中設定檔案路徑。如果要定義 PFX 金鑰且需要密碼，請在 `AppKeyPassword` 設定中進行設定。以下是需要新增到 Web.Config 中的 XML 片段：

  ```xml theme={null}
  <appSettings>
    <!-- The path to the master key file to use for encryption. To replace an existing master key, do not modify this file. Instead, you must use: CData.exe appChangeMasterKey -NewKey <new-master-key-path>. -->
    <add key="AppKey" value="C:\Keys\mykey.pfx" />
    <add key="AppKeyPassword" value="Password123" />
  </appSettings>
  ```

## 更改主要金鑰

如有必要，可以更換主要金鑰檔案。{siteNameShort} 始終使用你提供的金鑰進行加密。金鑰檔案由系統安全地管理和備份，該過程旨在為使用者降低風險和複雜度。要更改主要金鑰，請確保已停止伺服器，然後使用以下選項之一：

* \*\*跨平臺版：\*\*管理員可以使用 `arc.jar -ChangeMasterKey <new-master-key-file-path>` 命令輪換加密金鑰，而不會中斷操作。如果要將主要金鑰更改為 PFX 檔案且需要密碼，請使用 `arc.jar -ChangeMasterKey <new-master-key-file-path> <new-master-key-password>` 命令。
* \*\*.NET 版：\*\*管理員必須使用 `CData.exe appChangeMasterKey -NewKey <new-master-key-file-path> -@libdir "www\bin"` 命令（不要直接修改 Web.Config 檔案）。如果要將主要金鑰更改為 PFX 檔案且需要密碼，請使用 `CData.exe appChangeMasterKey -NewKey <new-master-key-file-path> -NewKeyPassword <new-PFX-password> -@libdir "www\bin"` 命令。

<Note>{siteNameShort} 在 PFX 憑證檔案中僅支援 RSA 演算法。其他 DSA 或 ECC 憑證將被拒絕。</Note>

## 使用安全模式

如果丟失了自定義主要金鑰，並且需要從其他記錄源重新儲存配置中的敏感值，可以在安全模式下啟動 {siteNameShort}。這會停用所有後端自動化服務，並啟用非常有限的功能，以便你嘗試恢復設定和執行其他任務。要啟用安全模式：

* \*\*跨平臺版：\*\*執行 `java -jar arc.jar -safemode`
* \*\*.NET 版：\*\*在 Web.Config 檔案的 `appSettings` 元素中新增 `<add key="SafeMode" value="true" />`。