> ## 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" />`。