TenantSecret | Object Reference for Salesforce and Force.com

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 once 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 string Properties Create, Nillable, Update Description The description of the tenant secret.
SecretValue	Type base64 Properties 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.
Status	Type Restricted picklist Properties Filter, Group, Nillable, Restricted picklist, Sort Description The current status of the tenant secret. Values are: ACTIVE Can be used to encrypt and decrypt new or existing data. ARCHIVED Cannot encrypt new data. Can be used to decrypt data previously encrypted with this key when it was active. DESTROYED Cannot 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.
Type	Type Restricted picklist Properties Create, Defaulted 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: 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. SearchIndex—search index files (available in API version 39.0 and later).
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. For example, you can build an automated tenant secret creation and activation solution similar to the following.

Start by creating an Apex class to create the new 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= ‘SearchIndex’;
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.

You can also upload a customer-supplied tenant secret.

Create a certificate that is compatible with customer-supplied (BYOK) tenant secrets. See “Generate a BYOK-Compatible Certificate” in the Platform Encryption REST API Developer Guide.

Then upload your matching tenant secret and tenant secret hash. Include the unique name of the compatible certificate. The tenant secret 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 tenant secret is uploaded.

Here’s an example of how to 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;

You can also export a tenant secret by writing the secret.SecretValue to a file. Here’s an example that uses a tenant secret of the SearchIndex type.

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

Here’s an example of how to 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. Once you destroy a tenant secret, related data is not 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;
3update secret;