This documents contains updates/corrections to publication SA34-2205: "4777 Magnetic Stripe Unit and 4778 PIN-Pad Magnetic Stripe Reader OS/2 Programming Guide" ;;-------------------------------------------------------------------------;; ;; Following information missing from Chapter 5 of the programmers guide. ;; ;; It explains the format of the 4777 encode data. ;; ;; ;; ;;-------------------------------------------------------------------------;; DESCRIBING THE FORMAT FOR THE ENCODE DATA: ------------------------------------------ The 4777 can support both single-track encoding and dual-track encoding, depending on the device. For the dual-track encoding to succeed, the 4777 must be capable of encoding multiple tracks when using the dual-track encode format. The application program supplies the data that the 4777 device-support code uses to form and calculate the correct parity for the output data characters. The character-definition field of the device-parameter table defines the output data bits. They are the low-order bits of the application program data. For example, if the character definition field of the device parameter tables is set to 5-bits per character, the output data character is the low-order 4 bits of the application program data bytes. The entire output character consists of the data bits plus the parity bit. For example, if a data byte with a value of 35H (0011010lB) passes to the 4777 device-support code for encoding on a magnetic stripe, the possible binary output values for the device are as follows: * P0101 for 5-bits per character * P10101 for 6-bits per character * P110101 for 7-bits per character where P represents the parity bit. Using the PSOM and the PEOM characters from the track parameters, the 4777 device-support code adds the SOM and the EOM characters to the application program data stream. The 4777 device-support code also calculates the LRC value and adds it to the data stream. For more information about the track parameters, see "Loading the Device Parameters (MagLoadDevParms)". A read head that is within the device permits a read back of the encoded data. For a successful comparison, the 4777 device-support code reads all the tracks and compares the data, including double records if they are specified. If the data comparison is successful, the encode operation ends. If the data comparison fails, the red light on the 4777 is switched on and the green light continues to flash. The operator can continue making encode attempts until one succeeds, or the application program can issue the MagAbort function call to cancel the MagEncodeData function call. The 4777 device-support code accumulates the number of encode failures. The application program can read this number with the MagReadErrorStats function call. Figure 4-4 shows the format of the single-track encode data and Figure 4-5 shows the format of the dual-track encode data. ------------------- | Lx | TRKx | DATAx | ------------------- Figure 4-4. Single-Track Encode Data Format --------------------------------------- | Lx | TRKx | DATAx | Ly | TRKy | DATAy | --------------------------------------- Figure 4-5. Dual-Track Encode Data Format The descriptions of the fields for the single-track and dual-track encode data formats are as follows: FIELD MEANING ----- ------- L Each L field represents a 1-byte field that defines the length of the respective TRK and DATA fields. The L field is not included in the length count. TRK Each TRK field represents a 1-byte field that identifies the track that is associated with the respective DATA field. Each TRK field can have only one corresponding track specified. If the field contains more than one track, an error is returned to the application program and the request ends. The definitions of the bits in the TRK field are as follows: BIT NUMBER DESCRIPTION ------ ----------- 7-3 These bits are reserved. 2 This bit indicates that the data is to he encoded on track 1 1 This bit indicates that the data is to he encoded on track 2 0 This bit indicates that the data is to he encoded on track 3 DATA Each DATA field represents, in hexadecimal, the respective track data to be encoded on the magnetic medium. The 4777 device-support code adds the SOM, the EOM, the parity bits, and the LRC characters into the data stream and sends the data to the 4777. PERFORMING AN ENCODE OPERATION: ------------------------------ This sections describes the default device-track parameters for an encode operation and the device lights that indicate the operating conditions of the 4777. The 4777 device support code automatically sets the default device-track parameters for an encode operation when the application program issues a MagOpen function call. The default parameters depend on what model of the 4777 is attached when you install the 4777 device driver. For the 4777 device driver, the defaults for MagEncodeData function call and their corresponding tracks are as follows: TRACK 1 ENCODE -------------- - Records written = single - Leading zero bits = 70 (10 magnetic characters) - Bits per character = 07 - Data parity = Odd - LRC parity = Even TRACK 2 ENCODE -------------- - Records written = double for Model 2 - Records written = single for Model 3 - Leading zero bits = 300 (60 magnetic characters) for Model 2 - Leading zero bits = 25 (05 magnetic characters) for Model 3 - Inter-record zero bits = 25 (5 magnetic characters) - Bits per character = 05 - Data parity = Odd - LRC parity = Even TRACK 3 ENCODE -------------- - Records written = double - Leading zero bits = 300 (60 magnetic characters) - Inter-record zero bits = 25 (5 magnetic characters) - Bits per character = 05 - Data parity = Odd - LRC parity = Even USER-SPECIFIED OPERATION: ------------------------ Your application program can override the default parameters and set new parameters in the 4777 device-support code. To load the 4777 parameters, the application program issues the MagLoadDevParms function call. This function call sets the operational parameters of the 4777 and determines how the data passes to and from each track. DEVICE LIGHTS FOR ENCODING OPERATIONS: -------------------------------------- The lights on the 4777 indicate the operating condition of the device. The operating condition of the device is one of the following: - Flashing Green Light (Ready to Encode) When the application program issues a MagEncodeData function call, the green light flashes two or three times per second. You can now pass the medium through the encoder. After the medium passes through the encoder, the green light goes off and the yellow light comes on. - Yellow Light (In Process - WAIT) The yellow light comes on after the medium passes through the encoder. It stays on until the read-back check on the data completes by the device-support code. The red light comes on if the 4777 device-support code detects an error. - Red Light (Error Detected - RETRY) When the red light remains on, the device read-back check has been unsuccessful. The red light remains on until : - A subsequent, successful encode occurs. - The application program issues a MagAbort function call to cancel the operation. ;;-------------------------------------------------------------------------;; ;; Following information is an addition to Chapter 2, pages 2-2 and 2-3. ;; ;; It explains the /Axxxx and /Qxx parameters. ;; ;; ;; ;;-------------------------------------------------------------------------;; 1. Following are the defaults the driver assumes when you specify /C1 thru /C4: Option Irq Addr Com Port Addr ------ ---- ---- ------------- /C1 Irq 4 3F8h Port address at BIOS 40:0 area /C2 Irq 3 2F8h Port address at BIOS 40:2 area /C3 Irq 3 3E8h Port address at BIOS 40:4 area /C4 Irq 3 2E8h Port address at BIOS 40:6 area Our driver will zero out the corresponding BIOS 40:x area after acquiring the port. To insure proper setup, you may want to verify the BIOS area before loading our driver. 2. Instead of using the /C1 thru /C4 option, you can specify the Irq and port address by using the following options on the device= statement for the FIOSERDD.SYS driver: /Axxxx - where xxxx is the Hex Comm port I/O addresss to use. /Qxx - where xx is the Decimal Interrupt level to use. (valid Int levels are 02, 03, 04, 05, 10, 11, or 15) When using the /Axxxx option, our driver does not zero out any of the BIOS area. 3. NOTE: you must perform the BIOS setup on your PC or configure the expansion serial port adapter to match the Irq/Port that our driver will be using as described above. NOTE: In ISA/PCI bus machines (non microchannel), you must insure that our driver is using an Interrupt that is NOT being used by any other driver or device. Interrupt levels can't be shared in ISA/PCI bus PC's. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; MagSetOperationMode on page 3-7: ;; ;; ;; ;;-------------------------------------------------------------------------;; Parameter "OperationMode" default is bit 0 = 1, data returns if the data for at least one of the requested tracks is valid. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinSetModeClr on page 4-22: ;; ;; ;; ;;-------------------------------------------------------------------------;; The "Remarks" section should state that: All cryptographic functions work in the CLEAR mode except for the following: PinReadPin4704 PinReadPin3624 PinReadPinAnsi98 ;;-------------------------------------------------------------------------;; ;; Following information is a NEW API, not document in the publication. ;; ;; PinSetModeSingle: ;; ;; ;; ;;-------------------------------------------------------------------------;; PinSetModeSingle (PinHandle, rc) Parameters The PinSetModeSingle function call uses the following parameters: PinHandle This word value parameter is the 4778 device-driver handle that was obtained from the PinOpen function call. rc This parameter is a word value that represents the return code from the PinSetModeSingle function call. The valid return codes are: 0 No error. 1793 The 4778 PinHandle parameter is not valid. 1794 The 4778 PIN Keyboard detected an error in the requested function call. 1798 An error occured in the PINCALLS.DLL file. REMARKS Will indicate to the 4778 that all encrypted Master Keys passed with the PinLoadMasterKey API have been "Single" encrypted by the application. Only supported on 4778's at microcode version "4778v210" or higher. Will be the default mode on all earlier version of the microcode. Need only be issued one time. Setting will be maintained by the 4778 when powered off. Current status (whether Single/Triple Mode) will be indicated by the last byte of the device serial number which can be retreived via the PinReadSN API: - Last byte of serial number is FF = Single Mode - Last byte of serial number is F3 = Triple Mode ;;-------------------------------------------------------------------------;; ;; Following information is a NEW API, not document in the publication. ;; ;; PinSetModeTriple: ;; ;; ;; ;;-------------------------------------------------------------------------;; PinSetModeTriple (PinHandle, rc) Parameters The PinSetModeTriple function call uses the following parameters: PinHandle This word value parameter is the 4778 device-driver handle that was obtained from the PinOpen function call. rc This parameter is a word value that represents the return code from the PinSetModeTriple function call. The valid return codes are: 0 No error. 1793 The 4778 PinHandle parameter is not valid. 1794 The 4778 PIN Keyboard detected an error in the requested function call. 1798 An error occured in the PINCALLS.DLL file. REMARKS Will indicate to the 4778 that all encrypted Master Keys passed with the PinLoadMasterKey API have been "Triple" encrypted by the application. Only supported on 4778's at microcode version "4778v210" or higher. Will be the default mode on all earlier version of the microcode. Need only be issued one time. Setting will be maintained by the 4778 when powered off. Current status (whether Single/Triple Mode) will be indicated by the last byte of the device serial number which can be retreived via the PinReadSN API: - Last byte of serial number is FF = Single Mode - Last byte of serial number is F3 = Triple Mode ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinLoadMasterKey on page 4-26: ;; ;; ;; ;;-------------------------------------------------------------------------;; The Remarks section should state: All bytes of the supplied Master Key must contain ODD parity. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinLoadKey on page 4-28: ;; ;; ;; ;;-------------------------------------------------------------------------;; The Remarks section should state: All bytes of the supplied triple encrypted key must contain ODD parity. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinLoadICV on page 4-29: ;; ;; ;; ;;-------------------------------------------------------------------------;; The "ICVBuffer" parameter description should state: This parameter is a long pointer to a 8-byte buffer that contains the Triple Encrypted initial-chaining value. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinLoadVerifParms on page 4-30: ;; ;; ;; ;;-------------------------------------------------------------------------;; The "default" values for the PinLength and DecTblBuffer data are: PinLength = 4 DecTblBuffer = 00 01 02 03 04 05 06 07 08 09 00 01 02 03 04 05 ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinReadPin3624 page 4-32: ;; ;; ;; ;;-------------------------------------------------------------------------;; The "PinKey" parameter should have this additional note added to it: Note: The 4778 will treat this 8 byte data as either being Single Encrypted or Triple Encrypted depending on the current mode setting as established by PinSetModeSingle/PinSetModeTriple. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinReadPinAnsi98 on page 4-32: ;; ;; ;; ;;-------------------------------------------------------------------------;; The "PinKey" parameter should have this additional note added to it: Note: The 4778 will treat this 8 byte data as either being Single Encrypted or Triple Encrypted depending on the current mode setting as established by PinSetModeSingle/PinSetModeTriple. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinVerifyPin on page 4-36: ;; ;; ;; ;;-------------------------------------------------------------------------;; The last sentence in the "Remarks" section is incorrect. This function can be used when the device is in either the Clear or the Encrypted modes. The "PinKey" parameter should have this additional note added to it: Note: The 4778 will treat this 8 byte data as either being Single Encrypted or Triple Encrypted depending on the current mode setting as established by PinSetModeSingle/PinSetModeTriple. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinCreateOffsetData on page 4-38: ;; ;; ;; ;;-------------------------------------------------------------------------;; The last sentence in the "Remarks" section is incorrect. This function can be used when the device is in either the Clear or the Encrypted modes. The "PinKey" parameter should have this additional note added to it: Note: The 4778 will treat this 8 byte data as either being Single Encrypted or Triple Encrypted depending on the current mode setting as established by PinSetModeSingle/PinSetModeTriple. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinGenerateMac on page 4-40: ;; ;; ;; ;;-------------------------------------------------------------------------;; The "MacKey" and "Maclcv" parameters should have this additional note added to it: Note: The 4778 will treat this 8 byte data as either being Single Encrypted or Triple Encrypted depending on the current mode setting as established by PinSetModeSingle/PinSetModeTriple. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinVerifyMac on page 4-43: ;; ;; ;; ;;-------------------------------------------------------------------------;; The "MacKey" and "Maclcv" parameters should have this additional note added to it: Note: The 4778 will treat this 8 byte data as either being Single Encrypted or Triple Encrypted depending on the current mode setting as established by PinSetModeSingle/PinSetModeTriple. ;;-------------------------------------------------------------------------;; ;; Following information is a clarification to the following API: ;; ;; PinReadSN on page 4-47: ;; ;; ;; ;;-------------------------------------------------------------------------;; The "SNBuffer" value for its FFH Flag byte should have the following added to its description: IF 4778 version "4778v210" or higher: FFH = Device in Single Encrypted Mode F3H = Device in Triple Encrypted Mode