Help Administrators

Using BYOK encryption with Replicon

Looking for help with this feature in Polaris PSA or Polaris PPM? Check out Using BYOK encryption with Replicon in the Polaris help.

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.

BYOK is not necessary for your Replicon data to be secure. Customers who are not using BYOK still have their data protected by industry-standard security controls, including encryption-at-rest using Replicon-managed encryption keys.

Selecting a BYOK approach

Replicon supports two different paths to BYOK encryption: customer-managed and Replicon-managed.

How customer-managed BYOK works

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:

  • All customer-related data systems within the Replicon Cloud Platform will be encrypted with the provided key or derived data keys
  • An automated audit report will be generated regularly to provide evidence that the requested encryption key is being used for all internal data systems
  • Encryption key material is never exposed to Replicon
  • The customer may choose to revoke encryption key access at any point in time

However, the customer-managed approach also imposes significant responsibility and burden upon the customer, which must be considered carefully.

For example, if customers fail to retain encryption keys for use in disaster recovery, all of their data could be permanently lost.

Among their responsibilities, customers must:

  • Provide multiple KMS keys, which are required to enable Replicon’s internal cross-region disaster recovery processes
  • Ensure their AWS account and the shared AWS KMS keys are always available, since these keys are required for Replicon services to be available. The customer is solely responsible for AWS billing maintenance, account security, and configuration management.
  • Bear all costs associated with the AWS KMS keys, including all Replicon Cloud Platform usage costs that result from the customer’s BYOK implementation
  • Maintain the capability to re-import the encryption key, if using AWS KMS key material imports (rather than AWS KMS server-side key material generation). A key re-import would be required to avoid complete data loss in scenarios such as an AWS data center power failure.

How Replicon-managed BYOK works

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:

  • All customer-related data systems within the Replicon Cloud Platform will be encrypted with the provided key or the derived data keys
  • An automated audit report will be generated regularly to provide evidence that the requested encryption key is being used for all internal data systems

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:

  • Generating the key material in such a way that it is not trivial to reproduce. Replicon does not guarantee the quality of the key material that is imported.
  • Maintaining the capability to re-import the encryption key in the future. In unlikely circumstances beyond Replicon’s control, such as a complete data center power failure, a key re-import will be required to avoid complete data-loss.

Understanding the BYOK onboarding process

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.

Onboarding with customer-managed BYOK

When using customer-managed BYOK, the onboarding process consists of these steps:

  1. Replicon and customer identify supported AWS regions
  2. Customer provisions AWS KMS CMKs
  3. Replicon provisions data systems using the imported encryption keys
  4. Replicon migrates any existing data to the new data systems
  5. Replicon generates an audit report that validates the implementation

 

  1. Replicon and customer identify supported AWS regions

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.

  1. Customer provisions customer-managed keys

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:

If you choose to externally generate and import the KMS key material, be aware that you are taking on the additional responsibility of maintaining the availability of that key material. AWS may lose access to the key material during some data center-level outage events, and require you to re-import the key material. If such a scenario occurs and you are unable to re-import the key material, access to all your Replicon data and backups will be irretrievably and permanently lost.

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.

Onboarding with Replicon-managed BYOK

When using Replicon-managed BYOK, the onboarding process consists of these steps:

  1. Replicon provides the customer with API endpoints and access credentials
  2. Customer develops an integration to import encryption keys using Replicon's API
  3. Replicon provisions data systems using the imported encryption keys
  4. Replicon migrates any existing data to the new data systems
  5. Replicon generates an audit report that validates the implementation

 

  1. Replicon provides credentials and endpoints

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:

      • API endpoints
      • Enterprise identifiers
      • Enterprise API keys
      • Key import process documentation

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.

  1. Customer performs a key import

We recommend a six-step process for performing a key import:

    1. Generate the encryption key that will be imported into Replicon.
Do not store this encryption key in any persistent medium without protecting it; e.g. use a hardware security module, or encrypt the key before storing it on disk.
    1. Back up and safely store the encryption key.
It is the customer’s responsibility to maintain availability of this encryption key. In rare circumstances, Replicon and AWS may lose this key, and the customer may need to re-import the key to maintain data access.
    1. Invoke a Replicon API to start a key import process.
Replicon will generate a new public/private keypair to protect the import process, and provide you with an import token (a unique identifier for this process) and the public key will be provisioned.
    1. To secure the encryption key while it is in-transit, encrypt the key with Replicon's unique public key for this import.
The encryption key should be secured by using PKCS#1 OEAP (RSA) using the public key from step #3, and then be base64 encoded.
    1. Invoke a Replicon API to upload the encrypted encryption key.
    2. Clean up any intermediate data that was generated during this process.


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.

This example does not persist the key, so it skips steps #2 and #6 in the recommended key import process. Implementing those steps is critical to a successful onboarding.
 

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.

 
Important reminders
  • Replicon will maintain the imported key material in a secure manner using industry standards
  • Replicon is not be able to export key material back to the customer
  • Replicon does not guarantee the quality of the key material that is imported; it is up to the customer to generate the key material such that it is not trivial to reproduce

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.

Final onboarding steps carried out by Replicon

Whether you're using customer-managed or Replicon-managed BYOK, the final onboarding steps carried out by Replicon will be the same:

  1. Replicon provisions data systems

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.

  1. Replicon migrates data systems

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.

  1. Replicon generates a report to validate the implementation

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.

FAQs

Is it possible to rotate the encryption key?

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.

Can we use the same encryption keys in multiple Replicon regions?

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.

Does Replicon maintain a copy of the encryption key?

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.

Related links

API authentication
Introduction to the Replicon API
Setting up webhooks to trigger event notifications
Viewing the available API operations

Start a free Replicon trial today based on your business needs

Start Free Trial