Ludovic Rousseau's blog (Posts about debug)

PCSC API spy using LIBPCSCLITE_DELEGATE

Ludovic Rousseau — Fri, 12 Apr 2024 15:17:59 GMT

As explained in How to use LIBPCSCLITE_DELEGATE? a new mechanism has been introduced for PC/SC calls debug.

Changes

Compared to the previous version documented in PCSC API spy, update:

no need to play with LD_PRELOAD any more
no need to install/uninstall a spy library

Demo

Run your program (here pcsc_scan) with LIBPCSCLITE_DELEGATE defined.

$ LIBPCSCLITE_DELEGATE=libpcscspy.so.0 pcsc_scan
PC/SC device scanner
V 1.7.1 (c) 2001-2022, Ludovic Rousseau <ludovic.rousseau@free.fr>
Using reader plug'n play mechanism
Scanning present readers...
Waiting for the first reader...
^C
SCardGetStatusChange: Command cancelled.

I used Control-C to abort the program because pcsc_scan never ends.

Traces

In another window I get:

$ pcsc-spy
SCardEstablishContext
 i dwScope: SCARD_SCOPE_SYSTEM (0x00000002)
 o hContext: 0x72EC0CEF
 => SCARD_S_SUCCESS [0x00000000]  [0.046759]
SCardGetStatusChange
 i hContext: 0x72EC0CEF
 i dwTimeout: 0x00000000 (0)
 i cReaders: 1
 i szReader: \\?PnP?\Notification
 i  dwCurrentState:  (0x00000000)
 i  dwEventState: SCARD_STATE_IGNORE, SCARD_STATE_CHANGED, SCARD_STATE_UNKNOWN, SCARD_STATE_UNAVAILABLE, SCARD_STATE_PRESENT, SCARD_STATE_EXCLUSIVE, SCARD_STATE_INUSE, SCARD_STATE_MUTE (0x55A373FA63AF)
 i  Atr length: 0x55A373FA63BE (94160513819582)
 i  Atr: NULL
 o szReader: \\?PnP?\Notification
 o  dwCurrentState:  (0x00000000)
 o  dwEventState:  (0x00000000)
 o  Atr length: 0x55A373FA63BE (94160513819582)
 o  Atr: NULL
 => SCARD_E_TIMEOUT [0x8010000A]  [0.002514]
SCardListReaders
 i hContext: 0x72EC0CEF
 i mszGroups: (null)
 o pcchReaders: 0x00000001
 o mszReaders: NULL
 => SCARD_E_NO_READERS_AVAILABLE [0x8010002E]  [0.000045]
SCardListReaders
 i hContext: 0x72EC0CEF
 i mszGroups: (null)
 o pcchReaders: 0x00000001
 o mszReaders: NULL
 => SCARD_E_NO_READERS_AVAILABLE [0x8010002E]  [0.000434]
SCardGetStatusChange
 i hContext: 0x72EC0CEF
 i dwTimeout: 0x0036EE80 (3600000)
 i cReaders: 1
 i szReader: \\?PnP?\Notification
 i  dwCurrentState:  (0x00000000)
 i  dwEventState:  (0x00000000)
 i  Atr length: 0x55A373FA63BE (94160513819582)
 i  Atr: NULL
   SCardCancel
    i hCard: 0x72EC0CEF
    => SCARD_S_SUCCESS [0x00000000]  [0.000741]
 o szReader: \\?PnP?\Notification
 o  dwCurrentState:  (0x00000000)
 o  dwEventState:  (0x00000000)
 o  Atr length: 0x55A373FA63BE (94160513819582)
 o  Atr: NULL
 => SCARD_E_CANCELLED [0x80100002]  [1.015056]
SCardReleaseContext
 i hContext: 0x72EC0CEF
 => SCARD_S_SUCCESS [0x00000000]  [0.000632]

Thread 1/2
Results sorted by total execution time
total time: 1.065758 sec
1.017570 sec (  2 calls) 95.48% SCardGetStatusChange
0.046759 sec (  1 calls)  4.39% SCardEstablishContext
0.000632 sec (  1 calls)  0.06% SCardReleaseContext
0.000479 sec (  2 calls)  0.04% SCardListReaders

Thread 2/2
Results sorted by total execution time
total time: 1.065758 sec
0.000741 sec (  1 calls)  0.07% SCardCancel

The (Python) program pcsc-spy is provided by pcsc-lite. It is included in the Debian libpcsclite-dev package.

Absolute filename

If you want to use a specific spy library or if the library is installed in a directory not handled by the GNU/Linux dynamic loader ld.so you can use an absolute filename.

The script setup_spy.sh is provided by pcsc-lite. It is also included in the Debian libpcsclite-dev package.

$ sh /usr/share/doc/libpcsclite-dev/setup_spy.sh
export LIBPCSCLITE_DELEGATE=/lib/x86_64-linux-gnu/libpcscspy.so.0

If you want to have LIBPCSCLITE_DELEGATE defined and used for all the future executions (maybe not recommanded) you can execute the export command using:

$ source /usr/share/doc/libpcsclite-dev/setup_spy.sh
export LIBPCSCLITE_DELEGATE=/lib/x86_64-linux-gnu/libpcscspy.so.0

Conclusion

It should now be a bit simpler to generate PC/SC call traces.

FAQ: wintypes.h or winscard.h not found

Ludovic Rousseau — Fri, 17 Mar 2023 20:45:00 GMT

One of the most popular search requests that bring people on my website https://pcsclite.apdu.fr/ is about wintypes.h not found.

Problem

For example you try to compile something and get the error:

smartcard/scard/helpers.c:28:10: fatal error: winscard.h: No such file or directory
 #include <winscard.h>
          ^~~~~~~~~~~~

Solution

The PC/SC header files (winscard.h, wintypes.h and some others) are provided by the development pcsclite package.

for Debian, Ubuntu or derivatives the package is pcsclite-dev
for Red Hat, Fedora and derivatives the package is pcsc-lite-devel
for other Unixes, use your favourite search engine 😜

You install the correct package and you try again to build your software.

Conclusion

I hope this blog article will be correctly indexed by search engines to help people find the solution.

PCSC API spy, update

Ludovic Rousseau — Sun, 12 Jun 2022 13:31:00 GMT

10 years ago I documented in "PCSC API spy, third try" a way to generate PC/SC API traces when using pcsc-lite.

Since then the ecosystem has changed. This article is an update of the previous blog article with more up-to-date information.

Changes

The pcsc-spy.py command has been renamed pcsc-spy (in 2012)
The libpcscspy.so library has been moved from /usr/lib/ to /usr/lib/x86_64-linux-gnu/ (for Intel 64-bits CPU systems)
opensc-tool can't be used with LD_PRELOAD= any more

Demo

As before we have two cases for the use of libpcsclite.so.1.

Applications linked with libpcsclite.so.1

This is the case of the pcsc_scan command for example.

