Sun Crypto Accelerator 6000 Board User’s Guide for Version 1.0

The Sun Crypto Accelerator 6000 Board supports PIN and credit card related functionality, ensuring the security of sensitive customer data by performing the entire operation within the secure cryptographic boundary of the board. Specialized key management capabilities and a new user library (libfinsvcs.so) and associated application interfaces are provided to support this feature. Data types referenced in this chapter are defined in the /opt/SUNWsca/include/finsvcs.h header file, which is included in Appendix F.

This chapter describes the application programming interface (API) to enable developers to use this new functionality. Basic familiarity with PIN and credit card processing and the associated standards is assumed. Sections include:

• Financial Service Components Overview
• Enabling the Financial Services Feature
• Financial Services Library Initialization
• Financial Services Data Types
• Key Management Overview
• Key Management Functions
• PIN Processing Functions
• Credit Card Processing Overview
• Administering Financial Services

---

Financial Service Components Overview

The new financial service library uses the underlying PKCS#11 infrastructure to tunnel complex commands to the board resident firmware. Financial applications are not required to interpret the PKCS#11 interface, however, because this interprettation is handled by the financial services library. A high level overview of the financial services components is depicted in FIGURE 4-1:

FIGURE 4-1 Financial Services High Level Architecture

There are three core components that comprise the board financial services functionality:

• Key Management
• PIN processing
• Card processing

These core components are described in the following sections.

---

Enabling the Financial Services Feature

The financial services functionality is currently disabled by default due to an issue in the Oracle Solaris Cryptographic Framework. Enabling financial services in a redundant hardware configuration might cause errors under heavy loads due to this issue. In a single card configuration, these errors do not occur.

  Make the following change in the /kernel/drv/mca.conf file:

enable-finsvcs=1;

---

Financial Services Library Initialization

This section describes the functions used to initialize the financial services library.

Library Open Function fs_lib_open()

Financial services applications must issue the fs_lib_open() function to initialize the financial services library. This function locates the desired PKCS#11 provider and verifies that it supports the financial services mechanism. The fs_lib_open() function returns a handle that must be used in subsequent financial services library calls.

The syntax for the fs_lib_open() function is as follows:

fsLibHandle_t fs_lib_open(char *tokenName, fsReturn_t *err)

TABLE 4-1 lists the parameters for the fs_lib_open() function.

TABLE 4-2 lists the return values for the fs_lib_open() function.

Library Shutdown Function fs_lib_close()

Applications can close the financial services library services when the services are no longer required.

The syntax for the fs_lib_close() function is as follows:

fsReturn_t fs_lib_close(fsLibHandle_t handle)

TABLE 4-3 lists the parameters for the fs_lib_close() function.

TABLE 4-4 lists the return values for the fs_lib_close() function.

Session Establishment Function fs_session_open()

Users can establish multiple financial services sessions, thus allowing multithreaded access to the financial services capabilities. Sessions can be created only after you have initialized the financial services library with the fs_lib_open() function. A unique session handle is returned and must then be used for all financial service requests for that specific session.

The syntax for the fs_session_open() function is as follows:

fsSessHandle_t fs_session_open(fsLibHandle_t handle)

TABLE 4-5 lists the parameters for the fs_session_open() function.

TABLE 4-6 lists the return values for the fs_session_open() function.

Session Shutdown Function fs_session_close()

Once a user has completed financial operations, they can dissolve the session by issuing the fs_session_close() function. The session handle obtained from the fs_session_open() function must be used with this function.

The syntax for the fs_session_close() function is as follows:

fsReturn_t fs_session_close(fsSessHandle_t handle)

TABLE 4-7 lists the parameters for the fs_session_close() function.

TABLE 4-8 lists the return values for the fs_session_close() function.

---

Financial Services Data Types

The financial services API requires the use of new data types defined in the finsvcs.h header file. Appendix F provides the finsvcs.h header file.

---

Key Management Overview

To meet the strict key management requirements of financial institutions, the board adheres to the following essential financial key management principles.

Key Separation and Compartmentalization of Risk

Keys must be used for specifically defined functions only. This requirement limits potential damage from a key compromise. To meet this requirement, functional key type information is associated with each financial key. The board allows generating and importing the types of keys defined in the following list and enforces that they are used for specific operations only.

The following types of financial keys are supported:

• Master File Key (MFK)

The board is a dedicated hardware security module (HSM). The MFK never leaves the secure HSM and encrypts other operational keys when they leave the HSM. An MFK can be used only on the encrypting HSM. MFKs are entered into the board in component form with the direct input device.

