Troubleshooting Bring Your Own Key
Read these frequently asked questions to help you troubleshoot any problems that arise with Shield Platform Encryption’s Bring Your Own Key service.
Required Editions
| Available in both Salesforce Classic (not available in all orgs) and Lightning Experience. |
| Available in: Enterprise, Performance, and Unlimited Editions with the Salesforce Shield or Shield Platform Encryption licenses. |
| Available for free in Developer Edition. |
- I’m trying to use one of the scripts you provide, but it doesn’t run.
- Make sure that you’re running the right script for your operating system. If you’re
working on a Windows machine, you can install a Linux emulator and use the Linux script.
These issues can also prevent the script from running:
- You don’t have write permission in the folder you’re trying to run the script from. Try running the script from a folder that you have write permission for.
- The certificate that the script references is missing. Make sure you’ve properly generated the certificate.
- The certificate is missing or isn’t being referenced by the correct name. Make sure you’ve entered the correct file name for your certificate in the script.
- I want to use one of the scripts you provide, but I also want to use my own random number generator.
- The script we provide uses a random number generator to create a random value that is
then used as your tenant secret. If you want to use a different generator, replace
head -c 32 /dev/random | tr '\n' =(or, in the Mac version,head -c 32 /dev/random > $PLAINTEXT_SECRET) with a command that generates a random number using your preferred generator.
Note We recommend /dev/random over /dev/urandom due to its truer random byte generation process. - What if I want to use my own hashing process to hash my tenant secret?
- No problem. Make sure that the result meets these requirements:
- Uses an SHA-256 algorithm.
- Results in a base64 encoded hashed tenant secret.
- Generates the hash of the random number BEFORE encrypting it.
- How should I encrypt my tenant secret before I upload it to Salesforce?
- If you’re using the script provided, the encryption process is taken care of. If you don’t use the script, specify the correct padding scheme when you encrypt your tenant secret. Check the padding requirements in our example scripts. Make sure the resulting encrypted tenant secret and hashed tenant secret files are encoded using base64. If either of these criteria aren’t met, you can’t upload your tenant secret.
- If you choose to not use one of the scripts provided, use the closest script as a model.
- My wrapped DEK isn’t accepted. What do I do?
- Make sure that you wrap your root-key generated DEKs (such as for Search Index Encryption) with the public key from the BYOK-compatible certificate that you generated by using the SHA512 padding algorithm. You can try wrapping your other BYOK tenant secrets using the SHA1 algorithm.
- My certificate is about to expire. What do I do?
- Certificates you use just for uploading secrets, such as for BYOK, only need to be valid when you upload the key material. But for Cache-only Keys your certificate is actively used and must remain valid in order for Salesforce to unwrap the content encryption key (CEK) that wraps the underlying data encryption key (DEK) material. An expired certificate will prevent your Cache-only Key from being used.
Important Salesforce is complying with an industry-wide reduction of the time to expiration for CA certificates. Please read the information in Certificates in Salesforce and plan accordingly. - My session token or import token has expired. What do I do?
- You can download the certificate you already created. You'll get a new session token file with it. On the Bring Your Own Key page in Setup, click the Download Certificate & Token button. Extract the session token file from the .zip file that downloads. Then upload the session token along with your wrapped tenant secret.
- I can’t upload my Encrypted tenant secret and Hashed tenant secret.
- A handful of errors can prevent your files from uploading. Use the chart to make that
sure your tenant secrets and certificates are in order.
Possible cause Solution Your files were generated with an expired certificate. Check the date on your certificate. If it has expired, you can renew your certificate or use another one. Your certificate isn’t active, or isn’t a valid Bring Your Own Key certificate. Ensure that your certificate settings are compatible with the Bring Your Own Key feature. Under the Certificate and Key Edit section of the Certificates page, select a 4096-bit certificate size, disable Exportable Private Key, and enable Platform Encryption. Read more about expired certificates in the “My certificate is about to expire” section. You haven’t attached both the encrypted tenant secret and the hashed tenant secret. Make sure that you attach both the encrypted tenant secret and the hashed tenant secret. Both of these files should have a .b64 suffix. Your tenant secret or hashed tenant secret wasn’t generated properly. Several problems can cause this error. Usually, the tenant secret or hashed tenant secret wasn't generated using the correct SSL parameters. If you’re using OpenSSL, you can refer to the script for an example of the correct parameters you should use to generate and hash your tenant secret. If you’re using a library other than OpenSSL, check that library's support page for help with finding the correct parameters to both generate and hash your tenant secret.
Still stuck? Contact your Salesforce account executive. They'll put you in touch with someone at Salesforce who can help.
- I'm having trouble uploading my certificates.
- To be uploaded successfully, a certificate must be in a valid JKS format. Review the requirements and common problems on Export and Import Certificates with a Keystore.
- I’m having trouble with my BYOK for Database Encryption.
- Database Encryption manages its key material differently.
- You can only upload customer-supplied tenant secrets on the Key Management page in Setup. API support isn’t available.
- You can’t generate BYOK-compatible certificates via the API.
- If you encounter these errors when attempting to upload key material, here are some
potential fixes.
Error Tips for Fixing the Problem Upload two files: your wrapped tenant secret and the session token that came with the certificate you used to wrap your tenant secret. Make sure that you select both of the required files: the encrypted tenant secret file and session token file. Then click Upload. This session token isn’t valid. Download another copy on this page, and try again. If you still can’t upload it, contact Salesforce Customer Support. On the Bring Your Own Database Encryption Key page in Setup, click the Download Certificate & Token button. Extract the session token file from the .zip file that downloads. Then upload the session token along with your wrapped tenant secret. Your tenant secret must be an AES 256-bit key wrapped with an AES 256-bit ephemeral key, all wrapped with the public key from the certificate downloaded from this page. If your tenant secret meets these requirements but you can’t upload it, contact Salesforce Customer Support. Make sure that your tenant secret and ephemeral key are the right size. Double-check that you encrypted them with the public key from the current certificate listed under the Manage Certificates section on the Bring Your Own Database Encryption Key page. We can’t authenticate your tenant secret with the right session ID. Try again later, or contact Salesforce Customer Support. Sometimes Salesforce can’t authenticate your session ID, which prevents us from matching your session with the session token you upload. The issue is usually caused by an internal process that resolves with time. Try uploading your wrapped tenant secret and session token later. You can’t upload customer-supplied tenant secrets for Database Encryption through the API. BYOK for Database Encryption is only available through Setup. Upload your customer-supplied tenant secret on the Bring Your Own Database Encryption Key page. Another certificate already uses this label. Enter a unique label. Each certificate must have a unique label. You can check the Manage Certificates & Keys page in Setup to see your existing certificates. Hmm, something went wrong. Try again later, or contact Salesforce Customer Support. Try your action again later, or contact your account executive for help troubleshooting in your pilot trial org. - I'm having problems uploading my BYOK for Data 360
- If you encounter these errors when attempting to upload key material, here are some potential fixes.
Error Tips for Fixing the Problem Data Cloud root key isn't ready for upload You may encounter this status when attempting to upload your Data 360 BYOK. Salesforce experienced an issue preparing your new Data Cloud root key. Its status is marked as Pending so that you can try again. Navigate to the Key Management page in Setup. In the Root Key Inventory, on the Data Cloud tab, click Retry. Legitimate contents but expired cert key. The certificate used is either invalid or has expired. Please download the certificate and token again. Valid token, but invalid wrapped key. The key uploaded is invalid. Please use the guidelines in the helper script to create and wrap your import key and try again. - I can't synchronize all of the data in my transactional database data with my new tenant secret.
- Due to how Database Encryption encrypts data at the fragment level, a new tenant secret is used for encrypting data as it is needed by your users. Previously encrypted data can always be decrypted with the earlier DEK. This is one reason that Database Encryption does not support destroying keys.
- I’m still having problems with my key. Who should I talk to?
- If you still have questions, contact your account executive. They’ll put you in touch with a support team specific to this feature.
See Also
Did this article solve your issue?
Let us know so we can improve!
