Preface

This document provides information about StrongAuth Key Appliance (SAKA) 4.0.

Default Paths and Filenames

The following table describes the default paths and filenames used in this book:

Placeholder	Description
GLASSFISH_HOME	The directory where the Payara Application Server is installed. Default location is STRONGAUTH_HOME/payara5/glassfish
JAVA_HOME	The directory where the Java Development Kit is installed. Default location is /lib/jvm/jre-11
MYSQL_HOME	The directory where the MariaDB Relational Database is installed. Default location is STRONGAUTH_HOME/mariadb-10.6.NN
REPL_HOME	The directory where StrongKey Replication Module-related files are installed. Default location is STRONGAUTH_HOME/replication
SAKA_HOME	The directory where StrongKey KeyApplianceTM 4.0-related files are installed. Default location is STRONGAUTH_HOME/saka
SKCC_HOME	The directory where StrongKey CryptoCabinetTM-related files are installed. Default location is STRONGAUTH_HOME/skcc
SKCE_HOME	The directory where StrongKey CryptoEngineTM-related files are installed. Default location is STRONGAUTH_HOME/skce
STRONGAUTH_HOME	The directory where StrongKey KeyApplianceTM 4.0 components are installed. Default location is /usr/local/strongauth
STRONGKEYLITE_HOME	The directory where StrongKey KeyApplianceTM 4.0-related files are installed. Default location is STRONGAUTH_HOME/strongkeylite

Third-party Website References

Third-party URLs are referenced herein and provide additional, related information.

NOTE: StrongKey is not responsible for third-party websites mentioned in this document. StrongKey does not endorse and is not responsible or liable for any content, advertising, products, or other materials available on or through such sites or resources. StrongKey will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services available on or through such resources.

StrongKey Welcomes Your Comments!

StrongKey is interested in improving its documentation and welcomes your comments and suggestions. To share your comments, please email info@strongkey.com referencing the title of this document in your email with your comments.

KAM Introduction

The StrongAuth KeyAppliance^TM (SAKA), StrongKey's flagship product, has undergone a radical change in the 4.0 release. The SAKA 4.0 retains all the great features of the 3.0 release, but also adds significant new capability.

The SAKA KeyAppliance Module (KAM) is a collection of technologies designed to assist companies with addressing PCI DSS, 45 CFR 170.299 (k), 201 CMR 17.00, HB-1149, and similar regulations that require encryption of sensitive data.

It does this in the following manner:

1. Securely generating, storing, using and controlling access to cryptographic keys within the system using a Federal Information Processing Standards (FIPS)140-2 Level 2 (or above) certified cryptographic Hardware Security Module (HSM) or Trusted Platform Module (TPM). These devices are designed to erase cryptographic key material rather than give it up when they sense they are being attacked. Keys generated on these devices never leave the device unless encrypted using other cryptographic keys.

2. Using only one cryptographic algorithm—the Advanced Encryption System (AES)—with a choice of 128-, 192-, or 256-bit symmetric keys for the encryption and decryption of PANs or PII.

3. Using only one cryptographic algorithms for generating Hashed Message Authentication Codes (HMAC)—while providing a choice of key sizes for the HMAC: the HmacSHA256 algorithm—with a 256-bit cryptographic key, HmacSHA224, HmacSHA384 and HmacSHA512 for preserving the integrity of encrypted data (ciphertext) in the system.

4. Storing ciphertext on the appliance system—never allowing it to leave the SAKA—while returning the calculated HMAC or a configurable pseudo-number of the PAN or PII as a “token” to be used by applications as a unique identifier for the PAN/PII.

5. By choosing the strongest algorithm and cryptographic components recommended by PCI DSS and the US National Institute of Standards and Technology (NIST), and by localizing all cryptographic processing on the SAKA and by storing ciphertext on the appliance, the SAKA narrows the scope of the application system at risk, and consequently, the scope for the PCI DSS/201 CMR 17.00/HB-1149 audit.

Architecture

SAKA is a Java Enterprise Edition 7 (JEE7) application encapsulated within an appliance, and provides secure web services to perform many different kinds of cryptographic functions. It consists of the following components:

• A JEE7 application server that hosts multiple web service applications

• A relational database that stores the ciphertext along with metadata about the ciphertext

• A cryptographic TPM or HSM that performs cryptographic functions

• A replication architecture that automatically replicates all transactions to every SAKA node defined within a cluster

• A Lightweight Directory Access Protocol (LDAP) server for authenticating and authorizing requesters of web services. In the event a site already has an LDAP directory server—such as Active Directory—SAKA can authenticate requesters against this directory server

• A FIDO-enabled web application that enables end-users to encrypt/decrypt files while storing cryptographic keys in the KA module of SAKA.

Versions of underlying components supported by SAKA in the current release are shown here:

Component	Name	Version
OperatingSystem	Rocky Linux (64-bit)	9.1
Java Virtual Machine	OpenJDK	11
Relational Database	MariaDB RDBMS	10.6
JEE7 Application Server	Payara	5
HSM Software	SafeNet Protect Toolkit C	7.2
	Utimaco CryptoServer	4.50.0.1
HSM Java Software	SafeNet Protect Toolkit J	7.2
	Utimaco CryptoServer JCE	4.50.0.1
Replication Software	JeroMQ	0.5.1
LDAP Service	OpenLDAP	2.4.46
	Microsoft Active Directory	Windows 2019

In the current release, SAKA supports the cryptographic algorithms and sizes shown below. StrongKey has chosen to restrict the algorithms and key sizes to the the strongest available. As guidelines from PCI and/or NIST evolve, so will SAKA to support the recommended algorithms and key sizes.

Algorithm	Purpose	Size
Elliptic Curve (EC)	Key Encryption	256-bit
	Key Custodian Authentication	256-bit
	Domain Administrator Authentication	256-bit
Advanced Encryption Standard	Data Encryption	128-, 192- and 256-bit
Hashed Message Authentication Code	Message Integrity	224-, 256-, 384- and 512-bit

Installation

Strongkey’s StrongAuth KeyAppliance (SAKA) is designed to be installed as a cluster with N appliances (nodes)in the cluster. A Development environment may have only a single node, while a Production environment must have a minimum of two (2) nodes. This is necessary to provide High Availability (HA) for cryptographic services to applications, and to ensure business continuity in the event of a disaster. A cluster may have more than two appliances, but two is the minimum. (If there are more than two nodes in the cluster, the third, fourth, etc. node follow the same steps as the second node).

As a result, SAKA installation follows a process where the tasks are alternated between two appliances. This chapter describes these tasks. The appliance expected to be installed first is known as the Primary SAKA, while appliances installed after the first SAKA instance are designated as Secondary SAKA in this documentation.

NOTE: Notwithstanding the designation of Primary and Secondary nodes within a SAKA 4.0 cluster, all nodes in the cluster are equal: they can receive and respond to web service requests simultaneously while replicating to each other asynchronously. While the replication latency depends on the network bandwidth between nodes of the cluster, the level of traffic on the network, and the number of transactions being processed at any given time, replication latency between nodes is generally in the order of seconds or minutes. If a node disappears from the cluster for any reason, all other nodes hold transactions for the missing node until it returns; when it does, synchronization is automatic.

When SAKA servers are delivered, the Linux operating system has already been installed with the necessary packages to operate the appliance. The operating system is partially configured; some parameters can only be configured upon connecting them to a network.

The uninstalled software components used by the SAKA application are delivered in the /usr/local/software/saka directory of each appliance.

At a high level, after choosing site-specific parameters in the forms shown in this chapter, the sequence of installation steps involves:

1. Installing the Primary with required software components—but not initializing the cryptographic module.

2. Installing the Secondary with required software components—but not initializing the cryptographic module.

3. Initializing the cryptographic module on the Primary.

4. Initializing the cryptographic module on the Secondary.

5. Creating a new encryption domain on the Primary, preparing the master key of the new domain for migration and testing the cryptographic web services on this appliance.

6. Completing the migration of the new encryption domain's master key on the Secondary and testing the cryptographic web services on this appliance.

7. Starting the appliance's administration console, adding service credentials for applications, configuring site-specific parameters, and running some tests.

8. Verifying two-way replication on the appliances.

Each SAKA ships with five (5) colored USB flash memory drives. The colored USB drives are intended to be used as described here:

Colored USB Drives and their Functions
	The Red flash drive is for use by the Key Custodian (KC) #1 for generating and storing their cryptographic keys and digital certificate. The KC1 who is also a Key Custodian, will use this credential to activate the cryptographic module on SAKA.
	The Green flash drive is for use by KC #2 for generating and storing their cryptographic keys and digital certificate. KC2 will use this credential to activate the cryptographic module on SAKA.
	The Blue flash drive is for use by KC #3 for generating and storing their cryptographic keys and digital certificate. KC3 will use this credential to activate the cryptographic module on SAKA.
	The Yellow flash drive is for use by the Domain Administrator (DA) for generating and storing their cryptographic keys and digital certificate. The DA will use this credential to administer SAKA.
	The Black flash drive is used optionally during the installation and configuration of SAKA instances to securely transfer the Migration and Storage Keys (MASK) of individual appliances to each other as a preparatory step.

NOTE: While the Production environment only needs four (4) USB flash drive tokens—Red, Green, Blue and Yellow—on a regular basis, it is recommended that the remaining flash drive tokens are used as secure backups of the primary tokens, in the event any of the primary tokens are lost/damaged. Without the tokens, the cryptographic hardware module cannot be activated; without the cryptographic hardware module, it is impossible to decrypt any cryptographic key in the appliance.

Preliminary Steps

Before getting started with the installation of the appliances, it is helpful to use the following checklist to smooth the process. All passwords should be written down on index cards, sealed in envelopes, and locked away. While the users responsible for the passwords will maintain them in memory, these envelopes will serve as backups in the event the responsible individual is unavailable to carry out a task. To print a copy, use this .PDF version instead.

saka01.[your-domain-name]

saka02.[your-domain-name]

Before starting the installation, both servers must be connected to the network. During the installation process, it is helpful for the appliances to be next to each to facilitate the exchange of key-material. After the installation is completed successfully, the Secondary SAKA can be relocated to its permanent destination. While the SAKA might undergo a change of the TCP/IP address when they move to their permanent location, the FQDN must remain the same.

As each operation is described, the server (Primary or Secondary) upon which it is performed will be bracketed in the heading.

Install Components [Primary]

Installation of SAKA begins on the Primary server. It installs the various components for the SAKA environment. It is assumed that the installers are familiar with Linux commands and the Linux operating system environment.

1. If your appliance uses the TPM, verify that the BIOS Setup has activated the TPM. Steps will vary based on the supplier of the BIOS on the appliance; while one manufacturer will identify the task as “Enable the TPM”, another might indicate this as “Enable embedded security.” In either case, the task will require setting up a password for the BIOS Setup and then activating the TPM.

2. Login to SAKA as root.

3. Start up a shell window.

4. Change the password of the root user to the one chosen for your site:
   

   shell> passwd

5. Change directory to /usr/local/software/saka.
   

   shell> cd /usr/local/software/saka

6. If the SAKA software distribution is not on the machine, unarchive the distribution to the /usr/local/software/saka directory:
   

   shell> tar zxvf /media/<device name>/SAKA-4.0-BuildNN-dist.tgz

7. Using a text editor (gedit or vi), edit the following section of the install-saka.sh script to customize IP address, passwords, database size, etc.
   

   ##########################################
   # Company name for self signed certificate
   COMPANY="StrongAuth Inc"
   
   # Server Passwords
   GLASSFISH_PASSWORD=adminadmin
   LINUX_PASSWORD=ShaZam123
   MARIA_ROOT_PASSWORD=BigKahuna
   MARIA_SKLES_PASSWORD=AbracaDabra
   
   # Batch Request user 
   BR1_LINUX_USERNAME=domain1
   BR1_LINUX_PASSWORD=Prest099
   BR1_LINUX_LOCK='Y'                      # Lock Batch request user?
   
   # Servers in cluster. For larger clusters, add more lines like 'SERVER#=<FQDN>' where # = SID
   SERVER1=saka201.strongauth.com
   SERVER2=saka202.strongauth.com
   #SERVER3=saka203.strongauth.com
   #SERVER4=saka204.strongauth.com
   
   ##########################################

   • The COMPANY name will be embedded in the digital certificates generated during the installation process. Replace the default value with the name of your company. Do not use commas or special characters in the name; while spaces are allowed, restrict the name to 64 characters or less.

   • The GLASSFISH_PASSWORD parameter is the password for the admin user for the Payara application server. The admin user is responsible for administrating the Payara server through the provided asadmin command line tool.

   • The LINUX_PASSWORD parameter is the password for the strongauth user in the Linux operating system environment. The strongauth user owns all files installed under /usr/local/stronguath and is the owner of the SAKA application. While this password is initially used to setup the account and its privileges, this may be changed at a later time, if desired.

   • The MARIA_ROOT_PASSWORD parameter is the password for the root user of the MariaDB database. While this password is initially used to setup the account and its privileges, this may be changed at a later time, if desired.

   • The MARIA_SKLES_PASSWORD parameter is the password for the skles user of the MariaDB database. While this password is initially used to setup the account and its privileges, this may be changed at a later time, if desired.

   • The BR1_LINUX_USERNAME parameter is the name of the batch request user in the Linux operating system environment. This user is used to transfer files to and from the appliance for batch processing operations of the first encryption domain.

   • The BR1_LINUX_PASSWORD parameter is the password for the domain1 user in the Linux operating system environment. While this password is initially used to setup the account and its privileges, this may be changed later, if desired.

   • The BR1_LINUX_LOCK parameter is to determine whether the batch request user account will be locked. The account is locked by default. If you expect to use the batch processing features of the appliance, change the value of this variable to N.

   • The SERVER# variables define the servers in the SAKA cluster. For every appliance that will be a member of the cluster, create a variable named SERVER<SID> where SID is a numerically incrementing value starting at 1 with no gaps in the sequence. Assign the FQDN of each appliance to these variables.

8. Run the install-saka.sh script:

   shell> ./install-saka.sh

9. Log out of SAKA.

10. Login to SAKA as strongauth.

11. Start up two (2) shell windows.

Install Components [Secondary]

This step installs all the required components for the appliance on a Secondary server.

1. If your appliance uses the TPM, verify that the BIOS Setup has activated the TPM. The actual steps will vary based on the supplier of the BIOS on the appliance. While one manufacturer will identify the task as “Enable the TPM”, another might indicate this as “Enable embedded security”. In either case, the task will require setting up a password for the BIOS Setup and then activating the TPM.

2. Login to SAKA as root.

3. Start a shell window.

4. Change the password of the root user to the one chosen for your site:
   

   shell> passwd

5. Change directory to /usr/local/software/saka.
   

   shell> cd /usr/local/software/saka

6. If the SAKA software distribution is not on the machine, unarchive the distribution to the /usr/local/software/saka directory:
   

   shell> tar zxvf /media/<device name>/SAKA-4.0-BuildNN-dist.tgz

7. Using a text editor (gedit or vi), edit the install-saka.sh script to customize IP address, passwords, database size, etc.

   NOTE: All parameters must be identical to those chosen for the Primary SAKA.

8. Run the install-saka.sh script:
   

   shell> ./install-saka.sh

9. Log out of SAKA.

10. Login to SAKA as strongauth.

11. Start up two (2) shell windows.

Define KCs [Primary]

The next process defines the three KCs for the environment, initializes the cryptographic hardware module, and starts the process of migrating the appliance's master key to the Secondary appliance.

1. In Window2, use the shell-alias tsl to tail the Payara server logs so you can watch the output of the server application as it scrolls by:
   

   shell> tsl

2. In Window1, change directory to /usr/local/strongauth/bin.
   

   shell> cd ~/bin

3. In Window1, execute Primary-SAKA-KeyCustodian-Setup-Wizard.sh.

   shell> ./Primary-SAKA-KeyCustodian-Setup-Wizard.sh

4. Complete the wizard steps, ensuring there are no errors in Window1 or Window2. If there are any errors, determine the cause of the error, log out of the session, log back in as root and execute the cleanup.sh script to clean out the installation. Fix the cause of the error and start the installation process with 4.1.1—Install Components [Primary].

Verify KCs [Secondary]

This process verifies the credentials of the three KCs from the Primary SAKA server, initializes the cryptographic hardware module, and starts the process of migrating the appliance's master key to the Primary appliance.

1. In Window2, use the shell alias TSL to tail the Payara server logs so you can watch the output of the server application as it scrolls by:
   

   shell> tsl

2. In Window1, change directory to /usr/local/strongauth/bin.
   

   shell> cd ~/bin

3. In Window1, execute Secondary-SAKA-Setup-Wizard.sh.
   

   shell> ./Secondary-SAKA-Setup-Wizard.sh

4. Follow the wizard steps to completion, ensuring there are no errors in Window1 or Window2. If there are any errors, determine the cause of the error, log out of the session, log back in as root and execute the cleanup.sh script to clean out the installation. Fix the cause of the error and start the installation process with 4.1.2—Install Components [Secondary].

Set Personal Identification Numbers (PINs) [Primary]

The PINs of the three KCs are set to activate the cryptographic hardware module and a new encryption domain is created.

