Академический Документы
Профессиональный Документы
Культура Документы
Users Guide
November 2010
Notices
This publication and the accompanying software are proprietary to DataCard Corporation and are protected under U.S. patent and copyright laws as well as various international laws and treaties. This publication may not be copied, translated, sold, or otherwise transferred to a third party, in whole or in part, without the express written permission of DataCard Corporation. Information in this publication is subject to change without notice. DataCard assumes no responsibility for any errors that may appear in this publication. Companies, names, and data used in examples herein are fictitious. No association with any real company or person is intended and none should be inferred. This product includes software developed by the Apache Software Foundation (www.apache.org). Copyright 2000 The Apache Software Foundation. All rights reserved. This product includes software developed by the JDOM Project (www.jdom.org). This product includes Tagish JAAS Login Modules and is covered under the GNU Lesser General Public License, which can be found at www.gnu.org/ copyleft/lesser.html. This product includes software developed by IAIK of Graz University of Technology. Copyright (c) 2002 Graz University of Technology. All rights reserved. This product includes software developed by the jTDS Project (jtds.sourceforge.net) and is made available under the terms of the GNU Lesser General Public LIcense which can be found at www.gnu.org/copyleft/ lesser.html. This product includes software developed by the Eclipse Project (www.eclipse.org). This product includes software developed by Mozilla as part of the Rhino project. The Rhino code included with the Program includes no modifications and is provided under the terms of the Mozilla Public License version 1.1 or later (www.mozilla.org/MPL/MPL-1.1.html) and the GNU General Public License version 2.0 or later (www.gnu.org/licenses/gpl2.html).
ii
Trademark Acknowledgments
Affina and Maxsys are registered trademarks and Datacard is a registered trademark and service mark of DataCard Corporation in the United States and other countries. MasterCard is a registered trademark of MasterCard International Incorporated. Visa is a registered trademark of Visa International Service Association. Adobe and Reader are registered trademarks of Adobe Systems Incorporated. Crystal Reports is a trademark or registered trademark of Crystal Decisions, Inc. in the U.S. and/or other countries. Windows is a registered trademark of Microsoft Corporation. All other product names are the property of their respective owners.
Datacard Group 11111 Bren Road West Minnetonka, MN 55343-9015 Phone: 952-933-1223 Fax: 952-933-7971 www.datacard.com 2006-2010 DataCard Corporation. All rights reserved. iii
Contents
Chapter 1: System Overview _______________________________________________ 1
Data Flow______________________________________________________________________ 3 Affina DP Data Flow ________________________________________________________ 3 Affina OSI Data Flow________________________________________________________ 4
Chapter 2: Installation______________________________________________________ 5
Minimum PC Requirements _____________________________________________________ 5 Install Prerequisite Software _____________________________________________________ 6 Install Affina Software_________________________________________________________ 11 Upgrade Instructions _________________________________________________________ 12 Windows Firewall Exceptions __________________________________________________ 13 Configure Affina Software_____________________________________________________ 14 License the Software _________________________________________________________ 16 Affina Software Licensable Features _______________________________________ 16 Affina OSI Software ___________________________________________________ 17 Affina Data Processing Software _______________________________________ 18 License Administrator Components ________________________________________ 18 License Server ID ______________________________________________________ 18 Product Keys _________________________________________________________ 18 Activation Keys _______________________________________________________ 18 Default User Groups __________________________________________________________ 19 User Access Rights ___________________________________________________________ 19 Key Management System_________________________________________________ 19 Affina Configuration ______________________________________________________ 19 Configuration Management ______________________________________________ 20 Batch Applications _______________________________________________________ 20
InputSC __________________________________________________________________ InputMag ________________________________________________________________ Input Data Examples _________________________________________________________ Data Generation - Magnetic Stripe and Job OID Only ______________________ InputSC and InputMag Affina DP ____________________________________ InputSC Affina OSI __________________________________________________ Data Generation Magnetic Stripe and/or Smart Card Input Data _________ InputMag and InputSC Affina DP ____________________________________ InputSC Affina OSI __________________________________________________ Personalization - Smart Card Data _________________________________________ DGI Format ___________________________________________________________ TLV Output Data Key Format __________________________________________________ DES Key Example _________________________________________________________ RSA Key Example _________________________________________________________
32 32 32 33 33 33 33 34 34 36 36 37 38 38
DataSet Profile________________________________________________________ Job Profile ____________________________________________________________ Product Profile ________________________________________________________ ADT Associations __________________________________________________ Visa Personalization Assistant (VPA) Output File______________________ M/Chip4 or VSDC for MULTOS ALU Templates _______________________ Profile Associations _______________________________________________________ Scripting Language and Profile Specifications__________________________________ Import the Release and Sample Profiles _______________________________________ Configuration Manager Tasks _________________________________________________ General Tasks ____________________________________________________________ Profile Management Tasks ________________________________________________ Profile Creation Tasks _____________________________________________________ Application-specific Configuration Manager Tasks _____________________________
75 75 76 76 76 76 76 77 78 79 79 80 84 91
vi
vii
Revision Log Affina Data Preparation, Affina One Step Issuance, and Affina Profiles and Scripting Users Guide
Revision A B C D E F G Date April 2006 November 2006 February 2007 July 2007 December 2007 June 2009 November 2010 Description of Changes First release of this document. Added information for the 1.0.1 release. Added information for the 1.1 release. Added information for the 1.2 release. Added information for the 1.3 release. Added information for the 1.5 release. Added information for the 1.6 release. Incorporated Help topics.
Related Manuals
Manual Title Datacard Affina Personalization Manager MULTOS Issuance Software Data Format and Operation Datacard Syntera Customization Suite Installation and Configuration Guide Part Number 539112-003 539768-001)
viii
1
Used In Affina OSI Affina PS Affina DP Affina OSI Affina PS
Affina DP is a file-based batch process system that monitors an input directory for files containing cardholder records. Affina DP uses the magnetic stripe data in the records and data generation profiles to generate an output file containing smart card application data. Affina PS uses GlobalPlatform and Datacard-defined profiles to provide instructions for using an input file with smart card application data to personalize applications on smart cards. Affina OSI combines the data generation functionality of Affina DP and the personalization functionality of Affina PS. It uses an input file containing cardholder magnetic stripe data to create personalized smart cards in one step. Most Affina software components are used in multiple configurations.
Component Configuration Manager Description The user interface for viewing GlobalPlatform profiles and creating and editing Datacard profiles. Profiles create configurations for generating data and personalizing cards. The Java-based Global Platform scripting engine (Affina JVM). Runs data generation procedures defined in profiles. It is invoked from Batch Engine (using DTE.dll Affina DP software) or from a Datacard Syntera Customization Suite (CS) software application (Affina OSI software). It uses standard interfaces provided by the PKCS#11 for cryptographic functions. Provides the user interface through which you manage cryptographic keys.
Used In Affina OSI Affina PS Affina DP Affina OSI Affina PS Affina DP Affina DP
Crypto Provider
Accesses the HSM directly to implement requests from PKCS#11 components. It also provides information about HSM availability. Gathers necessary information from input data and invokes the Affina PS software interpreter for data generation. There are four Batch applications: Batch Import monitors a directory for new input files and automatically associates a production setup to change input data into output data. You can also import data files manually. Batch Engine performs the processing required to change input data into output data by calling Affina PS using the DTE.dll. Batch Administrator is the user interface through which you define how input data is changed to output data. Batch Tracking lets you monitor the processing of input files. You can also track individual records and view any errors that may occur. Manages the personalization process. It parses input data into records and sends required data to the various modules of the personalization system. For smart card operation, Production Control initiates the operation based on a setup and sends data necessary for personalization to Syntera CS. Provides the environment for developing and running server-based personalization applications. In Affina OSI, Syntera CS instantiates the personalization process for each card and calls the Syntera CS application, Affina Profiles and Scripting, or Datacard Affina MULTOS Issuance Software loader for data generation and personalization. A Syntera CS application for personalizing applications on MULTOS cards. In Affina OSI, it invokes Affina PS for generating an application load unit (ALU) and then loads the ALU onto the MULTOS card.
Batch Applications
Affina OSI
Affina OSI
In addition, Affina DP includes several Application profiles, each with sample data and setups that you can adapt to your unique environment.
System Overview
Data Flow
Data follows different paths depending on whether you are using Affina DP or Affina OSI.
generates the smart card data for each record as specified in the Application profile. The output file is ready to become an input file for a high-speed personalization system such as the Datacard Maxsys card issuance system.
System Overview
Chapter 2: Installation
This chapter gives information about installing and configuring Affina issuance software, licensing the software, and setting up user groups.
Minimum PC Requirements
It is strongly recommended that you purchase your PC from Datacard. However, if you choose to use your own PC, the following minimum requirements must be met: 2.0 GHz Pentium 4 processor 1 GB RAM Minimum screen resolution of 1024 x 768 A minimum of 20 GB free hard drive space is required for the installation of the program and initial database files, and running the program. You must assess the need for any additional hard drive capacity requirements based on how you will use the software.
The following table lists the database products and the operating systems that Affina issuance software supports.
Database Products SQL Server 2005 SQL Server 2005 Express SQL Server 2008 SQL Server 2008 Express Operating Systems Windows XP Professional Windows 7 Professional Windows Server 2003 Windows Server 2008 R2
Installation
Cryptographic software from your HSM manufacturer must be installed to perform certain functions not available through the Key Management System. Datacard recommends installing cryptographic software before Affina software. Install the .NET Framework .NET Framework 3.5 SP1 is required to install SQL Server 2008 R2 Express on Windows XP or Windows 2003. It is pre-installed on Windows 7 and Windows Server 2008 R2. 1. Insert the Affina issuance software installation CD into your CD drive. The installation program starts automatically. (If the installation program does not start, use Windows Explorer to browse to the root directory of the CD and double-click DEMO32.EXE.) 2. Click Install Prerequisite Software. 3. Click Microsoft .NET Framework. If the .NET Framework version 3 is already installed, you will see a message asking whether you want to repair or uninstall it. Select Repair and then Next or select Cancel. Install Windows Installer Windows Installer 4.5 is required to install SQL Server 2008 R2 Express on Windows XP or Windows 2003. It is pre-installed on Windows 7 and Windows Server 2008 R2. 1. Insert the Affina issuance software installation CD into your CD drive. The installation program starts automatically. (If the installation program does not start, use Windows Explorer to browse to the root directory of the CD and double-click DEMO32.EXE.) 2. Click Install Prerequisite Software. 3. Click Server 2008 R2 Express. 4. Click Windows Installer 4.5.
Install Windows PowerShell Windows PowerShell 1.0 is required to install SQL Server 2008 R2 Express on Windows XP or Windows 2003. It is pre-installed on Windows 7 and Windows Server 2008 R2. 1. Insert the Affina issuance software installation CD into your CD drive. The installation program starts automatically. (If the installation program does not start, use Windows Explorer to browse to the root directory of the CD and double-click DEMO32.EXE.) 2. Click Install Prerequisite Software. 3. Click Server 2008 R2 Express. 4. Click Windows PowerShell 1.0. Install SQL Server 2008 R2 Express 1. Insert the Affina issuance software installation CD into your CD drive. The installation program starts automatically. (If the installation program does not start, use Windows Explorer to browse to the root directory of the CD and double-click DEMO32.EXE.) 2. Click Install Prerequisite Software. 3. Click SQL Server 2008 R2 Express. 4. Click SQL Server 2008 R2 Express again. The installation begins. Install SQL Server 1. Insert the Affina issuance software installation CD into your CD drive. The installation program starts automatically. (If the installation program does not start, skip to step 3.) 2. Click Exit. 3. Using a text editor such as Notepad, open the file X:\Third Party Software\SQL Server\SQL Server 2008 R2\SQLServer 2008 R2 Unattended Install.bat (where X is the drive letter of the CD). 4. Follow the instructions in the echo statements at the beginning of the file. 5. Save the file to a temporary location on your hard drive. 6. Using Windows Explorer, double-click the file you just saved. 7. Delete the SQLServer Unattended Install.bat file from your hard drive.
Installation
Install Runtime Crystal Reports 11 Runtime Crystal Reports is required for running reports with the Batch Administrator application. 1. Insert the Affina issuance software installation CD into your CD drive. The installation program starts automatically. (If the installation program does not start, use Windows Explorer to browse to the root directory of the CD and double-click DEMO32.EXE.) 2. Click Install Prerequisite Software. 3. Click Crystal Reports Run-time. 4. Follow the prompts on the screen. SafeNet HSM Install the software before you install the coprocessor board in your computer. You will ignore an error message at the end of the software installation. It is not necessary to install any SafeNet software included with the SafeNet board. The SafeNet software required for Affina software is included on the Affina installation CD. If you are connecting remotely to the SafeNet crypto board it is not necessary to install any SafeNet software from the Affina installation CD on the client (remote) PC. Follow these steps to install software and hardware on the PC that is hosting the SafeNet coprocessor board: 1. Insert the Affina issuance software installation CD into your CD drive. The installation program starts automatically. (If the installation program does not start, use Windows Explorer to browse to the root directory of the CD and double-click DEMO32.EXE.) 2. Click Install Prerequisite Software. 3. Do one of the following: Choose SafeNet PCI HSM Access Provider to install the software on the PC where the SafeNet HSM will be installed. Choose SafeNet HSM Net Server if the crypto board will be shared across a network or you are using a 64-bit operating system.
4. Follow the prompts on the screen. When the installation is complete, the following message appears:
5. Click OK. (The software was successfully installed.) 6. Turn off the computer and install the coprocessor board, following the installation instructions provided with the coprocessor board. 7. Start the computer. The Found New Hardware wizard starts. 8. Select No, not this time on the Welcome page. 9. Select Install automatically on the next page. Follow the prompts on the screen to finish the wizard. Install the Datacard Software Licensing System The Datacard Software Licensing System must be installed to use Affina issuance software. Perform the following procedure to install the licensing system. It is highly recommended that the License Server be installed on a server on a network shared by all computers that require licenses. 1. Insert the Affina issuance software installation CD into the CD drive. The installation program starts automatically. (If the installation program does not start, use Windows Explorer to browse to the root directory of the CD and double-click DEMO32.EXE.) 2. Select Install Prerequisite Software. 3. Select License Server. 4. Follow the prompts, clicking Next and/or OK as necessary.
10
Installation
4. Select One Step Issuance, Data Preparation (Batch), or Custom (Full). If you select One Step Issuance or Data Preparation, follow the prompts to install the software. If you select Custom, you will be prompted to select the components that you want to install. Click the icon to the left of any component that you do not want to install and then click This feature will not be available. 5. Click Install. The program will install. 6. Click Finished. At the end of the installation, one of the following message boxes opens. Click OK to go to the Affina Configuration application (see page 14).
11
Upgrade Instructions
Perform the following procedure to upgrade from a previous version of Affina DP and Affina OSI software. 1. Uninstall Affina DP or Affina OSI and then restart the computer. 2. Install Affina DP or Affina OSI as described in Install Affina Software on page 11. 3. Delete any ADTs associated with the current Application profiles, the profiles themselves, and the associated Product profiles. Then, load the new Application profile(s), reload or recreate the ADT(s), and then reload or recreate the Product profile(s). If you do not want to run the Samples provided with Affina DP or update the Release Application profiles, no further action is necessary. 4. If prompted, restart the computer. 5. Load the new Release and Sample profiles and overwrite any existing profiles. See Import the Release and Sample Profiles on page 78.
12
Installation
If you have installed a SafeNet HSM in your system that is shared with other computers on your network, you will also need to create a firewall for the SafeNet HSM Net Server program:
Name etnetserver Description HSM Message Dispatcher Server Sample Path \SafeNet\Net Server\etnetserver.exe
13
Configure License Server If your License Server is not installed on the same computer as your Affina software, use the following steps to specify the License Servers location. 1. In the License Server area of the Affina Configuration dialog box, select On a remote computer with this IP address and enter the IP address of the License Server computer. 2. Click Test to verify the connection. 3. Click Save.
14
Installation
Configure Database To create the Affina database on the computer you are using: 1. In the Database area, click Local. The application will attempt to detect local SQL Server instances. 2. Select the Server name from the list. The application will attempt to connect to the SQL Server instance selected and a dialog box will indicate whether or not a database was found. Click OK. 3. If a connection could not be made, enter the SQL Server instance name and then click Connect. The application will attempt to connect to the SQL Server instance selected and a dialog box will indicate whether or not a database was found. Click OK. If a database was not found, click Create Database and then click Connect after the database has been created. 4. Click Apply at the bottom of the Affina Configuration dialog box. 5. Click OK at the bottom of the Affina Configuration dialog box to close it. To connect to a database on another computer on your network: 1. In the Database area, click Remote. The application will attempt to detect remote SQL Server instances. 2. Select the Server name from the list. The application will attempt to connect to the SQL Server instance selected and a dialog box will indicate whether or not a database was found. Click OK. 3. If a connection could not be made, enter your SQL Server instance name and then click Connect. The application will attempt to connect to the SQL Server instance selected and a dialog box will indicate whether or not a database was found. Click OK. 4. Click OK in the confirmation message. 5. Click Apply at the bottom of the Affina Configuration dialog box. 6. Click OK at the bottom of the Affina Configuration dialog box to close it.
15
Configure Hardware Security Modules 1. In the Hardware Security Modules area, click in the SafeNet Hostname(s) or IP Address(es) text box and do one or both of the following: A. To delete the name of the computer you are using (the default value), press BACKSPACE until the name is erased. B. To add a computer that contains a SafeNet HSM, press the space bar and then type either the computer name or the computers IP address. 2. Click Apply at the bottom of the Affina Configuration dialog box. 3. Click OK at the bottom of the Affina Configuration dialog box to close it. 4. Restart Object Communicator or Batch Production for your changes to take effect. If you are using Windows XP or Windows Server 2003 and the Datacard Syntera CS Communicator Controller service or Datacard Affina PM Object Communicator Controller service is running under the Local System account, you will need to restart the computer.
16
Installation
No more than (n) programming stations can use the data generation capability at the same time.
Key Management System and Configuration Manager Profiles and Scripting Software
None
Affina Profiles and Scripting Connection (APS) or Affina Profiles and Scripting Site License (GP)
One license (n) for each programming station connection or Unlimited number of programming station connections
No more than (n) smart cards can be personalized using Profiles and Scripting software at the same time.
and/or MULTOS Issuance Software MULTOS Issuance Connection (AMI) or MULTOS Issuance Site License (MULTOS) One license (n) for each programming station connection or Unlimited number of programming station connections No more than (n) smart cards can be personalized using MULTOS Issuance software at the same time.
17
Site License
License Server ID
The License Server ID is a unique ID tag derived from the PC that License Server is installed on. The License Server ID is generated using License Administrator.
Product Keys
A product key is a unique alphanumeric identifier of a feature license. When feature licenses are ordered, the product keys are printed on a label affixed to the envelope containing the installation CD and on a sheet of paper inside the envelope. Each Affina software licensable feature (see table above) requires one or more product keys. A single product key can be used on a single license server.
Activation Keys
Activation keys are the final piece required to activate your Affina software feature license(s). After the License Server ID is sent to Datacard and your license is verified, an activation key will be sent for each product key. Activation keys authenticate the product key for a particular license server. Affina software will
18
Installation
operate only when each feature license has a product key and corresponding activation key entered into License Administrator. You can use the Remote Product Activation utility to activate the licenses. See the Licence Administrator Help topic Using Remote Product Activation for more details.
Affina Configuration
Members of the ADP_Operator and ADP_Supervisor groups can view data and perform test functions. Members of the ADP_Administrator group have full access to all features.
19
Configuration Management
Members of the ADP_Operator group can view profiles. Members of the ADP_Supervisor group can view, import (but not replace), and export profiles. Members of the ADP_Administrator group have full access to all features.
Batch Applications
In the Batch applications the ADP_Administrator and ADP_Supervisor groups have access to all commands and the ADP_Operator group can run the Batch Engine and Batch Input applications. Use the procedure Review and change access to Affina DP Batch applications to grant access rights to your ADP_Operator group. Review and change access to Affina DP Batch applications Access to Affina DP Batch applications is controlled via the Batch Administrator module. 1. Log on to the computer with a user name that has ADP_Administrator user privileges and start the Affina Data Preparation Launcher (Start | Programs | Datacard | Affina Data Preparation & One Step| Affina Data Preparation Launcher). On the Launcher, click Batch Administration. 2. From the menu bar select System | Access Control.
20
Installation
3. Select the ADP group whose access you want to review, and then expand the listings for each module and menu as necessary. 4. Remove access by double-clicking on a module, menu, or command that has a green check mark next to it. Grant access by double-clicking on a module, menu, or command that has a red no symbol next to it. Removing or granting access affects that level and any subordinate levels.
21
22
Installation
In Datacard issuance systems, input data contains fields that will be used to personalize cards. Each field can be identified by a character or group of characters called a Start Code. For example, the $ character might be used to identify the Primary Account Number (PAN) that will be embossed on the card by the Emboss module, and the " character might identify the magnetic stripe data that will be encoded on the card by the Magnetic Stripe module. There is also often a six digit ASCII search code at the beginning of a record that identifies the record number in the input file, and a record separator, which may be up to seven bytes long, at the end of a record. The Data setup on Datacard issuance systems identifies the fields in the input data, and the Product or Card setup specifies which operations each module will execute on a card.
23
Here is the content of the sample input data file named 1_VSDC.dat:
000001$4247 7758 6985 7153)12/15#VSDC SAMPLE"%B4247775869857153^SAMPLE/ VSDC^1512201123456789012345678901234?;4247775869857153=1512 2011234567890123?#END#
Smart card applications such as Visa Smart Debit Credit (VSDC) and M/Chip 4 include data elements that are included in legacy magnetic stripe data fields. Therefore, Affina DP and Affina OSI use magnetic stripe data fields for data generation (Affina DP) and for data generation and personalization in one step (Affina OSI).
24
Data Format
25
* These fields together, in binary format, comprise Track 2 Equivalent data used in EMV tags.
EMV Tags
A consortium of the financial companies Europay, MasterCard, and Visa (together referred to as EMV) has defined a common set of standards for financial card issuance. EMV defines a format for smart card data that uses a Basic Encoding Rules Tag, Length, Value (BER-TLV) format. The EMV BER-TLV encoding rules can be found in EMV Integrated Circuit Card Specifications for Payment Systems Book 3 Application Specification Annex B, Rules for BER-TLV Data Objects. The Affina default parser extracts the following fields from the magnetic stripe data and creates TLV data for each data element using the Tags listed.
Name PAN Cardholder Name Service Code Tag 5A 5F20 5F30 Name Expiration Date Track 1 Discretionary Data Track 2 Equivalent Data Tag 5F24 9F1F 57
26
Data Format
27
Field MIC
Description Smart Card field start code Length of all smart card data as a decimal number (excluding this field). Optional; smart card module instructions Reset card; use 2-byte lengths Reset card; use 4-byte lengths Do not reset card; use 4-byte lengths Length of all of the following data. Optional; size of the application name. Optional; application name. Length of all of the following data.
Embedded Length
Format Identifier
Total Length Application Name Length Application Name Application Data Length
0008 AffinaPS
Application Data Job OID** PIX Variable ASCII 4 Bytes [2B0501] The OID of the job to be executed. Proprietary application identifier; the second part of the AID described on page 27. If the PIX is less than four bytes, it is padded with 00 bytes. Length of all of the following data. 424777FF Bank Identification Number. Padded with F if less than 4 bytes. Reserved. 00 for EMV TLV and FF for DGI TLV.
2 Bytes 4 Bytes
3 Bytes 1 Byte
000000 00
28
Data Format
Field
Name*
Description Version of the KEK to use for encrypting sensitive data. Length of all of the data under this applications PIX. Optional; to support legacy products. If present, the data that follows is wrapped in the tag DF. Conditional upon existence of DF tag. If a DF tag is present, this is the length of all of the following application data. Smart card data in TLV or DGI format.
Data Length
2 Bytes
Data
Variable
* Color coding in this column relates to samples that follow. Data is in hexadecimal encoding unless otherwise noted. This data is present only when using SCPM format. **Affina DP requires input data in SCPM format to generate this field. These bytes have a different meaning for MULTOS data using ALUs. See the MULTOS Data Format and Operation manual.
SCPM Format
SCPM format smart data includes the format identifier and application name. This example also includes the Job OID.
00000000 00000010 00000020 00000030 00000040 7B30 4166 3130 3530 0000 3030 6669 3430 315D 0000 3037 6E61 3138 1010 0001 3832 5053 3139 0000 02CE FFFF 02FC 3030 02DC 9F45 FFFA 5B32 4438 4247 02DA 0308 4230 3830 77FF C19F 0008 3630 3630 0000 3602 {0000782........ AffinaPS..[2B060 1040181900D88060 501]......BGw... .........E....6.
PIX Format
PIX format smart card data excludes the format identifier, application name, and Job OID. When using PIX format data on a Datacard issuance system or simulator, the smart card data must be concatenated to the Job OID using the Data Setup as described in One Step Personalization Setup on page 93.
00000000 7B30 3030 3037 3338 1010 0000 02DC 4247 {0000738......BG 00000010 77FF 0000 0000 0000 0001 02CE 500B 5649 w...........P.VI 00000020 5341 2043 5245 4449 549F 4502 DAC1 9F36 SA CREDIT.E....6
29
Description Adds a Start Code and an Embedded Length. Specifies the smart card module format identifier. Specifies the name of a personalization application. Adds a Job OID (must be entered without square brackets, as the brackets are added by the parser) Defines TLV Format; 00 for EMV TLV and any other value for DGI TLV. Wraps application data in Tag DF when set to any value other than 00. For support of legacy applications only. Sets the name of the Key Encryption Key (KEK) to use for encrypting sensitive data.
ASCII
AffinaPS
ASCII
HEX HEX
00 00
ASCII
KEK
* The name of the corresponding field in the Smart Card Data Format table is given in parentheses, if it differs from this parameter name. Must be used together to create SCPM format. Using this field will cause fields marked with to be generated using default values if not otherwise specified.
30
Data Format
PIX_DATA
HEX
31
InputSC
InputSC is used by: Affina DP for smart card data, Affina OSI for smart card data and magnetic stripe data, Affina PS for smart card data Affina DP or Affina OSI for smart card data and magnetic stripe data in smart card (TLV) format
InputSC must contain the OID of the Job profile in square brackets at the beginning of the InputSC field ([2B0601040181900D88060501]). In the case of Affina DP, the Job OID may be the only data that InputSC contains; for Affina OSI and Affina PS, InputSC will typically contain magnetic stripe data and/or smart card data in PIX or SCPM format. Magnetic stripe data in InputSC is detected by the presence of the characters %B immediately following the Job OID. If these characters are not found, the input data must be in smart card format or an error will be returned. Using Affina DP, smart card data is provided to the parser using the Production Setup Input Data Field inputSmartcard.
InputMag
InputMag is only available in Affina DP for magnetic stripe data. It is provided to the parser using the Production Setup Input Data Field inputMagstripe.
32
Data Format
33
69 18 1A
34
Data Format
85 71 53 45 2F 56 53 44 43
35
DGI Format
This example shows how data in DGI format is parsed. This data was generated using Affina DP in SCPM format with the USE_DGI parameter set to 0x01. Here is the first portion of the file including the first DGI in the data, 0D01, which contains the tags 9F58, 9F59, 9F53, and 9F54.
00000000 00000010 00000020 00000030 00000040 00000050 00000060 00000070 00000080 00000090 000000A0 000000B0 000000C0 000000D0 000000E0 000000F0 3030 2036 2356 3234 5341 3230 3435 3737 3132 3233 0F00 3036 3036 FF00 0103 1000 3030 3938 5344 3737 4D50 3131 3637 3735 3230 3F7B 0841 3031 3035 0000 9F59 0080 3031 3520 4320 3735 4C45 3233 3839 3836 3131 3030 6666 3034 3031 FF00 0107 0030 2434 3731 5341 3836 2F56 3435 3031 3938 3233 3030 696E 3031 5D10 0000 9F53 D6C2 3234 3533 4D50 3938 5344 3637 3233 3537 3435 3738 6150 3831 1000 0102 0105 891A 3720 2931 4C45 3537 435E 3839 343F 3135 3637 39FF 5303 3930 0002 D50D 9F54 E395 3737 322F 2225 3135 3135 3031 3B34 333D 3839 FFFF 035B 3044 E342 0115 0600 3C05 3538 3135 4234 335E 3132 3233 3234 3135 3031 FA03 3242 3838 4777 9F58 0000 FE6A 000001$4247 7758 6985 7153)12/15 #VSDC SAMPLE"%B4 247775869857153^ SAMPLE/VSDC^1512 2011234567890123 45678901234?;424 7775869857153=15 1220112345678901 23?{0000789..... ...AffinaPS..[2B 0601040181900D88 060501]......BGw ...............X ...Y...S...T.... .....0......<..j
Here is a portion of how the data is parsed, with InputSC truncated to show only the first 40 bytes. Notice that the TLV Format byte has a value of 0xFF, indicating DGI format. Only the first DGI in the input file, 0D01, is included here.
$inputSC 0000: 5B 0010: 44 0020: 42 0030: 15 0040: 00 . . . $inputMag 32 38 47 9F 00 42 38 77 58 00 30 30 FF 01 10 36 36 00 03 00 30 30 00 9F 00 31 35 00 59 80 30 30 FF 01 00 34 31 00 07 30 30 5D 00 9F D6 31 10 00 53 C2 38 10 01 01 89 31 00 02 05 1A 39 00 D5 9F E3 30 02 0D 54 95 30 E3 01 06 3C | | | | | [2B0601040181900 D88060501]...... BGw............. ..X...Y...S...T. ........0......<
$inputUser . . . No MagStripe data Parse DCC Smartcard data Application Pix : Bin : keyVerEx: keyVer : Tag[0x0D01] 0000: 9F 58 01 03 9F 0010: 00 00 10 00 00 . . . 0x10 0x42 0x00 0x00 10 47 00 00 00 00 77 00 FF 00 01
59 01 07 9F 53 01 05 9F 54 06 00 | .X...Y...S...T.. | .....
36
Data Format
Length of key or key component Key or key component data value Length of key check value Key check value (if present; that is, if key check value length is not 0x00)
37
38
Data Format
4
File Dumb Terminal
KMS GUI
HSM
Sensitive key management tasks must be performed in the presence of a Security Officer who is logged on to the HSM.
39
Roles
Cryptoki defines two token user types: Security Officer (SO) and User. An SO is repsonsible for initializing a token and can set some attributes on public objects that a User cannot. A User, on the other hand, can create Private objects which an SO cannot access, but only after the User has been authenticated and granted access to the token. Datacard has extended the Cryptoki user types to allow multiple individuals to share a role and also to allow setting a minimum number of users in that role to be required for authentication. For example, it is possible to create three Users for a token and require that two of them log on in order to access the token. Here are some differences between a User and an SO. User Can create, modify, and destroy Private objects Cannot set the Export Usage (except on a single-use Backup/Restore key) Cannot set the Trusted Attribute Can perform Administrative functions except Load Firmware Certificate
40
SO Can Log In to an uninitialized token Cannot access Private objects Can set the Export Usage Can set the Trusted Attribute Can Load a Firmware Certificate but not do other Administrative functions
Sessions A session provides a logical connection between an application and a token. A session is required to gain access to the tokens objects and functions. Token objects are objects that are stored on the token and are persistent. Objects may also be created during a session, and these session objects are destroyed when the session is closed. A session can be a read-only session or a read/write session. In a read-only session, token objects cannot be created, modified, or destroyed. In a read/write session, modifiable objects can be created, modified, and destroyed. Although Cryptoki defines a read/write public (non-authenticated) session, Datacards implementation does not allow read/write public sessions. In Datacards implementation, read/write sessions require authentication. Authenticated User sessions have access to private objects, while authenticated SO sessions do not. Affina data preparation and personalization software, with the obvious exception of the Affina KMS, accesses tokens using read-only sessions. The following sections describe usages and attributes common to key objects.
41
Key Usage
Keys can have the following usages. Usages shown in italics are extensions to the PKCS #11 specification and are shown in italics in the KMS user interface.
Usage Encrypt Decrypt Sign Verify Wrap Unwrap Export Import Derive Description The key may be used for encryption. The key may be used for decryption. The key may be used for signing. The key may be used for verifying signatures or MAC values. The key may be used to wrap (that is, extract) other keys. The key may be used to unwrap keys. The key may be used to export other keys. Can be set only by members of the SO role. The key may be used to import other keys. The key can be used in key derivation functions.
42
Key Attributes
Keys may have the following attributes. Attributes shown in italics are extensions to the PKCS #11 specification and are shown in italics in the KMS user interface. Attributes shown in boldface can be changed only once and are shown in boldface in the KMS user interface.
Attribute Sensitive Description The key's value cannot be revealed in plain text. After a key becomes sensitive it cannot be modified to be nonsensitive. Cannot be changed after it is set to True. The key can be trusted for the application for which it was created. Can be set only by members of the SO role. The object can be modified; that is, the object's attributes can be changed after creation. This attribute can be set only when an object is created. The created key can only be wrapped or backed up by a trusted key. Cannot be changed after it is set to True. The key is visible only after the user is authenticated to the token where that object is stored. This attribute can be set only when an object is created. Private object can be created only by members of the User role. If a key has the usage Unwrap, an Unwrap Mask may also be defined. When this key unwraps a key, the key that is unwrapped can be used only to encrypt other keys. An extractable key can be wrapped (encrypted with another key) and then extracted from the HSM. Cannot be changed after it is set to False. If a key has the usage Derive, a Derive Mask can be defined. The Derive Mask can define specific usages for up to five levels of derivation. In this case, each of the intermediate keys can be used only to derive another key. The key may be wrapped (encrypted with another key) but only with keys marked with the Export usage. Cannot be changed after it is set to True. The key can be deleted. If this is not selected, the adapter must be tampered to remove the key.
Trusted Modifiable
Unwrap Mask
Extractable
Derive Mask
Exportable
Deletable
43
Configuring HSMs
Using the SafeNet HSM
Token Initialization Procedures
There are two token initialization procedures: Initialize the AdminToken and Initialize a Key Token. Initialize the AdminToken A key token must also be initialized. Keys must be stored in a key token. 1. Open the KMS (see Open the KMS on page 51). 2. Right-click the AdminToken and then select Login. 3. In the Login dialog, select Security Officer and then enter the PIN 9999. 4. From the Administration menu, select Init Token. 5. In the Token Initialization dialog box, select AdminToken from the Slot list. 6. For Certificate, click Browse and then navigate to the .crt file on the Affina PKCS#11 Firmware CD. 7. For Firmware, click Browse and then navigate to the .fm file on the Affina PKCS#11 Firmware CD. 8. For both the Security Officer (SO) and User login modes, select the appropriate mode for the token that you are initializing. For PKCS#11: A. Enter a user name. You can use up to 31 UTF-8 characters with the exception of the # character. B. Enter and then confirm the PIN. You can use up to 31 UTF-8 characters. For N of M: A. Choose the Number in Role (users, a minimum of two and a maximum of five) and the number of users required in order to log in (Number for Login). B. Enter a user name. Use up to 31 UTF-8 characters with the exception of the # character. C. Enter and then confirm the PIN. You can use up to 31 UTF-8 characters. You cannot change the user name without reinitializing the token.
44
9. Click OK to save the token. The firmware will update. The update process can take some time to complete. Do not perform any other actions until the update process is finished. Initialize a Key Token A key token must be initialized. Keys must be stored in a key token. 1. Open the KMS (see Open the KMS on page 51). 2. Right-click the AdminToken and then select Login. 3. In the Login dialog, select User and then enter the PIN(s) defined when you initialized the AdminToken. 4. From the Administration menu, select Init Token. 5. In the Token Initialization dialog box, from the Slot list select the appropriate slot for the token you are initializing. Enter a descriptive label if needed. 6. For both the Security Officer (SO) and User login modes, select the appropriate mode for the token that you are initializing. For PKCS#11: A. Enter a user name. You can use up to 31 UTF-8 characters with the exception of the # character. B. Enter and then confirm the PIN. You can use up to 31 UTF-8 characters. For N of M: A. Choose the Number in Role (users, a minimum of two and a maximum of five) and the number of users required in order to log in (Number for Login). B. Enter a user name. Use up to 31 UTF-8 characters with the exception of the # character. C. Enter and then confirm the PIN. You can use up to 31 UTF-8 characters. You cannot change the user name without reinitializing the token. 7. Click OK. After the token is initialized, you will be logged out of the AdminToken.
45
Administrative Functions
Create slots You must be logged into the AdminToken as a User in order to perform this task. 1. Open the KMS (see Open the KMS on page 51). 2. Right-click the AdminToken, and then select Login. 3. In the Login dialog, select User and then enter the PIN. 4. From the menu bar, select Administration | SafeNet | Create Slots. 5. In the dialog, enter the number of slots you want to create and then click OK. The slots will appear in the token navigator. After a slot has been created, it must be initialized to be used. Delete slots You must be logged into the AdminToken as a User in order to perform this task. 1. Open the KMS (see Open the KMS on page 51). 2. Right-click the AdminToken, and then select Login. 3. In the Login dialog box, select User and then enter the PIN(s). 4. In the Token Explorer, select the Slot(s) you want to delete and then click Delete (in the toolbar). 5. Click OK. The Slots will disappear from the Token Navigator. Download SafeNet firmware Perform the following procedure to download updated firmware to the SafeNet HSM. You must be logged into the AdminToken as a User in order to perform this task. 1. From the menu bar select Administration | SafeNet | Download Firmware. 2. In the Download Affina Firmware dialog box, browse to and then select the .fm file on the Affina PKCS#11 Firmware CD. 3. Click Open. The path appears in the dialog. 4. Click OK.
46
The firmware will update automatically. The process can take some time to complete. Do not perform any other actions until the update process is finished. Configure the adapter Perform the following procedure to configure the adapters clock and transport mode. You must be logged into the AdminToken as a User in order to perform this task. 1. From the menu bar select Administration | SafeNet | Adapter Configuration. 2. In the Adapter Configuration dialog: A. For Clock, the current adapter clock date and time is displayed. To change the date and time, select one of the following: Manual - To use the keyboard to enter the date and time in their respective boxes. Computer Clock - To synchronize the adapter clock with the computers clock.
Click Set when finished. B. For Transport Mode, choose how the adapter will behave when it is removed from the PCI bus on the PC. The board is designed to tamper (all data is erased) in order to prevent secure information from being moved to another PC. Disabled - The adapter cannot be removed without being tampered. Single Shot - The adapter can be removed and replaced once without being tampered. Continuous - The adapter can be removed and replaced unlimited times without being tampered.
Click Set when finished. C. For Security Mode, select the security options required for your installation. See the SafeNet ProtectToolkit C Administration Manual for descriptions of these options. Click Set when finished. 3. Click Close.
47
Load a firmware certificate Perform the following procedure to load a firmware certificate on the SafeNet HSM. You must be logged into the AdminToken as a Security Officer to load a certificate. 1. Open the KMS. 2. Right-click the AdminToken, and then select Login. 3. In the Login dialog, select Security Officer and then enter the PIN(s). 4. From the menu bar select Administration | SafeNet | Load Firmware Certificate. 5. In the Download Affina Firmware dialog box, browse to and select the .crt file on the Affina PKCS#11 Firmware CD. 6. Click Open. The path appears in the dialog. 7. Click OK. Tamper the adapter Tampering the adapter wipes out all data and returns the adapter to its factory state. Any firmware updates will remain. You must be logged into the AdminToken as a User in order to perform this task. 1. From the menu bar select Administration | SafeNet | Tamper Adapter. 2. Confirm that you want to tamper the adapter in the confirmation dialog. The adapter will be tampered. Set (Modify) PIN Perform the following procedure to set or modify the user PIN. You must be logged into the token as a Security Officer or User to perform this procedure. 1. Right-click on a token in the Token Navigator. 2. Select Set Pin. 3. In the PIN Modification dialog, for each user enter the current PIN and then enter and confirm the new PIN. 4. Click OK.
48
F. Click Next. G. For Component 1, enter 10101010101010102020202020202020 and then click OK and then Next.
49
H. For Component #2, enter 20202020202020204040404040404040 and then click OK and then Next. I. For Component #3, enter 40404040404040408080808080808080 and then click OK and then Next.
J. Click Finish. K. In the Import Key dialog box, confirm that the KCV is 3A 36 37 and then click Yes.
3. Import the Backup-Restore key. A. From the menu, select Import | Restore Object. B. Under Import Key: a. For Key, select the key created in the previous step, for example, ZMK.Datacard.01 b. For Folder, click Browse, navigate to \Program Files\Datacard\ ADP\Samples\KMS, select Backup-Restore.Datacard.01, and then click Open. C. Click OK. 4. Restore keys. A. From the menu, select Import | Restore Object. B. Under Import Key: a. For Key, select the key created in the previous step, for example, Backup-Restore.Datacard.01. b. Select From a zip file. c. For Folder, click Browse, navigate to \Program Files\Datacard\ ADP\KMS\Samples, select Backup-Restore.Datacard.01.zip, and then click Open. d. Click OK.
50
Creation Tasks
Generate a secret key This procedure generates a selected number of components to create a key. 1. From the menu bar select Create | Generate Secret Key. 2. Under Label, enter the Name, Owner, and Version in their respective text boxes. The Owner, Name, and Version fields must all be completed or they must all be left blank. In addition, the combination of Owner, Name, and Version must be unique within the database. 3. Select the key Type from the list. The keys size (in bits) appears in the Size box. 4. Select the key usage from the available options. (See Key Usage on page 42.) 5. Select the key attributes from the available options. (See Key Attributes on page 43.) 6. Click Finish. Generate a key pair This procedure creates a public and private key pair. 1. From the menu bar select Create | Generate Key Pair. 2. For the Public Key, under Label, enter the Name, Owner, and Version in their respective text boxes. The combination of Name, Owner, and Version must be unique within the database. 3. Under Key Type, select the key Type from the list, and then enter the Key Size (in bits) and the Public Exponent. 4. Select the key pair usage from the available options. (See Key Usage on page 42.)
51
5. Select the key pair attributes from the available options. (See Key Attributes on page 43.) If the Derive or Unwrap usages are selected, the Derive Mask and/or Unwrap Mask attributes will be available. If these attributes are then selected, the Derive Mask and/or Unwrap Mask options become available. See Create a derive mask on page 55 and Create an unwrap mask on page 56. 6. Click Next. 7. For the Private Key, enter the Name, Attribute, and Usage parameters as above. (The name must be different.) 8. Click Finish to generate the Key Pair. Generate a secret key in components This procedure creates a secret key from a selected number of generated components. Each component can be recorded individually for transport purposes. 1. From the menu bar select Create | Create Secret Key From Clear Components. 2. Under Label, enter the Name, Owner, and Version in their respective text boxes. The Owner, Name, and Version fields must all be completed or they must all be left blank. In addition, the combination of Owner, Name, and Version must be unique within the database. 3. Under Key Type, select the key Type from the list. 4. Select the key usage from the available options. (See Key Usage on page 42.) 5. Select the key attributes from the available options. (See Key Attributes on page 43.) If the Derive or Unwrap usages are selected, the Derive Mask and/or Unwrap Mask attributes will be available. If these attributes are then selected, the Derive Mask and/or Unwrap Mask options become available. See Create a derive mask on page 55 and Create an unwrap mask on page 56. 6. Enter the number of components. 7. Select whether the components will be entered using the keyboard or via a terminal. If you will be using the terminal, enter the timeout value (in
52
seconds). This value indicates how long the KMS will wait to receive a Key Component from a terminal before aborting the operation. Click Next. 8. If you selected Keyboard/Screen in the previous step, on the number of components entered in step 6, you will be given a corresponding number of screens with which to view the components. Click Next at each screen. 9. On the final screen click Next. 10. Click Finish. The key is loaded in the database and displayed in the Token Explorer. 11. Click Generate and Export. The Key Component dialog box opens, showing the key check value of the first encrypted key component. 12. Click Save. 13. In the Key dialog box, navigate to the location where you want the key component saved, enter a file name (a .bin extension will be added), and click Select. The Key Component dialog box opens as many times as the number of components you selected in step 1. When you have saved the last component, the key is stored in the database and appears in the Keys table. Create a secret key from clear components This procedure creates a secret key from a selected number of clear components. Each component can be recorded individually for transport purposes. 1. From the menu bar select Create | Create Secret Key From Clear Components. 2. Under Label, enter the Name, Owner, and Version in their respective text boxes. The combination of Name, Owner, and Version must be unique within the database. 3. Under Key Type, select the key Type from the list. The keys size (in bits) appears in the Size box. 4. Select the key usage from the available options. (See Key Usage on page 42.) 5. Select the key attributes from the available options. (See Key Attributes on page 43.) If the Derive or Unwrap usages are selected, the Derive Mask and/or Unwrap Mask attributes will be available. If these attributes are then selected, the Derive Mask and/or Unwrap Mask options become available. See Create a derive mask on page 55 and Create an unwrap mask on page 56. 6. Enter the number of components.
53
7. Select whether the components will be entered using the keyboard or via a terminal. If you will be using the terminal, enter the timeout value (in seconds). This value indicates how long the KMS will wait to receive a Key Component from a terminal before aborting the operation. Click Next. 8. If you selected Keyboard/Screen in the previous step, based on the number of components entered in step 6, you will be given a corresponding number of screens with which to view the components. Click Next at each screen after the information is entered. 9. Repeat step 8 until all components have been imported. 10. Click Finish. A complete key is constructed, loaded in the database, and displayed in the Token Explorer. Create a backup/restore key This procedure generates a key that can be used to back up and restore an object. A backup/restore key must have the Import and Export usages. Only a Security Officer can set the Export usage on an existing key. There are two methods for creating a backup/restore key. The Security Officer(s) can log on, create the key, and set the Import and Export usages. A key created by the Security Officer(s) cannot be Private. The User(s) can log on, create the key, and then set the Import usage (the key must also be Modifiable). The Security Officer(s) can then log on and set the Export usage.
1. Follow the steps in Generate a secret key on page 51. Set the usage to Import and Export. Select at least the Sensitive and Exportable attributes. Do not select Private.
54
Create a backup/restore key from components This procedure generates a key that can be used to backup and restore a backup key and/or other objects. A backup/restore key must have the Import and Export usages. Only a Security Officer can set the Export usage. There are two methods for creating a backup/restore key from components. The Security Officer(s) can log on, create the key, and set the Import and Export usages. The User(s) can log on, create the key, and set the Import usage (the key must also be Modifiable). The Security Officer(s) can then log on and set the Export usage.
1. Follow the steps in Generate a secret key in components on page 52. 2. Set the usage. (See Key Usage on page 42.) 3. Select the key attributes from the available options. (See Key Attributes on page 43.) The key should be Sensitive and should not be Exportable. 4. Click Finish. Create a wrap/unwrap key from components This procedure generates a key that can be used to wrap and/or unwrap a key. 1. Follow the steps in Generate a secret key in components on page 52. 2. Select the key attributes from the available options. (See Key Attributes on page 43.) The key should at least be Sensitive and Modifiable, and Exportable. 3. Set the usage to Wrap and Unwrap. 4. Click Finish. Create a derive mask You can use a derive mask to precisely control what a key derived by that key (and so on for each successive level) is allowed to do. This function is enabled only if the key has a usage of Derive and an attribute of Derive Mask. 1. For Level1, select the key usage from the available options. If Derive is selected, then Level2 is enabled. 2. Click Finish.
55
Create an unwrap mask You can use an unwrap mask to precisely control what a key unwrapped by that key is allowed to do. This function is only enabled if a key has a usage of Unwrap and an attribute of Unwrap Mask. 1. Select Unwrap and then select Unwrap Mask. 2. Under Unwrap Template, select the appropriate usage(s) for keys unwrapped by this key. If you are unwrapping a key with this key or modifying a key unwrapped by this key and set a usage not allowed by the Unwrap Mask, you will receive the error: CKR_ERROR: 0x000000D1 - CKR_TEMPLATE_INCONSISTENT. 3. Click Finish.
Importing Tasks
Restore an object This procedure restores an object from a file or zip file. 1. From the menu bar select Import | Restore Object. The Restore Object dialog box opens. 2. Select the import key from the Key list. 3. Select whether the object(s) are in individual files or are contained within a zip file. 4. Browse to and select the file(s) you want to import. Click Open. 5. The objects are displayed in the dialog. Select those you want to restore and then click OK. Unwrap a key This procedure unwraps an encrypted key. 1. From the menu bar, select Import | Unwrap Key. 2. Under Key Encryption Key, select the Mode and the KEK from their respective lists. 3. Under Encrypted Key, select the Key Type from the list and then select whether the encrypted key will be imported from a file, entered using the keyboard, or entered via a terminal.
56
If loading from a file, click Browse and then navigate to the file you want to import. Click Open. 4. Under Label, enter the Name, Owner, and Version in their respective text boxes. The combination of Name, Owner, and Version must be unique within the database. 5. Select the key usage from the available options. (See Key Usage on page 42.) 6. Select the key attributes from the available options. (See Key Attributes on page 43.) If the Derive or Unwrap usages are selected, the Derive Mask and/or Unwrap Mask attributes will be available. If these attributes are then selected, the Derive Mask and/or Unwrap Mask options become available. See Create a derive mask on page 55 and Create an unwrap mask on page 56.) 7. Click Finish. Import a public key This procedure imports a public key from a file. 1. From the menu bar select Import | Import Public Key. The Import dialog box opens. 2. Under Key, select the CKK_RSA key from the Type list. 3. Under File Name, click Browse and then navigate to the key file that you want to import. 4. Under Label, enter the Name, Owner, and Version in their respective text boxes. 5. Select the key pair attributes from the available options. (See Key Attributes on page 43.) 6. Select the key pair usage from the available options. (See Key Usage on page 42.) 7. Click OK.
57
Import a key pair Perform the following steps to import a key pair from a file in which the secret key is encrypted in ASN.1 format and the public key is not encrypted. 1. Unwrap the Secret Key: A. From the menu bar select Import | Unwrap Key. The Import dialog box opens. B. Under Key Encryption Key, select CKM_DES3_CBC_RSA_CRT_BITSTRING for Encryption Mode and the appropriate unwrap key for KEK. C. Under Encrypted Key, select CKK_RSA for the Key Type from the list. D. Click Browse and then navigate to the file containing the key pair. Click Open. E. Under Label, enter the Name, Owner, and Version in their respective text boxes. For RSA key pairs, the combination of the Owner and Version must be unique within the database. F. Select the key usage from the available options. (See Key Usage on page 42.) G. Select the key attributes from the available options. (See Key Attributes on page 43.) If the Derive or Unwrap usages are selected, the Derive Mask and/or Unwrap Mask attributes will be enabled. If these attributes are then selected the Derive Template and/or Unwrap Template options are enabled. See Create a derive mask on page 55 and Create an unwrap mask on page 56.) H. Click Finish. 2. Import the Public Key: A. From the menu bar select Import | Import Public Key. The Import dialog box opens. B. Under Key, select CKK_RSA from the key Type list. C. Under File Name, click Browse and then navigate to the folder containing the key pair. D. Under Label, enter the Name, Owner, and Version in their respective text boxes. For RSA key pairs, the Owner and Version entered must match the Owner and Version entered in step 1E above.
58
E. Select the key pair attributes from the available options. (See Key Attributes on page 43.) F. Select the key pair usage from the available options. (See Key Usage on page 42.) G. Click OK. Link an unwrapped RSA key pair 1. Unwrap the RSA Private Key. (See Unwrap a key on page 56.) 2. Import the Public Key: A. From the menu bar select Import | Import Public Key. The Import dialog box opens. B. Under Key, select CKK_RSA from the key Type list. C. Under File Name, click Browse and then navigate to the folder containing the key pair. D. Under Label, enter the Name, Owner, and Version in their respective text boxes. E. Select the key pair attributes from the available options. (See Key Attributes on page 43.) F. Select the key pair usage from the available options. (See Key Usage on page 42.) G. Click OK. If a matching RSA Private key is found, its label will be listed in the Paired Private Key field. Import the MULTOS Hash Modulus and TKCK This procedure imports a MULTOS Hash Modulus or a Transport Key Certifying Key (TKCK). The imported key must be a public key with the Trusted attribute enabled. This attribute can only be set by a Security Officer and only a Security Officer can modify a Trusted key. There are two methods for changing the key attribute to Trusted. The Security Officer can log on, import the key, and then set the Trusted attribute. A User can log on and then import the key (the key must be modifiable). The Security Officer must then log on and then set the key attribute to Trusted.
59
1. Log in to the KMS as a Security Officer. 2. From the menu bar select Import | Import Public Key. The Import dialog box opens. 3. Under Key, select CKK_RSA from the key Type list. 4. Under File Name, click Browse and then navigate to the key file that you want to import. 5. Select the key attributes from the available options. (See Key Attributes on page 43.) Both keys must be Trusted. 6. Select the key usage from the available options. (See Key Usage on page 42.) The Hash Modulus must have Encrypt and the TKCK must have Derive. 7. Click OK.
60
Exporting Tasks
Back up an object This procedure creates a backup of an object, including its value and all of its attributes. 1. In the Token Explorer, select one or more objects to back up. 2. From the menu bar select Export | Backup Object. The dialog box opens. 3. Select the key from the Key list. 4. Select whether the object(s) will be exported as individual files or will be contained within a zip file. 5. Browse to and select the destination folder for the object(s). Click OK. 6. The objects to back up are displayed in the dialog. Click OK. Wrap a key This procedure wraps the value of a public key, an extractable secret key, or a private key. 1. From the menu bar select Export | Wrap Key. 2. Select an Encryption Mode from the list. Only keys with a usage of Wrap will appear in the list. 3. Select the key from the Key list. 4. Select whether the key(s) will be exported as individual files or contained in a zip file. 5. Browse to and then select the destination folder for the key(s). Click OK. 6. The key(s) to export are displayed in the dialog. Click OK. Extract a public key 1. Select the public key you want to export from the Token Explorer. The key must have the attribute Extractable. 2. From the menu bar select Export | Extract Public Key. 3. In the Extract Public Key dialog box, browse to the location where you want the key saved and then click OK.
61
Certificate Tasks
Generate a VISA certificate request 1. In the KMS Token Explorer, select a private key. 2. From the toolbar above the Token Explorer list, select the Visa Certificate Request icon. The Certificate Request dialog box opens. 3. Enter a Tracking Number of up to six digits. 4. Enter the Service ID (the four most significant bytes of the PIX portion of the AID, padded on the right with \x00 if less than four bytes long). Example: 10100000 5. Enter your BIN (Bank Identification Number). 6. Select the month and year in which you want the certificate to expire. 7. Browse to and select the folder in which you want the certificate request stored. Click OK. 8. Click Finish. The certificate request will be generated with the .inp extension. The file is saved in the folder you specified. Generate a MasterCard certificate request 1. In the KMS Token Explorer, select a private key. 2. From the toolbar above the Token Explorer list, select the select the MasterCard Certificate Request icon. The Certificate Request dialog box opens. 3. Based on the key selected in step 1, the Private Key, Public Key Index (hex), and BIN fields will contain information. 4. Select the month and year in which you want the certificate to expire. 5. Browse to and select the folder in which you want the certificate request stored. Click OK. 6. Click Finish. The certificate request will be generated with the .sip extension. The request and an associated file (with the .hip extension) are saved in the folder you specified. 7. Follow the procedure defined by the MasterCard CA to send the request to MasterCard.
62
Generate a PBOC certificate request 1. In the KMS Token Explorer, select a private key. 2. From the toolbar above the Token Explorer list, select the PBOC Certificate Request icon. The Certificate Request dialog box opens. 3. Enter a Tracking Number of up to six digits. 4. Enter the Service ID (the four most significant bytes of the PIX portion of the AID, padded on the right with \x00 if less than four bytes long). Example: 10100000 5. Select the month and year in which you want the certificate to expire. 6. Browse to and select the folder in which you want the certificate request stored. Click OK. 7. Click Finish. The certificate request will be generated with the .inp extension. The file is saved in the folder you specified. Generate a JCB certificate request 1. In the KMS Token Explorer, select a private key. 2. From the toolbar above the Token Explorer list, select the JCB Certificate Request icon. The Certificate Request dialog box opens. 3. Select the month and year in which you want the certificate to expire. 4. Enter a Request Number of up to six digits. 5. Browse to and select the folder in which you want the certificate request stored. Click OK. Import a VISA CA certificate 1. From the menu bar select Certificates | Import VISA CA Certificate. 2. In the Import VISA CA Certificate dialog box, browse to and select the certificate you want to import. 3. Click Open. The certificate information appears in the dialog. 4. Click OK.
63
Import a VISA Issuer certificate You must import the CA certificate before importing the Issuer certificate. 1. From the menu bar select Certificates | Import VISA Certificate. 2. In the Import Visa Issuer Certificate dialog box, browse to and select the certificate you want to import. 3. Click Open. The certificate information appears in the dialog. 4. Click OK. Import a MasterCard CA certificate 1. From the menu bar select Certificates | Import MasterCard CA Certificate. 2. In the Import MasterCard CA Certificate dialog box, browse to and select the certificate file you want to import. 3. Click Open. The certificate information appears in the dialog. 4. Click OK. Import a MasterCard Issuer certificate You must import the CA certificate before importing the Issuer certificate. 1. From the menu bar select Certificates | Import MasterCard Certificate. 2. In the Import MasterCard Issuer Certificate dialog box, browse to and select the certificate you want to import. 3. Click Open. 4. Click OK. Import a PBOC CA certificate 1. From the menu bar select Certificates | Import PBOC CA Certificate. 2. In the dialog box, browse to and select the certificate you want to import. 3. Click Open. The certificate information appears in the dialog. 4. Click OK.
64
Import a PBOC Issuer certificate You must import the CA certificate before importing the Issuer certificate. 1. From the menu bar select Certificates | Import PBOC Issuer Certificate. 2. In the Import PBOC Issuer Certificate dialog box, browse to and select the certificate you want to import. 3. Click Open. The certificate information appears in the dialog. 4. Click OK. Import a JCB CA certificate 1. From the menu bar select Certificates | Import JCB CA Certificate. 2. In the Import JCB CA Certificate dialog box, browse to and select the public key file for the certificate you want to import. 3. Browse to and select the certificate you want to import. 4. Click Open. The certificate information appears in the dialog. 5. Click OK. Import a JCB Issuer certificate You must import the CA certificate before importing the Issuer certificate. 1. From the menu bar select Certificates | Import JCB Certificate. 2. In the Import JCB Issuer Certificate dialog box, browse to and select the certificate you want to import. 3. Click Open. The certificate information appears in the dialog. 4. Click OK.
65
Issuer_PK
BIN
IssuerPublicKeyIndex
CKK_RSA
VERIFY
2. Use the Issuer public key (Issuer_PK) to generate the certificate request (see Generate a VISA certificate request on page 62 for step-by-step instructions). 3. Generate or import the following Issuer application keys (see Generate a secret key on page 51 for step-by-step instructions). The key Owner must match the BIN derived from the PAN in the magnetic stripe data. The key Version for the Derivation Master Keys (DMKs) must match the 2nd byte of the value defined in the ADT for the Data Element IssuerApplicationData (for VSDC, this is the DerivationKeyIndex (DKI)). The key Version for the KEK must match the value defined in the ADT for the Data Element KEK_VER.
Name DMKac Owner BIN Version DKI Class CKO_SECRET_KEY Type CKK_DES2 Attribute Sensitive and Exportable Sensitive and Exportable Sensitive and Exportable Sensitive and Exportable Usage(s) DERIVE
DMKmac
BIN
DKI
CKO_SECRET_KEY
CKK_DES2
DERIVE
DMKenc
BIN
DKI
CKO_SECRET_KEY
CKK_DES2
DERIVE
KEK
BIN
KEK_VER
CKO_SECRET_KEY
CKK_DES2
WRAP
66
4. Import the VSDC CA and Issuer Certificates (see Import a VISA CA certificate on page 63 and Import a VISA Issuer certificate on page 64 for step-by-step instructions). Always import the CA Certificate before importing the Issuer Certificate. 5. If you are using Affina One Step Issuance software, you must also import the zone master key (ZMK) and card master key (KMC) into the Key Management System. They come from your card supplier. See Create a secret key from clear components on page 53 for step-by-step instructions.
67
Key Management System tasks for M/Chip4 1. Generate the following Issuer keys (see Generate a key pair on page 51 for step-by-step instructions). The key Owner must match the BIN derived from the PAN in the magnetic stripe data and the key Version entered must also be defined in the ADT as the value for the Data Element IssuerPublicKeyIndex.
Name Issuer_SK Owner BIN Version IssuerPublicKeyIndex Class CKO_PRIVATE _KEY CKO_PUBLIC_ KEY Type CKK_RSA Attribute Sensitive and Exportable Exportable Usage SIGN
Issuer_PK
BIN
IssuerPublicKeyIndex
CKK_RSA
VERIFY
2. Use the Issuer public key (Issuer_PK) to generate the certificate request (see Generate a MasterCard certificate request on page 62 for step-by-step instructions). 3. Generate or import the following Issuer application keys (see Generate a secret key on page 51 for step-by-step instructions). The key Owner must match the BIN derived from the PAN in the magnetic stripe data. The key Version for the Issuer Master Keys (IMKs) must match the value defined in the ADT for the Data Element KeyDerivationIndex and the key Version for the KEK must match the value defined in the ADT for the Data Element KEK_VER.
Name IMKac Owner BIN Version DKI Class CKO_SECRET_KEY Type CKK_DES2 Attribute Sensitive and Exportable Sensitive and Exportable Sensitive and Exportable Sensitive and Exportable Usage DERIVE
IMKsmi
BIN
DKI
CKO_SECRET_KEY
CKK_DES2
DERIVE
IMKsmc
BIN
DKI
CKO_SECRET_KEY
CKK_DES2
DERIVE
IMKidn
BIN
DKI
CKO_SECRET_KEY
CKK_DES2
DERIVE
68
Name IMKdac
Owner BIN
Version DKI
Class CKO_SECRET_KEY
Type CKK_DES2
Usage ENCRYPT
KEK
BIN
KEK_VER
CKO_SECRET_KEY
CKK_DES2
WRAP
4. Import the MasterCard CA and Issuer Certificates (see Import a MasterCard CA certificate on page 64 and Import a MasterCard Issuer certificate on page 64 for step-by-step instructions). Always import the CA Certificate before importing the Issuer Certificate. 5. If you are using Affina One Step Issuance software, you must also import the zone master key (ZMK) and card master key (KMC) into the Key Management System. They come from your card supplier. See Create a secret key from clear components on page 53 for step-by-step instructions.
69
Key Management System Tasks for M/Chip4, MICA, or VSDC MULTOS The M/Chip4 data generation keys are required for M/Chip4 and MICA MULTOS and the VSDC data generation keys are required for VSDC MULTOS along with the following keys. For M/Chip4, MICA, and VSDC MULTOS, the KEK must also have the usage Encrypt. 1. Generate the Application Provider Keyset (see Generate a key pair on page 51 for step-by-step instructions). For M/Chip4, the APK version must match the Application Provider Keyset ID in the ALU template that is listed in the ADT in the Data Element APK_VER; for VSDC, the version must be entered in the ADT. The key Owner must match the BIN derived from the PAN in the magnetic stripe data and the key version.
Name AP_SK Owner BIN Version APK_VER Class CKO_PRIVATE_KEY Type CKK_RSA Attribute Sensitive and Exportable Exportable Usage SIGN
AP_PK
BIN
APK_VER
CKO_PUBLIC_KEY
CKK_RSA
VERIFY
2. Import the MULTOS Hash Modulus and, if using Affina One Step Issuance software, the Transport Key Certifying Key (TKCK). See Import the MULTOS Hash Modulus and TKCK on page 59 for step-by-step instructions. 3. If you have defined an encrypted PIN in your ALU template, create or Import a PIN Encryption Key (PEK). The Version of the PEK must match the value defined in the ADT for the Data Element PEK_VER. The key Owner must match the BIN derived from the PAN in the magnetic stripe data and the key version.
Name PEK Owner BIN Version PEK_VER Class CKO_SECRET_KEY Type CKK_DES 2 Attribute Sensitive and Exportable Usage WRAP
4. If you are using MICA with PayPass, create or import the Issuer Master Key for CVC3 (IMKcvc3). The key Owner must match the BIN derived from the PAN in the magnetic stripe data. The key Version for the Issuer Master Keys (IMKs) must match the value defined in the ADT for the Data Element
70
KeyDerivationIndex. The IMKcvc3 must have the usage Derive for Dynamic CVC3 and Sign for Static CVC3.
Name IMKcvc3 Owner BIN Version DKI Class CKO_SECRET_KEY Type CKK_DES 2 Attribute Sensitive and Exportable Usage DERIVE SIGN
Key Management System Tasks for M/Chip4, MICA, or VSDC step/one The M/Chip4 data generation keys are required for M/Chip4 and MICA step/ one and the VSDC data generation keys are required for VSDC step/one along with the following keys. For M/Chip4, MICA, and VSDC step/one, the KEK must also have the usage Encrypt. 1. Import the step/one IMK_KE and IMK_AS. The Owner for both keys must match the value defined for the Data Element MCD_IssuerID in the ADT and the Version must match the value defined for the Data Element StepOneIMK_ID. The key Owner must match the BIN derived from the PAN in the magnetic stripe data.
Name IMK_KE Owner MCD_IssuerID Version StepOneIMK_ID Class CKO_SECRET_ KEY CKO_SECRET_ KEY Type CKK_DES2 Attribute Sensitive and Exportable Sensitive and Exportable Usage ENCRYPT
IMK_AS
MCD_IssuerID
StepOneIMK_ID
CKK_DES2
SIGN
2. If you are using MICA with PayPass, create or import the Issuer Master Key for CVC3 (IMKcvc3). The key Owner must match the BIN derived from the PAN in the magnetic stripe data. The key Version for the Issuer Master Keys (IMKs) must match the value defined in the ADT for the Data Element KeyDerivationIndex. The IMKcvc3 must have the usage Derive for Dynamic CVC3 and Sign for Static CVC3.
Name IMKcvc3 Owner BIN Version DKI Class CKO_SECRET_KEY Type CKK_DES 2 Attribute Sensitive and Exportable Usage DERIVE SIGN
71
72
5
XML Schemas
GP Profiles
Datacard Profiles
Visa VPA
MasterCard CU
Configuration Manager
73
Profile Descriptions
Configuration Manager manages both Datacard and GlobalPlatform (GP) profiles. All profiles can have an alias, an easy-to-remember name. You can assign and change aliases for Datacard profiles but not for GP profiles. Only one profile of each type can have the same alias, but profiles of different types (for example Product and Job) can have the same alias. A brief description for each type of profile is outlined below.
GP Profiles
There are four types of GP profiles: Application, Card, Key, and Loadfile. GP profiles are read only.
Application Profile
The Application profile serves as a container of information about the smart card application and its requirements. It defines the external data and key requirements of the application and its individual scripts. Application profiles contain one to many script fragments that are used for card customization. Within the context of the Affina Data Preparation (DP) system, only script fragments that do not use the GP Card object can be used. Generally this is the DataPrep script fragment.
Card Profile
The Card profile describes a smart card. This card could be a singularly unique card or a card that shares common characteristics, as defined in the Card profile, with other cards. Depending on how it is used, it either acts as a base template for a smart card or represents a single smart card by itself.
Key Profile
The Key profile that describes a cryptographic key, independent of any particular instance of the key. It acts as a template for creating the actual key.
Loadfile Profile
The Loadfile profile describes the physical file that contains the on-card executable application code.
74
Configuration Manager
Datacard Profiles
There are six types of Datacard profiles: Application Data Template (ADT), Application Profile Input Mapping (APIM), Application Profile Output Mapping (APOM), DataSet, Job, and Product. Users create or modify Datacard profiles using Configuration Manager.
DataSet Profile
The DataSet profile acts as a parser for either input or output data within the context of an application script fragment. The input DataSet profile serves as a parser for incoming cardholder data. It is responsible for creating a common issuer set of ECMAScript variables or objects that can be used later by the APIM. The output DataSet profile serves as a formatting tool for cardholder data. It is responsible for collecting data generated by the APOM after script fragment execution and for formatting the cardholder data for the output. A Default embedded DataSet is provided that does not require an APIM or APOM. However, you can use an APOM to selectively return data to an output file in the Affina DP environment or to the Audit trail in the One Step environment.
Job Profile
The Job profile defines the highest level of configuration within the Configuration Manager tool. It specifies which input and output DataSets will be used at runtime as well as which product to execute.
Affina Issuance Platform Users Guide 75
Product Profile
At runtime, when Syntera CS or a Batch production setup sends a request to the Affina Profiles and Scripting Interpreter with cardholder data, one or more script fragments will be executed. The Product profile allows a user to choose which Application profiles will be used at runtime and, more specifically, which script fragments defined in those Application profiles will be run. Because the order of script execution is important, the Product profile lets you specify the ordering of the process steps (AID/Script Fragment pair). You can also define which static values to use for each script fragment by assigning an ADT to each Application instance within the Product profile. ADT Associations An ADT may be associated with a MULTOS MChip4 ALU Template created using the M/Chip for MULTOS Customization Utility CU Tool or with a Visa Personalization Assistant (VPA) Output File. After an ADT is associated with a template or an output file, the contents of the template or output file can be viewed in the ADT Tab MC_CU/VPA Tool Association, and the ADT cannot be disassociated. However, an associated ADT can be exported from one system and imported into another system as long as the same template or output file is also provided. Visa Personalization Assistant (VPA) Output File VPA Output Files in XML format may be imported into Configuration Manager and associated with an ADT. After the ADT is associated with the output file, all Data Element values defined in the VPA file become Read-only values in the ADT. M/Chip4 or VSDC for MULTOS ALU Templates M/Chip4 ALU templates (.alt files) may be imported into Configuration Manager and associated with an ADT. After the ADT is associated with the template, all Data Element values for which Personalization has been set to Not Allowed in the template become Read-only values in the ADT. Data Element values for which Personalization is Allowed are editable in the ADT. Values for associated Data Elements may not be deleted, and all Data Elements defined in the template are considered to be Mandatory and to be provided by the ALU Generation System. The values in the template, including which Data Elements are ReadOnly, can be viewed in the ADT Tab MC_CU/VPA Tool Association.
Profile Associations
The following illustration is a graphical representation of profile interaction within the Configuration Manager tool. To avoid errors, create profiles in the order specified in Create a new job using release profiles on page 91.
76
Configuration Manager
Loadfile
Key
Application
Card
ADT Product
APIM
APOM
DataSet
Job
77
language defined by the W3C working group as Extensible Markup Language (XML) 1.0 in the W3C Recommendation February 10, 1998. The GlobalPlatform Card Specifications define the requirements that cards must meet in order to be considered GP 2.0.1 or 2.1 cards. GP cards have a JavaCard API and also a GP layer that interprets GP-specific card commands. This implementation of the Datacard GP Interpreter supports the use of cards that comply with the GlobalPlatform card specifications. As defined in the ECMA specification, all variables with $ as the first character are reserved for computer-generated variables.
78
Configuration Manager
General Tasks
Start Configuration Manager Use this procedure to start Configuration Manager. 1. Log on to the computer with a user name that has ADP_Administrator, ADP_Operator, or ADP_User user privileges and start the Affina Data Preparation Launcher (Start | Programs | Datacard | Affina Data Preparation | Affina Data Preparation Launcher). 2. On the Launcher, click Configuration Manager. Filtering objects You can control which objects are displayed in the Token Explorer by using the filter tool. 1. From the toolbar, click the Filter icon. 2. In the Browser Filter, enter the name, Owner and/or Version of the object(s) you want to display. You can also select the check box based on the class of object you want displayed. 3. Click OK. Set the base OID You can select the base object identifier (OID) for objects created in Configuration Manager. 1. From the Configuration Manager menu bar, select Configuration | Configuration Manager OID. The Configuration Manager Base OID dialog box opens. 2. If you have been issued a base OID, replace the default OID (which was generated for the computer on which Affina DP is installed) with the OID you have been issued. 3. Select whether you want to input OIDs in Hexadecimal or Decimal notation, and then click OK.
79
Set OID viewing preferences You can choose whether to view OIDs (object identifiers) in decimal notation or hexadecimal notation. In addition, you can choose whether to see an alias that may be more understandable to you. 1. To view OIDs in decimal notation, from the Configuration Manager menu bar, select Options | OID | View As Decimal. - or To view OIDs in hexadecimal notation, from the menu bar, select Options | OID | View As Hexadecimal. 2. To see an alias next to the OID, from the menu bar, select Options | OID | Show Alias.
80
Configuration Manager
Export a profile You can export a profile you created for use in another system. 1. Select the profile you want to export. 2. From the menu bar, select Configuration | Profiles | Export. 3. Browse to the folder where you want the profile saved or create a new folder. 4. Select Export all child profiles and/or Overwrite existing files as appropriate. 5. Click Export. A Results dialog box opens, showing the name of the file created. Delete a profile You can delete a profile that is no longer needed in your system. 1. Select the profile you want to delete. 2. From the Configuration Manager menu bar, select Configuration | Profiles and Tool Outputs | Delete. 3. Confirm that you want to delete the profile. Edit a profile You can edit an existing Datacard profile. 1. In the left pane, select the profile you want to change. 2. In the right pane, click Edit. 3. Make the necessary changes. (See the procedure for creating a profile of the type you selected for specific information.) 4. Click Apply Changes to save your work or click Apply to New Revision to save your changes in a new revision of the profile, leaving the profile you selected in step 1 unchanged.
81
Import a VPA Output File You can import a VPA output for use in your system. 1. From the Configuration Manager menu bar, select Configuration | Profiles and Tool Outputs | Import. 2. From the Import Files dialog, click Browse. 3. Browse to and select the file or files that you want to import, and then click Open. Information about the files you selected fills the dialog box. 4. If any row has a check mark in the Exists column, you must either select Overwrite existing file(s) or click Cancel and start the process over, taking care not to select files that already exist. 5. If any row shows an error in the Status column, the Error Details button becomes available. You can use this information to correct the error before starting this process again. 6. Click Import All. 7. If necessary, associate the VPA with an ADT. (See Create an ADT Association on page 83.) Import an ALU Template You can import an Application Load Unit template for use in your system. 1. From the Configuration Manager menu bar, select Configuration | Profiles and Tool Outputs | Import. 2. In the Import Files dialog box, click Browse. 3. In the Open dialog box, from the Files of type list, select ALU Templates (*.alt). 4. Browse to and select the template file or files that you want to import, and then click Open. Information about the files you selected fills the dialog box. 5. If any row has a check mark in the Exists column, you must either select Overwrite existing file(s) or click Cancel and start the process over, taking care not to select files that already exist. 6. If any row shows an error in the Status column, the Error Details button becomes available. You can use this information to correct the error before starting this process again. 7. Click Import All.
82
Configuration Manager
8. If necessary, associate the ALU Template with an ADT. (See Create an ADT Association on page 83.) Create an ADT Association An Application Data Template may be associated with a MULTOS MChip4 ALU Template created using the M/Chip for MULTOS Customization Utility (CU Tool) or with a Visa Personalization Assistant (VPA) Output File. After an ADT is associated with a template or an output file, the contents of the template or output file can be viewed in the ADT tab named MC_CU/VPA Tool Association, and the ADT cannot be disassociated. However, an associated ADT can be exported from one system and imported into another system as long as the same template or output file is also provided. VPA Output Files in XML format can be imported into Configuration Manager and associated with an ADT. After the ADT is associated with the output file, all Data Element values defined in the VPA file become Read-only values in the ADT. M/Chip4 ALU templates (.alt files) can be imported into Configuration Manager and associated with an ADT. After the ADT is associated with the template, all Data Element values for which Personalization has been set to Not Allowed in the template become Read-only values in the ADT. Data Element values for which Personalization is Allowed are editable in the ADT. Values for associated Data Elements may not be deleted, and all Data Elements defined in the template are considered to be Mandatory and to be provided by the ALU Generation System. The values in the template, including which Data Elements are Read-only, can be viewed in the ADT tab named MC_CU/VPA Tool Association.
1. In Configuration Manager, select an ADT from the left pane. Information about the selected ADT will appear in the right pane. 2. In the right pane, select the MC_CU/VPA Tool Association tab. 3. Click Edit. 4. Select the appropriate template type in the Tool Association tab. 5. In the Associate Tool Output dialog box, select the ALU Template/VPA from the list and then click Associate. 6. Click OK at the confirmation dialog. To exit without creating an association, click Undo Changes. 7. Click Apply Changes.
83
84
Configuration Manager
The ADT Profile Summary displays details about the ADT in the Profile Details area and all information for the ADT profile in XML format in the Profile Xml area. This tab is read-only. Create an APIM profile An Application Profile Input Mapping profile lets you map data from the output of a DataSet profile to a specified script fragment defined in an Application profile. 1. From the Configuration Manager menu bar, select Configuration | Profiles and Tool Outputs | Create | APIM. 2. In the Create New APIM Profile dialog box enter an Alias (a short name for the profile that will help you identify it) and a longer Description. 3. (Optional) Change the OID and choose whether you want the OID displayed in decimal or hexadecimal notation. 4. Select the associated Application profile and DataSet from the lists. 5. Click OK. The Data Elements tab opens in the right pane. It lists all the data elements defined in the associated Application profile. You can select any data element and supply a value for it as a JavaScript expression, such as $dataSet.cardholderName. 6. Click Edit to begin making changes. You can click Apply Changes or Undo Changes at any time. After you click Apply Changes, you cannot undo any changes you applied. The APIM Profile Summary displays details about the APIM in the Profile Details area and all information for the APIM profile in XML format in the Profile Xml area. This tab is read-only.
85
Create an APOM profile An Application Profile Output Mapping profile lets you map data from the output of a DataSet profile to an associated cardholder data field. 1. From the Configuration Manager menu bar, select Configuration | Profiles and Tool Outputs | Create | APOM. 2. In the Create New APOM Profile dialog box enter an Alias (a short name for the profile that will help you identify it) and a longer Description. 3. (Optional) Change the OID and choose whether you want the OID displayed in decimal or hexadecimal notation. 4. Select the associated Application profile and DataSet from the lists. If you are using Affina One Step Issuance, you can associate an APOM with the default DataSet. In that case data elements added to the APOM for the personalization script fragment are sent to the personalization systems Audit record. 5. Click OK. The Data Elements tab opens in the right pane. It lists all the data elements defined in the associated Application profile. You can select any data element and add it to the data output. A. Click Edit to begin making changes. You can click Apply Changes or Undo Changes at any time. After you click Apply Changes, you cannot undo any changes you applied and you must click Edit again to make additional changes. The Edit, Undo Changes, and Apply Changes buttons apply to all editable tabs for the profile. B. Select a data element. C. Click Add to Data Output Elements. 6. The Key Elements tab lists all the cryptographic keys defined in the associated Application profile. A. Select a key from the Available Key(s) list and then click Add to Output Key(s). B. To remove a key from the Output Key(s) list, select it and then click Remove Selected Key(s). 7. The Element Order tab lets you arrange the Data elements and Output Keys you have selected. Select an object from the list and then click either Move Up or Move Down. The APOM Profile Summary displays details about the APOM in the Profile Details area and all information for the APOM profile in XML format in the Profile Xml area. This tab is read-only.
86 Configuration Manager
Create a DataSet profile A DataSet profile acts as a parser for either input or output data. 1. From the Configuration Manager menu bar, select Configuration | Profiles and Tool Outputs | Create | DataSet. 2. In the Create New DataSet Profile dialog box enter an Alias (a short name for the profile that will help you identify it) and a longer Description. 3. (Optional) Change the OID and choose whether you want the OID displayed in decimal or hexadecimal notation. 4. Click OK. The DataSet Definition tab opens in the right pane. It lets you write two scripts: read and write. 5. Choose which script you want to work on, and then click Edit. 6. To write the script, enter JavaScript commands. You can click Apply Changes or Undo Changes at any time. After you click Apply Changes, you cannot undo any changes you applied and you must click Edit again to make additional changes. The Edit, Undo Changes, and Apply Changes buttons apply to all editable tabs for the profile. The DataSet Profile Summary displays details about the DataSet in the Profile Details area and all information for the DataSet profile (read script, write script, and identifying information) in XML format in the Profile Xml area. This tab is read-only.
87
Create a Job profile The Job profile specifies which input and output DataSets will be used at runtime as well as which product to execute. 1. From the Configuration Manager menu bar, select Configuration | Profiles and Tool Outputs | Create | Job. 2. In the Create New Job Profile dialog box enter an Alias (a short name for the profile that will help you identify it) and a longer Description. 3. (Optional) Change the OID and choose whether you want the OID displayed in decimal or hexadecimal notation. 4. Click OK. The Job Settings tab opens in the right pane. 5. Click Edit to begin making changes. You can click Apply Changes or Undo Changes at any time. After you click Apply Changes, you cannot undo any changes you applied. The Edit, Undo Changes, and Apply Changes buttons apply to all editable tabs for the profile. 6. Select the Input DataSet, Output DataSet, and Product to Execute from the lists. If you do not select a DataSet, the default DataSet will be used. 7. (Optional) Click Edit Product Selections Script. A Script Editor dialog box opens, in which you can enter JavaScript commands. For example, you might specify circumstances when a product other than the one you selected for Product to Execute would be used. 8. The Job Parameters tab lets you add or delete your own user-defined parameters. A. To add a parameter, click Add New Parameter, enter a name, choose an encoding type, and enter a default value. B. To delete a parameter that was previously added, select it and then click Delete Selected Parameter. The Job Profile Summary displays details about the Job in the Profile Details area and all information for the Job profile (input and output DataSets, the Product, and any Job Parameters you specified) in XML format in the Profile Xml area. This tab is read-only.
88
Configuration Manager
Create a Product profile The Product profile lets you choose which script fragments in which Application profiles will be executed. It also lets you specify the ordering of the process steps and control the input data for each script fragment. 1. From the Configuration Manager menu bar, select Configuration | Profiles and Tool Outputs | Create | Product. 2. In the Create New Product Profile dialog box enter an Alias (a short name for the profile that will help you identify it) and a longer Description. 3. (Optional) Change the OID and choose whether you want the OID displayed in decimal or hexadecimal notation. 4. Click OK. The Product Applications tab opens in the right pane. 5. Click Edit to begin making changes. You can click Apply Changes or Undo Changes at any time. After you click Apply Changes, you cannot undo any changes you applied. The Edit, Undo Changes, and Apply Changes buttons apply to all editable tabs for the profile. 6. To add an Application Instance, click Add Application Instance. A. In the Create New Application Instance dialog box select an Application Profile from the list. B. Enter the AID (Application Instance ID) published for the application. C. (Optional) Enter the Security Domain. D. Click OK. 7. Select from the list the ADT you want to use for this application instance. 8. To delete an Application Instance, select the instance you want to delete and click Remove Selected Application Instance. 9. The Product Process Steps tab lets you select which script fragments should be executed and the order in which they are executed. A. Select an application instance from the Step 1 pane. The script fragments in that application instance appear in the Step 2 pane. B. Select a script fragment from the Step 2 pane and then click Add to Current Process Steps. C. When all the required steps are listed in the bottom pane, place them in the order to be executed. To change the order, select a step and click Move Up or Move Down.
89
D. To view a script, select the process step and then click View Scripts. In the Script Editor dialog box, choose the script you want to view. Click OK or Cancel to close the Script Editor dialog box. E. To change a script, select the process step and then click Edit Scripts. In the Script Editor dialog box, choose the script you want to edit and then change or enter JavaScript commands. Click OK to save your changes or Cancel to close the Script Editor dialog box. 10. The Product Parameters tab lets you add your own parameters to the product. A. To add a parameter, click Add New Parameter, enter a name, choose an encoding type, and enter a default value. B. To delete a parameter that was previously added, select it and then click Delete Selected Parameter. 11. The Card Profiles tab lets you specify input and output card profiles by selecting from lists. The Product Profile Summary displays details about the Product in the Profile Details area and all information for the Product profile in XML format in the Profile Xml area. This tab is read-only.
90
Configuration Manager
91
E. Click Apply Changes to save the Product profile. VSDC and M/Chip4 only: If you are using Affina OSI software: A. In the Product Applications tab of the Product profile, click Edit and then select Add Application Instance. B. In the Create New Application Instance dialog box, for Application Profile select the appropriate application and for AID enter the AID of the Security Domain (see documentation from your card supplier for the value to use). Click OK. C. In the Product Applications tab, select Add Application Instance again. D. In the Create New Application Instance dialog box, for Application Profile select the Security Domain application profile and for AID and Security Domain enter the AID of the Security Domain instance. Click OK. E. In the Product Applications tab, for Select ADT for Application Instance, select the ADT you created in step 5. F. In the Product Process Steps tab, under Select Available Process Step, select the appropriate DataPrep script fragment and then click Add to Current Process Steps. G. Click Apply Changes to save the Product profile. 10. If necessary, add any Product-level configuration parameters. 11. Create a Job profile (see Create a Job profile on page 88 for step-by-step instructions). A. In the Job Settings tab, for Product to Execute, select the Product you created in step 9. B. Select Apply Changes to save the Job profile. 12. If necessary, add any Job-level configuration parameters. 13. Exit Configuration Manager.
92
Configuration Manager
93
5. If the input file includes a File Identification Record (FIR), select the File Identification Record check box. A. For the Identifier, enter the hexadecimal values of the identifier characters or click the ^ button to the right of the field, select each character by highlighting it, and then click OK until you have six Identifier characters. B. For the Number of Stop, select the appropriate value. 6. Under Record Separation, select the method used to separate records in the file. You must preface hexadecimal characters (such as 0D) with \x. If the file uses a fixed length, select Fixed Length and then enter the length of a record. If it uses a character sequence, select Character Sequence and then enter the sequence. For example, if it is #END#, enter #END#; if it is 0D 0A 0D 0A, enter \x0D\x0A\x0D\x0A.
7. Under Card/Carrier Data, select: Card Only if data contains only card data. Carrier Only if data contains only forms data. Card/Carrier if data contains both card and forms data.
For Carrier Data Field Location, select the location of the carrier data field from the menu list. 8. Click on the Data Fields tab at the upper left area of the window to display the Data Fields tab. 9. Under 9K Stream Field, click New. The Add New Stream Field dialog box opens. A. For the Field Name, enter a descriptive name such as Magstripe. B. For the Field Type, select Binary. C. For the Start of Field, verify that String is selected. D. For the String, enter the character used to identify the magnetic stripe data. For example, enter (quotation mark). E. For the End of Field, select the appropriate value from the pull-down list. F. Click OK.
94
10. Under Composite Field, click New. The New Composite Field dialog box opens. 11. For the Field Name, enter a descriptive name such as SC and then click OK. 12. The New Composite Field dialog box opens. Under Composite Field Result Properties, select Concatenate. For Affina PS A. In the first String field, enter the Job OID, for example: [2B0601040181900D88060501]. B. In the second String field, right-click in the String box and select dataField. From the list select Magstripe. C. Click OK. For MULTOS A. In the first String field, enter the MULTOS data and the Job OID, for example: <ONESTEP><JOBOID>2B0601040181900D88100503</ JOBOID><MAG>. B. In the second String field, right-click in the String box and then select dataField. From the list select Magstripe and then click the + button. C. In the third String field, enter </MAG></ONESTEP> and then click OK. 13. Click the Save icon in the Maxsys toolbar. The Save Document As dialog box opens. A. For File Name, enter a name for the specification. B. Click Save. Your setup appears in the left-hand pane and the name you specified appears at the top of the right-hand pane of the window. C. Click Close to close the Data Setup Configuration window.
95
96
For MULTOS For Setup Field Name, type SCRIPT. In the Value field, type the Format ID and application Name (including the delimiters < >).
\xFF\xFF\xFF\xFC<Multos>
Click Next. For Setup Field Name, type JobOID. In the Value field, type the Job OID (without delimiters). For example, type 2B0601040181900D88100503.
B. Select Exit. The Data Setup - APSsample window is displayed. 7. Select Actions, Append Field. The Append New Data Setup Field window appears. A. Select Composite, and then select OK. The Data Setup-Composite Field window appears. B. For Setup Field Name, type SMARTCRD. C. Select one of the following options: For Affina PS In Defined Fields, double-click the SCRIPT field and then the P3DATA data field. In the Field Contents field you will see the following: {SCRIPT}{Magstripe} For MULTOS a. Under Defined Fields, double-click the Script field and then: In the String field, enter <ONESTEP> and then click Insert. In the String field, enter <JOBOID> and then click Insert. Under Defined Fields, double-click JobOID. In the String field, enter </JOBOID> and then click Insert. In the String field, enter <MAG> and then click Insert. b. Under Defined Fields, double-click Magstripe. In the String field, enter </MAG> and then click Insert. In the String field, enter </ONESTEP> and then click Insert. In the Field Contents field you will see the following:
{Script}"<ONESTEP>""<JOBOID>"{JobOID}" </JOBOID>""<MAG>"{MAGSTRIPE}"<MAG>""</ONESTEP>"
97
D. Select Exit. The Data Setup window is displayed. 9. Select Actions, Append Field. The Append New Data Setup Field window appears. 10. Select Module Feedback, and then select OK. The Data Setup-Module Feedback Field window appears. A. Enter the Feedback fields listed below (select Next after entering each feedback field): ACCEPTCODE DLLERROR TIME AUDIT_1 AUDIT_2 AUDIT_3 AUDIT_4 AUDIT_5 AUDIT_6 AUDIT_7 AUDIT_8 B. For the final field, type AUDIT_9 and then select Exit. The Data Setup APSsample window is displayed. 11. Select File, Save, and then select File, Exit to close the Data Setup APSsample window.
98
99
c. Perform one of the following: For Affina PS In the Value field, type the Format ID, application Name (including the delimiters < >), and Job OID (including the delimiters [ ]). For example:
\xFF\xFF\xFF\xFC<AffinaPS>[2B0601040181900D876A0501]
For MULTOS In the Value field, type the Format ID and application Name (including the delimiters < >).
\xFF\xFF\xFF\xFC<Multos>
d. Click OK. For Affina PS, perform step D, and then skip to step 6. For MULTOS, perform steps E and F, and then proceed to step 6.
D. (Affina PS only) For Data Type, select Composite and then click OK. The Data Setup - Composite Field dialog box appears. a. For Field Name, type Smartcard. b. For Field Type, select Smartcard. c. Under Defined fields, double-click the Script field d. Under Defined Fields, double-click Magstripe. e. When complete, the Smartcard field value will be [Script][Magstripe]. f. Click OK.
E. (MULTOS only) For Data Type, select Composite and then click OK. The Data Setup - Composite Field dialog box appears. a. For Field Name, type 1Step. b. For Field Type, select Other. c. For Value: In the String field, enter <JOBOID> and the JobOID and then click Insert. In the String field, enter </JOBOID> and then click Insert. In the String field, enter <MAG> and then click Insert. d. Under Defined Fields, double-click Magstripe.
100
In the String field, enter </MAG> and click Insert. e. When complete, the following string will be created:
"<JOBOID> 2B0601040181900D88100503""</ JOBOID>" "<MAG>"{Mag}"</MAG>"
F. (MULTOS only) For Data Type, select Composite and then click OK. The Data Setup - Composite Field dialog box appears. a. For Field Name, type Smartcard. b. For Field Type, select Smartcard. c. Under Defined fields, double-click the Script field d. In the String field, enter <ONESTEP> and then click Insert. e. Under Defined Fields, double-click 1Step. f. In the String field, enter </ONESTEP> and then click Insert.
h. Click OK. 6. Click OK to close the NK Simulator Data Setup - APS dialog box. 7. Click Exit to close the Data Setup dialog box.
101
102
Production Setup
You will use the Batch Administrator application to create a production setup for each distinct smart card product you produce. The production setup specifies the directory in which input files will be placed, the DLL to use in parsing the information in the input file, the fields contained in each input record, additional fields to be generated during data preparation, the order in which processes are to be performed, and how the output file is to be stored.
103
Batch Administrator also has facilities for maintenance tasks, such as purging log files and printing reports.
Batch Production
During card production, Batch Engine and Batch Import must be running on your Affina DP computer. If you have created any production setups, Batch Engine and Batch Import will start automatically when you start your computer. You can minimize the windows.
Batch Tracking
While you are setting up and testing your Affina DP environment, it may be useful to run the Batch Tracking application. Batch Tracking shows the progress and results of each job you run. If any errors occur, you can view them by clicking the input file in Batch Tracking.
104
To view general information about a job, such as when the input file was received and when the job was completed, click the input file. To see additional job information, such as the number of records in the job, click the output file name. When the output file is selected, click the Job Data tab to view the data for each record, including each field in the output that is Loaded and not Hidden.
105
INDEX INTEGER LEFT LONG MAX MONEY NULL OPTION PERCENT RAW REVOKE SAVEPOINT SHORTINT STRING TIME TRUNCATE VALUE WHERE
INNER INTEGER4 LOCK LONGBINARY MEMO NAMES NUMBER ORDER PIVOT REAL RIGHT SELECT SINGLE TABLE TIMESTAMP UNION VALUES WITH
INSERT JOIN LOGICAL LONGINTEGER1 MIN NOAUDIT NUMERIC OWNER PRIMARY REFERENCES ROLE SET SMALLINT TEXT TRANSACTION UNIQUE VAR YESNO
INT KEY LOGICAL1 LONGTEXT MOD NOT OLEOBJECT PARAMETERS PROCEDURE RENAME ROLLBACK SHORT SOME TEXTALTER TRANSFORM UPDATE VARBINARY
1. Sample data and scripts included in this product are intended only as a supplement to the documentation. THIS MATERIAL AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
106
correctly installed. Also, performing these steps provides a good way to learn the steps you will need to do when setting up your own solution. See MChip4_ReleaseNote.rtf, MICA_MChip4_PayPass_ReleaseNote.rtf, or VSDC_ReleaseNote.rtf in the ...\Profiles\Release directory for important information about configuring the Application Profile you are using.
1. Start the Batch Administrator (on the Launcher, click Batch Administrator). 2. From the menu bar select Setup | Production Setup. The Select Production dialog box opens. 3. Click Restore. The Restore Production Setup dialog box opens. 4. Navigate to \Program Files\Datacard\ADP\Samples\Batch, select the .BATCH file for the production setup you want to use (for example, VSDC Sample.BATCH), and then click Open.
107
5. Under Identifier, change the Production Label to an appropriate name (for example, VSDC Sample), click Save, and then click Exit two times. Exit Batch Administrator. 6. Start Batch Engine and Batch Import (on the Launcher, click Batch Production). 7. Using Windows Explorer, go to \Program Files\Datacard\ADP\Batch, copy the single-record input file for the production setup you are using (1_VSDC.dat in the example), and paste it into Program Files\Datacard\ ADP\Batch\Input\VSDC. 8. Start Batch Tracking (on the Launcher, click Batch Tracking).
108
9. Expand the Sample folder for the production setup you are using (VSDC Sample in the illustration). The single-record input file (1_VSDC.dat) should be green. If it is still blue, click Refresh. If it is any other color, there is a problem with your installation. 10. To view the data produced, click the lowest branch of the job name and then click the Job Data tab.
109
Set up the Batch Engine (Optional Task) You can specify the label of the Batch Engine that will appear in dialog boxes referring to the Engine, view information about the server where the Engine is installed, and specify directories to be used during processing. 1. In the Batch Administrator menu bar, select Modules | Batch Engine | Batch Engine. - or In the Batch Engine menu bar, select Setup | Setup Batch Engine. 2. To change the label of the Batch Engine, in the Application Information area, type the label you want displayed to users. 3. To view the name of the server, click Refresh next to the Host Name text box. 4. To change the Listen Port Service, type the new port number in the text box. 5. To change the maximum number of processes that can be run simultaneously, type the new number in the text box. 6. To change directories used during processing, click Browse next to the directory you want to change, navigate to the directory you want to use, and click OK. The Input Shared, Input Temp, and Output Temp directories are purged automatically after processing the input file. Input files with errors will be stored in the Error Directory. 7. Click Save and then click Exit. Set up Job Mnemonics (Optional Task) The Job Mnemonics dialog box displays all the constants in the File Identification Records (FIRs) recognized by the system when processing input files. The standard CSM mnemonics are loaded during installation. If a mnemonic is not defined in the list, it will be added automatically by the Batch Engine when processing a file containing the new mnemonic.
To add a mnemonic manually
1. In the Batch Administrator menu bar, select System | Job Mnemonic Setup. 2. Click the Add button. A new row becomes available. 3. Type the mnemonic, press the T AB key, and type a description. 4. Click Save and then click Exit.
110
To delete a mnemonic
1. Click anywhere in the row and click Delete. 2. Click Save and then click Exit.
To back up the list of mnemonics
1. Click Backup. 2. In the Backup File dialog box, browse to the location where you want the backup stored. 3. Change the suggested file name if necessary. 4. Click Open.
To restore the list of mnemonics
1. Click Restore. 2. In the Restore File dialog box, browse to the location where the backup is stored and select it. 3. Click Open. 4. Click Save and then click Exit. Set up job status colors (Optional Task) You can define the display colors for the various states of each file processing step visible in the Batch Tracking application.
To access the Status Color Setup dialog box
In the Batch Administrator menu bar, select System | Status Color Setup.
111
Status Definitions
Status Not made Started Hold Done ReStarted Rejected ReAffected Aborted
To select a new color to illustrate a step
Description Not performed. Started. Temporarily suspended by the user. Completed. Restarted following a temporary suspension. Rejected because an error occurred. Re-made (for a job or a card that is reproduced following an error). Canceled due to a production obstacle.
1. Double-click the colored area. The Color dialog box opens. 2. Click the color you want displayed and then click OK. 3. Click Save and then click Exit. Select a language You can choose the language of the Batch application user interfaces. 1. From the Batch Administrator menu bar select Utilities | Setup Language. 2. Select the language for the user interface and then click Save.
112
113
In_Ref_MC4.dll, In_Ref_VSDC.dll, and In_Ref_Xml.dll (for use if the imported file is in XML format). An input DLL can be used for multiple product setups that use the same record separator. In_Ref_DTE.dll, In_Ref_MC4.dll, and In_Ref_VSDC.dll are copies of In_Ref.dll with different record separator specifications. (See Change the input DLL record separator.) G. In the Max Consecutive Errors field, select the maximum number of consecutive input data errors that can occur before the job is rejected. H. To have the system check for and reject duplicate input files, select Check Duplicated Files. The method for checking for duplicates is based on the file contents, not just on the file name. Thus, any file whose size or checksum is identical to an existing file in the database will be rejected if Check Duplicated Files is selected. I. To save rejected files in an error folder, select Archive Error File. Each time a file fails, a sequentially-numbered folder will be created in the Program Files\Datacard\ADP\File Handler\Files\Error directory. Within that folder, the input file will be stored with the name input file name_yyyymmdd_hhmmss.ext where input file name is the original input file name; yyyymmdd is the year, month, and day the file processing job was started; hhmmss is the hour, minute, second when the file processing job was started; and ext is the extension of the input file. J. In the Input Processing area, select the name of the Batch Engine processing module from the list. (If only one module is installed, there will be no list.) K. To allow the engine to activate the import process, select Enabled. (If only one module is installed, the check box will be selected.) L. In the Time Out column, enter the number of seconds after which the processing will be considered as failed for taking too much time. If a process times out, it will be interrupted and the data saved in the ADP database will be erased. A 0 (zero) in the Time Out column means processing can continue indefinitely. M. In the Max Error column, enter the maximum number of consecutively rejected files after which processing will be stopped. If this number is reached, you must restart the engine to continue processing. A 0 (zero) in the Max Error column means processing can continue indefinitely. N. In the Max Proc column, enter the maximum number of files that can be processed simultaneously. Simultaneous processing optimizes file processing time by running tasks in parallel. The number of tasks run in
114
parallel depends on the available CPU time on the machine hosting the program. O. To archive processed input files, select Enabled in the Archive Input File area. Browse to the directory where you want the files archived and then click OK. Archived input files will be stored in the Program Files\Datacard\ADP\Batch directory. Within that folder, the input file will be stored with the name input file name_yyyymmdd_hhmmss.ext where input file name is the original input file name; yyyymmdd is the year, month, and day the file processing job was started; hhmmss is the hour, minute, second when the file processing job was started; and ext is the extension of the input file. 5. In the Input Data Fields tab: A. Click Add. The New Field dialog box opens. B. Select the kind of field you want to add: Data Formula Generated Generated Data Field resulting from the input file. Field calculated in the Batch Engine using JavaScript expressions. Field generated by the Data Transformation Engine DLL. Field generated directly by the Input DLL (for example, a security field).
C. Click OK. A field named Field_1 is added to the FieldName list. D. Change the name of the new field to something meaningful (do not use any of the words listed in Reserved Words for Input Fields on page 105) and then press the E NTER key. The name you entered appears in the Data Field Name text box. E. Select the appropriate check boxes: O (Optional) Select if the field is not always present in the file (not available for Formula fields).
115
H (Hidden) L (Loaded)
Select to make the field invisible in the Batch Tracking module. Select for fields that should be loaded into the database. Loading data may be useful for troubleshooting. Conversely, not loading data will prevent the database from filling up as quickly. Your system will operate correctly without loading fields in the database.
F. (Optional) Enter a longer description of the field. G. For Data fields, select the Start and End Definitions: Position Code Enter the start/end position of the field, where the first position of the record is set to 1. Enter the code (delimiter) to identify the start or end of the field. Do not use the \ character; it is used to specify binary values. Example: % and & Enter the total length of the field (as a number). Select if a length is embedded in the field. Enter the number of characters that indicate the data length. Example: [SCM]0000013ZONESMARTCARD Start Code: [SCM] Embedded Value Length: 7 Field Length: 13 characters Field Value: ZONESMARTCARD Select if the field continues to the end of the record.
Length Embedded
End of Record
You can use a file containing a sample record to determine start and end positions for fields. Click Sample Record and browse to a file that contains a single record with the structure of the records in your data file. The sample file should not have a header (FIR), so you can find the positions of the various fields directly from the start of the file. When you select the field in the window, the fields Start Position, Length, and End Position are displayed in the Sample Data area to the right. Right-click and select a command (Add or Modify) and a Start and End Definition method. A new record is added to the list of fields or, if you chose Modify, the record that was highlighted is changed to reflect your selections. For Formula fields, click Expression. The Formula Field dialog box opens. H. (Data Fields only) For Output, if the start definition is a code, you have the option of copying the start code and/or end code field definitions to the
116 Affina DP (Batch) Setup
output field. Select Use field definitions in output to copy the start code to the output field. In addition, you can select Copy field end code in output to copy the end code to the output field. I. Select the appropriate field format, which determines how the field will be stored in the database and what kind of type checking will be done against the data. (If the data read does not match its declared type, an error occurs and the file is rejected.) Binary Data Char Data Digit Hexadecimal No checks. Any printable ASCII character is allowed. 0 to 9 allowed. 0 to 9 and A to F allowed.
6. On the Chained Process tab, you can specify how processes are linked together: sequentially or in parallel. A. To add a process to the list, click Add. The Select Process dialog box opens. B. Choose one of the process types, DLL or Formula, and then select from the list of available processes. After you click OK, the process appears in the Process list. (For DLLs, the Input DLL you specified on the Input Files tab is the process that appears in the list.) C. To move a DLL or formula up or down the production chain, select it and then click the up or down arrow buttons. D. To have two processes run in parallel, place them one after the other in the Processes list and then select Parallel for each one. 7. On the Dispatching tab: A. To change the Job File Name that will be created: a. Click Expression. The Formula Field dialog box opens. b. Select from the list of fields, unique indexes (for the production job, IDX_JOB, and the input file, IDX_IN_FILE), and functions defined in the system or enter a valid string at the keyboard. The file name must not contain the following characters: \ / : * ? " < > | c. To confirm the formula and close the Field Formula dialog box, click Save Script. The formula is updated in the Job File Name field.
117
B. To add a header record to the production file, select Add FIR and then, in the FIR Definition area, enter the file header ID string and the field separator that will be used for header information. C. Specify the record delimiter. You can mix ASCII and binary characters. For example, [END]\x0D\x0A means [END] followed by a carriage return-line feed. D. Specify the directory where all production files will be created by entering the full path or browsing to the directory. If your input data has multiple FIRs, you can merge the output data into a single file by selecting Merge Job. E. In the Error Output Directory area, select whether you want the program to save the error records and, if so, enter the full path or browse to the directory where you want the error records saved. F. In the Error Handling area: a. Select Skip Record to prevent the inclusion of bad records in the output file. b. Select Copy Input Record to Output File to copy the original input record (without any smart card data) to the output file. c. Select Add Template to Output File to use a bad record template to format the output file. Create a bad record template (the format will depend on the requirements of your system), and then click From File to browse to the location of the template file. Click Clear to remove the template information. G. In the Production Record area, select those fields from the left column (the ones you defined in the Input Data Fields tab) that should be in the record used for card production. You must select one field at a time and then click Add. After fields are copied to the right column, you can re-order them by selecting a field and clicking the up or down arrow button. H. In the Record Order area you define how the output file records will be sorted: a. Click Add. A Char field appears. b. Click Add again and select a different Char field from the list. Repeat this step until all relevant fields have been selected. c. Select the field that will have the highest precedence and, if necessary, click the up arrow until it is at the top of the list. Repeat until the fields are in the correct order. d. For each field, select ASC if it should be sorted in ascending order or select DESC if it should be sorted in descending order.
118 Affina DP (Batch) Setup
8. Click Save to save your setup or click Cancel to delete it. Back up a production setup Datacard recommends that you back up your production setups to removable media. 1. From the Batch Administrator menu bar select Setup | Production Setup. 2. In the Select Production dialog box select a setup from the Production List and then click Backup. 3. Browse to the location where you want the backup stored and then click Open. Delete a production setup You can delete a production setup that is no longer used. 1. Purge input files associated with the production setup. (See Purge input files on page 121.) 2. From the Batch Administrator menu bar select Setup | Production Setup. 3. In the Select Production Setup dialog box, select the production setup you want to delete and then click Delete. Change the input DLL record separator You can change the record separator specified by the input DLL if your environment requires it. 1. Use Windows Explorer to copy In_Ref.dll under a different name and In_Ref.ini under a corresponding name. The In_Ref.dll and In_Ref.ini files are stored in the \Program Files\Datacard\ADP\File Handler\DLL\Input directory. 2. From the Batch Administrator menu, select DLL | Input DLL. 3. In the Setup DLL dialog box, select the DLL you want to change and then click Setting. 4. In the Display Ini dialog box, expand RECORD and then click Rec_Mark. 5. In the Rec_Mark area, change the record separator as required and then click Save. 6. Click Exit in the Display Ini dialog box and again in the Setup DLL dialog box.
119
Monitoring Tasks
View event logs You can view Batch Application event logs if your user name belongs to a group with that privilege. 1. From the Batch Administrator menu bar select Utilities | View Log. 2. Select the log you want to view. Log entries appear with the most recent at the top of the list. View user actions You can view a list of all user actions on the Affina DP server if your user name belongs to a group with that privilege. 1. From the Batch Administrator menu bar select Utilities | View User Action. 2. Select the module for which you want to review user actions. Actions appear with the most recent at the top of the list. Create a File Error report Run-time Crystal Reports must be installed to perform this task. You can create a report explaining the file errors encountered when preparing data. 1. From the Batch Administrator menu bar select Report | File Error or A4 File Error. The BATCH_Report (File Error) dialog box opens. 2. Enter or select the start and end dates for the report, and then click Preview. 3. To print the report, click the Print Report button in the left-most position of the toolbar. Create a File Summary report You can create a report summarizing the files processed with a specified Production Setup. 1. From the Batch Administrator menu bar select Report | File Summary or A4 File Summary. The BATCH_Report (File Summary) dialog box opens. 2. Select a Production Setup from the list, and then click Preview. 3. To print the report, click the Print Report button in the left-most position of the toolbar.
120 Affina DP (Batch) Setup
Create a User Access report You can create a report that lists all user access events in a specified period. 1. From the Batch Administrator menu bar select Report | User Access or A4 User Access. The BATCH_Report (User Access) dialog box opens. 2. Enter or select the start and end dates for the report, and then click Preview. 3. To print the report, click the Print Report button in the left-most position of the toolbar.
Maintenance Tasks
Purge user actions You can remove user actions from the database, reducing disk space required, if your user name belongs to a group with that privilege. 1. From the Batch Administrator menu bar select Utilities | Purge User Action. 2. Select or type the date of the oldest user action you want to retain. 3. Click Clean. Purge input files You can remove input files from the database, reducing disk space required, if your user name belongs to a group with that privilege. 1. From the Batch Administrator menu bar select Utilities | Purge Input File. 2. Select the production setup for which you want to remove input files. 3. Select or type the date of the oldest input file you want to retain. 4. Click Clean.
Reset the SQL user for Batch applications password 1. Close any Batch applications that are running. 2. Use SQL Server Management Studio to change the adp user password: A. From the Start menu, select All Programs | Microsoft SQL Server 2005/8 | SQL Server Management Studio. B. If necessary, select the Server name and Authentication method, and then click Connect. C. In the Object Explorer pane, double-click Security and then double-click Logins. D. Under Logins, double-click adp. E. In the Login Properties adp dialog box, enter the new password in the Password and Confirm Password fields and then click OK. 3. Open the file \Datacard\ADP\File Handler\Batch_Admin.ini and delete the following line from the file:
122
BATCH=DB_LINK
4. Save the file. 5. Double-click the program \Datacard\ADP\File Handler\ Batch_Admin.exe. A. In the Connection String dialog box click Build. B. In the Data Link Properties dialog box, for Provider select Microsoft OLE DB Provider for SQL Server and then click Next. C. Click Connection. D. Click the arrow under server name and select your SQL Server instance name. E. For User name, enter adp. F. For Password, enter your password. The default password is Datacard2010. Be sure to use a complex password. G. For database, select ADP. H. Click Test Connection. If the Test Connection Succeeded dialog box appears, click OK. Otherwise, correct your settings and try again. I. Click OK.
J. Click OK. The connection string shown in the dialog box will be saved in the \Datacard\ADP\File Handler\DB_LINK file and will be immediately encrypted by the Batch_Admin.exe application. K. If the Batch Admin application reports a login failure for user adp, repeat the steps above until you are able to log in successfully.
123
124
Chapter 8: Maintenance
This chapter offers suggestions for on-going maintenance and trouble-shooting.
Depending on how your products are set up and your production volume, you may accumulate large amounts of historical data in your Affina system. Periodic purging of unnecessary data can reduce the amount of disk space required. Datacard recommends that you establish a regular schedule for backing up your Databases and for backing up, archiving, or purging your Event Logs. The frequency of your backups will vary depending on your production volume. High volume users may need to back up as often as once a month.
Databases
The Affina installation program installs the ADP database. Use your SQL Server product to back up and maintain your database.
Event Logs
Affina DP uses two types of event logs: Windows Event Logging and Application Logs.
125
Application Logs
The Affina DP Batch Applications and Affina Key Management System keep logs of activity and errors. If you call Datacard Smart Card Support for help in resolving a problem, you may be asked to send copies of your logs to assist in troubleshooting.
126
Maintenance
Chapter 9: Troubleshooting
This appendix lists problems you may encounter when setting up your Affina Data Preparation or Affina One Step Issuance environment, along with possible solutions.
This appendix is not meant to be read from beginning to end. Instead, use the Find function in Adobe Reader to search for your error.
Possible Solution: Recreate the data link for all Batch applications as described in Resetting the SQL user password for Batch applications on page 122. Running reports from Batch Administrator gives an error message: Class not registered. Probable Cause: Crystal Report Run-time is not installed. Solution: Install the Crystal Reports Run-time from the installation CD. See Install Runtime Crystal Reports 11 on page 9.
127
GPError: DataElement [ ... ] is ReadOnly Investigation: Check the Windows Event Viewer under Datacard Affina for an error message similar to the following: ERROR [Thread-5] (PSRuntime.java:606) - GPError: MagStripe mapping: org.mozilla.javascript.EcmaError: GPError: DataElement [CardholderName] is readOnly (_2B0601040181900D88060401#15) Probable Cause: A Data Element in the APIM or ADT has been set as ReadOnly and data had been passed in the input data file or parsed from the magnetic stripe data by the default parser which does not match the value defined in the ADT or APIM. Possible Solution: Uncheck Read-Only in the ADT or APIM. To change a value typically parsed from the magnetic stripe data, change the value in the input file. Tracking returns an error Script Failed and Error returned by the function Compute File Investigation: Check the Windows Event Viewer under Datacard Affina for errors. Possible Solutions: If the message in Event Viewer is: Failed to Load Object <nnnnnnnn>, then Object <nnnnnnnn> is missing from Configuration Manager or specified incorrectly in the Batch Administrator Production Setup. 1. Verify that field definitions in the Production Setup match objects loaded in Configuration Manager. A. Start the Configuration Manager. B. Start the Batch Administrator application, edit the Production Setup, and click the Input Data Fields tab. C. Check that all field definitions in the Fields Definition area match the corresponding objects in Configuration Manager. For example, the Job OID in the Production Setup Input Data fields tab must match the Job OID in Configuration Manager, as in the following illustration. If it does not, change the Production Setup to match Configuration Manager.
128
Troubleshooting
2. Verify that Rec_Mark specified in your input DLL matches the end of record identifier in your input file. A. Start the Batch Administrator application, edit the Production Setup, and click the Input Files tab. Note the Input DLL specified in the Input Process area. B. Click the Input Data Fields tab, click Sample Record, navigate to a data file that contains a single record, and click Open. Note the end of record identifier. Common values are #END# and [END]\x0D\x0A. C. Close the Production Setup and, from the menu bar, select DLL | Input DLL. D. In the Setup DLL dialog box select the Input DLL you noted in step A, and then click Setting. E. In the Display Ini dialog box, expand RECORD. F. If the value does not match what you noted in step B above, do one of the following: If no other Production Setups use the DLL, use the Display Ini dialog box to change the Rec_Mark value. Select a DLL that has the correct Rec_Mark value. Change the Input DLL specification in the Production Setup. If other Production Setups use the DLL, use Windows Explorer to save copies of the DLL and its associated INI file under a different file name. Use the Display Ini dialog box to change the Rec_Mark value in the copied INI file. Change the Input DLL specification in the Production Setup. Change the end of record identifier in your input file.
129
3. Verify that all necessary keys exist in the Key Management System. Tracking returns an error: Error Loading DLL Investigation: Verify that the Input DLL and/or its associated INI file specified in the Production Setup Input Files tab exists in the Program Files\Datacard\ ADP\File Handler\DLL\Input directory.
Possible Solution: If the Input DLL and/or its associated INI file does not exist, use Windows Explorer to save copies of In_Ref.dll and In_Ref.ini under the file name specified in the Production Setup Input Files tab. If necessary, use the Display Ini dialog box (from the menu bar, select DLL | Input DLL) to change the Rec_Mark value in the copied INI file.
130 Troubleshooting
Tracking reports an error: Error in opening Table Card request Investigation: Drilling down on the item displays a message: SELECT permission denied on object TB_CARD_RQT_2 database ADP. Probable Cause: This may happen if the user is not logged in as an Administrator. Possible Solution: Log in as an Administrator, go to the Program Files\Datacard\ ADP\Database folder and run RunPatchForRQT2AccessDenied.cmd to update the access permission for this dynamically created table. Tracking reports an error: Field <field name> not found Probable Cause: The Production Setup for the job has a field defined on the Input Data Fields tab that was not found in the input data. Possible Solution: Change your Production Setup to match your input data. Batch Import reports an error: No productions are defined Probable Cause: No production setups have been created or restored. Possible Solution: Use the Batch Administrator program to create or restore a Production Setup. If Batch Engine is running, close it, and then start Batch Production. Batch Administrator reports an error: Login failed for user adp Probable Cause: Affina issuance software has just been installed and SQL Server was not in Mixed Mode. Possible Solution: Restart SQL Server or the computer so that SQL Server will be running in Mixed Mode.
131
4. Expand SQL Native Client Configuration, enable TCP/IP, and make it first in Order.
132
Troubleshooting
5. Restart the SQL Server 2005 services. Make sure SQL Server and the SQL Server Browser service is running.
When attempting to start Configuration Manager, the error message Unauthorized Access You are not authorized to run Configuration Manager appears. Probable Cause: You must be a member of the ADP_Administrator, ADP_Supervisor, or ADP_Operator group, or running As Administrator to run Configuration Manager. Possible Solution: Add the user to one of the groups listed above. When attempting to import files, the following error message is returned: java.SQLException: Unable to get information from SQL Server: ComputerName Possible Cause: You are using a named instance of SQL Server and the SQL Server Browser service is not running. For example, your SQL Server instance name is ComputerName\SQLEXPRESS. Possible Solution: Enable and start the SQL Server Browser service as described in the Affina Issuance Release Notes under the Limitations section.
133
KMS Problems
After starting the KMS, the Token Navigator is empty or displays an error Probable Cause: The Crypto Server name is not correct Possible Solution: Run Affina Issuance Setup (Start | Programs | Datacard| Affina Issuance Software | Affina Issuance Setup), verify that the Name of the Server containing the Crypto board is entered correctly, and then click Close. Restart the KMS. 0x00000101 - CKR_USER_NOT_LOGGED_IN Possible Cause: The User(s) must be logged in to perform the requested action. Possible Solution: Log in to the token as User(s). 0x80000106 - CKR_SO_NOT_LOGGED_IN Possible Cause: The Security Officer(s) must be logged in to perform the requested action. Possible Solution: Log in to the token as Security Officer(s). 0x00000110 - CKR_WRAPPED_KEY_INVALID Possible Cause: The import or unwrap key being used for the requested action is the wrong one or the wrong type. Possible Solution: Select the appropriate key and try the function again. 0x000000D1 - CKR_TEMPLATE_INCONSISTENT Possible Cause: A usage has been defined that is not allowed by a Template such as one defined by an Unwrap mask. Possible Solution: Unwrap the key using an unwrap key with a mask that will allow the required action to be performed. Saving Problems Unable to store workbench state. Probable Cause: You must be a member of the Administrators, ADP_Administrator, ADP_Supervisor, or ADP_Operator group, or running As Administrator to run Affina KMS. Possible Solution: Add the user to one of the groups listed above.
134
Troubleshooting
135
136
Troubleshooting
137
138
Troubleshooting
139
140
Troubleshooting
Term ADT AID ALU APIM APOM BER-TLV BIN CM CU DDA DES DGI DP DTE ECMAScript EMV GP
Definition Application Data Template Application Identifier; composed of the RID and the PIX Application Load Unit Application Profile Input Mapping Application Profile Output Mapping Basic Encoding Rules-Tag Length Value Bank Identification Number Configuration Manager Customization Utility (MasterCard) Dynamic Data Authentication Data Encryption Standard Data Grouping Identifier Datacard Affina Data Preparation software Data Transformation Engine A standard scripting language defined by the European Computer Manufacturers Association Europay MasterCard Visa smart card standard GlobalPlatform
141
Definition Host (or Hardware) Security Module Key Check Value, a way of distinguishing cryptographic keys from each other without revealing plain text values Key Management System, part of ADP The MasterCard implementation of the EMV specifications The MasterCard implementation of the EMV specifications for use on smart cards that use the MULTOS operating system MasterCard Customization Utility Message Authentication Code MasterCard Integrated Card Application Universal Object Identifier Primary Account Number Proprietary Identifier; freely assigned by the RID owner Public Key Cryptography Standards Registered Identifier (of the application provider) Encryption algorithm developed by Rivest, Shamir, and Adelman Static Data Authentication VSDC Personalization Assistant Visa Smart Debit Credit, the Visa implementation of the EMV2000 specification Extensible Markup Language, defined by W3C
MC/CU MAC MICA OID PAN PIX PKCS RID RSA SDA VPA VSDC XML
142
Configuration Parameters
Configuration parameters are stored in the com.datacard.properties file which is installed in the ...\Program Files\Datacard\ADP\Java directory. Parameters preceded by a # character are ignored. In One Step mode, Object Communicator must be restarted after changes are made to configuration parameters.
143
A detailed description of how to set the format of the data returned in debug mode can be found at: http://logging.appache.org/log4j/1.2/apidocs/org/ appache/log4j/PatternLayout.html Example:
#log4j.rootCategory=debug, stdout, ps log4j.rootCategory=error, stdout, eventViewer log4j.appender.ps=org.apache.log4j.RollingFileAppender log4j.appender.ps.File=C:/Program Files/Datacard/ADP/Affina.data/adp_ps.log log4j.appender.ps.layout=org.apache.log4j.PatternLayout log4j.appender.ps.layout.ConversionPattern=%5r %5p [%t] (%F:%L) - %m%n log4j.appender.stdout=org.apache.log4j.ConsoleAppender log4j.appender.stdout.layout=org.apache.log4j.PatternLayout #log4j.appender.stdout.layout.ConversionPattern=%6r %5p [%t] (%F:%L) - %m%n log4j.appender.stdout.layout.ConversionPattern=%m%n log4j.appender.eventViewer=com.datacard.ps.EventLogAppender log4j.appender.eventViewer.layout=org.apache.log4j.PatternLayout log4j.appender.eventViewer.layout.ConversionPattern=%6p [%t] (%F:%L) - %m%n
144
Runtime Properties
When the COMPLIANT_BER parameter is set to True, the system will enforce BER-TLV compliance for all Jobs running on the system. As a result, any TLV that is not BER-TLV compliant will generate a TLV exception. Example:
COMPLIANT_BER=true
145
146