Platform Encryption Configure

Configure Platform Encryption

Configures Salesforce Shield Platform Encryption by generating the metadata that turns it on and choosing the right settings: which encryption scheme a field should use, which key-management model fits a requirement, and how the tenant-secret lifecycle works. This is a hybrid skill — it emits deployable *.settings-meta.xml / *.field-meta.xml where Platform Encryption exposes a real Metadata API surface, and returns grounded guidance where the operation is UI/REST-only.

Scope

• In scope: choosing and applying encryptionScheme on a field; enabling deterministic encryption, Cache-Only Keys, External Key Management, and replay detection via PlatformEncryptionSettings / EncryptionKeySettings; explaining BYOK / BYOKMS / EKM / Cache-Only key models; tenant-secret rotation and destruction semantics; the query behavior of encrypted fields.
• Out of scope: a plain custom field with no encryption (use platform-custom-field-generate); the raw Metadata API field reference (use platform-metadata-api-context-get); Classic Encryption (EncryptedText fields) — that is a separate, legacy feature; deploying/pushing metadata to an org (that belongs to a deploy lifecycle skill).

Required Inputs

Gather or infer before proceeding:

• Question type: is the user asking for a deployable artifact (a settings file, an encrypted field) or guidance (which model, what happens when I rotate a key)? Deployable → generate XML from assets/. Guidance → answer from references/. A question is guidance whenever the ask is to explain, confirm, or compare — "is that right?", "what's the relationship?", "can we…?", "is there an ordering requirement?", "explain the difference between X and Y", "which key model should we use?" — even if the user also says they are about to write, deploy, or author settings themselves. The user writing settings is their action; it does not make the skill's deliverable a file. Only an explicit "generate / create / give me the file / here is my field, encrypt it" is an artifact request.
• Key-model choice questions are guidance, not deployable metadata. "Explain BYOK vs external key management / BYOKMS / EKM / Cache-Only", "which one keeps key material out of Salesforce?", "should we use BYOK or EKM?" → answer them in a single markdown answer file (the guidance write-up), not a deployable *.settings-meta.xml. Naming the enabling setting in that answer (e.g. canExternalKeyManagement, enableCacheOnlyKeys) does NOT turn it into a settings artifact — cite the field name inline in the answer file; do not emit an EncryptionKey.settings-meta.xml unless the user explicitly says "generate/create the settings file."
• Field encryption target (for field work): the object and field API name, and whether the user needs to filter, sort, or group on the field (drives deterministic vs probabilistic).
• Key model (for key work): whether keys are Salesforce-derived (default), customer-supplied (BYOK), stored in an external KMS (BYOKMS/EKM), or fetched on demand (Cache-Only).

If the request is clear, generate or answer immediately — do not interrogate the user.

Workflow

1. Classify the request — deployable artifact vs guidance, using the Required Inputs above. Then scope the output to exactly what was asked:

   • A guidance question produces exactly one markdown answer file — a single file (e.g. answer.md) containing the full written diagnosis/explanation — and nothing else. Do not also emit a *.settings-meta.xml, a *.field-meta.xml, or a second helper doc. This covers every "what happens when…?", "how do I…?", "which model…?", "is X right…?", "can we…?", "what's the relationship / ordering…?" question, including query-behavior and Cache-Only/replay questions. A clause like "before I write our settings" or "before I author the file" describes the user's next step and does NOT turn the question into a deployable-metadata request — write the answer file, not a settings file.
   • Naming a metadata change in a guidance answer does NOT mean emitting the deployable file for it. A remediation or diagnosis question — "how do I make the field queryable?", "why did my query fail and how do I fix it?", "which key model keeps material out of Salesforce?" — is answered inside the one markdown answer file, naming the relevant element/scheme inline (e.g. "switch to a Deterministic* scheme and enable enableDeterministicEncryption", or "use External Key Management — canExternalKeyManagement"). Do not additionally materialize a *.field-meta.xml or *.settings-meta.xml to demonstrate that change — mentioning the element in the answer is the complete deliverable. Produce a deployable metadata file only when the user explicitly says generate/create/give me the field or settings file.
   • An artifact request gets only the specific metadata file(s) named — do not add a DEPLOYMENT_GUIDE.md, README.md, an EXPLANATION.md, an org-settings file, or any companion artifact the user did not ask for.
   • If a deploy step or org setting is a prerequisite, state it inside the one answer file (for guidance) or in a code comment inside the one artifact (for an artifact request) — never as an extra file.

2. For field encryption — read references/encryption-schemes.md to choose the scheme, then load assets/encrypted-field.field-meta.xml as the starting template. Set encryptionScheme to exactly one of the four valid enum values (see the reference). Only Deterministic* schemes are filterable.

   Write the field file at the SFDX source path, not the root. A *.field-meta.xml must live at objects/<ObjectApiName>/fields/<FieldApiName>__c.field-meta.xml (e.g. objects/Patient__c/fields/Diagnosis_Notes__c.field-meta.xml) — the object folder uses the object's API name (Patient__c for a custom object, Contact for a standard one) and the file is named after the field API name. Emitting the file at the repo root, in a flat directory, or under any other folder is a structural miss even when the XML itself is correct.

3. For org-level encryption settings — load assets/PlatformEncryption.settings-meta.xml (deterministic encryption, field-history encryption, MEK permission) or assets/EncryptionKey.settings-meta.xml (Cache-Only, EKM, Data 360, transactional DB, replay detection). Read references/key-models.md before setting any key-model field.

   Name the output file after the Settings member, not the root element, and write it under settings/. A Settings file must be settings/<member>.settings-meta.xml, where <member> is the org's metadata member name — EncryptionKey (root <EncryptionKeySettings>) and PlatformEncryption (root <PlatformEncryptionSettings>). Put it in the settings/ source folder (e.g. settings/EncryptionKey.settings-meta.xml), not the repo root. Naming the key-settings file Encryption.settings-meta.xml or EncryptionKeySettings.settings-meta.xml fails deployment with "The object '…' of type Settings metadata does not exist."

   Cache-Only Keys and replay detection are a one-way dependency, not an auto-enable. You may set enableReplayDetection only after enableCacheOnlyKeys is true; enabling Cache-Only does not turn replay detection on by itself. An org can validly run Cache-Only with replay detection off.

4. For tenant-secret operations (rotate, destroy, BYOK upload, Cache-Only callout setup) — read references/tenant-secret-lifecycle.md. These are UI/REST-only; capture the guidance in the single markdown answer file, not a deployable metadata file.

5. Validate any generated settings XML — run scripts/validate-encryption-metadata.sh with the file path as its argument, and fix anything it reports. It checks the replay-detection dependency and the encryptionScheme enum deterministically.

6. Compare against the worked example — verify a generated EncryptionKeySettings file against examples/cache-only-keys.settings-meta.xml.