Web Services Examples for Java Developers

This section describes the applications that are bundled with the CT-V software. This section covers the following topics:

• TokenSample Application

• CCTest

The user may use the obfuscated password or credential. See Creating Obfuscated Data Using Obfuscation Utility for more information.

TokenSample Application

This application sends the following requests to the web service:

• InsertToken

• GetValue

• InsertBatchWithCustomData

• InsertBatchWithMultipleVault

• GetBatchWithCustomData

• DeleteValue

• CreateNewTokenFormatWithTokenLength

• InsertTokenWithCustomData

• InsertBatchWithCustomData

• GetBatchWithCustomData

• Mask

• GetTokensByDateWithCustomData

• GetTokensByRangeDateWithCustomData

• InsertBatchWithCustomDataSmartCheck

• GetBatchWithCustomDataSmartCheck

Results are displayed on the screen.

Setup

The SafeNetTokenStub-8.12.3.000.jar file is compiled using Axis2 -1.7.8 and packaged with CT-V samples (SafeNetTokenization\Tokenization\samples).

To run the samples in this new environment, run 'wsrun.bat' for Windows machines and 'wsrun.sh' for Unix-like systems.

Use the following commands:

On Windows machines

wsrun.bat naeUser naePassword dbUser dbPassword token_vault_name data_to_tokenize

On Unix-like systems

./wsrun.sh naeUser naePassword dbUser dbPassword token_vault_name data_to_tokenize

Explanation of Source Code

It imports 'java.util.Calendar' specific to this sample that is used to generate the date used to call 'GetTokensByDateWithCustomData'.

import java.util.Calendar;

