Bring Your Own Key (BYOK)

The Bring Your Own Key (BYOK) feature is available to customers that are on Premier Support. Appian customers must purchase Premier Support to use the functionality described below. The functionality described below is not included in the base Appian platform.

Overview

Appian Cloud provides multiple Bring Your Own Key (BYOK) configurations options to our customers. This article provides a summary of the offering, along with procedural steps to guide you through the process to take advantage of this feature.

With BYOK, you now have decryption control of the disk that contains their data. You may use your own Encryption Keys to secure the disk that stores your data within your Appian Cloud environments. Appian Cloud currently offers two configurations options for customer owned keys:

  1. AWS CloudHSM Hardware Security Module (HSM) hosted in the your AWS Virtual Private Cloud (VPC).
  2. AWS Key Management Service (KMS) hosted in the region of your Appian Cloud environment(s).

Below, we will give a summary of each configuration option, as well as the procedural steps to step each up.

AWS CloudHSM

When using AWS CloudHSM, data encryption is accomplished using two different encryption keys: (1) the Key Encryption Key (KEK) and (2) the Data Encryption Key (DEK). The KEK encrypts the DEK which in turn is used to encrypt the data on the disk. With BYOK, you will be able to use both keys hosted in your AWS HSM.

Architecture

To communicate with your AWS CloudHSM instance, AWS puts an Elastic Network Interface (ENI) in a subnet inside your AWS account. The ENI can interact with the HSM residing in a separate VPC in an AWS account that is owned by AWS CloudHSM. Appian Cloud instances will communicate with this VPC via an IPsec VPN tunnel. Then, Appian Cloud instances hosting the encrypted disk with your data data will establish an end-to-end Transport Layer Security (TLS) connection with the HSM to perform the API calls.

In this setup, Appian Cloud will store Authentication Material in a secure location with the Appian Cloud Environment. This Authentication Material contains the credentials to gain access to your CloudHSM instance, as well as, the wrapped Data Encryption key (DEK).

The following diagram represents the connection between Appian Cloud and AWS CloudHSM:

BYOK Architecture

Prerequisites

The table below lists the tasks that you will need to perform and the typical role in your organization that will need to be involved in this process. Roles may vary depending on your organization structure.

Prerequisite Description Role in your organization
Premier Support This feature is only available via Premier Support Your Business relationship owner
Set up AWS CloudHSM cluster You will need to set up a CloudHSM cluster in your AWS account. Refer to AWS documentation for this step. Your Information Security team
Generate DEK and KEK Generate a DEK and KEK in their Cloud HSM. Both keys should be generated as 256-bit AES symmetric keys with a size of 32 bytes (see genSymKey docs). Appian recommends that the DEK be generated as a session key, which will ensure it does not persist in your HSM. The KEK should be generated by a different Crypto User account than the one that will be shared with Appian. See Step 5. Your Information Security team
Wrap DEK with KEK Wrap the DEK with the KEK directly in the Cloud HSM using the wrapKey function (refer to key_mgmt_util tool documentation) Your Information Security team
Collect Authentication Material Provide the following details and encrypts all files using a public key generated by Appian:
  1. Username and password of Crypto User. This account will be used to make API calls to your CloudHSM. The KEK should be shared with this Crypto User for cryptographic operations (refer to Share and Unshare Keys documentation).
  2. Issuing certificate (customerCA.crt). Public certificate in PEM encoding that was generated during the CloudHSM initialization. Refer to CloudHSM cluster documentation.
  3. KEK Key Handle. The key handle is the main identifier of the KEK which will be used to unwrap the DEK.
  4. CloudHSM IP address and partition name. Both fields can be viewed in the AWS Management Console.
  5. Wrapped DEK. Generated in the prerequisite 4.
Your Information Security team
Set up IPsec VPN tunnels to Your VPC You are required to establish IPsec VPN tunnels between Appian Cloud instances with BYOK enabled and the your AWS VPC where the CloudHSM cluster is hosted. Each node in the Appian Cloud instance should have connectivity with the CloudHSM ENI over the appropriate ports. Your Network Administrator / Authorized support contact

Steps

Once all prerequisites have been met:

Step Description Role in your organization
Create a Support Case Open a Support Case to enable Bring Your Own Key.
Include the following information:
  1. Configuration Option: AWS CloudHSM
Your Business Relationship Owner
Public Key Generation Appian will generate a public key that you will use to encrypt the Authentication Material. Appian Premier Support
Provide Authentication Material Encrypt the Authentication Material using GPG (See section How to encrypt Authentication Material with GPG). Attach this encrypted file to the support case. Your Information Security Team / Business Relationship Owner
Schedule A Maintenance Window Appian Support will work with you to schedule a maintenance window for the migration to Bring Your Own Key. Appian Premier Support

How to encrypt Authentication Material with GPG

