Changes:

1.7.2 - 10 August 2024, Ludovic ROUSSEAU

• 191 new ATRs

• provide meson configuration file

• improve pcsc_scan Windows support

  • Use Ctrl-C also on Windows

  • Windows can also use option -n

  • better output on Windows dumb terminals

• minor fixes and improvements

Pseudo code algorithm

The suggested way to fix the problem is to use something like that:

1. initial call to SCardGetStatusChange()

2. get the initial value from .dwEventState

3. copy this value in .dwCurrentState

4. second call to SCardGetStatusChange()

If a reader has been added before the second SCardGetStatusChange() call then SCardGetStatusChange() will return immediately.

Sample code

File sample.c:

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

#include <winscard.h>

#define CHECK(f, rv, panic) \
 printf(f "(): 0x%08lX, %s\n", rv, pcsc_stringify_error(rv)); \
 if ((SCARD_S_SUCCESS != rv) && panic) \
 { \
  return -1; \
 }

#define PANIC true
#define DONT_PANIC false

#define MAX_READERS 16

int main(void)
{
    LONG rv;
    SCARDCONTEXT hContext;
    LPTSTR mszReaders;
    DWORD dwReaders = 0;
    char *ptr, *readers[MAX_READERS] = {};
    int nb_readers;
    SCARD_READERSTATE rgReaderStates[MAX_READERS];

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

    rv = SCardListReaders(hContext, NULL, NULL, &dwReaders);
    CHECK("SCardListReaders", rv, DONT_PANIC)

    mszReaders = calloc(dwReaders, sizeof(char));
    rv = SCardListReaders(hContext, NULL, mszReaders, &dwReaders);
    CHECK("SCardListReaders", rv, DONT_PANIC)
    printf("Found readers:\n");
    nb_readers = 0;
    for (ptr=mszReaders; *ptr; ptr += strlen(ptr) +1)
    {
        printf(" %s\n", ptr);
        readers[nb_readers++] = ptr;
    }
    printf("Found %d readers\n", nb_readers);

    /* add the special reader */
    readers[nb_readers++] = "\\\\?PnP?\\Notification";

    /* get the initial states */
    for (int i=0; i<nb_readers; i++)
    {
        rgReaderStates[i].szReader = readers[i];
        rgReaderStates[i].dwCurrentState = SCARD_STATE_UNAWARE;
    }
    rv = SCardGetStatusChange(hContext, 0, rgReaderStates, nb_readers);
    CHECK("SCardGetStatusChange", rv, DONT_PANIC)

    /* set the current state */
    for (int i=0; i<nb_readers; i++)
    {
        rgReaderStates[i].dwCurrentState = rgReaderStates[i].dwEventState;
        printf("reader: %s, events #: %d\n",
            readers[i], rgReaderStates[i].dwEventState >> 16);
        printf("reader: %s, events state 0x%04X\n",
            readers[i], rgReaderStates[i].dwEventState & 0xFFFF);
    }

    /* wait for a change */
    rv = SCardGetStatusChange(hContext, INFINITE, rgReaderStates, nb_readers);
    CHECK("SCardGetStatusChange", rv, PANIC)

    /* new state */
    for (int i=0; i<nb_readers; i++)
    {
        printf("reader: %s, events #: %d\n",
            readers[i], rgReaderStates[i].dwEventState >> 16);
        printf("reader: %s, events state 0x%04X\n",
            readers[i], rgReaderStates[i].dwEventState & 0xFFFF);
    }

    free(mszReaders);

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

    return 0;
}

File Makefile:

# Linux
PCSC_CFLAGS := $(shell pkg-config --cflags libpcsclite)
LDLIBS := $(shell pkg-config --libs libpcsclite)

CFLAGS = $(PCSC_CFLAGS) -g

sample: sample.c

