Teneo Developers

Encrypting user data in sessions

In conversations with bots, users are often in a position of giving out personal information. Keeping track of what personal data may be captured by the bot is therefore part of the normal development of bots. The Pre-logging script event can be used to anonymize personal data in a way where the functionality of the bot is not compromized. With the Pre-logging script we can:

  • Remove data before it leaves Teneo Engine
  • Redact, remove, or encrypt sensitive data

The following approach documents how you can use the Pre-logging event to encrypt all user data for use cases where your bot handles sensitive data. We are using asymmetric (or public/private key) encryption, as this enables the bot to encrypt using the public key and allows you - as the developer - to keep the private key safe for decryption. This means that the user data stored is never visible in Teneo.

Please note that this comes with the downside that this is not visible when analyzing the data from your bot, and you will need to accomplish this from outside Teneo. The steps below will show you how you can accomplish this.

Setup Structure

Below you will wind the setup structure for this method:

encrypt-view

This setup follows the current best practice by using RSA, OAEP with SHA-256 and MGF-1 padding. This is a standard approach and can be used from modern environments. We've supplied a groovy script for convenience that can be found below.

We are prefixing and suffixing all encrypted values with €€ to make it much easier to search and replace for when decrypting.

Generating keys

As the first step, we need to generate both a private and a public key that will be used to decrypt the logs. This will be done with the help of OpenSSL.

  1. Use OpenSSL and generate your private key with the following line:
  • openssl genpkey -out privatekey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048
  1. Make sure you store the generated file somewhere safe.
  2. Now it is time to generate a public key by using the following command:
  • openssl rsa -in privatekey.pem -outform PEM -pubout -out publickey.pem

We will now proceed with uploading the publickey.pem to your solution as a file resource with the path /script_lib,

  1. Return to the Teneo solution you were in and click on 'Solution' in the upper left corner.
  2. Select 'Resources' on the left.
  3. Select 'File' at the top.
  4. Use 'Add' on the upper right to add the publickey.pem file. (Alternatively, you can drag and drop it.)
  5. Set the 'Published Location' for this file from / to /script_lib. This ensures the file can be accessed using a Groovy script later.
  6. Hit 'Save'.

Lastly, repeat the same steps and download the StringEncryptor class from StringEncryptor, and upload it into Teneo Studio as a file resource, with the path /script_lib.

Pre-logging event

Finally, we will add a Pre-logging script to access the files created above and redact the logs.

  1. Select the 'Scripts' tab at the top.
  2. While inside the 'Scripts' tab, select 'Pre-logging' and click on the 'Edit' button in the top right. This will open a new window where you can insert your script.
  3. Add the following code into the editing window:

groovy

1def encryptor = new StringEncryptor()
2
3_.getDialogHistoryUtilities().replaceLogVariables(encryptor.variableReplacer())
4_.getDialogHistoryUtilities().replaceMetadata(encryptor.variableReplacer())
5_.getDialogHistoryUtilities().replaceResponseVariables(encryptor.variableReplacer())
6
7_.getDialogHistoryUtilities().replaceRequestParameters(encryptor.parameterReplacer())
8_.getDialogHistoryUtilities().replaceResponseVariables(encryptor.parameterReplacer())
9
10_.getDialogHistoryUtilities().replaceUserInputText(encryptor.valueReplacer())
11_.getDialogHistoryUtilities().replaceResponseText(encryptor.valueReplacer())
12_.getDialogHistoryUtilities().replaceResponseURL(encryptor.valueReplacer())
13
14_.getDialogHistoryUtilities().replaceVariables(encryptor.objectVariableReplacer())
15

Please note that this code will encrypt all session data. The non-user session log data is kept, so that a Studio user can still see e.g. which flows has been raised or that a users name was captured, but is unable to see details (without the private key). Please edit the code if you want things such as folder name and flow name to be encrypted as well.

Testing

Make sure there are no errors in your solution before continuing to the next step. This can be done by chatting with the bot in Tryout and verifying that you don’t have any compilations errors:

  1. Return back to the main solution view. If the Tryout panel is not visible, make it appear by clicking the 'Tryout' button on the right side of the window.
  2. Make sure to click on 'Reload Tryout' if shown.
  3. Try to write a couple inputs like,
  • Hello
  • How are you?
  • Goodbye
  1. If you see a warning box appear, please go back and redo the steps above.

More on debugging your solution with Tryout can be found here.

Once you have verified that there are no errors, proceed with publishing your bot:

  1. Click the ‘Solution’ button in the upper left corner.
  2. Select the 'Publish' button. This will take you to the publish page for your bot.
  3. Click the 'Manage' button and, in the drop-down, choose 'Publish' under 'Latest'.
  4. You might see the warning Publish to 'Default env' stopped with warnings appear.

publish-error-2

This is nothing to worry about; the warning is shown when you publish your solution for the first time or when you have made certain global changes. To proceed, just check the checkbox 'Perform full application deployment on try again' and click the 'Try again' button.

  1. Once published, click on the blue 'Open' icon. This will open the published solution in a new browser tab.

It is important to acknowledge that conversations from here will be logged in your Log Data Source that can be accessed from your solution.

  1. Go ahead and try some small talk, like:
  • Hello
  • How are you?
  • My name is John
  • What is my name?
  • I like you
  1. Close the chat window to end the session.

See the logs

You can find the logged sessions inside your solution by checking out the session using the Session Viewer tab in Studio.

  1. Return back to the solution.
  2. Navigate to Optimization and select the tab 'Log Data'.
  3. Open the 'LDS' window (select the option Open under Manage Source).
  4. Click the button 'New Session Viewer Tab'.
  5. Under Order By select the options End Date and Descending.
  6. Click the Run Query button.
  7. Open the topmost session in the query results to view the details of the session.

All user data should now be encrypted, looking something like this:

encrypted-logs

Retrieving sessions from Inquire

As mentioned earlier in the text, using this method will not allow you to read the logs from Teneo itself. Instead you need to extract them and decrypt it from your computer. Lets proceed with retrieving the sessions from Inquire.

  1. Go ahead and download the following zip file: teneo-retrieve-inquire-sessions.zip.
  2. Unzip the package and setup an .env file using the .env_sample.
  3. Open up your command line and navigate to the relevant folder.
  4. Run npm install, yarn install, or bun install to download the dependencies.
  5. Finally, run node index.js to retrieve the sessions. The code will create one .json file per session retrieved.

Be aware that code will only return the sessions captured the previous hour. It is recommended to run this code hourly to retrieve all sessions.

Decrypting the sessions logs

As the final step, we need to decrypt the session logs. This can be done by using the decrypt.groovy file on the created .json files.

  1. Download the decrypt.groovy file and place it under the same folder your keys are in.
  2. Run the following script to decrypt the sessions.
  • groovy decrypt.groovy [path with sessions] [output directory].

Congratulations, you have now decrypted your session logs.