PlatformEncryptionSettings in SFDX

Architectural Overview#

PlatformEncryptionSettings is a critical security metadata type governing Salesforce Shield Platform Encryption. While perimeter TLS protects data in transit, Shield Platform Encryption provides natively integrated encryption-at-rest for sensitive customer data stored in the database, search index files, attachments, and event buses.

Managing PlatformEncryptionSettings in source control ensures that cryptographic parameters—such as deterministic encryption support, search index encryption, and event bus encryption—are systematically replicated across development, UAT, and production environments. Enterprise architects rely on this metadata type to fulfill strict regulatory compliance requirements (such as HIPAA, GDPR, PCI-DSS, and FedRAMP) without manual setup drift.

Directory and File Conventions#

In SFDX source format, PlatformEncryptionSettings is stored in the settings/ directory and referenced as Settings:PlatformEncryption.

Key Metadata Fields#

The XML schema of PlatformEncryptionSettings controls platform cryptographic policies:

Declarative XML and Package Manifest Examples#

Below is an enterprise configuration for Shield Platform Encryption:

<?xml version="1.0" encoding="UTF-8"?>
<PlatformEncryptionSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableDeterministicEncryption>true</enableDeterministicEncryption>
    <enableEventBusEncryption>true</enableEventBusEncryption>
    <enableSearchIndexEncryption>true</enableSearchIndexEncryption>
    <isShieldEnabled>true</isShieldEnabled>
</PlatformEncryptionSettings>

Scratch Org Definition Configuration#

When provisioning scratch orgs with Shield Platform Encryption:

{
  "orgName": "Shield Security Scratch Org",
  "edition": "Enterprise",
  "features": ["ShieldPlatformEncryption"],
  "settings": {
    "platformEncryptionSettings": {
      "enableDeterministicEncryption": true,
      "enableSearchIndexEncryption": true,
      "enableEventBusEncryption": true
    }
  }
}

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>PlatformEncryption</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

Manage PlatformEncryptionSettings using sf:

# Retrieve PlatformEncryptionSettings from the target org
sf project retrieve start --metadata Settings:PlatformEncryption

# Deploy PlatformEncryptionSettings to target environment
sf project deploy start --metadata Settings:PlatformEncryption

# Validate settings deployment without saving
sf project deploy validate --metadata Settings:PlatformEncryption

Architect Best Practices and Gotchas#

• Tenant Secret Provisioning: Deploying PlatformEncryptionSettings configures platform policies, but encryption requires an active tenant secret. In automated CI/CD pipelines, generate an initial tenant secret via Tooling API or Setup before applying field-level encryption.
• SOQL Limitations with Probabilistic Encryption: Standard probabilistic encryption generates randomized ciphertext, preventing fields from being used in ORDER BY, GROUP BY, or WHERE statements. Use deterministic encryption (enableDeterministicEncryption: true) when query filtering is mandatory.
• Apex Governor Limits: Decryption happens seamlessly in the platform runtime, but excessive SOQL retrieval of encrypted long text areas can incur CPU and memory serialization overhead.

Frequently asked questions

What does PlatformEncryptionSettings control in Salesforce Shield?

It configures encryption at rest policies for standard and custom fields, search indexes, change data capture streams, and event buses.

Where is PlatformEncryptionSettings located in an SFDX project?

It resides at force-app/main/default/settings/PlatformEncryption.settings-meta.xml and is retrieved using the Settings:PlatformEncryption identifier.

What is the architectural difference between probabilistic and deterministic encryption?

Probabilistic encryption produces unique ciphertexts preventing filtering, while deterministic encryption supports exact match SOQL queries and lookups.

Can PlatformEncryptionSettings be deployed into scratch orgs?

Yes, provided the parent Dev Hub or scratch org definition includes the ShieldPlatformEncryption feature license.