Exporting SmartKey keys to Cloud Providers for BYOK

Updated: February 8th, 2018


Here we will go over several ways to export SmartKey keys to major cloud providers that support BYOK for server-side encryption.

Requisite: Download SmartKey CLI from here.

Google Cloud

1. Create a 256-bit AES key and import it into SmartKey as a SECRET object type with the EXPORT key operation enabled.

$ head -c 32 /dev/urandom | LC_CTYPE=C tr '\n' = > mykey.txt
$ python smartkey-client.py import-key --in mykey.txt --obj-type SECRET --name Google-Cloud-Secret-Key -exportable

2. Download this key on your application environment.

$ python smartkey-client.py export-object --name Google-Cloud-Secret-Key

GCS (Cloud Storage)

1. Add the following option to the GSUtil section of GSUtil boto configuration file:

encryption_key = [YOUR_ENCRYPTION_KEY]
decryption_key1 = [YOUR_ENCRYPTION_KEY]

2. Now you can upload and download objects in GCS with encryption with your own keys.


3. GCS browser shows that the object is customer encrypted.

GCE (Compute Engine)

1. Add the key in GCE and launch instance.

2. The disk says that it's encrypted with customer keys.

Wrapped Key export

GCE also supports import of customer keys wrapped by a Google public key. In this case we must export the key as a secret as mentioned before and wrap it using openssl.

1. Fetch Google public key.

$ curl "https://cloud-certs.storage.googleapis.com/google-cloud-csek-ingress.pem" -o google-cloud-csek-ingress.pem
$ openssl x509 -pubkey -noout -in google-cloud-csek-ingress.pem > google-cloud-csek-public.pem

2. Wrap SmartKey exported key with Google public key.

$ openssl rsautl -oaep -encrypt -pubin -inkey google-cloud-csek-public.pem -in smartkey_exported_key -out rsawrappedkey.txt

3. Set the key data in GCE as a wrapped key

Note: SmartKey is very soon providing support to OAEP padded key wrapping algorithm. With the support you can perform the wrapping operation in SmartKey itself, without the need of exporting the actual keys.


AWS KMS provides a wrapping key and a token in order to import customer keys. The steps are very similar to Google Cloud Wrapped Key export setup:

1. Create a 256 bit AES key and import in SmartKey as a SECRET type with EXPORT enabled.

$ head -c 32 /dev/urandom | LC_CTYPE=C tr '\n' = > mykey.txt
$ python smartkey-client.py import-key --in mykey.txt --obj-type SECRET --name AWS-Cloud-Secret-Key -exportable

2. Download this key on your application environment.

$ python smartkey-client.py export-object --name AWS-Cloud-Secret-Key > my_secret.key

3. Initiate creation of key of external origin in KMS.

4. Download the zip containing the wrapping key and import token.

5. Wrap the exported secret key with the AWS Wrapping Key.

$ openssl rsautl -encrypt -in my_secret_key -oaep -inkey wrappingKey_fcb572d3-6680-449c-91ab-ac3a5c07dc09_080410435 \  -pubin -keyform DER -out aws-wrapped.key

6. Upload this wrapped key and the downloaded token to complete the import.

7. Use this imported key for server-side encryption in AWS Services. In S3 for example, one can enable this during bucket creation itself.


Azure Key Vault only supports direct import of keys with no wrapping. Thus, only SECRET ojbects are supported for BYOK. Check out the Google Cloud section to generate and export SECRET keys.

You have to choose to upload your key either as a software or hardware key depending on your requirement.


1. Create an external key in Alibaba.

1a. Create a new key by selecting key material source as “External”.

1b. Newly created key should show up with status as “Pending Import” and key material source as “External”.

2. Download key encryption material.

Download the key encryption material, you will need it for key wrapping in Smartkey and key importing into Alibaba.

• Public key
• Import Token

3. Import Alibaba public key into Smartkey.

Import the public key from previous step into Smartkey as RSA key.

4. Create Customer Master Key in Smartkey.

Create a new AES key and make sure to select the “exportable” option.

5. Wrap customer master key with Alibaba public key.

5a. Use Smartkey-Cli to wrap the newly created AES key (customer master key) with imported Alibaba public key.

$ smartkey-cli wrap-key --kid <customer master key> --alg RSA --mode OAEP_MGF1_SHA1 --wrapping-kid <Alibaba public key> --out alibabawrap.key 

5b. Apply base64 encoding on wrap key.

$ openssl enc -e -base64 -A -in alibabawrap.key -out alibabawrapbase64.key

6. Upload key into Alibaba KMS.

Import the encoded wrap key into Alibaba. You will also need the import token which we downloaded from Alibaba in Step 2.

7. Alibaba KMS should have external key enabled now.

With successful import your external key should be "Enabled" now.


Salesforce's Shield Platform Encryption is introducing a new pilot feature called Cache-Only Keys. This capability enhances the existing Bring Your Own Key (BYOK) capability by allowing customers to host their key material in a wrapped format which Salesforce will fetch as required. While this will be cached in an encrypted form, Salesforce will not retain or persist the key material in any system of record or backups.

ESK (Equinix SmartKey) can be used as HSM backed Software-as-a-service(SAAS) for ESKSalesforce Cache only BYOK solution. This guide explains how to use ESK to securely generate encryption key and configure in Salesforce’s Shield Platform.


1. Salesforce account with permission to below settings.

a. Name Credentials
b. Certificate & Key Management
c. Key Management

