Shield Encryption

Overview

Salesforce Shield Platform Encryption provides encryption at rest for data stored in Salesforce. It operates at the platform level, encrypting data before it is written to disk and decrypting it when authorized users access it.

Shield Encryption is separate from Classic Encryption (which uses Encrypted Text field type and a 128-bit key). Shield uses 256-bit AES encryption with a tenant-specific key hierarchy.

Key Hierarchy

Master Secret (Salesforce HSM)
    |
    +-- Tenant Secret (customer-generated, stored encrypted)
            |
            +-- Data Encryption Key (derived, per-record or per-field type)

• Master Secret -- Managed by Salesforce in Hardware Security Modules (HSMs). Customers cannot access it.
• Tenant Secret -- Generated by the customer. Combined with the Master Secret to derive the Data Encryption Key.
• Data Encryption Key -- Derived key used to encrypt/decrypt actual field values. Never stored; re-derived on each use.

Deterministic vs Probabilistic Encryption

Deterministic Encryption

The same plaintext always produces the same ciphertext. This enables certain query operations.

Supported operations on deterministic fields:

• = and != comparisons in WHERE clauses
• IN clauses
• GROUP BY and ORDER BY
• DISTINCT
• Case-sensitive matching
• Unique value enforcement

Limitations:

• Less secure than probabilistic (frequency analysis is theoretically possible)
• Only available for certain field types

Probabilistic Encryption

Each encryption produces a different ciphertext (uses random initialization vector). More secure but limits query operations.

Supported operations on probabilistic fields:

• Basic read/write
• Exact-match filter on some fields (with deterministic derivation cache)

Not supported on probabilistic fields:

• LIKE operator
• GROUP BY
• ORDER BY
• DISTINCT
• Aggregate functions (SUM, AVG, etc.)
• Formula field references
• Some standard report filters

Decision Matrix

Requirement	Deterministic	Probabilistic
Filter with = in SOQL	Yes	Limited
Use in GROUP BY	Yes	No
Use in ORDER BY	Yes	No
Use LIKE operator	No	No
Maximum security	No	Yes
Formula field reference	Limited	No
Unique enforcement	Yes	No
Report grouping	Yes	No

Rule: Use deterministic encryption when you need to filter or group by the field. Use probabilistic when the field is display-only and maximum security is required.

Encryptable Fields

Standard Fields That Can Be Encrypted

Object	Fields
Account	Name, Description, Phone, Fax, Website, BillingAddress, ShippingAddress
Contact	Name, Email, Phone, MailingAddress, Description
Case	Subject, Description
Lead	Name, Email, Phone, Company, Address
Opportunity	Name, Description, Amount (deterministic only)

Custom Field Types That Support Encryption

• Text
• Text Area
• Text Area (Long)
• Text Area (Rich)
• Email
• Phone
• URL
• Date
• Date/Time

Not encryptable:

• Number (except currency in some contexts)
• Checkbox
• Picklist
• Lookup/Master-Detail
• Formula
• Auto-number

Tenant Secret Management

Generate a Tenant Secret

Setup > Platform Encryption > Key Management > Generate Tenant Secret

Select the type:

• Data in Salesforce -- encrypts standard and custom fields
• Data in Chatter -- encrypts Chatter posts and files
• Data in Files and Attachments -- encrypts files, attachments, and content
• Search Index -- encrypts the search index
• Data in Analytics -- encrypts CRM Analytics data
• Event Bus -- encrypts platform event payloads

Tenant Secret Rotation

Rotate tenant secrets periodically for compliance. Rotation does not re-encrypt existing data immediately.

Rotation process:

1. Generate a new tenant secret for the data type
2. The new secret becomes active for new encryptions
3. Old secrets are marked as Archived (still used to decrypt old data)
4. Run the Background Encryption service to re-encrypt existing data with the new key

Setup > Platform Encryption > Key Management > Generate Tenant Secret
Setup > Platform Encryption > Encryption Statistics > Encrypt Now (sync existing data)

Rules:

• Archived secrets can still decrypt data; do not destroy them unless you want permanent data loss
• Destroying a tenant secret makes all data encrypted with it permanently unreadable
• Run Background Encryption after rotation to re-encrypt with the new key
• Plan rotation during off-peak hours; Background Encryption is resource-intensive

Bring Your Own Key (BYOK)

Upload your own key material instead of having Salesforce generate it.

Setup > Platform Encryption > Key Management > Bring Your Own Key

Upload a 256-bit AES key encrypted with a Salesforce-provided certificate. This gives you control over key material while Salesforce manages the encryption operations.

Cache-Only Keys

Cache-only keys are stored only in memory (Salesforce cache), never persisted to disk. They are used for encrypting external data temporarily stored in Salesforce.

Use cases:

• Data from external systems that must not be stored encrypted at rest in Salesforce
• Transient data that needs field-level encryption during processing
• Compliance scenarios requiring that Salesforce never has a permanent copy of the key

Limitations:

• Data becomes unreadable if the cache-only key expires or is evicted
• Must re-supply the key material when the cache entry expires
• Not suitable for long-term data storage

