Sunday, April 5, 2020

PCSC sample in Java using intarsys smartcard-io

Here is a new PCSC sample in Java language I promised in PC/SC sample in different languages.

We already saw in a previous article "PCSC sample in Java" that the standard JVM includes javax.smartcardio to access smart cards. We will now see another Java wrapper.

intarsys smartcard-io

The project intarsys smartcard-io is hosted at https://github.com/intarsys/smartcard-io.
The licence is 3-Clause BSD.

Installation

Installation is easy. Just get the provided is-smartcard-io.jar files from deploy/ directory and the 3 runtime dependencies from lib/ directory.

I have not tried to rebuild the library from source.

Source code

The API is easy to use since it is a direct mapping to the PC/SC WinScard API.


package com.company;

import de.intarsys.security.smartcard.pcsc.IPCSCCardReader;
import de.intarsys.security.smartcard.pcsc.IPCSCConnection;
import de.intarsys.security.smartcard.pcsc.IPCSCContext;
import de.intarsys.security.smartcard.pcsc.PCSCContextFactory;
import de.intarsys.security.smartcard.pcsc.nativec._IPCSC;

import java.util.List;

public class Blog {
    public static void main(String[] args) {
        try {
            /* Establish context */
            IPCSCContext context = PCSCContextFactory.get().establishContext();

            /* Display the list of readers */
            List<IPCSCCardReader> readers = context.listReaders();
            for (IPCSCCardReader reader : readers) {
                System.out.println("found " + reader + " named " + reader.getName());
            }

            /* Use the first reader */
            IPCSCCardReader reader = readers.get(0);

            /* Connect to the card */
            IPCSCConnection connection = context.connect(
                    reader.getName(), _IPCSC.SCARD_SHARE_SHARED,
                    _IPCSC.SCARD_PROTOCOL_Tx);

            /* Send Select Applet command */
            byte[] select = {0x00, (byte)0xA4, 0x04, 0x00, 10, (byte)0xA0, 0x00, 0x00, 0x00, 0x62, 0x03, 0x01, 0x0C, 0x06, 0x01};
            byte[] answer;
            answer = connection.transmit(select, 0, select.length, 256, false);
            System.out.println("answer: " + answer.length + " bytes");
            for (int i=0; i<answer.length; i++) {
                System.out.print(String.format("%02X ", answer[i]));
            }
            System.out.println();

            /* Send test command */
            byte[] command = {0x00, 0x00, 0x00, 0x00};
            answer = connection.transmit(command, 0, command.length, 256, false);
            System.out.println("answer: " + answer.length + " bytes");
            for (int i=0; i<answer.length; i++) {
                System.out.print(String.format("%02X ", answer[i]));
            }
            System.out.println();
            for (int i=0; i<answer.length - 2; i++) {
                System.out.print((char)answer[i]);
            }
            System.out.println();

            /* Disconnect */
            connection.disconnect(_IPCSC.SCARD_LEAVE_CARD);

            /* Release context */
            context.dispose();
        } catch(Exception e) {
            System.out.println("Ouch: " + e.toString());
        }
    }
}

Output

found pcscreader 0 named Gemalto PC Twin Reader
found pcscreader 1 named Cherry KC 1000 SC Z
answer: 2 bytes
90 00 
answer: 14 bytes
48 65 6C 6C 6F 20 77 6F 72 6C 64 21 90 00 
Hello world!

High level API

Intarsys smartcard-io also provides a higher level API compatible with javax.smartcardio.
As documented in the project README:
javax.smartcardio Provider

The library comes with an alternative javax.smartcardio provider. There are a couple of things to consider:

Intended differences
  • dedicated PCSC context for terminals, terminal and card
  • waitForChange(timeout) semantics improved(?), state change is reset even in case of timeout
  • reader insertion is handled, too
  • no finalizer for card!

javax.smartcardio bug/limitation

One big problem with the SUN/Oracle implementation of javax.smartcardio is that only one PC/SC context is created.
It works fine with a mono-threaded application. But it is very problematic with a multi-threaded application if you want to access different readers at the same time from different threads.

As documented in pcsc-lite SCardEstablishContext():
Each thread of an application shall use its own SCARDCONTEXT

This is because only one thread can use a SCARDCONTEXT at the same time. So 2 SCardTransmit() calls on 2 different cards from 2 threads but using the same SCARDCONTEXT will be serialized by pcsc-lite. This is NOT what you want if you intent to execute the 2 card commands at the same time.

