Versions Compared

Old Version 46

changes.mady.by.user John Brinckwirth

Saved on

compared with

New Version Current

changes.mady.by.user Shilpa

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

In this article

Table of Contents
maxLevel3

Overview

...

All SnapLogic endpoints use the Standard Encryption setting by default. As an Org admin using Groundplex instances to run your Pipelines, you can encrypt Account credentials that access endpoints from SnapLogic using data/server keys. 

...

titleMake Backup Copies of Your Data Keys

...

Organizations using self-managed Snaplexes (Groundplexes) can subscribe toEnhanced Encryption. With Enhanced Encryption, in contrast to Standard Encryption, organizations create their own private keys and do not share them with SnapLogic. The UI encrypts Account data with a public key and the Groundplex decrypts it with a private key.

Starting the Snaplex for the first time automatically generates the data keys. The keys need to be manually synced across the Groundplex nodes. The account data encryption keys are located in the /etc/snaplogic directory. The jcc-datakeys.jks file is the keystore and the jcc-datakeys.pass is the password for the keystore. The same set of keys should be used on all the Groundplexes nodes across the whole Org.

For TLS connections, the Snaplex also maintains SSL certificates. These are also in the /etc/snaplogic directory, the jcc-serverkeys.jks file is the keystore and jcc-serverkeys.pass is the password for the keystore. These should be unique for each node and, therefore, should not be synced across the Groundplex nodes. The certificates are not used for account encryption but for TLS connections only.

Workflow

To enable Enhanced Encryption, follow the high-level steps listed here. Find the detailed procedures below.

  1. A Snaplex administrator:

    1. Restarts the SnapLogic service on one Snaplex node to generate the keystores and password files.

    2. Copies the data keystore and data password file to the other nodes for each Snaplex node.

    3. Restarts all Snaplex nodes.

  2. In SnapLogic Manager, an Org admin:

    1. Enables Enhanced Encryption

    2. Selects the encryption sensitivity (sensitivity determines how many Account fields will be encrypted)

    3. Selects the public key. After Enhanced Encryption is enabled, an Org admin can rotate the key. Running Pipelines continue executing while the key is being rotated.

After Enhanced Encryption is enabled for an Org:

  • All Accounts are sent to the Groundplex to be decrypted with the old key and encrypted with the new key.

  • Encrypted Account fields do not display values, as shown below. However, you can change the value by entering and saving a new one.

    Image Added

  • If an Org admin changes the encryption sensitivity level from Low, Medium, High to High, existing accounts remain at the previous level unless you update them. Changing from High to Low, Medium, High causes account data to be encrypted. All new Accounts follow the updated sensitivity encryption level.

  • The encrypted data is not automatically decrypted if you revert from Enhanced to Standard encryption. The encrypted values continue to work as long as the server key is still in the node.

  • Accounts that were exported when the Org used the old key have the sensitive fields encrypted with the old key. When an Account is imported into the Org after the key is rotated, it is imported with the old key. To convert these imported accounts to the new key, go to Manager and redo the key rotation with the new key.

Best Practices

We strongly recommend the following:

  • Make backup copies of the generated data keystore and password files. Otherwise, if the data keys

...

  • become corrupted

...

  • and unrecoverable,

...

  • you must manually re-

...

  • enter all sensitive Account field values to recover

...

titleBest Practice

...

  • connectivity.

  • Do not change an Org that uses Enhanced Encryption back to Standard Encryption. If you do so, existing OAuth 2.0 accounts

...

  • will not function

...

Enabling Enhanced Account Encryption

Prerequisites

  • ; you must re-create them.

Prerequisites

The following requirements must be met to use Enhanced Encryption.

  • Google Chrome version 37 and later

    .
  • A Groundplex. Windows and Linux machines are supported, but if you plan to host your Snaplex instances in an mixed ecosystem (Windows and Linux OS), the server and data keys must be encrypted on a Linux machine to be used on a Linux-based Snaplex. 
  • If you are using Linux, make sure you have the latest install of the RPM/DEB on each Groundplex node. 
  • A Java 11 environment.

Preparing Groundplex Nodes for Enhanced Encryption

...

  • .

  • A Java 11 environment.

  • For nodes deployed on Linux OS, the latest version of the RPM/DEB SnapLogic installer. 

  • Snaplexes can be deployed either on Windows or Linux operating systems. However, for a Snaplex on the Windows OS, you must encrypt the data keys on a Linux machine and copy it to the nodes running on Windows.

Limitations

  • The script that generates and updates the data keystore is supported only on Linux OS. You can generate the keystore and password file on a Linux machine and copy them to a Windows machine. If all of a self-managed Snaplex’s nodes are on Windows machines, install the Linux RPM (Snaplex installation package) on a Linux machine solely for the purpose of generating or updating the key store using the jcc.sh script.

  • To use Enhanced Encryption, an Org cannot have a mixture of self-managed Snaplexes and those managed by SnapLogic. Before enabling Enhanced Encryption, work with SnapLogic support to remove Cloudplexes from the Org or convert them to Groudplexes.