2. SmartKey account with appropriate permissions to create groups, app, security object and plugin.

Smartkey Setup

Step 1: Create Group in ESK (Equinix SmartKey)

1. Login to Equinix SmartKey (www.smartkey.io)

2. Click on left navigation bar to navigate to “Groups”

3. Click on (+) icon to create new group.

Step 2: Create an APP in ESK

1. Click on left navigation bar to navigate to “Apps”

2. Click on (+) icon to create new app.

3. Enter desired information (refer below screenshot) and select above created group and click save.

4. Navigate to Apps dashboard to see newly created app.

5. Click on copy API key. It will open a model window.

6. Go to USERNAME/PASSWORD tab in model window.

7. Copy and Save username / password. Details will be required later to configure “Named Credentials” in salesforce later.

Step 3: Create plugin in ESK

1. Click on “Plugins” tab on left navigation panel.

2. Click on (+) button to create new plugin.

3. Enter <plugin name>

4. Select “Group” created in Step 1.

5. Copy and paste code plugin code and save. Download Plugin Code

6. Copy and save UUID of plugin created for future configuration.

Step 4: Generate and Download Self Signed Certificate in Salesforce

1. Login to Salesforce. Go to “Setup”.

2. Create a (Self Signed) certificate under Security >> Certificate and Key Management with below setting.

3. Disable Exportable Private key.

4. Check box to “Use Platform Encryption.

Please refer Salesforce documentation for more info on “Certificate and Key Management”.

5. Once certificate is created, please download it.

Downloaded certificate and save to your desired location.

Step 5: Import Certificate to ESK

1. Login to SmartKey

2. Click on left navigation bar to navigate to “Security Objects”

3. Click on (+) button to create new Security object.

4. Enter name of security object and select Group created in Step 1.

5. Click on “IMPORT” button.

6. Choose value format as “BASE 64”

7. Choose Security Object type as “Certificate”

8. Click on “Upload a file” button to upload converted certificate at Step 4.5

9. Click IMPORT button to import the certificate into SmartKey as security object.

Salesforce Setup

Step 6: Define Name Credential in Salesforce

1. Login to Salesforce. Go to “Setup”.

2. Click on “Named Credentials” under Security in left navigation bar.

Click on button: New Named Credential. It will open screen to create Name Credential.

3. Enter details for named credential

a. Enter Label & Name of your choice

b. Enter URL as below (uuid: uuid of plugin created in Smartkey setup Step 3 ) https://www.smartkey.io/sys/v1/plugins/invoke/uuid

c. Select Identity Type as “Named Principal” and Authentication protocol as “Password Authentication”.

d. Enter username and password of SmartKey App created in Smartkey setup Step 2 and click Save.

Steps to generate encryption keys and import to Salesforce

We can generate as many keys as we want with SmartKey and configure in Salesforce using steps mentioned below. Whenever customer wants to rotate key, simply execute the plugin and generate a new key. The same needs to be configured in Salesforce afterwards.

Step 1: Generate JWE Token (BYOK Cache only KEY) using plugin

1. Go to plugin created in Step 3 of SmartKey Setup.

2. Click on “ADD TEST INPUT” on right hand side.

3. Enter below payload in text box

"cert" : <uuid of certificate imported in SmartKey>,
"name": "<unique name of key eg: salesforce_ency_key_v1>"

4. Click “RUN TEST”

5. Plugin generates security objects (AES encryption key and meta information) in SmartKey and return their uuid.

Copy the value of “opq_key_identifier” field in response body.
This would be required while setting up BYOK in Salesforce.

dek: is uuid of AES encryption key generated by plugin and stored securely in Smartkey. Salesforce will use it as data encryption key.

opq_key_identifier: Smartkey plugin also generates a security object of type “OPAQUE”. It contains meta information to generate response (JWE Token) required by Salesforce. Meta information has below information:

a) AES Encryption key UUID (dek)
b) UUID of certificate used.

When Salesforce platform call SmartKey plugin to fetch encryption keys. Plugin reads meta information from opaque object and processes dek key material and certificate used (while generating meta info and AES initially) to generate JWE token. Same is return to salesforce in desired JSON format.

Refer salesforce documentation for more info on JWE token.

6. "dek” value is AES encryption key which generated by plugin and the key is stored in SmartKey. The key material would be securely transferred to Salesforce as part of JWE token.

7. Go to Security Objects screen to see newly created object.

Step 2: Configure Salesforce to use SmartKey to fetch Cache-only Key at runtime

1. Go to Setup >> Security >> Platform Encryption >> Key Management

2. Click on Bring Your Own Key button

1. Go to Setup >> Security >> Platform Encryption >> Key Management

3. Select the desired certificate to be used (it should be same as one used while executing plugin to generate encryption key and meta information).

4. Select “Use a Cache-Only Key” radio button.

5. Select “Named Credential” created with SmartKey endpoint.

6. Enter BYOK Id (opq_key_identifier) generated by SmartKey plugin in previous step.

7. Click save

8. Once configuration is saved, Salesforce will call SmartKey to fetch JWE token and decrypt it with private key of the certificate.

9. You can see newly imported key on “Key Management” screen.

Step 3: Step 3: Verify Key Import in ESK Event logs

1. Logs are generated in ESK while fetching encryption keys during setup (after step 2.9).

2. Go to Event logs in Smartkey to verify (refer below screenshot).

3. Logs are also generated later when Salesforce call SmartKey to fetch encryption keys at runtime.