This documentation is for an older version of HVR.

Configuring and Managing Hub Wallet

Since v5.6.5/5

This section describes the steps to create, enable, disable, delete, rotate encryption key, migrate wallet, or configure the hub wallet.

The argument hubdb used in the command examples specifies the connection to the hub database. For more information about supported hub databases and the syntax for using this argument, see Calling HVR on the Command Line.

Creating and Enabling Hub Wallet

To use the hub wallet and encryption feature of HVR, first the hub wallet should be created and then the encryption enabled by defining the encryption data category.

Creating and Enabling Software Wallet

Following are the steps to create and enable the software wallet:

Create software wallet. Set the wallet password and the wallet type. Following is the command (hvrwalletconfig) to set the wallet type as SOFTWARE.
```
hvrwalletconfig -p hubdb Wallet_Type=SOFTWARE
```
After executing this command, a prompt asking to set a password for the software wallet will be displayed.
Enable encryption. Following is the command that will instruct HVR to start encryption of data (this includes the existing data in the hub database). The category of data to be encrypted depends on the property Encryption defined in this command.
```
hvrwalletconfig hubdb Encryption=category_of_data
```

Creating and Enabling KMS Wallet

Following are the steps to create and enable the KMS wallet:

Set the wallet password and the wallet type. Select your preferred credential method for the KMS wallet:
- If the authentication method is KMS Access Key Id, following is the command (hvrwalletconfig) to set the wallet type as KMS. The KMS connection properties Wallet_KMS_Region, Wallet_KMS_Customer_Master_Key_Id, Wallet_KMS_Access_Key_Id should be defined in this command.
```
hvrwalletconfig -p hubdb Wallet_Type=KMS Wallet_KMS_Region=eu-west-1 Wallet_KMS_Customer_Master_Key_Id=1234abcd-12ab-1234590ab Wallet_KMS_Access_Key_Id=AKIAJDRSJY123QWERTY
```
  After executing this command, a prompt asking to set a password for the hub wallet will be displayed. The password for the KMS (secret key) should be supplied.
- If the authentication method is KMS IAM role, following is the command (hvrwalletconfig) to set the wallet type as KMS. The KMS connection properties Wallet_KMS_Region, Wallet_KMS_Customer_Master_Key_Id, Wallet_KMS_IAM_Role should be defined in this command.
```
hvrwalletconfig hubdb Wallet_Type=KMS Wallet_KMS_Region=eu-west-1 Wallet_KMS_Customer_Master_Key_Id=1234abcd-12ab-1234590ab Wallet_KMS_IAM_Role=PRODROLE
```
  For KMS IAM role, since the authentication is done based on the AWS IAM Role, hvrwalletconfig option -p is not required in the command. For more information, see description for the KMS Wallet in section Hub Wallet Types of Hub Wallet and Encryption.
Enable encryption. Following is the command (hvrwalletconfig) that will instruct HVR to start encryption of data (this includes the existing data in the hub database). The category of data that is encrypted depends on the property Encryption defined in this command.
```
hvrwalletconfig hubdb Encryption=category_of_data
```

Verifying Hub Wallet Status

This section describes the steps/commands to check the hub wallet status (whether active or not, type of the wallet and encryption configured).

Following is the command (hvrwalletconfig) to check the hub wallet status.

hvrwalletconfig hubdb

For example,

hvrwalletconfig -h oracle myhub/myhub

Sample outputs:

The following is displayed when Wallet not configured.

hvrwalletconfig: HVR 5.7.6/0 (linux_glibc2.17-x64-64bit)
Encryption=NONE

The following is displayed when Software wallet is configured with SECRETS_ONLY encryption.

hvrwalletconfig: HVR 5.7.6/0 (linux_glibc2.17-x64-64bit)
Encryption=SECRETS_ONLY
Wallet_Type=SOFTWARE
Encryption_Key_Filename=hvrwallet-6177f115.p12
Encryption_Key_Sequence=1

Auto-Open Password

This section describes the steps/commands to enable or disable the auto-open password method for supplying the wallet password. For more information the about auto-open password method, see section Methods to Supply Wallet Password in Hub Wallet and Encryption.

Enable Auto-Open Password

To enable the auto-open password method, option -P of the hvrwalletconfig command is required. Following is the command to enable auto-open password method:
```
hvrwalletconfig -p -P hubdb
```
After executing this command, a prompt asking to supply the wallet password is displayed.

Disable Auto-Open Password

To disable the auto-open password method, the property Wallet_Auto_Open_Password should be left blank. Following is the command to disable auto-open password method:
```
hvrwalletconfig -p hubdb Wallet_Auto_Open_Password=
```

Auto-Open Plugin

This section describes the steps/commands to enable or disable the auto-open plugin method for supplying the wallet password. For more information about the auto-open plugin method, see section Methods to Supply Wallet Password in Hub Wallet and Encryption.

