C H A P T E R 5 |
![]() |
Note - The financial services features described in this chapter are supported for the Oracle Solaris OS on both SPARC and x86 platforms. These features are not currently supported for the Linux OS. |
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. The following sections are included:
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.
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 interpretation is handled by the financial services library. A high-level overview of the financial services components is depicted in FIGURE 5-1:
FIGURE 5-1 Financial Services High-Level Architecture
Three core components comprise the Sun Crypto Accelerator 6000 board financial services functionality:
These core components are described in the following sections.
This section describes the functions used to initialize the financial services library.
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:
TABLE 5-1 lists the parameters for the fs_lib_open() function.
TABLE 5-2 lists the return values for the fs_lib_open() function.
Successfully initialized, desired token found, and support for financial services verified |
|
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:
TABLE 5-3 lists the parameters for the fs_lib_close() function.
Financial services library handle returned from the fs_lib_open function |
TABLE 5-4 lists the return values for the fs_lib_close() function.
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:
TABLE 5-5 lists the parameters for the fs_session_open() function.
TABLE 5-6 lists the return values for the fs_session_open() function.
Once a user has completed financial operations, a user 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:
TABLE 5-7 lists the parameters for the fs_session_close() function.
TABLE 5-8 lists the return values for the fs_session_close() function.
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.
To meet the strict key management requirements of financial institutions, the Sun Crypto Accelerator 6000 board adheres to the following essential financial key management principles.
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 the keys use for specific operations only.
The following types of financial keys are supported:
The Sun Crypto Accelerator 6000 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.
Encrypts other keys for key exchange operations. The KEKs are entered into the board in component form with the direct input device.
Encrypts PINs. There are two types of supported PEKs:
The following key form requirements are enforced by the board.
For security unique security officers enter the MFK and KEKs directly into the board with the direct input device connected to the board’s serial port. This extra security step is required to meet the following key management requirements:
|
The MFK is the only financial services key maintained on the board. This key never leaves the board.
Several security officers enter the MFK as a series of key components that combine to make the MFK. Since a different security officer enters each component, no single user knows the MFK.
Each security officer entering a component of the MFK must follow these steps:
1. Connect the direct input device to the board’s serial port.
|
Once the MFK components are loaded, a valid security officer must enable the direct input device.
|
A security officer also enters the KEKs 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, which prevents any 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.
|
Financial applications require their keys be encrypted using the MFK. Thus, changing the MFK is a complex process.
2. Use the fs_translate_key() function to request that all of their keys be reencrypted using the new MFK.
The board must maintain the old MFK until this process is complete.
3. Once this process is complete, a security officer can use the new MFK by typing the enable mfk command.
Financial applications require key management related functionality from the HSM. The following basic capabilities are required:
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:
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 5-9 lists the parameters for the fs_generate_key() function.
Buffer for the generated key, encrypted with the MFK or a derivative |
TABLE 5-10 lists the return values for the fs_generate_key() function.
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 5-11 lists the parameters for the fs_import_key() function.
KEK key shared with the peer node with which the im ported key was encrypted |
|
TABLE 5-12 lists the return values for the fs_import_key() function.
The oKey is filled in for this case if the key is successfully imported |
|
The board must allow users to move keys from one device to another. Additionally, the peer device might not be a Sun Crypto Accelerator 6000 board. The export key function enables this feature and allows users to export keys from the Sun Crypto Accelerator 6000 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 5-13 lists the parameters for the fs_export_key() function.
Key shared with the peer node with which the exported key is encrypted |
|
TABLE 5-14 lists the return values for the fs_export_key() function.
The oKey is filled in for this case if key successfully exported |
|
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:
TABLE 5-15 lists the parameters for the fs_translate_key() function.
TABLE 5-16 lists the return values for the fs_translate_key() function.
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:
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 5-17 lists the parameters for the fs_retrieve_object() function.
TABLE 5-18 lists the return values for the fs_retrieve_object() function.
An application can query the board for its current status. The following board status values are supported:
The syntax for the fs_status() function is as follows:
The parameter for the fs_status() function is as follows:
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.
The board supports ANSI/ISO Format 0 and ISO Format 1 PIN-blocks described in this section.
The ANSI/ISO Format 0 is an 8-byte block constructed with the combining of two 64-bit components: The cleartext PIN, and the cleartext account number field.
The cleartext PIN, represented in hexadecimal characters, appears as follows:
The cleartext PIN hexadecimal characters are defined in TABLE 5-19.
The cleartext account number field, represented in hexadecimal characters, appears as follows:
The cleartext account number field hexadecimal characters are defined in TABLE 5-20.
12 right most digits of the PAN represented as 4-bit binary numbers with values of 000 to 1001 (0 to 9) |
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:
The ISO-1 PIN-block format hexadecimal characters are defined in TABLE 5-21.
The Sun Crypto Accelerator 6000 board supports the Visa PIN Validation Value (PVV) and the IBM-3624 methods for calculating PINs.
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 the 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 following input is required for the IBM-3624 PIN calculation method:
The PAN consists of the right most 11 digits of the PAN, excluding the mod-10 check digit that must be used to generate the PVV. For example:
PAN |
PAN Digits Selected |
4839 1234 5678 9019 |
1234 5678 901 |
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.
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.
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 5-22 lists the parameters for the fs_pin_verify() function.
TABLE 5-23 lists the return values for the fs_pin_verify() function.
This function translates a PIN from one encryption key to another. This function occurs during 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 5-24 lists the parameters for the fs_pin_translate() function.
Input PEK used to encrypt the PIN - this key is encrypted with the MFK |
|
TABLE 5-25 lists the return values for the fs_pin_translate() function.
The Sun Crypto Accelerator 6000 board supports credit card verification (CV) 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. The (CV) is a cryptographic checksum of the data stored on a magnetic card.
Credit card verification is performed during normal ATM and POS transactions to verify the magnetic card data. The following algorithms are supported:
The fs_card_verify() function provides credit card processing operations for the board’s financial services API. Verification for Visa, MasterCard, and American Express credit cards is supported.
The fs_card_verify() function requires a valid session handle as the first argument with the handle parameter. This session handle can be obtained through a call to fs_session_open(). All keys used by these functions must have been created using the financial services key management functions. See Key Management Functions.
The fs_card_verify() function enables an application to perform secure card verification operations. A card algorithm type must be provided in the alg argument. The allowable values for the card algorithm type are as follows:
The caller must also supply a card verification key (CVK) with the cvk parameter. This key must have been previously imported into the device with the fs_key_import() function. Additionally, personal account number (PAN) information and algorithm specific card data must be provided through the pan and data parameters. The following is an example of the fs_card_verify() function:
#include finsvcs.h fsReturn_t fs_card_verify(fsSessHandle_t handle, fsCardAlg_t alg, fsKey_t *cvk, fsPan_t *pan, fsCardData_t *data); |
Upon successful verification, the fs_card_verify() function returns the fsReturn_t value of fsOK. Otherwise, an error code is set in the fsReturn_t value. The following is a list of possible errors and their meanings:
The financial services functionality is disabled. Enabling financial services in a redundant hardware configuration might cause errors under heavy loads. In a single-card configuration, these errors do not occur.
|
Make the following change in the /kernel/drv/mca.conf file:
This section describes the financial services administrative features and commands.
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.
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.
To enable financial services features, an FSSO must place the board in one of two modes:
TABLE 5-26 describes the financial services administrative commands.
Note - Only FSSOs can initiate the commands listed in TABLE 5-26, and each command must be entered with a direct input device. |
Copyright © 2013, Oracle and/or its affiliates. All rights reserved.