/ /

自动化配置加密

自动化配置加密可保护自动化代理的本地备份配置文件中的敏感凭证。当代理将集群配置的备份存储在磁盘上时，它会使用 AES-256-GCM 对敏感字段（包括密码和身份验证密钥）进行加密，而不是以明文形式写入。

此功能可帮助组织满足 PCI-DSS、HIPAA 和 SOC 2 等框架的合规要求。

默认下禁用加密。除非您明确启用此功能，否则现有部署将保持未加密状态。

加密方法

Ops Manager支持三种自动化配置加密方法：

方法	最适合	密钥加密密钥(KEK) 来源
在线 (KMIP)	具有 KMIP 基础架构的环境	客户托管的 KMIP服务器
离线	气隙或独立运行的实例环境	机器生成的密钥
默认	自动合规调整	遵循静态加密设置

在线 (KMIP)

提示

当 KMIP 基础架构可用时，使用在线 ( KMIP )模式。它提供了最强的安全性，因为主密钥永远不会离开您的 HSM。

在线模式最适合具有 KMIP 基础架构的环境。主密钥驻留在与 KMIP 兼容的外部 HSM 中，从不接触磁盘。单独的引导密钥可在本地保护 KMIP 证书凭证，从而实现无人值守重启。

注意

此方法需要现有的与 KMIP 兼容的服务器。您必须配置客户端证书 (mTLS)身份验证，以匹配MongoDB Enterprise Advanced 的 security.kmip.* 配置。

要使用在线模式，请将 encryptionMethod设立为 ONLINE_KMS 并提供您的 KMIP服务器详细信息。

Parameter	说明	必需
`kmip.serverName`	KMIP服务器主机名或IP	是
`kmip.port`	KMIP服务器端口。默认：`5696`。	No
`kmip.serverCAFile`	CA 证书路径 (Unix)	是
`kmip.serverCAFileWindows`	CA 证书路径 (Windows)	可选的
`kmip.clientCertificateFile`	客户端证书路径 (Unix)	是
`kmip.clientCertificateFileWindows`	客户端证书路径 (Windows)	可选的
`kmip.clientCertificatePassword`	客户端证书密码（如果 PEM 已加密）	No
`kmip.keyIdentifier`	KMIP服务器上现有密钥的 UUID。如果为空，代理会自动创建一个新密钥。	No
`kmip.useLegacyProtocol`	使用 KMIP 1.0/1.1（创建 + GET）而不是 KMIP 1.2（加密/解密）。当 KMIP服务器不支持KMIP 1.2 时使用。	No

配置模式

{
  "configEncryption": {
    "encryptionMethod": "ONLINE_KMS",
    "kmip": {
      "serverName": "<hostname>",
      "port": 5696,
      "serverCAFile": "<path-unix>",
      "serverCAFileWindows": "<path-windows>",
      "clientCertificateFile": "<path-unix>",
      "clientCertificateFileWindows": "<path-windows>",
      "clientCertificatePassword": "<password>",
      "keyIdentifier": "<optional-uuid>",
      "useLegacyProtocol": false
    }
  }
}

开始之前

在启用在线KMIP加密之前，请验证以下内容：

TLS 握手：运行以下命令并确认握手成功且证书已接受：
openssl s_client -connect <serverName>:<port> \ -CAfile <serverCAFile> -cert <clientCertificateFile>
证书权限：确认客户端证书已获授权执行所需的 KMIP 操作。检查 KMIP 服务器的管理控制台或日志。
网络可访问性：确认代理托管可以通过配置的端口访问 KMIP服务器。验证防火墙规则、安全组和 DNS 解析。
证书过期：确保服务器CA 和客户端证书未过期。要进行检查，运行：
openssl x509 -enddate -noout -in <certFile>

KMIP 服务器权限

必须为 KMIP服务器上的以下操作授权客户端证书：

KMIP模式	所需操作
默认 (KMIP 1.2)	创建、加密、解密对称密钥
旧版 (`useLegacyProtocol: true`)	创建、GET 对称密钥

如果提供 keyIdentifier，则不需要“创建”权限。请参阅 KMIP服务器文档，为客户端证书配置适当的权限。

离线

离线模式最适合气隙或独立运行的实例运行环境。该代理将客户提供的 UUID 与物理机参数相结合，从而派生出加密密钥。此方法不需要外部依赖。

要使用离线模式，请将 encryptionMethod设立为 OFFLINE_SOFTWARE 并提供以下参数：

Parameter	说明	必需
`dynamicSalt`	用于密钥派生的 UUID。用作轮换触发。	是

动态 Salt UUID

dynamicSalt 是加密随机 UUID，用作密钥派生进程的附加 input。