Enable Auto-Open Plugin

To enable the auto-open plugin method, the property Wallet_Auto_Open_Plugin should point to the plugin file directory. Following is the command to enable auto-open plugin method:
```
hvrwalletconfig hubdb Wallet_Auto_Open_Plugin=/home/user/myplugin.sh
```

Disable Auto-Open Plugin

To disable the auto-open plugin method, the property Wallet_Auto_Open_Plugin should be left blank. Following is the command to disable auto-open plugin method:
```
hvrwalletconfig hubdb Wallet_Auto_Open_Plugin=
```

Rotating Hub Encryption Key

This section describes the steps/commands to rotate the hub encryption key and also view and manage the hub encryption key history. For more information, see section Hub Encryption Key Rotation in Hub Wallet and Encryption.

Following is the command to rotate the hub encryption key:
```
hvrwalletconfig -r hubdb
```
Following is the command to view the hub encryption key history sequences and rotation timestamps:
```
hvrwalletconfig hubdb Encryption_Key_History
```
Following is the command to view the sequence number of the current hub encryption key:
```
hvrwalletconfig hubdb Encyption_Key_Sequence
```
Following is the command to view the entire wallet configuration, including history and other wallet settings:
```
hvrwalletconfig hubdb
```

Migrating Hub Wallet

This sections describes the steps/commands for migrating the wallet. For more information, see section Hub Wallet Migration in Hub Wallet and Encryption.

Migrating to Software Wallet

Following is the command to migrate to the software wallet.

hvrwalletconfig -p -m hubdb Wallet_Type=SOFTWARE

Migrating to KMS Wallet

Following are the commands to migrate to the KMS wallet:

To migrate to a KMS wallet with authentication method as KMS Access Key Id,

hvrwalletconfig -p -m hubdb Wallet_Type=KMS Wallet_KMS_Region=eu-west-1 Wallet_KMS_Customer_Master_Key_Id=1234abcd-12ab-1234590ab Wallet_KMS_Access_Key_Id=AKIAJDRSJY123QWERTY

To migrate to a KMS wallet with authentication method as KMS IAM role,

hvrwalletconfig -m hubdb Wallet_Type=KMS Wallet_KMS_Region=eu-west-1 Wallet_KMS_Customer_Master_Key_Id=1234abcd-12ab-1234590ab Wallet_KMS_IAM_Role=PRODROLE

Changing Software Wallet Password

The password for the software wallet can be changed, if required.

Following is the command to change the password for the software wallet:
```
hvrwalletconfig -p -m hubdb
```
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.

Disabling and Deleting Hub Wallet

The hub wallet can be deleted if it is not required anymore or if the wallet itself is not accessible, etc. The hub wallet password is required for disabling and deleting the hub wallet. The artifacts (hub encryption key sequence and key history) can be deleted or retained while deleting the hub wallet.

If the wallet password is forgotten, the hub wallet can be deleted by following the steps mentioned in force deletion without wallet password.

Following are the steps to delete the software wallet:

Stop HVR Scheduler.
Disable encryption. Following is the command (hvrwalletconfig) that will instruct HVR to stop encrypting all passwords and also to decrypt the existing passwords in the hub database and obfuscate them.
```
hvrwalletconfig hubdb Encryption=NONE
```
Encryption cannot be disabled if the hub wallet is not accessible (due to a corrupted software wallet file or inaccessible KMS, etc) or if the wallet password is wrong/forgotten.
Delete the wallet. One of the following command (hvrwalletconfig) can be used to delete the hub wallet and artifacts.
- To delete only the hub wallet and retain the artifacts,
```
hvrwalletconfig -da hubdb
```
  In case the hub wallet is not accessible anymore (due to a corrupted software wallet file or inaccessible KMS), then use the following command to force delete the wallet and retain the artifacts:
  hvrwalletconfig -daf hubdb
- To delete the hub wallet and artifacts,
```
hvrwalletconfig -dA hubdb
```
  In case the hub wallet is not accessible anymore (due to a corrupted software wallet file or inaccessible KMS), then use the following command to force delete the wallet and the artifacts:
  hvrwalletconfig -dAf hubdb

Force Deletion Without Wallet Password

If the hub wallet password is forgotten, then use the following command to force delete the hub wallet:

Since encryption is not disabled before deleting the wallet forcefully, the information that were encrypted by using this wallet will have to be manually fixed by the user (for example, entering the password again in the location connection screen).
Artifacts is not retained when forcefully deleting a wallet without disabling the encryption.

Force delete the wallet and artifacts:
```
hvrwalletconfig -dAf hubdb
```
Set encryption to NONE. The following command is optional.
```
hvrwalletconfig hubdb Encryption=NONE
```
Setting encryption to NONE after deleting the wallet will not decrypt the passwords that were encrypted using the wallet. This command may be executed to avoid any problems while creating a new hub wallet in the future.