Please Note:

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.4.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:

Tokenize
Detokenize
Delete a token by its original value
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.

Note

Token vault cannot be created through the CipherTrust Manager UI. You can use the SetupDB utility to create a token vault for CipherTrust Manager. Refer to "Configure Vault using Java Utilities" for details.

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.

Note

The CT-V installer won't understand %CATALINA_HOME% when you enter the path to the directory where CT-V should be installed. You will need to provide the actual path. For example, if Tomcat is installed in C:\Program Files\Apache Software Foundation\Tomcat 7.0, and %CATALINA_HOME% = C:\Program Files\Apache Software Foundation\Tomcat 7.0, when the CT-V install requests a directory into which it should install CT-V, enter C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\cctest\WEB-INF\lib. If the directory path contains spaces, do not quote the path.

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:

Tokenize
Detokenize
Delete a token by specifying its original value
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.4.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.4.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.

Note

NAE and Key Manager are synonymous.

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:

Remove the comment lines, , 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:

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.

Note

Cctest uses operations having the names, "dt" and "dv". Do not confuse them with the Tomcat users, "dt" and "dv". If you change the existing rolenames, in the jsp pages, it will change the values that begin with "sfnt_".

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

Web Services Examples for Java Developers

TokenSample Application

Setup

CCTest

Installation

Prerequisites

Creating a Token Vault on the KeySecure Classic

Basic Installation and Set Up of CCTest

Edit a Tomcat file

Modify the SafeNetToken.properties file

Store the Key Manager and Database Credentials

Testing CCTest

Enabling SSL after Verifying Installation

Redirect the HTTP Request to HTTPS

Troubleshooting

On this page

Suggest A Change