Ops Manager用户界面：单击 Generate 自动生成新的 UUID。
公共API：提供加密随机 UUID（版本 4）。使用安全的随机生成器。避免使用可预测、连续或硬编码的 UUID。

将动态盐更改为新的 UUID 会触发密钥重新派生，这是离线模式的主节点 (primary node in the replica set)轮换机制。

配置模式

{
  "configEncryption": {
    "encryptionMethod": "OFFLINE_SOFTWARE",
    "dynamicSalt": "<UUID>"
  }
}

默认

如果对部署中的任何进程启用了静态加密 (security.enableEncryption)，则离线加密会自动激活，无需显式配置。否则，配置将保持未加密状态。

注意

默认模式不支持手动密钥轮换。

配置加密

您可以使用Ops Manager用户界面或公共API配置自动化配置加密。

通过Ops Manager用户界面

在Ops Manager中配置项目级别的加密。

导航到“自动化配置加密”设置。

单击 Settings、Admin Project Settings、Automation Config Encryption。

选择一种加密方法。

选择Online (KMIP) 、 Offline或Default 。

填写所选方法的必填字段。

有关字段说明，请参阅在线 (KMIP) 或离线。

保存并部署更改。

单击 Save，然后查看并部署更改。

通过公共API

您可以通过Ops Manager自动化配置终结点管理自动化配置加密。

终结点：PUT /groups/{PROJECT-ID}/automationConfig

在自动化配置请求正文中包含 configEncryption对象。要学习；了解有关完整请求和响应的更多信息，请参阅更新自动化配置。

您必须具有Project Automation Admin角色才能使用此终结点。

请求正文

在自动化配置请求正文中包含configEncryption 对象。有关完整的字段引用，请参阅在线 (KMIP) 或离线。

在线 (KMIP)：

{
  "configEncryption": {
    "encryptionMethod": "ONLINE_KMS",
    "kmip": {
      "serverName": "kmip.example.com",
      "serverCAFile": "/path/to/ca.pem",
      "clientCertificateFile": "/path/to/client.pem"
    }
  }
}

离线：

{
  "configEncryption": {
    "encryptionMethod": "OFFLINE_SOFTWARE",
    "dynamicSalt": "<UUID>"
  }
}

响应代码

有关完整的响应规范，请参阅更新自动化配置。以下错误代码特定于 configEncryption验证：

HTTP 代码	说明	注意
`200 OK`	配置已保存为草稿。	返回一个空的JSON对象： `{}`
`400 Bad Request`	`INVALID_CONFIG_ENCRYPTION_SETTINGS`	如果 `configEncryption`对象未通过内部验证，则返回此结果。
`403 Forbidden`	`CHANGE_NOT_ALLOWED_EXTERNAL_SYSTEM`	如果项目受到外部托管锁的限制，则返回此函数。

禁用加密

要禁用自动化配置加密，请将加密方法设立为“默认”。

导航到“自动化配置加密”设置。

单击 Settings、Admin Project Settings、Automation Config Encryption。

选择默认。

将加密方法设置为 Default。

保存并部署更改。

单击 Save，然后查看并部署更改。

注意

如果项目中没有使用静态加密的部署，则在部署此更改后将禁用加密。

加密字段

只有敏感字段才会被加密。端口、日志路径和拓扑结构等非敏感操作数据仍以明文形式存在。

category	字段
身份验证	`auth.key` `auth.newKey` `auth.autoPwd` `auth.newAutoPwd` `auth.autoKerberosWindowsPassword`
用户凭证	`auth.usersWanted.[].initPwd` `auth.usersWanted.[].scramSha1Creds.salt` `auth.usersWanted.[].scramSha1Creds.storedKey` `auth.usersWanted.[].scramSha1Creds.serverKey` `auth.usersWanted.[].scramSha256Creds.salt` `auth.usersWanted.[].scramSha256Creds.storedKey` `auth.usersWanted.[].scramSha256Creds.serverKey`
TLS	`tls.autoPEMKeyFilePwd`
LDAP	`ldap.bindQueryPassword` `ldap.newBindQueryPassword`
Prometheus	`prometheus.password` `prometheus.passwordHash` `prometheus.passwordSalt` `prometheus.tlsPemPassword`
BI Connector	`mongosqlds.[].tlsPEMKeyPassword`
加密提供商	`encryptionProviders.awsKms.accessKeyId` `encryptionProviders.awsKms.secretAccessKey` `encryptionProviders.awsKms.sessionToken` `encryptionProviders.azureKeyVault.clientId` `encryptionProviders.azureKeyVault.tenantId` `encryptionProviders.azureKeyVault.secret` `encryptionProviders.googleCloudKMS.serviceAccountKey`
配置加密	`configEncryption.kmip.clientCertificatePassword`

