Replicon's Bring Your Own Key (BYOK) encryption capabilities allow enterprise customers to provision and manage encryption keys that are used to secure their data while at-rest in Replicon's Cloud Platform.
This document outlines the two available BYOK options – customer-managed and Replicon-managed. It also outlines the onboarding process for each approach.
If you need more information about the processes outlined in this document, please contact your Customer Success Manager or contact Replicon Support.
Replicon supports two different paths to BYOK encryption: customer-managed and Replicon-managed.
With the customer-managed BYOK approach, the customer is responsible for providing Replicon with access to two or more customer-managed keys (CMKs) via AWS's Key Management Service (KMS). Replicon will then provision our data management systems to use these CMKs during all encryption-at-rest operations.
The customer-managed BYOK approach has the highest level of security:
However, the customer-managed approach also imposes significant responsibility and burden upon the customer, which must be considered carefully.
Among their responsibilities, customers must:
With the Replicon-managed BYOK approach, the customer develops an integration to import encryption keys to the Replicon Cloud Platform. After this secure import process is completed, Replicon provisions our data management systems to use these imported keys during all encryption-at-rest operations.
The Replicon-managed BYOK approach provides these strong security guarantees:
Replicon will maintain the imported key material in a secure manner using industry standards, including the use of hardware security modules.
Replicon will not be able to export key material back to the customer, since we do not have the ability to view or access the key material. No encryption key revocation ability is granted to the customer.
To ensure security and data resiliency, the customer is responsible for:
When the BYOK onboarding process begins, the customer will be introduced to an engineer from Replicon's Cloud Operations team, referred to as the onboarding engineer throughout this document.
This individual will be responsible for coordinating all the onboarding activities. Having a single point of contact allows for efficient and accurate communication as we work together through the onboarding process.
When using customer-managed BYOK, the onboarding process consists of these steps:
All implementations of BYOK require at least two Replicon-supported AWS regions to be provisioned. One region is where normal, day-to-day data operations take place, and a second region is used by Replicon to provide disaster-recovery capabilities. Additional regions may be used if a customer requires geographic data residency.
Replicon's onboarding engineer, solutions engineering team, and implementation team will work with the customer to identify the regions that need to be included. Once these regions are determined, it will be the customer’s responsibility to implement the AWS KMS keys in those regions.
Within each region selected for implementation, the customer must create one symmetric customer master key (CMK) with AWS's KMS service. This symmetric key can be either:
Once the CMKs are created, you must apply a key policy to each key to allow Replicon to use it. Apply the following key policy to each CMK, replacing "123456789012" with your own AWS account ID to allow you to manage the key.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Enable my own AWS account to manage this key",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:root"
},
"Action": "kms:*",
"Resource": "*"
},
{
"Sid": "Allow Replicon use of the key",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::127450652264:root"
},
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "*"
},
{
"Sid": "Allow Replicon attachment of persistent resources",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::127450652264:root"
},
"Action": [
"kms:CreateGrant",
"kms:ListGrants",
"kms:RevokeGrant"
],
"Resource": "*",
"Condition": {
"Bool": {
"kms:GrantIsForAWSResource": "true"
}
}
}
]
}
Once you’ve applied the key policy to each CMK, communicate the Amazon Resource Names (ARNs) that identify each CMK created through KMS to your Replicon onboarding engineer. These ARNs use the following format:
arn:aws:kms:us-west-2:123456789012:key/93302c1f-1a71-4c07-a2bf-c6fbe0d245e1
Replicon's onboarding engineer will test the CMKs to ensure that we have the necessary access. After this test is complete, the remaining onboarding steps (outlined below), will be undertaken.
Are you a FedRAMP customer?
Replicon provides a FedRAMP-certified hosting solution for US government customers. If you are implementing as a FedRAMP customer, your onboarding engineer will provide a slightly different key policy to enable onboarding in that environment.
Refer to Final steps below for information about
the remainder of the onboarding process.
When using Replicon-managed BYOK, the onboarding process consists of these steps:
Replicon's onboarding engineer will kick off the implementation process by providing the customer with an information packet about the key import process. This packet will include:
As development work is typically required to successfully implement the import APIs, we will include test endpoints and credentials in addition to the production endpoints and credentials.
We recommend a six-step process for performing a key import:
Example 1: Bash / OpenSSL
In this example, we walk through the six key import steps using the common OpenSSL toolkit and a bash shell environment.
# The information packet provided by Replicon will provide these three values:
# Enterprise API key:
apikey="1234-abcde-987"
# Enterprise short identifier:
enterpriseid="dave"
# Replicon's API endpoint; a different staging/test environment may be
# provided for initial development purposes
endpoint="https://global.replicon.com"
# Step 1: Generate the encryption key that will be imported into Replicon
# - typically an enterprise's HSM or other key management systems will be used
# - this demo workflow creates a key using openssl's keygen capabilities
# - in this workflow, we avoid the key ever hitting disk unencrypted; a
# password-based AES encryption is used to protect the key while on disk
# - the created encryption key must be backed up, and able to be restored
# - please don't really use password "RepliconRocks"; you can do better
openssl rand 32 | \
openssl enc -aes-256-cbc -pass pass:RepliconRocks -md sha1 | \
base64 > secure-key.b64
# Step 2: Backup and safely store the encryption key
# Maintaining availability of this encryption key is the responsibility
# of the key importer. In unlikely circumstances, Replicon may lose this
# key and it may need to be re-imported to maintain data access.
# Step 3: Invoke a Replicon API to start a key import process
# We also pull the "publicKey" and "importToken" out of the response
# for later usage.
curl --fail -X PUT -d "" -H "Authorization: ApiKey $apikey" \
$endpoint/\!/ems/enterprises/$enterpriseid/cmk/import-key-request > \
importreq.json
cat importreq.json | jq -r '.publicKey' > publickey.crt
importtoken="$(cat importreq.json| jq -r '.importToken')"
# Step 4: Re-encrypt the encryption key with the public key from the import
# request to secure it while in-transit to Replicon's services
cat secure-key.b64 | \
base64 -d | \
openssl enc -d -aes-256-cbc -pass pass:RepliconRocks -md sha1 | \
openssl rsautl -encrypt -oaep -inkey publickey.crt -pubin | \
base64 > secure-key-import-ready.b64
# Step 5: Complete key import by uploading the import token and the
# encrypted secure key.
curl --fail -H "Authorization: ApiKey $apikey" \
-H "Content-Type: application/json" \
$endpoint/\!/ems/enterprises/$enterpriseid/cmk/import-key \
-d '{"importToken":"'$importtoken'","keyMaterial":"'$(cat secure-key-import-ready.b64)'"}'
# Step 6: Cleanup intermediate files, leaving only secure-key.b64
rm importreq.json publickey.crt secure-key-import-ready.b64
Example 2: node.js crypto & axios
In this abbreviated example, we show the generation and uploading of a key using node.js' crypto libraries.
const client = axios.create({
baseURL: `${config.EXTERNAL_API_URL}/!/ems/enterprises/${eid}/cmk`,
headers: {
authorization: `ApiKey ${apiKey}`,
},
});
const respGet = await client.put('/import-key-request');
const keyMaterial = crypto.randomBytes(32);
const encKeyMaterial = crypto.publicEncrypt(respGet.data.publicKey, keyMaterial);
const respPost = await client.post('/import-key', { importToken: respGet.data.importToken, keyMaterial: encKeyMaterial.toString('base64') });
// Response will be a JSON object that contains a status key and an id key.
The customer must maintain the capability to re-import the encryption key, to prevent complete data loss in case of disaster.
Refer to Final steps below for information about
the remainder of the onboarding process.
Whether you're using customer-managed or Replicon-managed BYOK, the final onboarding steps carried out by Replicon will be the same:
Replicon will internally provision the required data systems that use encryption-at-rest with your custom CMKs. We will identify any Replicon instances associated with your customer account (e.g. multi-region instances, sandboxes, development environments), and provision the required new data systems to support those instances.
In the event that you have existing data with Replicon, our operations team will migrate your data to the new systems, and then delete and purge data from the old systems. This process will involve a disruption of service during the migration; we will work with you to find the best window of time to perform this maintenance work, which typically takes under 8 hours.
When your BYOK implementation is complete, your onboarding engineer will run an automated report of the implementation. To generate this report, the system scans all of your applicable instances and related data stores within Replicon's Cloud Platform, and validates that they are configured with the expected encryption-at-rest configuration.
The report, delivered in a JSON format, contains highly detailed information about the internal configuration of data systems, and highlights any deviations from the expected configuration. It allows both the customer and Replicon to be confident that the implementation is complete, and that the BYOK configuration is sound.
This report can be run on-demand after the implementation for continued compliance validation. The onboarding engineer can work with you to provide the ongoing visibility that meets your needs.
Yes, follow the onboarding process outlined above to rotate a key, then contact your CSM when the new key is imported. We’ll require approximately 8 hours of downtime to perform the backend operations required to rotate the key; your CSM and Replicon's Operations team will work with you to schedule a maintenance window.
In rare cases, global enterprises use multiple instances for data-residency legal compliance, or for enhanced performance. In these configurations, either the same encryption keys or different encryption keys can be used for each instance, depending upon your security and legal requirements.
Replicon does not maintain an exportable copy of the imported encryption key material. Imported encryption keys are stored in hardware security modules (HSMs) that allow Replicon to perform data-key generation, and encryption and decryption. While we may use multiple HSMs globally to support high availability, disaster recovery, and future data migration requirements, the imported keys are never available to any Replicon staff or computer systems.