知行之桥自定义主密钥配置指南：AES与PFX证书完整实施说明

一．背景

在企业的数据集成和文件传输应用中，知行之桥作为核心枢纽，负责连接数据库、内部应用、云服务及外部合作伙伴。而这些连接的背后，是大量的敏感信息——数据库密码、API密钥、系统登录凭据，它们都存储在端口的配置中。

知行之桥在设计之初就高度重视数据安全。产品内置了默认主加密密钥来保护存储在端口配置中的敏感数据，开箱即用，为所有端口配置中的敏感数据提供基础加密保护，确保它们不会以明文形式存储。

同时，对于有特定安全要求的组织，知行之桥也支持定义自定义主密钥的功能，这一设计使企业能够将MFT系统的加密实践与其既有的密钥管理基础设施无缝集成，实现对加密材料的完全自主控制，从而满足最深层次的安全与合规要求。

二．要求

知行之桥支持两种格式的自定义主密钥，可根据自身安全策略选择：

密钥格式	说明
AES密钥文件	包含随机字符串的密钥文件，轻量易用，适合快速实现自定义加密的场景
PFX证书文件	PKCS#12格式的数字证书，可设置密码保护，适合已建立PKI证书体系的企业

算法限制：使用PFX证书时，知行之桥仅支持RSA算法。其他算法（如DSA、ECC）的证书将被系统拒绝，请在生成证书时注意选择。

关键前提：密钥备份的强制性要求

自定义主密钥赋予企业完全的控制权，同时也意味着完全的责任归属。

一旦失去对自定义主密钥的访问权限，所有经其加密的凭据和配置数据将永久无法解密。

因此，在配置自定义主密钥之前，必须建立并实施完备的密钥备份与恢复机制：

• 将密钥文件存储在安全、可靠的位置
• 妥善保管PFX证书密码
• 确保在紧急情况下，有授权人员可以访问备份

三．设置步骤

3.1 定义自定义主密钥

注意：密钥存储路径需知行之桥有权访问

3.1.1 跨平台版本

在 arc.properties 配置文件中设置属性：

AES密钥

1.使用cdata.encryption.key 属性值为密钥文件路径。
2.使用 APP_KEY 环境变量来提供密钥文件的文件路径

PFX证书

使用cdata.encryption.key 属性值为证书文件路径，并在 cdata.encryption.key.password 中设置证书密码。

属性：

cdata.encryption.key：指定 AES 密钥文件的路径（包含随机字符串），或用于加密知行之桥中密码和机密等敏感数据的 PFX (PKCS#12) 证书文件。仅在想要使用自定义密钥或将密钥存储在非默认位置时才需要。
cdata.encryption.key=file:///var/opt/mykeys/mysecret.key

cdata.encryption.key.password：定义用于主密钥的 PFX 文件的密码
cdata.encryption.key.password=MyS3curePa55w0rd

3.1.2 .NET版本

在 Web.Config 文件的  节点中，通过以下两个键值对分别指定主密钥文件路径及PFX证书密码（如适用）：

AppKey可定义密钥

如果定义PFX密钥且需要密码，可用AppKeyPassword 设置密码

注意：Web.Config 文件中仅能包含一个  节点，请确保将上述配置添加至现有节点中，而非重复创建。

3.1.3 确认设置

设置成功后，AppDirectory中将会生成一个.arc_secure_key文件，同时还会生成一个~backup目录用于备份该key文件。

3.2 主密钥更改

如需更换主密钥（例如定期轮换或应对密钥泄露），知行之桥提供了专门的命令行工具，确保过程平滑无中断。

请不要直接修改 arc.properties或者Web.Config 文件，否则将会导致知行之桥无法识别之前已经加密的敏感数据.

操作前请确保：知行之桥服务已停止运行，且新密钥文件已准备就绪。

3.2.1跨平台版本

• 更换AES密钥文件（无需密码）
  arc.jar -ChangeMasterKey
• 更换PFX证书文件（需要密码）
  arc.jar -ChangeMasterKey

3.2.2 .NET版本

• 更换AES密钥文件（无需密码）
  CData.exe appChangeMasterKey -NewKey -@libdir “www\bin”
• 更换PFX证书文件（需要密码）
  CData.exe appChangeMasterKey -NewKey -NewKeyPassword -@libdir “www\bin”

四．安全模式

如果丢失了自定义主密钥，且无法找回，但您在其他地方保留有所有敏感信息的原始记录（如密码、API密钥等），可以通过安全模式启动知行之桥，以便重新配置系统。

安全模式的作用

启用安全模式后，知行之桥将：

• 禁用所有后端自动化服务，防止系统在无法解密的情况下执行错误操作
• 启用非常有限的管理功能，允许您查看端口配置并重新输入敏感信息

否则因为知行之桥不能解密所有的密钥信息，系统运行起来就会产生大量报错。

需要特别注意的是：启用安全模式并不意味着系统会自动切换回默认主密钥。

• 安全模式只是为您提供一个“修复窗口”，让您可以手动重新输入所有敏感信息
• 进入安全模式后，您需要重新配置自定义主密钥
• 然后逐个端口重新输入密码、API密钥等凭据
• 完成所有重新配置后，退出安全模式，系统恢复正常运行

启用方法

• 跨平台版：运行 java -jar arc.jar -safemode
• .NET 版：在 Web.Config 文件的 appSettings 元素中添加 

五．适用场景

该功能主要面向有严格安全要求的组织，具体场景包括：

• 合规性要求：满足GDPR、HIPAA、PCI DSS等法规中关于加密密钥必须由企业自行控制和管理的要求。
• 内部安全策略对齐：使第三方MFT软件的加密实践，与您企业既定的密钥管理规范、密码策略强制保持一致。
• 与现有基础设施集成：方便您将加密密钥纳入企业现有的密钥管理系统 中进行统一存储、轮换和审计。
• 提升安全水位：在默认密钥之外，增加一层由您完全掌控的防护，降低因软件内置密钥带来的潜在风险。

注：文案部分图片及内容来源于网络，版权归原创作者所有，如有侵犯到您的权益，请您联系我们进行删除，给您带来困扰，我们深感抱歉。