clean:
    rm -f sample

 SCardEstablishContext(): 0x00000000, Command successful.
 SCardListReaders(): 0x8010002E, Cannot find a smart card reader.
 SCardListReaders(): 0x8010002E, Cannot find a smart card reader.
 Found readers:
 Found 0 readers
 SCardGetStatusChange(): 0x8010000A, Command timeout.
 reader: \\?PnP?\Notification, events #: 33
 reader: \\?PnP?\Notification, events state 0x0000

 >>> connection of a new reader here

 SCardGetStatusChange(): 0x00000000, Command successful.
 reader: \\?PnP?\Notification, events #: 34
 reader: \\?PnP?\Notification, events state 0x0002
 SCardReleaseContext(): 0x00000000, Command successful.

 SCardEstablishContext(): 0x00000000, Command successful.
 SCardListReaders(): 0x00000000, Command successful.
 SCardListReaders(): 0x00000000, Command successful.
 Found readers:
  Gemalto PC Twin Reader 00 00
 Found 1 readers
 SCardGetStatusChange(): 0x00000000, Command successful.
 reader: Gemalto PC Twin Reader 00 00, events #: 0
 reader: Gemalto PC Twin Reader 00 00, events state 0x0012
 reader: \\?PnP?\Notification, events #: 34
 reader: \\?PnP?\Notification, events state 0x0000

 >>> removal of the reader here

 SCardGetStatusChange(): 0x00000000, Command successful.
 reader: Gemalto PC Twin Reader 00 00, events #: 0
 reader: Gemalto PC Twin Reader 00 00, events state 0x000E
 reader: \\?PnP?\Notification, events #: 35
 reader: \\?PnP?\Notification, events state 0x0002
 SCardReleaseContext(): 0x00000000, Command successful.

 SCardEstablishContext(): 0x00000000, Command successful.
 SCardListReaders(): 0x00000000, Command successful.
 SCardListReaders(): 0x00000000, Command successful.
 Found readers:
  Gemalto PC Twin Reader 00 00
 Found 1 readers
 SCardGetStatusChange(): 0x00000000, Command successful.
 reader: Gemalto PC Twin Reader 00 00, events #: 0
 reader: Gemalto PC Twin Reader 00 00, events state 0x0012
 reader: \\?PnP?\Notification, events #: 36
 reader: \\?PnP?\Notification, events state 0x0000

 >>> connection of a second reader

 SCardGetStatusChange(): 0x00000000, Command successful.
 reader: Gemalto PC Twin Reader 00 00, events #: 0
 reader: Gemalto PC Twin Reader 00 00, events state 0x0010
 reader: \\?PnP?\Notification, events #: 37
 reader: \\?PnP?\Notification, events state 0x0002
 SCardReleaseContext(): 0x00000000, Command successful.

Remarks

Conclusion

I was aware of this race issue with SCardGetStatusChange() since a long time (at least 2018. Thanks Maksim). But I got a new motivation boost after an issue was reported SCardGetStatusChange: Race condition when attaching multiple readers at the same time.

It is now the job of applications programmers to use this new feature in their codes.

If you find a regression in your application because of this change please open an issue.

Changes:

2.3.0: Ludovic Rousseau

3 August 2024

• SCardGetStatusChange(): add the number of reader events

• Add Appstream metainfo announcing HW support

• meson: specify minimum meson version to use

• fix formats under musl libc

• Send libpcsclite.so logs to stderr instead of stdout

• Some other minor improvements

Changes:

1.6.1 - 5 July 2024, Ludovic Rousseau

• fix 'parse' build issues on some systems (pthread & strlcpy)

• Some other minor improvements

Specification

From:

RSP Technical Specification
Version 3.0
19th October 2022
https://www.gsma.com/esim/resources/sgp-22-v3-0/

Chapter 2.12 Multiple Enabled Profiles, page 77:

This specification defines optional support of Multiple Enabled (MEP), where several Profiles can be in Enabled state. This enables a Device with more than one baseband to use more than one Profile at the same time for providing connectivity to different networks.

The multiplexing of the APDU streams to those Profiles on a single physical interface is specified in ETSI TS 102 221 (Smart Cards; UICC-Terminal interface; Release 17). This specification uses the term "eSIM Port" for what ETSI TS 102 221 calls a logical SE interface (LSI).

[...]

Several options for different features are defined for MEP:

• APDU multiplexing can use any of the mechanisms defined in ETSI TS 102 221 [6], e.g.:

  • eSIM Port selection via the APDU MANAGE LSI (select LSI) when the transmission protocol T=0 or T=1 is used.

  • eSIM Port selection via the NAD byte when the transmission protocol T=1 is used.