• Key Encryption Key (KEK)

Encrypts other keys for key exchange operations. The KEKs are entered into the board in component form with the direct input device.

• PIN Encryption Key (PEK)

Encrypts PINs. There are two types of supported PEKs:

• Terminal PIN Key (TPK) - Encrypts PINs on the terminal side of the transaction (ATM, POS device).
• Zone Working Key (ZWK) - Encrypts PINS when transferring between different financial institutions.

• PIN Verification Key (PVK)

Verifies PIN operations.

• Card Verification Key (CVK)

Verifies card operations.

Allowed Key Forms

The following key form requirements are enforced by the board.

• Cleartext keys must stay within the board, with the exception of existing as at least two separate components, each under the control of a different security officer.
• When not stored in the board or when in component form, all keys must be enciphered with a key of equal or greater cryptographic strength.

Direct Key Loading

For security, the MFK and KEKs are entered directly into the board with the direct input device connected to the board’s serial port. These keys are entered in component form by unique security officers. This extra security step is required to meet the following key management requirements:

• Split knowledge - No single user can know the entire key.
• Dual control - The component and a valid user name and password are required to enter a key component.

Loading the MFK

The MFK is loaded with the direct input device. The MFK is entered as a series of key components that are combined to create the MFK. Each component is entered by a different security officer, preventing any single user from knowing the MFK. The MFK is the only financial services key maintained in the board. This key never leaves the board.

The command syntax for loading the MFK is as follows:

sca6000, so}> load mfk

Enabling the MFK

Once the MFK components are loaded, the MFK must be enabled with the direct input device by a valid security officer.

The command syntax for enabling the MFK is as follows:

sca6000, so}> enable mfk

Loading the KEKs

The KEKs are also entered with the the direct input device. However, unlike the MFK, these keys are extracted from the board by financial applications. The extracted keys are encrypted with the MFK. The KEKs are never in the clear. Similar to the MFK, KEKs are entered in component form preventing any single individual from knowing the actual KEK. A label must also be entered with the direct input device and is used programmatically by an application to retrieve the desired KEK.

The command syntax for loading the KEKs is as follows:

sca6000, so}> load kek

Change the MFK

Financial applications require their keys be encrypted using the MFK, thus changing the MFK is a complex process. After entering the new MFK, the applications must request that all of their keys be reencrypted using the new MFK with the fs_translate_key() function. The board must maintain the old MFK until this process is complete. Once this process is complete, a security officer can use the new MFK by typing the enable mfk command.

---

Key Management Functions

Financial applications require key management related functionality from the HSM. The following basic capabilities are required:

• Generate Key
• Import Key
• Export Key
• Translate Key (from the old MFK to the new MFK)
• Retrieve KEK

Generate Key Function fs_generate_key()

Applications generate different types of financial keys. DES keys are primarily used for these functions. Along with the key type, key usage information is required to limit when the key can be used. The following types of key uses are supported:

• PIN Encryption Keys
• Terminal PIN Key (TPK)
• Zone Working Key (ZWK)
• PIN Verification Key (PVK)
• Card Verification Key (CVK)

Once generated these keys are encrypted by the MFK and returned in the user provided buffer upon success.

The syntax for the fs_generate_key() function is as follows:

fsReturn_t fs_generate_key(fsSessHandle_t handle, fsKeyType_t type, fsKeyUsage_t usage, fsKey_t *key)

TABLE 4-9 lists the parameters for the fs_generate_key() function.

TABLE 4-10 lists the return values for the fs_generate_key() function.

Import Key Function fs_import_key()

To interoperate with peer nodes, the board must be able to import keys from these peers. Applications can import existing keys from peer nodes with the import function.

The syntax for the fs_import_key() function is as follows:

fsReturn_t fs_import_key(fsSessHandle _t handle, fsKeyUsage_t usage,  fsKey_t *KEK, fsKey917_t *iKey, fsKey_t *oKey, BOOLEAN useVariants)

TABLE 4-11 lists the parameters for the fs_import_key() function.

TABLE 4-12 lists the return values for the fs_import_key() function.

Export Key Function fs_export_key()

The board must allow users to move keys from one device to another. Additionally, the peer device might not be a board. The export key function enables this feature and allows users to export keys from the board. How the exported keys are transported to the peer is determined by the application developer.

The syntax for the fs_export_key() function is as follows:

fsReturn_t fs_export_key(fsSessHandle_t handle, fsKeyUsage_t usage, fsKey_t *KEK, fsKey_t *iKey, fsKey917_t *oKey, boolean_t useVariants);

TABLE 4-13 lists the parameters for the fs_export_key() function.

TABLE 4-14 lists the return values for the fs_export_key() function.

Translate Key Function fs_translate_key()

When the MFK is updated, users must convert all of their keys using the new MFK.

The syntax for the fs_translate_key() function is as follows:

fs_return_t fs_translate_key(fsSessHandle_t handle, fsKey_t *iKey, fsKey_t *oKey)

TABLE 4-15 lists the parameters for the fs_translate_key() function.

TABLE 4-16 lists the return values for the fs_translate_key() function.

Retrieve Object Function fs_retrieve_object()

Applications can retrieve select objects from the board. For security reasons, there are two types of objects that are input with the direct input device that can be retrieved by applications:

• KEKs
• Decimalization tables used in IBM-3624 PIN verification operations

When the object is entered, a unique label is also entered. This label is used to locate the object.

The syntax for the fs_retrieve_object() function is as follows:

fsReturn_t fs_retrieve_object(fsSessHandle_t handle, fsObjectType_t type, char *label, fsObjectData_t *obj)

TABLE 4-17 lists the parameters for the fs_retrieve_object() function.

TABLE 4-18 lists the return values for the fs_retrieve_object() function.

Status Function fs_status()

An application can query the board for its current status. The following board status values are supported:

• fsStateUninit - Device not initialized for financial services.
• fsStateNormalMode - Core functionality enabled. User's cannot import or export keys in this mode.
• fsStateSensitiveMode - Only key import and export requests allowed.
• fsStateMfkChange - Change of the MFK pending - only key translations done in this mode.

The syntax for the fs_status() function is as follows:

fsReturn_t fs_status(fsStatusBuff_t *status)

The parameter for the fs_status() function is as follows:

• status - Status buffer

---

PIN Processing Functions

The Sun Crypto Accelerator 6000 Board supports PIN verification and translation functionality. The interface ensures that sensitive customer data is exposed only within the secure HSM. This section describes the capabilities and interfaces supported.

PIN Block Formats

The board supports ANSI/ISO Format 0 and ISO Format 1 PIN-blocks described in this section.

ANSI/ISO Format 0

The ANSI/ISO Format 0 is an 8-byte block constructed with the combining of two 64-bit components: The clear text PIN, and the cleartext account number field.

The cleartext PIN, represented in hexadecimal characters, appears as follows:

C N P P P P P/F P/F P/F P/F P/F P/F P/F P/F F F 

The cleartext PIN hexadecimal characters are defined in TABLE 4-19.

The cleartext account number field, represented in hexadecimal characters, appears as follows:

C C C C A A A A A A A A A A A A

The cleartext account number field hexadecimal characters are defined in TABLE 4-20.

ISO Format 1

ISO Format 1 is the supported ISO-1 PIN block. This format supports a PIN length between 4 and 12 digits. PINs longer than 12 digits are truncated.

The ISO-1 PIN-block format, represented in hexadecimal characters, appears as follows:

1 L P P P P P/R P/R P/R P/R P/R P/R P/R P/R R R 

The ISO-1 PIN-block format hexadecimal characters are defined in TABLE 4-21.

PIN Calculation Methods

The Sun Crypto Accelerator 6000 Board supports the Visa PIN Validation Value (PVV) and the IBM-3624 methods for calculating PINs.

Visa PVV

PVV is a calculation and verification method specified by Visa. The credit card issuer or a designated agent provides a PIN Verification Service (PVS). This service compares the cardholder's PIN to a cryptographic transformation of the PIN.

The PVV method is a two step process:

1. When a PIN related credit card is issued, the issuer derives a 4-digit PVV. The PVV and the PIN Verification Key Index (PVKI) are either encoded on the credit card or registered in an online database. The stored PVV is called the reference PVV.

2. When a cardholder enters their PIN at the point of service, a transaction PVV is generated. The transaction PVV is compared to the reference PVV by the issuer or their agent. If the two PVVs match, the cardholder is authenticated.

For PVV, the following input is required:

• The customer's primary account number (PAN)
• The customer's PIN
• A one digit PVKI

IBM-3624

The following input is required for the IBM-3624 PIN calculation method:

• The customer’s PIN
• The PIN verification key (PVK) used in the PIN calculation algorithm and encrypted with the MFK
• Validation information for identifing the customer, this is typically the customer’s account number
• Check length, this is the number of PIN digits to check
• Reference offset data
• Decimalization table used to convert algorithm output into decimal digits

Personal Account Number (PAN)

The right most 11 digits of the PAN, excluding the mod-10 check digit that must be used to generate the PVV - for example:

PIN

The PIN associated with the PAN must be used to generate the PVV. Regardless of the length of the PIN (4 to 12 digits), only the left most four digits are used.

PVKI

The PVKI is a one digit value that identifies which PIN verification key (PVK) to use for the PVV calculation. The PVKI is a single digit value from 0 to 6. A PVKI of 0 indicates that the PIN cannot be verified through PVS.

PIN Verify Function fs_pin_verify()

The PIN verify operation is executed by the credit card issuer or their agent to authenticate a cardholder's transaction. The Sun Crypto Accelerator 6000 board supports two types of PIN verification, Visa PVV and IBM-3624. Additionally, the board supports two types of PIN block formats, ANSI/ISO Format 0 and ISO Format 1.

The syntax for the fs_pin_verify() function is as follows:

fsReturn_t fs_pin_verify(fsSessHandle_t handle, fsPinAlg_t alg, fsKey_t *PEK, fsKey_t *PVK,  fsPAN_t *PAN, fsPIN_t *iPIN, fsPinData_t *data)

TABLE 4-22 lists the parameters for the fs_pin_verify() function.

TABLE 4-23 lists the return values for the fs_pin_verify() function.

PIN Translate Function fs_pin_translate()

This function translates a PIN from one encryption key to another. This function is typically done at banking transactions. An example is when a cardholder uses their ATM card at a different bank than the one that issued the card. At the transaction, the PIN comes in encrypted using a PIN encryption key (PEK) specified by the point of service bank. To route the transaction to the credit card issuing bank, the transaction decrypts the PIN using the transaction originator’s PEK and then reencrypts it using the credit card issuing bank's PEK. The PIN block format can be requested to be translated (from ISO Format 0 to ISO Format 1 for example).

The syntax for the fs_pin_translate() function is as follows:

fsReturn_t fs_pin_translate(fsSessHandle_t handle, fsKey_t *iPEK, fsKey_t *oPEK, fsPIN_t *iPIN, fPIN_t *oPIN, fsPAN_t *PAN)

TABLE 4-24 lists the parameters for the fs_pin_verify() function.

TABLE 4-25 lists the return values for the fs_pin_verify() function.

---

Credit Card Processing Overview

The Sun Crypto Accelerator 6000 Board board supports credit card verification processing for the major types of credit cards, Visa, MasterCard, and American Express. The interface ensures that sensitive customer data is only exposed within the HSM. This section describes the capabilities and interfaces supported.

Credit Card Processing Functions

The card verification (CV) is a cryptographic checksum of the data stored on a magnetic card. The Sun Crypto Accelerator 6000 board supports CV operations for Visa, MasterCard, and American Express credit cards.

Credit Card Verification Methods

Credit card verification is performed during normal ATM and POS transactions to verify the magnetic card data. The following algorithms are supported:

• CVV - Visa
• CVC - MasterCard
• CSC - American Express

---

Administering Financial Services

This section describes the financial services administrative features and commands.

Financial Services Security Officers (FSSO)

FSSOs have specific financial services permissions. Each FSSO requires a unique security officer account created with the scamgr utility, described in Chapter 3. Only security officers can create and delete FSSO accounts. FSSO authentication is required to input keys and certain commands with the direct input device. These accounts can be configured to require single or multiple FSSO authentication for certain commands. To require multiple FSSOs per board to authenticate commands, a security officer must enable Multi-Admin mode, which is described in Multi-Admin Authentication.

Direct Input Device

A direct input device is required to load critical security parameters into the board. Only FSSOs can use the direct input device. See Direct Input Devices.

The direct input device is required to import the MFK and the KEKs. An FSSO must log in to the board with the direct input device and then initiate the key input command to import these keys.

Setting Financial Services Mode (fsmode)

To enable financial services features, an FSSO must place the board in one of two modes:

• Normal mode - Enables all functions except importing and exporting keys.
• Sensitive mode - Enables importing and exporting keys.

Administrative Commands

TABLE 4-26 describes the financial services administrative commands.

Sun Crypto Accelerator 6000 Board User’s Guide for Version 1.0

819-5536-12

Copyright © 2010, Oracle and/or its affiliates. All rights reserved.