Utilities and Tools
This section provides information about the utilities and tools included in CT-V package. Typically these utilities are web services that are introduced in other chapters, where the basic installation instructions may also appear. The content here provides additional help of the kind that might appear in an application user guide.
This section covers the following topics:
Note
The user may use the obfuscated password or credential. See Creating Obfuscated Data Using Obfuscation Utility for more information.
Bulk Token Utility
CT-V provides a command line utility that enables you to tokenize/detokenize a very large data set at impressive speed. For details, refer to CT-V Bulk Utility User Guide.
WebService Security - TokenServiceAuth
CT-V provides a web service utility that you can use to enhance security with respect to Key Manager and database credentials. This is introduced and summarized in SOAP Web Service for Java Developers.
This section describes the utility, its GUI, its purpose, and how to use it in greater detail.
Purpose
Without this service, CT-V web service methods require both the Key Manager and database credentials when calling its methods. Some administrators may find it undesirable to give such credentials to WS consumers. To address this, CT-V administrators can now create "token service" users where the Key Manager and database credentials are encrypted and completely unknown to consumers of the WS. The consumer receives, instead, a token service username and password to authenticate with the Tokenization web service.
This utility allows CT-V administrators to create, delete, and update token service users; and to use a GUI to do so. The GUI is titled “CipherTrust Vaulted TokenizationAuthorization Tool”, and its features and functions are described below, under the heading, [Using the Web Service Security Utility GUI]. You can also use a CLI interface, as explained below. Be aware that the CLI is documented by a help file that appears when you initiate the service from the CLI.
Location and Setup
The utility is installed with the CT-V jar file, com.safenet.token.auth.TokenServiceAuth.
Tip
This document refers to Microsoft Windows environment variables when describing setup. If you're on a Unix-like system, replace %CATALINA_HOME% with the equivalent on your system and replace the backslashes with forward slashes. For example, where the directory that contains JCE might be %JAVA_HOME%\lib\ext on Windows, it would be $JAVA_HOME/lib/ext on a Unix-like system.
You can invoke TokenServiceAuth via the command line:
CLI Version
If you are in an environment where a graphical user interface (GUI) is unable to run, you may run the utility from the command line using the system property, UseGUI=no
Optional parameters
DmaskPassword - obfuscated password can be used, if this value is set to yes.
DStorageLocation - specify the location of the directory where tsadata.dat and tsausers.dat files will be stored. If the location is not specified, then the files are created in the same directory where SafeNetTokenService-8.12.4.000.jar is located.
A help screen will appear, providing CLI user instructions.
Using the Web Service Security Utility GUI
The first time the utility launches you will be prompted to enter a new password for the admin user. After that, you can create, update, or delete existing token service users, as well as the Key Manager and database credentials associated with token service users.
The GUI provides 5 tabs:
All Users: Lists all token service users. To display the Key Manager and database passwords, select the token service user and click the "Show User Passwords" button. To hide it, click "Hide All Password." Note that if you switch to a different tab, all displayed passwords will be hidden automatically.
Create/Update User: Allows you to create and update multiple sets of credentials. If the token service user already exists, it will be updated. The Persistent Passphrase setting option enables you to define the passphrase used to set up persistent caching for webservice users. To use persistent caching, both of the following properties must be configured in the JCE provider (CADP JCE): Symmetric_Key_Cache_Enabled and Peristent_Cache_Enabled.
Note
The persistent key caching feature is not supported in this release.
Reset User Password: Allows you to update token service users and the admin user. If you update the admin user, you will be prompted to enter the current admin password. For all other users, you won't. You can update multiple users at once by holding the Ctrl key while selecting users.
Delete User: Allows you to delete token service users. As with the "Reset User Password" tab, you select multiple users at once by holding the Ctrl key while selecting users. The admin account will not appear in the list.
Consistency Check: Allows you to check the consistency of the two files, tsadata.dat and tsausers.dat. There is a relationship between these two files. This check tests that users in tsausers.dat are also in tsadata.dat. If the consistency check fails, it may be necessary to delete the two files and recreate the users.
The Token Administrator gives the token service username and password to those who will call CT-V WS methods. When someone uses the WS methods, they still apparently require the four parameters Key Manager and database usernames and passwords. However, instead of passing the Key Manager username and password, you pass the token service username and password. For the database username and password, you pass an empty string.
Note
After five minutes the GUI will prompt for the admin password. If a valid one is not entered, the application will close.
You cannot delete the admin user account.
You can change the admin password in the "Reset User Password" tab of the dialog.
You cannot create a token service user named 'admin'. That is a reserved user.
The two files, tsadata.dat and tsausers.dat, are, by default, created in the same directory as SafeNetTokenService-8.12.4.000.jar.
To change the location of tsadata.dat and tsausers.dat files, you must call System.setProperty(“StorageLocation”, <user location>);
Using the Web Service Security Utility CLI
To create the new user, tsUser0, having the Key Manager user dsuser, and password dspassword, and database user dbuser, with database password dbpassword, run the following command:
To update any of the three sets of credentials, run the command again with the desired change. For example, to change the Key Manager password from a_password to b_password, run:
If user, tsUser0, already exists, you will be prompted to confirm the update. You can change any of the last five parameters. To change the token service user, tsUser0 to tsUser1, you would have to delete tsUser0 and create tsUser1. Refer to the Help file for more information on the CLI.
Troubleshooting
Tip
A good resource to use for checking problems is Tomcat's log directory, %CATALINA_HOME%/logs. If you run into difficult issues, here are suggestions:
Issue: You no longer have the admin's password.
Try: There is no password recovery mechanism for the admin user, but remember that three sets of credentials for each token service user are simply stored in the files, tsadata.dat and tsausers.dat. There is no issue in recreating the token service users, other than the time it takes to re-enter all of the credentials information.
Issue: You no longer have the password for one of the token service users.
Try: You can reset a token service user password by using the "Create/Update User" tab in the GUI, or using the "-cu" parameter on the command line, as in the second example in the examples above.
Issue: You added or deleted a token service user, but the WS errors with unknown user or the deleted token service user still exists.
Try: You must restart Tomcat after making such a change.
SearchPurge Utility
CT-V provides the SearchPurge utility which can be used to search and purge the tokens/values. The search/purge can be conducted based on the parameters specified in the Utilitiy.properties file.
The Search and Purge utility is invoked with the following command.
Note
The Utility.properties file should be in the same location as that of .jar file.
The Search and Purge operations run independently: Search operation to search the tokens/values and Purge operation to purge the tokens/values. Both utilizes the same parameters to search/purge the tokens/values and only differs in the operation type as specified in the Utility.properties file.
Note
The customTokenProperty of token is not to be used to run the SearchPurge utility.
Maintaining the SearchPurge Utility
Before running the Search or Purge operation, the user is required to maintain the following files:
Utility.properties
Input.csv
Output.csv
Note
The location of the Input/Output files is user defined (if output file location is not defined, default output.csv file is generated in the current directory after Search/Purge operation is performed). Also the Input file is required when criteria other than Date is used to search/purge the tokens/values.
Maintain the following parameters in Utility.properties file before setting the Search/Purge operation criteria:
| Parameter | Description | Remarks |
|---|---|---|
| TokenVaultName | Enter the name of the token vault on which the operation is to be performed. | Mandatory |
| NaeUser | Enter the Key Manager user name. | Mandatory |
| DBUser | Enter the name of the database user. | Mandatory |
| Operation | Enter the operation name. It can have one of the following values: Search: To search the tokens/values. Purge: To delete the tokens/values. | Mandatory |
| Criteria | Enter the criteria based on which the operation is to be performed. The criteria selection is outlined after this section. | Mandatory |
The Search and Purge operations are run with any one of the following four criteria:
Date
TokenProperty
Token
Value
The Date criterion is maintained in the Utiliiy.properties file and TokenProperty/Token/Value criteria are maintained in the Input.csv file and Utility.properties file.
On setting the Date criterion, user has to maintain the following related parameters in the Utility.properties file:
DateType: It is the token creation date or last access date.
StartDate: It is the start date (in the yyyy-mm-dd format) for the date range when the tokens were created or accessed.
EndDate: It is the end date (in the yyyy-mm-dd format) for the date range when the tokens were created or accessed.
The following table summarizes how the parameters are maintained:
Criteria Summary
| Criteria | Description | Remarks | |
|---|---|---|---|
| Date | DateType | It defines the column date on which the filter is to be applied and can have value CREATION_DATE or LAST_ACCESS_DATE. It is maintained in the Utility.properties file. | Mandatory for Criteria = Date and optional for other criteria. |
| StartDate | It defines the value for the start date when the operation is performed on the date range. The date format to be used is yyyy- mm-dd. It is maintained in the Utility.properties file | Mandatory for Criteria=Date and optional for other criteria. | |
| EndDate | It defines the value for the end date when the operation is performed on the date range. The date format to be used is yyyy- mm-dd. It is maintained in the Utility.properties file. | Mandatory for Criteria=Date and optional for other criteria. | |
| Value | It defines the plain value based on which the search/purge operation is to be performed. It is maintained in the Input.csv file. | NA | |
| TokenProperty | It defines the tokenproperty based on which the search/purge operation is to be performed. It is maintained in the Input.csv file. NOTE: The customTokenProperty (second string of the TokenProperty) is not to be used to run the SearchPurge utility. | NA | |
| Token | It defines the tokens based on which the search/purge operation is to be performed. It is maintained in the Input.csv file. | NA | |
| CustomData | It defines the customer specified data, such as merchant’s name It is maintained in the Utility.properties file for Criteria = Date, otherwise maintained in input.csv file for other criteria. | Optional. | |
| Format | It defines the format of the returned data after Search operation. It can have one of the following two values: 0: If format has this value, then the returned data will have plain values. 6: If format has this value, then the returned data will have masked values. It is maintained in the Utility.properties file. | Mandatory if Criteria = Token and optional for other criteria. | |
| InFilePath | It defines the path to the input file that uses new line as delimiter. Each data line has the format <values/tokens/tokenProperty>, <CustomData> where CustomData is optional. It is maintained in the Utility.properties file. | Mandatory if criteria is other than Date. | |
| OutFilePath | It defines the path to the output file that has the returned tokens/values or error messages, if any. It is maintained in the Utility.properties file. | Optional |
Maintaining the Input.csv File
The input.csv file is required to maintain the corresponding input values for the criteria TokenProperty, Token and Value. The location of the file is user defined and needs to be entered in the Utility.properties file.
Maintaining the Output.csv File Location
It is optional to provide the output file for the search/purge operation. If the output file is not provided then the system generates it in the current directory after Search/Purge operation is performed.
Note
The output file will have a maximum of 10,000 entries for each search operation performed against a single value mentioned in the input.csv file even if the operation returns more than 10,000 entries.
Executing the SearchPurge Utility
After maintaining the Utility.properties, input.csv and output.csv (optional) files, perform the following steps to execute the Search and Purge utility:
On the Command Line Interpreter (CLI), type the following command:
The CLI prompts for nae password.
Enter the nae password and then database password.
Press the Enter key.
The SearchPurge Utility performs the operation and displays the following message to check the output file:
Check the output.csv file for tokens/values.