文件工件

该代理会在其配置的备份目录中存储两个文件。代理用户必须具有此目录的读/写入访问权限。

file	说明	权限 (Unix / Windows)
`mms-cluster-config-backup.json`	具有内联加密敏感字段的集群配置	`0600` / `0600`
`master.key`	封装的加密密钥(JSON)	`0400` / `0600`

代理使用原子模式写入文件（写入临时文件，然后重命名）。代理会在密钥文件之前保留配置文件，以确保在写入期间发生崩溃时一致的回滚。

警告

请勿修改这些文件。当无法访问Ops Manager时，代理使用它们从重启中恢复。

密钥轮换

代理支持手动和自动密钥轮换。

手动轮换

要手动轮换加密密钥，请使用以下触发器：

模式	触发器
在线 (KMIP)	更新Ops Manager中的任何 KMIP 配置属性
离线	在Ops Manager中生成新的动态 Salt UUID
默认	先切换到在线或 Offline模式

自动轮换

代理会在以下情况下自动轮换加密密钥：

代理进程将重新启动。
代理版本变更（升级或降级）。

何时轮换

在以下情况下轮换密钥：

疑似密钥泄露
根据组织的安全策略安排轮换
涉及基础设施访问权限的人事变动

Considerations

以下情况可能会影响部署中的自动化配置加密。

硬件更改：更换硬件或迁移VM可能会使代理无法访问本地备份。该代理通过从Ops Manager获取新配置来自动恢复。
VM cloning: 克隆的VM保留相同的机器身份，并且可以解密离线加密的数据。使用在线 (KMIP)模式实现克隆隔离的安全性。
代理升级和降级：更改代理版本会使加密项目失效。代理自动从Ops Manager获取新配置以重新加密。
Ops Manager连接：如果代理无法解密本地文件且无法访问Ops Manager，则会进入错误状态并重试，直到连接恢复。
KMIP服务器可用性：在代理操作进行密钥包装和解包期间，必须可访问 KMIP服务器。
Kubernetes Operator：Operator模式会禁用加密。Kubernetes Operator 单独管理密钥。
延迟迁移：现有部署在升级转为默认模式。如果为任何进程启用了静态加密，则会自动激活离线加密。

安全架构

加密系统使用信封加密，并使用加密字段的数据加密密钥（DEK）和保护 DEK 的密钥加密密钥 (KEK)。在在线模式下，KEK 驻留在与 KMIP 兼容的 HSM 中，并且从不接触磁盘。在离线模式下，代理从特定于机器的属性中派生出 KEK，将加密数据绑定到物理托管。

加密算法

下表列出了加密进程每个阶段使用的加密算法。

用途	算法	详情
字段加密	AES-256-GCM	256 位密钥、96 位随机数、128 位身份身份验证标签。每个字段都使用唯一的随机数，并通过经过身份验证的数据 (AAD) 绑定到其配置路径，从而防止篡改或字段重新定位。
KEK 派生（离线）	PBKDF2-HMAC-SHA256	使用高迭代次数派生 KEK，以实现针对暴力攻击的计算强化。
DEK 包装	AES 密钥包装 (RFC 3394)	经 NIST 批准的算法，用于在 KEK 下保护 DEK。生成具有 8 字节完整性检查值的包装密钥。
DEK 包装（在线 KMIP 1.2）	KMIP 服务器端加密/解密	主密钥永远不会离开 KMIP服务器。服务器直接包装和解包 DEK。
DEK 封装（在线 KMIP 旧版）	AES 密钥包装 (RFC 3394)	该代理从 KMIP服务器检索密钥并在本地用于 AES 密钥换行，然后从内存中将其清零。

安全属性

自动化配置加密系统提供以下安全ACID 一致性保证。

在线模式引导：一个单独的本地包装密钥保护存储在 config.json 中的 KMIP 证书凭证。这使代理能够在无人值守的重启期间对 KMIP服务器进行身份验证，而无需在磁盘上存储明文密钥。
原子写入：代理使用崩溃安全原子模式写入配置和密钥文件。写入期间，代理可点从故障中完全恢复。
磁盘上没有明文密钥：启用加密后，代理会将备份文件中的所有凭证字段替换为加密值。master.key文件仅包含打包（加密）的密钥。

安全最佳实践

请按照以下建议加强自动化配置加密部署。

当 KMIP 基础架构可用时，首选在线 (KMIP)。它提供最强的安全。
使用 KMIP 1.2（默认）而不是旧版协议。主密钥永远不会离开 HSM。
根据组织的策略定期轮换密钥。
限制对代理配置目录的文件系统访问权限。
在脱机模式下更改硬件或迁移VM之前，确保Ops Manager连接。代理通过在下次成功轮询时获取新配置来自动恢复。

