Bring Your Own Key (BYOK) Setup Process in Appian Cloud
This help topic applies to Appian Cloud users only.


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.

Purpose

The purpose of this article is to give a high-level overview of the setup process to enable BYOK in Appian Cloud.

Summary

Appian Cloud customers can use their own Encryption Keys to secure the disk that stores their data. Appian Cloud sites can use a key from a AWS CloudHSM Hardware Security Module (HSM) hosted inthe customer’s AWS Virtual Private Cloud (VPC). With the introduction of BYOK, customers now have the decryption control of the disk that contains their data. Appian Cloud’s BYOK capability is currently only supported for AWS CloudHSM.

Data encryption is accomplished using two different encryption keys: (1) the Key Encryption Key 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, customers will be able to use both keys hosted in their AWS HSM.

Architecture

To communicate with the customer’s AWS CloudHSM instance, AWS puts an Elastic Network Interface (ENI) in a subnet inside the AWS customer 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 servers will communicate with the customer VPC via an IPSEC tunnel. Then, Appian Cloud servers hosting the encrypted disk with customer data establish an end-to-end Transport Layer Security (TLS) connection with the HSM to perform the API calls.

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

BYOK Architecture

Prerequisites Checklist

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

Prerequisite Description Role in customer organization
1. Premier Support This feature is available via Premier Support Business relationship owner
2. Set up AWS CloudHSM cluster Customer sets up a CloudHSM cluster in their AWS account. Refer to AWS documentation. Information Security team
3. Generate DEK and KEK Customer generates 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). The KEK should be generated by a different Crypto User account than the one that will be shared with Appian. See Step 5. Information Security team
4. Wrap DEK with KEK Customer wraps the DEK with the KEK directly in the Cloud HSM using the wrapKey function (refer to key_mgmt_util tool documentation) Information Security team
5. Collect Authentication Material Customers provides 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 the customer’s 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.
Information Security team
6. Set up IPSec VPN tunnels to Customer VPC Customers are required to establish IPSec VPN tunnels between Appian Cloud instances with BYOK enabled and the customer’s Virtual Private Cloud (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. Network Administrator / Authorized support contact

Considerations

  • The Authentication Material is stored in a secure location in Appian Cloud.
  • The DEK will only exist for a brief period of time. It should be created as a session key and will not persist.
  • The KEK should be created by a different crypto user than the one shared with Appian Cloud. The KEK will persist in the CloudHSM, and it will never be retrieved by Appian Cloud.
  • For Appian Cloud instances with BYOK enabled, availability of the CloudHSM is a requirement for the instances to properly start up.
  • Appian only stores the wrapped DEK. If Appian is unable to unwrap the DEK, the site will be unavailable. If the customer’s CloudHSM is unavailable at the time when an Appian Cloud server needs it, the site will be unavailable until the CloudHSM is available again.

Steps

Once all prerequisites have been met:

  1. Open a Support Case requesting for enabling BYOK in your Appian Cloud instance(s).
  2. Appian will generate a public key that the customer will use to encrypt the Authentication Material.
  3. Customer will encrypt the Authentication Material using GPG (See section How to encrypt Authentication Material with GPG)
  4. Customer attaches encrypted file to support case.
  5. Appian Premier Support will schedule a maintenance window and deploy the necessary configurations.
  6. After the maintenance window, customer data in the Appian Cloud instances will be encrypted using the key in CloudHSM.

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 customers 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 Order

F.A.Q

How can I enable BYOK on my sites?

Please contact Appian Support if you desire to use BYOK in your sites.

Can BYOK be used on existing sites?

This is supported. All data from the existing site will need to be moved to a new disk that will be encrypted with the new encryption key. Consequently, this requires close coordination during this transition.

Does Appian keep a copy of the customer Encryption Key?

Appian Cloud will only store the wrapped Data Encryption Key. The DEK is unwrapped using the KEK that is stored in the HSM and the unwrap operation happens directly in the HSM. If the Appian Cloud site is unable to unwrap the Data Encryption Key, Appian won’t be able to decrypt the disk storing the customer’s data and the site will be unavailable.

Does Appian request the Key Encryption Key to HSM for every read/write operations?

The Key Encryption Key is only used when unwrapping the Data Encryption Key and the Key Encryption Key is not used after the disk is open. The Data Encryption Key will remain present in kernel memory for read and write operations.

What happens if the key is lost?

If the customer loses the key, all the data, including all backups, would be unrecoverable.

Do you support other HSMs apart from AWS CloudHSM?

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

Open in Github

On This Page

FEEDBACK