Home#include <v4kf.lh>
rdrhandle:chipActivate(flags[[, countrycode, socket]])SYNOPSIS
DESCRIPTION
Enable a SmartCard chip using T=0 or T=1 protocol (auto-detected). Optionally read public identification data from EMV compatible chips and EF_ID from german "EC-Karte mit Chip".
When running the command against a regular chip card, it can only be used if the reader is in the Locked state, which secures the chip card against removal during operation in insertion readers and causes the chip contact to engage in motorized readers.
Alternatively, the command can be run on a SAM card by specifying a non-zero socket number. The value selects the SAM socket to access (1..N, depending on the number of SAM sockets installed.)
While this state processes, the reader is in the Processing state and v4kf:isProcessing() returns true. The reader returns to the previous state on completion.
The optional countrycode can be used when activating an EMV card to tell the card the supposed nationality of the card terminal.
The command returns immediately. Actual execution of any reader operation is done within the event loop.
The processing result is provided with the v4kf.processingComplete() callback. The data passed to the callback contains the information that was read from the chip. It is encoded using the ISO7816/EMV Tag-Length-Value method.
The flags parameter is a bit-wise of some of the following modifier bits:
| flag | Description |
|---|---|
| V4KF_IDENTIFY_ALL | After activating the chip, read back any public identification information that the chip offers. This can take several seconds. |
| V4KF_IDENTIFY_EFID | (DEPRECATED -- The german GeldKarte has been discontinued, activating this option is now just a waste of time.) After activating the chip, request the EF_ID identification from a german "EC-Karte mit Chip / GeldKarte". If an EF_ID could be read, the EF_ID data is tagged using the tag 0xCF, which lies in the private range as of ISO7816-4. This allows returning EMV and EF_ID in one block. |
| V4KF_IDENTIFY_TRACK2EQUIV | After activating the chip, request the "Track 2 Equivalent Data" from a EMV compatible credit card. This data, if available, is a copy of the data that is on the magstripe track 2. |
| V4KF_IDENTIFY_ATR | Return the ATR response of the chip. The data is tagged using 0xCE, which lies in the private range is of ISO7816-4. This allows piggy-backing the ATR onto the other data. Asking for the ATR takes no extra time. |
| V4KF_IDENTIFY_EMV_MODE V4KF_IDENTIFY_7816_MODE |
Without any of these two options the command tries to activate using EMV specific quirks first, and then goes to ISO7816 mode. Specify exactly one option to enforce using just this one mode. This can reduce the activation time by 200-300ms |
| V4KF_IDENTIFY_SCAN_ALL_APPLICATIONS | In normal use, the command reads data by probing the card with a list of hardcoded application ids (AID). On first match, the data for this ID is read and returned. By setting this flag, all known AID values are probed in sequence and all available data is returned in multiple blocks tagged with the EMV 0x70 header tag. This feature is extremely slow and typically only useful for debugging. |
| V4KF_IDENTIFY_INJECT_AID |
Inject the AID value that was used to open the data file as the first tag into the 0x70 EMV data block,
using the standard tag code 0x4F for AID. Processing time for adding this flag is negligible. |
| V4KF_IDENTIFY_INJECT_IBAN V4KF_IDENTIFY_INJECT_BIC |
Some, but not all, german bank account cards provide institute information in the response
to the "get PSE record" command. For convenience, this information can be injected at the beginning of the 0x70 EMV datablock. The values are tagged with the standard tag codes 0x5F53 (IBAN) an 0x5F54 (BIC). Warning -- The cards report an incomplete IBAN, where the account number has been replaced by zeroes. However, the german BLZ can still be extracted from this data, which can be useful. Processing time for adding this flag is negligible. |
NOTES
The tagged data can be decoded using v4kf.emvDecode() and v4kf.emvLookup().