Implementation

Reda ZAITI, from Thales, implemented the second mechanism: eSIM Port selection via the NAD byte. The original patch is simple: Add possibility to set/get NAD on T=1 for MEP.

This feature can be used to test eSIM chips using a standard smart card reader. The CCID driver must manage the T=1 protocol so only TPDU readers can be used.

The PC/SC workgroup does not define anything regarding MEP. So it was implemented using SCardControl() and the control code SCARD_CTL_CODE(3600).

Sample code

A sample code GetSetNAD.py is provided:

#! /usr/bin/env python3

"""
#   GetSetNAD.py: get/set NAD value
#   Copyright (C) 2022  Ludovic Rousseau
"""

#   This program is free software; you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation; either version 3 of the License, or
#   (at your option) any later version.
#
#   This program is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License along
#   with this program; if not, see <http://www.gnu.org/licenses/>.

from smartcard.System import readers
from smartcard.pcsc.PCSCPart10 import SCARD_LEAVE_CARD, SCARD_CTL_CODE
from smartcard import Exceptions
from smartcard.util import toHexString


def get_nad(cardConnection):
    print("Get NAD")

    get_NAD = [0x3F, 0, 0]
    print(" command:", toHexString(get_NAD))
    res = cardConnection.control(SCARD_CTL_CODE(3600), get_NAD)
    print("  result:", toHexString(res))
    status = res[3]
    if status == 0:
        print("Success")
        nad = res[4]
        print("NAD:", nad)
    else:
        print("Failed!")


def set_nad(cardConnection, nad):
    print("Set NAD")

    set_NAD = [0x3E, 0, 1, nad]
    print(" command:", toHexString(set_NAD))
    res = cardConnection.control(SCARD_CTL_CODE(3600), set_NAD)
    print("  result:", toHexString(res))
    status = res[3]
    if status == 0:
        print("Success")
    else:
        print("Failed!")


if __name__ == "__main__":
    import sys

    reader_idx = 0
    if len(sys.argv) > 1:
        reader_idx = int(sys.argv[1])

    reader = readers()[reader_idx]
    print("Reader:", reader)

    cardConnection = reader.createConnection()
    cardConnection.connect(disposition=SCARD_LEAVE_CARD)

    get_nad(cardConnection)
    set_nad(cardConnection, 42)
    get_nad(cardConnection)

 ./GetSetNAD.py 1
Reader: Gemalto PC Twin Reader 01 00
Get NAD
 command: 3F 00 00
  result: 3F 00 02 00 00
Success
NAD: 0
Set NAD
 command: 3E 00 01 2A
  result: 3E 00 01 00
Success
Get NAD
 command: 3F 00 00
  result: 3F 00 02 00 2A
Success
NAD: 42

$ echo "00 00 00 00" | scriptor -r "Gemalto PC Twin Reader 01 00"
Using given card reader: Gemalto PC Twin Reader 01 00
Using T=1 protocol
Reading commands from STDIN
> 00 00 00 00
Can't get info: Transaction failed.

