Setup and Configuration of the Enhanced Password Protection

Enabling the enhanced password protection requires manual configuration. An administrator needs to use the password protection tool distributed with YSoft SafeQ. 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 YSoft SafeQ 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 YSoft SafeQ 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 YSoft SafeQ is able to reach the configured file with the secret key. YSoft SafeQ is able to recognize whether passwords in configuration files are obfuscated or encrypted and is able to process both versions.


Encrypted password has a prefix ENCSTR: which is used by YSoft SafeQ to recognize an encrypted password. Using plain passwords starting with this prefix must be avoided.

Stop all YSoft SafeQ Services

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

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

Get-Service*YSoft* | Where-Object { $_.Name -ne 'YSoftPGSQL' -and $_.Name -ne'YYSoftPGSQL' } | Stop-Service

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:

<safeq_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.

If a Management cluster is used, an administrator must use a shared location or distribute the key to all servers, see Enhanced Password Protection for more details.

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.


dataProtection.pathToKey = c:/mycustompath/keys.txt
dataProtection.enableAutomaticKeySetup = true

Enable enhanced password protection in configuration files

Once you have generated the secret key the next step is to setup components of YSoft SafeQ 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.

Component

Configuration file

Management Service

<safeq_folder>\Management\conf\safeq.properties

IMS

<safeq_folder>\Management\ims\application.properties

Database

<safeq_folder>\Management\validator\conf\DBValidator.properties


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:

dataProtection.pathToKey = c:/mycustompath/keys.txt

Make sure that the path contains only forward slashes.


Correct: c:/mycustompath/keys.txt

Wrong: c:\mycustompath\keys.txt


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

Property

Values

Default

Description

dataProtection.enableAutomaticKeySetup

true/false

false

When set to true then the secret key is generated automatically if it is not already generated. Previous key initialization is not needed in this case.

dataProtection.keyCachingSeconds

-1/0/N

-1

Time (in seconds) for which keys will be cached in memory without need to read them from the file with secret keys. Value -1 dictates to keep keys forever in the cache (until restart of the service). Value 0 dictates not to cache keys. Positive integer value N dictates keeping keys in the cache and delete them if not used for N seconds.

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.


Enabling the feature does not mean that passwords in configuration files will be protected. An administrator has to encrypt passwords in configuration files manually first. Passwords stored in DB will be automatically encrypted when saved through Management web interface.

Manually encrypt Passwords in Configuration Files

An administrator has to manually encrypt passwords and insert them into configuration file. YSoft SafeQ 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:


Component

Configuration file

List of passwords which can be encrypted in the file

Management Service

<safeq_folder>\Management\conf\safeq.properties

database.global.management.password

database.cluster.management.password

database.cluster.guest.password

databaseWarehouse.global.management.password

databaseWarehouse.cluster.management.password

databaseWarehouse.cluster.guest.password



IMS

<safeq_folder>\Management\ims\application.properties

spring.datasource.password

Database

<safeq_folder>\Management\validator\conf\DBValidator.properties

connectionInfoSQ.userPassword

connectionInfoSQ.userManagementPassword

connectionInfoDW.userPassword

connectionInfoDW.userManagementPassword


Please follow the procedure below to encrypt a passwords:

  1. Ensure that relevant YSoft SafeQ 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. 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.


The Text encryption (obfuscation) widget in Management web interface cannot be used for enhanced password protection, it obfuscates the text using the legacy way of encryption.

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. YSoft SafeQ is able to recognize encrypted passwords and decrypt them when needed.


  1. Ensure that relevant YSoft SafeQ 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 YSoft SafeQ 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).


Location

List of secret names for protected passwords

Configuration files

database.global.management.password

database.cluster.management.password

database.cluster.guest.password

databaseWarehouse.global.management.password

databaseWarehouse.cluster.management.password

databaseWarehouse.cluster.guest.password

spring.datasource.password

connectionInfoSQ.userPassword

connectionInfoSQ.userManagementPassword

connectionInfoDW.userPassword

connectionInfoDW.userManagementPassword

connectionInfoDW.userGuestPassword

Management Interface

mailpass

ldap-replicator-*-pass

ldap-replicator-<DOMAIN>-pass (<DOMAIN> stands for domain name when using multiple LDAP domains)

scanServerUserPassword

globalMailPassword

openIdConnectClientSecret

mailOAuth2ClientSecret

Database

tenants.db_pass

tenant_warehouses.db_pass

tenant_1.users_idm_tokens.token