Cache-Only is the simple Node js project that provides APIs for Salesforce Platform Encryption Cache-Only keys.
Following are the APIs exposed
This API just provides Readme document as response.
This API is used to fetch key material based on Key Id. This is the API which Salesforce will call for fetching Cache-only keys. Please note there are only 4 pre-generated Keys and newly generated keys are not stored anywhere in this App.
The 4 pregenerated and stored key ids are with these key ids:
pdo25-byok-cert-dec24-1
pdo25-byok-cert-dec24-2
pdo25-byok-cert-dec24-3
pdo25-byok-cert-dec24-4
{
"kid": "pdo25-byok-cert-dec24-1",
"jwe": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJraWQiOiJwZG8yNS1ieW9rLWNlcnQtZGVjMjQtMSJ9.iLE7FoTl2OjMRPPXhTFbOAkxVQ9SqIODaFIzYRxN1I2Vtf1TH_C78KQXQS6ZDauKPqvccGr8AWu-Mu-I0TZsgMKKQl_yiUeXar3uryFJ5WcbSuYtfz9OxWTUnIX_977v_cwDVNv8Gnce3Oz2MIY0TUmdTSLww7WQEU9ku38eWaS1et5x9UCotT8O0CtABJ4om4dcemmemvLcwA4cl9lVjOQ_3HATld1OkqE-dlonV3Shtx982FIlnxLzrMW8oenljYEsR_RXsutWDEmcHnuvqlsP0CdJWCWP-WmSKkGHo9fBQs27N6-7gVN_oV-jTnLiT4ULKgaysgDLZiIs8lN1L8PCLOqer-Ug6GHFq8RYmq61R5cVGQAHjOlyFQUWysxBuULtuJxra01S89SmEVrrmUG-o_-o_3y4p30r-AjC6al6pmH09xB1zw5rEqGEtA8jSZK_VLqA0HTzZaTF8iVPQHanxxVT_tLOr4Yjw9zxdC7T9e7jQ2AHoemBxHVyf2A4LkEwwPPbJSiTl5vO22g_4ow5CvN6FzmklOWz2086eMuEitlXf9Jv6aw9FpqrxFzZsaY6JmEMj8kqSvSMDYm-sLVI_YBISlbHIZbGbkQyy_c0xBzO0if5PJWmmih-uMS2AZI27GwnqkEC_SOYEpsZJ007kHfFscZNIjur2F6ge-M.Y7P6OVuui_sQ3aTo.Q-iM1YzFrPL3GsMGOQrXZvzk682LjOWusv6cMxw6CPY.pfThBXz8GjcdPwSJEz8UPw"
}
This API is used to generate new key material based on Key Id. Please note that newly generated keys are not stored anywhere in this App.
POST /generate
"kid" = "pdo25-byok-cert-dec24-1"
"cert" = "-----BEGIN CERTIFICATE-----
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
-----END CERTIFICATE-----"
{
"kid": "pdo25-byok-cert-dec24-4",
"jwe": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0.PXI17Plh22MC96YXkfvrsOo797Pa8PJnUjhUeOAFqKrCeY9zQzIR4wrJ3d8UzAEPeN8JBNGtTObCbEzt8BONZSD0D1-FA7ia8QLQHBPR2Z87TKAfPZlJWj38jbwmfm-TG7aCoqSgU-iQ5uFxT5iwhx3urjvQNNRfpk0sbGNC2eM5LhqU8YVJFkodlqAaLtG7G7OpFZAL3M4xVKpv7BUgiDhpY5-9ghCkul7C0kUL1tio1UO0OZ6510RVKvgepWM0mzthCvpwXCAFTfizBjgiRbie49BTROvaCJlA6DMMmrzXhfJ7ij2W7Io0XHZoimQq5o6GbuRwlbpJEIUR6zLmueOT1Swadu8kuTYviiWQuEcdt9zl_MkjEtAnaYc2nH9P4HfZUPGJgA0D5YMTVddncfqJmCym4bogJu_AjGCJSZjEnR65f8xtW_FDFDwWFwpSK5yFhO6bIvzIiD3hp8K0Sqk96PvW42T7KdcflxjmMLGpIRtbJDf35srom7aRGhEyl5kQGUCKK2d0dABc5bQocVrRbOi4QlJdik4iAvNpaRrFdR9oypzzHqrO38YHtt0jyD5xV12YebFxavZe_d_qsO5Fa8wwziCoPi1bEq9AH7QWDgmvCan87U17rzg9vbFpaTYOU60E-iriQH4HAqqwSbB6gGG5H5UtFCTh67JnqqQ.yGHi7M_6b2UbTkJs.wMm7oHYj4myXMdsVQGG0JaTP285VDXoYdP36zCHvlfQ.FdLFpWHV_pAd1T1RNFX3zg"
}
For latest help article please refer: https://help.salesforce.com/s/articleView?id=sf.securitypebyokcache.htm&language=enUS&type=5
Procure "Shield - Platform Encryption" and "Cache-Only Keys for Platform Encryption" Addon
Both are two seperate SKUs and are not include Out of the Box with Salesforce Editions. Shield - Platform Encryption provide BYOK capabilities, but to enable KMS and cache-only Keys additional addon "Cache-Only Keys for Platform Encryption" is required.
Enable Cache-Only Key
Login to your Salesforce Org and go to Setup and then Encryption Settings. Scroll down to "Allow Cache-Only Keys" under "Advanced Encryption Settings" and click on toggle button to enable Cache-Only Keys.
Setup > Platform Encryption > Encryption Settings > "Allow Cache-Only Keys" under "Advanced Encryption Settings"
If you can not find Platform Encryption in Setup, then most likely "Shield - Platform Encryption" license is not enabled. If "Allow Cache-Only Keys" option is disabled or hidden, then most likely "Cache-Only Keys for Platform Encryption" is not enabled. If you have procurred both addons and trying in Sandbox, then do "Match Production License" in Sandbox.
Generate Tenant Secret
Navigate to Setup > Platform Encryption > Key Management and click "Generate Tenant Secret" button under "Fields and Files (Probabilitistic)" or Fields (Deterministic)". Please note that Cach-Only key does not work for "Search Index" or "Event Bus" encryption.
Setup > Platform Encryption > Key Management and click "Generate Tenant Secret" button
Prepare your Key Service
Make sure you Key Service is up and running and publically accessible for the next steps.
Create Named Credentials
In order to make callout from Salesforce to you Key Service, Salesforce will rely on Named Credentials for authorization. Follow the steps mentioned in this article to create named credential to you Key Service.
Please note:
I have noticed that only legacy Named Credentials are listed when providing Cache-Only Keys (Step 8 below). This might be due to configurations in my org, since official documentation does not mention it. If you face similar challenge, please try with Legacy Named Credentials.
Cache-Only Key integration will make API call like this: callout:<named_credential>/<key-id>
Therefore, please make sure you include required path in the named credential. For example; if your Key Service API call for getting Key is like this: https://my-kms.domain.com/getkey/:keyid then your named credential URL should be; https://my-kms.domain.com/getkey/
You can test your named credential by using this piece of code.
String endPoint = 'callout:<named-credential>/<keyid>'; //replace <named-credential> with named credential name and <keyid> with Key Id
HttpRequest request = new HttpRequest();
request.setMethod('GET');
request.setEndpoint(endPoint);
HttpResponse response = (new Http()).send(request);
System.debug('Response: ' + response); //Response Code should be 200
System.debug('Body: ' + response.getBody()); //Body should be something like; {"kid": "passed key id","jwe": "key material"}
Setup > Platform Encryption > Key Management and click "Bring Your Own Key" button
On Bring Your Own Key Page, click on "Create Self-Signed Certificate", provide Label and Unique Name 'without any spaces' and click Save. Please note:
Prepare Key Material
There are certain specifications and steps required to generate key material that is compatible with cache-only keys, these are explained in detail in this article. In nutshell, steps include generating 256 AES Key and taking Public Key from the Certificate and using JWE compact serialization to generate Key material.
Code in this project follow these specifications and you can just call generate API as mentioned above to generate a new key material.
Integrate KMS for BYOK
Navigate to Setup > Platform Encryption > Key Management and click "Bring Your Own Key" button under "Fields and Files (Probabilitistic)" or Fields (Deterministic)". Please note that Cach-Only key does not work for "Search Index" or "Event Bus" encryption.
Setup > Platform Encryption > Key Management and click "Bring Your Own Key" button
On Bring Your Own Key Page, select "Use a Cache-Only Key", provide Key Id and select Named Credential created earlier for Key Service and then click on Save. Process will take some time and it will appear as if nothing is happening. Please be patient and after completion you will start seeing new Key under "Fields and Files (Probabilitistic)" or Fields (Deterministic)".
Please note:
Start using new Key
Once new key is upload you can see encryption status under Setup > Platform Encryption > Encryption Statistics. It will require "Sync" to re-encrypt old data with new keys, however all new data will start encrypting using new keys.
Setup > Platform Encryption > Encryption Statistics
Please note:
Testing and Debugging
For more details on debugging Cache-Only Keys please refer this article.
Enjoy!!
Amin Rehman