1. In Window1, use sudo and restart the Payara application server (supply the strongauth user's password when prompted).
   

   shell> sudo /sbin/service glassfishd restart

2. In Window1, execute KC-SetPINTool.sh.
   

   shell> ./KC-SetPINTool.sh

3. Using the red, green, and blue flash drives, set the PINs for the three KCs to activate the cryptographic hardware module on the appliance, ensuring there are no errors in either window.

4. In Window1, execute New-Domain-Setup-Wizard.sh.
   

   shell> ./New-Domain-Setup-Wizard.sh

5. Follow the steps of the wizard, ensuring there are no errors in Window1 or Window2. If there are any errors, determine the cause of the error, log out of the session, log back in as root, and execute the cleanup.sh script to clean out the installation. Fix the cause of the error and start the installation process with 4.1.1—Install Components [Primary].

Set PINs and Complete Key Migration [Secondary]

This step duplicates the previous step on the Secondary server and completes the key migration process for the encryption domain that was just created.

1. In Window1, use sudo and restart the Payara application server (supply the strongauth user's password when prompted):
   

   shell> sudo /sbin/service glassfishd restart

2. In Window1, execute the KC-SetPINTool.sh.
   

   shell> ./KC-SetPINTool.sh

3. Using the red, green, and blue flash drives, set the PINs for the three KCs to activate the cryptographic hardware module on the appliance, ensuring no errors in either window.

4. In Window1, execute Secondary-SAKA-Replication-Final.sh.
   

   shell> ./Secondary-SAKA-Replication-Final.sh

5. Follow the steps of the wizard, ensuring there are no errors in Window1 or Window2. If there are any errors, determine the cause of the error, log out of the session, log back in as root, and execute the cleanup.sh script to clean out the installation. Fix the cause of the error and start the installation process with 4.1.2—Install Components [Secondary].

Create System Users [Primary]

This introduces the Domain Administration Console (DAC) Tool, modifying the encryption domain configuration to add at least two (2) users to the SAKA internal database.

1. In Window1, execute the DACTool.sh script.
   

   shell> ./DACTool.sh

2. Using the yellow flash drive, set the preferences for the Domain Administrator and then connect to saka01.

3. Under the Users section, create at least two users:

   Username: encryptdecrypt Privileges: encrypt, decrypt

   Username: pinguser Privilege; decrypt

4. The encryptdecrypt user will be the calling application's main credential to consume the SAKA web service. The name of this user can be modified if another name is preferred, but it is important that the name of the pinguser stays as pinguser.

5. Additional users beyond these two may be created with whatever privilege desired.

6. In Window1, import the self-signed certificate from the Secondary SAKA with certimport.sh:
   

   shell> ./certimport.sh saka02.<domain-name>

7. In Window1, change directory to the /usr/local/strongauth/topaz directory:
   

   shell> cd ~/topaz

8. In Window1, execute sakamlient.jar as follows to “ping” both appliances simultaneously.
   

   shell> java -jar sakamclient.jar https://saka01.<domain-name>:8181, https://saka02.<domain-name>:8181 <domain-id> <password> P

9. Two threads call the appliance “ping” web service. If both servers are “alive”, the installation was successful.

Create a New Encryption Domain [Primary]

Create and replicate a new encryption domain on the SAKA cluster. SKCE and SKCC require a dedicated encryption domain to escrow the encryption keys used by SKCE.

1. In Window1, change directory to /usr/local/strongauth/bin.
   

   shell> cd ~/bin

2. In Window1, execute the script, New-Domain-Setup-Wizard.sh.
   

   shell> ./New-Domain-Setup-Wizard.sh

3. Follow the steps of the wizard, ensuring there are no errors in Window1 or Window2. If there are any errors, determine the cause of the error, log out of the session, log back in as root, and execute the cleanup.sh script to clean out the installation. Fix the cause of the error and start the installation process with 4.1.1—Install Components [Primary].

Complete Second Domain Key Migration [Secondary]

Complete the key migration process for the second domain created in the previous step.

1. In Window1, execute the script, Secondary-SAKA-Replication-Final.sh.
   

   shell> ./Secondary-SAKA-Replication-Final.sh

2. Follow the steps of the wizard, ensuring there are no errors in Window1 or Window2. If there are any errors, determine the cause of the error, log out of the session, log back in as root, and execute the cleanup.sh script to clean out the installation. Fix the cause of the error and start the installation process with 4.1.2—Install Components [Secondary].

Add System Users [Primary]

Use the DACTool to add two users to SAKA's internal database.

1. In Window1, execute DACTool.sh.
   

   shell> ./DACTool.sh

2. Using the yellow flash drive, set the preferences for the Domain Administrator and then connect to saka01.

3. Under the Users section, create at least two users:

   Username: encryptdecrypt Privileges: encrypt, decrypt

   Username: pinguser Privilege: decrypt

4. In Window1, change directory to the /usr/local/strongauth/topaz directory:
   

   shell> cd ~/topaz

5. In Window1, execute the sakamlient.jar client application to ping both appliances simultaneously.
   

   shell> java -jar sakamclient.jar https://saka01.<domain-name>:8181, https://saka02.<domain-name>:8181 <domain-id> <password> P

6. Two threads will attempt to call the ping web service of the appliances and report on their success. If both machines report they are alive, the installation was successful.

Configure the SKCE domain [Primary]

The SKCE module—to be hereafter called the CryptoEngine Module (CEM) in SAKA—requires configuration changes to access the newly created domain. Even if the CEM will not be used it is necessary to make these configurations. Follow these steps to configure the CEM:

1. In Window1, if using a self-signed certificate for the FIDO applicationID, import it into the Payara TrustStore using the certimport script:
   

   shell> certimport.sh <FQDN> -p<PORT> -kGLASSFISH

   Examples:
   

   certimport.sh saka01.strongauth.com -p8181 -kGLASSFISH certimport.sh www.domain.com -p443 -kGLASSFISH

2. In Window1, execute create-SKCE-Users.sh to setup service credentials for the CEM. Specify 2 for domain number 2 and a password for the service credentials:
   

   shell> ./create-SKCE-Users.sh 2 <password>

3. In Window1, change directory to /usr/local/strongauth/skce/etc.
   

   shell> cd ~/skce/etc

4. Edit the skce-configuration.properties file.

   Update the value of the following two properties to reflect the values specified in Section 7, Step 3:
   

   skce.cfg.property.saka.cluster.1.domain.1.password=skce.cfg.property.saka.cluster.1.domain.1.username=

5. In Window1, change directory to /usr/local/strongauth/skcc/etc.
   

   shell> cd ~/skcc/etc

6. Edit the skcc-configuration.properties file. Update the value of the following two properties to reflect the pinguser password specified in Section 7, Step 3 for the property skcc.cfg.property.sakapwd and the value of the passwords in Section 10, Step 3 for the following properties:
   skcc.cfg.property.service.cc.ce.password
skcc.cfg.property.service.cc.fe.password
skcc.cfg.property.service.cc.ce.ping.password
   

   skcc.cfg.property.sakapwd=skcc.cfg.property.service.cc.ce.password=skcc.cfg.property.service.cc.fe.password=skcc.cfg.property.service.cc.ce.ping.password=

7. In Window1, use sudo and restart the Payara application server (supply the strongauth user's password when prompted):
   

   shell> sudo /sbin/service glassfishd restart

8. In Window1, change directory to /usr/local/strongauth/bin.
   

   shell> cd ~/bin

9. In Window1, execute the script, KC-SetPINTool.sh.
   

   shell> ./KC-SetPINTool.sh

10. Using the red, green, and blue flash drives, set the PINs for the three Key Custodians to activate the cryptographic hardware module on the appliance, ensuring there are no errors in Window1 or Window2.

Replicate the CEM Domain [Secondary]

The final step of the installation replicates the CEM domain on the Secondary SAKA.

1. In Window1, execute create-SKCE-Users.sh to setup service credentials for the CEM. Specify 2 for domain number 2 and a password for the service credentials:
   

   shell> ./create-SKCE-Users.sh 2 <password>

   This should be the same password as provided in Section 10, Step 2.

2. In Window1, change directory to /usr/local/strongauth/skce.
   

   shell> cd ~/skce

3. In Window1, securely copy the keystore files directory from the primary node to this node using scp or sftp to perform this task:
   

   shell> scp -r strongauth@<primary-node>:skce/keystores .

4. In Window1, change directory to /usr/local/strongauth/skce/etc.
   

   shell> cd ~/skce/etc

5. Edit the skce-configuration.properties file. Update the value of the following two properties to reflect the values specified in Section 10, Step 2:
   

   skce.cfg.property.saka.cluster.1.domain.1.password=skce.cfg.property.saka.cluster.1.domain.1.username=

6. In Window1, change directory to /usr/local/strongauth/skcc/etc.
   

   shell> cd ~/skcc/etc

7. Edit the skcc-configuration.properties file. Update the value of the following two properties to reflect the pinguser password specified in Section 7, Step 3 for the property skcc.cfg.property.sakapwd and the passwords from Section 10, Step 3:

   skcc.cfg.property.service.cc.ce.password, skcc.cfg.property.service.cc.fe.password, and skcc.cfg.property.service.cc.ce.ping.password
   

   skcc.cfg.property.sakapwd=
   skcc.cfg.property.service.cc.ce.password=
   skcc.cfg.property.service.cc.fe.password=
   skcc.cfg.property.service.cc.ce.ping.password=

8. In Window1, if using a self-signed certificate for the applicationID (see Section 11), import it into the Payara TrustStore using the certimport script:
   

   shell> certimport.sh <FQDN> -p<PORT> -kGLASSFISH

   Examples:
   

   certimport.sh saka01.strongauth.com -p8181 -kGLASSFISH certimport.sh www.domain.com -p443 -kGLASSFISH

9. In Window1, use sudo and restart the Payara application server (supply the strongauth user's password when prompted):
   

   shell> sudo /sbin/service glassfishd restart

10. In Window1, change directory to /usr/local/strongauth/bin.
    

    shell> cd ~/bin

11. In Window1, execute KC-SetPINTool.sh.
    

    shell> ./KC-SetPINTool.sh

12. Using the red, green, and blue flash drives, set the PINs for the three KCs to activate the cryptographic hardware module on the appliance, ensuring there are no errors in Window1 or Window2.

This concludes the installation of the SAKA cluster. If you have any questions or problems, please contact support@strongkey.com or call us at (408) 331-2000.

Details about how to configure the appliance for a specific environment are presented in 14—KAM Configuration.

Detailed documentation about configuring individual components of SAKA are available at the following sites. It is strongly recommended that you make a full backup of SAKA before making any change that might affect the operations of the appliance.

NOTE: On machines using the TPM, resetting the TPM from the BIOS setup (or any other software that interacts with the TPM directly) will permanently delete the EC keys within the module, thus invalidating all keys and encrypted data within SAKA. It is strongly recommended that the BIOS password is protected very carefully and any administration of the appliance at the BIOS level is performed very carefully.

CCS Web Service Operations

The Card Capture Service (CCS) web service application supports an array of web services for working with the ANSI X9.24-1:2009 Derived Unique Key Per Transaction (DUKPT) algorithm for protecting data and Personal Identification Numbers (PINs). Client applications send requests to the CCS through a standard Simple Object Access Protocol (SOAP)—or Representational State Transfer (REST)-based web services over the Secure Hyper Text Transfer Protocol (HTTPS).

SOAP-based web service calls can be expected to return a CCReturnObject (see definition below). In the case of some errors, you should also anticipate the return of either StrongKeyLiteExceptions or CCExceptions. REST-based web service calls will return HTTP Status Codes corresponding with the success or type of failure encountered. Successful operations always return a 200 OK alongside a JavaScript Object Notation (JSON) or Extensible Markup Language (XML) response. A JSON will be returned unless strongkeylite.cfg.property.ccsresponseformat is overwritten on the SAKA server to specify that “xml” responses should be returned. Other valid Response Statuses specific to failure conditions include:

• 400 Bad Request

• 401 Unauthorized

• 404 Not Found

• 500 Internal Server Error

CCReturnObject

The following example defines the CCReturnObject type. A line-by-line explanation follows.

#	XML Content
1	<xs:complexType name="CCReturnObject">
2	<xs:sequence>
3	<xs:element name="did" type="xs:long" minOccurs="0"/>
4	<xs:element name="messagekey" type="xs:string" minOccurs="0"/>
5	<xs:element name="message" type="xs:string" minOccurs="0"/>
6	<xs:element name="objectContent" type="xs:anyType" minOccurs="0"/>
7	<xs:element name="objectType" type="xs:int" minOccurs="0"/>
8	<xs:element name="srid" type="xs:long" minOccurs="0"/>
9	</xs:sequence>
10	</xs:complexType>

#	XML Content Explanation
1	The start of the CCReturnObject element.
2	The start of a sequence.
3	The DID element—the identifier of the encryption domain that serviced this request.
4	The messagekey element—a message code used by the appliance as a reference. Messages of the format 'SKL-MSG-NNNN' indication a success and message of the format 'SKL-ERR-NNNN' indication failures (where NNNN are numerals).
5	The message element—a message which describes a success or a failure condition.
6	The objectContent element—a JSON or XML that contains the result of a successful web service operation. A JSON will be returned by default unless the encryption domain's or SAKA's strongkeylite.cfg.property.ccsresponseformat property is overwritten on the server.
7	The objectType element—an integer value identifying the kind of object returned. 1 = CC_DATA 2 = CC_DIGEST 3 = CC_ENCRYPTED_OBJECT 4 = CC_ENCRYPTED_SYMMETRIC_KEY 5 = CC_ENCRYPTED_SYMMETRIC_KEYS 6 = TOKEN 7 = DECRYPTED_XML 8 = REENCRYPTED_PIN 9 = KEY_CHECK_VALUE 10 = MAC_REQUEST 11 = MAC_RESPONSE
8	The srid element—a unique request identifier for this transaction.
9	The end of the sequence.
10	The end of the CCReturnObject.

Manufacturer Identifiers for Processing CardHolder Data (CHD)

All CCS operations require a cryptographic key—usually called a Base Derivation Key (BDK)—to be identified for use in the web service operation. Each web service provides one or more mechanisms for identifying the right key to use for that operation. One mechanism is to identify a BDK based on a Manufacturer Identifier, as shown in the following table. At any time in a particular domain, there can only be a single BDK loaded into the appliance per manufacturer for use by SAKA in processing CCS transactions. Note that this does not prevent storing many BDKs on SAKA, but for decrypting CHD only one BDK may be loaded for use per manufacturer. By supplying the manufacturer ID as a web service parameter, you can instruct the appliance to use the corresponding BDK for that manufacturer in the DUKPT operation the web service will be performing.

Additionally in the case of the GetCardCaptureData web service, the manufacturer ID also determines how the appliance will parse the card-swipe captured, encrypted, and provided by your application to SAKA for processing. Every terminal manufacturer defines their CHD swipe data format differently, so it is important that the correct manufacturer ID parameter is passed in when submitting a request to the GetCardCaptureData web service. A list of manufacturers by their associated identifiers follows here:

ID TECH	0
UIC	1
MagTek	2
Infinite	3
Dejavoo	4
PAX	5
PADV6	6

NOTE: When processing PINs from cards, this parameter is irrelevant.

CCS Module GetCardCaptureData Mechanics

The GetCardCaptureData GCD) operation receives a card swipe (along with other parameters to authenticate and authorize the transaction), decodes it according to the manufacturer-specific definition of their swipe format, decrypts the track data using the DUKPT algorithm for data-decryption, and either tokenizes or returns the PAN (based on SAKA configuration parameters; by default, only a token is returned). It uses a previously stored BDK identified by the manufacturer ID. The web service operation requires six parameters:

DID	The unique encryption domain identifier.
username	The username (service-credential) within the encryption domain with the authorization to call this web service. The credential requires the Encryption privilege at a minimum, but may also require Decryption privileges within the encryption-domain if a plaintext PAN is to be returned.
password	The password of the username to authenticate the credential of the requester.
ccd	The hex-encoded data containing the captured data. Note that all CCS web services operate on hex-encoded data.
mfr	The numerical identifier of the manufacturer of the device that captured the card data.
dsn	The device serial number (DSN) of the device that captured the card data. This value is required, but only currently used for logging purposes.

When SAKA receives the request, it verifies the credentials presented in the web service operation against its internal database, or an optional LDAP directory server, and then determines their authorization to request the GetCardCaptureData service by determining if they are a member of the EncryptionAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the installation process of SAKA; when using the SAKA internal database, this group is created automatically.

If the requester is authorized, SAKA starts by decoding the ccd parameter based on the manufacturer-specific format. The manufacturer can be provided with the mfr parameter, or optionally set automatically via the SAKA configuration property strongkeylite.cfg.property.defaultmanufacturer. If the swipe is properly formatted and can be successfully decoded, the encrypted track data is decrypted using the BDK loaded for this manufacturer. The track data is then parsed to extract details such as Expiration Date, IssuerID, Cardholder Name, etc.

By default, the PAN will be encrypted by the appliance and a token will be returned in the response. If tokenization is not desired, the SAKA configuration property strongkeylite.cfg.property.ccsautodelete must be set to true. Alternatively or in addition to returning a token, the PAN can be returned in a plaintext format if the SAKA configuration property strongkeylite.cfg.property.ccsplaintextpan is set to true. When strongkeylite.cfg.property.ccsplaintextpan is true, the service credential requesting the PAN must also be a member of the DecryptionAuthorized group in addition to being a member of the EncryptionAuthorized group.

On success, the following will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object:

DID	Unique encryption domain identifier for the domain that serviced this request.
SRID	Unique request identifier for this transaction.
Token	(Optional) If strongkeylite.cfg.property.ccsautodelete is set to false (default: false), a token value is returned that references the PAN. This token can always be supplied to the decrypt web service by authorized applications for recovery of the PAN.
PAN	(Optional) If strongkeylite.cfg.property.ccsplaintextpan is set to true (default: false), the plaintext PAN from the swipe is returned.
ExpiryDate	Four digits to represent the expiration month and expiration year of the card.
ExpiryMonth	Two digits to represent the expiration month of the card.
ExpiryYear	Two digits to represent the expiration year of the card.
MaskedPAN	Masked PAN as received in any available masked data provided in the swipe.
Digest	Always null. Reserved for future use.
Valid	True if this PAN conforms to the Luhn Algorithm.
Exists	(Optional) If strongkeylite.cfg.property.ccsautodelete is set to false (default: false), Exists will be true if this PAN is already encrypted by the appliance.
AssociationID	The Card Association ID recovered from the track data.
IssuerID	The Card Issuer ID recovered from the track data.
CardholderName	The full name of the cardholder.
Firstname	The first name of the cardholder.
Lastname	The last name of the cardholder.
Track2	(Optional) If strongkeylite.cfg.property.ccsprocesstrack2 is set to true (default: false), track2 data will be returned. If strongkeylite.cfg.property.ccsautodelete is false, the PAN portion of the track2 data will be replaced with a token. If strongkeylite.cfg.property.ccsplaintextpan is true, the track2 data will be returned raw, even if strongkeylite.cfg.property.ccsautodelete is false. If strongkeylite.cfg.property.ccsautodelete is true but strongkeylite.cfg.property.ccsplaintextpan is false, the Track2 element will be null as neither a token or the PAN is authorized for return.
Notes	Always null. Reserved for future use.

CCS Module DukptEncrypt Mechanics

The DukptEncrypt (DENC) operation encrypts a hex-encoded plaintext using a key derived from the BDK and Key Serial Number (KSN). The cryptographic algorithm and type of cryptographic key to be derived from the BDK+KSN combination are specified as parameters to determine the type of encryption to be performed. The web service operation requires eight (of a total of nine) parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The credential requires the Encryption privilege at a minimum, but may also require Decryption privileges if the BDK is recovered through a token parameter in the web service.
password	The password of the username to authenticate the credential of the requester.
bdktoken	The token that references the escrowed BDK. If this parameter is specified, the mfr parameter must be null. Also, by specifying this parameter, the user making the web service must also have Decryption privilege.
mfr	The numerical identifier of the manufacturer for which this BDK is assigned. If this parameter is specified, the bdktoken parameter must be null.
ksn	The key serial number (KSN) to use to generate a derived key. This must be exactly 10 bytes and must be formatted as a hex-encoded string.
plaintext	The plaintext to be encrypted. The plaintext must be sent to the web service as a hex-encoded string. Even if the plaintext is only alphanumeric characters, it is expected that the plaintext value is hex-encoded for transport to the web service.
algorithm	The algorithm to use for this encryption. Valid choices are TDES and AES. Alternately, a full transform can be specified in format, “AES/CBC/ZeroBytePadding” if the default mode and padding of each derivedkeytype needs to be overwritten. Continue reading the description of the web service mechanics for more details.
derivedkeytype	The type of key to be derived by the DUKPT process. Valid choices are: “DEK” (Data Encryption Key, request or both ways) “DEK_RESPONSE” (Data Encryption Key, response) “PIN” (PIN Encryption Key) “MAC” (Message Authentication Key, request or both ways) “MAC_RESPONSE” (Message Authentication Key, response)

When SAKA receives the request, it verifies the credentials presented against its internal database or an optional LDAP directory server, and determines their authorization to request the DukptEncrypt service by verifying if they are a member of the EncryptionAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the installation process of SAKA; when using the SAKA internal database, this group is created automatically.

If the requester is authorized, SAKA proceeds to recover the BDK for this operation. If the manufacturer ID is provided in the web service call, the BDK associated with the manufacturer is recovered. If a BDK token is provided, the BDK is recovered based on that token. In this case, the user must also be a member of the DecryptionAuthorized group.

Using the BDK and portions of the provided KSN, an initial key (sometimes called the Initial PIN Encryption Key or IPEK) is derived. Using the IPEK, the derived key (of the type requested for this transaction) is generated based on other portions of the KSN. Each type of derived key has a default encryption mode and padding associated with it:

Derived Key Type	Encryption Mode	Padding
DEK	CBC	ZeroBytePadding
DEK_RESPONSE	CBC	ZeroBytePadding
PIN	ECB	NoPadding
MAC	ECB	NoPadding
MAC_RESPONSE	ECB	NoPadding

If the default encryption mode and padding for your chosen type of derived key is correct, then you will just need to select either “AES” or “TDES” as the algorithm in the web service request. You can overwrite the default or explicitly state your preferred encryption mode and padding by supplying the full cryptographic transform as the algorithm parameter in the web service. For instance, a TDES PIN key can be derived and encrypted in CBC mode with ZeroBytePadding if the algorithm web service parameter is specified as “DESede/CBC/ZeroBytePadding”. Take notice that in this case, we specify Triple DES algorithm using Java's official name for the algorithm “DESede.”

NOTE: StrongKey has currently tested only the Electronic Code Book (ECB) and Cipher Block Chain (CBC) modes of encryption and, for the ANSI DUKPT processing module, only ZeroBytePadding and NoPadding mode of padding. Additionally, when using the CBC mode of encryption, the only currently supported Initialization Vector (IV) is an all-zero block. If other encryption modes, padding types, or IVs are desired, please contact support@strongkey.com.

To learn more about Java cryptographic algorithms, modes of encryption and padding, please refer to the Java Cryptography Architecture (JCA) Reference Guide.

Once the plaintext is encrypted, the result is hex-encoded and the following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object:

DID	The unique encryption domain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
BDKToken	The BDKToken used to service this request (or null if the BDK token was not specified as a web service parameter).
MFR	The manufacturer ID used to service this request (or null if the manufacturer ID was not specified as a web service parameter).
KSN	The KSN used to service this request.
Ciphertext	The ciphertext generated from this request, formatted as a hex-encoded string.

CCS Module DukptDecrypt Mechanics

The DukptDecrypt (DDEC) operation decrypts a hex-encoded ciphertext string using a key derived from the BDK and KSN. The algorithm and type of derived key are specified as parameters to determine the type of decryption to be performed. The web service operation requires eight (of a total of nine) parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The user requires the Decryption privilege to execute this operation.
password	The password of the username to authenticate the credential of the requester.
bdktoken	The token that references the BDK within the SAKA encryption domain. If this parameter is specified, the mfr parameter must be null.
mfr	The numerical identifier of the manufacturer for which this BDK is assigned. If this parameter is specified, the bdktoken parameter must be null.
ksn	The KSN to use to generate the derived key. This must be exactly 10 bytes sent to the web service, formatted as a hex-encoded string.
ciphertext	The ciphertext to be decrypted. The ciphertext must be sent to the web service as a hex-encoded string.
algorithm	The algorithm to use for this decryption. Valid choices are “TDES” and “AES.” Alternatively, a full transform can be specified in the form of “AES/CBC/ZeroBytePadding” if the default mode and padding of each derived key type needs to be overwritten. Continue reading the description of the web service mechanics for more details.
derivedkeytype	The type of key to be derived by the DUKPT process. Valid choices are: “DEK” (Data Encryption Key, request or both ways) “DEK_RESPONSE” (Data Encryption Key, response) “PIN” (PIN Encryption Key) “MAC” (Message Authentication Key, request or both ways) “MAC_RESPONSE” (Message Authentication Key, response)

When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the DukptDecrypt service by verifying if they are a member of the DecryptionAuthorized group. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the installation process for SAKA; when using the internal database on SAKA, this group is created automatically.

If the requester is authorized, SAKA proceeds to recover the BDK for this operation. If the manufacturer ID is provided in the web service call, the BDK associated with the manufacturer is recovered. If a BDK Token is provided, the BDK is recovered based on that token.

Using the BDK and portions of the provided KSN, an IPEK is derived. Using the IPEK, the derived key (of the type requested for this transaction) is generated based on other portions of the KSN. Each type of derived key has a default encryption mode and padding associated with it.

Those defaults are listed in the following table:

Derived Key Type	Encryption Mode	Padding
DEK	CBC	ZeroBytePadding
DEK_RESPONSE	CBC	ZeroBytePadding
PIN	ECB	NoPadding
MAC	ECB	NoPadding
MAC_RESPONSE	ECB	NoPadding

If the default decryption mode and padding for your chosen type of derived key are correct, you will just need to select either “AES” or “TDES” as the algorithm in the web service request. You can override the default values, or explicitly state your preferred decryption mode and padding, by supplying the full cryptographic transform as the algorithm parameter in the web service. For instance, a TDES PIN key can be derived and decrypted in CBC mode with ZeroBytePadding if the algorithm web service parameter I s specified as “DESede/CBC/ZeroBytePadding.” Take notice that in this case, we specify Triple DES algorithm using Java's official name for the algorithm “DESede.”

NOTE: StrongKey has currently tested only the Electronic Code Book (ECB) and Cipher Block Chain (CBC) modes of encryption and, for the ANSI DUKPT processing module, only ZeroBytePadding and NoPadding mode of padding. Additionally, when using the CBC mode of encryption, the only currently supported Initialization Vector (IV) is an all-zero block. If other encryption modes, padding types, or IVs are desired, please contact support@strongkey.com.

To learn more about Java cryptographic algorithms, modes of encryption and padding, please refer to the Java Cryptography Architecture (JCA) Reference Guide.

Once the plaintext is encrypted, the result is hex-encoded and the following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object.

DID	The unique encryption domain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
BDKToken	The BDKToken used to service this request (or null if the BDK token was not specified as a web service parameter).
MFR	The manufacture ID used to service this request (or null if the manufacturer ID was not specified as a web service parameter).
KSN	The KSN used to service this request.
Plaintext	The plaintext generated from this request, formatted as a hex-encoded string. Be sure to hex decode the value to recover your desired plaintext value.

CCS Module DukptMAC Mechanics

The DukptMac (DMAC) operation generates a message authentication code (MAC) for some hex-encoded plaintext bytes using a key derived from the BDK and KSN following the ANSI-defined MACing scheme. The type of derived key is specified as parameters.

The web service operation requires seven (of a total of eight) parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The credential requires the Encryption privilege at a minimum, but may also require Decryption privileges if the BDK is recovered through a token parameter in the web service.
password	The password of the username to authenticate the credential of the requester.
bdktoken	The token that references the BDK within the SAKA encryption domain. If this parameter is specified, the mfr parameter must be null.
mfr	The numerical identifier of the manufacturer for which this BDK is assigned. If this parameter is specified, the bdktoken parameter must be null.
ksn	The KSN to use to generate the derived key. This must be exactly 10 bytes sent to the web service, and must be formatted as a hex-encoded string.
plaintext	The ciphertext to be decrypted. The ciphertext must be sent to the web service as a hex-encoded string.
requesttype	The type of MAC operation that must be performed by the DUKPT process. Valid choices are: “MAC_REQUEST” “MAC_RESPONSE”

When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the DukptMac service by verifying if they are a member of the EncryptionAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the internal database on SAKA, this group is created automatically.

If the requester is authorized, SAKA proceeds to recover the BDK for this operation. If the manufacturer ID is provided in the web service call, the BDK associated with the manufacturer is recovered. If a BDK token is provided, the BDK is recovered based on that token. In this case, the user must also be a member of the DecryptionAuthorized group.

Using the BDK and portions of the provided KSN, an IPEK is derived. Using the IPEK, the derived MAC key (of the type requested for this transaction) is generated based on other portions of the KSN. The derived MAC key is then used to generate a MAC for the decoded plaintext input using the ANSI-defined algorithm for generating message authentication codes.

This web service operation does two kinds of operations based on the value of the requesttype parameter. When a customer's application sends a DUKPT-encrypted message to SAKA for decryption, the ATM may have included a MAC with the DUKPT message. The customer's application may extract the MAC from the message sent by the ATM, use the DukptMac web service operation to regenerate a MAC for the specified plaintext. The application may then compare the regenerated MAC with the one sent by the ATM to determine if they are identical: if they are, it indicates that the message was decrypted correctly.

In the second operation, the customer's application may need to send a response to the ATM on a business transaction. In this case, the application may want to send a MAC of the plaintext message-response so the ATM may determine if the integrity of the message-response is intact. In such a situation, the application will call the DukptMac operation and specify MAC_RESPONSE in the requesttype parameter. This tells SAKA, how it should cryptographically process the input parameters to generate the right MAC response.

Once the MAC has been generated, the following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object:

DID	The unique encryption domain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
BDKToken	The BDKToken used to service this request (or null if the BDK token was not specified as a web service parameter).
MFR	The manufacture ID used to service this request (or null if the manufacturer ID was not specified as a web service parameter).
KSN	The KSN used to service this request.
MAC	The MAC generated from this request, formatted as a hex-encoded string.

CCS Module ReencryptPINBlock Mechanics

The ReencryptPINBlock (RPB) operation decrypts a hex-encoded PIN block ciphertext string using a PIN encryption key derived from the BDK and KSN. The algorithm to use with the PIN encryption key is specified as a parameter to determine the type of decryption to be performed. The decrypted PIN block is then encrypted again using another derived PIN-encryption key. This second PIN encryption key is derived from the specified Terminal PIN Key (TPK) using the same KSN (as was specified for PIN decryption) and will re-encrypt the PIN Block using the same algorithm as before. Note that the TPK is used in an identical manner as the BDK for the re-encryption process. The RPB web service operation requires eight parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The user requires the Decryption privilege to execute this operation.
password	The password of the username to authenticate the credential of the requester.
bdktoken	The token that references the BDK. The BDK is used to decrypt the supplied ciphertext.
tpktoken	The token that references the TPK. The TPK is used to re-encrypt the decrypted PIN block. Note that the escrow of the TPK is handled as a separate web service operation in the Key Management Service module of the SAKA; the TPK token must exist in SAKA for the RPB web service to be executed successfully.
ksn	The KSN to use to generate a derived key. This must be exactly 10 bytes sent to the web service, and must be formatted as a hex-encoded string.
ciphertext	The PIN Block ciphertext to be decrypted. The ciphertext must be sent to the web service as a hex-encoded string.
algorithm	The algorithm to use for this decryption. Valid choices are “TDES” and “AES” with the default value being “TDES”. Alternatively, a full transform can be specified in the form of “AES/CBC/ZeroBytePadding” if the default mode and padding of each derived key type needs to be overwritten. Continue reading the description of the web service mechanics for more details.

When SAKA receives the request, it verifies the credentials presented against its internal database— or an optional LDAP directory server—and determines their authorization to request the ReencryptPINBlock service by verifying if they are a member of the DecryptionAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the internal database on SAKA, this group is created automatically.

If the requester is authorized, SAKA proceeds to recover the BDK for this operation based on the BDK Token parameter. Using the BDK and portions of the provided KSN, an IPEK is derived. Using the IPEK, the derived key (of the type requested for this transaction) is generated based on other portions of the KSN.

The default cryptographic mode and padding for the RPB web service is the Electronic Code Book (ECB) and NoPadding, respectively with the TDES algorithm. While you can override this by specifying the full cryptographic algorithm, mode and padding in the web service parameter, most banking infrastructure use the “DESede/ECB/NoPadding” cryptographic transform for PIN block transaction processing. In this situation, specifying either “TDES” or not specifying any parameter for the algorithm parameter of the web service operation produces the same result.

DID	The unique encryption doomain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
KSN	The KSN used to service this request.
ENCPIN	The hex-encoded PIN block ciphertext as encrypted by the TPK using this KSN.

KAM Web Service Operations

The KeyAppliance Module (KAM) web service application works by having client applications—whether they are e-commerce, payment processing, business intelligence, healthcare, or other applications that deal with sensitive data—send the sensitive data to SAKA through a standard Simple Object Access Protocol (SOAP)-based web service over Secure Hyper Text Transfer Protocol (HTTPS).

KAM Encryption Mechanics

For encrypting sensitive data, the web service call requires four parameters:

DID	The unique encryption domain identifier. This is a numeric integer that logically represents the context within which the data is encrypted and tokenized.
username	The encryption domain username with the authorization to call this web service.
password	The password of the username to authenticate the credential of the requester.
plaintext	The sensitive data that must be encrypted and tokenized.

When SAKA receives the request, it first verifies the credentials presented against its internal database or an LDAP directory server (depending on which is configured), and then determines their authorization to request the encryption service by determining if they are a member of an EncryptionAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation and configuration process; when using the SAKA internal database, this is performed automatically.

If the requester is authorized, SAKA uses an encryption key to encrypt the plaintext. It also uses a separate HMAC key to generate a unique HMAC of the plaintext. After performing these two cryptographic operations, it stores the ciphertext, the HMAC, the key-identifiers, and metadata about the request in the RDBMS. SAKA never stores the plaintext in the database or anywhere on the system—the plaintext is discarded immediately after the transaction. By default SAKA also generates a numerical token that is characteristically similar to the plaintext (16 digits for a credit-card number, 9 digits for a social security number, etc.) which can be used as a substitute for the plaintext data in applications.

Upon storing the data, SAKA replicates the transaction object to all other SAKA nodes within the same cluster and returns the token to the requester. The requesting application may use this token as a unique identifier for the plaintext and store it within its own database. The token can be configured to be identical in length to the plaintext data (up to a maximum 64 digits).

The replication latency between nodes within a cluster depends on the network capacity between nodes and the saturation of the network at the time of replication. The DEMO appliance provided by StrongKey on the internet has 1GbE ports and the network has light to moderate traffic on it; as a result, we have observed transactions to be replicated from one node to the other in an average of 1–2 seconds.

An illustration of the web service process is shown in the following diagram (to focus on the application's perspective, the replication details are not shown):

KAM Decryption Mechanics

For decrypting ciphertext, the web service call requires four parameters:

DID	The unique encryption domain identifier.
username	The encryption domain username with the authorization to call this web service.
password	The password of the username to authenticate the credential of the requester.
token	The token—by default, a 16-digit number—referencing the object (given to applications during the original encryption call).

When SAKA receives the request, it first verifies the credentials presented against its internal database or an optional LDAP directory server and then determines their authorization to request the decryption service by determining if they are a member of a DecryptionAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation and configuration process; when using the SAKA internal database, this is performed automatically.

If the requester is authorized, SAKA searches its RDBMS for the token, determines the identifier of the key that was used to encrypt it originally and uses that key to decrypt the ciphertext. If the key was rotated at some point due to PCI DSS or other security requirements, SAKA uses the rotated key to decrypt the ciphertext—applications are neither aware nor concerned about cryptographic key management operations when requesting encryption and/or tokenization services from SAKA.

After the decryption process, SAKA retrieves the identifier of the HMAC key originally used by the application and, with the HMAC key, recalculates a new HMAC with the just-decrypted plaintext. It then compares the original HMAC (stored after the successful encryption operation) with the just-calculated HMAC; if the two HMACs are identical, SAKA knows the decryption process was successful.

SAKA logs the decryption request—without storing or logging the sensitive plaintext—replicates the transaction object to all other SAKA nodes within the same cluster and returns the plaintext to the requester.

Notes on the Mechanics

• Two separate keys are used for the encryption and HMAC calculation.

• The default size of the AES encryption key is 256 bits. This can be customized to use either a 128-bit or 192-bit AES key by modifying the SAKA properties file (see 14—KAM Configuration for details).

• The default size of the HMAC key is 256 bits. This can be customized to use either a 224-bit, 384-bit, or 512-bit key by modifying the SAKA properties file (see
  14—KAM Configuration for details).

• The default duration for encryption key usage is one (1) month, while that of the HMAC key is one (1) year. At the start of a new month—starting with the first encryption request past midnight—SAKA starts using a new encryption key that it generates automatically based on configured policies; a new HMAC key is generated on the first day of a new calendar year. However, these durations can be customized to use keys on either a daily, weekly, monthly, or an annual basis in the SAKA properties file (see 14—KAM Configuration for details).

KAM Deletion Mechanics

SAKA can delete encrypted records from its internal database if a site's data retention policy demands it. For deleting ciphertext, the web service call requires four parameters:

DID	The unique encryption domain identifier.
username	The encryption domain username with the authorization to call this web service.
password	The password of the username to authenticate the credential of the requester.
token	The token—by default, a 16-digit number—referencing the object (given to applications during the original encryption call).

When SAKA receives the request, it first verifies the credentials presented against its internal database or an optional LDAP directory server and then determines their authorization to request the deletion service by determining if they are a member of a DeletionAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation and configuration process; when using the SAKA internal database, this is performed automatically.

If the requester is authorized, SAKA searches its RDBMS for the token; if found, the record is deleted and the deletion logged. The deletion is replicated to other nodes of the cluster before a response is returned to the calling application indicating whether or not the deletion was successful.

Once deleted, the original plaintext cannot be returned to any calling application. While the key that encrypted the original plaintext might still be present in SAKA—potentially, to decrypt other records encrypted by the same key—a successful call to the deletion web service permanently removes the record from the database. Note that this does not imply that sites using SAKA may not have other copies of the encrypted record on their backup tapes. It remains the responsibility of the site to ensure compliance to its data retention policy.

KAM Search Mechanics

Certain applications may have a need to search the SAKA internal database to determine if a specific piece of sensitive data exists. SAKA provides a web service method for performing this task. The method requires four parameters:

DID	The unique encryption domain identifier.
username	The encryption domain username with the authorization to call this web service.
password	The password of the username to authenticate the credential of the requester.
plaintext	The sensitive data to for which to search.

When SAKA receives the request, it verifies the credentials presented against its internal database or an optional LDAP directory server and then determines their authorization to request the search service by determining if they are a member of a SearchAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of theSAKA installation process; when using the SAKA internal database, this group is created automatically.

If the requester is authorized, SAKA converts the plaintext to an HMAC and searches its RDBMS for the HMAC; if found, the token is returned to the caller and and the search is logged and replicated to other nodes. A non-null return value to the calling application indicates the search was successful.

KAM Entropy Mechanics

Certain applications may have a need for true random numbers generated from a certified hardware-based random number generator (RNG). Since SAKA includes a hardware RNG, it provides a web service for requesting and receiving true random numbers from its underlying RNG. The method requires four parameters:

DID	The unique encryption domain identifier.
username	The encryption domain username with the authorization to call this web service.
password	The password of the username to authenticate the credential of the requester.
bytes	Number of bytes of entropy requested. The bytes are returned as Base64 encoded text.

When SAKA receives the request, it verifies the credentials presented against its internal database or an optional LDAP directory server and then determines their authorization to request the entropy service by determining if they are a member of an EncryptionAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the SAKA internal database, this group is created automatically.

If the requester is authorized, SAKA gathers the requested number of bytes of entropy from its cryptographic hardware module, Base64-encodes them and returns the encoded bytes to the calling application. While most applications are likely to Base64-decode the encoded bytesperhaps to seed a Pseudo-Random Number Generator (PRNG) in their application/system—some may choose to use the Base64-encoded text as-is—perhaps as truly random passwords or web session identifiers, etc.

KAM General Purpose Key Encryption Mechanics

For encrypting sensitive data using a General Purpose Key (GPK) previously stored on SAKA, the web service call requires the following parameters:

DID	The unique encryption domain identifier. This is a numeric integer that logically represents the context within which the GPK is stored.
username	The encryption domain username with the authorization to call this web service.
password	The password of the username to authenticate the credential of the requester.
gpktoken	The token of the GPK.
plaintext	The sensitive data that must be encrypted.
encoding	The encoding in which to process this transaction. Valid values are Hex and Base64. The iv parameter must be encoded in this format. The ciphertext returned by this web service will be returned in this encoding.
algorithm	The algorithm transform to use for this encryption. The transform must be in the form of “algorithm/mode/padding.”
iv	An Initialization Vector to be used for this encryption. For ECB-mode encryption, the iv should be null.
aad	The Additional Authenticated Data which can be included in GCM-mode encryptions. This value can be null, even in GCM mode (in which case AAD is not required).

When SAKA receives the request, it first verifies the credentials presented against its internal database or an LDAP directory server (depending on which is configured), and then determines their authorization to request the encryption service by determining if they are a member of both the EncryptionAuthorized group and DecryptionAuthorized group (decryption authorization is necessary to access the GPK key). Note that if using LDAP, these groups and their members must be created in the LDAP directory as a distinct task of the SAKA installation and configuration process; when using the SAKA internal database, this is performed automatically.

If the requester is authorized, SAKA locates and decrypt the GPK key. SAKA then initializes the encryption cipher using the algorithm and optionally iv and aad specified in the web service. The web service has been tested with the following algorithms:

• AES/ECB/ZeroBytePadding
• AES/ECB/PKCS7Padding
• AES/ECB/TBCPadding
• AES/ECB/X9.23Padding
• AES/ECB/ISO7816-4Padding
• AES/ECB/ISO10126-2Padding
• AES/CBC/ZeroBytePadding
• AES/CBC/PKCS7Padding
• AES/CBC/TBCPadding
• AES/CBC/X9.23Padding
• AES/CBC/ISO7816-4Padding
• AES/CBC/ISO10126-2Padding
• AES/OFB/NoPadding
• AES/CFB/NoPadding
• AES/GCM/NoPadding

Upon encrypting the data, SAKA encodes the encrypted bytes using the encoding specified in the web service and returns it to the calling application.

KAM General Purpose Key Decryption Mechanics

For decrypting sensitive data using a GPK previously stored on SAKA, the web service call requires the following parameters:

DID	The unique encryption domain identifier. This is a numeric integer that logically represents the context within which the GPK is stored.
username	The encryption domain username with the authorization to call this web service.
password	The password of the username to authenticate the credential of the requester.
gpktoken	The token of the GPK.
ciphertext	The encrypted data that must be decrypted.
encoding	The encoding in which to process this transaction. Valid values are Hex and Base64. The iv and ciphertext parameters must be encoded in this format.
algorithm	The algorithm transform to use for this decryption. The transform must be in the form of “algorithm/mode/padding”.
iv	An Initialization Vector to be used for this decryption. For ECB mode decryption, the iv should be null.
aad	The Additional Authenticated Data which can be included in GCM mode decryptions. This value can be null, even in GCM mode (in which case AAD is not required).

Upon decrypting the data, SAKA returns UTF-8-encoded plaintext to the calling application.

KAM Batch Operations

Some business operations require performing periodic cryptographic operations on millions of records. While the standard web services are capable of receiving such large requests individually, the operations can be made significantly more efficient by submitting the input data in an eXtensible Markup Language (XML) file and performing the operation on the appliance without authenticating and authorizing each request (except for the first), and by eliminating the network round-trips for each web service call.

SAKA provides four (4) web service methods for encrypting, decrypting, deleting, and searching for sensitive data using XML-based files in batch mode.

The XML input file conforms to the SKLESBatchInput element, defined in the SAKA XML Schema Definition (XSD) file supplied with the appliance. Any number of records may be processed through batch files more efficiently; the only limitation to the number of records in such a batch file would be the appliance's operating system limit on the file size.

NOTE: An XML input file with one million 16-digit credit card numbers, and conforming to the SAKA XSD, uses a little less than 40 megabytes of space, or approximately 25,000 records per megabyte of space. Based on this, a one-Gigabyte file can store 25 million input records. An input file with the maximum file size limitation of Linux (8 Terabytes) can accommodate 200 billion credit card numbers.

The appliance processes the input file in batch mode: it performs just a single authentication and authorization check, a single verification of the encryption domain's status and proceeds to execute the requested cryptographic operation for each record in the input file. It writes the result to a different XML file corresponding the SKLESBatchOutput element in the SAKA XSD. The input and output files may be transferred to and from the appliance using the Secure File Transfer Protocol (SFTP), secure NFS, or SAMBA over TLS.

KAM Relay Mechanics

To minimize the decryption of sensitive PAN data within the application network, SAKA supports a “relay” web service method permitting applications to relay a transaction to a payment gateway (PG). This is accomplished through a Hypertext Transfer Protocol Secure (HTTPS) POST method, or a Simple Object Access Protocol (SOAP) action within an HTTPS POST method.

The business benefit of using the relay web service is that the application dealing with the PG does not need to decrypt credit card numbers (CCN) before sending transaction to the gateway—SAKA performs this service (functioning like a proxy) on behalf of the application and, thus, reduces or eliminates the need for decrypting CCN. However, to relay transactions, SAKA must have direct network connectivity to the PG's web server, either over the internet or through a virtual private network.

Here is a sample representation of how an infrastructure might look when configured to use the relay web service to multiple payment gateways:

In this configuration, the site has the following:

• A web tier in the demilitarized zone (DMZ) receiving customer transactions from the internet

• An application tier with servers and databases representing business logic and data

• A PCI zone containing SAKA

• Three payment gateways: PG1, which offers both an HTTPS and SOAP interface to the transaction gateway; PG2, which only offers an HTTPS interface; and PG3, which only offers a SOAP interface

One may connect any number of payment gateways to SAKA as long as the gateways offer standard HTTPS or SOAP interfaces to their services.

When SAKA receives the request it verifies the credentials presented against its internal database or an optional LDAP directory server and determines their authorization to request the relay service by determining if they are a member of two groups—the RelayAuthorized group and the DecryptionAuthorized group. This is the only service that requires authorized requesters to be part of two groups. This is because the security of the appliance requires that tokens be decrypted and substituted for actual sensitive information and relayed to the payment gateway.

To use the relay web service, applications that normally communicate with the PG must be modified to communicate with SAKA—which requires seven (7) parameters to perform its task:

DID	The unique encryption domain identifier. This is a numeric integer that logically represents the context in which data is encrypted and tokenized. Specify the DID to ensure the relay service can not only authenticate the request correctly, but also decrypt any tokens before relaying the transaction.
username	The username within the encryption domain that has authorization to call the web service. At most sites, this is a service credential used by the application communicating with SAKA.
password	The password of the username within the encryption domain to authenticate the credential of the requester.
relayurl	The URL of the payment gateway that receives transactions. The appliance checks to see if the supplied URL matches—completely or partially—URLs configured and authorized for use by the appliance for relaying transactions. For example, if https://test.authorize.net is configured as an authorized URL for this appliance, supplying the URL https://test.authorize.net/gateway/transact.dll in this parameter will allow the transaction to be relayed to the gateway (assuming all other checks pass). However, https://test.authorize.com/gateway/transact.dll will not.
relayprotocol	The web service only accepts HTTP- or SOAP-based relay requests; as such, this parameter must specify either HTTP or SOAP (uppercase) depending on the interface the PG offers.
relayencoding	While future versions of the web service will support additional encoding schemes, the appliance currently accepts only UTF-8 in this parameter.
relaycontent	Carries XML content conforming to the schema defined in SKLESRelaySchema.xsd. This schema definition—supplied with the software that implements this service—defines the syntax of the transaction that is translated by SAKA and relayed to the payment gateway.

Depending on the type of protocol specified in the relayprotocol parameter, the appliance builds a standard HTTPS POST message, or one encapsulating a SOAP request, and posts it to the specified URL. As part of relaying the transaction, the appliance can decrypt tokens specified in the relaycontent parameter and substitute decrypted content for them before posting it to the payment gateway's website.

The appliance waits for a response from the gateway and transmits the response back to the calling application without interpreting the response. All relay transactions are logged in the application server's logs (however, sensitive data is never logged).

Since the relay web service works on standard SOAP over HTTPS, any programming environment that supports these two protocols can consume the service. StrongKey supplies two sample Java clients that show how to consume the service using the HTTPS and the SOAP protocols.

HTTPS Interface

A few notes about the HTTPS interface for the relay web service:

1. The relay service only performs HTTP POSTs; GETs are not supported at this time.

2. The service allows for specifying any number of HTTP headers, HTTP parameters, and SAKA tokens that need decrypting and substituting in the relay request to the gateway.

3. All headers, parameters and tokens are specified in XML elements that must conform to the supplied SKLESRelaySchema.xsd. If in doubt about the XML, test your sample XML with xmllint (on the Linux platform) against the XSD file. Fix any errors before sending the XML to the appliance.

4. The appliance will not print any sensitive decrypted/detokenized information in the server log.

SOAP Interface

A few notes about the SOAP interface for the relay web service:

1. The SOAP message sent to SAKA for the relay request embeds another SOAP Envelope containing the message to be relayed to the payment gateway. This might be confusing initially, but is acceptable to the appliance. Just make sure that samples of XML created for testing pass validation tests using xmllint against the XSD defined in SKLESRelaySchema.xsd.

2. The relay service only performs HTTP POSTs; GETs are not supported at this time.

3. The service allows for specifying any number of HTTP headers. HTTP parameters are not supported in this interface.

4. The appliance will not print any sensitive decrypted/detokenized information in the server log.

KMS Web Service Operations

The Key Management Service (KMS) web service application supports an array of web services for managing ANSI X9.24-1:2009 DUKPT keys. It works by having client applications send requests to the KMS through a standard SOAP- or REST-based web services over HTTPS.

SOAP-based web service calls can be expected to return a CCReturnObject (see definition below). In the case of some errors, anticipate the return of either StrongKeyLiteExceptions or CCExceptions.

REST-based web service calls return HTTP Status Codes corresponding with the success or type of failure encountered. Successful operations will always return a 200 OK alongside either a JSON or XML response. A JSON will be returned unless the strongkeylite.cfg.property.ccsresponseformat property is overwritten on SAKA to specify that XML responses should be returned. Other valid Response Statuses specific to failure conditions include:

• 400 Bad Request

• 401 Unauthorized

• 404 Not Found

• 500 Internal Server Error

CCReturnObject

The following example defines the CCReturnObject type:

#	CCReturnObject XML Content
1	<xs:complexType name="CCReturnObject">
2	<xs:sequence>
3	<xs:element name="did" type="xs:long" minOccurs="0"/>
4	<xs:element name="messagekey" type="xs:string" minOccurs="0"/>
5	<xs:element name="message" type="xs:string" minOccurs="0"/>
6	<xs:element name="objectContent" type="xs:anyType" minOccurs="0"/>
7	<xs:element name="objectType" type="xs:int" minOccurs="0"/>
8	<xs:element name="srid" type="xs:long" minOccurs="0"/>
9	</xs:sequence>
10	</xs:complexType>

The following table explains each line of the above XML file:

#	CCReturnObject XML Content Explanation
1	The start of the CCReturnObject element.
2	The start of a sequence.
3	The DID element—the identifier of the encryption domain that serviced this request.
4	The messagekey element—a message code used by the appliance as a reference. Messages of the format 'SKL-MSG-NNNN' indication a success and message of the format 'SKL-ERR-NNNN' indication failure (where NNNN are numerals).
5	The message element—a message which describes a success or failure condition.
6	The objectContent element—a JSON or XML that contains the result of a successful web service operation. A JSON will be returned by default unless the encryption domain or the SAKA strongkeylite.cfg.property.ccsresponseformat property is overwritten on the server.
7	The objectType element—an int value that identifies the kind of object being returned. 1 = CC_DATA 2 = CC_DIGEST 3 = CC_ENCRYPTED_OBJECT 4 = CC_ENCRYPTED_SYMMETRIC_KEY 5 = CC_ENCRYPTED_SYMMETRIC_KEYS 6 = TOKEN 7 = DECRYPTED_XML 8 = REENCRYPTED_PIN 9 = KEY_CHECK_VALUE 10 = MAC_REQUEST 11 = MAC_RESPONSE
8	The srid element—a unique request identifier for this transaction.
9	The end of the sequence.
10	The end of the CCReturnObject.

CCKeyComponentType

The CCKeyComponentType element is used by the loadKeyComponent web service to transport a Key Component and all its metadata as a single object. The SOAP interface will pass this parameter to the web service as a structured object, whereas the REST interface will pass a JSON representation of that structured object.

The following example defines the CCKeyComponentType element using the SOAP interface.

#	CCKeyComponentTypeXML Content
1	<xs:complexType name="CCKeyComponentType">
2	<xs:sequence>
3	<xs:element name="KeyName" type="xs:string" minOccurs="0"/>
4	<xs:element name="KeyComponent" type="xs:string" minOccurs="0"/>
5	<xs:element name="KeyCheckValue" type="xs:string" minOccurs="0"/>
6	<xs:element name="KeyAlgorithm" type="xs:string" minOccurs="0"/>
7	<xs:element name="KeySize" type="xs:string" minOccurs="0"/>
8	<xs:element name="KValue" type="xs:int" minOccurs="0"/>
9	<xs:element name="NValue" type="xs:int" minOccurs="0"/>
10	</xs:sequence>
11	</xs:complexType>

The following table explains each line of the above XML file:

#	CCKeyComponentTypeXML Content Explanation
1	The start of the CCKeyComponentType element.
2	The start of a sequence.
3	The KeyName element—the identifier for the key that this Key Component belongs to. All Key Components in a set must have the same KeyName.
4	The KeyComponent element—a hex-encoded string representation of this Key Component.
5	The KeyCheckValue element—a hex-encoded string representation of the Key Check Value (KCV) for this Key Component. The KCV will be checked against the Key Component to verify the integrity of this Key Component.
6	The KeyAlgorithm element—the algorithm of the key to which this Key Component belongs. Valid values are AES and TDES.
7	The KeySize element—the size of the key to which this Key Component belongs. Only keys of length 128 are currently supported.
8	The KValue element—a numerical identifier for this Key Component in the set of Key Components. Must be one of the int values 1, 2, or 3.
9	The NValue element—a numerical representation of the total amount of Key Components in this set. Must be one of the int values 2 or 3.
10	The end of the sequence.
11	The end of the CCKeyComponentType element.

The following shows an example CCKeyComponentType in JSON format (REST interface):

{
  "KeyName": "myBDK",
  "KeyComponent": "4010E7B1F6A91C40217A253E3D3131CA",
  "KeyAlgorithm": "AES",
  "KeyCheckValue": "A60EA8",
  "KeySize": "128",
  "KValue": 1,
  "NValue": 3
}

CCCryptographicMaterialType

The CCCryptographicMaterialType is used as a sub-element of CCEncryptedAnsiX9241KeyType. It is used to store different types of encoded cryptographic material (i.e., binary data).

The following example defines the CCCryptographicMaterialType type:

#	CCCryptographicMaterialType XML Content
1	<xsd:complexType name="CCCryptographicMaterialType">
2	<xsd:choice>
3	<xs:element name="Base64Data" type="xs:string"/>
4	<xs:element name="HexData" type="xs:string"/>
5	</xsd:choice>
6	</xsd:complexType>

The following table explains each line of the above XML file:

#	CCCryptographicMaterialTypeXML Content Explanation
1	The start of the CCCryptographicMaterialType element.
2	The start of a choice.
3	The Base64Data element—cryptographic material encoded using Base64.
4	The HexData element—cryptographic material encoded using hex.
5	The end of the choice.
6	The end of CCCryptographicMaterialType.

CCEncryptedAnsiX9241KeyType

The CCEncryptedAnsiX9241KeyType is used by the storeAnsiX9241Key and replaceAnsiX9241Key web services to transport a key's metadata (and optionally an encrypted key) as a single object. The SOAP interface will pass this parameter to the web service as a structured object, whereas the REST interface will pass a JSON representation of that structured object.

When using the SOAP interface, the following example defines the CCEncryptedAnsiX9241KeyType type:

#	CCEncryptedAnsiX9241KeyType XML Content
1	<xs:complexType name="CCEncryptedAnsiX9241KeyType">
2	<xs:sequence>
3	<xs:element name="SID" type="xs:int"/>
4	<xs:element name="DID" type="xs:int"/>
5	<xs:element name="AKID" type="xs:int"/>
6	<xs:element name="SRID" type="xs:int"/>
7	<xs:element name="BankID" type="xs:int"/>
8	<xs:element name="TerminalID" type="xs:int"/>
9	<xs:element name="TerminalType" type="xs:string"/>
10	<xs:element name="KeyName" type="xs:string"/>
11	<xs:element name="ParentToken" type="xs:string"/>
12	<xs:element name="Token" type="xs:string"/>
13	<xs:element name="EncryptedKey" type="xs:CCCryptographicMaterialType"/>
14	<xs:element name="KeyType" type="xs:string"/>
15	<xs:element name="KeyAlgorithm" type="xs:string"/>
16	<xs:element name="KeyEncoding" type="xs:string"/>
17	<xs:element name="KeySize" type="xs:string"/>
18	<xs:element name="KCV" type="xs:string"/>
19	<xs:element name="Notes" type="xs:string"/>
20	</xs:sequence>
21	</xs:complexType>

The following table explains each line of the above XML file:

#	CCEncryptedAnsiX9241KeyType XML Content Explanation
1	The start of the CCEncryptedAnsiX9241KeyType element.
2	The start of a sequence.
3	The SID element—the server ID of the server that processed this request. This element is only used in the event the server returns this object to the calling application. When using this object in a web service call, this element should be NULL.
4	The DID element—the domain ID of the server that processed this request. This element is only used in the event the server returns this object to the calling application. When using this object in a web service call, this element should be NULL.
5	The AKID element—the ANSI Key ID assigned to the stored key. This element is only used in the event the server returns this object to the calling application. When using this object in a web service call, this element should be NULL.
6	The SRID element—a unique request ID for this transaction. This element is only used in the event the server returns this object to the calling application. When using this object in a web service call, this element should be NULL.
7	The BankID element—a numeric identifier for the bank with which this key is associated.
8	The TerminalID element—an optional numerical identifier for the terminal with which this key is associated.
9	The TerminalType element—an optional string identifier for the type of terminal to which this key belongs.
10	The KeyName element—the name associated with this key. If ParentToken is null, this value will be used to recover the pre-load key components of this key. Otherwise, this value is primarily used for logging.
11	The ParentToken element—the token identifier of the wrapping key used to encrypt this ANSI key. If this ANSI key is being assembled from pre-loaded key components, this element must be NULL.
12	The Token element—the token identifier created for this stored key. This element is only used in the event the server returns this object to the calling application. When using this object in a web service call, this element should be NULL.
13	The EncryptedKey element—a CCCryptographicMaterialType object that stores the encoded encrypted key bytes. If this ANSI key is being assembled from pre-loaded key components, this element must be NULL.
14	The KeyType element—the type of key that is being stored. Valid values are BDK, MAC, LTMK, TMK, and TPK.
15	The KeyAlgorithm element—the algorithm associated with this key. When this stored key is referenced by other web service calls, this algorithm will be used exclusively with this key. Valid values are AES and TDES.
16	The KeyEncoding element—the type of encoding used in the EncryptedKey element. Valid values include Hex and Base64. If this ANSI key is being assembled from pre-loaded key components, this element must be NULL.
17	The KeySize element—the size of the key being stored. Currently the only supported Keysize is 128.
18	The KCV element—a hex-encoded string representation of the KCV for this Key Component. The KCV will be checked against the assembled/decrypted key to verify the integrity of this key.
19	The Notes element—any notes to store alongside the key.
20	The end of the sequence.
21	The end of CCEncryptedAnsiX9241KeyType.

The following shows an example CCEncryptedAnsiX9241KeyType in JSON format (REST interface):

{
  "BankID": 1,
  "TerminalID": 123,
  "TerminalType": "DEFAULT",
  "KeyName": "myTPK",
  "ParentToken": "1000000000000001",
  "EncryptedKey": "982D868704702DF9070922F1DFB260A8",
  "KeyType": "TPK",
  "KeyAlgorithm": "TDES",
  "KeyEncoding": "Hex",
  "KeySize": "128",
  "KCV": "6776FF",
  "Notes": "myNotes"
}

This is an example of storing a key wrapped by a previously stored key. If this request were storing a key from key components, the ParentToken, EncryptedKey, and KeyEncoding elements would be omitted. In that case, the KeyName element would be crucial to identify the stored Key Components used to assemble the key.

KMS Module loadKeyComponent Mechanics

The loadKeyComponent (LKC) operation receives a CCKeyComponentType object (along with other parameters to authenticate and authorize the transaction) to store a key component for use with calls to the loadBaseDerivationKey or storeAnsiX9241Key web services. This operation requires four parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The credential requires the Key Component Operator (KMO) privilege.
password	The password of the username to authenticate the credential of the requester.
keycomp	The CCKeyComponentType object that contains the key component and metadata.

When SAKA receives the request, it verifies the credentials presented in the web service operation against its internal database, or an optional LDAP directory server, and then determines their authorization to request the loadKeyComponent service by determining if they are a member of the KMOAuthorized group. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the SAKA internal database, this group is created automatically.

If the requester is authorized, SAKA parses out the contents of the CCKeyComponentType object. The KCV is used in conjunction with the Key Component to verify the integrity of the Key Component.

On success, the following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object.

DID	The unique encryption domain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
KeyName	The KeyName of this loaded component.
K	The K value of this loaded component.
N	The N value of this loaded component.
KCV	The KCV of this loaded component.

KMS Module loadBaseDerivationKey Mechanics

The loadBaseDerivationKey (LBK) operation takes a set of previously stored Key Components and assembles them into a BDK. This BDK is not persisted to the appliance and is used to process transactions in the CardCryptoService (CCS) Servlet. The loadBaseDerivationKey web service requires six parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The credential requires the Key Component Custodian (KMO) privilege.
password	The password of the username to authenticate the credential of the requester.
keyname	Identifier for the assembled key. This must match the keyname provided for each of this key's Key Components submitted to the loadKeyComponent web service.
kcv	Hex-encoded string representing the KCV for the assembled key.
mfr	The numerical identifier of the manufacturer for which this BDK is assigned. Please see Chapter 5 for a detailed explanation of Manufacturer IDs.

When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the loadBaseDerivationKey service by verifying if they are a member of the KMCAuthorized group. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the SAKA internal database, this group is created automatically.

If the requester is authorized, SAKA proceeds to check for the key components of this key. If all the necessary key components are found, the BDK is assembled from these key components. The KCV provided in the web service call is compared to the KCV of this generated key. If they do not match, the integrity of the key cannot be confirmed and the request will fail. If the integrity of the key is confirmed, the key is ready for use with CCS web services.

NOTE: If the application server or the appliance is rebooted, the assembled key will be erased and must be reloaded into the appliance. If permanent storage is desired, refer to the storeAnsiX9241Key web service.

Once the BDK is successfully loaded, the following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object:

DID	The unique encryption domain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
KCV	The KCV of this loaded component.

KMS Module generateBaseDerivationKey Mechanics

The generateBaseDerivationKey (GBK) operation uses the cryptographic hardware module of the appliance to generate a new 128-bit key that can be used for a Base Derivation Key as defined by the ANSI X9.24-1 DUKPT standard. The web service operation requires four parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The user requires the Key Management Custodian privilege to execute this operation.
password	The password of the username to authenticate the credential of the requester.
mfr	The numerical identifier of the manufacturer for which this BDK is assigned. In this web service, this value is used primarily for logging purposes.

When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the GBK service by verifying if they are a member of the KMCAuthorized group. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the internal database on SAKA, this group is created automatically.

If the requester is authorized, SAKA utilizes the True Random Number Generator (TRNG) from the appliance's cryptographic hardware module to generate a new 128-bit key. This key is divided into three key components. The key components are packaged in CCKeyComponentType objects along with their corresponding KCV and other metadata. Additionally, a fourth CCKeyComponentType object is created that does not store a key component, but contains the KCV of the assembled BDK.

Once the CCKeyComponentType objects are created, in the case of SOAP, an array of these objects will be returned. In the case of REST, a JSON representation of the array is returned:

CCKeyComponentTypeArray[0]	Contains the first key component with KCV and metadata.
CCKeyComponentTypeArray[1]	Contains the second key component with KCV and metadata.
CCKeyComponentTypeArray[2]	Contains the third key component with KCV and metadata.
CCKeyComponentTypeArray[3]	Contains only the KCV of the assembled BDK (does not include the assembled BDK itself).

An example JSON array response for KMS Module's GBK service:

[{
 "KeyName": "0",
 "KeyComponent": "F540DF52C1E3957D0B69BE23E443C003",
 "KeyCheckValue": "D35DF4",
 "KeyAlgorithm": "AES",
 "KeySize": "128",
 "K": 1,
 "N": 3
}, {
 "KeyName": "0",
 "KeyComponent": "EA60664815BF97F1692315842D331437",
 "KeyCheckValue": "6A3D7F",
 "KeyAlgorithm": "AES",
 "KeySize": "128",
 "K": 2,
 "N": 3
}, {
 "KeyName": "0",
 "KeyComponent": "554548549AFB786036FFF422D9DEBC54",
 "KeyCheckValue": "FB1843",
 "KeyAlgorithm": "AES",
 "KeySize": "128",
 "K": 3,
 "N": 3
}, {
 "KeyCheckValue": "4B0333"
}]

KMS Module generateInitialKey Mechanics

The generateInitialKey (GIK) operation uses a previously loaded BDK and the supplied device serial number (DSN) to generate and return an Initial Key (sometimes called the Initial PIN Encryption Key or IPEK). The manner in which the Initial Key is returned to the calling application is determined by the returntype option.

The GIK web service operation requires seven parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The user requires the Key Management Custodian privilege to execute this operation.
password	The password of the username to authenticate the credential of the requester.
mfr	The numerical identifier of the manufacturer for which BDK will be used to derive the Initial Key. The BDK must have already been loaded by the loadBDK web service.
DSN	The DSN to use to generate a derived key. This must be either an 11-byte hex-encode string (43 bits of data) or 15-byte hex-encoded string (59 bits). Using the former, the server will automatically pad the DSN with the hex value “FFFF.”
PublicKeyToken	The token which identifies the public key that will be encrypting the Initial Key. Can be null when returntype equals KeyComponents.
ReturnType	The method in which to return the Initial Key. Currently the only accepted value is KeyComponents.

When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the generateInitialKey service by verifying if they are a member of the KMCAuthorized group. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the internal database on the SAKA, this group is created automatically.

If the requester is authorized, SAKA proceeds to recover the BDK for this operation based on the Manufacturer ID. Using the BDK and portions of the provided DSN, an initial key is derived. This key is broken up into three key components. These key components are packaged in CCKeyComponentType objects along with their KCV and other metadata. A fourth CCKeyComponentType object is created that does not contain a key component but contains the KCV of the Initial Key.

Once the CCKeyComponentType objects are created—using SOAP—an array of these objects will be returned. Using REST, a JSON representation of the array is returned:

CCKeyComponentTypeArray[0]	Contains the first key component with KCV and metadata.
CCKeyComponentTypeArray[1]	Contains the second key component with KCV and metadata.
CCKeyComponentTypeArray[2]	Contains the third key component with KCV and metadata.
CCKeyComponentTypeArray[3]	Contains only the KCV of the assembled BDK (does not include the assembled BDK itself).

An example JSON array response for KMS Module's generateInitialKey service:

[{
 "KeyName": "0",
 "KeyComponent": "F540DF52C1E3957D0B69BE23E443C003",
 "KeyCheckValue": "D35DF4",
 "KeyAlgorithm": "AES",
 "KeySize": "128",
 "K": 1,
 "N": 3
}, {
 "KeyName": "0",
 "KeyComponent": "EA60664815BF97F1692315842D331437",
 "KeyCheckValue": "6A3D7F",
 "KeyAlgorithm": "AES",
 "KeySize": "128",
 "K": 2,
 "N": 3
}, {
 "KeyName": "0",
 "KeyComponent": "554548549AFB786036FFF422D9DEBC54",
 "KeyCheckValue": "FB1843",
 "KeyAlgorithm": "AES",
 "KeySize": "128",
 "K": 3,
 "N": 3
}, {
	"KeyCheckValue": "4B0333"
}]

KMS Module storeAnsiX9241Key Mechanics

The storeAnsiX9241Key (SDK) operation is used for persistent, secure storage of ANSI X-924.1 keys in SAKA. The web service receives a CCEncryptedAnsiX9241KeyType object (along with other parameters to authenticate and authorize the transaction) containing all the metadata necessary to store the key.

There are two methods for storing a key on the appliance using the values from the CCEncryptedAnsiX9241KeyType. The first involves assembling the key from a set of key components that were previously loaded through the loadKeyComponent web service. The second method is to decrypt an encrypted key using a previously stored key as the wrapping key.

The web service automatically determines the attempted method of key storage, depending on whether the ParentToken value of the CCEncryptedAnsiX9241KeyType object is null or not. The SDK web service operation requires four parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The user requires at minimum the Key Management Administrator and encryption privileges to execute this operation. If the ANSI key is a wrapped key, then the decryption privilege is also required to recover the wrapping key.
password	The password of the username to authenticate the credential of the requester.
encansikey	The CCEncryptedAnsiX9241KeyType object that contains the key component and metadata.

When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the storeAnsiX9241Key service by verifying if they are a member of the KMAAuthorized and EncryptionAuthorized groups. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the internal database on the SAKA, this group is created automatically.

If the requester is authorized, the SAKA proceeds to parse the CCEncryptedAnsiX9241KeyType object. Depending on what parameters are available, the code will branch into one of two paths:

1. If a ParentToken parameter is specified, the appliance will make an additional check to verify if the user is a member of the DecryptionAuthorized group. If authorized, the wrapping key will be recovered from secure storage for use in this transaction. The wrapping key is used to decrypt the provided EncryptedKey data.

2. If a ParentToken parameter is not specified, the appliance will search it's internal maps for Key Components associated with the key specified by the KeyName. If the necessary key components are found, the key is assembled from these components (and the components subsequently erased).

Once the appliance has assembled/decrypted the ANSI key, a KCV is calculated and compared with the provided KCV. If they do not match, the integrity of the key cannot be confirmed and the request will fail. If the integrity of the key is confirmed, the key is securely stored in the appliance.

Once the ANSI key is successfully stored, the following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object:

DID	The unique encryption domain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
Token	The token reference to this encrypted ANSI key.
KeyName	The identifier used to reference this key in the request.

KMS Module replaceAnsiX9241Key Mechanics

The replaceAnsiX9241Key (RDK) operation is used for persistent, secure storage of ANSI X-924.1 keys in SAKA. The web service receives a CCEncryptedAnsiX9241KeyType object (along with other parameters to authenticate and authorize the transaction) that contains all the metadata necessary to store the key. While behaving similarly to the storeAnsiX9241Key web service, this web service additionally marks another—previously stored—ANSI key as “retired,” so the newly stored ANSI key can replace it.

There are two methods for replacing a key on the appliance using the values from the CCEncryptedAnsiX9241KeyType element. The first involves assembling the key from a set of key components that were previously loaded through the loadKeyComponent web service. The second method is to decrypt an encrypted key using a previously stored key as the wrapping key.

The web service will automatically know which method of key replacement you are attempting based on whether the ParentToken value of the CCEncryptedAnsiX9241KeyType object is NULL or not.

The RDK web service operation requires four parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The user requires the Key Management Administrator privilege and the encryption privilege at minimum to execute this operation. If the ANSI key is a wrapped key, then the decryption privilege is also required to recover the wrapping key.
password	The password of the username to authenticate the credential of the requester.
encansikey	The CCEncryptedAnsiX9241KeyType object that contains the key component and metadata.

When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the replaceAnsiX9241Key service by verifying if they are a member of the KMAAuthorized and EncryptionAuthorized groups. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the internal database on the SAKA, this group is created automatically.

If the requester is authorized, SAKA parses the CCEncryptedAnsiX9241KeyType object. Depending on what parameters are specified, the code will branch into one of two paths:

1. If a ParentToken is specified, the appliance will make an additional check to verify if the user is a member of the DecryptionAuthorized group. If authorized, the wrapping key will be recovered from secure storage for use in this transaction. The wrapping key is used to decrypt the provided EncryptedKey data.

2. If a ParentToken is not specified, the appliance will search it's internal maps for Key Components associated with the key specified by the KeyName. If the necessary key components are found, the key is assembled from these components (and the components are subsequently erased).

Once the appliance has assembled/decrypted the ANSI key, a KCV is calculated and compared with the provided KCV. If they do not match, the integrity of the key cannot be confirmed and the request will fail. If the integrity of the key is confirmed, the key is ready to be securely stored. Within a single transaction, the to-be-replaced token is marked as “retired.” The replacement key is then encrypted and stored by the appliance. If either action in this two-phase transaction fails, the entire transaction is rolled back.

Once the ANSI key is successfully stored, the following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object:

DID	The unique encryption domain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
Token	The token reference to this encrypted ANSI key.
KeyName	The identifier used to reference this key in the request.

KMS Module deleteAnsiX9241Key Mechanics

The deleteAnsiX9241Key (DLK) operation is used to delete an ANSI key previously stored on the appliance. The DLK web service operation requires five parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The user requires the Key Management Administrator privilege and Deletion privilege to execute this operation.
password	The password of the username to authenticate the credential of the requester.
bankid	An optional bank identifier used to identify this ANSI key. Currently only used for logging purposes.
KeyToken	The token that references the ANSI key to be deleted.

When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the DLK service by verifying if they are a member of the KMCAuthorized and DeletionAuthorized groups. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the internal database on the SAKA, this group is created automatically.

If the requester is authorized, SAKA locates the key identified by the KeyToken parameter. Once identified, the record is deleted from the appliance's database. The following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object:

DID	The unique encryption domain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
BankID	The bank ID used in this request.
KeyToken	The token reference deleted by this request.

KMS Module updateAnsiX9241Key Mechanics

The updateAnsiX9241Key (UPK) operation is used to update the status and/or the notes associate with an ANSI key previously stored on the appliance. The UPK web service operation requires seven parameters:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The user requires the Key Management Administrator privilege to execute this operation.
password	The password of the username to authenticate the credential of the requester.
bankid	An optional bank identifier used to identify this ANSI key. Currently only used for logging purposes.
KeyToken	The token that references the ANSI key to be deleted.
NewStatus	The optional updated status for this ANSI key. Valid values for NewStatus are Active, Inactive, Suspended, and Retired.
NewNotes	The optional updated notes for this ANSI key.

When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the UPK service by verifying if they are a member of the KMCAuthorized group. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the SAKA installation process; when using the internal database on the SAKA, this group is created automatically.

If the requester is authorized, SAKA locates the key identified by the KeyToken parameter. Once identified, the record for this key is updated in the appliance's database with the non-null values from the NewStatus and NewNotes parameters. The following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object:

DID	The unique encryption domain identifier for the domain that serviced this request.
SRID	A unique request identifier for this transaction.
BankID	The BankID used in this request.
KeyToken	The token reference deleted by this request.
NewStatus	The new status for this key.
NewNotes	The new notes for this key.

KAM Batch Operations

The KAM supports the ability to perform cryptographic operations on large sets of plaintext data in batch mode, as opposed to sending each request in a unique web service call. As fast as SAKA is, batch mode operations—especially for decryption—are sped up significantly through the avoidance of many functions that are repeated for each web service call.

SAKA supports all four (4) types of cryptographic operations: encryption, decryption, deletion, and searching. There are no limits to the number of records that may be processed within each batch operation. However, each of the operations must meet the following prerequisites:

• The input file for the batch operation must conform to the SKLESBatchInput (SBI) element of the SAKA XML Schema Definition (XSD), which is included on every appliance, and is shown later in this chapter.

• The XML input file must be transferred to SAKA separately; StrongKey recommends the use of the Secure File Transfer Protocol (SFTP), but Network File System (NFS) and/or Server Message Block (SMB) protocols may also be used to transfer files to the appliance. Each encryption domain must have an operating system user defined with a home directory writable by the strongauth user to enable the batch operations. Note that the installation of a new appliance automatically creates the first encryption domain and a batch operation user called domain1 at the Linux operating system layer to enable the file transfers through SFTP. When additional encryption domains are made, batch operation users must be added manually to enable the file transfer capability.

• The batch operation must be requested through a web service—the same web service that supports all other cryptographic operations. The Demo Client application described in the previous chapter—sakaclient.jar—has sample code to show how the web services may be requested; this chapter uses the demo application in its examples below.

• The user requesting the batch operation must be authorized for the cryptographic operation.

After the batch operation is completed, SAKA creates the output as an XML file, conforming to the SKLESBatchOutput (SBO) element from the SAKA XML Schema Definition (XSD). The output must be transferred from the appliance similarly to how the input file was transferred. After the file is transferred by the batch operation user, it must be deleted explicitly, as some of the operations (encrypt, decrypt, and search) result in creating output files that contain sensitive data in an unencrypted form.

NOTE: SAKA deletes input files for the encryption and search operations immediately after completing the batch job; however, it does not delete the input files for the decryption and deletion operations since they only contain tokens.

SKLESBatchInput Element

Among the many elements used by the appliance, and which are defined in the SAKA XSD file (SAKA.xsd), is the SBI element; it defines the structure of the XML input file for batch operations. This element is used for all four (4) types of cryptographic operations—encryption, decryption, deletion, and search.

All sub-elements of the SBI element are mandatory. Failure to include values for all SBI sub-elements will prevent the batch job from executing. A sample of the input file for different transactions is shown below, followed by an explanation:

#	SBI XML Content
1	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2	<skles:SKLESBatchInput
3	xmlns:skles='http://strongkeylite.strongauth.com/SKLES201009'>
4	<skles:DomainId>1</skles:DomainId>
5	<skles:JobId>X1234-20100920T211723</skles:JobId>
6	<skles:Transaction>Encrypt</skles:Transaction>
7	<skles:InputNumber>5</skles:InputNumber>
8	<skles:InputValues>
9	<skles:Input>1111222233330001</skles:Input>
10	<skles:Input>1111222233330002</skles:Input>
11	<skles:Input>1111222233330003</skles:Input>
12	<skles:Input>1111222233330004</skles:Input>
13	<skles:Input>1111222233330005</skles:Input>
14	</skles:InputValues>
15	</skles:SKLESBatchInput>

The following table explains each line of the above XML file:

#	SBI XML Content Explanation
1	The start of the XML file.
2	The start of the SBI element. Note that all elements in this example are qualified with the skles prefix.
3	The namespace definition to which this schema instance conforms; in this case, http://strongkeylite.strongauth.com/SKLES201009.
4	The DomainID element—the value for this element is 1. This value is mandatory—all cryptographic operations in SAKA operate within encryption domains, and without a domain ID, the appliance would not know which domain to use for processing the batch file. A valid numerical domain identifier is necessary.
5	The JobID element identifies a unique job name that the client application can use to identify its input/output XML files. The same JobID is written out in the output XML file by the appliance. In this example, the JobID is X1234-20100920T211723. There are no rules about what to use for a JobID, but it is helpful to have the source application name and the date-timestamp of the creation of the input file.
6	The Transaction element identifies the type of cryptographic operation to perform on each input element in the file. In this example, the batch file is requesting the Encrypt transaction. Each input file may specify only a single operation; this operation will be performed on all input records that follow. The four valid values for this element are: Encrypt, Decrypt, Delete, and Search.
7	The InputNumber element identifies the number of input records in this file. While this is helpful to human readers, the appliance processes exactly as many input records exist in the file regardless of what the InputNumber element states.
8	The InputValues element signals the start of all input records.
9–13	Each Input element has precisely one sensitive data value. This can be anything—up to a maximum of 1024 characters long. The appliance processes every single record as it reads them from the file. A missing or invalid value will cause the termination of the job on the appliance, leaving a partially processed output file. Thus it is important that the structure of the XML input file be verified against the SAKA schema before submitting the job to the appliance.
14	The closing InputValues tag.
15	The closing SBI tag.

An example of the SBI element for a decryption operation is shown below:

#	SBI Decrypt XML Example
1	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2	<SKLESBatchInput
3	xmlns='http://strongkeylite.strongauth.com/SKLES201009'>
4	<DomainId>1</DomainId>
5	<JobId>JOB123-20100920T111353</JobId>
6	<Transaction>Decrypt</Transaction>
7	<InputNumber>5</InputNumber>
8	<InputValues>
9	<Input>9999000000000786</Input>
10	<Input>9999000000000787</Input>
11	<Input>9999000000000788</Input>
12	<Input>9999000000000789</Input>
13	<Input>9999000000000790</Input>
14	</InputValues>
15	</SKLESBatchInput>

The following table explains each line of the above XML that differs from the first example:

#	SBI Decrypt XML Explanation
2	The start of the SBI element. Elements in this example are unqualified because the default namespace definition in line 3 is associated with an empty prefix (nothing after the xmlns).
6	The Transaction element identifies the Decrypt operation.
9–13	Each Input element has precisely one token—the Pseudo Number (PSN)—that was originally assigned by the appliance when it was first encrypted. This token is required to locate the encrypted data in the appliance; decrypt it and write it to the output file.

The XML files for Delete and Search operations are identical to the two presented here. They only differ in the Transaction element and the type of data presented in the Input elements; deletion operations take tokens as their input value, while search operations require the original plaintext data.

SKLESBatchOutput Element

Upon completion of a batch operation, if there are no errors, SAKA creates an XML file that conforms to the SBO element. This element, also defined in the SAKA.xsd file, is identical for the output of any type of cryptographic operation. A sample SBO file is presented below:

#	SBO XML Example
1	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2	<SKLESBatchOutput
3	xmlns='http://strongkeylite.strongauth.com/SKLES201009'>
4	<DomainId>1</DomainId>
5	<JobId>X1234-20100520T211723</JobId>
6	<Transaction>Encrypt</Transaction>
7	<InputNumber>5</InputNumber>
8	<OutputValues>
9	<Output>
10	<Input>1111222233330001</Input>
11	<Result>9999000000001002</Result>
12	</Output>
13	<Output>
14	<Input>1111222233330002</Input>
15	<Result>9999000000001003</Result>
16	</Output>
17	<Output>
18	<Input>1111222233330003</Input>
19	<Result>9999000000001004</Result>
20	</Output>
21	<Output>
22	<Input>1111222233330004</Input>
23	<Result>9999000000001005</Result>
24	</Output>
25	<Output>
26	<Input>1111222233330005</Input>
27	<Result>9999000000001006</Result>
28	</Output>
29	</OutputValues>
30	<OutputNumber>5</OutputNumber>
31	</SKLESBatchOutput>

The following table explains each line of the above XML file:

An example of the SBO element for a Decryption operation is identical to the SBO file for the Encrypt operation, except that the Input and Result values are reversed—i.e., the Input element has the token, vile the Result element has the original plaintext data.

The SBO files for the Delete and Search operations have different types of Result output. The Delete example is shown below:

#	SBO File after Batch Deletion
1	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2	<SKLESBatchOutput
3	xmlns='http://strongkeylite.strongauth.com/SKLES201009'>
4	<DomainId>1</DomainId>
5	<JobId>DELETE-20100520T211723</JobId>
6	<Transaction>Delete</Transaction>
7	<InputNumber>4</InputNumber>
8	<OutputValues>
9	<Output>
10	<Input>9999000000002986</Input>
11	<Result>True</Result>
12	</Output>
13	<Output>
14	<Input>9999000000002987</Input>
15	<Result>True</Result>
16	</Output>
17	<Output>
18	<Input>9999000000004988</Input>
19	<Result>SKL-ERR-1011: Token not found</Result>
20	</Output>
21	<Output>
22	<Input>9999000000007989</Input>
23	<Result>SKL-ERR-1011: Token not found</Result>
24	</Output>
25	</OutputValues>
26	<OutputNumber>4</OutputNumber>
27	</SKLESBatchOutput>
28	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
29	<SKLESBatchOutput
30	xmlns='http://strongkeylite.strongauth.com/SKLES201009'>

The following table explains each line of the above XML file:

#	SBO XML Explanation
6	The Transaction element identifies the Delete operation.
9–12	This Output element shows that the token—9999000000002986 in this case—was deleted because the Result element indicates “True.”
13–16	This Output element also indicates that the record was deleted from the appliance.
17–20	This Output element indicates an error—the error code and message indicate the provided token number was not found on the appliance, so nothing was deleted.
21–24	This Output element also indicates the same error as the previous one.

The SBO file for the Search example is shown below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<SKLESBatchOutput  

xmlns='http://strongkeylite.strongauth.com/SKLES201009'>

<DomainId>1</DomainId>

<JobId>SEARCH-20100520T112723</JobId>

<Transaction>Search</Transaction>

<InputNumber>3</InputNumber>

<OutputValues>

<Output>

<Input>1111222233330001</Input>

<Result>9999000000003007</Result>

</Output>

<Output>

<Input>1111222233330002</Input>

<Result>9999000000003008</Result>

</Output>

<Output>

<Input>1111222533330003</Input>

<Result></Result>

</Output>

</OutputValues>

<OutputNumber>3</OutputNumber> 

</SKLESBatchOutput>

The following table explains each line of the above XML file:

#
6	The Transaction element identifies the Search operation.
9–12	This Output element shows that the input value—1111222233330001 in this case—was found on the appliance and its token value is in the Result element as 9999000000003007.
13–16	This Output element also indicates that the input value was found on the appliance and has a token value of 9999000000003008.
17–20	This Output element indicates that the token number provided was not found on the appliance, hence nothing was returned in the Result element.

Generating the SBI XML file

While it is expected that most applications communicating with SAKA will be modified to generate the SBI XML input file directly, there will be some period where it will be necessary to perform the batch operations expediently without having to wait for internal applications to be reprogrammed.

To help during the transition process, the appliance's strongkeyliteClient.jar application includes an option called GenerateBatchInput in the application to take an ASCII text file, with a single record per line in the file, free of any comments or ornamentation, and convert it into an XML file conforming to the SBI schema.

Typing the following command provides some help on the usage of GenerateBatchInput:

java -cp sakaclient.jar GenerateBatchInput

When run, it results in the following output:

Parameter	Explanation
<input-file-name>	The full file-name of the plain ASCII input file containing the lines of text to be converted to SBI in an XML file.
<output-file-name>	The full file-name of the XML file that will contain the resulting XML. It is strongly recommended that convention for these filenames is established so there are no over-write errors. StrongKey recommends the following: the domain ID, followed by a hyphen, followed by the source application name or requester, followed by a hyphen, followed by the date-timestamp. An example would be 1-PANDB-20100920154535.xml, indicating that the XML file belongs to domain ID 1, was sourced from the PAN database application and was created at 3:45:35PM on 20 September 2010. This will ensure that the same application creating the same text file for a second batch operation will not overwrite the first file on the appliance even as it is being processed (as it will be likely very difficult for any application to write out two files in the exact same second).
<DID>	The unique encryption domain identifier in which this batch job will be processed.
<job-name>	A helpful job-name that can be embedded inside the XML file, so the resulting output can be processed by the client application meaningfully. This name can be an identifier string that has meaning in the application environment.
<Encrypt|Decrypt|Delete|Search>	One of the four cryptographic operations requested for this XML file.
<number-of-records>	The number of lines in the plain ASCII text file. While this is not meant to be a hard number that will prevent the appliance from processing the XML file if the actual number is more or less than this number, it is a helpful guide to humans who may be reviewing the XML file.
[SAKA.xsdlocation-name]	An optional parameter specifying the full path location of the SAKA.xsd file against which the strongkeyliteClient.jar application builds the XML document. On the SAKA server, this parameter is unnecessary since the file exists in /usr/local/strongauth/strongkeylite/etc. However, it may be useful to generate this XML file on other computers—PCs or other servers—without needing access to the appliance itself for generating the XML input file. In that case, copying SAKA.xsd to any location on one's PC or server (along with strongkeyliteClient.jar and its supporting libraries, of course) makes it possible to generate this XML input file outside the appliance. SAKA.xsd must be present at the specified location, otherwise the strongkeyliteClient.jar application will not know what type of XML to generate.

In the current directory where the strongkeyliteClient.jar file exists, if a plain ASCII text file exists—plain-input.txt—including the following lines of text...

1111222200000001
1111222200000002
1111222200000003
1111222200000004
1111222200000005
1111222200000006
1111222200000007
1111222200000008
1111222200000009
1111222200000010

...the following command will convert it to an XML file in the SBI format...

java -cp sakaclient.jar GenerateBatchInput plain-input.txt 1-ABCD-20100920T163300.xml
	1 ABCD-PAN-Conversion Encrypt 10

...and resulting in the following XML file:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SKLESBatchInput xmlns="http://strongkeylite.strongauth.com/SKLES201009">
    <DomainId>1</DomainId>
    <JobId>ABCD-PAN-Conversion</JobId>
    <Transaction>Encrypt</Transaction>
    <InputNumber>10</InputNumber>
    <InputValues>
        <Input>1111222200000001</Input>
        <Input>1111222200000002</Input>
        <Input>1111222200000003</Input>
        <Input>1111222200000004</Input>
        <Input>1111222200000005</Input>
        <Input>1111222200000006</Input>
        <Input>1111222200000007</Input>
        <Input>1111222200000008</Input>
        <Input>1111222200000009</Input>
        <Input>1111222200000010</Input>
    </InputValues>
</SKLESBatchInput>

The following figure shows the use of the optional SAKA-location-name parameter since this was executed on a PC where the SAKA.xsd file was not automatically available:

There are no limits to the number of records that may be included in an SBI element of the XML file; however, very large numbers of records may require that the Java executable program be provided more “heap memory” for its execution by supplying an “-Xms” and/or “-Xmx” option, as follows:

java -Xms2048m -Xmx4096m -cp sakaclient.jar GenerateBatchInput plain-input.txt 1-ABCD-20100920T163300.xml 1 ABCD-PAN-Conversion Encrypt 1000000 SAKA.xsd

Indicating that this generation process use 2GB of heap-memory initially when creating the Java Virtual Machine (JVM) to execute the program, and use a maximum of 4GB during the execution, if needed.

The resulting XML file may now be transferred to the appliance for batch processing.

Transferring XML Files to and from the Appliance

To execute the batch operation to the appliance, the XML input file must be transferred to the appliance, into a specific directory. Until the file reaches the specified location, the appliance will be incapable of performing the execution.

Transferring the XML input file requires access to the appliance though one of three supported file-transfer protocols on the appliance: SFTP, NFS, or SMB. This chapter explains how to transfer files using SFTP; NFS, and SMB are beyond the scope of this document, but can be discussed with StrongKey separately, if desired.

Every encryption domain must have a user defined at the Linux operating system layer (generically called Batch-Requester in this document) to be able to transfer the XML files into and out of the appliances. The first encryption domain (DID 1) creates during the installation process, but each additional encryption domain requires that the user be created manually.

The Batch-Requester has a Linux username like “domainN” where “N” is the domain identifier. So, the operating system username for the first encryption domain will be domain1, while that of the second encryption domain will be domain2 and so on.

Each Batch-Requester has a home directory under /usr/local/strongauth/batchrequests where the directory is owned by the strongauth user, but with read-write privileges for the domainN user, too. The home directory for domain1 will be /usr/local/strongauth/batchrequests/domain1.

Under the /usr/local/strongauth/batchrequests/domain1 directory are two subdirectories: in and out. All XML input files must be transferred into the in subdirectory, while all processed XML output files must be transferred from the out subdirectory.

Assuming a domain identifier of 1, using the domain1 credential and the password given by the SAKA Domain Administrator, transfer the file to /usr/local/strongauth/batchrequests/domain1/in. This is shown in the following figure. Once the file is there, the job can be submitted for execution.

Submitting Batch Operations

To submit a batch operation to the appliance, the requester—who may be a human being or an application—must submit the XML input file and a web service request to the appliance. The last section discussed how to transfer the input XML file to the appliance.

Submitting the web service request to the appliance is no different from submitting any other SAKA web service request: it requires four parameters, as follows:

DID	The unique encryption domain identifier.
username	The username (service credential) within the encryption domain with the authorization to call this web service. The credential requires the Key Component Operator (KMO) privilege.
password	The password of the username to authenticate the credential of the requester.
filename	The filename of the XML input file that was transferred to the appliance before the web service request is made. The filename must not include any path qualifiers—just the name of the file.

An example of submitting a batch encryption request using the sakaclient.jar client program is shown below:

java -jar sakaclient.jar https://demo2.strongauth.com:8181 1 encryptonly Abcd1234! BE 1-ABCD-20100920T163300.xml

Upon successfully sending the batch web service request, the sakaclient.jar program displays the following output:

The output file produced from the batch execution has the following name format: the domain identifier, followed by the unique batch request ID assigned to this job, followed by -Output.xml. The example above indicates that this was the 18^th batch request job submitted to domain ID 1, hence the output file has a name of 1-18-Output.xml.

Using SFTP (or NFS or SMB if it is configured), the requester can now pick up the processed output file.

NOTE: While the appliance will automatically delete input XML files for encryption and search operations (it keeps the input XML files for the decrypt and delete operations since they do not have any sensitive data in them), the output files MUST be deleted after transferring them if they were submitted for any operation other than the Delete operation. This is because all other operations result in output files that will have the unencrypted sensitive data in them. Not transferring and deleting these files immediately after the web service call has completed will increase the risk of plaintext being exposed.

All the other batch operations use the identical four parameters: DID, username, password, and input filename. The only difference is inside the XML input file which identifies the cryptographic operation that must be performed.

KAM DemoClients

To test SAKA web services, the appliance comes with a Java-based client application that can be used to test the web service operations of the SAKA server. The Java client—called sakaclient.jar—can be used to call web service operations on a DEMO appliance on the internet—demo.strongauth.com—or on the SAKA cluster within a network.

The DEMO SAKA uses the identical software as appliances delivered to customers. This allows application development teams to verify their code without having to wait for a SAKA implementation internally. Once verified against the DEMO SAKA, the identical code will work against the internal SAKA implementation without changing a single line of code. The only differences would be the URL of the host and the parameters passing at runtime. (We recommend parameterizing the URL of the appliances being called; this will make it easier to point applications to SAKA during deployment to production).

The client application is a simple Java application that calls the web service on SAKA to perform one of many operations; it simulates what the applications must do to call the EncryptionService on the SAKA server. While the client application will certainly be different, based on site-specific business functions it implements and the programming language and application model it uses, ultimately it must perform the same web service functions as the test client application bundled in SAKA. Because the client application focuses only on testing the implementation of the SAKA service, it is ideal for ensuring the correctness of a specific site’s implementation.

The currently supported perations of the DEMO client are:

1. Encrypt simulated credit card numbers.

2. Decrypt the ciphertext for previously encrypted credit card numbers.

3. Encrypt and decrypt a credit card number within a single transaction.

4. Delete a credit card number from the cluster.

5. Search for a credit card number on the cluster.

6. Return bytes of entropy from the SAKA Cryptomodule.

7. Submit a job to encrypt credit card numbers, in batch mode.

8. Submit a job to decrypt credit card numbers, in batch mode.

9. Submit a job to delete credit card numbers, in batch mode.

10. Submit a job to search for credit card numbers, in batch mode.

11. Relay a payment transaction to authorize.net using HTTP POST (requires the site’s own account and access keys to authorize.net to perform this test).

The client application distinguishes between these operations to allow sites to test different levels of authorization for the web services:

1. Users who are authorized to only encrypt.

2. Users who are authorized to only decrypt.

3. Users who are authorized to encrypt and decrypt.

4. Users who are authorized to only delete.

5. Users who are authorized to only search.

6. Users who are authorized to only relay transaction to a payment gateway.

7. Users who are authorized to perform all operations.

8. Users who are NOT authorized to perform any operation.

Installing SAKA Clients

Two files must be copied onto a remote computer to install the demo client:

• The sakaclient.jar file

• The TLS server certificates of the SAKA servers

These files may be copied from the SAKA server to the remote computer on a USB flash drive, or they may be downloaded directly to the remote computer using a browser.

USB Copy from SAKA

The following instructions show how to copy using a USB flash drive:

1. Login to SAKA with the strongauth account.

2. Start up the Graphical User Interface (GUI) with the startx command.

3. Plug a USB flash drive into the SAKA server. A File Manager window should open within a few seconds, showing the files on the USB flash drive (if any).

4. Using the File Manager, copy the <FQDN>.der file (where FQDN is the fully qualified domain name of the SAKA server) from the STRONGAUTH_HOME/certs directory to the flash drive.

5. Using the File Manager, also copy the sakaclient.jar file, sakagclient.jar file, and the lib directory from the STRONGAUTH_HOME/topaz directory to the flash drive.

6. From the File Manager of the USB flash drive, unmount the drive from the SAKA server.

7. Remove the USB flash drive.

8. Copy the <FQDN>.der file, .JAR files, and lib folder to a folder on the remote computer running Windows. For this discussion, assume the files have been copied to a folder called saka under the user’s home directory on the Windows PC.

9. This successfully concludes the section on how to copy a SAKA TLS certificate and the sakaclient.jar file to the local PC using the USB flash drive.

Downloading the Certificate

The following instructions show how to copy the files using the Firefox browser. The Firefox browser can be downloaded from www.firefox.com, if necessary.

NOTE: While it is possible to perform these “certificate-trust” steps using another browser, such as Internet Explorer, Chrome, or Safari, StrongKey has not documented these detailed steps in this document. Those familiar with connecting to a site with an unknown TLS certificate and then viewing and saving the TLS certificate to a computer are welcome to use any browser to perform these steps. There is no difference in the TLS certificate no matter which browser downloads the certificate.

The images below show the required files being downloaded from https://demo2.strongauth.com:8181/ or https://demo3.strongauth.com:8181/. Just follow the instructions, substituting the demo2.strongkey.com or demo3.strongkey.com site name with the FQDN of the SAKA server:

NOTE: demo2 and demo3 represent a cluster of two SAKA nodes. They are configured in the DMZ of StrongKey's domain and replicate to each other over a local area network. To use the Demo client to test against StrongKey's demo appliances, either URL should work for the examples provided below. The internal cluster is likely to have the same or more SAKA nodes, and may or may not support all web services, depending on what has been configured for use.

1. From a PC, using the Firefox browser, type in the URL of the SAKA server in the address bar; the URL must specify the https protocol and port 8181. For example, if the primary SAKA server is saka01 in yourdomain.com, the URL would be https://saka01.yourdomain.com:8181/index.html. The following screen displays in the browser:
   

2. Click I Understand the Risks. The following image displays:
   

3. Select the Add Exception... button. The Add Security Exception dialog displays.
   

4. In the Location field, type the URL of the certificate and click Get Certificate. The View... button lights up.

5. To view the certificate, click View…. The Certificate Viewer dialog displays.
   

6. Click the Details tab.
   

7. Click Export… Then add a .pem extension to the filename. Select the directory where the Client Demo files will be installed, then click Save.
   

8. Select the Close button on the Certificate Viewer dialog.

This successfully concludes the section on how to copy the SAKA TLS certificate and the sakaclient.jar file to a local PC using the Firefox browser.

Importing the Certificate into the JVM

To import the SAKA digital certificates into the JVM environment and to run the test client application, execute the following steps.

1. On a Windows PC, open a Command Prompt as Administrator.

2. Change directory to the C:\Program Files\Java\jdk1.8.0_66\bin folder.

3. Type the following command on a single line:

   keytool.exe -importcert -keystore ..\jre\lib\security\cacerts -storepass changeit -alias saka -file <location-of-file>\<FQDN>.der

   A prompt displays to trust the digital certificate during the import process.

4. Verify that the certificate was imported correctly with the following command.

   keytool -list -keystore ..\jre\lib\security\cacerts -storepass changeit -alias saka

   The listed certificate and its MD5 hash appear in the response.

sakaclient.jar Operations

The sakaclient.jar file supports the following options:

Displaying Help Options

Type the following commands to verify that the client application is executable.

java -jar sakagclient.jar 
	java -cp sakagclient.jar GCMMain

By default the sakgclient shows a helpful prompt of the operations it can perform and the parameters it expects for each operation.

An explanation of the parameters to the demo client application follows:

Parameter		Explanation
https://<host:port>		Use https://demo.strongkey.com for testing
<did>		The unique encryption domain identifier. This was provided separately by StrongKey as a unique domain for testing.
<username>		The username within the encryption domain with authorization to call the web service. These usernames were provided separately for testing.
<password>		The password of the username within the encryption domain that has authorization to call the web service. These passwords were provided separately for testing.
Supported Operations
E	Encryption	Encryption of 16-digit PANs where only the last 8 digits of the PAN must be specified on the command line; the first 8 digits are programmed into the client application as a convenience for quick testing.
D	Decryption	Decryption of a token.
B	Both encryption and decryption	Encryption and decryption of 16-digit PANs where only the last 8 digits of the PAN must be specified on the command line; the first 8 digits are coded into the client application as a convenience for quick testing.
<string-to-encrypt>		A UTF-8 string of arbitrary length. If the string has blank spaces or special punctuation marks, enclose the string in double quotes and place a backslash in front of the special punctuation mark to escape it from being processed by the Linux shell (if using Linux to test this tool).
<token>		For decryption, the client expects the token that was returned by KAM when encrypting the string.

Encryption (CBC Mode)

To encrypt a test string, type in the following commands separately. In this example the URL is https://demo.strongkey.com, the domain ID is the numeral 1, the username is all and the password is Abcd1234!. The string to be encrypted is within double quotes:

java -jar sakagclient.jar https://demo.strongkey.com 1 all Abcd1234!
E “You must be the change you want to see in the world.  M. K. Gandhi”

java -jar sakagclient.jar https://demo.strongkey.com 1 all Abcd1234!
B “You must be the change you want to see in the world.  M. K. Gandhi”

The top half of the window pictured below shows the sequence of activities performed by sakagclient: a new AES encryption key was generated by the client (shown as a Base64-encoded string on the first line) and escrowed on the KAM, which returned the token 1000000000101315. Using the token as the initialization vector (IV) for the CBC mode of operation, sakagclient encrypts the string within double quotes and displays the Base64-encoded ciphertext on the last line of the output.

The bottom half of the window pictured below shows a variation of the same command, but this time the command has specified the B option, which encrypts the supplied string, then immediately decrypts the ciphertext in the same operation and compares the decrypted plaintext with the original to determine if they are the same.

The second command also generates a new AES key and escrows it—resulting in a new token 1000000000101316—then recovers the escrowed key from the KAM and decrypts the ciphertext to compare with the original. As the output shows, the original and decrypted plaintext are identical.

The KAM has the ability to escrow cryptographic keys in this manner—TDES, AES, RSA, ECDSA—almost any cryptographic (or binary) object that can be Base64-encoded to a UTF-8 string of length less than 10,000 characters can be encrypted and stored on the SAKA server as a secure vault. SAKA has been successfully used to store more than 50 million objects in production use at customer sites.

An error message resembling the following implies the SAKA server's TLS certificate has not imported successfully into the JVM.

Exception in thread "main" javax.xml.ws.WebServiceException:
Failed to access the WSDL at:
https://demo.strongauth.com/strongkeyliteWAR/EncryptionService?wsdl.
It failed with:
sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target.
at com.sun.xml.internal.ws.wsdl.parser.RuntimeWSDLParser.tryWithMex
(RuntimeWSDLParser.java:151) at com.sun.xml.internal.ws.wsdl.parser.RuntimeWSDLParser.parse
(RuntimeWSDLParser.java:133) at com.sun.xml.internal.ws.client.WSServiceDelegate.parseWSDL
(WSServiceDelegate.java:254) at com.sun.xml.internal.ws.client.WSServiceDelegate.<init>
(WSServiceDelegate.java:217) at com.sun.xml.internal.ws.client.WSServiceDelegate.<init>
(WSServiceDelegate.java:165) at com.sun.xml.internal.ws.spi.ProviderImpl.createServiceDelegate
(ProviderImpl.java:93) at javax.xml.ws.Service.<init>
(Service.java:56) at com.strongauth.strongkeylite.web.EncryptionService.<init>
(EncryptionService.java:79) at strongkyeliteClient.Main.main
(Main.java:109)

If the certificate seems to have successfully imported into the JVM, and can see it when listed within KeyTool, then the Command Tool is likely pointing to a different JVM in its Path setting. Make sure the Command Tool is using the JVM with the imported certificates in its cacerts file. Either change the Path setting permanently through the Control Panel, or change it temporarily in the Command Tool itself.

Alternatively, call the correct JVM by specifying the full pathname of the Java executable without changing the Path.

An error resembling the following implies that a JAR library—bcprov-jdk15on-1.54.jar—is not in the lib subdirectory where sakagclient exists.

Make sure there is a subdirectory called lib in the same folder where the sakagclient.jar file exists, and that BouncyCastle JCE Provider 1.54 exists in the lib subdirectory. Then attempt the command again.

Exception in thread "main" java.lang.NoClassDefFoundError: org/bouncycastle/util/encoders/Base64
	at GCMMain.decryptText(GCMMain.java:324)
	at GCMMain.main(GCMMain.java:237)
Caused by: java.lang.ClassNotFoundException: org.bouncycastle.util.encoders.Base64
	at java.net.URLClassLoader.findClass(URLClassLoader.java:381)
	at java.lang.ClassLoader.loadClass(ClassLoader.java:424)
	at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:331)
	at java.lang.ClassLoader.loadClass(ClassLoader.java:357)
	... 2 more

Decryption (CBC Mode)

To test decryption, call sakagclient with the D option and use the ciphertext from the encryption transaction (from the transaction similar to the top half of the diagram in Section 3.2 of this chapter) on the local computer—it is sure to be different from the ciphertext shown in this document) as well as the token from the encryption test as parameters. Make sure to copy the ciphertext exactly as it shows in the output of the encryption command:

java -jar sakagclient.jar https://demo.strongauth.com 1 all Abcd1234!
D HdYm1/+R5FA32AvqJ/WsnwirsW0UHiZF/7Qpc6ySXbVDIQsjjGtDBeObdvvQU5FKu5grm58v5DXtqNk1jl39cNBpR0Ht3DX/xUz2vZPC0uo=
1000000000101315

The operation may take a little while because cryptographic keys may need to be loaded from the internal database and decrypted before the actual encrypted object can be decrypted. However, once the keys are decrypted, they are cached for a short duration (15 minutes); repeating the same decryption operation immediately produces an immediate response. The following picture shows the successful return of the original string (“You must be the change you want to see in the world. M. K. Gandhi”)

NOTE: The first web service request for encryption or decryption within a user's session will see a long delay because of the following factors:

• The latency of the internet

• The verification of the user's authorization (which causes the decryption of a hierarchy of keys in the hardware module to verify the user's password)

• The decryption of the symmetric key before it is available for use

• The actual encryption/decryption of the PAN data

A key-caching feature of SAKA (15 minutes by default) enables subsequent operations to see significant improvements in performance. However, at the end of the default caching period, the keys are flushed from memory and the first cryptographic operation after the flush will see a similar delay as keys are decrypted and loaded into cache memory. The caching window can be configured for individual business needs.

From a performance point of view, the current generation of SAKA, using a TPM, delivers approximately 200–220 web service operations per second (WSOPS) when multi-threaded client applications make requests. In a clustered environment where all nodes in the cluster may service client applications, the overall WSOPS will be higher than for an individual SAKA, but will be difficult to predict in advance without understanding the topology of a given network and affected applications.

Encryption (GCM Mode)

To test the GCM of authenticated encryption, type in the following command:

java -cp sakagclient.jar GCMMain https://demo.strongkey.com 1 all Abcd1234!
E “You must be the change you want to see in the world.  M. K. Gandhi”

java -cp sakagclient.jar GCMMain https://demo.strongkey.com 1 all Abcd1234!
E “You must be the change you want to see in the world.  M. K. Gandhi”

This is, essentially, asking the sakagclient to encrypt the string specified on the command line using the GCM mode of operation. The result of this execution is shown in the top half of the figure below.

In this execution, sakagclient first calls KAM to retrieve some entropy from the TRNG on the SAKA (shown in the retrieved seed line). It then generates a new AES key, escrows it on the KAM and gets a token (1000000000101319). Using the last 96 bits of the token for the Additional Authenticated Data (AAD), sakagclient then encrypts the supplied string in the GCM mode of operation to display the resulting ciphertext.

In the bottom half of the following figure, the same string is encrypted and decrypted by specifying the B (both) option. It performs the same operations as for the encrypt operation, but goes on to recover the original cryptographic key by recovering it from KAM, decrypting the ciphertext and comparing the original plaintext with the decrypted value.

Decryption (GCM Mode)

To test decryption, call sakagclient with the D option and use the ciphertext from the encryption transaction (from the transaction similar to those shown in Section 9.3.2—it is sure to be different from the ciphertext shown in this document) and the token from the encryption test as parameters. Make sure to copy the ciphertext exactly at it shows in the output of the encryption command.

java -cp sakagclient.jar GCMMain https://demo.strongauth.com 1 all Abcd1234!
D vQm9+o6Ofjv4kNuHH7KfJsExIcH0z3BvI1YJO6PpFIlc9nxNgESBJjJLg3MlCBgLGU8Wlq/prCKROeYa0oWRm1tZS56ObUYMEE/XdR2ia4WsNQ== 
1000000000101319

A result displays similar to the following:

In this manner, the sakagclient can be used to test various web services of the SAKA KAM.

KAM KCSetPINTool

For cryptographic services to be available on SAKA, the cryptographic hardware module on the appliance must be activated. The cryptographic module—either the Trusted Platform Module (on the Model-T) or the Hardware Security Module (on the Model-H)—holds the “root” key of the key hierarchy that protects all cryptographic keys on the appliance. However, the hardware module can only be activated by Key Custodians (KCs) with their Personal Identification Numbers (PINs)—which they established during the installation of the appliances. Only when the hardware module is activated, does the “root” key become available, which in turn, enables cryptographic services to become available to business applications.

NOTE: SAKA security is entirely predicated on the “root” key. However, on the Model-T, the Storage Root Key (SRK) cannot leave the hardware module—this is part of the design specification for the TPM, as specified by the Trusted Computing Group (TCG). Once created upon initialization, the SRK can only be activated for use or destroyed during re-initialization. On the Model-H, the “root” key is generated inside the HSM, and can leave the HSM only under the protection of another encryption key in a controlled process.

In the event of a restart of the SAKA, since it is unfeasible for KCs to be available in remote server-rooms where the SAKA is typically deployed, SAKA includes a client application—the Key Custodian SetPIN Tool (KCSPTool)—that allows KCs to activate the hardware module from remote locations. All that is required is for the KCs to have a connection to SAKA from their computers and the USB flash drive that contains their credential (which was created when SAKA was initially set up).

While it is recommended that KC connections be controlled through an access-control list of a router or switch to prevent denial-of-service (DoS) attacks, the connection need not be secured for confidentiality since SAKA accepts KC commands and responses only over a secure transport protocol—Transport Layer Security.

The installation process of SAKA instances would have resulted in the KCs being given the KCSPTool on some media they would use to install on their computers. Since the KCSPTool is a Java application, it can run on any platform where a Java Virtual Machine (JVM) is available. It is necessary for the KCs to have a supported version of the JVM on their computer to use the tool. See 3—Architecture for the supported version of the JVM for your appliance.

On a Windows PC, the KCs would use a Command Tool script (a batch file) to start the KCSPTool. On a Linux computer, this would be shell script. The script file can be associated with an icon on the KC's desktop to make it convenient for the KC to use the tool.

NOTE: It is strongly recommended that KCs never copy their credential file from the USB flash drive to their computer for convenience. While it might be tempting, leaving the file on the computer could leave the file vulnerable as it might be copied off by an attacker, who might then try to determine the KC's PIN by subjecting the file to a dictionary attack or a rainbow table attack. Sites may not only want to enforce this through a company policy, but also through automated tools that delete such credential files when found on the hard disk of a KC's computer. Ultimately, the site must rely on the responsibility of the KC to preserve the security of their credential—policies and automated tools can only go so far.

When the KCSPTool starts it displays the following screen:

Setting KC Preferences

Since each KC is assigned to a specific role with a specific credential file, the KCSPTool provides a preferences panel to save frequently used parameters so they don't have to be typed in repeatedly. However, the password is never saved and must always be typed.

The Preferences panel can be viewed by selecting File → Preferences from the menu. Once selected, it displays the following panel:

The form's fields echo the main display of the KCSPTool. The only difference is the SAKA URLs text area which allows the KC to type in several URLs of different SAKA servers for which they may be a custodian. While most sites may only have one primary SAKA server—and thus only one URL in this text box—some sites may have multiple SAKA servers for which KCs are responsible. Typing in the URLs of the different appliances allows them to select the one they wish to activate from the drop-down on the main panel.

Once the KC has made his/her choices, selecting the Save button saves the preferences.

Changing KC Passwords

Changing the password to a KC keystore may be necessary when changing ownership of the keystore, as part of a company's security policy, or just as a good practice. The KCSP provides the ability to change the password of any KC keystore though the Change Password panel.

To change the password on a KC keystore, follow this process:

1. Insert the KC's SAKA USB flash drive into the computer.

2. Select File → Change Password from menu. The following dialog displays:

   

3. Browse to and select the keystore to populate the Keystore Location field.

4. Enter the Current Password for this keystore. Click the Verify button to confirm the password.

5. If the password is confirmed successfully, the two bottom fields will become usable. Enter the desired New Password and again in the New Password Again field. Once finished, press the Enter key within the New Password Again field and the tool will confirm whether both passwords match. If successful, the Save button will be enabled.

6. Click the Save button to apply the new password to the keystore.

Setting the KC PIN on the SAKA Server

To activate the cryptographic hardware module, each KC must perform the following steps. They may do this individually on their own computers, but until all KCs have activated the module, the cryptographic web services do not become available to applications.

1. The KC inserts their SAKA USB flash drive into the computer.

2. After starting KCSPTool, the KC verifies the displayed choices on the panel and makes appropriate changes, if any.

   

3. The KC then types the password and clicks Verify.

   NOTE: If the password is incorrect, a message appears, stating, “The password does not verify; correct it and try again.” Make changes to the password and click Verify again.

4. Once the password is verified correctly, click Submit. A successful transaction results in the message, “Successfully set PIN on server.” The results pane displays how many PINs have been set, what the minimum required number is, and which KCs have set PINs.

   NOTE: If the server is unavailable, a message appears, stating, “Failed to access the WSDL at [Web Service URL].” Make changes to the Webservice URL and try again.

5. The KC can now exit the tool. Once all KCs have similarly activated the cryptographic module with their credentials, SAKA is now ready to receive and respond to web service requests from applications.

KAM DACTool

The Domain Administration Console Tool (DACTool) is a graphical user interface (GUI)-based tool to manage the encryption domains within a SAKA installation. It is meant to be used by SAKA domain administrators to perform the following tasks:

• Deactivate and activate an encryption domain

• Add, modify, and delete users from the SAKA internal database

• Schedule or run standard jobs on SAKA

• Modify the configuration of an encryption domain

• Set a domain administrator's (DA) preferences when using DACTool

DACTool is a Java-based Rich Client Application (RCA). This means it is not a web-based application and must be installed on the machine where it will execute. Since it is installed on the SAKA server, it is always accessible on the appliance itself, but it can be installed and configured to work on any platform where a supported Java Virtual Machine (JVM) is available. It is best viewed on a screen with 1920×1200 resolution.

To start DACTool on the SAKA server:

1. Login to the appliance from the console as strongauth.

2. Start the XWindows environment by typing in startx from the command-prompt.

3. Execute /usr/local/strongauth/bin/DACTool.sh shell script from a command-tool window. This will open the Main Panel of the DACTool.

   

DACTool menus are as follows:

Changing DA Passwords

Changing the password to a DA keystore may be necessary when changing ownership of the keystore, as part of a company's security policy, or just as a good practice. DACTool provides the ability to change the password of any DA keystore though the Change Password panel.

To change the password on a DA keystore, follow this process:

1. The DA inserts their SAKA USB flash drive into their computer. Click File → Change Password from the menu. The following dialog displays:
   

2. In the Keystore Location field, Browse to the location of the keystore.

3. Enter the Current Password for this keystore. Click Verify to confirm the password.

4. If the password is confirmed successfully, the two bottom fields will become usable. Enter the desired New Password and again in the New Password Again field. Once finished, press the Enter key within the New Password Again field and the tool will confirm whether both passwords match. If successful, the Save button will be enabled.

5. Click the Save button to apply the new password to the keystore.

Preferences

The values specified in the Preferences panel prevent the DA repeatedly typing values on every connection to SAKA.

The Preferences panel is made visible by clicking Preferences → Set Preferences from the menu, or by clicking the Preferences icon on the Main Panel.

The Preferences panel is shown in the figure below. A table follows explaining the fields on the panel.

After the appropriate values are entered in the Preferences panel, click the Save button. This creates a hidden directory in your home directory called .strongkeyliteDAConsole which contains a file called appProperties. Preferences are stored in this file.

To delete all preferences, delete the entire .strongkeyliteDAConsole (notice the period in front of the directory name) subdirectory and its contents. A new subdirectory and files are always created when DACTool is run.

Clicking the Reset button on this panel resets the values to the original values when you came to this panel. If you have saved any preference values, the saved values now become your original values.

Clicking Cancel returns DACTool to the Main Panel without making any changes to any Preferences. If any preference values were saved while on this screen, clicking Cancel will not revert your Preferences to the original values.

Systems

Before a DA can perform any function with the SAKA server, they must connect to the server; the DA must have the USB flash drive with their digital certificate (in the BCFKS file) on it, containing their PrivateKey.

When the DA attempts to connect to the SAKA server with the DACTool, the tool requests a nonce—a random number used only once—anonymously. The server generates a random nonce from its True Random Number Generator (TRNG) and sends it to DACTool. DACTool, upon receiving it, prompts the DA for the password to the BCFKS file. Upon getting the correct password, DACTool uses the PrivateKey to digitally sign the nonce before sending the connection request to the SAKA server. If the digital signature on the nonce is verified correctly by the server and the random nonce is accurate, the SAKA server establishes a connection. The DA may now perform administrations commands on the SAKA server.

Whether a DACTool command succeeds or fails, SAKA always sends a new randomly generated nonce in the response. Every new administration command sent by the DACTool must include the new nonce—digitally signed—to the SAKA server. The signed nonce is always verified before the command is executed.

To open the Systems panel, click Systems → View Systems on the menu or click the Systems icon on the Main Panel. The following dialog opens:

The panel shows a table with all configured appliances in a table. The table shows the FQDN of the server, the port number where the Administration Service is listening, and an icon—either in red or green color—to indicate if the DACTool is currently connected to SAKA or not. In the above figure, it shows one SAKA server listening on port 8181—the same port where the Encryption Service is typically accessible—and red connection icons indicating that the DACTool is not connected to any one of them.

There are two buttons—Connect and Disconnect—that are initially disabled. Upon selecting a specific SAKA server, one of the two buttons will become enabled. If DACTool does not have a connection to a SAKA server, it will enable the Connect button; if DACTool is already connected to it—indicated by a green connection icon—the Disconnect button becomes enabled.

When the Connect button is selected, the tool displays the Connection Parameters panel, shown below. If the DA has saved any preferences earlier, they will be displayed here; otherwise, the application's default values will be displayed. The DA may specify values in the Connection Parameters panel before making the connection.

After typing the password to the keystore, click Verify.

NOTE:If the password is incorrect, a message appears, stating, “Password does not verify keystore.” Make changes to the password and click Verify again.

Upon supplying the correct values in the Connection Parameters panel and confirming the keystore password is correct, click the Connect button. DACTool attempts to connect to the selected SAKA server and provides one of two possible responses.

If the SAKA services are not running, or if they are but the Key Custodians of the SAKA have not activated the cryptographic hardware module on the server since the server was restarted, the following error message displays on the status bar of DACTool:

Could not get a nonce from server—the SAKA service may not be running or the Key Custodians may not have activated the crypto-module.

If such an error message is displayed, the DA cannot do anything with the SAKA server until the services have been started and the Key Custodians activate the cryptographic hardware module. (See Chapter 10 for more details).

If the services are running and the Key Custodians have activated the cryptographic module, the connection icon will turn green and a message displays, “Successfully connected to the SAKA server.” The Disconnect button also becomes enabled.

All administrative tasks on this encryption domain on the SAKA are now available until it the Disconnect button is clicked or DACTool is closed.

Domains

All cryptographic services performed by the SAKA servers are organized by SAKA encryption domains (SED). An SED is a logical entity that has a unique identifier, a name, its own key management policies, keys, users, and data. SAKA can host as many SEDs as the machine's physical capacity permits (it can theoretically manage (2⁶⁴‒1) encryption domains—but practically, most appliances will have just a few encryption domains on them—service providers that perform payment services, etc. may have a few hundred or even thousands of domains—one per customer).

When SAKA is newly installed, there is only one SED created on the machine as part of the installation process. This SED has a domain identifier (DID) value of 1. Most sites are likely to have just this one SED on the machine, and as such, the default values in the DA Preferences panel and the Domains panel are appropriate.

Click the Domains icon or Domains → View Domain on the menu. The following displays:

The Retrieve an encryption domain's information panel displays two fields—neither of which are modifiable—and two buttons:

Currently connected to SAKA	The URL of the SAKA server to which DACTool is currently connected. This field remains blank if there is no current connection.
Retrieve Encryption Domain	The unique identifier of the encryption domain to which DACTool is currently connected. This field remains blank if there is no current connection.
Cancel	Cancels the operation and return you to the Home panel.
Retrieve	Retrieves information about the encryption domain and provides an opportunity to view and edit information about it.

If the fields on this panel are not blank, upon selecting the Retrieve button, after a few seconds, a panel like the following is displayed (your domain information will differ):

NOTE: The blue buttons at left are used to dynamically restart the replication services which normally would require a full application restart to accomplish. Replication services consist of several ports and threads; this includes the Acknowledger thread (for receiving replication acknowledgment messages), the BackLog Proccessor (for re-sending old/stale replication objects if they are not acknowledged after a certain period after the replication record was created), the Publisher (for broadcasting replication messages the first time after they are created), and the Subscriber (for listening for incoming replication messages). Restart Replication restarts all the above-mentioned sub services at once.

View or make adjustments to the fields, which are defined here:

Currently connected to SAKA	The URL of the SAKA instance to which DACTool is currently connected.
Domain identifier	The unique identifier of the encryption domain to which DACTool is currently connected. This value can never be modified.
Domain's name	The “friendly” name of the encryption domain. This name can only be established when the domain is first created and never modified.
Domain's current status	The current status of this encryption domain: Active—Indicating the domain provides all cryptographic services to authorized clients. Inactive—Indicating the domain does NOT provide any encryption or decryption services to clients. However, a DA can perform all administrative actions on an inactive domain since administrative services always remain active on the domain. Other—Indicating that the domain does NOT provide any cryptographic services, but has a status different from Inactive, the meaning of which is site-specific. By default, it functions identically to Inactive status. Domain status can be modified by business and security policies.
TPM UUID of encryption key	For SAKA servers using the TPM cryptographic module, this field displays the universally unique identifier of the key object representing the EC encryption keys of this domain. This key object encrypts all symmetric encryption keys of this encryption domain. This value can never be modified.
TPM UUID of signing key	For SAKAs that use the TPM cryptographic module, this field will display the universally unique identifier of the key object that represents the EC signing keys of this domain. This key is used to digitally sign the digital certificates of the Domain Administrators of this domain. This value can never be modified.
Notes (if any)	User-defined comments with a maximum length of 512 alphanumeric characters.
Cancel	Cancels the operation and returns to the Home panel.
Reset	Resets all values to those retrieved from the database, as long as modifications since then have not been saved. Once saved, the saved values will become the new originals.
Save	This button is disabled by default, but if any modifiable values are changed on the screen, the button becomes enabled. Selecting it saves modified values to the database.

Click Save if any changes were made.

Adding a New Domain

The question arises: if DACTool only edits and views an encryption domain's information, how does one add a new encryption domain to SAKA? A business may have many reasons for creating a new domain. Some of the reasons are:

• To address a new regulation requiring different policies for encryption and/or key management

• To serve a different department—such as Human Resources for encrypting Social Security Numbers or pension-related financial data

• To serve a different subsidiary's compliance requirements

• To separate the encryption and storage of credit card numbers based on card issuer

SAKA is capable of hosting as many encryption domains as the physical capacity of the machine permits. So, how does one create a new domain?

The process of creating a new domain, while fairly simple, has one important prerequisite: the unique EC cryptographic keys of the new domain must be securely migrated from the Primary SAKA server to the Secondary under the protection of the Migration and Storage Key (MASK). This process is essential to ensure that encryption keys and data of the new domain are available on the Secondary server in the event of a disaster affecting the Primary server.

While a new encryption domain can be created on any node of the cluster, we recommend performing this task on the Primary.

Generating and Storing Keys

The first portion of adding a new domain generates EC cryptographic keys on the Primary server for the new domain and stores metadata about the new domain in the SAKA database. It also initiates the key migration process for the new domain's cryptographic keys.

1. Login as strongauth on the primary SAKA server.

2. Start up two shell windows.

3. In Window2, change to /usr/local/strongauth/glassfish/domains/domain1/logs.

   shell> cd /usr/local/strongauth/glassfish/domains/domain1/logs

   or use the shell alias aslg:

   shell> aslg

4. In Window2, run the tail -f command on the server.log file so you can watch the output of the server application as it scrolls by.

   shell> tail -f server.log

   or use the shell-alias tsl:

   shell> tsl

5. In Window1, change directory to /usr/local/strongauth/bin.

   shell> cd ~/bin

6. In Window1, execute the New-Domain-Setup-Wizard.sh.

   shell> ./New-Domain-Setup-Wizard.sh

7. Follow the steps of the wizard, ensuring there are no errors in Window1 or Window2. If there are errors, contact StrongKey at support@strongkey.com and discontinue the new domain process.

8. In Window1, execute create-SKCE-Domain.sh to setup this domain for the CEM. Specify the domain number (DID) of this new domain and a password you would like to use to secure the CEM service credentials:

   shell> ./create-SKCE-Users.sh <DID> <password>

Migrating Keys

The process completes key migration on the Secondary SAKA server for the new domain setup initiated in the previous step.

1. Login as strongauth on the secondary SAKA server.

2. Start up two shell windows.

3. In Window2, change the /usr/local/strongauth/glassfish/domains/domain1/logs directory.

   shell> cd /usr/local/strongauth/glassfish/domains/domain1/logs

   or use the shell-alias aslg:

   shell> aslg

4. In Window2, run the tail -f command on the server.log file so you can watch the output of the server application as it scrolls by.

   shell> tail -f server.log

   or use the shell-alias tsl:

   shell> tsl

5. In Window1, change directory to /usr/local/strongauth/bin.

   shell> cd ~/bin

6. In Window1, execute the Secondary-SAKA-Replication-Final.sh.

   shell> ./Secondary-SAKA-Replication-Final.sh

7. Follow the steps of the wizard, ensuring there are no errors in Window1 or Window2. If there are errors, contact StrongKey at support@strongkey.com and discontinue the new domain process.

8. In Window1, execute New-SKCE-Domain.sh to setup service credentials for the CEM. Specify the DID of this new domain and a password you would like to use to secure the CEM service credentials. These values must be the same as those supplied on the Primary SAKA server:

   shell> ./New-SKCE-Domain.sh <DID> <password>

9. Repeat steps 1–8 for all other Secondary SAKA servers in the cluster.

The new domain is now ready for configuration via DACTool. The DA must now choose to which domain to connect on the Systems panel. All administration functions described in this chapter continue to perform normally on the new domain.

Users

There are three types of users in every SED: administrative users (also called Domain Administrators or DAs), ping users, and normal users.

Domain Administrators

DAs always have administrative privileges within the SED, but with the exception of the first DA of an SED, they may or may not have encryption and decryption privileges over the data within an SED.

When a new SED is created—either at installation time or subsequently—each SED is created by default with a new DA username of administrator1. The password for this DA is chosen at creation time by the individual executing the domain creation wizard. This DA (administrator1) not only has administrative privileges over the new SED, but also cryptographic service privileges. Using the EncryptionService web services the primary DA can encrypt and decrypt any object within the SED over which they have administrative privileges.

To prevent DAs from having such encryption and decryption privileges over the SED while giving them administrative privileges, create additional DA credentials within the SED using the DACTool and restrict the new DAs' privileges. The credential of administrator1 should be locked away in a secure location so it cannot be used, except as a backup credential during disaster recovery.

Every DA must have a digital certificate with its corresponding EC keys to strongly authenticate to SAKA for executing administrative commands. The certificate and keys are typically stored on a USB flash drive so they may be portable and can be kept off the machines likely to be used by the DA.

NOTE: SAKA comes with five (5) color-coded USB flash drives; the yellow token is designated for the DA. Sites are free to use any flash drive, as long as they maintain control over its contents.

The SED's first DA keys and certificate are generated on this token during the creation of the new domain; subsequent DA keys and/or certificates can either be generated using DACTool or supplied to DACTool if they are generated/created using another tool (such as keytool, OpenSSL, Mozilla, etc.).

Pinguser

The pinguser is a special SAKA user with the username pinguser. This user has only a single—and extremely limited—privilege: to be able to decrypt the single first encrypted record in the encryption domain and report the plaintext data associated with it. This user exists to allow Operations staff to detect if the web service is fully operational at the application layer without having access to any of the plaintext sensitive data in the encryption domain.

The first encrypted record in any encryption domain on the appliance is something called the well-known-PAN. In SAKA version 1.0 it is a test record containing the first ten prime numbers followed by a zero: 1235711131719230. In SAKA 2.0 each node of the cluster has its own default well-known PAN: 1111000000001111 for server ID #1, 2222000000002222 on server ID #2, 3333000000003333 on server ID #3, and so on. These well-known PANs are created by the New Domain Wizard when a new encryption domain is created. Since this is the first transaction sent to the new domain on the appliance—assuming the default configuration and values are being used—the web service returns the well-known token 1000000000000001 on server ID #1, 2000000000000001 on server ID #2, and so on.

NOTE: SAKA 2.0 provides the ability to return tokens that conform to the Luhn algorithm (https://en.wikipedia.org/wiki/Luhn_algorithm). In this case, the tokens will be discontinuous; please see 14—KAM Configuration, Section 2 for details.

The username (pinguser) and the tokens requested for decryption within each encryption domain (1000000000000001, 2000000000000001, etc.) are hard-coded into the SAKA application. Hence, when creating the pinguser credential using DACTool, the username must precisely state pinguser. Each encryption domain is expected to have only one such pinguser credential.

Normal Users

Normal users are those who only have encryption, decryption, delete and search privileges—or a combination of these privileges.

Normal users are created and defined the same way as DAs. However, a site has the choice of defining their normal users in one of three locations:

1. The internal SAKA database—in which case all users and their privileges are local to the SAKA server and are managed using DACTool.

2. Microsoft's Active Directory (AD)—in which case all normal users are defined and managed in AD using Microsoft-provided tools (see 14—KAM Configuration, Section 3.1 in this manual); however, all DAs are defined and managed in the internal SAKA database.

3. Any other Lightweight Directory Access Protocol (LDAP)-based directory server—in which case all normal users are defined and managed in the LDAP directory using the directory-provided tools (see Integrating with Another Directory Server—an open-source LDAP directory server—in Chapter 14 of this manual); however, all DAs are defined and managed within the internal SAKA database.

It is also possible to configure SAKA to use two mechanisms to authenticate and authorize cryptographic service requesters—the local database and either AD or another LDAP directory server. SAKA must be configured with both options and told which repository to look up first when verifying a requester's credential for supplying cryptographic services.

NOTE: It is not possible to configure SAKA to use AD and another LDAP directory simultaneously for verifying credentials or to use all three mechanisms to verify credentials—the internal database, AD, and another LDAP directory.

Selecting the Users icon on the DACTool toolbar, the side-bar provides two options: to add a new user and to view existing users within the internal SAKA database. SAKA cannot show SAKA users defined in Microsoft's AD or another LDAP directory server.

Add New User

Adding a new normal user to the SAKA internal database requires creating a unique username for the user, assigning a password to them, and assigning either the encryption, decryption, deletion, search or a combination of these privileges to the user. When creating the pinguser, you must assign it only the decryption privilege.

Adding a Domain Administrator requires creating a unique username for the DA, assigning a password to the DA, assigning them the SAKA DA privilege and specifying the digital certificate of the new DA so their digital signature can be verified for authentication and administrative actions.

NOTE: It is recommended for security reasons, that with the exception of the first Domain Administrator—which is created as part of the SAKA setup—that DAs not be assigned any cryptographic privileges to encrypt, decrypt or delete sensitive data. This allows separate administrative privileges from cryptographic privileges for control purposes.

After additional DAs have been created, the first DA's credential may be locked up and maintained—with its PIN in a sealed, tamper-evident envelope—as a safety measure in a remote location: either a bank safe or in the custody of a non-technical custodian.

To add a new user to SAKA, click Add New User on the side-panel or Users → Add User on the menu. The following panel displays, allowing addition of a new user—DA or Normal—to the internal SAKA database.

Currently connected to SAKA	The SAKA URL to which DACTool is currently connected.
Domain Identifier (DID)	The unique identifier of the encryption domain to which DACTool is currently connected.
Username	The username of the new user who is being granted privileges to this SED. While the system can use any username, it is better to use some standard convention to make management easier. Here are a few suggestions: If the user is a new DA, then use the username administrator followed by a numeral indicating the number of the DA within this SED. The first DA for an SED always has the username administrator1, so the next one should be called administrator2, and so on. If the user is the ping user, the username must be pinguser. If the username is for an application, then it is recommended to use the terms encryptonly-, decryptonly-, or encryptdecrypt- as prefixes to the application's abbreviation to identify the authorization of the username. For example, if the application is a point-of-sale application, a username with only encryption privileges might be called encryptonly-pos01 for the first such username. If a username already exists in the SAKA database, an error message will be returned indicating a duplicate value already exists.
Password	A password for the new user. The password must be a minimum of 8 characters with a combination of alphabet, numerals, and at least one special character.
Again	A field for repeating the new user's password to verify it.
Encryption Authorized	These radio buttons determine whether the new user is authorized to request encryption web services. By default it is set to Yes. However, it can be changed to No, if desired.
Decryption Authorized	This radio button group determines whether the new user is authorized to request decryption web services. By default it is No. However, it can be changed to Yes, if desired.
Deletion Authorized	This radio button group determines whether the new user is authorized to request deletion web services. By default it is set to No. However, it can be changed to Yes, if desired.
Search Authorized	This radio button group determines whether the new user is authorized to request search web services. By default it is set to No. However, it can be changed to Yes, if desired.
Relay Authorized	This radio button group determines whether the new user is authorized to request relay web services. By default it is set to No. However, it can be changed to Yes, if desired.
SAKA Domain Administrator?	This radio button group determines whether the new user is to be designated as a DA for this SED. By default, it is No. If the choice is set to Yes, three other radio buttons become enabled.
Generate Keystore	This radio button indicates that DACTool must generate a new EC cryptographic key pair for the new DA, and also must create a digital certificate signed by the Signing Key of this SED. If this radio button is selected, the Keystore field becomes enabled to specify the location of the BCFKS keystore.
Paste CSR	This radio button indicates that DACTool must accept a Certificate Signing Request (CSR) generated elsewhere for the new DA, and also must create a digital certificate signed by the Signing Key of this SED. No cryptographic keys are generated by DACTool for this option. If this radio button is selected, the Certificate Signing Request field is enabled to accept the CSR text.
Paste Signing Certificate	This radio button indicates that DACTool must accept a digital certificate issued elsewhere for the new DA. No keys are generated and no certificate is issued out of DACTool for this option. If this radio button is selected, the Signing Certificate (PEM) field becomes enabled to accept the digital certificate text.
Keystore	If the Generate Keystore radio button is selected for a new DA's credential, this field must specify the location where the BCFKS keystore will be created by DACTool with the new DA's cryptographic key pair and digital certificate. Only the directory of the keystore must be provided. DACTool automatically creates a unique B filename for the new DA. The Browse button may be used to locate the directory where the new keystore must be created.
Certificate Signing Request	If the Paste CSR radio button is selected for a new DA's credential, this field must specify the Privacy Enhanced Mail (PEM)-encoded certificate signing request for the new DA.
Signing Certificate (PEM)	If the Signing Certificate (PEM) radio button is chosen for a new DA credential, this field must specify the PEM-encoded digital certificate for the new DA.
Cancel	Cancels the operation and returns to the Home panel.
Reset	Resets the form to default values.
Save	Disabled by default. If all appropriate fields are filled in on the form, the button becomes enabled. Selecting it writes the new credential to the internal database.

Adding a new user is as simple as supplying the parameters to the fields in the form and selecting the Save button. DACTool determines if the two passwords typed in are identical and match the rules for passwords—use the Enter key on your keyboard to activate the logic—it doesn't work when you use the Tab key or the mouse pointer to move from field to field.

The following screen shows a successfully added new user:

When adding a new DA to SAKA, select the Yes radio button to the SAKA Domain Administrator? Option. When you do so, the grayed-out radio buttons on the right side of the form become active.

Unless you are familiar with public key cryptography or have a Public Key Infrastructure (PKI) in your environment, select Generate Keystore. This option allows creation of a new 256-bit EC key pair and digital certificate (issued by SAKA), and save them in a Java Keystore file at a custom location.

When the Generate Keystore radio button is selected, the Keystore text field and the Browse button become active. Either specify the full path and filename of the new keystore in the text field or, using the Browse button, select a location and then specify the keystore filename. Use a format that identifies the DID and the DA's username in the filename, such as 1-administrator2.bcfks or 3-johndoe.bcfks, where the numeral represents the DID, and the name represents the DA's username. The .bcfks file extension indicates that this is a BCFKS file containing the new credentials of the DA.

It is also recommended that, for security reasons, DAs should NOT have any privileges to perform any cryptographic functions such as encrypt, decrypt, etc. They should only be permitted to perform administrative functions such as adding/removing users, changing passwords, configuring the appliance, etc.

View Users

Selecting Users → View Users on the menu or the View Users item on the side panel brings up the following panel. This form contains several filters for searching the internal database for existing users.

Currently connected to SAKA	The URL of the SAKA to which DACTool is currently connected.
Currently connected to Domain	The unique identifier of the encryption domain to which DACTool is currently connected.
Retrieve which groups of users?	Specifies the filters on which to search the internal SAKA database. All Users (including Administrators) Administrators Only Users authorized for Encryption Users authorized for Decryption Users authorized for Deletion Users authorized for Search Users authorized for Encryption and Decryption Users authorized for Encryption, Decryption, and Deletion Users authorized for Encryption, Decryption, Deletion, and Search Users not authorized for any operation: Useful to search for sers who might not need to be in the internal database Specific User: Search for a specific username—the text field next to the radio button becomes enabled when it is selected. The username must match exactly for this choice to work. Like Username: Specify SQL-like queries where only part of the username is provided with a % symbol as a wild card for matches. For example, search for jo% would result in successful matches for john, joe, jonas, jo-ellen, etc. It is also possible to specify the wild card in the middle or towards the end of the search parameter. The text field next to this radio button becomes enabled when it is selected.
Cancel	Cancels the operation and returns to the Home panel.
Retrieve	Disabled by default, but if an appropriate radio button is selected (and text-fields are filled in where necessary), this button becomes enabled. When selected, it submits the query to SAKA to retrieve the users, if any are found.

Clicking Retrieve results in a list similar to the following figure. A description of the fields follows.

#	Serial number of the record.
Username	Name of the user in alphabetical order.
Encrypt?	A green check mark indicates that the user is authorized to request encryption web services from SAKA; a blank in this column indicates that the user does not have this privilege.
Decrypt?	A green check mark indicates that the user is authorized to request decryption web services from SAKA; a blank in this column indicates that the user does not have this privilege.
Delete?	A green check mark indicates that the user is authorized to request deletion web services from SAKA; a blank in this column indicates that the user does not have this privilege.
Relay?	A green check mark indicates that the user is authorized to request relay web services from SAKA; a blank in this column indicates that the user does not have this privilege.
Search?	A green check mark indicates that the user is authorized to request search web services from SAKA; a blank in this column indicates that the user does not have this privilege.
KMO?	A green check mark indicates that the user is authorize to request web services which require KMO privileges from the SAKA; a blank in this column indicates that the user does not have this privilege.
KMA?	A green check mark indicates that the user is authorize to request web services which require KMA privileges from the SAKA; a blank in this column indicates that the user does not have this privilege.
KMC?	A green check mark indicates that the user is authorize to request web services which require KMC privileges from the SAKA; a blank in this column indicates that the user does not have this privilege.
Administrator?	A yellow check mark indicates that the user is a Domain Administrator, authorized to administer this SED; a blank in this column indicates that the user does not have this privilege.
HMAC Key	Every user's password is processed with a symmetric encryption key to create a hashed message authentication code (HMAC). This is a one-way cryptographic operation that cannot be reversed, but can be verified with the same password, key, and algorithm. This column indicates which specific key was used by SAKA to generate the user's HMAC.
Edit	Opens a dialog to edit user information.
Delete	Deletes a user's record.
Cancel	Cancels and returns to the Home panel.

The only exception to the display format shown above is if a Specific User is chosen. Since DACTool knows only one user will result, it opens the View/Edit user information dialog, as shown here:

Using this form, the password and encryption/decryption/deletion privileges of this user may be changed.

To change a user's password, just delete the obfuscated characters from the two fields and type the new password—using at least one alphabet character, one numeral, one special character, and a minimum of 8 characters.

The behavior of these fields is identical to that described in Section 11.1—Changing DA Passwords.

NOTE: It is not possible to change the privileges of administrator1 from this panel. Only his/her password can be changed by another DA. If a DA's password is changed on this screen, the DA must also change the password on their BCFKS keystore to match the password in the internal database.

When a list of users are displayed in the table in DACTool, selecting a user—except administrator1—enables the Edit and Delete buttons. Clicking Edit opens a dialog as if Specific User had been chosen. If the user is a DA, you can take away their administration privileges. However, you cannot give someone DA privileges on this panel; you must add them as a new user with DA privileges.

Deleting a User

Except for administrator1—selecting the Delete button allows permanent deletion of users from the internal database. However, only if the credential will never be needed again. Users may be temporarily disabled by taking away their encryption and decryption privileges and/or changing their password.

If you choose to delete a user, you will be presented with a confirmation dialog, such as the following:

Selecting Yes on this dialog will delete the user and update the visible records in the DACTool table.

Jobs

Scheduled Jobs

To open the Scheduled Jobs ialog, click Jobs → Scheduled Jobs on the menu or the Scheduled Jobs icon displays the following panel on DACTool:

The panel displays a table with the following columns They are:

JID	The Job Identifier.
Job name	The name of the job.
Frequency	How often the job runs: Daily, Weekly, or Monthly.
Next run at	Date and time the job will next launch.

SAKA includes five jobs that assist with different aspects of key management. Four of the five jobs can be scheduled to run at a fixed frequency, or executed just once on demand. One job can only be executed once, on demand, and cannot be scheduled for frequent execution. The jobs are:

1. Delete Encryption Requests—allows a site to delete encryption request records from the internal database—along with all related ciphertext (encrypted data)—at periodic intervals if policy and/or business processes require it. Once deleted, the plaintext (unencrypted data) is never available again. The job is disabled by default and must be enabled through its configuration parameter before it can be scheduled to run. If the job is disabled in the configuration section, scheduling it on this panel will not execute the job. A report is generated each time the job is executed and stored in the STRONGKEYLITE_HOME/log directory.

2. Add Pseudo-Numbers—this job allows a site to switch from HMAC tokens to Pseudo-Numbers (PSN) (also known as tokens). An HMAC is a unique value generated by SAKA in combination with a symmetric cryptographic key and an algorithm for a sensitive data item. The HMAC cannot be reversed to arrive at the original value, but can be verified—given the original value, the cryptographic key, and the algorithm—by regenerating the HMAC again and comparing the preserved HMAC with the regenerated one. While fixed in length, HMACs do not resemble data such as credit card numbers or social security numbers. SAKA can be configured to generate numerical tokens that resemble the original data—but are not harmful if disclosed. If a site began using HMACs, but chose to switch to tokens at some point, this job will generate unique tokens for all existing records in its internal database. As the job is executed, a report is generated and stored in the STRONGKEYLITE_HOME/log directory.

3. Rotate HMACs—this job allows a site to rotate HMAC keys and re-generate new HMACs for existing records in the internal database when the HMAC keys change. Some regulations—such as the PCI DSS—require that symmetric encryption keys be changed at least once a year. While SAKA allows minimized risk of key compromise by using a new symmetric encryption key as frequently as every day, the regulation nonetheless requires a key rotation. While the symmetric encryption key can change automatically at customizable intervals, the HMAC key is configured to be used for a full year before it is rotated. However, in order to ensure that the rollover of the HMAC key does not bog down SAKA performance, this job allows the site DA to run the job at a time that is convenient to the site. The key rolls over at midnight of the new calendar year, every year. It is strongly recommended that this job is executed fairly soon—within the first week of the new year—after the key rolls over, lest the system get too critical for this maintenance activity at a busier time of the month/year. When the job is executed, a report is generated and stored in the STRONGKEYLITE_HOME/log directory.

4. Rotate Symmetric Keys—this job allows a site to rotate symmetric encryption keys and re-encrypt sensitive data automatically without the interruption of cryptographic services for client applications. This job is configured to run by default, but it must be scheduled by a site once SAKA is installed. Depending on whether the site's key duration policy is Daily, Weekly, Monthly, or Annually, this job can be scheduled to execute at the same frequency to ensure that keys that are a year old are rotated (for PCI DSS compliance). Sites needing a more aggressive key rotation policy can configure a key rotation schedule appropriate to their needs.

5. Rotate Symmetric Keys Range—this job allows a site to rotate symmetric encryption keys and re-encrypt sensitive data for a range of records, instead of for all records that might meet the default filter (cryptographic keys that are a year old). If configured, the job runs automatically without interrupting cryptographic services for client applications.

This job is useful after the first time a site imports existing records into SAKA. As an example, if the site has 10 million records and they are all imported in one batch job, it is likely that all records will have been encrypted by a single or at most two symmetric data encryption keys (actual time will depend on whether the site has deployed the standard or the high performance machine). While this is very useful from a performance point of view (because there are only one or two keys to use for decryption), this not only becomes a security risk—the more ciphertext existing for a single key, the more useful information a cryptanalyst might gain towards deciphering data—but can be a performance sink during the annual key rotation mandated by PCI DSS: millions of records will have to get re-encrypted within the 24–48 hour period.

Instead, if the 10 million records were encrypted by 350 symmetric keys, at most 29,000 objects are encrypted by any given key, and the key rotation can be spread out over 350 days, ensuring that the re-encryption job finishes in 5–10 minutes each day.

Four buttons are visible on one side of the panel. While they may appear enabled upon first entry to this panel, some buttons become disabled when a specific job is selected from the list. These buttons are:

Schedule	Used to schedule a recurring job in SAKA. However, because the Add Pseudo-Numbers job is expected to be executed just once, the Schedule button never enables when this job is highlighted.
Run Once	Allows a site to execute a job on demand. While a job may have been scheduled to run at a particular frequency, a site may require the execution of a job on demand for business reasons.
Delete	Cancels a previously scheduled job.
Cancel	Returns to the DACTool Home page without doing anything.

Scheduling a Job

To schedule a job, select the job in the table. A message about what the job does displays itself in the status bar of the screen. If the Schedule button remains enabled, select the button. A scheduling form displays itself at the bottom of the panel for specifying how frequently you want the job to be executed—Once, Daily, Weekly, or Monthly—and when the first run of the job should be executed. The form is shown below:

Upon supplying the form values and clicking Save, a confirmation dialog displays.

To cancel the scheduling of this job, click No at this point and return back to the DACTool. Upon clicking Yes, the scheduling is submitted to the SAKA server. After completing the transaction, the table in DACTool is updated to reflect the newly scheduled job.

Canceling a Scheduled Job

To cancel a previously scheduled job, select from the table the job that was already scheduled, and the Delete button become enabled. Upon clicking the Delete button, you are presented with a dialog to confirm the deletion of the job schedule, as follows:

If you want to cancel the transaction, you can click No at this point and return back to DACTool. Upon clicking Yes, the cancellation is submitted to the SAKA server. After completing the transaction, the table in DACTool is updated.

Configuration

Selecting the Configuration icon on the DACTool toolbar displays a blank panel, but it provides two options on the side panel that are reflected in the main drop-down choices: View Mutable Configuration and View Immutable Configuration. Every editable configuration property—with default and permissible values—is described in Chapter 14.

This section of the manual discusses how to navigate this part of DACTool.

The Mutable Configuration can be modified to a site's policy or configuration.

To edit a Mutable Configuration property, perform the following steps:

1. Select the configuration item you want to modify. Click Edit.

2. The following dialog displays. The fields are described below.
   
   

   Domain ID	Domain Identifier for the SED.
   Property	The name of the property in question.
   Value	The value assigned to the property.
   Notes	User-defined comments of 512 characters or less.
   Hint	A description of the property.

   Modify the configuration value to your desired value.

3. Click OK to return to the Mutable Configuration screen. The configuration value will show your updated value.

4. Click Save to write the new configuration to the database. The new values go into effect immediately with no need to restart SAKA or the application server. The Reset, Edit, and Save buttons become disabled on a successful save operation. They become enabled again when a configuration parameter is selected or the Configuration panel is re-launched.

The Immutable Configuration cannot be modified via DACTool. It is available to view, but may not be modified, as doing so will prevent SAKA from working as designed. The Immutable Configuration screen appears similar to the Mutable Configuration, except the entire panel is grayed out so that none of the properties are modifiable. The only button option is Cancel, which takes you back to the DACTool Home page.

NOTE: Knowledgeable developers and systems administrators may realize that these are just Java properties and can be modified. Modifying an immutable property will void the warranty on the product and void the support contract.

KAM Key Migration Tool

During the SAKA domain creation process a key is created called the encryption domain Key (EDK). While everything else specific to a domain is automatically replicated, this key must be manually migrated to each appliance in the cluster for that appliance to encrypt and decrypt records in the domain. This key migration is ordinarily handled by the new domain creation process for all nodes in the cluster. There are, however, some cases where an EDK must be migrated after the domain creation process has taken place.

One such scenario is if a new appliance is being added to the cluster. During this process, the EDKs from each of the existing domains must be migrated to the TPM in the new appliance. Another potential scenario is if the motherboard is replaced on an existing appliance in the cluster; in this case, the appliance will lose its TPM and the EDKs will need to be remigrated to this appliance.

The new domain process uses a streamlined EDK migration wizard that only works for all the TPMs existing at the time of the domain creation. When an EDK must be migrated after the domain has already been created, it is done using the Key Migration (KM) Tool. KMTool is designed to take an EDK from any appliance and migrate it to another appliance in the cluster. KMTool uses a similar process to the wizards and provides the same degree of security and control as the wizards in the key migration process.

Prerequisites

KMTool enforces strict controls for the migration of an EDK. All three Key Custodians (KCs) and the Domain Administrator (DA) must provide their credentials to KMTool before an EDK can be exported from or imported to a SAKA.

Additionally, the design of KMTool requires it to be executed locally on the SAKA server. This means that the keystores for the KCs and DA must be accessible to the file system of the SAKA running KMTool. This can be done either by having all KCs and the DA physically available at the location of the SAKA or by copying the KC and DA keystore files over the network onto the SAKA server temporarily. Before copying keystores from a KC keystore, be sure to consult your company's security policy and get the proper approvals.

Besides the security requirement of running KMTool, the Migration Authority Storage Key (MASK) of the SAKA receiving the migrated EDK must be available. This file is created during the Secondary Setup Wizard process, which must be performed prior to using KMTool. Finally, the appliances involved in the migration must have already been activated using the Key Custodian SetPIN Tool.

If you are exporting a migration key, start KMTool on saka01—any SAKA that has the EDK. If you are importing a migration key, start KMTool on saka02—the SAKA that will be receiving the EDK. Execute the /usr/local/strongauth/bin/KMTool.sh shell script from a terminal window. This will display the following window:

Validating Credentials

The three Key Custodians and the Domain Administrator must now authenticate themselves to the appliance in the Validate Credentials panel of the KMTool. For each role—Key Custodian 1, Key Custodian 2, Key Custodian 3, and Domain Administrator—follow these steps:

1. Select the appropriate Custodian role from the drop-down menu.

2. If your role is the Domain Administrator, provide your Admin Username (the default administrator username is administrator1) and the DID of your domain.

3. If the KC is physically located in front of the appliance, the KC inserts their USB token into the appliance.

4. Click Browse and select the appropriate KC credential file—it will have a filename that matches their role.

5. The KC types in their password to the credential file in the Password field.

6. Click Verify to ensure that the password unlocks the credential file correctly. If the password is correct, a message will appear on the bottom of the tool, as shown here:
   

7. If the password verification is successful, click Validate to send the credential to the appliance for validation. If the process works correctly, a success message will appear on the bottom of the screen: “Successfully validated [role]'s credential on server.” Once the DA and all KCs have successfully validated their credentials, KMTool will unlock the second and third panels.

Migrating a Key from this Appliance

The second panel of KMTool is the Migrate a key from this appliance panel. This panel allows you to specify a MASK file from saka02 and create migration keyfile.

1. Complete the fields as described below.
   
   

   Test Token	A unique Pseudo-Number (Token) created on the Primary appliance, to be used for a decryption test on the new appliance. The standard “well-known token” is 9999000000000001 and was created during the installation wizard. This value is currently not used during the key migration process and can be safely left as default.
   Mask Location	Location of the MASK file of the saka02 appliance. In a production environment, this file is on the black flash drive but can also be found on saka02 in the /usr/local/strongauth/strongkeylite/etc directory.

2. When finished, click Migrate. This action generates a migration keyfile (in the same directory as saka02's MASK file) with a filename that has the following format:

   <source-appliance-FQDN>-<target-appliance-FQDN>-<domain Id>-migkey.xml

   ...where FQDN is the fully qualified domain name of the appliance. In this example, the filename is:

   saka01.strongauth.com-saka02.strongauth.com-1-migkey.xml

3. If the migration key is generated successfully, KMTool will produce the following message: “Migrated Encryption Domain #1's master-key to [target-appliance-FQDN].”

NOTE: Additional EDKs can be migrated from other domains before closing KMTool. To migrate another EDK, validate the DA from the extra domain (don't forget to change the DIDfield). After validating the domain, click Migrate again to generate another migration key for this extra domain. This process can be repeated for each other domain.

Import a Migrating Key to this Appliance

Once you have a migration key from saka01, that EDK can be imported into saka01. After starting KMTool on saka02 appliance, all Key Custodians and the Domain Administrator must validate their credentials with KMTool.

After all KCs and the DA are validated, the Import a migrating key to this appliance panel will be unlocked. This panel allows you to specify a migration keyfile from saka01 and import it into saka02:

Key File	The filename of the migrating key generated on the saka01 appliance.
Domain ID	The encryption domain identifier for which the key has to be migrated; this is automatically filled out by the tool.
Key UUID	The UUID created while generating the key; this is automatically filled out by the tool and helps verify the unique ID of the migrating EDK.

In the previous section, we created a migration key name saka01.strongauth.com-saka02.strongauth.com-1-migkey.xml. Yours will be named differently depending on the names of your appliances and to and from which domains you are migrating.

1. Browse to and select a keyfile.

2. After selecting the file, click Import to import this key into saka02. If the process works correctly, you will see a message indicating success: “Successfully imported migrating key to this SAKA.”

   NOTE: Additional EDKs can be imported from other domains before closing KMTool. To import another EDK, validate the DA from the extra domain (don't forget to change the DID field). After validating the domain, click Import again to import another migration key for this extra domain. This process can be repeated for each other domain.

   Click Exit to close KMTool.

This concludes the key migration process and you can exit KMTool. The saka02 appliance is now capable of decrypting objects encrypted by other appliances within the trusted cluster.

KAM KMS ConsoleTool

The SAKA has many web services for processing transaction using ANSI X-924.1 keys. But before those keys can be used, they must loaded into the appliance. SAKA supports two methods for loading Base Derivation Keys (BDKs)—one for temporary storage and one for persistent storage. Additionally, SAKA can store Local Terminal Master Keys (LTMKs), Terminal Master Keys (TMKs), and Terminal PIN Keys (TPKs) using persistent storage.

SAKA includes a client application—the Key Management Server Console Tool (KMSConsoleTool)—that allows KCs to load ANSI keys into temporary or permanent storage from remote locations. KCs just need a connection to SAKA from their computers and their Key Component and Key Check Value (KCV) from the ANSI Key.

While it is recommended that KC connections be controlled through an access control list of a router or switch to prevent denial-of-service attacks, the connection need not be secured for confidentiality since SAKA accepts KC commands and responses only over a secure transport protocol—Transport Layer Security.

The installation process of the SAKAs would have resulted in the KCs being given the KMSConsoleTool on some media that they would use to install on their computers. Since the KMSConsoleTool is a Java application, it can run on any platform where a Java Virtual Machine (JVM) is available. It is, however, necessary for the KCs to have a supported version of the JVM on their computer to use the tool. See Chapter 1 for the supported version of the JVM for your appliance.

On a Windows PC, the KCs would use a Command Tool script (a batch file) to start the KMSConsoleTool. On a Linux computer, this would be a shell script. The script file can be associated with an icon on the KC's desktop to make it convenient for the KC to use the tool.

When the KMSConsoleTool is started, it presents the following screen:

Complete the fields as described in the table below.

Load Key Component/Load BDK/Store ANSI X9241 Key	The KMS Console performs three main key management tasks: Loading key components into the SAKA Assembling a BDK from stored key components to load into SAKA Persisting ANSI X-924.1 keys permanently on the SAKA These radio buttons specify which task the KMSConsoleTool should perform.
Key Size	The size of the key to be stored in the SAKA.
Key Algorithm	The algorithm associated with the key being stored. When this stored key is referenced by other web service calls, this algorithm will be used exclusively with this key.
Key Type	The type of key that is being stored in the SAKA.
Key Name	A user-defined name to associate with this key or Key Component being loaded into the appliance. When loading multiple Key Components from a set, all Key Components must have the same key name.
Encrypted Key	The hex-encoded, wrapped ANSI key to be stored in the SAKA.
Key Component	The hex-encoded Key Component to be loaded into the appliance.
Show	Allows the user to view the Key Component being typed (normally hidden by default). This allows a Key Component custodian to check whether they have made any typos. Care must be taken to ensure only the Key Component custodian is able to view the plaintext Key Component.
Key Check Value	A hex-encoded string representation of a KCV. When loading a Key Component, this KCV belongs to that Key Component. When loading a BDK or storing an ANSI key, this KCV belongs to the assembled/decrypted key.
K	A numerical identifier for this Key Component in the set of Key Components.
N	The total amount of Key Components in this set.
Manufacturer	When loading a BDK, the manufacturer associated with this BDK.
Bank ID	A numeric identifier for with which bank this key is associated.
Terminal ID	An optional numerical identifier for with which terminal this key is associated.
Terminal Type	An optional string identifier for to which type of terminal this key belongs.
Notes	User-defined notes to be stored alongside the key.
Parent Token	The token identifier of the wrapping key used to encrypt this ANSI key.
DID	The unique encryption domain identifier.
Username	The username (service credential) within the encryption domain with the authorization to call this web service.
Password	The password of the username to authenticate the requeter's credential.
Webservice URL	Every SAKA listens to KMS commands at a specific URL. This is established at installation of the SAKA. The KC should specify this URL in this field. SAKA always uses the TLS protocol, so the URL must begin with https.
Reset	This button resets all values to the defaults on the tool's panel.
Exit	Exits the KMSConsoleTool.
Submit	Disabled by default. If all appropriate fields are filled in on the form, the button is enabled. Selecting it submits the activation command to KMS. Once completed, feedback is provided on whether the command succeeded.

Loading Key Components

Start by loading a set of Key Components into the appliance.

1. After starting the KMSConsoleTool, verify the Load Key Component radio button is selected.

2. Specify a Key Name between 1 and 128 alphanumeric characters long. This Key Name will be used to associate multiple Key Components with a specific key, but serves no further purpose once the assembled key is loaded.

3. Provide the first Key Component, its corrosponding Key Check Value, and set the K value to 1. If your key only has two components, change the N value to 2.

4. Fill in the requested SAKA user information (DID, Username, Password). The user must have Key Management Operator (KMO) privilege to authenticate to this web service.
   

5. After the required fields are filled, the Submit button becomes enabled. Click Submit. Results and corresponding returned messages are listed here:

   The Key Component could not be validated by the Key Check Value	Storage of KeyComponent FAILED: SKL-ERR-6000: Failed to validate key-component with KCV:40…
   The SAKA information is incorrect or has insufficient permissions	Client received SOAP fault from server: SKL-ERR-1029: Request failed...
   Success	Successfully loaded key component on server.

6. If the Key Component was successfully loaded, the next Key Component from this set should be loaded. Provide the second Key Component, its KCV, and set K to 2.

7. Click Submit. If the Key Component loaded, “Successfully loaded key component on server,” will appear on the bottom left.

8. If your key has three components, then a third Key Component must be loaded. Provide the third Key Component, its KCV, and set K to 3.

9. Click Submit. If the Key Component loaded, “Successfully loaded key component on server,” will appear on the bottom left.

Loading a BDK

Before a BDK can be loaded into SAKA, its Key Components must first be loaded. Check the Loading Key Components section for instructions on loading a Key Component.

1. After components for this BDK have been loaded, click the Load BDK radio button.

2. Provide the name of the key used when loading the components, the KCV of the assembled BDK, the manufacturer to associate with this BDK, and the necessary SAKA information (DID, Username, Password). The user must have Key Management Custodian (KMC) privilege in order to authenticate to this web service. The dialog changes to look as such:
   

3. When all required fields have been filled, the Submit button becomes enabled.

4. Click Submit. If creating and storing the BDK succeeded, the message appears, “Successfully loaded BDK on server.”

Storing ANSI X-924.1 Keys from Key Components

Before a BDK or LTMK can be stored on SAKA, its Key Components must first be loaded. Check the Loading Key Components section for instructions on loading a Key Component.

1. After the Key Components have been loaded, select Store ANSI X9241 Key mode.

2. Select the Key Algorithm and Key Type for this key. In the following example, we will be loading a Triple DES (TDES) LTMK.

3. Provide the name of the key used when loading the components, the KCV for the key that is to be stored, a Bank ID to associate with this key, and the necessary SAKA information (DID, Username, Password). The user must have KMC privilege and Encryption privilege in order to authenticate to this web service.

4. Optionally, supply a Terminal ID to associate with this key, a Terminal Type to associate with this key, and any Notes you want to associate with this key.

5. When all required fields have been filled, the Submit button becomes enabled.

6. Click Submit. If successful, a message appears: “Successfully stored ANSI X9241 Key.”

7. Record the token returned in the output. SAKA uses this value to identify this LTMK.

NOTE: If you do not record the value now, you will have to store the LTMK all over again to use it for later operations.

Storing ANSI X-924.1 Keys from Wrapped Keys

Once an LMTK is stored, it is possible to start storing TMKs under it. For more information on storing an LMTK, see the previous section. A wrapped TMK can be unwrapped and stored using the following steps:

1. After the LTMK has been stored, select the Store ANSI X9241 Key radio button.

2. Change the Key Algorithm and Key Type for this key. The following is an example of loading a TDES TMK.

3. Provide the wrapped TMK (hex-encoded) in the Encrypted Key field; the KCV for the TMK; the Bank ID to associate with the TMK, the token reference of the LTMK received when you previously stored the LTMK in the Parent Token field, and the necessary SAKA information (DID, Username, Password). The user must have KMC privilege, Decryption privilege, and Encryption privilege to authenticate to this web service.

4. Optionally, supply a Terminal ID to associate with this key, a Terminal Type to associate with this key, and any Notes to associate with this key.
   

5. When all required fields have been filled, the Submit button becomes enabled.

6. Click Submit. If successful, a message appears: “Successfully stored ANSI X9241 Key.”

7. Record the token returned in the output. SAKA uses this value to identify this LTMK.

NOTE: If you do not record the value now, you will have to store the LTMK all over again to use it for later operations.

Following the same steps used in this section, a TPK can be loaded under the TMK by selecting the TPK Key Type and replacing the Parent Token with the token returned when the TMK was successfully stored. The user privileges and all other mechanics remain the same between loading a TMK or TPK.

KAM Configuration

The SAKA software comes with many customizable properties that do not need to be changed for most sites. However, some properties must be customized for each site, and sites may want to customize some based on their security policies. The following table presents a list of all the properties used by this release of SAKA.

Configuration properties are divided into either Immutable or Mutable properties. Immutable properties, as their definition implies, may not be changed at any time as this will impact SAKA operations. Mutable properties, however, may be modified as needed to meet business, operational, technical, and/or security requirements.

NOTE: It must be emphasized that an immutable property value must never be modified, as this will break the SAKA application and void your support. There is also the danger of permanently corrupting your data if an immutable property is modified and the SAKA provides encryption and/or decryption services to client applications.

All SAKA server properties are bundled in the resources folder of the strongkeyliteEJB module in the SAKA application. This file provides the central configuration for the system. Properties used by client applications—such as the SAKA Domain Administration Console Tool (DACTool) or the SAKA Key Custodian SetPIN Tool applications—are bundled within the client applications and should not be modified at all.

SAKA server properties can be modified in one of two ways:

1. By modifying the properties file—strongkeylite-configuration.properties—in the STRONGKEYLITE_HOME/etc directory. Changes made to this file override the configuration properties bundled in the application module, and thus, apply to all encryption domains in SAKA. An editor (gedit, nano or vi) may be used to edit this file; the application server (or SAKA) must be restarted for the changed properties in this file to take effect.

2. By using the DACTool and modifying the configuration properties though the graphical console. Changes made in the DACTool are persisted in the SAKA internal database and apply only to the encryption domain where the modification is made. The application server or the SAKA does not require a restart for these changed properties to take effect. They are effective immediately after they are saved to the internal database.

Immutable Configuration

All properties are in the format key=value where the key is of the form strongkeylite.cfg.property.<some-property-name>.

Property	strongkeylite.cfg.maxlen.10charstring
Explanation	The size of a 10-character string within the application. As the name indicates, the string cannot be more than 10 characters.
Immutable Value	10
Property	strongkeylite.cfg.maxlen.1024charstring
Explanation	The size of a 1024-character string within the application. As the name indicates, the string cannot be more than 1024 characters.
Immutable Value	1024
Property	strongkeylite.cfg.maxlen.128charstring
Explanation	The size of a 128-character string within the application. As the name indicates, the string cannot be more than 128 characters.
Immutable Value	128
Property	strongkeylite.cfg.maxlen.12285charstring
Explanation	The size of a 12285-character string within the application. As the name indicates, the string cannot be more than 12285 characters.
Immutable Value	12285
Property	strongkeylite.cfg.maxlen.13336charstring
Explanation	The size of a 13336-character string within the application. As the name indicates, the string cannot be more than 13336 characters.
Immutable Value	13336
Property	strongkeylite.cfg.maxlen.16384charstring
Explanation	The size of a 16384-character string within the application. As the name indicates, the string cannot be more than 16384 characters.
Immutable Value	16384
Property	strongkeylite.cfg.maxlen.16charstring
Explanation	The size of a 16-character string within the application. As the name indicates, the string cannot be more than 16 characters.
Immutable Value	16
Property	strongkeylite.cfg.maxlen.17792charstring
Explanation	The size of a 17792-character string within the application. As the name indicates, the string cannot be more than 17792 characters.
Immutable Value	17792
Property	strongkeylite.cfg.maxlen.2048charstring
Explanation	The size of a 2048-character string within the application. As the name indicates, the string cannot be more than 2048 characters.
Immutable Value	2048
Property	strongkeylite.cfg.maxlen.2080charstring
Explanation	The size of a 2080-character string within the application. As the name indicates, the string cannot be more than 2080 characters.
Immutable Value	2080
Property	strongkeylite.cfg.maxlen.256charstring
Explanation	The size of a 256-character string within the application. As the name indicates, the string cannot be more than 256 characters.
Immutable Value	256
Property	strongkeylite.cfg.maxlen.32768charstring
Explanation	The size of a 32768-character string within the application. As the name indicates, the string cannot be more than 32768 characters.
Immutable Value	32768
Property	strongkeylite.cfg.maxlen.32charstring
Explanation	The size of a 32-character string within the application. As the name indicates, the string cannot be more than 32 characters.
Immutable Value	32
Property	strongkeylite.cfg.maxlen.4charstring
Explanation	The size of a 4-character string within the application. As the name indicates, the string cannot be more than 4characters.
Immutable Value	4
Property	strongkeylite.cfg.maxlen.4096charstring
Explanation	The size of a 4096-character string within the application. As the name indicates, the string cannot be more than 4096 characters.
Immutable Value	4096
Property	strongkeylite.cfg.maxlen.5charstring
Explanation	The size of a 5-character string within the application. As the name indicates, the string cannot be more than 5 characters.
Immutable Value	5
Property	strongkeylite.cfg.maxlen.512charstring
Explanation	The size of a 512-character string within the application. As the name indicates, the string cannot be more than 512 characters.
Immutable Value	512
Property	strongkeylite.cfg.maxlen.6charstring
Explanation	The size of a 6-character string within the application. As the name indicates, the string cannot be more than 6 characters.
Immutable Value	6
Property	strongkeylite.cfg.maxlen.64charstring
Explanation	The size of a 64-character string within the application. As the name indicates, the string cannot be more than 64 characters.
Immutable Value	64
Property	strongkeylite.cfg.maxlen.65535charstring
Explanation	The size of a 65535-character string within the application. As the name indicates, the string cannot be more than 65535 characters.
Immutable Value	65535
Property	strongkeylite.cfg.maxlen.7charstring
Explanation	The size of a 7-character string within the application. As the name indicates, the string cannot be more than 7 characters.
Immutable Value	7
Property	strongkeylite.cfg.maxlen.8charstring
Explanation	The size of an 8-character string within the application. As the name indicates, the string cannot be more than 8 characters.
Immutable Value	8
Property	strongkeylite.cfg.maxlen.8192charstring
Explanation	The size of an 8192-character string within the application. As the name indicates, the string cannot be more than 8192 characters.
Immutable Value	8192
Property	strongkeylite.cfg.maxlen.9charstring
Explanation	The size of a 9-character string within the application. As the name indicates, the string cannot be more than 9 characters.
Immutable Value	9
Property	strongkeylite.cfg.property.admincertdnprefixsigning
Explanation	The prefix of the DN of the signing digital certificate issued to the DA. The unique domain identifier of the encryption domain is appended to this prefix during the creation of the certificate. The DA's signing certificate is used by the SAKA DACTool application to authenticate the DA to the SAKA server for administrative actions.
Immutable Value	CN=SAKA Domain Administrator Signing Certificate, OU=Domain ID
Property	strongkeylite.cfg.property.batchrequests.rootdir
Explanation	All batch jobs must transfer their files to the appliance (using SFTP, SMB or NFS, etc.) before the web service request for the transaction may be sent to the appliance. This configuration property identifies the root directory of all subdirectories where each encryption domain will transfer XML files in and out, before and after the cryptographic batch job is executed. The default location is /usr/local/strongauth/batchrequests.
Immutable Value	/usr/local/strongauth/batchrequests
Property	strongkeylite.cfg.property.domaincertdnprefixencryption
Explanation	The prefix of the DN of the encryption digital certificate issued to the encryption domain. The unique domain identifier of the encryption domain is appended to this prefix during the creation of this certificate. The SAKA domain's encryption certificate keys are used to protect all symmetric keys within the domain.
Immutable Value	CN=SAKA Encryption Certificate, OU=Domain ID
Property	strongkeylite.cfg.property.domaincertdnprefixsigning
Explanation	The prefix of the DN of the signing digital certificate issued to the encryption domain. The unique domain identifier of the encryption domain is appended to this prefix during the creation of this certificate. The SAKA domain's signing certificate keys are used to sign all digital certificates issued by this encryption domain. In that sense, this signing key's certificate represents a “mini” Certificate Authority (CA) whose sole purpose is to issue certificates to resources within its encryption domain. This CA cannot be used for purposes outside SAKA.
Immutable Value	CN=SAKA Signing Certificate, OU=Domain ID
Property	strongkeylite.cfg.property.enckeyalgorithm
Explanation	The cryptographic algorithm used by the SAKA to perform symmetric encryption and decryption of sensitive data. The only algorithm currently supported by the SAKA is the Advanced Encryption Standard, or AES.
Immutable Value	AES
Property	strongkeylite.cfg.property.encprefix
Explanation	The prefix used to distinguish between cryptographic keys within an encryption domain. SAKA uses three types of symmetric keys: 1) for encryption; 2) for generating Hashed Message Authentication Codes (HMAC) of plaintext sensitive data; and 3) for generating HMACs of user passwords in the SAKA internal database. Each of these keys are labeled with a key prefix so they may be uniquely identified for their purpose.
Immutable Value	ENC-
Property	strongkeylite.cfg.property.encsuffix
Explanation	The suffix used to map keys within internal data-structures of the SAKA application.
Immutable Value	-ENC
Property	strongkeylite.cfg.property.hmacprefix
Explanation	The prefix used to distinguish cryptographic HMAC keys within an encryption domain. SAKA uses three types of symmetric keys: 1) for encryption; 2) for generating HMACs of plaintext sensitive data; and 3) for generating HMACs of user passwords in the SAKA internal database. Each of these keys are labeled with a key prefix so they may be uniquely identified for their purpose.
Immutable Value	HMAC-
Property	strongkeylite.cfg.property.jdbc.dbdriver
Explanation	The name of the Java Database Connectivity (JDBC) driver used by the key rotation modules to communicate with the database directly. While most of the SAKA uses Java Persistence API (JPA) to communicate with the database, the Rotate HMAC Keys and the Rotate Symmetric Keys jobs use JDBC to dramatically improve performance and minimize memory consumption.
Immutable Value	com.mysql.jdbc.Driver
Property	strongkeylite.cfg.property.jdbc.jndiname
Explanation	The Java Naming and Directory Interface (JNDI) name for the resource to access the MariaDB database.
Immutable Value	jdbc/strongkeylite
Property	strongkeylite.cfg.property.keyduration.hmac
Explanation	Cryptographic keys used by the web service application are changed frequently, based on the policy defined in this property. The policy for the HMAC key is to use a new key every year (annual).
Immutable Value	annual
Property	strongkeylite.cfg.property.keyduration.pwd
Explanation	Cryptographic keys used by the web service application are changed frequently, based on the policy defined in this property. The policy for the PWD key is to use a new key every year (annual).
Immutable Value	annual
Property	strongkeylite.cfg.property.keyuse.annualformat
Explanation	The suffix used to label cryptographic keys when symmetric cryptographic keys are used for an entire calendar year. This property value is concatenated with the key's prefix property to derive the unique label of a cryptographic key. For instance, an encryption key, used annually would have the label ENC-2010 in the calendar year 2010, while another symmetric key would have the label ENC-2011 in 2011. An HMAC key in 2010 would have the label HMAC-2010, etc.
Immutable Value	yyyy
Property	strongkeylite.cfg.property.keyuse.dailyformat
Explanation	The suffix used to label cryptographic keys when symmetric cryptographic keys are used for 24 hours. This property value is concatenated with the key's prefix property to derive the unique label of a cryptographic key. For instance, an encryption key, generated and used on the 1st day of January in 2010 would have the label ENC-01-JAN-2010, while a key generated and used on the 3rd day of March in 2010, would have the label ENC-03-MAR-2010. HMAC keys for the same dates would have the labels HMAC-01-JAN-2010 and HMAC-03-MAR-2010 respectively.
Immutable Value	dd-MMM-yyyy
Property	strongkeylite.cfg.property.keyuse.monthlyformat
Explanation	The suffix used to label cryptographic keys when symmetric cryptographic keys are used for one calendar month. This property value is concatenated with the key's prefix property to derive the unique label of a cryptographic key. For instance, an encryption key, used for the month of January in 2010 would have the label ENC-JAN-2010, while an HMAC key would have the label HMAC-JAN-2010.
Immutable Value	MMM-yyyy
Property	strongkeylite.cfg.property.keyuse.weeklyformat
Explanation	The suffix used to label cryptographic keys when symmetric cryptographic keys are used for one week, starting from the second past midnight on a Sunday (Universal Coordinated Time) through the last second of the Saturday the same week. Since weeks do not have names, the week is indicated by the numeric value of the week—the first week of a year is 1, while the last week of the calendar year would be 52. This property value is concatenated with the prefix property to arrive at the unique label of a cryptographic key. For instance, an encryption key, generated and used on January 5th, 2010 would have the label ENC-1-2010, while an HMAC key would have the label HMAC-1-2010.
Immutable Value	w-yyyy
Property	strongkeylite.cfg.property.ldapctxfactory
Explanation	The Java class used to create a Lightweight Directory Access Protocol (LDAP) context for querying an LDAP-based Directory server.
Immutable Value	com.sun.jndi.ldap.LdapCtxFactory
Property	strongkeylite.cfg.property.noncesigningalgorithmhsm
Explanation	The cryptographic algorithm used by application tools to digitally sign nonces for authentication, when an HSM is used as the cryptographic hardware module in the SAKA server.
Immutable Value	SHA256withECDSA
Property	strongkeylite.cfg.property.pwdprefix
Explanation	The prefix used to distinguish cryptographic HMAC keys used for generating HMACs of user passwords, within an encryption domain. SAKA uses three types of symmetric keys: 1) for encryption; 2) for generating HMACs of plaintext sensitive data; and 3) for generating HMACs of user passwords in the SAKA internal database. Each of these keys are labeled with a key prefix so they may be uniquely identified for their purpose.
Immutable Value	PWD-
Property	strongkeylite.cfg.property.sklesxsdnsurl
Explanation	SAKA converts XML files to Java objects and vice-versa. This URL defines the current XML Schema Definition (XSD) in use by the appliance. The current URL for this version of SAKA is: http://strongkeylite.strongauth.com/SKLES201009
Immutable Value	http://strongkeylite.strongauth.com/SKLES201009
Property	strongkeylite.cfg.property.strongkeylitehome
Explanation	The location on the SAKA file system where SAKA software components are installed.
Immutable Value	/usr/local/strongauth/strongkeylite