SafeNetTokenizerStub stub = new SafeNetTokenizerStub("http://localhost:8080/axis2/services/SafeNetTokenizer); creates the stub based on the service location at http://localhost:8080/axis2/services/SafeNetTokenizer.

SafeNetTokenizerStub.InsertToken insert = new SafeNetTokenizerStub.InsertToken(); creates an instance of SafeNetTokenizerStub.InsertToken and the following code snippet populates this object. Notice that insert.setFormat passes an Integer object that corresponds with the token formats listed in SOAP Web Service for Java Developers.

insert.setNaeUser(args[0]);

insert.setNaePassword(args[1]);

insert.setDbUser(args[2]);

insert.setDbPswd(args[3]);

insert.setTableName(args[4]);

insert.setFormat( new Integer(1) );

insert.setValue( "01644333453543479" );

insert.setLuhnCheck( true );

SafeNetTokenizerStub.InsertTokenResponse response = stub.insertToken(insert);

Here, stub.insertToken(insert); returns an instance of InsertTokenResponse and then printed to standard output.

Calls to GetValue, InsertBatchWithCustomData, GetBatchWithCustomData, DeleteValue, CreateNewTokenFormatWithTokenLength, InserTokenWithCustomData, and Mask are similarly designed.

CCTest

An ASCII text version of this documentation appears in CCTest install.txt, which is provided in the Tokenization\samples\cctest directory, along with the cctest.war file. An ASCII text version of the documentation appears in the CCTest directory; install.txt appears in the Tokenization\samples\cctest directory, along with the cctest.war file.

CCTest enables users to provide sample input values and:

1. Tokenize

2. Detokenize

3. Delete a token by its original value

4. Delete a token by the token value

Refer to the illustration of the CCTest GUI below for a preview of the functionality.

Installation

The following documentation describes the steps necessary to get the CT-V CCTEST demo application installed and running. CCTEST is a web application that uses Tomcat and JSP pages to demonstrate tokenization in a web environment. This documentation refers to Microsoft Windows environment variables. If you're on a Unix-like system, replace%CATALINA_HOME% with what is equivalent on your system and replace the back-slashes with forward- slashes. For example, the directory that contains JCE might be

%JAVA_HOME%\lib\ext on Windows

$JAVA_HOME/lib/ext on a Unix-like system

Prerequisites

• Tomcat version 6, 7, 8, or 9 is installed and runnable.

• The environment variable, CATALINA_HOME, is set to the root install directory of Tomcat.

• The CADP JCE provider has been installed and can use AES 256 keys.

• If CT-V is functioning, CADP JCE is installed, too. It's typically installed in %JAVA_HOME%/ lib/ext or %JAVA_HOME%/jre/lib/ext.

• A token vault named CCTEST created on the Key Manager. For help, see the following section:

Creating a Token Vault on the KeySecure Classic

Create a token vault named CCTEST on the KeySecure Classic. The files, tokenize.jsp, detokenize.jsp, and delete.jsp expects a token vault of this name. If you wish to use a different token vault name, replace CCTEST with your new name in these files.

Basic Installation and Set Up of CCTest

Unzip the cctest contents into %CATALINA_HOME%\webapps, so that you have %CATALINA_HOME%\webapps\cctest.

After installing cctest, install the CT-V into %CATALINA_HOME%\webapps\cctest\WEB-INF\lib.

Edit a Tomcat file

Tomcat provides several methods for authenticating users. It refers to these methods as realms. A realm is a collection of users, passwords, and roles. The cctest sample uses Tomcat's simplest authentication mechanism, UserDatabaseRealm, where users, passwords, and roles are stored in the file %CATALINA_HOME%\conf\tomcat-users.xml. This file is loaded into memory once and remains until Tomcat is shut down.

The cctest sample uses 4 roles. Users who can:

1. Tokenize

2. Detokenize

3. Delete a token by specifying its original value

4. Delete a token by specifying its token value. It uses 4 users:

   • a - An admin-type user that can perform all roles

   • d - A user that can only detokenize

   • dv - A user that can only delete values

   • dt - A user that can only delete tokens by the original value

To add these users, make a backup copy of %CATALINA_HOME%\conf\tomcat-users.xml in case you need to rollback to the original, and add the following between and to the original file:

<role rolename="sfnt_tokenize" />

<role rolename="sfnt_detokenize" />

<role rolename="sfnt_delete_by_value" />

<role rolename="sfnt_delete_by_token" />

<user username="a" password="asdf1234" roles="sfnt_tokenize,sfnt_detokenize,sfnt_delete_by_value,sfnt_delete_by_token"/>

<user username="user" password="asdf1234" roles="sfnt_tokenize,sfnt_detokenize,sfnt_delete_by_value,sfnt_delete_by_token"/>

<user username="t" password="asdf1234" roles="sfnt_tokenize" />

<user username="d" password="asdf1234" roles="sfnt_detokenize" />

<user username="dv" password="asdf1234" roles="sfnt_delete_by_value" />

<user username="dt" password="asdf1234" roles="sfnt_delete_by_token" />

Important Points

• As a safety precaution, you should change the passwords of the existing Tomcat admin users to stronger ones.

• If you change or add rolenames for the web application (not the Key Manager user/password), you'll have to change/add them in %CATALINA_HOME%\webapps\cctest\WEB-INF\web.xml, as well as in the *.jsp pages.

• The jsp pages inspect roles to determine which operation the logged-in user can perform.

• The roles are in two places in web.xml, so change/modify both.

• Note that Cctest uses operations having the names, "dt" and "dv". Don't confuse them with the Tomcat users, "dt" and "dv". If you change the existing rolenames, in the jsp pages, you'll be changing values that begin with "sfnt_".

• Since tomcat-users.xml is read once Tomcat starts, you need to restart Tomcat after the change.

Modify the SafeNetToken.properties file

In %CATALINA_HOME%\webapps\cctest\WEB-INF\lib, modify SafeNetToken.properties to point to your database server.

If you have previously installed SafeNet Tokenization 6.6.0.01 and are using the same database, you can copy the existing SafeNetToken.properties file instead.

Store the Key Manager and Database Credentials

The Key Manager and database usernames and passwords must be encrypted. To do this, you must use the authorization utility, TokenServiceAuth, in SafeNetTokenService-8.12.3.000.jar. For this sample, create a user named "tsUser0" with the password, "asdf1234". You can change both the username, tsUser0, and password after confirming cctest functions properly. To run the utility that encrypts Key Manager and database credentials, run the following command from a command prompt:

java -cp %CATALINA_HOME%\webapps\cctest\WEB-INF\lib\SafeNetTokenService-8.12.3.000.jar com.safenet.token.auth.TokenServiceAuth

The first time you run it you'll be prompted to enter an admin password. Enter something you can remember.

After this, click the 'Create/Update User' tab. For 'TS User:' enter tsUser0 and asdf1234 for the password (the sample code expects these values). For the Key Manager and database credentials, use those that are needed for the token vault, CCTEST.

Testing CCTest

Start Tomcat if it's not already running. The CCTEST URL is http://localhost:8080/cctest.

Log in using user, a, with the password, asdf1234. User, 'a', is an admin user that can tokenize, detokenize, and delete tokens.

Enter a value to tokenize and click the "Tokenize" button. If all went well, the value you entered should be tokenized. If the status remains "Tokenizing ..." something may have gone wrong. Check the log files in '%CATALINA_HOME%\logs'.

Enabling SSL after Verifying Installation

To enable SSL, edit %CATALINA_HOME%\conf\server.xml. Find the lines like the following:

<!-- <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" /> -->

Remove the comment lines, <!-- and -->, and change the lines to:

<Connector port="443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="<path to location of keystore file>/.keystore" keystorePass="changeit" />

This assumes there is no other server listening on port 443. If you're not using SSL, edit %CATALINA_HOME%\conf\server.xml. Find the lines like the following:

<!-- <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="1000" redirectPort="443" /> -->

Remove the comment lines, , and change the lines to:

<Connector port="80" protocol="HTTP/1.1" connectionTimeout="1000" />

This assumes there is no other server listening on port 80.

Redirect the HTTP Request to HTTPS

By default, Tomcat will allow clients to call servlets, such as cctest, using the non-secure http transport, even after you've enabled SSL. Once you've enabled it you must make a change in web.xml to force http sessions to use https.

Open %CATALINA_HOME%\webapps\cctest\WEB-INF\web.xml, find the XML element, transport- guarantee, and comment-out as follows:

<transport-guarantee>NONE</transport-guarantee>
using <!-- and -->, and uncomment
<!-- <transport-guarantee>CONFIDENTIAL</transport-guarantee> -->

Troubleshooting

There are many moving parts to this setup. A good source for checking problems is Tomcat's log directory, %CATALINA_HOME%/logs.

Issue: You changed a jsp page, web.xml, and tomcat-user.xml, but don't see the results.

Try: Any one of these changes requires a Tomcat restart.

Issue: You changed a jsp page and restarted Tomcat, but your web request seems to hang.

Try: Look in the %CATALINA_HOME%/logs directory. If there was a syntactical error in your change, the error will have been output to one of the log files. Look amongst the most recently changed log files. You don't need to restart Tomcat if you've had a compilation error and you've fixed it. Tomcat will try to recompile the jsp page.

Important Points

• Only after compilation has succeeded and you completed editing a jsp, you must restart Tomcat. This can save you time.

• If you edit a jsp page Tomcat will recompile it after you're restarted it and when a client references the page.

• The roles are in two places in web.xml, so change/modify both.

Since tomcat-users.xml is read once, when Tomcat starts, you have to restart Tomcat after the change.