You can use the ldd command to know what library has been dynamically linked at build time:

$ ldd /usr/bin/pcsc_scan 
	linux-vdso.so.1 (0x00007fffac11b000)
	libpcsclite.so.1 => /lib/x86_64-linux-gnu/libpcsclite.so.1 (0x00007f85a5f24000)
	libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007f85a5f03000)
	libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f85a5d2a000)
	/lib64/ld-linux-x86-64.so.2 (0x00007f85a5f4f000)

You can use the LD_PRELOAD solution by doing:

In on terminal you run the pcsc-spy program. In another terminal you run:

$ LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libpcscspy.so.0 pcsc_scan -r
libpcsclite_nospy.so.1: cannot open shared object file: No such file or directory
No reader found.

In the first terminal you get the trace:

$ pcsc-spy 
SCardEstablishContext
 i dwScope: SCARD_SCOPE_SYSTEM (0x00000002)
 o hContext: 0x0E4C693B
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.002456]
SCardGetStatusChange
 i hContext: 0x0E4C693B
 i dwTimeout: 0x00000000 (0)
 i cReaders: 1
 i szReader: \\?PnP?\Notification
 i  dwCurrentState:  (0x00000000)
 i  dwEventState: SCARD_STATE_IGNORE, SCARD_STATE_UNKNOWN, SCARD_STATE_UNAVAILABLE, SCARD_STATE_EMPTY, SCARD_STATE_INUSE, SCARD_STATE_MUTE (0x55EDE352031D)
 i  Atr length: 0x55EDE352032C (94480209412908)
 i  Atr: NULL
 o szReader: \\?PnP?\Notification
 o  dwCurrentState:  (0x00000000)
 o  dwEventState:  (0x00000000)
 o  Atr length: 0x55EDE352032C (94480209412908)
 o  Atr: NULL
 => Command timeout. (SCARD_E_TIMEOUT [0x8010000A])  [0.007774]
SCardListReaders
 i hContext: 0x0E4C693B
 i mszGroups: (null)
 o pcchReaders: 0x00000001
 o mszReaders: NULL
 => Cannot find a smart card reader. (SCARD_E_NO_READERS_AVAILABLE [0x8010002E])  [0.000908]
SCardListReaders
 i hContext: 0x0E4C693B
 i mszGroups: (null)
 o pcchReaders: 0x00000001
 o mszReaders: NULL
 => Cannot find a smart card reader. (SCARD_E_NO_READERS_AVAILABLE [0x8010002E])  [0.000531]

Thread 1/1
Results sorted by total execution time
total time: 0.011769 sec
0.007774 sec (  1 calls) 66.06% SCardGetStatusChange
0.002456 sec (  1 calls) 20.87% SCardEstablishContext
0.001439 sec (  2 calls) 12.23% SCardListReaders

Application loading libpcsclite.so.1

In this case you need to modify the system configuration to replace the libpcsclite.so.1 library. This is done by the install_spy.sh script. You only need to run the script once.

$ sudo bash /usr/share/doc/libpcsclite-dev/install_spy.sh
Using directory: /lib/x86_64-linux-gnu
Spying library is: /lib/x86_64-linux-gnu/libpcscspy.so.0

On Debian (and derivatives like Ubuntu) and with pcsc-lite version 1.9.8 and more the script is provided by the libpcsclite-dev package.

In on terminal you run the pcsc-spy program. In another terminal you run the program you want to spy. For example:

$ opensc-tool -a
No smart card readers found.
Failed to connect to reader: No readers found

In the first terminal you get the trace:

SCardEstablishContext
 i dwScope: SCARD_SCOPE_USER (0x00000000)
 o hContext: 0x2667F6DA
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.005316]
SCardListReaders
 i hContext: 0x2667F6DA
 i mszGroups: (null)
 o pcchReaders: 0x00000001
 o mszReaders: NULL
 => Cannot find a smart card reader. (SCARD_E_NO_READERS_AVAILABLE [0x8010002E])  [0.000079]
SCardReleaseContext
 i hContext: 0x2667F6DA
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000074]

Thread 1/1
Results sorted by total execution time
total time: 0.007195 sec
0.005316 sec (  1 calls) 73.88% SCardEstablishContext
0.000079 sec (  1 calls)  1.10% SCardListReaders
0.000074 sec (  1 calls)  1.03% SCardReleaseContext

Do not forget to restore the system configuration using the uninstall_spy.sh script.

$ sudo bash /usr/share/doc/libpcsclite-dev/uninstall_spy.sh
Using directory: /lib/x86_64-linux-gnu

Redirection in a file

It is still possible to redirect the traces in a file. Instead of running pcsc-spy you do:

$ mkfifo ~/pcsc-spy
$ cat ~/pcsc-spy > logfile

And in another terminal you start the application as indicated above (i.e. using LD_PRELOAD= or after running install_spy.sh)

You can then analyse the logs later using:

$ pcsc-spy logfile

Remarks

Bugs found

I note that SCardReleaseContext() is not always called by pcsc_scan before exit. I just fixed this problem in pcsc-tools.

Install/uninstall

It is important to run the uninstall_spy.sh script to undo the changes made by the install_spy.sh script.

It is important you undo the changes before any execution of the ldconfig (configure dynamic linker run-time bindings) administration command. ldconfig is used, for example, during the installation of a package.

If you run uninstall_spy.sh after an execution of ldconfig you may get a broken libpcsclite installation with an error like:

$ pcsc_scan 
pcsc_scan: error while loading shared libraries:
libpcsclite.so.1: cannot open shared object file: No such file or directory

To fix te problem you can force reinstall the libpcsclite1 (or equivalent) package.

Order of execution

It is important to start pcsc-spy before the application you want to spy. If you start pcsc-spy after the application you have 2 cases:

if the fifo file ~/pcsc-spy does not yet exist then pcsc-spy will display nothing
if the fifo file ~/pcsc-spy already exists then libpcscspy.so will use it to send logs and will be blocked until something reads the file (pcsc-spy or the cat command to redirect the content)

Conclusion

I hope this update is useful.

if you have ideas to improve the logs please contact me.

Level 1.5 smart card support on macOS

Ludovic Rousseau — Thu, 01 Mar 2018 13:07:00 GMT

In a previous article "Level 1 smart card support on Mac OS X" I described some simple commands to check if the smart card stack is working correctly on a macOS system.

By re-reading the presentation "Working with Smart Cards: macOS and Security" by Richard Purves I discovered a new command.

I already knew "system_profiler SPUSBDataType" to list the USB devices. I mentioned it in "Level 1 smart card support on Mac OS X" to check the USB reader is seen by the system. But system_profiler provides a better command for smart cards.

SPSmartCardsDataType

system_profiler has another very interesting command: system_profiler SPSmartCardsDataType

Clean macOS installation

Example 1:

