Use AWS Encryption Modifier

When your organization needs access to Amazon Web Services (AWS) resources through CSM, Cherwell has a unique Amazon key that must be used in each request. This key is sensitive information, so Cherwell has provided new CSM encryption resources that you can use within your Business Object Forms to ensure secure communication with AWS.

Amazon Key

The Amazon key (secret) is a string of characters that must be sent to Amazon every time a CSM user interacts with AWS (example: when a support agent logs a ticket requesting an Amazon EC2 resource). The Amazon key is sent through the HTTP header of every CSM request. This key is unique to Cherwell and does not change.

Encryption Key and Nonce (Cherwell-Generated)

Because of its sensitive nature, the Amazon key is encrypted and stored in CSM in the Business Object field. With every request to AWS, the key must be decrypted and passed through the HTTP header of the request. The encryption and decryption actions require both a Cherwell-generated encryption key and a nonce.

The Cherwell-generated encryption key is generated and stored only one time, and the value of the key remains constant. This key is stored globally and should be protected so that it's never overwritten. One option is to wrap the global value into an Action Block that makes sure that it's only populated if it doesn't already have a value. You can also add other protection measures such as scoping so that only a designated set of people are allowed to write to the storage location.

The Cherwell-generated nonce is an arbitrary value that is unique to each Business Object. The nonce value is stored with the Amazon key in the Business Object Field and is used together with the Cherwell-generated encryption key during the encryption and decryption processes.

Security and Scope

All configuration to the Amazon key and the Cherwell-generated encryption key and nonce is performed in CSM Administrator within a Blueprint. As a precaution to protect sensitive data, the encryption key stored value, nonce field, and the encrypted Amazon key should be scoped so that only appropriate users can read and modify the values.
If the Amazon key is modified erroneously, you cannot decrypt the value on the Business Object, which means you will have to request a new key from Amazon.

Recommendations for Configuring AWS Encryption

You can build CSM resources to ensure successful communication with AWS while maintaining an encrypted version of the Amazon key. Suggested configuration includes storing the Amazon key and nonce in Business Object Fields, creating an Action Block that checks for the Cherwell-generated encryption key stored value, and creating a One-Step Action and Form Button for submitting the AWS request.

Creating Fields for Storing the Amazon Key and Nonce

As a best practice, store the Amazon key and nonce inside text Fields in the Business Object that is used for the AWS request. Once the fields are available, you can run the One-Step™ Action that stores the Amazon key and Cherwell-generated nonce directly inside text Fields.

To create the text Fields:

  1. In CSM Administrator, open the Business Object in edit mode.
  2. Add a text Field for the Amazon key. The key is populated through the One-Step Action that you create below.
  3. Create a text Field for the Cherwell-generated nonce. This Field is populated by setting its default value as the output of the GenerateEncryptionNonce system function in the Field Properties window.
  4. Change the default character length of the Text field that you created in the previous step to 24 characters. The default length is 15 characters.
  5. Save and publish your changes.

Creating an Action Block to Populate the Encryption Key Stored Value

Create an Action Block that populates a stored value containing the Cherwell-generated encryption key. This Action Block is used in a One-Step Action that decrypts the Amazon key and passes it to AWS through the HTTP request header.

The Action Block first uses an expression to check for the stored value. If it does not exist, a system function is called to generate the encryption key and store it on the Business Object Field. The encryption key is generated and stored only one time. From that point forward, when the Action Block is triggered in the One-Step Action, the expression confirms that the stored value exists and moves to the next step.

Before creating the Action Block, create a stored value for the Cherwell-generated encryption key.

To create the Action Block:

  1. In CSM Administrator, select Managers > Action Blocks to open the Action Block Manager.
  2. In the General tab, in the Name field, provide an intuitive name (example: Encryption Key).
  3. Drag the Decide Between Multiple Cases action from the Advanced Actions section in the designer toolbox on to the editor as the first step.
  4. Configure Case 1 with a custom expression:
    1. In the Value field, select the stored value that you created for the Cherwell-generated encryption key. This key is used with the Cherwell-generated nonce to encrypt and save the Amazon key on the Business Object Form.
    2. In the Operator field, select Empty.
  5. Configure the first decision step to take action when the stored value is empty:
    1. Drag the Update Variables and Stored Values action from the Advanced Actions section in the designer toolbox on to the step.
    2. In the General tab, in the Stored Value field, select the stored value that you created for the Cherwell-generated encryption key.
    3. In the Value field, select the GenerateEncryptionKey system function.

Creating a One-Step Action for the AWS Request

Use a One-Step Action to populate the header of the HTTP request with the Amazon key so that CSM can successfully interact with the AWS resource. Individual steps include confirming that the Cherwell-generated encryption key exists in the Business Object, updating the Business Object with updated variables, decrypting the Amazon key, and passing the decrypted Amazon key to AWS through the header of the HTTP request.

To create the One-Step Action:

  1. Create a new One-Step Action.
  2. From the designer toolbox, drag the Action Block that you created above as the first step in the One-Step Action.
  3. Add a second step that prompts the user for the Amazon key, which is then encrypted through the Cherwell-generated encryption key and nonce. To configure the step:
    1. Open the Modify/Format Value window.
    2. Add an Encryption Key modifier.
    3. Update the Key field with the value of the encryption key.
    4. Update the Nonce field with the AWS Resource Nonce value.
    5. Select OK.
  4. Add a third step and set the value to Encrypted Secret.
  5. Add a final action step that decrypts the Amazon key and submits an HTTP request to AWS with the Amazon key in the header of the request.
    1. Add the HTTP Request action type to the One-Step Action.
    2. In the General tab, select GET.
    3. In the URL field, add the URL to the Amazon site.
    4. In the Headers tab, select the green plus sign.
    5. In the Key field, select the Amazon key. In the Value field, select the AWS Resource Amazon Key and then select to modify the value.
    6. Select the green plus sign again to open the Modify/Format Value window.
    7. Select Encryption in the Modifier field.
    8. Select the nonce and the Cherwell-generated encryption key.
    9. Select Decrypt.
    10. Select OK.
  6. Save your changes to the One-Step Action.

After running the One-Step Action from the Form, CSM completes the request to AWS.

Creating the Form Button that Launches the One-Step Action

In the Business Object Form, add a button that launches the One-Step Action that you configured above.

To add the Button:

  1. Open the Form in edit mode.
  2. Drag a button to the form.
  3. Right-click the button and select Control properties.
  4. Configure the button with the One-Step Action.
  5. Save the form.