00000004 [140363545183936] APDU: 00 00 00 00
00000005 [140363545183936] ../src/ifdhandler.c:1360:IFDHTransmitToICC() usb:08e6/3437:libudev:0:/dev/bus/usb/001/008 (lun: 10000)
00000004 [140363545183936] ../src/commands.c:2289:CmdXfrBlockTPDU_T1() T=1: 4 and 65548 bytes
00000004 [140363545183936] ../src/openct/proto-t1.c:599:t1_build() more bit: 0
00000005 [140363545183936] sending: 2A 40 04 00 00 00 00 6E
00000006 [140363545183936] -> 000001 6F 08 00 00 00 00 20 00 00 00 2A 40 04 00 00 00 00 6E
00002295 [140363545183936] <- 000001 80 04 00 00 00 00 20 00 00 00 00 92 00 92
00000016 [140363545183936] received: 00 92 00 92
00000004 [140363545183936] ../src/openct/proto-t1.c:242:t1_transceive() R-BLOCK required
00000004 [140363545183936] sending: 2A 92 00 B8
00000005 [140363545183936] -> 000001 6F 04 00 00 00 00 21 00 00 00 2A 92 00 B8
00002016 [140363545183936] <- 000001 80 04 00 00 00 00 21 00 00 00 00 92 00 92
00000012 [140363545183936] received: 00 92 00 92
00000004 [140363545183936] ../src/openct/proto-t1.c:242:t1_transceive() R-BLOCK required
00000003 [140363545183936] ../src/openct/proto-t1.c:250:t1_transceive() Rule 7.2
00000002 [140363545183936] sending: 2A 92 00 B8
00000005 [140363545183936] -> 000001 6F 04 00 00 00 00 22 00 00 00 2A 92 00 B8
01555310 [140363545183936] <- 000001 80 00 00 00 00 00 22 40 FE 00
00000020 [140363545183936] ../src/commands.c:1564:CCID_Receive Card absent or mute
00000006 [140363545183936] ../src/openct/proto-t1.c:234:t1_transceive() fatal: transmit/receive failed
00000004 [140363545183936] SW:
00000004 [140363545183936] ../src/ifdwrapper.c:543:IFDTransmit() Card not transacted: 612
00000003 [140363545183936] ../src/winscard.c:1622:SCardTransmit() Card not transacted: rv=SCARD_E_NOT_TRANSACTED
00000003 [140363545183936] ../src/winscard.c:1650:SCardTransmit() UnrefReader() count was: 2
00000005 [140363545183936] ../src/winscard_svc.c:719:ContextThread() TRANSMIT for client 15, rv=SCARD_E_NOT_TRANSACTED

Conclusion

Very few people will use this feature. I guess only developers of eSIM and testers/evaluators of eSIM will need this.

My driver is Free Software and was modified to add the feature. This is the beauty of Free Software.

Meson for libccid

A typical use case is:

meson setup builddir
cd builddir
meson compile
meson install

If you need/want to disable or enable some libccid options then change the first command to use something like:

meson setup builddir -Dserial=true -Dembedded=true

The available options are (file meson.options):

extra_bundle_id

appended to the name of the bundle directory

class

enable the CCIDCLASSDRIVER in Info.plist

composite-as-multislot

composite device are seen as multi-slots (disabled by default)

embedded

for embedded systems [limit RAM and CPU resources by disabling features (log)] (disabled by default)

os_log

use os_log(3) instead of printf() for debug (Sierra 10.12 and up)] (disabled by default)

pcsclite

use pcsc-lite debug support

serial

build the driver for the serial CCID readers (disabled by default)

zlp

enable the Zero Length Packet patch for some Gemalto readers (disabled by default)

In the case of regression

If you need a special configuration that is not possible using meson it is still possible to generate and run the configure script and build libccid as before:

./bootstrap
./configure your_arguments

You can also create a patch and submit it to https://salsa.debian.org/rousseau/PCSC/ or https://github.com/LudovicRousseau/PCSC.

Conclusion

Meson is a nice tool.

I do not expect regression but since version 1.6.0 is the first release with meson support I may have missed some use cases.

Changes:

1.6.0 - 1 June 2024, Ludovic Rousseau

• Add support of

  • Aladdin R.D. JCR SecurBio

  • AvidCard CAC Smart Card Reader

  • FujitsuTechnologySolutions GmbH Dual Smartcard Reader D321

  • Ledger Stax

  • NXP Pegoda 3

  • authenton #1- CTAP2.1

• provide files for meson build tool (replaces autoconf/automake)

• Add possibility to set/get NAD on T=1 for MEP

• multi-slots readers

  • Better handling of reader removal

  • Use CLOCK_MONOTONIC for timeouts

• Some other minor improvements

Changes:

2.0.10 (June 2024)

• add 'swig' in pyproject.toml build requires

• CardMonitoringThread(): do not catch unexpected exceptions

Changes:

2.2.3: Ludovic Rousseau

26 May 2024

• meson:

  • Fix build on Slackware 15

  • fail if both libusb and libudev are used

• Fix memory leak on exit

• libpcscspy: dump an output buffer only if the call succeeded

• Some code cleanup

Changes:

1.5.16 - May 2024, Ludovic Rousseau

• add support of CKA_MODIFIABLE and CKA_DESTROYABLE attributes

• minor improvements