The problem is not present on Windows because the Microsoft WinSCard implement is different.
I don't know how javax.smartcardio behaves on macOS. The WinSCard on macOS has been rewritten using the low level API CryptoTokenKit since macOS Yosemite 10.10 in 2014 (see "OS X Yosemite and smart cards status") and is no more using pcsc-lite.

Conclusion

This wrapper is easy to use and provides access to all the PC/SC fuctions.

Sunday, March 22, 2020

ATR statistics: ATR list growth (part 2)

In January 2016 I started a study of each byte contained in a smart card ATR. See "ATR list study".

My goal was to publish one new article every week. So with 19 bytes that was a job for 5 months. But it took me more than 4 years! I imagine it is because of some lack of time and/or motivation.

My first article was about the ATR list growth. In January 2016 I had 2098 ATRs in the list. Now I have 3316 ATRs in the list and the number is still growing.

Graph


The red line indicates the position in January 2016.

New ATRs only

In 2016 the linear regression for the graph was y = 6.308x10-6 x - 940.4.
For the last 4 years it is y = 9.381x10-6 x - 2409.7

The growth is now 48% faster than before. Woah!

I guess that is because it is very simple to submit a new ATR using the web interface at https://smartcard-atr.apdu.fr/. Before I create this service, in 2010, you had to send me a new ATR by email. Now you just (mostly) click on a button.

No, I will not re-compute all the statistics with the new, more complete, ATR list.

Thank you

to all of you who submit new ATRs.

ATR statistics: TCK - Check byte TCK (conditional)

Article from the series "ATR statistics".

TCK - Check byte TCK (conditional)

The ISO 7816-3 specification is not public. So I can't copy/paste part of the text. I will use Wikipedia instead.
The ChecK byte (if present) allows a check of the integrity of the data in the ATR. If present, TCK is the Exclusive OR of the bytes in the ATR from T0 (included) to TCK (excluded).
TCK shall be present if and only if any of the TDi present in the ATR encodes a value of T other than 0.