The steps below assume that you will be generating on a Linux/Unix system using GNU Privacy Guard (GPG) encryption utility. Refer to the software documentation for instructions on how to install this utility in your system.

  1. Import the public key provided by Appian: gpg --import appianCloud_pub.gpg
  2. Retrieve the key ID: gpg --list-keys
  3. Create a single text file that contains the Authentication Material listed in the prerequisites section. (e.g. auth_material.txt). An example is provided below to illustrate the contents of the file. Please note that you will need to replace the values with their actual authentication material generated during the CloudHSM setup process. cryptouser_username=kekRetriever cryptouser_password=XXXXXXXXXXXXXXXXXXX issuing_certificate: -----BEGIN CERTIFICATE----- .... ...Your certificate contents here... .... -----END CERTIFICATE----- kek_key_handke: Y cloudhsm_ip_address: 172.X.X.X cloudhsm_partition: hsm000000
  4. Create a zip file with the auth_material.txt and the generated wrapped key (Prerequisite 4).
  5. Encrypt the zip file with the Appian public key. In the command below, replace KEY_ID with the value obtained in Step 2. gpg -e -r KEY_ID auth_material.zip
  6. A new encrypted file will be created in the current directory (e.g. auth_material.zip.gpg ). Share this file with Appian via support case.

Order of Events

The following diagram explains step-by-step the flow between the Appian Cloud and AWS CloudHSM to use the Key Encryption Key hosted in the HSM:

BYOK Step By Step

AWS Key Management Service (KMS)

Amazon's Key Management Service allows you to abstract away the complexity of CloudHSM by exposing the key functionality via an API. For the purposes of Appian Cloud, you may use an AWS Customer Master Key in order to control access to your environments.

Architecture

In this configuration option, Appian Cloud will utilize your AWS CMK in 2 ways:

  1. Generating the Data Key to use for encryption of your data
  2. Decrypting the generated data key

Appian Cloud leverages the KMS API to generate a data key using your CMK. This data key is used to encrypt your data. All use of the data key to perform encryption operations occurs on the Appian Cloud instances that store your data. Furthermore, invocation of the KMS API to generate the data key and decrypt the data key also occur on the Appian Cloud instances that store your data.

Below is the process of data key generation. As shown in the diagram, upon the migration to a Bring Your Own Key setup, Appian will programmatically generate this data key and subsequently store the encrypted copy in a secure credential store within Appian Cloud.

BYOK KMS Key Generation

After the data for your Cloud environment instance(s) has been encrypted, we will decrypt the data on each subsequent startup of your environment.This process is show below:

BYOK KMS Decryption

Steps

Steps Description Organizational Role
Create a Support Case Open a Support Case with Appian Support to enable Bring Your Own Key.
Include the following information:
  1. Configuration Option: AWS KMS
Your Business Relationship Owner
Generate Policy Statement Appian Premier Support will create an IAM User within Appian Cloud that will be used exclusively with your Appian environment. Your technical support contact will provide you with the KMS Key Policy Statement that will need to be added to your created KMS CMK (next step). Appian Premier Support
Creation of the KMS CMK Once your Premier support contact has provided a key policy statement, you are set to create the KMS Customer Master Key that will be used with your environment. Engage your AWS Administrator to create this key and add the provided key policy statement to it. You may reference AWS documentation on how to create a CMK and add this policy statement to it.
Below are the constraints for the CMK:
  1. Must be Symmetric
  2. Must be created in the same AWS region as your Appian Cloud Environment
The Key Policy statement will give us permission to utilize your key in order to generate data keys and run decryption operations.
Once the CMK has been created, please post the Amazon Resource Number (ARN) into the Appian Cloud Support Case.
Your AWS Administrator

F.A.Q.

How can I enable BYOK on my environments?

Please follow the prerequisites listed under the BYOK configuration type of your choosing. Contact Appian Technical Support with any questions.

Can BYOK be used on existing environments?

Yes, BYOK can be configured on existing environments. Furthermore, you may move between different configurations of BYOK. If you have previously configured BYOK with an HSM, you can switch to utilizing KMS, or vice versa. All data from the existing environment will need to be moved to a new disk that will be encrypted with the new encryption key. Consequently, this requires close coordination with Appian Technical Support during the transition.

Does Appian keep a copy of your Encryption Key?

Appian Cloud will only store the encrypted Data Encryption Key. If Appian is unable to unwrap/decrypt the Data Encryption Key, Appian won’t be able to decrypt the disk storing your data and the site will be unavailable.

What happens if the key is lost?

If the key is lost, all the data, including all backups, would be unrecoverable.

Does Appian request decryption of the data key(s) for every read/write operations?

No, decryption of Data Encryption Key(s) is not necessary after the disk is open, which occurs on each startup of your environment. The decrypted Data Encryption Key will remain present in kernel memory for read and write operations.

Do you support other HSMs apart from AWS CloudHSM?

Appian Cloud’s BYOK capability is currently only supported for AWS CloudHSM.

Is key rotation supported?

Use of Amazon's built-in automatic CMK key rotation is supported for the AWS KMS configuration only. This type of rotation maintains access to the old key for decryption regardless of the rotation of the underlying material, and also maintains the same key metadata. Manual key rotation is not supported for either configuration option.

Open in Github

On This Page

FEEDBACK