Enabling the enhanced password protection requires manual configuration. An administrator needs to use the password protection tool distributed with Dispatcher Paragon. The tool is able to generate a secret key, encrypt passwords and perform other operations. Read Password Protection Tool Manual for more information. 

Before using this guide, it is recommended to read Enhanced Password Protection for a general understanding of the feature.

Enabling of Enhanced Password Protection

Enabling the enhanced password protection consists of these steps. 

1. Stop all Dispatcher Paragon services.
2. Generate a secret key. There are two possible alternatives:
   1. Manually generate a secret key.
   2. Setup automatic generation of a secret key.
3. Enable enhanced password protection in configuration files.
   
4. Manually encrypt selected passwords:
   1. Manually encrypt passwords in configuration files.
   2. Manually change database passwords in the database.
5. Start all Dispatcher Paragon services and check that all services started successfully.
   

You can check the sections below for more details about every step.

The enhanced password protection is enabled when the secret key is generated and Dispatcher Paragon is able to reach the configured file with the secret key. Dispatcher Paragon is able to recognize whether passwords in configuration files are obfuscated or encrypted and is able to process both versions. 

Stop all Dispatcher Paragon Services

Stop all Dispatcher Paragon services in the whole environment (Management Servers, Site Servers) except the Dispatcher Paragon Bundled PostgreSQL (available if an embedded PostgreSQL DB is used).

You can use the following PowerShell script to perform the task:

Manually generate a secret key

First of all, the key file needs to be initialized. All secret keys are stored in a file with a custom name. Use the command line tool data-protection.bat distributed in the following location:

<dispatcher_paragon_folder>\Management\utilities\data-protection-cli\bin

1. Find an appropriate location for the file where the secret key will be stored.

2. Provide the tool with the path for the file with the secret key. There are two options.

   1. Edit the KEY_PATH parameter in data-protection.bat batch file and set the path. 

      set KEY_PATH=C:/mycustompath/keys.txt

   2. Use argument -pathtokey with the path to the file with the secret key for all commands when using the tool.

      
      

3. Use the data-protection.bat tool with command initkeys to create the secret key. If the file for the key does not exist it will be created. 

   data-protection.bat initkeys

   
   

4. Check the output of the tool. 

   Key created in an existing file at C:/mycustompath/keys.txt
5. Now, you can use the secret key for passwords encryption.
   
   

Setup automatic generation of a secret key

The generation of a secret key can be automated. To do so, add configuration property dataProtection.enableAutomaticKeySetup into all configuration files to that you also add property dataProtection.pathToKey. Set the property to value true. The list of configuration files is in the section below.

Enable enhanced password protection in configuration files

Once you have generated the secret key the next step is to setup components of Dispatcher Paragon to use the enhanced password protection. An administrator can configure behavior of the enhanced data protection features per component via corresponding configuration file. It is recommended to protect passwords in all components.

See the table below to see which components can be protected. Enhanced password protection must be enabled for each component separately via given configuration file. 

The enhanced password protection is enabled by adding configuration property dataProtection.pathToKey with the path to the key file to each of the configuration files mention above. Typically, all components are supposed to have the same key file configured. If the property is not contained in the configuration file or is set to empty, the enhanced password protection is disabled. See the example below which enables the enhanced password protection:

The feature can be further tweaked per given component by following properties:

Enabling enhanced password protection in Management component

Follow the procedure below to enabling enhanced password protection in management component. You can do it analogically for other components. 

1. Ensure that Management Service and LDAP replicator Windows services are stopped. 
2. Edit configuration file safeq.properties.
3. Add property dataProtection.pathToKey and set value to the file with the secret key.
4. Optional: If you want to automatically generate the secret key then add property dataProtection.enableAutomaticKeySetup and set it to value true.
5. Optional: You can also configure cache behavior by adding property dataProtection.keyCachingSeconds.

Manually encrypt Passwords in Configuration Files

An administrator has to manually encrypt passwords and insert them into configuration file. Dispatcher Paragon is able to recognize encrypted passwords and decrypt them when needed. 

The list of all passwords which can be encrypted per given component via configuration file is below:

Please follow the procedure below to encrypt a passwords:

1. Ensure that relevant Dispatcher Paragon services are stopped.

   1. You can use following command.

      Get-Service*YSoft* | Where-Object { $_.Name -ne'YSoftPGSQL' -and $_.Name -ne 'YYSoftPGSQL' } | Stop-Service
2. Extract all passwords from configuration file which is to be encrypted.
3. Use the tool and encrypt a password. 
   1. 
      
      1. Run command line (cmd) as administrator.

      2. Use the tool and encrypt the password.

         data-protection.bat encrypt -name database.global.management.password
      3. The tool prompt you to insert password for encryption. Insert it and press the key <ENTER>.
4. Copy the encrypted password (output of the tool including the ENCSTR: prefix) and insert it into the configuration file. 

   1. Be careful and insert the encrypted password to the same property in configuration file you have used in argument -name. Example of protecting the property database.global.management.password in configuration file safeq.properties.

      database.global.management.password = ENCSTR:FgeW9YrHY+6tQ86uBi0AxLp6YjtvorbtENPng+M63FPuYsetgxfQQQ5+Pur14bk/
5. Repeat steps 3 and 4 till all passwords collected in step 2 are encrypted.  

Manually change Database Passwords in the Database

An administrator has to manually retrieve passwords from the database, encrypt them and then insert them back into the database. Dispatcher Paragon is able to recognize encrypted passwords and decrypt them when needed. 

1. Ensure that relevant Dispatcher Paragon services are stopped.

   1. You can use following command.

      Get-Service*YSoft* | Where-Object { $_.Name -ne 'YSoftPGSQL' -and $_.Name -ne 'YYSoftPGSQL' } | Stop-Service
2. Get password and tenant_guid for tenants from the database and write them down.
   1. SELECT tenants.db_pass, tenants.tenant_guid FROM cluster_mngmt.tenants;
      SELECT tenant_warehouses.db_pass, tenant_warehouses.tenant_guid FROM cluster_mngmt.tenant_warehouses;
3. Use the tool and manually encrypt all passwords.
   1. Run command line (cmd) as administrator.
   2. Run data-protection.bat with parameters:
   3. For each tenants.db_pass and tenants.tenant_guid from cluster_mngmnt.tenants table run.
      1. data-protection.bat encrypt -name tenants.db_pass

      2. The tool prompt you to insert password for encryption. Insert it and press the key <ENTER>.

      3. Write down the result of the encryption for tenants.db_pass (e.g. ENCSTR:HMHo9s/7STh0GWy1K6fmQHRgy4rspkCRBMOLwnE0rP2eZZMtxaEyoJ6uuXruD0Mx) and its tenant_guid (e.g. f900b632-aad8-4d99-ad98-33496f83812d).
      4. Repeat for the next tenant.
   4. For each tenant_warehouses.db_pass and tenant_warehouses.tenant_guid  from cluster_mngmt.tenant_warehouses table run.
      1. data-protection.bat encrypt -name tenant_warehouses.db_pass

      2. The tool prompt you to insert password for encryption. Insert it and press the key <ENTER>.

      3. Write down the result of the encryption for tenant_warehouses.db_pass (e.g. ENCSTR:HMHo9s/7STh0GWy1K6fmQHRgy4rspkCRBMOLwnE0rP2eZZMtxaEyoJ6uuXruD0Mx) and its tenant_guid (e.g. f900b632-aad8-4d99-ad98-33496f83812d).
      4. Repeat for the next tenant
4. Update passwords in the database by encrypted versions.
   1. UPDATE cluster_mngmt.tenants set db_pass = <encryptedPassForTenants> where tenant_guid = <tenantGuidFrom2ndStep>
      UPDATE cluster_mngmt.tenant_warehouses set db_pass = <encryptedPassForTenantWarehouses> where tenant_guid = <tenantGuidFrom2ndStep>
5. Verify that components are able to work with encrypted passwords. 
   1. For more information on how to verify whether Dispatcher Paragon is able to work with encrypted passwords see Enhanced password protection - troubleshooting .

List of all secret names 

In the table below there is a list of secret names for all protected passwords. Even for passwords encrypted automatically, manual encryption/decryption might be useful in some scenarios (e.g. restoring DB backup with encrypted passwords).