CipherTrust Vaulted Tokenization for Other Databases

This chapter describes the implementation of CT-V with databases other than the supported databases.

It covers the following topics:

• Database-Specific Token Vault Implementation

• API Method List

• API Methods

Database-Specific Token Vault Implementation

CT-V provides a framework that enables you to use Thales token vaults stored in databases other than the Oracle, MySQL, Informix, and MS SQL Server databases. The framework supplies an interface that allows CT-V to use such token vaults, and this document describes the API.

Thales support for these other databases may be made available through Thales Professional Services. In this chapter, the term “support” refers only to the provision of a

Note

feasible technical capability.

To use the Java API methods provided here, you can generate the baseline Java class by running the following command:

java com.safenet.token.tvm.genclass <class name>

This will generate a class with the name specified by the <class name> parameter with all the required functions and parameter types. The generator creates a sample template.

Note

This documentation refers to the created class as TVMTemplate, but this is a generic name. As indicated above, you can substitute any name you want for <class name>, subject to the requirement that the class name must start with the characters “TVM”.

To use this API, import package com.safenet.token.tvm. This provides class TVMTemplate, which inherits all methods of TVM. Here is the signature:

public class TVMTemplate extends TVM

The JAR file named SafeNetTVM.jar serves as a JDK for creating database specific TVM. It enables CT-V to work with different databases. Each different type of database can have a different management model, and TVM provides classes that help you set up the appropriate database connections.

API Method List

To add support for the new database system to CT-V, the TVM API methods listed below must be implemented. Each API method listed below is described in detail under a separate heading.

• TVMTemplate() - create new instance of the TVM.

• close() - close (clean up code specific to your implementation of the token vault).

• setCredentials() - set database user name and password.

• getConnectionString() - construct and return driver-specific connection string.

• getDriverClass() - construct and return JDBC driver class string.

• install() - perform database-specific installation procedures for the token vault; this function is reserved for future use.

• upgrade() - upgrade token vault and other database objects to current release.

• uninstall() - uninstall database structures for the token vault; this function is reserved for future use.

• create() - create database objects for the token vault.

• drop() - remove an existing token vault.

• getSessionInfo() - get information to help with low-level database debugging/tracing.

• getDatabaseMetaInfo() - read various metadata information from the database.

• getTokenVaultInfo() - get token vault information from meta data tables.

• getTokenVaultListExt() - get list of token vault names available in the database (create its own connection and close it when done, just as getTokenVaultInfoExt() does).

• getBaselineTokenData() - used by the upgrader for migration to new token vault; gets rows of tokens from the baseline (application) table.

• updateTokens() - used for the upgrade process: replaces temporary tokens (created for the upgrade process) with the original tokens obtained from the application table via getBaselineTokenData function (above).

• getTokenVaultInfoExt() - get token vault information via a new connection (creates and closes its own database connection).

• renameTokenVault() - called during upgrade process to rename token vault tables as required.

• rekey() - implements various stages of the re-key operation.

• setTokenVaultInfo() - save token vault information into metadata tables.

• setTokenFormatInfo() - save token format information to the database.

• getTokenFormatInfo() - read token format information from the database.

• getCipherTextByToken() - get ciphertext values associated with given tokens.

• getCipherTextByTokenWithErrors() - get cipher text values for given tokens and save any errors encountered instead of throwing exceptions.

• getTokenByMACValue() - get tokens associated with given hash values.

• getTokensByDate() - get an array of up to 10,000 tokens that were created on or before a specified date.

• deleteTokens() - delete entries for given tokens from the token vault.

• deleteValues() - delete entries for given hash values from the token vault.

• tokenize() - generate tokens or return existing tokens.

• tokenizeWithErrors() - same operation as the tokenize function, except this method does not throw exceptions when errors occur, and instead saves error information into the result object.

Note

"info" arguments defined as HashMap<String, String>...

Some functions take the HashMap<String, String> object called "info" as an input parameter. This object stores parameter name – parameter value pairs that the framework passes to API functions.

For example, the create() function receives a parameter name “TokenSize”, and a corresponding parameter value that specifies the size of the token column to be created. In this example, “TokenSize”, the first string in the pair, is the literal name assigned to the bucket. The second string in the pair "size", represents the value in that bucket.

API functions can get the values set by the framework with the following code:

String parameterValue = info.get(parameterName);

Likewise, some functions are expected by the framework to populate (set) the info object on output. For example, getTokenVaultInfo is expected to set parameter name “CryptoKeyName” to the parameter value "myKey", where myKey is the value of the crypto key.

API functions that use the info object set the parameter name – parameter value pairs using the following code:

info.set(parameterName, parameterValue);

Be aware that many API functions accept the HashMap<String, String> argument, including install(), upgrade(), uninstall(), create(), drop(), getDatabaseMetaInfo(), getTokenVaultInfo(), getTokenVaultListExt(), getTokenVaultInfoExt(), setTokenVaultInfo(), setTokenFormatInfo(), and getTokenFormatInfo().

The API functions that use these info parameter name-value pairs specify which parameters will be set by the framework on input, and which parameters are expected to be set by this implementation on output.

Class TVM Template

Class TVMTemplate()Database-specific implementation of TVM interface.

Syntax

public class TVMTemplate extends TVM

constructor()

Creates new instance of this TVM; in most cases, it is sufficient to call the constructor of the base class.

Syntax

public TVMTemplate(String host, String port, String database, String server)

API Methods

The API methods described below are specific to the TVM, and enable you to perform high level TVM set up and administrative procedures.

• close()

• setCredentials()

• getConnectionString()

• getDriverClass()

• install()

• upgrade()

• uninstall()

• create()

• drop()

• getSessionInfo()

• getDatabaseMetaInfo()

• getTokenVaultInfo()

• getTokenVaultListExt()

• getBaselineTokenData()

• updateTokens()

• getTokenVaultInfoExt()

• renameTokenVault()

• rekey()

• setTokenVaultInfo()

• setTokenFormatInfo()

• getTokenFormatInfo()

• getCipherTextByToken()

• getCipherTextByTokenWithErrors()

• getTokenByMACValue()

• deleteTokens()

• deleteValues()

• tokenize()

• tokenizeWithErrors()