This section describes how to deploy CT-V using SOAP Web Services.

SOAP Web Services

The SOAP Web Service works with Axis2 and Apache Tomcat server and enables you to:

• (CreateNewRegExTokenFormat, CreateNewTokenFormat and CreateNewTokenFormatWithTokenLength) - create new token formats. The latest addition, CreateNewRegExTokenFormat, uses Java regular expressions to simplify the process.

• (InsertBatch, InsertBatchWithCustomData, InsertBatchWithMultipleVault, InsertToken, InsertIrreversibleToken, InsertTokenWithCustomData, InsertTokenWithCustomDataWithTokenProperty, InsertTokenWithTokenProperty, InsertBatchWithTokenProperty, InsertBatchWithTokenPropertyBatch, InsertBatchWithCustomDataAndTokenProperty, InsertBatchWithCustomDataAndTokenPropertySmartCheck, and InsertBatchWithCustomDataAndTokenPropertyBatchSmartCheck) - create tokens.

• CreateMaskingFormat - create new masking formats to be used in the get() methods that return plaintext values.

• (GetBatch, GetBatchWithCustomData, GetValue, and GetValueWithCustomData) - get plaintext values.

  Note

  The plaintext for token generated using InsertIrreversibleToken() method will not be returned, instead it will return the string value “Irreversible Token”.

• (GetTokensByTokenProperty, GetTokenBatchWithCustomData, GetTokensByDateWithCustomData, GetTokensByRangeDateWithCustomData, and GetTokenWithCustomData) - get the tokens.

• (GetCustomTokenPropertyByTokens and GetCustomTokenPropertyByValue) - get the customTokenProperty.

• GetDisabledTokens - get the disabled tokens.

• (DeleteToken, DeleteTokenEx, DeleteTokenBatch, DeleteTokenExBatch, DeleteValue, DeleteValueWithCustomData, DeleteValueBatch, DeleteTokenByTokenProperty and DeleteValueBatchWithCustomData) - delete tokens/values.

• DisableTokenBatch - disable tokens from the token vault.

• Mask - create tokens without storing them in the token vault mask.

• (UpdateBatchTokenProperty and UpdateTokenProperty) - update the tokenProperty(s) for the tokens.

• create "token service" users where the Key Manager and database credentials are encrypted and remain completely unknown to consumers of the WebService. The consumer receives, instead, a token service username and password to use for authentication with the CT-V WebService. Key Manager and database credentials do not need to be exposed.

• create cctest, a web application that uses Tomcat and JSP pages to demonstrate tokenizing in a web environment. This application provides a GUI that enables users to select and apply different token formats and to perform common token operations. The user can perform four operations:

  • Tokenize

  • Detokenize

  • Delete a token by its original value

  • Delete a token by the token value

  The user can enter sample plaintext or ciphertext as input. Displayed output shows products of the selected operation, using the selected token format, on the user-provided input.

• continue a bulk tokenization or de-tokenization process even when row level errors (null values, invalid values) appear in the input. Your application can enable this “Smart Check” option by using new (overloaded) versions of the insert() or get() calls with a boolean value is set to true.

  Note

  When running batch jobs in Oracle, we recommend that you execute the analyze table command after running the first batch job on a token vault. For example:

  !yaml

  analyze table compute statistics;

If this command is not used, performance will degrade after running batches between 5000 and 10000 rows. This performance degradation will cause a Read Timeout Exception.

Creating Stub for Axis2 Client

Before creating Stub for Axis 2 client, JDK version 7, 8 or 10 must be installed on the intended machine.

1. Download Axis2 binary distribution, for the same version as Axis2 engine, and extract the same.

2. Open the command prompt on Windows.

3. Set environment variable AXIS2_HOME to location of extracted distribution.

4. Create a folder Stub at any accessible location.

5. Change directory to Stub.

6. Fire command %AXIS2_HOME%\bin\WSDL2Java -uri <Location of WSDL> -p <Package Name> -dadb -s -o <Output Directory for generated Source>.

