TenantSecret

You can rotate tenant secrets of the Data type once every four hours in a sandbox org or every 24 hours in production orgs. You can rotate tenant secrets of the SearchIndex type one time every seven days.

This information is about Shield Platform Encryption and not Classic Encryption.

Note

Supported Calls

create(), query(), retrieve(), update()

Fields

Field Name	Details
Description	Type textarea Properties Create, Nillable, Update Description The description of the tenant secret.
KeyDerivationMode	Type picklist Properties Create, Filter, Group, Restricted picklist, Sort Description The key derivation mode applied to customer-supplied key material. Modes are: PBKDF2 The customer-supplied key material is used by the Shield KMS to create a derived data encryption key. NONE The customer-supplied key material is used by the Shield KMS as the final data encryption key to directly encrypt and decrypt data. Available in API version 43.0 and later.
RemoteKeyCertificate	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The name of the certificate whose public key is used to encrypt the SecretValue during a remote key callout. Available in API version 45.0 and later.
RemoteKeyIdentifier	Type string Properties Create, Filter, Group, Nillable, Sort Description A unique key identifier for key material fetched from a remote key service. Available in API version 45.0 and later.
RemoteKeyServiceID	Type reference Properties Create, Filter, Group, Nillable, Sort, Update Description The named credential used to fetch remote key material from a remote key service. Available in API version 45.0 and later.
SecretValue	Type base64 Properties Create, Nillable, Update Description The encrypted 256-bit secret value encoded in base64.
SecretValueCertificate	Type string Properties Create, Filter, Group, Nillable, Sort, Update Description The certificate needed to upload a customer-supplied tenant secret. Each certificate has a unique name.
SecretValueHash	Type base64 Properties Create Description The matching tenant secret hash for an uploaded customer-supplied tenant secret.
Source	Type picklist Properties Create, Default on create, Filter, Group, Restricted picklist, Sort Description The source of the encryption key material. Values are: HSM A Salesforce-generated tenant secret. Uploaded A customer-supplied tenant secret or data encryption key. Remote A tenant secret or data encryption key fetched from a key service outside of Salesforce. Available in API version 44.0 and later.Tenant secrets with a Source value of Remote are listed as Fetched on the Key Management page in Setup. Available in API version 43.0 and later.
Status	Type picklist Properties Filter, Group, Nillable, Restricted picklist, Sort, Update Description The status of the tenant secret. Values are: Active Can be used to encrypt and decrypt new or existing data. Archived Can’t encrypt new data. Can be used to decrypt data previously encrypted with this key when it was active. Destroyed Can’t encrypt or decrypt data. Data encrypted with this key when it was active can no longer be decrypted. Files and attachments encrypted with this key can no longer be downloaded. You can update the Status field through the API in versions 44.0 or later.
Type	Type picklist Properties Create, Default on create, Filter, Group, Restricted picklist, Sort Description The type of tenant secret. The Type field is available in API version 39.0 and later. The following values appear in the Type picklist: Analytics—CRM Analytics data (available in API version 39.0 and later). Data—data stored in the Salesforce database. Includes data in encrypted fields, files, and attachments but not search index files. Tenant secrets created in API version 34.0 and later default to the Data type. Database—transactional database including standard and custom fields, metadata, and Apex (available in API version 62.0 and later). DeterministicData—data stored in the Salesforce database. Includes data in encrypted fields, files, and attachments, but not search index files (available in API version 39.0 and later). EventBus—Change Data Capture event data (available in API version 43.0 and later). SearchIndex—search index files (available in API version 39.0 and later). For Hyperforce orgs on API version 63.0 and later, create secrets of type SearchIndex with the DataEncryptionKey object. For Hyperforce orgs on API version 62.0 and earlier, and for all non-Hyperforce orgs, create secrets of type SearchIndex with the TenantSecret object.
Version	Type int Properties Filter, Group, idLookup, Sort Description The version number of this secret. The version number is unique within your org.

Usage

Use this object to create or update an org-specific tenant secret or customer-supplied key material.

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, the video How To Use Salesforce APIs Collection With Postman by Sudipta Deb provides step by step instructions on getting started using REST with Salesforce.