故障排除

以下部分介绍常见问题、强制恢复步骤和代理日志标签。

常见问题

下表列出了常见症状、可能的原因以及解决步骤。

症状	可能的原因	解决方案
代理在初创企业时进入错误状态	硬件或机器身份已更改（离线模式）	恢复Ops Manager连接。代理会自动恢复。
代理在初创企业时进入错误状态	无法访问 KMIP服务器或证书已过期（在线模式）	验证 KMIP 连接和证书有效性。如有需要，请在Ops Manager中更新凭证。运行 `openssl s_client` 以验证 TLS 握手、检查证书过期情况并验证防火墙和 DNS 设置。
日志显示“无法找到对象：KEY_ID”	加密密钥在 KMIP 中不可用	使用以下选项之一：在 KMIP 中恢复具有指定密钥ID 的密钥。通过Ops Manager轮换密钥。删除 `master.key`，重新启动代理，并允许其从Ops Manager获取新配置并创建新的 KMIP 密钥ID。
`agent_kmip_connect_failed` 在日志中	TLS 握手被拒绝	验证 `serverCAFile` 是否与 KMIP服务器CA 匹配。验证 `clientCertificateFile` 是否已被服务器接受。检查 KMIP服务器日志是否有身份验证失败的情况。
`agent_kmip_operation_failed` 在日志中	KMIP服务器拒绝了操作	验证客户端证书是否具有所需权限（创建/加密/解密或创建/GET）。验证 `keyIdentifier` 中的密钥 UUID 在服务器上是否存在且处于“活动”状态。
备份文件未更新	文件权限或磁盘空间不足	验证代理用户是否具有对配置目录的写入访问权限。
升级或降级后解密失败	加密工件受版本限制	代理会自动从Ops Manager获取新配置。

强制恢复

如果代理无法解密其本地备份并且可以访问Ops Manager ，则可以重置加密状态。

停止自动化代理

停止受影响托管上的自动化代理。

删除主密钥文件

从代理的备份目录中删除 master.key。此目录与包含 mms-cluster-config-backup.json 的目录相同，通常由代理配置文件中的 mmsConfigBackup 设置进行配置。

重新启动代理

启动代理。它从Ops Manager获取新配置并重新加密。

警告

在启动代理之前， Ops Manager必须可访问。如果没有连接，代理就没有可回退的配置，并进入错误状态。

要在恢复过程中禁用加密，请参阅禁用加密。

Log Tags

以下日志标签标识代理日志中与加密相关的事件。

Tag	等级	说明
`agent_encryption_write_start`	INFO	已启动写入操作
`agent_encryption_write_complete`	DEBUG	写入完成
`agent_decryption_read_start`	INFO	已启动读取/解密操作
`agent_decryption_read_complete`	DEBUG	读取/解密已完成
`agent_dek_cache_hit`	DEBUG	从缓存提供的加密密钥
`agent_dek_cache_miss`	INFO	未缓存密钥；正在再生
`agent_encryption_key_rotation`	INFO	已触发密钥轮换
`agent_encryption_key_rotation_failure`	ERROR	密钥轮换失败
`agent_encryption_method_transition`	INFO	加密方法已更改
`agent_encryption_dek_wrapped`	DEBUG	加密密钥包装（包括方法）
`agent_encryption_dek_unwrapped`	DEBUG	解包的加密密钥（包括方法）
`agent_encryption_field_encrypted`	DEBUG	加密的字段路径（Field Path）（仅路径，无值）
`agent_decryption_field_decrypted`	DEBUG	解密字段路径（Field Path）（仅路径，无值）
`agent_encryption_failure`	ERROR	加密操作失败
`agent_decryption_failure`	ERROR	解密操作失败
`agent_encryption_unexpected_error`	ERROR	加密子系统中出现意外错误
`agent_kmip_connect`	DEBUG	已建立 KMIP TLS 连接
`agent_kmip_connect_failed`	ERROR	KMIP TLS 连接失败（包括服务器、端口、重试次数）
`agent_kmip_operation`	DEBUG	KMIP 操作已完成（操作类型、密钥ID、持续时间）
`agent_kmip_operation_failed`	ERROR	KMIP 操作失败（操作类型、密钥ID、错误）
`agent_kmip_key_created`	INFO	在 KMIP服务器上创建的新密钥（密钥ID）
`agent_kmip_key_reused`	DEBUG	重复使用现有 KMIP 密钥（密钥ID、来源）
`agent_kmip_tls`	DEBUG	已构建 KMIP TLS 配置（证书路径、密码保护标志）

注意

Ops Manager从不记录敏感值。