Installing CT-V as Rest Web Services

This section contains the following topics, which describes how to install CT-V as REST Web Service.

• Prerequisites

• Extracting the Package

• Installation

Prerequisites

The installation program is used to install the CT-V API and Web Service (WS) for Java developers.

Before installing the CT-V, ensure the following conditions are met:

• The JVM version must be 7 (minimum 1.7.0_121), 8 (minimum 1.8.0_111), 10, 11, or 17 . The JAVA_HOME variable is no longer required; however, it is used in CT-V documentation to represent the location of your JVM. When using JRE, the jar and properties files will be placed in JAVA_HOME/lib/ext. When using JDK, the jar and properties files will be placed in JAVA_HOME/jre/lib/ext or in the user-specified location. Be sure that the location is part of your CLASSPATH.

• Download the encryption policy files for unlimited strength ciphers (US_export_policy.jar and local_policy.jar) and install them in JAVA_HOME/lib/security. You need these to use AES-256 keys.

  • For Sun/Oracle Java, download corresponding version of the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from https://www.oracle.com/technetwork/java/javase/downloads/index.html.

    Note

    For Java 10, 11, and 17, the encryption policy files are not required to be installed separately.

• Remove any earlier versions of the CADP JCE Provider (IngrianNAE-x.x.x.jar) from JAVA_HOME/lib/ext or JAVA_HOME/jre/lib/ext. Having an older version of the IngrianNAE jar file will abort the installation process immediately with an error.

  Note

  You cannot simply rename the old jar file; It must be deleted or moved to a directory not in JAVA_HOME. Otherwise, the JVM will still find it, even if its file name doesn't end in jar.

• Backup any existing IngrianNAE.properties files. The installer will copy your previous settings to the new properties file, but any embedded comments will be lost. Keeping a copy of your old properties file will help you if troubleshooting is necessary.

• Have access to a database user account with the following permissions:

  • CREATE TABLE

  • SELECT on the token vault table

  • INSERT on the token vault table

  • DELETE on the token vault table

  • UPDATE on the token vault table

• If there are multiple instances or versions of Java on your machine, be sure that the following are true before testing the CT-V:

  • The CLASSPATH variable lists the JDK/JRE instance that holds the CT-V files. If the CLASSPATH variable includes multiple JDKs or JREs, the instance used by the CT-V must be listed before the others.

  • If the CADP JCE is not installed in JAVA_HOME/lib/ext, the CLASSPATH variable includes the IngrianNAE- 8.12.2.000.jar file included in this software.

  • No other java bin directories occur before the system32 directory in the PATH variable.

  • The first instance of java.exe file included in the PATH variable is the same as the java.exe included in JAVA_HOME/bin.

• Create NAE user on Key Manager.

• Create versioned AES-256 key and non-versioned HmacSHA256 key on Key Manager.

• Create Token vault using either KeySecure Classic UI or API.

  See topics in Tasks section for details.

• For Java 11 and higher versions, download the following JAR files from a trusted source and add their paths in Tomcat's CLASSPATH:

  • jaxb-api-2.3.1.jar

  • jaxb-impl-2.3.1.jar

  • jaxb-core-2.3.0.1.jar

  • javax.activation-1.2.0.jar

Extracting the Package

• Navigate to the directory where you have downloaded CT-V.

• Unzip the software file using any standard archive utility.

  The software adheres to the following naming convention:

  Part Number - Product Name - Product Version Number - File Format

  For example,

  610-000671-002_CipherTrustVaultedTokenization-8.12.3.000-xxx.zip

  When the CT-V package is extracted, a directory structure is created. Refer to CipherTrust Vaulted Tokenization Package Details for details.

Installation

To install CT-V as REST Web Service:

1. Copy the tmrest.war file , from the /SafeNetTokenization/Tokenization/restfulService directory to the %CATALINA_HOME%/webapps directory. If the Tomcat server is already running, it may automatically extract the contents to the %CATALINA_HOME%/webapps/tmrest directory. If the Tomcat Server doesn't run, restart the server. The Tomcat will extract the contents automatically.

   • For Java 10, add the --add-modules=java.se.ee command to the Tomcat configuration. For example, on a Windows machine, navigate to Tomcat configure >Java>Java 10 Options and add the command.

   • For Java 17, if following exception is thrown, add the --add-opens java.base/java.net=ALL-UNNAMED command to the Tomcat configuration.

     java.lang.reflect.InaccessibleObjectException: Unable to make field private static volatile java.net.Authenticator

     java.net.Authenticator.theAuthenticator accessible: module java.base does not "opens java.net" to unnamed module