$ system_profiler SPSmartCardsDataType
SmartCards:

    Readers:

      #01: Cherry KC 1000 SC (ATR:<3b7f9600 00803180 65b08441 3df612ff fe829000>)

    Reader Drivers:

      #01: org.debian.alioth.pcsclite.smartcardccid:1.4.27 (/usr/libexec/SmartCardServices/drivers/ifd-ccid.bundle)

    Tokend Drivers:

    SmartCard Drivers:

      #01: com.apple.CryptoTokenKit.pivtoken:1.0 (/System/Library/Frameworks/CryptoTokenKit.framework/PlugIns/pivtoken.appex)

    Available SmartCards (keychain):

    Available SmartCards (token):

You get a lot of useful information:

list of smart card readers
list of installed reader drivers
list of tokend drivers
list of smart card drivers
available smart cards (keychain)
available smart cards (token)

What you can see in my example:

I use a Cherry KC 1000 SC reader. A card is inserted in the reader and you see the ATR.
by default Apple provides a CCID driver
by default Apple provides a PIV CryptoTokenKit token to support Personal Identity Verification cards

Using SafeNet Authentication Client

Example 2:

$ system_profiler SPSmartCardsDataType 
SmartCards:

    Readers:

      #01: Gemalto PC Twin Reader (ATR:<3b7f9600 00803180 65b08503 00ef120f fe829000>)

    Reader Drivers:

      #01: org.debian.alioth.pcsclite.smartcardccid:1.4.27 (/usr/libexec/SmartCardServices/drivers/ifd-ccid.bundle)
      #02: com.SafeNet.eTokenIfdh:9.0.0.0 (/Library/Frameworks/eToken.framework/Versions/A/aks-ifdh.bundle)
      #03: com.gemalto.ifd-bccid:1.0 (/usr/local/libexec/SmartCardServices/drivers/ifd-bccid.bundle)
      #04: org.debian.alioth.pcsclite.smartcardccid:1.4.27 (/usr/local/libexec/SmartCardServices/drivers/ifd-ccid-SafeNet-eToken5300.bundle)
      #05: (null):(null) (/Library/Frameworks/eToken.framework/Versions/A/ikey-ifdh.bundle)

    Tokend Drivers:

      #01: com.Safenet.eTokend:9.0 (/Library/Frameworks/eToken.framework/Versions/A/eTokend.tokend)

    SmartCard Drivers:

      #01: com.apple.CryptoTokenKit.pivtoken:1.0 (/System/Library/Frameworks/CryptoTokenKit.framework/PlugIns/pivtoken.appex)
      #02: com.gemalto.Gemalto-Smart-Card-Token.PKCS11-Token:1.0 (/Library/Frameworks/eToken.framework/Versions/A/SafeNet Authentication Client.app/Contents/PlugIns/PKCS11 Token.appex)

    Available SmartCards (keychain):

        com.gemalto.Gemalto-Smart-Card-Token.PKCS11-Token:9A522A4489DFA3DE:

          #01: Kind: private RSA 2048-bit, Certificate: <1cc4a99c 25e2b4eb 381850d2 e8e7a9a8 8d258b31>, Usage: Sign Decrypt Unwrap 
          #02: Kind: private RSA 2048-bit, Certificate: <425fa8c1 27ad75a1 aec73183 2b053b41 38befe7f>, Usage: Sign Decrypt Unwrap 
          #03: Kind: private RSA 4096-bit, Certificate: <16b5321b d4c7f3e0 e68ef3bd d2b03aee b23918d1>, Usage: Sign Decrypt Unwrap 
          #04: Kind: private RSA 4096-bit, Certificate: <16b5321b d4c7f3e0 e68ef3bd d2b03aee b23918d1>, Usage: Sign Decrypt Unwrap 
          #05: Kind: private RSA 2048-bit, Certificate: <31fde547 b4ca58d4 7b6231c2 62730efd 8c7538a1>, Usage: Sign Derive Decrypt Unwrap 

    Available SmartCards (token):

        com.gemalto.Gemalto-Smart-Card-Token.PKCS11-Token:9A522A4489DFA3DE:

          #01: Kind: private RSA 2048-bit, Certificate: <1cc4a99c 25e2b4eb 381850d2 e8e7a9a8 8d258b31>, Usage: Sign Decrypt Unwrap 
          #02: Kind: private RSA 2048-bit, Certificate: <425fa8c1 27ad75a1 aec73183 2b053b41 38befe7f>, Usage: Sign Decrypt Unwrap 
          #03: Kind: private RSA 4096-bit, Certificate: <16b5321b d4c7f3e0 e68ef3bd d2b03aee b23918d1>, Usage: Sign Decrypt Unwrap 
          #04: Kind: private RSA 2048-bit, Certificate: <31fde547 b4ca58d4 7b6231c2 62730efd 8c7538a1>, Usage: Sign Derive Decrypt Unwrap 
          #05: Certificate <1a222d8f 7458d082 d413fbdb 40c85f56 f48def63>

In this second example I installed SAC (SafeNet Authentication Client) from Gemalto. You can see some differences:

more reader drivers are installed
a tokend driver is installed
another SmartCard (Crypto Token Kit or CTK) driver is installed
the card inserted in the reader is available in the keychain

Conclusion

This command provides information of a higher level that pcsctest.
You know what drivers (for readers and for cards) are installed.

PCSC framework spy: broken since Mac OS X Yosemite

Ludovic Rousseau — Tue, 23 Feb 2016 14:18:00 GMT

In "PCSC API spy, on Mac OS X" I proposed a way to spy on all PC/SC calls of an application.

A few months later Yosemite was available and my spying library does not work any more ☹.

PCSC framework replacement: fails

Example of failure:

$ DYLD_FRAMEWORK_PATH=/tmp pcsc_scan
PC/SC device scanner
V /Users/lroussea/Documents/sc/costa/pcsc-tools (c) 2001-2011, Ludovic Rousseau 
Compiled with PC/SC lite version: 1.4.0
SCardEstablishContext: Service not available.

Spy output (in a second terminal window):

$ ./pcsc-spy
SCardEstablishContext
 i dwScope: SCARD_SCOPE_SYSTEM (0x00000002)
 o hContext: 0x00000000
 => Service not available. (SCARD_E_NO_SERVICE [0x8010001D])  [0.000001109]
SCardReleaseContext
 i hContext: 0x00000000
 => Invalid handle. (SCARD_E_INVALID_HANDLE [0x80100003])  [0.000000006]

Results sorted by total execution time
total time: 0.001138 sec
0.001109 sec (  1 calls) 97.45% SCardEstablishContext
0.000006 sec (  1 calls)  0.53% SCardReleaseContext

If I run pcsc_scan alone, with no PC/SC spy, then the command runs as expected.

Something detects the usage of a new PCSC framework and rejects the first call. I guess the culprit is the original PCSC framework itself and this is a new security feature from Yosemite.

Running the application as root (using sudo) does not help.

SIP: System Integrity Protection

