Password Protection Tool Manual
Password protection tool is used to create a secret key. After the secret key is generated the tool can be used for encryption and decryption of passwords (and possibly other data). Password protection tool is used via batch file data-protection.bat and it is used via Command Line Interface (later on just CLI).
Within this section the term tool will be used as a placeholder for password protection tool.
Tool location
The tool is typically located at following directory:
<dispatcher_paragon_folder>\Management\utilities\data-protection-cli\
During update of Dispatcher Paragon the tool will be rewritten by the latest version in the directory shown above. The old version of the tool will be backed up. New backup directory indicated a date of the update will be crated for the backup.
Example of backup directory:
<dispatcher_paragon_folder>\Management\backup\20190903085747.078\utilities\data-protection-cli\
Password Protection Tool Setup
Tool Setup
The password protection tool requires JAVA 11 to be installed on the system. If Dispatcher Paragon have been already installed then an administrator does not need to do anything. If it is not the case then the administrator has to configure environment variable %JAVA_HOME% or %PATH% and setup the path to the java executable.
Key storage setup
By default the key file is stored in "%APP_HOME%/conf/keys.txt". The location can be changed by editing the batch file data-protection.bat.
set KEY_PATH=%APP_HOME%/conf/keys.txtNote that KEY_PATH variable can be overruled by the tool argument -pathtokey.
Logging
By default tool logs are stored in "bin/logs/data-protection.log". When the file size reaches 20MB (default value), the original file is renamed to "data-protection.log.yyyy-MM-dd-HH" and a new (empty) data-protection.log is created.
Password Protection Tool Commands
Parameter -name, which is required by some commands, is a name of secret which should be protected. In context of Dispatcher Paragon, it is a name of property in a configuration file or a name for storing the password in the database. For example, in a configuration file you can see the following line:
my.password = hChKrDtN8956
In this case, my.password is the name of the secret (argument -name) and hChKrDtN8956 is the secret in a plain text form.
To use most of the commands an administrator must ensure that the physical file with the secret key must exist on the hard drive. The secret key can be generated by the command initkeys. Then the path to the file can be set either in data-protection.bat file (see the tool setup section above) or via argument -pathtokey. Without the secret key the encryption or decryption will not be possible.
HELP
The tool writes a user help message into CLI.
Example:
data-protection.bat help |
ENCRYPT
The tool encrypts a password. The user has to provide the secret name. The tool asks the administrator for inserting a password which is to be encrypted. Press the key <ENTER> to confirm the password insertion.
The tool is able to encrypt plain text passwords as well as legacy obfuscated passwords.
Arguments | Description | Mandatory |
-name <str> | Secret name. | Yes |
-pathtokey <str> | Path to a file with the secret key. | No |
Example including the output:
data-protection.bat encrypt -name my.password |
VERIFY
The tool verifies that an encrypted password can be decrypted. The output is true if it is possible or false otherwise. An administrator has to provide the secret name. The tool asks the administrator for inserting a password which is to be verified. Press the key <ENTER> to confirm the password insertion.
Note that by using this command an administrator can verify that the password can be decrypted without exposing the real password in plain text in the console.
Arguments | Description | Mandatory |
-name <str> | Secret name. | Yes |
-pathtokey <str> | Path to a file with the secret key. | No |
Example including the output:
data-protection.bat verify -name my.password |
DECRYPT
The tool decrypts an encrypted password. An administrator has to provide also the secret name. The tool asks the administrator for inserting a password which is to be decrypted. Press the key <ENTER> to confirm the password insertion.
Note that after password decryption the plain text appears in the console.
Arguments | Description | Mandatory |
-name <str> | Secret name. | Yes |
-pathtokey <str> | Path to a file with the secret key. | No |
Example including the output:
data-protection.bat decrypt -name my.password |
INITKEYS
The tool generates new secret key if one does not exist yet.
The tool checks whether the file with secret key exists and if not then it creates one. The tool does not overwrite already created secret key.
Arguments | Description | Mandatory |
-pathtokey <str> | Path to a file with the secret key. | No |
Example:
data-protection.bat initkeys |
CHANGEKEY
The tool generates and adds new secret key that will be used for further password encryption.
Previously generated keys can be still used for decryption if not removed by the command deleteoldkeys.
Arguments | Description | Mandatory |
-pathtokey <str> | Path to a file with the secret key. | No |
Example:
data-protection.bat changekey |
DELETEOLDKEYS
The tool deletes old keys from file with keys.
After executing this command, passwords encrypted by the old keys cannot be decrypted by the tool any more. Ensure that all passwords are encrypted by the last generated key.
Arguments | Description | Mandatory |
-pathtokey <str> | Path to a file with the secret key. | No |
Example:
data-protection.bat deleteoldkeys |
PROTECTKEYS
The tool encrypts stored secret keys with DPAPI.
Arguments | Description | Mandatory |
-pathtokey <str> | Path to a file with the secret key. | No |
-out <str> | Path to an output file (key file will be rewritten if not specified). | No |
Example:
data-protection.bat protectkeys |
UNPROTECTKEYS
The tool removes DPAPI protection from stored keys.
Arguments | Description | Mandatory |
-pathtokey <str> | Path to a file with the secret key. | No |
-out <str> | Path to an output file (key file will be rewritten if not specified). | No |
Example:
data-protection.bat unprotectkeys |