2. Navigate to the /SafeNetTokenization/Tokenization/lib/ext directory and run the installation program as an administrator as shown below:

   java -jar TokenizationInstaller-8.12.3.000.jar

3. Accept the software license agreement.

   The installation program verifies the java environment by checking:

   • the JAVA_HOME variable is correctly configured

   • the JVM version is 7 (minimum 1.7.0_121), 8 (minimum 1.8.0_111), 10, 11, or 17

   • the encryption policies needed to use AES-256 encryption keys are in place.

4. Enter no against the prompt Set up the CipherTrust Vaulted Tokenization to operate with an Apache Tomcat Server and Axis2 SOAP Web Service.

5. Enter yes against the prompt Install the CipherTrust Vaulted Tokenization.

6. The installer places the JCE provider jar files to JAVA_HOME/lib/ext (for JRE 7 and 8) or JAVA_HOME/jre/lib/ext (for JDK 7 and 8) or the user-specified location.

7. Configure the following parameters in the IngrianNAE.properties file:

   • Log_File - The location of the log file that the client will create.

   • NAE_IP.1 - The IP address of the NAE server on the Key Manager.

     Note

     If using IPV6 address, specify it in curly braces, for example, {2002:0dc8:85k3:0000:0000:9a2e:0370:5221}.

     A combination of IPv4 and IPv6 addresses can be specified, provided, they are separated by colons(:) and each IPv6 address must be enclosed within {}. IPv6 is supported only for CipherTrust Manager.

   • NAE_Port - The port of the NAE server on the Key Manager.

8. Enter the absolute path of the CT-V installation directory to the /CATALINA_HOME/webapps/tmrest/WEB-INF/lib directory.

9. Configure the following values in the SafeNetToken.properties file:

   • HostName - The IP address of the database server.

   • PortNumber - The port number of the database server. If your database installation uses the default ports, this value will be 1433 for SQLServer,1521 for Oracle, 3306 for MySQL, and 9088 for Informix.

   • DatabaseType - The type of database. Either SQLServer, Oracle, MySQL, or Informix. Use one of these value exactly.

   Note

   To enable SQLServer over SSL, you have the option to manually modify the properties file after completing the installation process. To use this option, set DatabaseType to SQLServerSSL.

10. InformixServerName - Provide the Informix server name. This option is displayed only when Informix is specified in the DatabaseType.

11. DatabaseLibraryPath - Displays the complete path to a database specific .jar file that implements token vault operations. The jar file is TVMMySQL.jar, TVMOracle.jar, TVMSQLServer.jar or TVMInformix.jar as per the selected database type.

    Note

    You may modify the location of the jar file using the DatabaseLibraryPath parameter in the SafeNetToken.properties file. The new location for the jar file must be specified in the CLASSPATH.

12. Run the CT-V Upgrade. Enter yes to run the upgrade process. This feature will upgrade token vault tables created using older versions.

    • Enter the database user name and password as prompted to run the upgrade process.

    • Enter yes to run the token vault conversion process.

      The screen displays the list of available tables including the ones already converted (converted table means the token vaults structure are up to date).

    • Enter yes to upgrade another schema, else no.

    Note

    If you have MySQL database, and want to use the multiple databases feature, then configure the Databases.json file located in the CATALINA_HOME/webapps/tmrest/WEB-INF/lib directory.

13. Restart the Apache Tomcat server.

14. Navigate to http://<YourHost>:8080/tmrest.

    Click the WADL option to view the CT-V WADL.

    The CT-V is now configured.

    Note

    You can call the API from your java application. See Using CipherTrust Vaulted Tokenization Java APIs for instructions on how to update your applications.

    Note

    To connect CT-V with the database with specific parameters, such as multiSubnetFailover in SQL Server, a hidden parameter _JdbcUrlOverride can be set in the SafeNetToken.properties file. For example, to run CT-V in SQL Server Multi-Subnet Failover Cluster environment using SQLJDBC 4.1 or SQLJDBC 4.2 driver, set multiSubnetFailover=true in the connection string as shown here:

    _JdbcUrlOverride=jdbc:sqlserver://<SQL_Cluster_Name>:<port>;sendStringParametersAsUnicode=true;selectMethod=direct;responseBuffering=full;databaseName=<database_name>;multiSubnetFailover=true

CT-V provides the feature to install the application in silent mode, see Silent Installation.