A new change since El Capitan is that the use of DYLD_FRAMEWORK_PATH does not work for programs in protected directories, like /usr/bin/.

$ type pcsctest
pcsctest is hashed (/usr/bin/pcsctest)

$ DYLD_FRAMEWORK_PATH=/tmp pcsctest

MUSCLE PC/SC Lite Test Program

Testing SCardEstablishContext    : Command successful.
Testing SCardGetStatusChange 
Please insert a working reader   : Command successful.
Testing SCardListReaders         : Command successful.
Reader 01: Gemalto PC Twin Reader
Enter the reader number          : ^C

Here the command succeeds but nothing is sent over the spy pipe.

In Yosemite I could use DYLD_FRAMEWORK_PATH=/tmp but with the same results as described above. On El Capitan the dynamic linker dyld just ignores DYLD_FRAMEWORK_PATH.

Another way to check that is to use lldb, the debugger provided with Xcode.

$ lldb pcsctest
(lldb) target create "pcsctest"
Current executable set to 'pcsctest' (x86_64).
(lldb) run
error: process exited with status -1 (cannot attach to process due to System Integrity Protection)
(lldb) quit

Conclusion

I know no way to spy the PC/SC calls done by an application on Mac OS X (with version >= 10.10).

This is problematic because PC/SC is still unstable on El Capitan. See "OS X El Capitan and smart cards: known bugs" for example. In some cases it would really help to know what PC/SC call returns an error to be able to:

Report the error to Apple if it is a bug in PC/SC
Tell the customer that it is a bug on Apple side
Try to find a way to avoid the problem, if possible

CCID USB spy using Wireshark

Ludovic Rousseau — Wed, 08 Oct 2014 19:35:00 GMT

Sometimes you need to know exactly what is happening at the USB level. You have two options:

use a hardware USB analyzer
use a software USB analyzer

Since I do not have the budget to buy a hardware USB monitor I will use the software solution.

Wireshark

Since some time, it is possible to use the wonderful Wireshark program to display and analyze USB frames. Wireshark is mainly used for analyzing network packets but it is also possible to display USB packets. Wireshark is even able to display the CCID commands inside the USB packets.

How-to

A documentation is available at USB capture setup and also at Capturing USB data through Wireshark.
This article describes what I did.

Setup the kernel

You first need to load the usbmon kernel module.

$ sudo modprobe usbmon

tshark (a command line tool) should now be able to capture on usbmon interfaces. Check it using:

$ tshark -D
1. eth0
2. any
3. lo (Loopback)
4. nflog
5. nfqueue
6. usbmon1
7. usbmon2

In my case I have 2 USB buses labeled usbmon1 and usbmon2.

Capture the USB frames

Before capturing the USB frames you need to know on which USB bus is connected your device.

Identify the device USB bus

$ lsusb 
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 004: ID 08e6:3437 Gemplus GemPC Twin SmartCard Reader
Bus 002 Device 002: ID 80ee:0021 VirtualBox USB Tablet
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

In my case the device I want to study is on the bus 002 so I will use usbmon2.

Start the capture

$ tshark -i usbmon2 -w trace1.pcap
Capturing on 'usbmon2'
tshark: The capture session could not be initiated on interface 'usbmon2' (Can't open USB bus file /sys/kernel/debug/usb/usbmon/2t: Permission denied).
Please check to make sure you have sufficient permissions, and that you have the proper interface or pipe specified.

For security reasons tshark refuses to be run as root. So I needed to change some file access rights.

$ sudo chmod +rx /sys/kernel/debug/
$ sudo chmod a+rw /sys/kernel/debug/usb/usbmon/2t

Then (re)start tshark and use Ctrl-C to stop after some traffic has been captured.

$ tshark -i usbmon2 -w trace1.pcap
Capturing on 'usbmon2'
1270 tshark: Can't get packet-drop statistics: Can't open USB stats file /sys/kernel/debug/usb/usbmon/2s: Permission denied
Please report this to the Wireshark developers.
http://bugs.wireshark.org/
(This is not a crash; please do not report it as such.)

Capture analysis

The file trace1.pcap contains the USB frames and can be displayed using the graphical interface of Wireshark.

Enable the CCID decoder

Unless you can read the CCID protocol from hexadecimal, it is a good idea to tell Wireshark to decode the USB frames as USBCCID.
Go in the menu "Analyze" -> "Decode as..." and select USBCCID in the dialog.

Wireshark will then display the USB frames with nice CCID names:

Here you can see a CCID Power On command.

The command name is displayed in the top window: "Packet - PC to Reader: ICC Power On"
And the content of the command (the 10 last bytes specific to CCID) are documented in the lower window: "Message Type: PC_to_RDR_IccPowerOn (0x62)", etc.

I do not expect every one to use Wireshark to look at CCID frames. But if you have a problem with a CCID reader and wants to know exactly what is happening Wireshark can help you for a very very limited budget (Wireshark is a free software under GNU GPL v2 license).

This blog article is also a way for me to document how to do it for the next time :-)

Conclusion

Wireshark is a great tool.
Linux is a great kernel.
Debian GNU/Linux is a great operating system.

USB issues with a Raspberry Pi

Ludovic Rousseau — Thu, 24 Apr 2014 17:50:00 GMT

Some people report problems with my CCID driver and a Raspberry Pi. The problem is not with the CCID driver but with the Raspberry Pi itself.

I don't know if the problem is hardware, software or a combination of the two. I found a description of the problem on the excellent website yoctopuce.com. For example from the article "Cook and Hold with Raspberry Pi (video)" you can read:

There is one caveat on the Raspberry Pi : the USB support is still somewhat ~~buggy~~ perfectible, and we will need to configure it to make it work reliably. The problem is, the RasPi will occasionally drop USB packets for "full-speed" peripherals (such as keyboard, mouse, modems, as well as some audio devices) when working in standard "high-speed" mode. The problem is less acute with the most recent firmware, but it is not completely solved. The only reliable workaround for now is to force all peripherals to run in "full-speed" mode. This will have the negative side effect of limiting all peripherals (including the on-board network adapter) to 1.5 MBytes/s, but anyway, the Raspberry Pi is not designed to be a race horse...

To force USB to run in "full-speed" mode, simply add dwc_otg.speed=1 to the /boot/cmdline.txt file, as follows:
dwc_otg.lpm_enable=0 console=ttyAMA0,115200 kgdboc=ttyAMA0,115200
dwc_otg.speed=1 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4
elevator=deadline rootwait

Level 1 smart card support on Mac OS X

Ludovic Rousseau — Thu, 20 Mar 2014 15:03:00 GMT

It may not be easy to check if a smart card stack works or not. I will explain what you can do as a first step to check your smart card stack on Mac OS X.

pcsctest

Apple provides a command line tool pcsctest. It is an evolution of testpcsc provided by the "official" pcsc-lite.