Preparing Snaplex Nodes for Enhanced Encryption

Enhanced Encryption key sizes are not supported in the SnapLogic managed Snaplex installation. After restarting the SnapLogic service, a new key pair is generated automatically and saved to disk, per JCC node. You must copy the generated data keys files (, jcc-datakeys.jks and jcc-datakeys.pass), from one node to all of the others in the for that Groundplex. 

Note
title

Server Keys

Server keys (jcc-serverkeys.jks and jcc-serverkeys.pass) must be unique per JCC node. Do not copy server keys across all nodes.

...

On Linux Operating Systems

To enable Enhanced Encryption on a Linux machine, follow these steps:

  1. On

...

  1. the machine hosting a node, restart the node.

  2. Find the keys in the  /etc/snaplogic folder.

...

  1. Copy the jcc-datakeys.jks and jcc-datakeys.pass files to the machines hosting the other Snaplex nodes

...

  1. .

  2. Restart the SnapLogic service on each node.

During startup, the nodes upload their public keys to the SnapLogic cloud.

...

Org admins can view the keys

...

in the Encryption Settings dialog.

...

On Windows Operating Systems

As mentioned previously, you must generate the data keys on a Linux machine by downloading a Linux installation package and starting a node. To prepare nodes on Windows machines:

Note
title

Recommendation

Data keys are the same across JCC nodes; however, the server keys are unique for each JCC node. You should generate the data keys on a Linux machine and copy them to the folder pointed to by the SL_KEY_DIR folder property on the Windows machine. Only the security administrators and users that run the Groundplex service  Only the system admins on the node must have access to the this directory.

...

  1. Find the jcc-datakeys.jks

...

  1. and jcc-datakeys.pass

...

  1. in the /etc/snaplogic folder of the Linux machine.

  2. Copy the data key files to a directory on the Windows machine that only security administrators and users running the Snaplex node can access. 

  3. Add the directory name as the value of a new SL_KEY_DIR

...

  1. Java property in the Snaplex configuration file:

    1. Navigate to the target Snaplex in Manager

...

    1. and

...

    1. click to open it.

    2. Click the Node Properties tab, and under Global Properties, click 

...

    1. Image Added

       to enter the key-value pair.

    2. Add the following in the Snaplex property

...

Paste code macro
themeAgate
jcc.jvm_options = -DSL_KEY_DIR=c:\\snaplogic_keys

Image Removed

...

    1. , where Value is the location of the data keys. For example:

      Image Added

    2. Click Update.

  2. Restart the

...

  1. SnapLogic service on all

...

  1. nodes with the updated slpropz configuration.

...

Enabling Enhanced

...

Encryption

...

in SnapLogic

Before enabling Enhanced Encryption, verify that the same data key is used on all nodes for a given Snaplex. To configure Enhanced Account Encryption on a Groundplex for your SnapLogic Org:

  1. Log in as an Org admin and navigate to Manager

...

  1. .

  2. From the left menu, select Settings.

  3. Scroll to Account Data Encryption and click Configure Encryption.

...

  1. Image Added

  2. On the Groundplex tab of Encryption Settings

...

  1. ,

...

  1. select Enhanced encryption.

...

Verify that the same key is used on all nodes of the Groundplex; otherwise, you cannot configure the Org with Enhanced Encryption because all keys used across an Org must be consistent

  1. Select the level of sensitivity

...

  1. :

...

  1. Image Added

    High. Encrypts passwords and secret keys
    Medium and High. Encrypts usernames, passwords, and secret keys
    Low, Medium, and High. Encrypts host name, database names, database URL properties, usernames, passwords, and secret keys.

...

...

 To learn about which fields are encrypted for an Account, see the sensitivity level definition in the Account’s documentation for that Snap Pack.

  2. To set a key for the entire Org, select the target key. Only

...

  1. keys that are available on all nodes are displayed.

  2. Confirm the new key. This configuration causes all accounts to be decrypted using the existing keys and then re-encrypted with the newly selected Org-level key.

  3. Click Update to apply enhanced encryption. 

When you view the Org Settings, the new Status displays status is displayed under Configure Encryption with the following fields:Image Removed

Scope and Limitations

  • Once Enhanced Account Encryption is enabled, you are not be able to see or edit the existing values for the encrypted data types.

Image Removed

However, you are able to enter a new value in that field and save it.

  • If you change your sensitivity level from Low, Medium, High to High, existing accounts remain at the previous level unless you update them; going in the other direction causes account data to be encrypted. All new accounts follow the new sensitivity encryption level.
  • If you revert to standard encryption, the encrypted data is not automatically decrypted. As long as the server key is still in the node, the encrypted values continue to work.

Key Rotation

...

 

Groundplex processing status

Status

Indicates if the Groundplex processing has been successfully executed without encountering errors or issues.

Description

The number of accounts encrypted and processed out of the total number of accounts.

Last Update

