Académique Documents
Professionnel Documents
Culture Documents
Table of Contents
This code is neither supported nor warrantied. Licensees assume full risk of use.
1.2 Purpose
This document defines the steps necessary to integrate the example code into the Aster environment.
Developers will need to adapt these steps and test the resulting integration in a specific installation.
1.3 Audience
This document’s primary audience is developers writing Aster applications. System architects, security
officers, and other parties with an interest in Aster data protection may find this document useful.
1.4 Developer resources
The following documents from the Voltage SDE product family may be useful as well:
Voltage SecureData Administrator Guide
Voltage SecureData Web Service Developer Guide
Voltage SecureData Simple API Developer Guide
Please contact your Voltage Security account manager or sales engineer to verify you are using the
latest version of this integration.
Aster Scalar UDF Integration Guide 5/15
1
SST uses a static multi-dimensional data structure for mapping a token from a payment account
number (PAN). This data structure is initialized once at setup and, unlike database-driven tokenization
solutions, does not change over the system’s life.
6/15 Aster Scalar UDF Integration Guide
Within the Voltage SDE management console, separate identities are provisioned for the Simple API
and SOAP web services. To access both, provision duplicate identites. See the Authentication and Web
Service overviews in the Voltage SDE Web Service Developer Guide for details.
2
Voltage Security and F5 have an integration partnership for delivering the benefits of Voltage SDE
FPE and SST to customers using BIG-IP without modifying application code. Consult with your Voltage
account manager or sales engineer for details.
Aster Scalar UDF Integration Guide 7/15
The above command ingests the WSDL URL, generates corresponding Java classes, and compiles those
classes. The output can be used to call web services from Java or a Groovy script.
We have provided a script to generate JAX-WS classes using wsimport with a Voltage SDE WSDL.
These objects are included in a JAR archive as part of the build process.
AUTHORIZATION_METHOD: Set to the constant SharedSecret for this implementation. One may
modify the code to support other authentication methods described later.
IBE_IDENTITY: The authentication identity used by the stateless key manager. Different
identity strings are given access to different keys.
LIBRARY_NAME: The name of the C library loaded by JNI at program startup. The corresponding
value normally will not change, but is defined for future versions of the Simple API.
POLICY_URL: The URL for the data protection policy file.
TRUST_STORE_DIRECTORY: The on-disk location of the Simple API certificate store. This object
includes diagnostic statements to determine if this directory is accessible or not.
WSDL_URL: A web services URL location to the web services server.
As delivered, these constants reference a public Voltage key server and web services server. Although
these symbols are defined as private static final constants, it is possible to modify the code and
read these parameters from a file into a Properties object.
3.3 LDAP authentication
Voltage SDE supports multiple forms of authentication including directory authentication. As
delivered, the source code uses shared secret authentication. In this method, we store the
authentication token in plain text.
Installations finding this method unacceptable may integrate a Java data vault, store the secret in the
vault, and obtain the secret programmatically (rather than using a constant definition). Installations
may also use directory service authentication. Consult with Voltage professional services for help with
these topics.
8/15 Aster Scalar UDF Integration Guide
These constants are defined in Section 3.2, Singleton objects. Please use this information to modify
the solution for your production needs.
4.5 Install the Aster Java API
Please install the Aster Java API on the queen node. After installation, copy the following files to the
~/scalarUdf/sqlmr-java-sdk-lib directory:
Aster Scalar UDF Integration Guide 9/15
ncluster-aggregator-api.jar
ncluster-api-util.jar
ncluster-graph-api.jar
ncluster-scalar-api.jar
ncluster-sqlmr-api.jar
ncluster-sqlmr-runnercommon.jar
ncluster-sqlmr-swigkvstore.jar
ncluster-sqlmr-testrunner.jar
ncluster-system-aggregators.jar
One may also modify the CLASSPATH environment variable as defined in the installation scripts to
reference the directory containing these JAR archives on the Queen.
4.7 Distribute the JNI files and certificate store to all cluster nodes
According to Teradata professional services, Java Native Invocation (JNI) files, including the
corresponding C libraries, should reside in /usr/lib on all cluster nodes. For the Simple API
specifically, we also must distribute a certificate trust store to all nodes as well.
Work with system administration to obtain write permission for the deployment user to the /usr/lib
directory. Then copy the JNI files and certificates to all cluster nodes.
We provide a script called createTrustStore.sh that performs this step. This script assumes that
cluster nodes are numbered sequentially, SIAster1 through SIAster8 specifically. One may modify
this script, documented in Appendix A.1, to fit a particular installation’s needs.
When running this script, one may ignore the inc: not a regular file error. As a side note, this
script assumes the deployment user has password-free ssh and scp privileges on all cluster nodes.
4.8 Build the scalar UDFs
Verify a suitable Java Development Kit (JDK) resides on the Aster queen. Normally the JDK resides in:
/home/beehive/toolchain/x86_64-unknown-linux-gnu/jdk1.8.0_101/bin
Inspect the buildUdf.sh shell script and verify the environment variable definitions are correct for
this installation. Specifically, verify both JAVA_HOME and CLASSPATH are correct.
Run buildUdf.sh, which will perform the following tasks:
1. Build the JAX-WS classes used for Java to SOAP web services.
2. Compile the custom scalar UDFs used by the solution.
3. Built a Java Archive (JAR) file containing these objects along with the web services objects.
4. Package this custom JAR file and the Simple API for Java libraries per Aster Java API
specifications.
The contents of the buildUdf.sh script is provided in Appendix A.2 for reference. Note the URL for
the wsimport command should be updated to reflect site-specific requirements.
10/15 Aster Scalar UDF Integration Guide
The installLibraries.sql file is an Aster SQL script that performs the UDF installation. The script is
documented in Appendix A.3.
In this script, authorized_user_name is the Aster database user that will execute the UDFs. Change
this user to one with UDF execution permissions. Note that “file does not exist” error messages may
be ignored the first time this SQL script is executed.
Installation is now complete. The following chapter provides documentation on how to test the
solution using supplied sample data.
Aster Scalar UDF Integration Guide 11/15
5.1 Preparation
Prior to using the UDFs, please create a “scratch” schema to avoid collisions with production data. In
our example, we use the “public” schema, provided by default as part of an Aster installation.
5.2 Create sample tables
We can create sample data tables to test the UDF and verify proper operation. To do so, we perform
two major steps: creating blank tables and loading these tables with sample data.
5.1.2 Creating blank tables
We execute the SQL CREATE TABLE command twice, once to create a customer table and once to
create a loyalty table. The commands below, included in the sampleTableDdl.sql file, generate
the tables:
After creating blank tables, we load sample data for evaluation and test purposes as described next.
5.2.2 Loading sample data
We provide two Comma Separated Value (CSV) structured data files for test and evaluation purposes.
These files are named, not too surprisingly, customers.csv and loyalty.csv respectively. We can
load data using the ncluster_loader command with appropriate parameters for this file type.
Here are sample ncluster_loader commands for loading our tables:
ncluster_loader --username authorized_user_name --password-prompt \
--csv customers customers.csv
12/15 Aster Scalar UDF Integration Guide
ncluster_loader --username authorized_user_name --password-prompt \
--csv loyalty loyalty.csv
Once these tables are loaded, we can use the UDFs to protect and access sensitive columns.
5.3 Protecting the customers table
We can test the UDF and verify proper operation by protecting the credit card column named cc in
the customers table. To do so, execute the following query from within an act shell:
Please note that the single quotes around the format name are required: the function call will
fail with double quotes. Also recall the parameter 'CC_NUM' references a data protection format
defined within the Voltage SDE infrastructure.
And compare the result set with the original data contained in the customers.csv file. Note the
original and re-identified values are identical.
Note this last query demonstrates how Voltage Format-Preserving Encryption maintains the integrity
of database table references. This serves as an example of distributing de-identified data to a third
party for the purpose of executing a loyalty marketing program.
Comments? Questions? Let us know if you have any questions or comments. Contact your Voltage
Security Voltage account manager or sales engineer. We’d love to hear about your experiences
integrating Voltage SecureData Enterprise with Aster, especially if we could change this guide to make
the task easier.
Aster Scalar UDF Integration Guide 13/15
# The directory used for building the SecureData + Aster Scalar UDF
SIMPLE_API_HOME=~/scalarUdf/simpleApi
# Directories where Simple API and certificates will be stored on the Aster
nodes
# Note the source code must be updated if these change
REMOTE_LIB_HOME=/usr/lib
REMOTE_TRUST_STORE=trustStore
# Use SSH and SCP to copy the local trust store and library to the nodes
for i in $(seq 1 8);
do
ssh $BASE_CLUSTER_NAME${i} "rm -fr $REMOTE_LIB_HOME/$REMOTE_TRUST_STORE"
ssh $BASE_CLUSTER_NAME${i} "mkdir $REMOTE_LIB_HOME/$REMOTE_TRUST_STORE"
scp * $USER@$BASE_CLUSTER_NAME${i}:$REMOTE_LIB_HOME/$REMOTE_TRUST_STORE
scp $SIMPLE_API_HOME/lib/libvibesimplejava.so
$USER@$BASE_CLUSTER_NAME${i}:$REMOTE_LIB_HOME
done
# The directory used for building the SecureData + Aster Scalar UDF
DEV_HOME=~/scalarUdf
# The URL of the SecureData appliance that hosts the web services description
language (WSDL) for tokenization
# Substitute this URL with the URL appropriate for the build environment
WSDL_URL=https://voltage-pp-
0000.dataprotection.voltage.com/vibesimple/services/VibeSimpleSOAP?wsdl
14/15 Aster Scalar UDF Integration Guide
# The bin directory for the Java software development kit (SDK)
# We recommend the latest Java, Java 1.8 as of this writing
JAVA_HOME=/home/beehive/toolchain/x86_64-unknown-linux-gnu/jdk1.8.0_101/bin