The Apple pcsctest source code is available at http://opensource.apple.com/source/SmartCardServices/SmartCardServices-55111/src/PCSC/testpcsc.c

The good news is that this command line tool is installed by default. So every Mac OS X install should have it out of the box.

Command line tool

To run a command line tool you need to start the Terminal application from the /Applications/Utilities/ directory.

Terminal icon

You will then get a Terminal window with a prompt

Normal execution

In green the commands entered by the user.
In yellow the important information.

If your reader is connected and a smart card is inserted you should get something like:

$ pcsctest 

MUSCLE PC/SC Lite Test Program

Testing SCardEstablishContext    : Command successful.
Testing SCardGetStatusChange 
Please insert a working reader   : Command successful.
Testing SCardListReaders         : Command successful.
Reader 01: Gemplus GemPC Twin 00 00
Enter the reader number          : 1
Waiting for card insertion         
                                 : Command successful.
Testing SCardConnect             : Command successful.
Testing SCardStatus              : Command successful.
Current Reader Name              : Gemplus GemPC Twin 00 00
Current Reader State             : 0x34
Current Reader Protocol          : 0x0
Current Reader ATR Size          : 9 (0x9)
Current Reader ATR Value         : 3B 65 00 00 20 63 CB A6 A0 
Testing SCardDisconnect          : Command successful.
Testing SCardReleaseContext      : Command successful.
Testing SCardEstablishContext    : Command successful.
Testing SCardGetStatusChange 
Please insert a working reader   : Command successful.
Testing SCardListReaders         : Command successful.
Reader 01: Gemplus GemPC Twin 00 00
Enter the reader number          : 1
Waiting for card insertion         
                                 : Command successful.
Testing SCardConnect             : Command successful.
Testing SCardStatus              : Command successful.
Current Reader Name              : Gemplus GemPC Twin 00 00
Current Reader State             : 0x34
Current Reader Protocol          : 0x0
Current Reader ATR Size          : 9 (0x9)
Current Reader ATR Value         : 3B 65 00 00 20 63 CB A6 A0 
Testing SCardDisconnect          : Command successful.
Testing SCardReleaseContext      : Command successful.

PC/SC Test Completed Successfully !

You should note:

the reader name Gemplus GemPC Twin 00 00
the card ATR 3B 65 00 00 20 63 CB A6 A0

In this case the reader is correctly found and the communication with the card is working.

You can then use the online Smart card ATR parsing tool to check the ATR corresponds to the card you inserted. In the present case it is a French banking card.

No reader connected

$ pcsctest 

MUSCLE PC/SC Lite Test Program

Testing SCardEstablishContext    : Service not available.

On Mac OS X the PC/SC service (in fact the pcscd daemon) is started by the securityd process at boot and when a USB smart card reader is connected.
So if no reader is connected you get the error: "Service not available" because pcscd is not yet running.

No smart card inserted

$ pcsctest 

MUSCLE PC/SC Lite Test Program

Testing SCardEstablishContext    : Command successful.
Testing SCardGetStatusChange 
Please insert a working reader   : Command successful.
Testing SCardListReaders         : Command successful.
Reader 01: Gemplus GemPC Twin 00 00
Enter the reader number          : 1
Waiting for card insertion

The program is then waiting for a card insertion.

If you have a card inserted and you do not get the ATR or an error then you have a problem.

If you insert a card and get the error "Card is unpowered" then you may have inserted the card the wrong way (or your card is dead).

System information

If your reader is connected but you can't see it with pcsctest then maybe the USB device is not seen by Mac OS X.

You can use the System Information application from the /Applications/Utilities/ directory.

System Information icon

In the application you select the USB subsection in the Hardware section and can see all the USB devices known by the system.

If you can't see your USB smart card reader then you have a USB issue, not a PC/SC issue.

Command line

You can also use the equivalent command in the Terminal:

$ system_profiler SPUSBDataType

Conclusion

These first steps are easy to execute on Mac OS X. If the pcsctest test succeeds then you can be confident that the smart card reader and the PC/SC layer are working correctly.

If the pcsctest test fails then you need to go to a level 2 smart card support on Mac OS X.

PCSC API spy, on Mac OS X

Ludovic Rousseau — Sat, 08 Feb 2014 16:49:00 GMT

In a previous article "PCSC API spy, third try" I described a way to get a nice log of all the PC/SC calls made by an application. The example was using an application on GNU/Linux. A version for Mac OS X was planned but not yet available at that time.

I now realise I finished the Mac OS X version of pcsc-spy but have not yet blogged about it. It is time to fix this.

Installation

pcsc-spy is part of (the official) pcsc-lite. You can get it from the PCSC lite project web page. The latest version of pcsc-lite as I write this blog entry is 1.8.10.

$ curl -O https://alioth.debian.org/frs/download.php/file/3963/pcsc-lite-1.8.10.tar.bz2
$ tar xjf pcsc-lite-1.8.10.tar.bz2
$ cd pcsc-lite-1.8.10/
$ ./configure
[...]
$ cd src/spy
$ make
$ make framework

Now you can find a PCSC.framework directory that is the equivalent of libpcscspy.so on GNU/Linux.

The installation is not automatic but very easy. You copy the PCSC.framework directory in /tmp

$ cp -a PCSC.framework /tmp

Copy the official PCSC.framework (binary only) in /tmp

$ cp /System/Library/Frameworks/PCSC.framework/PCSC /tmp

Since we use the temporary directory /tmp the log/debug files will be automatically erased on the next system boot. No side effect.

Execution

In a Terminal application window (shell) run the pcsc-spy command:

$ ./pcsc-spy

In another Terminal application windows run the application you want to debug:

$ DYLD_FRAMEWORK_PATH=/tmp pcsctest

MUSCLE PC/SC Lite Test Program

Testing SCardEstablishContext    : Command successful.
Testing SCardGetStatusChange 
Please insert a working reader   : Command successful.
Testing SCardListReaders         : Command successful.
Reader 01: Feitian bR301 00 00
Enter the reader number          : 1
Waiting for card insertion         
                                 : Command successful.
Testing SCardConnect             : Command successful.
Testing SCardStatus              : Command successful.
Current Reader Name              : Feitian bR301 00 00
Current Reader State             : 0x34
Current Reader Protocol          : 0x0
Current Reader ATR Size          : 12 (0xc)
Current Reader ATR Value         : 3B A7 00 40 18 80 65 A2 08 01 01 52 
Testing SCardDisconnect          : Command successful.
Testing SCardReleaseContext      : Command successful.
Testing SCardEstablishContext    : Command successful.
Testing SCardGetStatusChange 
Please insert a working reader   : Command successful.
Testing SCardListReaders         : Command successful.
Reader 01: Feitian bR301 00 00
Enter the reader number          : 1
Waiting for card insertion         
                                 : Command successful.
