platform-encryption-configure

配置平台加密

通过生成启用平台加密的元数据并选择合适的设置，来配置 Salesforce Shield 平台加密：字段应使用哪种加密方案、哪种密钥管理模型符合要求，以及租户密钥的生命周期如何运作。这是一项混合型技能——对于平台加密提供真实 Metadata API 接口的部分，生成可部署的 *.settings-meta.xml / *.field-meta.xml；对于只能通过 UI/REST 执行的操作，则提供有依据的指导。

范围

• 范围内：为字段选择并应用 encryptionScheme；通过 PlatformEncryptionSettings / EncryptionKeySettings 启用确定性加密、仅缓存密钥、外部密钥管理和重放检测；解释 BYOK / BYOKMS / EKM / 仅缓存密钥模型；租户密钥轮换和销毁的语义；加密字段的查询行为。
• 范围外：不加密的普通自定义字段（请使用 platform-custom-field-generate）；原始 Metadata API 字段参考（请使用 platform-metadata-api-context-get）；经典加密（EncryptedText 字段）——这是另一项旧版功能；向组织部署/推送元数据（这属于部署生命周期技能）。

---

必需输入

继续之前，先收集或推断以下信息：

• 问题类型：用户是在询问可部署产物（设置文件、加密字段），还是在寻求指导（该使用哪种模型、轮换密钥会发生什么）？可部署产物 → 根据 assets/ 生成 XML。指导 → 根据 references/ 作答。凡是要求解释、确认或比较的问题，都属于指导——例如“这样对吗？”、“它们之间有什么关系？”、“我们能……吗？”、“有顺序要求吗？”、“解释一下 X 和 Y 的区别”、“我们应该使用哪种密钥模型？”——即使用户还说自己准备编写、部署或创建设置，也仍然属于指导。 用户编写设置是用户自己的操作；这并不会让技能的交付物变成文件。只有明确提出“生成 / 创建 / 给我文件 / 这是我的字段，请为它加密”，才属于产物请求。
• 密钥模型选择问题属于指导，而非可部署元数据。“解释 BYOK 与外部密钥管理 / BYOKMS / EKM / 仅缓存密钥的区别”、“哪种方式能让 Salesforce 无法接触密钥材料？”、“我们应该使用 BYOK 还是 EKM？” → 将回答写入单个 Markdown 答案文件（指导说明），而不是可部署的 *.settings-meta.xml。在回答中提及启用设置（例如 canExternalKeyManagement、enableCacheOnlyKeys）不会使其变成设置产物——在答案文件中直接引用字段名称；除非用户明确提出“生成/创建设置文件”，否则不要生成 EncryptionKey.settings-meta.xml。
• 字段加密目标（字段相关工作）：对象和字段 API 名称，以及用户是否需要按此字段筛选、排序或分组（这决定使用确定性还是概率性加密）。
• 密钥模型（密钥相关工作）：密钥由 Salesforce 派生（默认）、由客户提供（BYOK）、存储于外部 KMS（BYOKMS/EKM），还是按需获取（仅缓存）。

如果请求明确，立即生成或作答——不要追问用户。

---

工作流

1. 对请求进行分类——根据上文的必需输入，判断请求是要可部署的产物还是指导说明。然后严格限定输出范围，仅包含用户要求的内容：

   • 指导性问题恰好生成一个 Markdown 答案文件——单个文件（例如 answer.md），其中包含完整的书面诊断或说明，除此之外不生成任何内容。不要同时生成 *.settings-meta.xml、*.field-meta.xml 或第二份辅助文档。此规则适用于所有“……时会发生什么？”“我该怎么做……？”“哪个模型……？”“X 对吗……？”“我们能否……？”“……之间的关系／顺序是什么？”等问题，包括查询行为以及 Cache-Only／重放相关问题。诸如“在我编写设置之前”或“在我创建文件之前”这样的短语描述的是用户接下来的步骤，并不会将问题变成可部署元数据请求——应编写答案文件，而不是设置文件。
   • 在指导性答案中提及元数据变更，并不意味着要生成对应的可部署文件。对于修复或诊断问题——“如何让字段可查询？”、“为什么我的查询失败了，该如何修复？”、“哪种密钥模型能让资料不进入 Salesforce？”——应在唯一的 Markdown 答案文件中作答，并在文中指出相关元素／方案（例如“切换到 Deterministic* 方案并启用 enableDeterministicEncryption”，或“使用 External Key Management——canExternalKeyManagement”）。不要额外生成 *.field-meta.xml 或 *.settings-meta.xml 来演示此变更——在答案中提及相关元素就是完整交付内容。只有在用户明确要求生成／创建／提供字段或设置文件时，才生成可部署元数据文件。
   • 对于产物请求，只生成明确指定的元数据文件——不要添加 DEPLOYMENT_GUIDE.md、README.md、EXPLANATION.md、组织级 settings 文件，或用户未要求的任何配套产物。
   • 如果部署步骤或组织设置是前提条件，应将其写在唯一的答案文件中（指导性请求），或写在唯一产物的代码注释中（产物请求）——绝不能另建文件。

