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 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()

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.
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.
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

Three functions are available: describeSObjects(),create(), and query()

Describe DataEncryptionKey with describeSObjects()

To get information about the ExternalEncryptionRootKey sObject, use describe.

1curl --location 'https://DOMAIN.my.salesforce.com/services/data/v62.0/sobjects/'\ 
2DataEncryptionKey/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.

Create a DEK with create()

To create a 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' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer TOKEN' \
4--data '{
5    "Type": "search index"
6}'

On success, the response is be similar to

1{
2  "errors" : [ ],
3  "success" : true
4}

On error, the response is similar to

1"errors" : [
2  // Example of one error object
3  {
4    "statusCode" : "MALFORMED_ID",
5    "message" : "Contact ID: id value of incorrect type: 001xx000003DGb2999",
6    "fields" : [
7      "Id"
8     ]
9  },
10  //Second error object,
11  //Third error object
12]

List DEKs with query()

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.

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'

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        },

On error, the response is similar to

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

Upload a DEK

To upload a data encryption key generated outside of Salesforce, first create a certificate that’s compatible with customer-supplied key material. See Generate a BYOK-Compatible Certificate in Salesforce Help.

Retrieve the DataEncryptionKey.SessionToken value with a list query on the DEK. A new temporary DEK is created. The session token is displayed under the sessionToken column.

Retrieve the BYOK-compatible certificate that you created for your key.

Generate a data encryption key. You can use this script to generate a customer-supplied data encryption key. Alternatively, generate a key using a method of your choice. It must meet the specifications outlined in Bring Your Own Key Overview.

Upload your generated SecretValue and the session token associated with your certificate. Include the unique name of the compatible certificate. The key material is uploaded in encrypted form.

1DataEncryptionKey secret = new DataEncryptionKey ();
2      secret.description = 'New uploaded secret';
3      secret.type= 'Search Index';
4      secret.SecretValue = ...
5      EncodingUtil.base64Decode('...');;
6      secret.SecretValueCertificate = ...;
7      secret.SecretValueHash = ...
8      EncodingUtil.base64Decode('...');
9      insert secret;

To validate that the data encryption key is uploaded, retrieve a list of all DEKs using query or queryAll on the DataEncryptionKey object.

Object Reference for the Salesforce Platform

DataEncryptionKey

Supported Calls

Special Access Rules

Fields

Usage