Testing SCardConnect             : Command successful.
Testing SCardStatus              : Command successful.
Current Reader Name              : Feitian bR301 00 00
Current Reader State             : 0x34
Current Reader Protocol          : 0x0
Current Reader ATR Size          : 12 (0xc)
Current Reader ATR Value         : 3B A7 00 40 18 80 65 A2 08 01 01 52 
Testing SCardDisconnect          : Command successful.
Testing SCardReleaseContext      : Command successful.

PC/SC Test Completed Successfully !

In the first Terminal window you will get the colorfull (oh yeah!) log output:

SCardEstablishContext
 i dwScope: SCARD_SCOPE_SYSTEM (0x00000002)
 o hContext: 0x0103253B
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000722]
SCardGetStatusChange
 i hContext: 0x0103253B
 i dwTimeout: 0xFFFFFFFF (4294967295)
 i cReaders: 0
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000044]
SCardListReaders
 i hContext: 0x0103253B
 i mszGroups: (null)
 o pcchReaders: 0x00000015
 o mszReaders: NULL
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000059]
SCardListReaders
 i hContext: 0x0103253B
 i mszGroups: (null)
 o pcchReaders: 0x00000015
 o mszReaders: Feitian bR301 00 00
 o mszReaders: 
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000042]
SCardGetStatusChange
 i hContext: 0x0103253B
 i dwTimeout: 0xFFFFFFFF (4294967295)
 i cReaders: 1
 i szReader: Feitian bR301 00 00
 i  dwCurrentState: SCARD_STATE_EMPTY (0x00000010)
 i  dwEventState: SCARD_STATE_IGNORE, SCARD_STATE_CHANGED, SCARD_STATE_UNKNOWN, SCARD_STATE_UNAVAILABLE, SCARD_STATE_EXCLUSIVE, SCARD_STATE_INUSE, SCARD_STATE_EMPTY, SCARD_STATE_MUTE, SCARD_STATE_PRESENT, SCARD_STATE_UNPOWERED, SCARD_STATE_ATRMATCH (0x00007FFF)
 i  Atr length: 0x00000012 (18)
 i  Atr: 00 00 00 00 68 70 E7 0D 01 00 00 00 01 00 00 00 00 00
 o szReader: Feitian bR301 00 00
 o  dwCurrentState: SCARD_STATE_EMPTY (0x00000010)
 o  dwEventState: SCARD_STATE_CHANGED, SCARD_STATE_PRESENT (0x00000022)
 o  Atr length: 0x0000000C (12)
 o  Atr: 3B A7 00 40 18 80 65 A2 08 01 01 52
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000163]
SCardConnect
 i hContext: 0x0103253B
 i szReader Feitian bR301 00 00
 i dwShareMode: SCARD_SHARE_SHARED (0x00000002)
 i dwPreferredProtocols: 0x00000003 (T=0, T=1)
 i phCard 0x00007FFF (32767)
 i pdwActiveProtocol 0x00000000 (0)
 o phCard 0x0001616A (90474)
 o dwActiveProtocol: T=0 (0x00000001)
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000411198]
SCardStatus
 i hCard: 0x0001616A
 i pcchReaderLen 0x00000034 (52)
 i pcbAtrLen 0x00000021 (33)
 o cchReaderLen 0x00000014 (20)
 o mszReaderName Feitian bR301 00 00
 o dwState 0x00000034 (52)
 o dwProtocol 0x00000001 (1)
 o bAtrLen 0x0000000C (12)
 o bAtr 3B A7 00 40 18 80 65 A2 08 01 01 52
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000473]
SCardDisconnect
 i hCard: 0x0001616A
 i dwDisposition: SCARD_UNPOWER_CARD (0x00000002)
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000594971]
SCardReleaseContext
 i hContext: 0x0103253B
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000209]
SCardEstablishContext
 i dwScope: SCARD_SCOPE_SYSTEM (0x00000002)
 o hContext: 0x01035D3C
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000541]
SCardGetStatusChange
 i hContext: 0x01035D3C
 i dwTimeout: 0xFFFFFFFF (4294967295)
 i cReaders: 0
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000033]
SCardListReaders
 i hContext: 0x01035D3C
 i mszGroups: (null)
 o pcchReaders: 0x00000015
 o mszReaders: NULL
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000034]
SCardListReaders
 i hContext: 0x01035D3C
 i mszGroups: (null)
 o pcchReaders: 0x00000015
 o mszReaders: Feitian bR301 00 00
 o mszReaders: 
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000039]
SCardGetStatusChange
 i hContext: 0x01035D3C
 i dwTimeout: 0xFFFFFFFF (4294967295)
 i cReaders: 1
 i szReader: Feitian bR301 00 00
 i  dwCurrentState: SCARD_STATE_EMPTY (0x00000010)
 i  dwEventState: SCARD_STATE_CHANGED, SCARD_STATE_PRESENT (0x00000022)
 i  Atr length: 0x0000000C (12)
 i  Atr: 3B A7 00 40 18 80 65 A2 08 01 01 52
 o szReader: Feitian bR301 00 00
 o  dwCurrentState: SCARD_STATE_EMPTY (0x00000010)
 o  dwEventState: SCARD_STATE_CHANGED, SCARD_STATE_PRESENT (0x00000022)
 o  Atr length: 0x0000000C (12)
 o  Atr: 3B A7 00 40 18 80 65 A2 08 01 01 52
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000129]
SCardConnect
 i hContext: 0x01035D3C
 i szReader Feitian bR301 00 00
 i dwShareMode: SCARD_SHARE_SHARED (0x00000002)
 i dwPreferredProtocols: 0x00000003 (T=0, T=1)
 i phCard 0x0001616A (90474)
 i pdwActiveProtocol 0x00000001 (1)
 o phCard 0x00011242 (70210)
 o dwActiveProtocol: T=0 (0x00000001)
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000411238]
SCardStatus
 i hCard: 0x00011242
 i pcchReaderLen 0x00000034 (52)
 i pcbAtrLen 0x00000021 (33)
 o cchReaderLen 0x00000014 (20)
 o mszReaderName Feitian bR301 00 00
 o dwState 0x00000034 (52)
 o dwProtocol 0x00000001 (1)
 o bAtrLen 0x0000000C (12)
 o bAtr 3B A7 00 40 18 80 65 A2 08 01 01 52
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000465]
SCardDisconnect
 i hCard: 0x00011242
 i dwDisposition: SCARD_UNPOWER_CARD (0x00000002)
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000594863]
SCardReleaseContext
 i hContext: 0x01035D3C
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000369]

Results sorted by total execution time
total time: 4.221649 sec
1.189834 sec (  2 calls) 28.18% SCardDisconnect
0.822436 sec (  2 calls) 19.48% SCardConnect
0.001263 sec (  2 calls)  0.03% SCardEstablishContext
0.000938 sec (  2 calls)  0.02% SCardStatus
0.000578 sec (  2 calls)  0.01% SCardReleaseContext
0.000369 sec (  4 calls)  0.01% SCardGetStatusChange
0.000174 sec (  4 calls)  0.00% SCardListReaders