7. Compile generated Source code by keeping AXIS2_HOME\lib jars in classpath, using JAVAC tool.

8. Change directory to <Output Directory for generated Source>\src and fire command jar cvf <STUB NAME> <Package Name>\*.class.

   Note

   Above steps are generic and are applicable for all platforms.

For Windows OS:

Pre-requisite: Axis engine compatible distribution is already downloaded and extracted to C:\axis2 and service URL is http://localhost:8080/axis2/services/SafeNetTokenizer?wsdl

1. Launch CMD and create directory <Stub>.

2. Change to directory <Stub>.

3. Run command set AXIS2_HOME="C:\axis2"

4. Run %AXIS2_HOME%\bin\WSDL2Java -uri http://localhost:8080/axis2/services/SafeNetTokenizer?wsdl -p com.safenet.tokenization.client -dadb -s -o C:\Stub\Classes

5. Run command cd C:\Stub\Classes\src

6. Run command C:\Stub\class\src>javac -classpath C:\axis2\lib* com\safenet\tokenization\client\*.java

7. Run command C:\Stub\class\src> jar cvf SafeNetTokenStub.jar com\safenet\tokenization\client\*.class

TokenServiceAuth()

Create "token service" users whose Key Manager and database credentials are encrypted and invisible to WS consumers. Consumer receives, instead, an encrypted token service username and password to use for authentication with the CT-V WS. Installed with the CT-V jar file, this new utility, com.safenet.token.auth.TokenServiceAuth, allows create, delete, and update of token service users.

Invoke the GUI interface via the command line with:

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

Or invoke a CLI version:

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

Parameters

• new password for the admin user

• token service users

• Key Manager credentials associated with token service user

• Database credentials associated with token service users

cctest

Demonstrate tokenizing in a web environment. cctest is a web application that uses Tomcat and JSP pages. Both CLI and GUI versions enable users to select and apply different token formats and to perform common token operations. The user can perform four operations:

• Tokenize

• Detokenize

• Delete a token by its original value

• Delete a token by the token value

The user enters sample plaintext or ciphertext as input value, a token format identifier, and the operation to be performed. Displayed output shows products of the selected operation, using the selected token format, on the user-provided input, or a status (e.g., deleted).

If the status remains "Tokenizing ..." something may have gone wrong. Check the log files in %CATALINA_HOME%\logs (or your equivalent)

Refer to the illustration of the GUI below for a preview of the functionality:

To improve performance and productivity, CT-V code provides a Bulk Tokenizer application that provides scripted, multi-thread tokenization capabilities. The tokenizer code automatically splits arrays into multiple batches and runs these batches as multiple threads.

Two configuration parameters, NumTMThreads and BatchSizeThresholdToThread, enable you to control how many threads are used, when threading is used, and the size of the batches.

Parameters

• Use NumTMThreads to set the number of threads to use when performing the TokenService methods listed above. The default is 8, with a suggested batch size of 40k.

• Use BatchSizeThresholdToThread to specify the minimum number of elements that must be in a String array in order to allow threading. The minimum valid value that allows threading is 1000. Specifying any value lower than 1000 will result in an exception. The default is 2000. Thus, if there are 4000 or more elements in the array, then the code will use threading (assuming NumMTThreads > 1). If there are less than 4000, the code will not use threads to perform the operation; the operation will run as one batch. There is no maximum. Setting BatchSizeThresholdToThread to a high value (e.g., 10,000,000), would prevent TokenService from using threads.

• By adjusting the configuration parameters, you can optimize performance for the size of the job and the balance of thread processing to batch processing in your current environment.

  Note

  • When using the CT-V API in a multithreaded application on a single CPU, you can expect normal performance when using ten to fifteen threads. Increasing the thread count in this environment increases the likelihood of performance degradation.

  • When running batch jobs in Oracle, we recommend that you execute the analyze table command after running the first batch job on a token vault. For example:

    analyze table <your token vault table> compute statistics;

    If this command is not used, performance degrades after running batches between 5000 and 10000 rows.