Encryption Modifiers

When integrating CSM with other systems (Examples: Amazon, Microsoft Teams) you may be required to store private information such as API keys, user names, and/or passwords in the CSM database. This information is sensitive, so Cherwell provides CSM encryption resources that you can use within your system to ensure secure storage and communication of that sensitive data.

Encryption modifiers are only available in certain contexts, such as within One-Step™ Actions, expressions, or prompts.

What You Need for Encryption

  • Encryption Key (stored value): This key is system-generated and is unique to each customer. To do this, create an empty stored value called Cherwell Encryption Key. As the encryption and decryption modifier will not work without this piece, you may want to create a One-Step Action or Action Block to ensure that the stored value is populated, and if not, generate a value.
  • Nonce (field data or stored value): A nonce is a random value and is combined with the Cherwell encryption key to hash a string.
    • Field data: This string must be entered via a One-Step Action, because a modifier needs to be applied to encrypt the string. If storing the data on a record, link to a One-Step Action from the form to add the value, rather than allowing direct entry into the field.
    • Stored Value: If the nonce in a stored value, as is often the case with One-Step Actions, set a One-Step Action to run on publish of the solution and prompt the user for the value. This allows encryption to happen via a One-Step Action, rather than directly providing a stored value that contains plain-text sensitive data.
  • Data String (field or stored value): This string needs to be entered via a One-Step Action because a modifier must be applied to encrypt the string. If storing the data on a record, an action on the form can add the value. If it's in a stored value, a One-Step Action ran on publish of the One-Step Action can prompt the user for the value and encryption can happen then.

Once you encrypt the string with an encryption key and nonce, you will need these exact values to decrypt it.

Encryption Key and Nonce (Cherwell-Generated)

Data strings of a sensitive nature should be encrypted and stored in CSM in the Business Object field. With every request to the other system, the string must be decrypted at the point of use. 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 add 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 per account record as a stored value, depending on the situation. If the string you want to encrypt is stored on a Business Object record, the nonce used for encryption should live on the record as well. If the string you want to encrypt is in a stored value, then your nonce should also be a stored value.
Note: Each solution that uses a stored value nonce should include its own stored value. This minimizes the impact of a nonce changing or being compromised.

Security and Scope

All configuration to the data string 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 data string should be scoped so that only appropriate users can read and modify the values.

Create Fields for Storing the Data String and Nonce

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

To create the text fields:

  1. In CSM Administrator, create or edit a Blueprint, and then open the Business Object.
  2. Add a text field for the external key. The key is populated through the One-Step Action that you create in the following step.
  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 100 characters. The default length is 15 characters.
  5. Save and publish your changes.

Create 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 external key and passes 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.

The default expression must have the "Terminate parent One-Step Actions and Action Blocks" option disabled.

Note: 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 data string 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.