Example 1:

Build an automated tenant secret creation and activation solution similar to the following.

Start by creating an Apex class to create the tenant secret. Specify the value of the tenant secret to encrypt data of a particular type.

1global class CreateNewSecret implements Schedulable {
2   global void execute(SchedulableContext SC) {
3      TenantSecret secret = new TenantSecret ();
4      secret.description = 'Created new secret from scheduled job';
5      secret.type= 'Database';
6      insert secret;
7   }
8}

Type is available in API version 39.0 and later. Type is optional; all tenant secrets default to the Data type.

Note

Schedule the Apex class to run at the specified interval.

This Apex code only needs to be run a single time to schedule the job. This code runs the job every 90 days.

1CreateNewSecret secret = new CreateNewSecret();
2String schedule = '0 0 0 1 JAN,APR,JUL,OCT ?';
3String jobID = system.schedule('Automated secret creation and activation', schedule, secret);

Validate that the job is scheduled.
Validate that tenant secrets are created after the job is run.

Example 2

Upload a customer-supplied tenant secret.

Create a certificate that’s compatible with customer-supplied key material. See Generate a BYOK-Compatible Certificate in Salesforce Help.

Then upload your matching key material and key material hash. Include the unique name of the compatible certificate. The key material is uploaded in encrypted form.

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

You can use this script to generate a customer-supplied tenant secret and tenant secret hash.

Validate that the key material is uploaded.

Example 3

Opt out of key derivation on a key-by-key basis when you upload key material. When you upload your key material, specify 'Source':Uploaded and 'KeyDerivationMode':'NONE', and set non-null values for the SecretValueCertificate, SecretValue, and SecretValueHash.

Example 4

Import a tenant secret of the Data type.

1TenantSecret secret = [SELECT Id FROM TenantSecret WHERE Type = 'Data' AND Version = 2];
2secret.SecretValue = "<previously_exported_secret_as_a_String>";
3update secret;

Example 5

Export a tenant secret by writing the secret.SecretValue to a file. Here’s an example that uses a tenant secret of the Data type.

1TenantSecret secret = [SELECT SecretValue FROM TenantSecret WHERE Type = 'Data' AND Version = 2];
2secret.SecretValue =...;
3update secret;

Example 6

Destroy a tenant secret of the Data type.

Your tenant secret is unique to your organization and to the specific data to which it applies. When you destroy a tenant secret, related data isn’t accessible unless you previously exported the key and then import the key back into Salesforce.

Warning

1TenantSecret secret = [SELECT Id FROM TenantSecret WHERE Type = 'Data' AND Version = 2];
2secret.SecretValue = NULL;
3secret.Status = Destroyed;
4update secret;

Example 7

Change the Status of a tenant secret from Archived to Destroyed. Include the SecretValue and new tenant secret Status.

1TenantSecret secret = [SELECT Id FROM TenantSecret WHERE Type = 'Data' AND Version = 2];
2secret.Status = Destroyed;
3update secret;

Cache-Only Key Service customers can change the Status of cache-only key tenant secrets. For example, reactivate a cache-only key by changing its Status from Destroyed to Active.

Example 8

Create a callout connection that fetches a cache-only key tenant secret from a key service outside of Salesforce.

Make sure that your org has at least one active Data in Salesforce key, either Salesforce-generated or customer-supplied. Then turn on Allow Cache-Only Keys with BYOK from the Advanced Settings page in Setup.
Create a certificate that’s compatible with customer-supplied key material. See Generate a BYOK-Compatible Certificate in Salesforce Help.
Create and assemble your key material.
Create a named credential to serve as your authenticated callout mechanism. You can define your named credential through Setup or directly with Apex. Specify a BYOK-compatible certificate and an HTTPS endpoint.
Configure the connection to your remote key service. This connection uses a named credential and its associated certificate to fetch a specified cache-only key tenant secret.
1remote_params = { 'Source': 'Remote', 2'RemoteKeyIdentifier': ..., 3'RemoteKeyServiceId': ..., 4'RemoteKeyCertificate': ...} 5 6sf.TenantSecret.create(remote_params)

Object Reference for the Salesforce Platform