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`.
ExternalId	Type string Description This field is reserved for internal use.
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
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'