TCK#%
110353.23 %
0x001235.94 %
0x1290.43 %
0x2890.43 %
0x0580.39 %
0x8980.39 %
0x9980.39 %
0xC180.39 %
0x0370.34 %
0x0970.34 %
0x0E70.34 %
0x1670.34 %
0x1C70.34 %
0x3870.34 %
0x4370.34 %
0x6570.34 %
0x8870.34 %
0x8C70.34 %
0xA570.34 %
0xB770.34 %
0x0660.29 %
0x0D60.29 %
0x1560.29 %
0x1B60.29 %
0x4A60.29 %
0x5260.29 %
0x5960.29 %
0x5A60.29 %
0x6260.29 %
0x6A60.29 %
0x6D60.29 %
0x7660.29 %
0x7760.29 %
0x7A60.29 %
0x7F60.29 %
0x8360.29 %
0x9060.29 %
0x9C60.29 %
0xA160.29 %
0xA960.29 %
0xF360.29 %
0xFF60.29 %
0x-150.24 %
0x0A50.24 %
0x0F50.24 %
0x1450.24 %
0x1850.24 %
0x1E50.24 %
0x3150.24 %
0x3A50.24 %
0x3C50.24 %
0x4550.24 %
0x5850.24 %
0x6B50.24 %
0x7550.24 %
0x7E50.24 %
0x8050.24 %
0x8450.24 %
0x8F50.24 %
0x9850.24 %
0xB650.24 %
0xBD50.24 %
0xC450.24 %
0xCC50.24 %
0xD250.24 %
0xDA50.24 %
0xFE50.24 %
0x0740.19 %
0x1740.19 %
0x1940.19 %
0x1A40.19 %
0x1D40.19 %
0x2140.19 %
0x2440.19 %
0x3240.19 %
0x3940.19 %
0x3F40.19 %
0x4940.19 %
0x4C40.19 %
0x5C40.19 %
0x5E40.19 %
0x6040.19 %
0x6340.19 %
0x6840.19 %
0x6C40.19 %
0x7040.19 %
0x7140.19 %
0x7440.19 %
0x7940.19 %
0x8640.19 %
0x8A40.19 %
0x9140.19 %
0x9540.19 %
0x9B40.19 %
0x9D40.19 %
0x9F40.19 %
0xA040.19 %
0xA240.19 %
0xA640.19 %
0xB040.19 %
0xB440.19 %
0xBE40.19 %
0xC940.19 %
0xD040.19 %
0xD640.19 %
0xE040.19 %
0xE140.19 %
0xE940.19 %
0xEC40.19 %
0xF840.19 %
0x0130.14 %
0x0230.14 %
0x0830.14 %
0x0C30.14 %
0x1F30.14 %
0x2A30.14 %
0x3030.14 %
0x3330.14 %
0x3D30.14 %
0x4730.14 %
0x4D30.14 %
0x4E30.14 %
0x4F30.14 %
0x5330.14 %
0x5530.14 %
0x5730.14 %
0x5B30.14 %
0x6F30.14 %
0x7230.14 %
0x7830.14 %
0x7B30.14 %
0x7D30.14 %
0x8230.14 %
0x9230.14 %
0x9430.14 %
0x9730.14 %
0x9A30.14 %
0x9E30.14 %
0xA830.14 %
0xAA30.14 %
0xAB30.14 %
0xAD30.14 %
0xB130.14 %
0xB930.14 %
0xBC30.14 %
0xC230.14 %
0xC530.14 %
0xCF30.14 %
0xD330.14 %
0xD430.14 %
0xD730.14 %
0xDF30.14 %
0xEF30.14 %
0xF230.14 %
0xF430.14 %
0xF730.14 %
0xFA30.14 %
0x1020.10 %
0x1120.10 %
0x1320.10 %
0x2220.10 %
0x2520.10 %
0x2620.10 %
0x2720.10 %
0x2920.10 %
0x2B20.10 %
0x2D20.10 %
0x2E20.10 %
0x3520.10 %
0x3620.10 %
0x3B20.10 %
0x4020.10 %
0x4120.10 %
0x4820.10 %
0x5020.10 %
0x5120.10 %
0x5420.10 %
0x5D20.10 %
0x5F20.10 %
0x6420.10 %
0x6620.10 %
0x6720.10 %
0x6920.10 %
0x7320.10 %
0x7C20.10 %
0x8520.10 %
0x8720.10 %
0x8B20.10 %
0x8D20.10 %
0x8E20.10 %
0xAC20.10 %
0xAF20.10 %
0xBA20.10 %
0xBB20.10 %
0xC320.10 %
0xC720.10 %
0xC820.10 %
0xD520.10 %
0xD820.10 %
0xDC20.10 %
0xDD20.10 %
0xDE20.10 %
0xE420.10 %
0xE520.10 %
0xE820.10 %
0xEA20.10 %
0xEB20.10 %
0xF020.10 %
0xF620.10 %
0xFB20.10 %
0xFC20.10 %
0xFD20.10 %
0x0410.05 %
0x0B10.05 %
0x2310.05 %
0x2C10.05 %
0x2F10.05 %
0x3E10.05 %
0x4210.05 %
0x4610.05 %
0x5610.05 %
0x6110.05 %
0x8110.05 %
0x9310.05 %
0x9610.05 %
0xA310.05 %
0xA710.05 %
0xAE10.05 %
0xB210.05 %
0xB310.05 %
0xB510.05 %
0xC610.05 %
0xCA10.05 %
0xCB10.05 %
0xCE10.05 %
0xD110.05 %
0xD910.05 %
0xDB10.05 %
0xE210.05 %
0xE310.05 %
0xEE10.05 %
0xF110.05 %
0xF510.05 %
0xF910.05 %


A large part (53%) or ATR do not have a TCK. These cards are T=0 only.

Some ATR have a TCK of 0 but this value is invalid. For example with 3B 88 80 01 00 00 00 00 77 83 95 00 00.
In most cases the TCK has a value of 0 but that is because a pattern is used in the ATR matching. For example with 3B 8C 80 01 04 43 FD 00 00 00 00 00 00 00 00 00 00. The pattern used to match the ATR is "3B 8C 80 01 04 43 FD .. .. .. .. .. .. .. .. .. .." to accept any value for the "." but my program replaced any "." by a "0".

Some ATR should have an ATR but do NOT contain it. For example with 3B 9E 96 80 1F C7 80 31 E0 73 FE 21 1B 66 D0 01 77 97 0D 00. My parsing program indicates TCK = 0x-1 in this case but that is only a way to indicate a missing TCK. Only 4 ATRs are in this category.

Since the TCK is a checksum no special value is expected. So it is not surprising that the values from 1 to 255 have a mostly equal distribution.

ATR statistics: Historical bytes - Historical bytes Ti (optional)

Article from the series "ATR statistics"

Historical bytes Ti (optional)

The ISO 7816-3 specification is not public. So I can't copy/paste part of the text. I will use Wikipedia instead.

From Wikipedia https://en.wikipedia.org/wiki/Answer_to_reset#Historical_bytes_Ti:
Historical Characters Ti for i≥1, if present (as defined by K coded in T0), typically hold Information about the Card Builder, Type of Card (Size etc.), Version number and the State of the Card.

