Hub Wallet and Encryption

Since v5.6.5/5

The hub wallet is an advanced method for secure password encryption and storage. When you enable the hub wallet, all user passwords in HVR are encrypted using a modern AES256 encryption scheme and then stored in the hub database. The hub encryption key used for encryption is stored in the hub wallet. The hub wallet can be a software wallet file which is encrypted by a wallet password, or a KMS account (AWS). For more information, see Hub Wallet Types.

Hub wallet is not a replacement for Encrypted Network Connection. Hub wallet and Network connection encryption should be used together for best security.

Benefits of using the hub wallet:

• Without the hub encryption key, anyone who has access to the hub database cannot decrypt the passwords stored in the hub database.
• HVR sends these encrypted passwords over the network to other HVR processes. If the connection is intercepted and the messages are accessed, it will not be possible to decrypt the sensitive information (like password) without the hub encryption key.

If the hub wallet is not configured and enabled, a less secure method is implemented. All user passwords in HVR are obfuscated (using a password obfuscation method) and stored in the hub database. If either of the following happens, unauthorized access to the hub database or the network connection is intercepted and the messages are read, the obfuscated passwords may be obtained and de-obfuscated.

For the steps to set up the hub wallet, see Configuring and Managing Hub Wallet.

HVR commands such as HVR GUI, HVR Remote Listener, HVR Scheduler, or a job (such as capture, integrate running under scheduler) are separate HVR processes that take part in encryption.

Hub Wallet Configuration File

The hub wallet configuration file (HVR_CONFIG/files/hvrwallet-hubname/hvrwallet-tstamp.conf) is required for managing (creating, enabling, disabling, deleting) the hub wallet. It contains the configuration properties for the hub wallet like encryption type, wallet type, encryption key history, and information related to the KMS. The properties that can be saved/configured in the hub wallet configuration file differ based on hub wallet type. For more information about the properties that can be configured in the hub wallet configuration file, see section Properties in hvrwalletconfig. The hub wallet configuration file is a plain text file which must only be updated using the command hvrwalletconfig. If this file is updated using a normal text editor, it could corrupt the wallet configuration file or lead to improper functioning of hub wallet. The timestamp in the hub wallet configuration file name is time when the hub wallet configuration is created. Each time the hub wallet configuration is updated, the hub wallet configuration file name gets a new timestamp.

Prior to HVR 5.7.0/0, the hub wallet configuration file name and path was HVR_CONFIG/files/hvrwallet-hubname-timestamp.conf

How It Works

Whenever an HVR process running on the hub (called as hub process in this article) needs the hub encryption key (to encrypt/decrypt data), it looks into the hub wallet configuration file to determine the hub wallet type and other required information related to the hub wallet. The hub process then opens the hub wallet by supplying the wallet password and fetches the decrypted hub encryption key into this hub process's memory. A decrypted hub encryption key is never stored on the disk.

Since the wallet password is stored in the process memory, whenever the HVR Scheduler is restarted, the wallet password is lost from its memory.

Methods to Supply Wallet Password

The wallet password must always be supplied for opening the hub wallet. Following are the different methods for supplying the wallet password:

• Manual (default): In this method, the user needs to supply the wallet password manually. The hub process waits for the wallet password until the user supplies it manually. The wallet password may be supplied:

  • In the HVR GUI, the hub process asks for the wallet password interactively. This is the GUI for the command hvrwalletopen.
  • Through the CLI, the hub process waits indefinitely for the user to supply the wallet password. The user needs to supply the wallet password using the command hvrwalletopen.

• Auto-Open Password: In this method, intervention from the user is not required; instead the wallet password is supplied by automatically fetching it from the wallet configuration file. The wallet password is stored obfuscated in the hub wallet configuration file. This method is good for a situation where user intervention is not desirable after a system restart, however, it is less secure to have the wallet password stored in the wallet configuration file.
  To enable or disable this method, see section Auto-Open Password in Configuring and Managing Hub Wallet.

  If this method is used together with the software wallet, the backup of the files involved (wallet configuration file and software wallet file) should be taken at the same time. It is recommended to save/store the backups in separate locations to prevent the security threat involved in case one backup is compromised.