Encrypted Field Query Limitations

What Works

// Deterministic encryption -- exact match works
List<Contact> contacts = [
    SELECT Id, Name, Email
    FROM Contact
    WHERE Email = 'user@example.com'
    WITH SECURITY_ENFORCED
];

// Deterministic -- GROUP BY works
AggregateResult[] results = [
    SELECT BillingCity, COUNT(Id) cnt
    FROM Account
    GROUP BY BillingCity
];

What Does Not Work

// LIKE is never supported on encrypted fields
// This will throw a runtime error
List<Contact> contacts = [
    SELECT Id, Email
    FROM Contact
    WHERE Email LIKE '%@example.com'
];

// Probabilistic -- GROUP BY fails
// This will throw a runtime error if the field is probabilistic
AggregateResult[] results = [
    SELECT EncryptedField__c, COUNT(Id) cnt
    FROM MyObject__c
    GROUP BY EncryptedField__c
];

Workaround Patterns

// For LIKE-style searches on encrypted fields, use a non-encrypted derived field
// Store a hashed domain for email searches
// Or use Salesforce Search (SOSL) which works on encrypted fields if search index is also encrypted

List<List<Contact>> searchResults = [
    FIND 'example.com' IN EMAIL FIELDS
    RETURNING Contact(Id, Name, Email)
];

Apex Crypto Class

The Crypto class provides encryption, decryption, hashing, and MAC generation for custom encryption needs (separate from Shield Platform Encryption).

Generate an AES Key

Blob key = Crypto.generateAesKey(256); // 128 or 256 bits
// Store this key securely (Named Credential, Protected Custom Metadata, etc.)
// Never hardcode keys in Apex

Encrypt and Decrypt

public class EncryptionService {

    // Encrypt plaintext
    public static Blob encryptData(String plaintext, Blob key) {
        Blob data = Blob.valueOf(plaintext);
        // AES-256-CBC with random IV (prepended to ciphertext)
        Blob encrypted = Crypto.encryptWithManagedIV('AES256', key, data);
        return encrypted;
    }

    // Decrypt ciphertext
    public static String decryptData(Blob ciphertext, Blob key) {
        Blob decrypted = Crypto.decryptWithManagedIV('AES256', key, ciphertext);
        return decrypted.toString();
    }
}

encryptWithManagedIV vs encrypt:

• encryptWithManagedIV -- Salesforce generates and manages the initialization vector (IV). Easier and recommended.
• encrypt -- You provide your own IV. Use when interoperating with external systems that require a specific IV.

Generate HMAC

// Verify data integrity with HMAC
Blob hmacKey = Crypto.generateAesKey(256);
Blob data = Blob.valueOf('sensitive data');
Blob mac = Crypto.generateMac('HmacSHA256', data, hmacKey);

// Verify
Blob expectedMac = Crypto.generateMac('HmacSHA256', data, hmacKey);
Boolean isValid = (mac == expectedMac);

Hashing

// One-way hash (no key, cannot decrypt)
Blob hashedData = Crypto.generateDigest('SHA256', Blob.valueOf('data to hash'));
String hexHash = EncodingUtil.convertToHex(hashedData);

Supported Algorithms

Operation	Algorithms
Encryption	AES128, AES192, AES256
Hashing	MD5, SHA1, SHA256, SHA512
HMAC	HmacSHA1, HmacSHA256, HmacSHA512, HmacMD5
Digital Signature	RSA-SHA1, RSA-SHA256, RSA, ECDSA

Shield Event Monitoring

Shield Event Monitoring tracks user activity for security and compliance auditing.

Key event types:

• Login and logout events
• API calls
• Report exports
• Visualforce page views
• Lightning page views
• URI events
• Content distribution events

Querying Event Logs:

List<EventLogFile> logs = [
    SELECT Id, EventType, LogDate, LogFileLength
    FROM EventLogFile
    WHERE EventType = 'Login'
    AND LogDate = LAST_N_DAYS:7
];

Integration with external SIEM:

# Download event log files via SF CLI
sf data query --query "SELECT Id, EventType, LogFile FROM EventLogFile WHERE EventType='Login' AND LogDate=TODAY" --target-org myOrg --result-format csv

Anti-Patterns

1. Encrypting every field. Encryption has query and performance costs. Only encrypt fields containing sensitive data (PII, PHI, financial data).
2. Using probabilistic encryption on filter fields. If you need to filter by the field, use deterministic encryption.
3. Destroying archived tenant secrets. This permanently destroys all data encrypted with that key. Archive, do not destroy.
4. Hardcoding Crypto keys in Apex. Store keys in Protected Custom Metadata Type or Named Credentials.
5. Using MD5 or SHA1 for security-sensitive hashing. Use SHA256 or SHA512.
6. Not rotating tenant secrets. Establish a rotation schedule per compliance requirements.
7. Ignoring search impact. Encrypted fields are not searchable unless the search index is also encrypted.
8. Not testing with encryption enabled. Tests should run in a sandbox with encryption enabled to catch query errors early.