DataEncryptionKey

The DataEncryptionKey object is part of the Bring Your Own Key (BYOK) feature, which allows users to upload a data encryption key (DEK) using a public key generated by the Salesforce Shield Key Management Service (KMS). Customers create their own DEKs and upload them to Salesforce. Users access this entity via the API to list DEK keys for auditing purposes. They can also programmatically use this object to create the certificate and to upload key material. This object is available in API version 63.0 and later.

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

Field	Details
CreatedBy	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The email address of the user who created the DEK. For example, `user@example.com`.
DataEncryptionKeyCertName	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The name of the certificate whose public key is used to encrypt the DEK during a remote key callout. When you want to create a BYOK-compatible certificate, use this property in a call to create() to name the certificate. You need to know the name to retrieve the certificate later. Specify only the file name. Salesforce will add the .crt extension when it creates the file.
Description	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The user-defined description of the root key.
DoesUseKeyDerivation	Type boolean Properties Create, Defaulted on create, Filter, Group, Sort, Update Description Indicates whether the DEK is intended to be used as part of a derived key (`true`) or not (`false`). See Components Involved in Deriving Keys for information on derived keys. The default value is `false`.
LastModifiedBy	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The email address of the user who most recently modified the key. For example, `user@example.com`.
RootKeyIdentifier	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The unique key identifier assigned by Salesforce to the root key used to create the DEK.
RootKeyKmsIdentifier	Type string Properties Create, Filter, Nillable, Sort, Update Description The unique key identifier from the external KMS, such as an AWS Amazon Resource Name (ARN). For example, `arn:aws:kms:us-west-2:123456789000:key/123ab456-7cd8-9012-3e4f-5gh678i901j2`
SecretValue	Type textarea Properties Create, Nillable, Update Description The encrypted 256-bit secret value encoded in base64.
SessionToken	Type textarea Properties Create, Nillable, Update Description Contains the token for the session that was active when the DEK was last wrapped. If the session is inactive, a new certificate is required in order to transmit the DEK.
Source	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The source of the encryption key material. Values are: `AWS`—A tenant secret or DEK fetched from the Amazon Key Management Service DEKs with a Source value of AWS are listed as Fetched on the Key Management page in Setup. `Salesforce`—A Salesforce-generated DEK.
Status	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The status of the key. Possible values are: `Activation Pending`—Salesforce is waiting for confirmation of a valid key policy in the external key store. `Active`—Can be used to encrypt new DEKs and decrypt existing DEKs. `Archived`—Can’t encrypt new DEKs. Can be used to decrypt previously created DEKs. `Canceled`—Root key activation canceled by a user. `Inactive`—The root key, and the DEKs that it encrypts, are inaccessible. Inaccessible DEKs can’t be used to decrypt data, which renders that data also inaccessible.
Type	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The type of DEK. This value appears in the Type picklist: Search Index—search index files. For Hyperforce orgs on API version 63.0 and later, create secrets of type SearchIndex using the DataEncryptionKey object. For Hyperforce orgs on API versions 62.0 and earlier, and for all non-Hyperforce orgs, create secrets of type SearchIndex using the TenantSecret object. You also specify a type of SearchIndex when you are creating a BYOK-compatible certificate using the DataEncryptionKey object.
Version	Type int Properties Create, Filter, Group, Nillable, Sort, Update Description The version number of this secret. The version number is unique within your org.

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:
1"SecretValue":"<b64 string>" 2"SessionToken":"<session token string>" 3"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.

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

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.

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

Download your Certificate

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

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3   <types>
4      <members>DataEncryptionKeyCertName</members>
5      <name>Certificate</name>
6   </types>
7   <version>65.0</version>
8</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).

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

Describe a DataEncryptionKey with describe()

To get information about the DataEncryptionKey sObject, use describe.

1curl --location 'https://DOMAIN.my.salesforce.com/services/data/v62.0/sobjects/'\ 
2                     DataEncryptionKey/describe'
3                     --header 'Content-Type: application/json' \
4                     --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

1{
2   "totalSize": (COUNT),
3   "done": true,
4   "records": [
5      {
6         "attributes": {
7         "type": "DataEncryptionKey",
8         "url": "/services/data/v63.0/sobjects/DataEncryptionKey/(ID)"
9         },
10         ATTRIBUTE LIST
11      },
12   ]

On error, the response is similar to

1[
2   {
3      "message": "ERROR MESSAGE",
4      "errorCode": "ERROR CODE"
5   }
6]

Object Reference for the Salesforce Platform