• Auto-Open Plugin: In this method, intervention from the user is not required; instead the wallet password is supplied by automatically executing a user defined plugin/script. The hub process can execute a user defined plugin/script to obtain the wallet password. Here, the wallet password may be stored obfuscated in the hub wallet configuration file or else it can be stored on a separate machine in the network. If the wallet password is stored on a separate machine, the user defined plugin/script can be used to fetch it from that machine.
  An example plugin:

  #!/bin/sh
  echo mywalletpassword | $HVR_HOME/bin/hvrwalletopen
  

  To enable or disable this method, see section Auto-Open Plugin in Configuring and Managing Hub Wallet.

Classification of Data

Data/information in HVR is logically classified so that it can be used and protected more efficiently. Classification of data is based upon the sensitivity of the data and the impact it can have on the user/business should that data be accessed without authorization or be misused.

All data in HVR is classified into one of the following sensitivity levels, or categories:

• Secret: Unauthorized access/misuse of data in this category could cause a severe level of risk to the user/business. This category typically includes the passwords and private keys used for accessing/connecting to a database or technology.
• Confidential: Unauthorized access/misuse of data in this category could result in a moderate level of risk to the user/business. This category includes the user data like values in user-table that are part of replication, key-values exposed in error messages, and the files such as transaction (TX) files, diff files, intermediate files (direct file compare and online compare), .coererr file.
• Official: Unauthorized access/misuse of data in this category could result in a lesser risk (compared to Confidential) to the user/business. This includes the column names, timestamps and change metadata.
• Public: Data that is available in the public. This category includes the HVR product documentation.

Hub wallet supports encryption of Secret and Confidential data only. Also see hvrwalletconfig property Encryption.

Hub Wallet Types

HVR supports the following types of hub wallets:

1. Software Wallet: In this wallet type, the hub wallet is an encrypted (using PKCS #12 standard) and password protected file (HVR_CONFIG/files/hvrwallet-hubname/hvrwallet-timestamp.p12) that stores the hub encryption key. The password for the software wallet (file) should be supplied by the user while creating the software wallet.

   Prior to HVR 5.7.0/0, the software wallet file name and path was HVR_CONFIG/files/hvrwallet-hubname-timestamp.p12

   When the command to create the software wallet is executed, HVR creates a hub wallet configuration file and a software wallet file. It also generates a hub encryption key inside the software wallet file.

   Whenever the hub process needs the hub encryption key (to encrypt/decrypt data), it opens the software wallet by supplying the wallet password and fetches the decrypted hub encryption key from the software wallet file (.p12) and then stores it in the hub process's memory. Note that the hub encryption key is decrypted only after the wallet password is supplied.

   Whenever the hub encryption key is rotated or the software wallet password is changed, the hub encryption key is actually migrated to a new software wallet.

2. KMS Wallet: In this wallet type, the hub wallet is a network service (AWS KMS) that encrypts the hub encryption key. The encrypted hub encryption key is stored in the hub wallet configuration file. The KMS wallet is protected either by the AWS KMS credentials or the AWS IAM role, which should be supplied by the user while creating the KMS wallet.

   When the command to create the KMS wallet is executed, HVR contacts KMS using the credentials supplied/configured. The KMS then generates the hub encryption key, encrypts it, and then sends it to HVR. HVR will save the hub encryption key in the wallet configuration file. Depending on the authentication method chosen for the KMS wallet, the KMS Access Key Id or KMS IAM Role should be supplied with the KMS wallet create command, this will be saved in the wallet configuration file.

   • If the authentication method is KMS Access Key Id, the wallet password is the secret access key of the AWS IAM user used for connecting HVR to KMS.

   • If the authentication method is KMS IAM Role, there is no separate wallet password required since the authentication is done based on the AWS IAM Role. This authentication mode is used when connecting HVR to AWS S3 by using AWS Identity and Access Management (IAM) Role. This option can be used only if the HVR remote agent or the HVR Hub is running inside the AWS network on an EC2 instance and the AWS IAM role specified here should be attached to this EC2 instance. When a role is used, HVR obtains a temporary Access Keys Pair from the EC2 machine. For more information about IAM Role, refer to IAM Roles in AWS documentation.

   Whenever the hub process needs the hub encryption key (to encrypt/decrypt data), it fetches the encrypted hub encryption key from the wallet configuration file and sends it to AWS KMS. The KMS then decrypts the hub encryption key and sends it back to HVR, which is then stored in the hub process's memory.

   For the KMS wallet which is based on the KMS Access Key Id authentication, the wallet password is changed whenever the KMS credential (secret access key of the IAM user) is updated.

Hub Encryption Key Rotation

The hub encryption key should periodically be rotated to meet the cryptographic best practices and industry standards. Rotating the hub encryption key is when you retire the existing key and replace it with a newly generated key. The hub encryption key rotation helps to keep data leaks bounded in case the hub encryption key is stolen/compromised.

When the command to rotate the hub encryption key is executed, the following process takes place:

1. Generate new hub encryption key.

2. Decrypt catalog table data with the old hub encryption key.

3. Encrypt catalog table data with the new hub encryption key.

The hub encryption key rotation does not re-encrypt data outside of HVR catalogs such as Job scripts, Windows services, UNIX crontabs, and HVR GUI configuration. These non-catalog items (services) have the hub encryption key in their memory. When the hub encryption key is rotated, the process memory will still have the old key. To obtain the new key, the non-catalog items (services) need to be restarted by the user manually, and for services that store the key, the script or service must be recreated.

After the hub encryption key rotation, the old hub encryption key is deactivated, encrypted with the newest key, and retained. It is retained to decrypt the data that was encrypted using the old hub encryption key. During the rotation and a short time afterwards, the old hub encryption key still needs to be available for HVR. After the rotation, it might be needed for non-catalogs items such as Job scripts, Windows services, UNIX crontabs, and HVR GUI configuration.

The hub encryption key has a unique sequence number to maintain the history or keep track of all versions of the hub encryption key.

History

The old hub encryption keys are stored in the hub wallet configuration file, which is protected with the new hub encryption key. HVR keeps the history of hub encryption key in the hub wallet configuration file in a JSON format.

The old/history hub encryption keys retained in hub wallet configuration file can be purged/deleted (hvrwalletconfig option -d or -S or -T) to avoid compromise/leakage of these keys.

Hub Wallet Migration

Moving the hub encryption key from one wallet to another is called wallet migration.

Following are the two modes of wallet migration:

• Wallet migration with the same hub encryption key
  In this mode, during the wallet migration, the hub encryption key does not change; instead only the wallet storage is changed. The encrypted wallet storage is first decrypted and the hub encryption key is moved to the new wallet that is encrypted. During wallet migration, both the old wallet and new wallet must be available simultaneously while the encryption key is decrypted. After the wallet migration completes, the old wallet is discarded.

• Wallet migration with a new hub encryption key
  In this mode, during the wallet migration, the hub encryption key is replaced (rotated) with a new hub encryption key and the wallet storage is changed. The encrypted wallet storage is first decrypted and the hub encryption key is rotated and then it is moved to the new wallet that is encrypted. During wallet migration, both the old wallet and new wallet must be available simultaneously while the encryption key is decrypted. After the wallet migration completes, the old wallet is discarded.

See also, hvrwalletconfig (option -m), and section Migrating a Hub Wallet in Configuring and Managing Hub Wallet.

Migration Scenarios

The following scenarios/conditions lead to the migration of hub wallet.

In the software wallet, migration happens if a user:

• Switches to another wallet type.

• Changes the wallet password.

  • When the command to change the software wallet password is executed, HVR creates a new wallet file (.p12) with a new password and then moves the hub encryption key from the existing wallet file to the new file. This is the reason for using hvrwalletconfig with option -m while changing the software wallet password.

• Rotates the hub encryption key.

  • When the hub encryption key is rotated, the existing hub encryption key stored in the software wallet file (.p12) is retired and it is replaced with a newly generated hub encryption key in a new software wallet file.

In the KMS wallet, migration happens if a user:

• Switches to another wallet type.

• Changes KMS credentials and uses hvrwalletconfig with option -m.

  • If option -m is not used, the KMS credential change is considered as a configuration update. The updated configuration is saved in the wallet configuration file.

• Changes KMS Customer Master Key (CMK) ID and uses hvrwalletconfig with option -m.

  • If option -m is not used, the KMS CMK ID change is considered as a configuration update. The updated configuration is saved in the wallet configuration file.

During the migration, the old KMS account will be accessed by HVR for decryption.

See Also

• Configuring and Managing Hub Wallet

• hvrwalletconfig

• hvrwalletopen

• Encrypted Network Connections