DataEncryptionKey

DEKs are used to encrypt and decrypt data. They reside in either the Salesforce database or in an external KMS. They’re created by root keys, and when persisted, wrapped by root keys as well.

Supported Calls

create(), describeSObjects(), query(), queryAll()

Special Access Rules

This object is available as part of the Shield and Salesforce Platform Encryption add-on subscriptions.

Fields

Usage

Four functions are available: describe(),create(), query() and queryAll().

• Use create() to create BYOK-compatible certificates and DEKs.
• Use query() or queryAll() to list one or all of your DEKs.
• Use describe() to get information abut the DataEncryptionKey object.

You use create() and queryAll() together to upload a Search Index Encryption DEK. Check the Examples section for how to do each of these steps.

• Create a BYOK-compatible certificate with create(). This will create a temporary DEK to contain the certificate reference. Specify a Type of Search Index and a name for the certificate file.
• Use queryAll() to list your DEKs. The temporary DEK will include the name of your certificate file in the DataEncryptionKeyCertName attribute. It will also include a session token in the sessionToken attribute. Save this value for later.
• Downlad the certificate using the metadata object API. Specify Certificate for the object name node, and the DataEncryptionKeyCertName for the members node. The certificate file will be in the zip file returned by the metadata object API.
• Run the BYOK Search Index Encryption script to generate the payload.bin file which contains the plaintext of your new DEK. Use the certificate file you created when you run the script. Alternatively, generate a key using a method of your choice. It must meet the specifications outlined in Bring Your Own Key Overview.
• Generate a b64 string from the contents of the payload.bin file.
• Run the DataEncryptionKey.create() method again, this time with the the b64 string and the session token. Specify:

  "SecretValue":"<b64 string>"
  "SessionToken":"<session token string>"
  "Type":"SearchIndex"

  With success, the temporary DEK is replaced by the uploaded secret. The certificate is deleted, and the session token eventually expires. A call to queryAll() will show the new DEK. The DEK will also appear on the Search Index Encryption Key Management page.

Examples

Use your preferred developer environment to run the examples. Use the Salesforce developer Introduction to REST API for basic information on making REST calls into Salesforce. Also, Introducing the Salesforce Shield Platform Encryption REST API gives you starter information on using REST to work with Shield Platform Encryption.

Create a BYOK-compatible certificate with create()

To create a BYOK-compatible certificate, use a POST method to create an sObject of type DataEncryptionKey. Specify a Type of search index (case insensitive), and an appropriate string value for DataEncryptionKeyCertName. You need to name the certificate to retrieve it later. Specify just the name. Salesforce will add the .crt extension to the file.

curl --location 'https://DOMAIN.my.salesforce.com/services/data/v62.0/sobjects/'\ 
                     DataEncryptionKey/create'
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer TOKEN' \
     --data '{
              "Type": "search index",
              "DataEncryptionKeyCertName": "my-byok-compatible-cert"
            }'

List all DEKs with queryAll()

To retrieve DEKs, use query or queryAll on the DataEncryptionKey sObject. You must specify a limit for the query. All DEKs are retrieved, including archived DEKs. You use queryAll to get the session token.

curl --location 'https://DOMAIN.my.salesforce.com/services/data/v63.0/queryAll/?q=SELECT+FIELDS(ALL)+FROM+DataEncryptionKey+LIMIT+10' \
                     --header 'Authorization: Bearer TOKEN'

Download your Certificate

Retrieve the certificate using Metadata API. object to download your new certificate.

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

Your certificate will be contained in the cert folder.

Create a DEK with create()

To create the final DEK, use a POST method to create an sObject of type DataEncryptionKey. Specify a Type of search index (case insensitive).

curl --location 'https://DOMAIN.my.salesforce.com/services/data/v63.0/sobjects/DataEncryptionKey/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "SecretValue":"b64-secret"
    "SessionToken":"session-token value"
    "Type": "search index"
}'

Describe a DataEncryptionKey with describe()

To get information about the DataEncryptionKey sObject, use describe.

curl --location 'https://DOMAIN.my.salesforce.com/services/data/v62.0/sobjects/'\ 
                     DataEncryptionKey/describe'
                     --header 'Content-Type: application/json' \
                     --header 'Authorization: Bearer TOKEN'

On success, the response is the full JSON description of the DataEncryptionKey sObject.

Return Values for Create()

The response for creating a certificate or DEK are the same. On success, the response is be similar to

{
   "totalSize": (COUNT),
   "done": true,
   "records": [
      {
         "attributes": {
         "type": "DataEncryptionKey",
         "url": "/services/data/v63.0/sobjects/DataEncryptionKey/(ID)"
         },
         ATTRIBUTE LIST
      },
   ]               

On error, the response is similar to

[
   {
      "message": "ERROR MESSAGE",
      "errorCode": "ERROR CODE"
   }
]