2. 对于字段加密——阅读 references/encryption-schemes.md 以选择方案，然后将 assets/encrypted-field.field-meta.xml 载入为起始模板。将 encryptionScheme 设置为四个有效枚举值中的一个（参见参考资料）。只有 Deterministic* 方案支持筛选。

   请将字段文件写入 SFDX 源路径，而不是根目录。 *.field-meta.xml 必须位于 objects/<ObjectApiName>/fields/<FieldApiName>__c.field-meta.xml（例如 objects/Patient__c/fields/Diagnosis_Notes__c.field-meta.xml）——对象文件夹使用对象的 API 名称（自定义对象使用 Patient__c，标准对象使用 Contact），文件名则使用字段 API 名称。即使 XML 内容正确，将文件放在仓库根目录、扁平目录或其他任何文件夹中，也属于结构错误。

3. 对于组织级加密设置——载入 assets/PlatformEncryption.settings-meta.xml（确定性加密、字段历史记录加密、MEK 权限）或 assets/EncryptionKey.settings-meta.xml（Cache-Only、EKM、Data 360、事务型 DB、重放检测）。设置任何密钥模型字段之前，请阅读 references/key-models.md。

   输出文件名应使用 Settings 成员名称，而不是根元素名称，并将文件写入 settings/。 Settings 文件必须位于 settings/<member>.settings-meta.xml，其中 <member> 是组织的元数据成员名称——EncryptionKey（根元素为 <EncryptionKeySettings>）和 PlatformEncryption（根元素为 <PlatformEncryptionSettings>）。请将文件放入 settings/ 源文件夹（例如 settings/EncryptionKey.settings-meta.xml），而不是仓库根目录。将密钥设置文件命名为 Encryption.settings-meta.xml 或 EncryptionKeySettings.settings-meta.xml，会导致部署失败，并报错 "The object '…' of type Settings metadata does not exist." 仅缓存密钥和重放检测是单向依赖关系，不会自动启用。 只有在 enableCacheOnlyKeys 为 true 后，才能设置 enableReplayDetection；启用仅缓存模式本身不会自动开启重放检测。组织可以在关闭重放检测的情况下正常使用仅缓存模式。

4. 对于租户密钥操作（轮换、销毁、上传 BYOK、设置仅缓存模式的回调）——请阅读 references/tenant-secret-lifecycle.md。这些操作只能通过 UI/REST 完成；请将相关指导写入唯一的 Markdown 答案文件，而不是可部署的元数据文件。

5. 验证生成的设置 XML——以文件路径作为参数运行 scripts/validate-encryption-metadata.sh，并修复它报告的所有问题。该脚本会确定性地检查重放检测依赖关系和 encryptionScheme 枚举值。

6. 与已完成的示例进行比较——根据 examples/cache-only-keys.settings-meta.xml 验证生成的 EncryptionKeySettings 文件。

---

规则 / 约束

约束	原因
encryptionScheme 必须恰好是 CaseInsensitiveDeterministicEncryption、CaseSensitiveDeterministicEncryption、None、ProbabilisticEncryption 其中之一	这些是 Metadata API（CustomField，API 44.0+）接受的唯一值；任何其他字符串都会导致部署失败。
仅当 enableCacheOnlyKeys 为 true 时才设置 enableReplayDetection	合约规定："设置 enableReplayDetection 为 true 前，必须先将 enableCacheOnlyKeys 设为 true"——这是单向依赖关系。
只有当字段必须用于筛选、排序或分组时，才使用确定性方案	概率加密更强，但无法筛选；确定性加密以牺牲部分密码学强度为代价，换取可查询性。
绝不要声称对概率加密字段进行筛选/排序/分组会悄然返回零行	平台会拒绝该查询，并返回 INVALID_FIELD（参见注意事项）；告诉用户查询“什么也不返回”是不准确的。
不要输出 enableExternalKeyManagement——该字段实际为 canExternalKeyManagement	WSDL 元素是 canExternalKeyManagement；部分文档中的示例使用了不存在的元素名称。
事务数据库、EKM 和 Data 360 密钥字段要求 API 63.0+	canEncryptTransactionalDatabase、canExternalKeyManagement、canManageDataCloudKeys 均在 63.0 中引入。
指导类问题必须恰好生成一个 Markdown 答案文件——绝不要生成可部署的 *.settings-meta.xml / *.field-meta.xml，也不要生成第二份文档	答案文件是用户的参考文档——它会保留在工作区中，也可供分享或修订。针对指导类问题生成可部署的元数据文件属于未经请求的配置，可能被意外应用；不生成文件则会让用户没有可用的交付物。
产物类请求只能生成所要求的元数据文件——不要生成配套文件	添加 DEPLOYMENT_GUIDE.md/README.md/EXPLANATION.md，或用户未要求的额外 settings 文件，都会造成干扰。前置条件应写在产物的代码注释中，而不是另行生成文件。