Analysis

PC/SC commands are in blue
Input arguments are in green
Output arguments are in mangenta
Errors are in bold red
The last part of the log contains some statistics about: functions called and times consumed by each of them

Raw log file

If you want to store a log file for a later analysis or if you want to send me a log trace it is better to store the log in raw format. You can do that (as on GNU/Linux) by doing:

$ mkfifo ~/pcsc-spy
$ cat ~/pcsc-spy > logfile

and run your PC/SC application.

The API trace is stored in the file logfile. It is displayed using:

$ pcsc-spy.py logfile

Documentation

The documentation is included with the pcsc-lite source code and is also available online at pcsc-spy.1 manpage.

Conclusion

It is easy to generate a nice PC/SC log on Mac OS X.

PCSC API spy, third try

Ludovic Rousseau — Fri, 18 Nov 2011 08:52:00 GMT

[UPDATE from 2022]: see also "PCSC API spy, update".

I already blogged about how to spy the PCSC API in PCSC API spy for GNU systems and PCSC API spy, another way. But I am still not happy with the limitations and side effects.

Limitations of previous solutions

ltrace

ltrace is able to trace the calls to any library (including libpcsclite.so.1). But one major limitation is that it does not work if the library is not linked to the executable. It does not work when:

libpcsclite.so.1 is used by a library used by the executable (like a PKCS#11 library)
libpcsclite.so.1 is dynamically loaded using dlopen() as is done by OpenSC

Internal tracing

Internal tracing do not have the limitations of ltrace. But one major drawback is the need to rebuild pcsc-lite with a specific configuration. This may be very difficult or impossible to do on a production system.

Use an independent library

The new idea is to not need to rebuild pcsc-lite. Instead we will use a new library that will be placed between the PC/SC client and the PC/SC library. This new library will spy all the calls and send them to a pretty displayer.

+------------------+
|  PC/SC client    |
+------------------+
        |
+------------------+    +-------------+
| libpcscspy.so.0  | -> | pcsc-spy.py |
+------------------+    +-------------+
        |
+------------------+
| libpcsclite.so.1 |
+------------------+

Two configurations are available

To be able to spy the PC/SC layer the application flow must be modified so that all PC/SC calls are redirected.

Applications linked with libpcsclite.so.1

We will use the standard LD_PRELOAD loader option to load our spying library.

Example:
LD_PRELOAD=/usr/lib/libpcscspy.so opensc-tool -a

Application loading libpcsclite.so.1

This is the case for the PC/SC wrappers like pyscard (for Python) and pcsc-perl (for Perl). The LD_PRELOAD mechanism can't be used. Instead we replace the libpcsclite.so.1 library by the spying one.

Use install_spy.sh and uninstall_spy.sh to install and uninstall the spying library.

Using the spying library without pcsc-spy.py is not a problem but has side effects:

a line "libpcsclite_nospy.so.1: cannot open shared object file: No such file or directory" will be displayed
some CPU time will be lost because of the PC/SC calls redirection

Starting the spy tool

Direct output

$ pcsc-spy.py

Store for later use

If a command argument is passed we use it instead of the default ~/pcsc-spy FIFO file. It is then possible to record an execution log and use pcsc-spy.py multiple times on the same log.

To create the log file just do:

$ mkfifo ~/pcsc-spy
$ cat ~/pcsc-spy > logfile

and run your PC/SC application. The API trace is stored in the file logfile. It is displayed using:

$ pcsc-spy.py logfile

Example using OpenSC

Executed command

$ LD_PRELOAD=/usr/lib/libpcscspy.so opensc-tool -a
Using reader with a card: Gemalto GemPC Twin 00 00
3b:9f:95:81:31:fe:9f:00:65:46:53:05:30:06:71:df:00:00:00:81:61:0f:d9

API log

$ pcsc-spy.py
SCardEstablishContext
 i dwScope: SCARD_SCOPE_USER (0x00000000)
 o hContext: 0x0103E68C
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000219919]
SCardListReaders
 i hContext: 0x0103E68C
 i mszGroups: (null)
 o pcchReaders: 0x0000001A
 o mszReaders: NULL
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000128]
SCardListReaders
 i hContext: 0x0103E68C
 i mszGroups: (null)
 o pcchReaders: 0x0000001A
 o mszReaders: Gemalto GemPC Twin 00 00
 o mszReaders: 
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000101]
SCardGetStatusChange
 i hContext: 0x0103E68C
 i dwTimeout: 0x00000000 (0)
 i cReaders: 1
 i szReader: Gemalto GemPC Twin 00 00
 i  dwCurrentState:  (0x00000000)
 i  dwEventState:  (0x00000000)
 i  Atr length: 0x00000000 (0)
 i  Atr: 
 o szReader: Gemalto GemPC Twin 00 00
 o  dwCurrentState:  (0x00000000)
 o  dwEventState: SCARD_STATE_CHANGED, SCARD_STATE_PRESENT (0x00000022)
 o  Atr length: 0x00000017 (23)
 o  Atr: 3B 9F 95 81 31 FE 9F 00 65 46 53 05 30 06 71 DF 00 00 00 81 61 0F D9
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000184]
SCardConnect
 i hContext: 0x0103E68C
 i szReader Gemalto GemPC Twin 00 00
 i dwShareMode: SCARD_SHARE_SHARED (0x00000002)
 i dwPreferredProtocols: 0x00000003 (T=0, T=1)
 i phCard 0x02432010 (37953552)
 i pdwActiveProtocol 0x00000020 (32)
 o phCard 0x00015425 (87077)
 o dwActiveProtocol: T=1 (0x00000002)
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000020242]
SCarControl
 i hCard: 0x00015425
 i dwControlCode: CM_IOCTL_GET_FEATURE_REQUEST (0x42000D48)
 i bSendLength 0x00000000 (0)
 i bSendBuffer
 i  NULL
 o bRecvLength 0x00000012 (18)
 o bRecvBuffer
 o  0000 0A 04 42 33 00 0A 12 04 42 33 00 12 13 04 42 00 ..B3....B3....B.
 o  0010 00 01                                           ..
  parsing CM_IOCTL_GET_FEATURE_REQUEST results:
  Tag FEATURE_IFD_PIN_PROPERTIES is 0x4233000A
  Tag FEATURE_GET_TLV_PROPERTIES is 0x42330012
  Tag FEATURE_CCID_ESC_COMMAND is 0x42000001
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000130]
SCarControl
 i bSendBuffer
 i  NULL
 o bRecvLength 0x00000004 (4)
 o bRecvBuffer
 o  0000 00 00 07 00                                     ....
  parsing FEATURE_IFD_PIN_PROPERTIES results:
  wLcdLayout: 0 0
  bEntryValidationCondition: 7
  bTimeOut2: 0
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000334]
SCardDisconnect
 i hCard: 0x00015425
 i dwDisposition: SCARD_LEAVE_CARD (0x00000000)
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000362]
SCardGetStatusChange
 i hContext: 0x0103E68C
 i dwTimeout: 0x00000000 (0)
 i cReaders: 1
 i szReader: Gemalto GemPC Twin 00 00
 i  dwCurrentState: SCARD_STATE_CHANGED, SCARD_STATE_PRESENT (0x00000022)
 i  dwEventState: SCARD_STATE_CHANGED, SCARD_STATE_PRESENT (0x00000022)
 i  Atr length: 0x00000017 (23)
 i  Atr: 3B 9F 95 81 31 FE 9F 00 65 46 53 05 30 06 71 DF 00 00 00 81 61 0F D9
 o szReader: Gemalto GemPC Twin 00 00
 o  dwCurrentState: SCARD_STATE_CHANGED, SCARD_STATE_PRESENT (0x00000022)
 o  dwEventState: SCARD_STATE_PRESENT (0x00000020)
 o  Atr length: 0x00000017 (23)
 o  Atr: 3B 9F 95 81 31 FE 9F 00 65 46 53 05 30 06 71 DF 00 00 00 81 61 0F D9
 => Command timeout. (SCARD_E_TIMEOUT [0x8010000A])  [0.000000352]
