VivoKey Reader Developer Guide
Introduction
VivoKey Reader is a Android smartphone app that allows your NFC enabled smartphone to appear as an attached PC/SC compliant contactless reader for Windows computers and laptops. This guide is for PC/SC application developers who wish to support VivoKey Reader.
ATR - Answer To Reset
Contact smart cards support ATR, but contactless standards such as ISO14443 or ISO15693 do not. When ATR is requested, like all contactless readers do, VivoKey Reader will calculate one for the contactless chip currently in the field. For ISO7816 compliant smartcards (ISODEP), historical bytes are used. Because of this, ATR is sometimes reported slightly differently from different readers for the same contactless chip. For all ISO15693 type transponders, VivoKey Reader will always respond with an ATR of 3B 8F 80 01 80 4F 0C A0 00 00 03 06 0B 00 00 00 00 00 00 63. For more information about ATRs, visit https://smartcard-atr.apdu.fr/
Getting transponder UID
Getting the UID of the card is done by sending the get data APDU command FF CA 00 00 00.
| CLA | INS | P1 | P2 | Lc |
|---|---|---|---|---|
|
FF |
CA |
00 |
00 |
00 |
VivoKey Reader returns the chip’s UID followed by 90 00 for success or 6A 81 for unsupported.
Get ATS - Answer To Select
Getting the ATS of the card is done by sending the get data APDU command FF CA 01 00 00.
| CLA | INS | P1 | P2 | Lc |
|---|---|---|---|---|
|
FF |
CA |
01 |
00 |
00 |
VivoKey Reader returns the chip’s ATS followed by 90 00 for success, 64 00 for error, or 6A 81 if card type is unsupported. Different types of chips will return different types of ATS data;
- ISO 14443-A: Returns historical bytes for ATS
- ISO 14443-B: Returns INF field of ATTRIB response
- ISO 15693: Returns 6A 81 (unsupported)
Get Firmware Version
You can retrieve the app version of VivoKey Reader connected to your host using the get firmware command.
| CLA | INS | P1 | P2 | Lc |
|---|---|---|---|---|
|
FF |
AB |
02 |
00 |
00 |
This command will return the name and version number of the VivoKey Reader app connected to the host system. For example, version 1.0 of VivoKey Reader will return 56 69 76 6F 4B 65 79 52 65 61 64 65 72 5F 76 31 2E 30 which decodes to “VivoKeyReader_v1.0” in ASCII, followed by 90 00.
Get Serial Number
The serial number command will return a unique smartphone identifier that VivoKey Reader is running on. However, this is not a secure method of identifying the mobile phone.
| CLA | INS | P1 | P2 | Lc |
|---|---|---|---|---|
|
FF |
AB |
02 |
00 |
00 |
A unique identifier of the smartphone VivoKey Reader is running on will be returned. The format is a simple 8 byte value followed by 90 00. For example, send FF AB 02 00 00 and receive 97 74 D5 6D 68 2E 54 9C followed by 90 00. This is not guaranteed to change, but changing may require a factory reset of the smartphone in question. If the device serial number is unable to be obtained, the error code 6A 81 will be returned instead.
Play Audio
While a card is present, it is possible to send a pseudo-ADPU which will result in the VivoKey Reader application running on the phone to emit a type of notification alert sound or audio file. Up to 3 types of alerts are supported, depending on the P2 value.
| CLA | INS | P1 | P2 | Lc |
|---|---|---|---|---|
|
FF |
BB |
01 |
NN |
00 |
The sound that plays depends on the value of P2. A value of 01 plays alert sound 1, 02 plays alert sound 2, and 03 plays sound 3. A value of 00 for P2 results in no sound playing (silence). Other P2 values will result in error 6A 81.
Display Screen Message
While a card is present, it is possible to send a pseudo-APDU which will result in the VivoKey Reader application on the phone displaying a short message (up to 80 characters) as a pop-up on screen.
| CLA | INS | P1 | P2 | Lc | Data |
|---|---|---|---|---|---|
|
FF |
BB |
02 |
timeout |
length |
data |
The P2 parameter contains the timeout for the message in seconds. A value of 00 means the message will be displayed until dismissed. Multiple messages will be shown in a kind of queue until they time out or are manually dismissed. The payload of the pseudo-APDU contains the message to be displayed. Messages longer than 80 characters will be truncated.
ACS Command Support
VivoKey Reader supports some of the proprietary commands for ACS readers like the ACR122U, ACR1252U, ACR1552U, and others. Because ACS readers are widely deployed in the field, supporting ACS proprietary commands helps ensure maximum compatibility with existing PC/SC client software and applications.
ACS Get Reader Firmware command support
Most ACS readers return a firmware version in response to the APDU command FF 00 48 00 00, but they do not properly return the SW1 and SW2 suffix. For example, the ACR1252 returns 41 43 52 31 32 35 32 55 5F 56 31 31 31 2E 31 which if converted to ASCII is “ACR1252U_V111.1” while the ACR122U returns 41 43 52 31 32 32 55 32 30 31 or “ACR122U201”. You may notice there is no 90 00 at the end. This lack of SW1 and SW2 is likely an oversight since this kind of command is not typically sent using SCardTransmit. Commands like this which communicate directly with the reader (not the card) are typically sent using SCardControl, which does not have any status words. We believe ACS mistakenly omitted the status word bytes SW1 and SW2 from this response when sent using SCardTransmit, but now it's too late to correct it as many applications already account for this oversight.
VivoKey Reader will return app version information in the same way, without SW1 and SW2, just to ensure compatibility with ACS’s mistake. For example, version 1.0 of VivoKey Reader will return 56 69 76 6F 4B 65 79 52 65 61 64 65 72 5F 76 31 2E 30 (VivoKeyReader_v1.0) without 90 00 since all software designed to work with ACS readers will likely be expecting this type of return data without SW1 and SW2.
ACS Direct Transmit
Because non-ISO7816 compliant NFC chips (like NTAG, Ultralight, etc.) do not use APDUs to communicate, commands must be wrapped in a pseudo-APDU (PPDU). Certain ACS readers support this through a “Direct Transmit” PPDU that starts with FF 00 00 00. VivoKey Reader emulates support for this PPDU for both ISO14443-A and ISO15693 transponders.
| CLA | INS | P1 | P2 | Lc | Data |
|---|---|---|---|---|---|
|
FF |
00 |
00 |
00 |
length |
payload |
For example, to pass the “GET_VERSION” command 0x60h to an NTAG2xx chip using the ACS Direct Transmit PPDU, a PC/SC client would send FF 00 00 00 01 60 and get back the 8 byte result from the chip of 00 04 04 02 01 00 13 03 followed by 90 00 to indicate success for a total of 10 bytes returned.
SpringCard command support
VivoKey Reader supports some of the proprietary commands for certain SprintCard readers. Because ACS readers are widely deployed in the field, supporting ACS proprietary commands helps ensure maximum compatibility with existing PC/SC client software and applications.
SpringCard Get Data PPDU
SpringCard implements various proprietary subcommands under the GET DATA (FF CA) PPDU with customized P1 and P2 values. VivoKey Reader implements only some of the more commonly used or relevant commands. All Get Data PPDUs start with FF CA and end with either a 90 00 for success or 6A 81 for error / unsupported.
SpringCard Complete Identifier command
The Complete Identifier command returns multiple pieces of information about the card in a single command response. The exact data returned depends on card type.
| CLA | INS | P1 | P2 | Lc | Data |
|---|---|---|---|---|---|
|
FF |
00 |
00 |
00 |
length |
payload |
The Complete Identifier the following data based on the type of card, followed by 90 00.
- ISO 14443-A : ATQA (2 bytes) + SAK (1 byte) + UID
- ISO 14443-B : Complete ATQB (11 or 12 bytes)
- ISO 15693 : Answer to GET SYSTEM INFORMATION command. If the card doesn’t support the GET SYSTEM INFORMATION COMMAND, a valid SYSTEM INFORMATION value is constructed, including the UID and the DSFID byte.
SpringCard Type Of Card command
| CLA | INS | P1 | P2 | Lc |
|---|---|---|---|---|
|
FF |
CA |
F1 |
00 |
00 |
Returns card type according to PC/SC part 3 supplemental document: PIX.SS (standard, 1 byte) + PIX.NN (card name, 2 bytes). This is the same data used in the construction of the ISO14443A-3 ATR.
SpringCard Get ATR command
| CLA | INS | P1 | P2 | Lc |
|---|---|---|---|---|
|
FF |
CA |
FA |
00 |
00 |
Returns the card ATR followed by 90 00.
SpringCard Encapsulate
Because non-ISO7816 compliant NFC chips (like NTAG, Ultralight, etc.) do not use APDUs to communicate, commands must be wrapped in a pseudo-APDU (PPDU). Certain SpringCard readers support this through an “encapsulate” PPDU that starts with FF FE 00 00. VivoKey Reader does not support the complete SpringCard “encapsulate” command implementation, only the command necessary to perform the transceive itself is supported.
| CLA | INS | P1 | P2 | Lc | Data | Le |
|---|---|---|---|---|---|---|
|
FF |
00 |
ignored |
ignored |
length |
payload |
ignored |
Like ACS’s “direct transmit” command, SpringCard’s “encapsulate” command starts with a PPDU CLA byte of FF, but uses FE for the instruction. For example, to pass the “GET_VERSION” command 0x60h to an NTAG216 chip, a PC/SC client would send FF FE 00 00 01 60 and get back the 8 byte result from the chip of 00 04 04 02 01 00 13 03 followed by 90 00 to indicate success for a total of 10 bytes returned.
The P1 value of a SpringCard Encapsulate command is meant to control chip communication protocols and specifics, which are not part of the control mechanisms offered through smartphone NFC chip drivers at the application level. As such VivoKey Reader ignores the value of P1 and will process any command included in the payload. Likewise, Le is not necessary here and any value submitted is ignored by VivoKey Reader.
Identiv Command Support
VivoKey Reader supports some of the proprietary commands for certain Identiv readers like the uTrust 3700F. Supporting Identiv proprietary commands helps ensure maximum compatibility with existing PC/SC client software and applications.
Identiv Pass Thru
Identiv's "Pass Thru" pseudo-APDU was designed to send raw data to an ISO14443-A standard framing card, however VivoKey Reader will transmit payload data to ISO14443-A and ISO15693 transponder types.
| CLA | INS | P1 | P2 | Lc | Data | Le |
|---|---|---|---|---|---|---|
|
FF |
EF |
ignored |
00 |
length |
payload |
ignored |
Like ACS’s “direct transmit” command and SpringCard’s “encapsulate” command, Identiv’s “pass thru” command is a pseudo-APDU wrapper for the raw data payload to send. For example, to pass the “GET_VERSION” command 0x60h to an NTAG216 chip, a PC/SC client would send FF EF 00 00 01 60 and get back the 8 byte result from the chip of 00 04 04 02 01 00 13 03 followed by 90 00 to indicate success for a total of 10 bytes returned.
Probe Commands
VivoKey Reader supports some defacto-standard pseudo-APDUs used for obtaining information about the reader and driver being used. We are calling these “probe commands” because the application is probing for information about connected devices. These are a collection of commands that provide names, version of product, version of firmware, and version of driver.
Probe Command Table
| COMMAND | CLA | INS | P1 | P2 | Lc |
|---|---|---|---|---|---|
|
Vendor Name |
FF |
9A |
01 |
01 |
00 |
|
Product Name |
FF |
9A |
01 |
03 |
00 |
|
Sequence |
FF |
9A |
01 |
05 |
00 |
|
Firmware Version |
FF |
9A |
01 |
06 |
00 |
|
Driver Version |
FF |
9A |
01 |
07 |
00 |
Example probe / response APDUs
Send the “Vendor Name” probe, get back “VivoKey Technologies, Inc.” followed by 90 00.
> FF 9A 01 01 00
< 56 69 76 6F 4B 65 79 20 54 65 63 68 6E 6F 6C 6F 67 69 65 73 2C 20 49 6E 63 2E 90 00
Send the “Product Name” probe, get back “VivoKey Reader” followed by 90 00.
> FF 9A 01 03 00
< 56 69 76 6F 4B 65 79 20 52 65 61 64 65 72 90 00
Sending the “Sequence” probe returns the same data as the Get Serial Number command documented above (FF AB 02 00 00). This value is derived from a unique ID from the phone the app is running on. The return data could be anything, but must be at least 2 bytes long and not longer than 255 bytes. For example; “97 74 D5 6D 68 2E 54 9C“ followed by 90 00.
> FF 9A 01 05 00
< 97 74 D5 6D 68 2E 54 9C 90 00
Sending the “Firmware Version” probe returns the same data as the Get Firmware Version command documented above (FF AB 01 00 00), i.e. “VivoKeyReader_v1.0” followed by 90 00. These two commands should always return the exact same data.
> FF 9A 01 06 00
< 56 69 76 6F 4B 65 79 52 65 61 64 65 72 5F 76 31 2E 30 90 00
Send the “Driver Version” probe, get back “1.0” followed by 90 00.
> FF 9A 01 07 00
< 31 2E 30 90 00
Unsupported at this time
Mifare Crypto1 & Memory Structure Access
At this time we are not opting to support specific Mifare card commands, but could in the future. This means support for all key handling and authentication required for Mifare is currently unsupported. Furthermore, to support Mifare card commands, the smartphone would also need to have NFC reader hardware which supported Mifare licensing requirements - i.e. contains an NFC reader chip from NXP or reader chip with proper licensing attached.
PCSC 2.0 Part 3 transparent session
The PCSC standard includes a PPDU for managing transparent “sessions”;
| CLA | INS | P1 | P2 | Lc | Data |
|---|---|---|---|---|---|
|
FF |
C2 |
00 |
function |
length |
payload |
Because session support is complicated, and various direct transparent transmit options are available, we are not supporting Part 3 sessions at this time. VivoKey Reader will recognize the APDU command, but return 6A 80 if attempted.
Customized extended support
If you need VivoKey Reader to support something specific, please contact us. We are open to developing support for additional commands.