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 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
serves as your tenant secret. 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 use one of the scripts provided, the encryption process is taken care of. If you don’t use the provided scripts, 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 your key doesn’t meet either of these criteria, you can’t upload it.
- If you choose not to use one of the scripts provided, use the closest script as a model.
- My wrapped DEK wasn’t accepted. What do I do?
- Make sure that you wrap your root-key generated DEK with the public key from the BYOK-compatible certificate. Make sure that you generated your certificate 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 that you use just for uploading secrets, such as for BYOK, only need to be valid when you upload the key material. The Cache-Only Key service requires active, valid certificates. Salesforce uses these certificates to unwrap the content encryption key (CEK) that wraps the underlying data encryption key (DEK) material. An expired certificate prevents the service from accessing your cache-only key.
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 created. You 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 sure
that 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. Make sure 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, turn off Exportable Private Key, and turn on 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 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 use OpenSSL, use the Salesforce-provided script as an example of the correct parameters for generating and hashing your tenant secret. If you use a library other than OpenSSL, check that library's support page for the required parameters for generating and hashing 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.
- Your 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 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 root key
- If you encounter these errors when attempting to upload a root key, here are some
potential fixes.
Error Tips for Fixing the problem {Data Category}root key isn't ready for uploadSalesforce experienced an issue preparing your new root key. Its status changes to Pending so that you can try again. Go to the Key Management page in Setup. In the Root Key Inventory, select the tab for the data category you want to encrypt. Then click Retry. Legitimate contents but expired cert key. The certificate used is either invalid or has expired. Download the certificate and token again. Valid token, but invalid wrapped key. The key uploaded is invalid. Follow the guidelines in the helper script to create and wrap your import key. Then try again. - I can't synchronize all of the data in my transactional database data with my new tenant secret.
- Database Encryption doesn’t support destroying keys. Due to how Database Encryption encrypts data at the fragment level, Salesforce generates a new tenant secret for encrypting data as needed. Previously encrypted data can always be decrypted with the earlier tenant secret.
- I’m still having problems with my key. How do I get help?
- 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!