---

注意事项

问题	解决方案
对概率加密字段进行筛选／排序／分组	查询会被拒绝，并返回 INVALID_FIELD：“field '' can not be sorted / filtered / grouped in a query call.” 如果需要支持查询，请将字段改为确定性加密方案。
以为仅缓存密钥会自动启用重放检测	并不会。请显式设置 enableReplayDetection，且只能在设置 enableCacheOnlyKeys=true 之后设置。
确定性匹配的区分大小写行为	CaseSensitiveDeterministicEncryption 会精确匹配大小写；CaseInsensitiveDeterministicEncryption 会对大小写进行规范化。选错会导致相等筛选条件悄然失效。
混淆 BYOK 与 BYOKMS/EKM	BYOK = 你上传密钥材料，由 Salesforce 存储；BYOKMS/EKM = 密钥材料保留在你的外部 KMS 中。参见 references/key-models.md。
使用 enableExternalKeyManagement 元素名称	元素名称错误。字段是 canExternalKeyManagement。
混淆 Classic Encryption 与 Shield	encryptionScheme 仅适用于 Shield。EncryptedText 自定义字段属于旧版 Classic 功能，不在范围内。

---

输出要求

交付内容取决于请求——只能生成以下指定内容，不得添加其他内容：

• 指导类问题必须且只能生成一个 Markdown 答案文件。 任何“……时会发生什么”“如何……”“哪种模型……”“X 是否合适……”等问题——包括加密字段的查询行为、仅缓存密钥与重放检测的关系、租户密钥／BYOK／仅缓存密钥的生命周期，以及密钥模型的选择——都应通过编写一个完整说明诊断／解释的 Markdown 文件来回答（例如 answer.md）。不要另外生成可部署的 *.settings-meta.xml／*.field-meta.xml 文件或第二份文档，也不要完全不生成文件——答案文件是用户可长期参考的文档。
• 字段加密构件：只能生成设置了 encryptionScheme 的 *.field-meta.xml，路径为 objects/<ObjectApiName>/fields/<FieldApiName>__c.field-meta.xml。不能生成设置文件，也不能生成部署指南。选择与请求匹配的 <type>：字符串字段长度不超过 255 个字符时使用 Text；只有字段必须超过 255 个字符（256+）时才使用 LongTextArea。“最长 255 个字符的长文本”应使用 Text 字段，而不是 LongTextArea。删除模板中的说明性注释块，交付干净的元数据。附带的聊天说明应简短——用一两句话说明所选方案及原因（例如：“ProbabilisticEncryption — 静态数据保护最强；该字段无法筛选／排序／分组，符合你不需要查询的要求。”）。不要复述整个提示，不要枚举所有方案，也不要添加设置／部署教程；交付物是文件，而不是长篇说明。
• 组织设置构件：只能生成请求所需的设置文件，路径为 settings/<member>.settings-meta.xml，文件名应与其 Metadata API 成员名称一致——settings/PlatformEncryption.settings-meta.xml（根元素为 <PlatformEncryptionSettings>）和／或 settings/EncryptionKey.settings-meta.xml（根元素为 <EncryptionKeySettings>）。不要使用根元素名称作为文件名，也不要将文件放在仓库根目录。

不要添加用户未要求的配套文件（DEPLOYMENT_GUIDE.md、README.md、额外的组织设置文件）；应在构件的代码注释中说明前置条件，或在唯一的答案文件中说明指导内容。文件结构遵循 assets/ 中的模板。

---

跨技能集成

需求	委派给
不加密的自定义字段	platform-custom-field-generate
原始 Metadata API 类型／字段参考	platform-metadata-api-context-get

参考文件索引

文件	何时阅读
assets/encrypted-field.field-meta.xml	生成加密自定义字段之前
assets/PlatformEncryption.settings-meta.xml	生成组织加密策略设置（成员 PlatformEncryption）之前
assets/EncryptionKey.settings-meta.xml	生成密钥管理设置（仅缓存、EKM、Data 360；成员 EncryptionKey）之前
references/encryption-schemes.md	选择确定性或概率性加密方案，或说明加密字段查询行为时
references/key-models.md	配置或说明 BYOK / BYOKMS / EKM / 仅缓存密钥模型时
references/tenant-secret-lifecycle.md	用户询问密钥轮换、销毁或 BYOK 上传时
examples/cache-only-keys.settings-meta.xml	验证生成的仅缓存密钥设置文件时
scripts/validate-encryption-metadata.sh	生成任何设置 XML 后——验证重放依赖项和方案枚举值