The timestamp of the last update or completion of the Groundplex processing operation.

Rotating Private Keys

To rotate the Enhanced Encryption key, follow these steps:

  1. Install the latest

...

  1. Snaplex RPM/DEB installation package on one of the Groundplex nodes

...

  1. that is already

...

  1. using Enhanced Encryption. This step is required to get the new addDataKey option in the jcc.sh script.

  2. As the root user, run the following command

...

  1. .

...

  1. This command

...

  1. generates a new key pair and

...

  1. appends it to the keystore

...

  1. in the /etc/snaplogic folder with the specified alias

...

  1. . In the example, the alias is keyFeb2020:

    Code Block
    /opt/snaplogic/bin/jcc.sh addDataKey keyFeb2020

  2. Copy the generated data keys files (jcc-datakeys.jks and jcc-datakeys.pass) from this node to all the others

...

  1. for the

...

  1. Snaplex, similar to when originally setting up

...

  1. Enhanced Encryption.

  2. Restart the nodes

...

  1. . This step is required to pick up the updated key pair.

...

  1. To do an online restart, use the Snaplex restart option in the Dashboard.

...

When all

...

nodes

...

run with the new key pair

...

, the Enhanced Encryption settings display the drop-down list, allowing the Org admin to change to the new key.

After you enable Enhanced Encryption on your Groundplex nodes:

  • Currently running Pipelines continue when the key is being rotated.

  • Accounts in the organization are sent to the Groundplex to be decrypted with the old key and then encrypted with the new key.

  • Accounts that were exported when the Org ran with the old key have the Sensitivity fields encrypted with the old key. When the account information is imported into the Org after the key is rotated, the account is imported with the old key. To convert these imported accounts to the new key, go to Manager and redo the key rotation with the new key.
  • The updates to the key store using the script are supported only on a Linux-based Groundplex machine. The updated key store can be copied to the Windows-based Groundplex machine to ensure that the rotated key is applied on the Windows machine as well. If using a Groundplex on Windows only, you can install the Linux RPM on a stand-alone machine for the purpose of updating the key store using the jcc.sh script.

Adding Groundplex Nodes

...

Adding new Nodes to the Snaplex

When you add nodes to a self-managed Snaplex, the new nodes must have the same encryption key as the others. If the new node does not have a matching key, it is ignored until the keys are synchronized . You can redo the configuration through the Enhanced Encryption Settings dialog in the and the JCC is restarted. All nodes' current configuration can be checked in Manager > Settings > Configure Encryption by checking the current key compatibility status.

Updating Windows Groundplex Instances to Use an Encrypted Keystore

To .

Special Use Case: Adding Linux Nodes to an Org Where Keys Were Generated on a Windows Node

The recommended procedure to enable Enhanced Encryption on Windows Groundplex instances , the recommended procedure is to generate the keys on a Linux machine and then copy them onto the Windows node. The advantage is that the generated keystore is encrypted, and the same keystore can be used on both Windows and Linux nodes.

If there are existing For Windows installations with Enhanced Encryption where the key was not initially generated in Linux, adding additional steps are required to add new Linux-based nodes require these additional steps, . This is because, in such cases, there would be a datakeys.jks file under the etc folder, with no .pass file. To prepare the keystore to be used on Linux machines:

  1.  Copy the keystore datakeys.jks from the Windows machine to the Linux machine and place it in /etc/snaplogic/jcc-datakeys.jks.

  2. Perform the following steps as the root user on the Linux node (change the JRE version as appropriate).

...

languagebash
themeAgate

  1.  

    Code Block
    # Perform

...

  1. the operations below as root user
# Copy the datakeys.jks file from windows to the Linux machine, file should be placed at /etc/snaplogic/jcc-datakeys.jks
export JRE_HOME=/opt/snaplogic/pkgs/jdk-11.0.8+10-jre
cd /opt/snaplogic
# Generate password file with a secure password. Change RANDOM_SECURE_PASSWORD to a secure password to use for the keystore
export MYPASS=

...

  1. `openssl rand -base64 32`
echo -n $MYPASS  > /etc/snaplogic/jcc-datakeys.pass
# Encrypt the keystore with the new password

...

  1. $JRE_HOME/bin/keytool -storepasswd -new $MYPASS -keystore /etc/snaplogic/jcc-datakeys.jks  -storepass ""
# Encrypt the key with the same password

...

  1. $JRE_HOME/bin/keytool -keypasswd -alias account-autogen -new $MYPASS -keystore /etc/snaplogic/jcc-datakeys.jks -storepass $MYPASS -keypass ""

...

  1.  
The keystore is now in a format suitable for use on Linux machines. You can now copy the same The jcc-datakeys.jks  and jcc-datakeys.pass files can be copied to other Linux-based nodes without having to repeat repeating the prior steps in this section.  We also recommend that you update the original Windows node to run with this encrypted keystore by setting the setting the SL_KEY_DIR property described in Using a Windows Machineas described in On Windows Operating Systems.