SCardGetStatusChange
 i hContext: 0x0103E68C
 i dwTimeout: 0x00000000 (0)
 i cReaders: 1
 i szReader: Gemalto GemPC Twin 00 00
 i  dwCurrentState: SCARD_STATE_PRESENT (0x00000020)
 i  dwEventState: SCARD_STATE_PRESENT (0x00000020)
 i  Atr length: 0x00000017 (23)
 i  Atr: 3B 9F 95 81 31 FE 9F 00 65 46 53 05 30 06 71 DF 00 00 00 81 61 0F D9
 o szReader: Gemalto GemPC Twin 00 00
 o  dwCurrentState: SCARD_STATE_PRESENT (0x00000020)
 o  dwEventState: SCARD_STATE_PRESENT (0x00000020)
 o  Atr length: 0x00000017 (23)
 o  Atr: 3B 9F 95 81 31 FE 9F 00 65 46 53 05 30 06 71 DF 00 00 00 81 61 0F D9
 => Command timeout. (SCARD_E_TIMEOUT [0x8010000A])  [0.000000303]
SCardGetStatusChange
 i hContext: 0x0103E68C
 i dwTimeout: 0x00000000 (0)
 i cReaders: 1
 i szReader: Gemalto GemPC Twin 00 00
 i  dwCurrentState: SCARD_STATE_PRESENT (0x00000020)
 i  dwEventState: SCARD_STATE_PRESENT (0x00000020)
 i  Atr length: 0x00000017 (23)
 i  Atr: 3B 9F 95 81 31 FE 9F 00 65 46 53 05 30 06 71 DF 00 00 00 81 61 0F D9
 o szReader: Gemalto GemPC Twin 00 00
 o  dwCurrentState: SCARD_STATE_PRESENT (0x00000020)
 o  dwEventState: SCARD_STATE_PRESENT (0x00000020)
 o  Atr length: 0x00000017 (23)
 o  Atr: 3B 9F 95 81 31 FE 9F 00 65 46 53 05 30 06 71 DF 00 00 00 81 61 0F D9
 => Command timeout. (SCARD_E_TIMEOUT [0x8010000A])  [0.000000215]
SCardConnect
 i hContext: 0x0103E68C
 i szReader Gemalto GemPC Twin 00 00
 i dwShareMode: SCARD_SHARE_SHARED (0x00000002)
 i dwPreferredProtocols: 0x00000003 (T=0, T=1)
 i phCard 0x0243EA80 (38005376)
 i pdwActiveProtocol 0x7FFEE90B2420 (140732808242208)
 o phCard 0x000104C4 (66756)
 o dwActiveProtocol: T=1 (0x00000002)
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000142]
SCardBeginTransaction
 i hCard: 0x000104C4
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000070]
SCardEndTransaction
 i hCard: 0x000104C4
 i dwDisposition: SCARD_LEAVE_CARD (0x00000000)
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000002802]
SCardDisconnect
 i hCard: 0x000104C4
 i dwDisposition: SCARD_RESET_CARD (0x00000001)
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000058724]
SCardReleaseContext
 i hContext: 0x0103E68C
 => Command successful. (SCARD_S_SUCCESS [0x00000000])  [0.000000204]

Results sorted by total execution time
total time: 0.304753 sec
0.219919 sec (  1 calls) 72.16% SCardEstablishContext
0.059086 sec (  2 calls) 19.39% SCardDisconnect
0.020384 sec (  2 calls)  6.69% SCardConnect
0.002802 sec (  1 calls)  0.92% SCardEndTransaction
0.001054 sec (  4 calls)  0.35% SCardGetStatusChange
0.000464 sec (  2 calls)  0.15% SCardControl
0.000229 sec (  2 calls)  0.08% SCardListReaders
0.000204 sec (  1 calls)  0.07% SCardReleaseContext
0.000070 sec (  1 calls)  0.02% SCardBeginTransaction

Analysis

PC/SC commands are in blue
Input arguments are in green
Output arguments are in mangenta
Errors are in bold red
The last part of the log contains some statistics about: functions called and times consumed by each of them

Next steps

Some ideas for the future:

Parse the APDU

For now the APDUs are displayed as a buffer of bytes. It would be great to display the command name corresponding to an INS byte. For example "SELECT FILE" is easier to read than "A4".

Smart card activity live monitoring

I often run pcscd in debug mode to know if something is happening at the PC/SC layer. I then know if the application is doing a lot of smart card accesses and I will just wait or if the application is locked somewhere and I should kill/debug it.

The idea is to send the PC/SC API log stream to a "live monitor" able to display a status using colors for example. The GUI still has to be designed. Please propose ideas.

PC/SC calls correctness

With all the PC/SC API calls you can check your application is using the API correctly. For example you should have the same number of SCardEstablishContext() and SCardReleaseContext() calls.

Mac OS X support

Logs from pcscd are very difficult to read. See pcscd debug output on Mac OS X. A clear PCSC API spy tool would be a real plus.

I do plan to work on porting the spying layer but I don't know when I will work on it. You can work on it and provide patches and ideas.

Windows support?

I do not plan to work on a Windows port myself. At least not without a very big amount of money :-).

If you want to work on this please do. I may integrate your changes if they do not break GNU/Linux and Mac OS X supports.

[UPDATE] Petr Svenda wrote a PC/SC API spy for Windows: PC/SC APDU inspection and manipulation tool (APDUPlay)

Conclusion

I hope this API spy feature will work in the long term. It is already the 3rd iteration of API log.

The displayer program (pcsc-spy.py) is written in Python. It should be easy to extend and make it do some complex tasks.