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:

• Bulk Token Utility

• WebService Security - TokenServiceAuth

• SearchPurge Utility

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.

You can invoke TokenServiceAuth via the command line:

java -cp SafeNetTokenService-8.12.4.000.jar com.safenet.token.auth.TokenServiceAuth

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

java -DUseGUI=no -cp SafeNetTokenService-8.12.4.000.jar com.safenet.token.auth.TokenServiceAuth

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.

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:

java -DmaskPassword=no -DUseGUI=no -cp SafeNetTokenService-8.12.4.000.jar com.safenet.token.auth.TokenServiceAuth -cu tsUser0 a_password dsuser dspassword dbuser dbpassword

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:

java -DmaskPassword=no -DUseGUI=no -cp SafeNetTokenService-8.12.4.000.jar com.safen et.token.auth.TokenServiceAuth -cu tsUser0 b_password dsuser dspassword dbuser dbpassword

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

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.

java -cp SafeNetTokenService-8.12.4.000.jar com.safenet.token.SearchPurgeUtility Utility.properties

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.

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

Maintain the following parameters in Utility.properties file before setting the Search/Purge operation criteria:

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

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.

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:

1. On the Command Line Interpreter (CLI), type the following command:

   java -cp SafeNetTokenService-8.12.4.000.jar com.safenet.token.SearchPurgeUtility Utility.properties
   

   The CLI prompts for nae password.

2. Enter the nae password and then database password.

3. Press the Enter key.

   The SearchPurge Utility performs the operation and displays the following message to check the output file:

   Search operation is complete, please check the output file
   

4. Check the output.csv file for tokens/values.