You can read the previous article about the T0 byte at ATR statistics: T0 - Format byte.

Regarding the T0 high nibble values we have:

hbn#%
0x0F74335.86 %
0x0E21210.23 %
0x0D1507.24 %
0x071366.56 %
0x051286.18 %
0x081165.60 %
0x0B1155.55 %
0x0A1075.16 %
0x09904.34 %
0x06864.15 %
0x0C723.47 %
0x04462.22 %
0x02401.93 %
0x03150.72 %
0x00130.63 %
0x0130.14 %




A large part (38%) of the ATR have 15 (0x0F) historical bytes, i.e. the maximum size.

The bytes can contain application information like for 3B 6F 00 FF 00 56 72 75 54 6F 6B 6E 73 30 20 00 00 90 00
Historical bytes00 56 72 75 54 6F 6B 6E 73 30 20 00 00 90 00
Category indicator byte: 0x00 (compact TLV data object)
Tag: 5, Len: 6 (card issuer's data)
Card issuer data: 72 75 54 6F 6B 6E "ruTokn"
Tag: 7, Len: 3 (card capabilities)
Selection methods: 48
- DF selection by file identifier
- DF selection by path
Data coding byte: 32
- Behaviour of write functions: proprietary
- Value 'FF' for the first byte of BER-TLV tag fields: valid
- Data unit in quartets: 0
Command chaining, length fields and logical channels: 0
- Logical channel number assignment: No logical channel
- Maximum number of logical channels: 1
Mandatory status indicator (3 last bytes)
LCS (life card cycle): 0 (No information given)
SW: 90 00 ()
or contain only the card name like for 3B 6F 00 FF 52 53 41 53 65 63 75 72 49 44 28 52 29 31 30
Historical bytes52 53 41 53 65 63 75 72 49 44 28 52 29 31 30
Category indicator byte: 0x52(proprietary format) "SASecurID(R)10"

I do not think it is important to detail all the possible information contained in the historical bytes.

For those who are interested you can read the ISO 7816-4 (note: not the 7816-3) chapter "8.1.1 Historical bytes".

Saturday, March 21, 2020

ATR statistics: TC4

Article from the series "ATR statistics".

TC4

TC4 should have the same meaning as TC3.

For T = 1: type of error detection code used

Bit 1 of the first TC for T=1 indicates the error detection code to be used:
  • CRC if bit 1 is set to 1;
  • LRC (default value) if bit 1 is set to 0.
Bits 8 to 2 of the first TC for T=1 are reserved for future use and shall be set to 0.

TC4#%
2072100.00 %

In my list of ATR none of them defines an TC4.

Wednesday, March 18, 2020

Wait for a card state change: SCardGetStatusChange()

I am "often" asked for a way to detect a card movement. There is a simple active loop solution but the correct answer is to use SCardGetStatusChange()

Simple but inefficient approach

It is possible to get a reader status using SCardStatus(). It is then possible to imagine something like:

while(TRUE)
{
  SCardStatus(hCard, NULL, 0, &dwState, NULL, NULL, NULL);
  if (dwState & SCARD_PRESENT)
  {
    do stuff
  }
  sleep(1);
}

The problems with this code are:
  • it consumes CPU cycles even when nothing happens
  • when the code is executing the sleep(1) then no card movement is detected. So you can wait for up to 1 second before you detect a card event. You can shorted the delay to 0.1 second but then you will waste even more CPU cycles.
Of course this solution is not efficient and not recommanded.

Correct solution: SCardGetStatusChange()

The WinSCard API provides the function SCardGetStatusChange() to wait for events.

You give a list of reader names and the function returns when the state of one (or more) reader changes, or a timeout occurs. I let you read the API documentation for the details.

You can interrupt the function using SCardCancel() if needed. The function will then return before the expiration of the timeout.

Source code


#include <stdio.h>
#include <stdlib.h>

#ifdef __APPLE__
#include <PCSC/winscard.h>
#include <PCSC/wintypes.h>
#else
#include <winscard.h>
#endif

#define CHECK(f, rv) printf(f ":[0x%08lX] %s\n", rv, pcsc_stringify_error(rv))

int main(void)
{
    LONG rv;
    SCARDCONTEXT hContext;
    LPTSTR mszReaders = NULL;
    DWORD dwReaders;

    rv = SCardEstablishContext(SCARD_SCOPE_USER, NULL, NULL, &hContext);
    CHECK("SCardEstablishContext", rv);

#ifdef SCARD_AUTOALLOCATE
    dwReaders = SCARD_AUTOALLOCATE;

    rv = SCardListReaders(hContext, NULL, (LPTSTR)&mszReaders, &dwReaders);
    CHECK("SCardListReaders", rv);
#else
    rv = SCardListReaders(hContext, NULL, NULL, &dwReaders);
    CHECK("SCardListReaders", rv);

    mszReaders = calloc(dwReaders, sizeof(char));
    rv = SCardListReaders(hContext, NULL, mszReaders, &dwReaders);
    CHECK("SCardListReaders", rv);
#endif

    if (dwReaders > 1)
    {
 printf("Using reader: %s\n", mszReaders);

 SCARD_READERSTATE reader_states[] = {
     {
  .szReader = mszReaders,
  .pvUserData = NULL,
  .dwCurrentState = SCARD_STATE_UNAWARE,
  .dwEventState = SCARD_STATE_UNAWARE,
     },
 };

 /* first call to get the current state */
 rv = SCardGetStatusChange(hContext, 0, reader_states, 1);
 CHECK("SCardGetStatusChange", rv);

 /* set the state we expect to change */
 reader_states[0].dwCurrentState = reader_states[0].dwEventState;

 /* wait for a state change, or a timeout after 3 seconds */
 rv = SCardGetStatusChange(hContext, 3 * 1000, reader_states, 1);
 CHECK("SCardGetStatusChange", rv);

 printf(".dwEventState: 0x%08lX\n", reader_states[0].dwEventState);
    }

#ifdef SCARD_AUTOALLOCATE
    rv = SCardFreeMemory(hContext, mszReaders);
    CHECK("SCardFreeMemory", rv);
#else
    free(mszReaders);
#endif

    rv = SCardReleaseContext(hContext);
    CHECK("SCardReleaseContext", rv);

    return 0;
}

Comments

The code uses the first reader returned by SCardListReaders(). I wanted to keep the code very simple. Adding support of multi readers is left as an execise to the reader.

pcsc-lite on GNU/Linux supports the auto allocation. But the PC/SC API on macOS does not. That is why I use the #ifdef SCARD_AUTOALLOCATE.

Outputs

The outputs on GNU/Linux and macOS are slightly different. Can you find the difference (except the reader name)?

GNU/Linux

$ ./sample 
SCardEstablishContext:[0x00000000] Command successful.
SCardListReaders:[0x00000000] Command successful.
Using reader: Gemalto PC Twin Reader 00 00
SCardGetStatusChange:[0x00000000] Command successful.
SCardGetStatusChange:[0x00000000] Command successful.
.dwEventState: 0x00050022
SCardFreeMemory:[0x00000000] Command successful.
SCardReleaseContext:[0x00000000] Command successful.

macOS


$ ./sample
SCardEstablishContext:[0x00000000] Command successful.
SCardListReaders:[0x00000000] Command successful.
SCardListReaders:[0x00000000] Command successful.
Using reader: Cherry KC 1000 SC Z
SCardGetStatusChange:[0x00000000] Command successful.
SCardGetStatusChange:[0x00000000] Command successful.
.dwEventState: 0x00000022
SCardReleaseContext:[0x00000000] Command successful.

.dwEventState

The difference is the .dwEventState value. On GNU/Linux the 16 upper bits are not 0.

From the documentation:
dwEventState also contains a number of events in the upper 16 bits (dwEventState & 0xFFFF0000). This number of events is incremented for each card insertion or removal in the specified reader. This can be used to detect a card removal/insertion between two calls to SCardGetStatusChange()

In the GNU/Linux output we have .dwEventState: 0x00050022 so we got 5 card events for this reader. The events were card insertion, removal, insertion, removal and insertion.

The lower 16-bits value is 0x0022 in both cases and it indicates SCARD_STATE_CHANGED and SCARD_STATE_PRESENT.

Other language

SCardGetStatusChange() is for the C language API. Since it is possible to use the smart card API with many languages (at least 23) each wrapper has (or should have) its own equivalent.

For example in Python you can use the low level API with the Python method SCardGetStatusChange() or use the higher API with the CardMonitor() class.

Conclusion

It is easy to use SCardGetStatusChange(). Please use it when needed.

It is also easy to misuse it. After writting this article I (re)discovered that I already wrote about SCardGetStatusChange() in "How to use SCardGetStatusChange()?" two years ago. This articles has different details and may also help you.

Sunday, March 8, 2020

New version of pcsc-tools: 1.5.6

I just released a new version of pcsc-tools, a suite of tools for PC/SC.

Changes:

1.5.6 - 8 March 2020, Ludovic ROUSSEAU
  • 62 new ATRs
  • pcsc_scan: better support of Windows

See also my previous article "Better pcsc_scan on Windows".