Saturday, April 12, 2014

CCID descriptor statistics: dwMechanical

Article from the serie "CCID descriptor statistics"

The dwMechanical field is a number value from the CCID USB descriptor:
The value is a bitwise OR operation performed on the following values:
• 00000000h No special characteristics
• 00000001h Card accept mechanism
• 00000002h Card ejection mechanism
• 00000004h Card capture mechanism
• 00000008h Card lock/unlock mechanism
A footnote in the specification also indicates:
These mechanisms of the dwMechanical parameter have been included for completeness; however, these functions of motorized CCIDs are not covered by this release of the specification. A future release may attempt to standardize the interface to these mechanical functions.

dwMechanical#%
0x0000000024696.85 %
0x0000000172.76 %
0x0300000010.39 %


The normal value should be 0x00000000: "No special characteristics" since this field is not covered by the CCID specification.

1 reader is using 0x03000000 (that should be 0x00000003)
  • MYSMART MySMART PAD V2.0

7 readers are using 0x00000001 "Card accept mechanism"
  • FujitsuTechnologySolutions GmbH SmartCase KB SCR eSIG
  • Hewlett-Packard Company HP USB CCID Smartcard Keyboard
  • Identive Identive CLOUD 4500 F Dual Interface Reader
  • Identive Identive CLOUD 4510 F Contactless + SAM Reader
  • Identive Identive CLOUD 4700 F Dual Interface Reader
  • Identive Identive CLOUD 4710 F Contactless + SAM Reader
  • Lenovo Lenovo USB Smartcard Keyboard
  • SCM Microsystems Inc. SCL010 Contactless Reader
  • SCM Microsystems Inc. SCL01x Contactless Reader

CCID descriptor statistics: dwProtocols

Article from the serie "CCID descriptor statistics"

The dwProtocols field is a number value from the CCID USB descriptor:
RRRR –Upper Word- is RFU = 0000h
PPPP –Lower Word- Encodes the supported protocol types. A ‘1’ in a given bit position indicates support for the associated ISO protocol.
0001h = Protocol T=0
0002h = Protocol T=1
All other bits are reserved and must be set to zero. The field is intended to correspond to the PCSC specification definitions. See PCSC Part3. Table 3-1 Tag 0x0120.
Example: 00000003h indicates support for T = 0 and T = 1.

dwProtocols#%
0x0000 0x000320781.50 %
0x0000 0x00022710.63 %
0x0000 0x0001197.48 %
0x0000 0x030010.39 %


The value 0x0300 is bogus and is used by the reader:
  • MYSMART MySMART PAD V2.0

Some readers (7.48%) only supports the T=0 protocol. They are:
  • ATMEL AT91SC192192CT-USB ICCD reader
  • ATMEL AT98SC032CT-USB
  • ATMEL VaultIC420 Smart Object
  • ATMEL VaultIC440
  • ATMEL VaultIC460
  • BIFIT iBank2Key
  • Gemalto Hybrid Smartcard Reader
  • Gemalto SA .NET Dual
  • Gemalto Smart Enterprise Guardian Secure USB Device
  • Gemalto Smart Enterprise Guardian Secure USB Device
  • IID AT90S064 CCID READER
  • INSIDE Secure VaultIC 405 Smart Object
  • INSIDE Secure VaultIC 441 Smart Object
  • Inside Secure VaultIC 420 Smart Object
  • Inside Secure VaultIC 440 Smart Object
  • Inside Secure VaultIC 460 Smart Object
  • KEBTechnology KONA USB SmartCard
  • Kingtrust Multi-Reader
  • RSA RSA SecurID (R) Authenticator
  • SchlumbergerSema SchlumbergerSema Cyberflex Access
  • SecuTech SecuTech Token
  • Softforum Co., Ltd XecureHSM
  • TianYu CCID Key TianYu CCID SmartKey

Some readers (10.63%) only supports T=1 protocol. They are:
  • ACS ACR122U PICC Interface
  • ASK-RFID CPL108
  • Aktiv Co., ProgramPark Rutoken Magistra
  • Aktiv PINPad Ex
  • Aktiv PINPad In
  • Aktiv Rutoken ECP
  • Aktiv Rutoken lite
  • BIFIT USB-Token iBank2key
  • CCB eSafeLD
  • Crypto Stick Crypto Stick v1.4
  • Feitian ePass2003
  • Free Software Initiative of Japan Gnuk
  • Gemalto PDT
  • German Privacy Foundation Crypto Stick v1.2
  • Giesecke & Devrient GmbH Star Sign Card Token 350 (ICCD)
  • Giesecke & Devrient GmbH Star Sign Card Token 550 (ICCD)
  • GoldKey Security PIV Token
  • IIT E.Key Almaz-1C
  • Macally NFC CCID eNetPad
  • OCS ID-One Cosmo Card USB Smart Chip Device
  • Philips Semiconductors JCOP41V221
  • Philips Semiconductors SmartMX Sample
  • REINER SCT cyberJack RFID basis
  • Watchdata W5181
  • Yubico Yubikey NEO CCID
  • Yubico Yubikey NEO OTP+CCID
  • id3 Semiconductors CL1356A_HID
  • id3 Semiconductors CL1356T5
  • id3 Semiconductors CL1356T
  • ubisys 13.56MHz RFID (CCID)
Many of the readers with support of only 1 protocol are tokens with an integrated smart card. Since you can't change the card only the protocol used by the card is declared. So it is not really a limitation of the reader.

CCID descriptor statistics: dwSynchProtocols

Article from the serie "CCID descriptor statistics"

The dwSynchProtocols field is a number value from the CCID USB descriptor:
• RRRR-UpperWord- is RFU=0000h
• PPPP-Lower Word- encodes thes upported protocol types. A ‘1’ in a given bit position indicates support for the associated protocol.
0001h indicates support for the 2-wire protocol
0002h indicates support for the 3-wire protocol
0004h indicates support for the I2C protocol
All other values are outside of this specification, and must be handled by vendor-supplied drivers.

A footnote in the specification also indicates:
This release of the specification does not support devices with the 2-wire, 3-wire, and I2C protocol so PPPP = 0000h. This field is intended to be forward compatible with the PCSC specification.
I imagine this value is for synchronous cards only.

dwSynchProtocols#%
0x0000000021885.83 %
0x000000073513.78 %
0x0000000110.39 %


The normal value should be PPPP = 0000h. Most of the readers provide this value.

The reader with value 0x00000001 is:
  • C3PO TLTC2USB

The readers with value 0x00000007 are:
  • Akasa AK-CR-03
  • Alcor Micro AU9520
  • Alcor Micro AU9522
  • Alcor Micro AU9540
  • Alcor Micro SCR001
  • C3PO KBR36
  • C3PO LTC31 v2
  • C3PO LTC32
  • C3PO LTC36
  • Cherry GmbH SmartBoard XX44
  • Cherry GmbH SmartTerminal ST-1275
  • Cherry GmbH SmartTerminal XX44
  • Feitian bR301
  • Fujitsu Siemens Computers SmartCard Keyboard USB 2A
  • Fujitsu Siemens Computers SmartCard USB 2A
  • GIS Ltd SmartMouse USB
  • Giesecke & Devrient GmbH StarSign Crypto USB Token
  • KOBIL KAAN Advanced
  • KOBIL KAAN Base
  • OMNIKEY 6321 CLi USB
  • OMNIKEY AG CardMan 3021
  • OMNIKEY AG CardMan 3121
  • OMNIKEY AG CardMan 3621
  • OMNIKEY AG CardMan 3821
  • OMNIKEY AG CardMan 5121
  • OMNIKEY AG CardMan 5125
  • OMNIKEY AG CardMan 6121
  • OMNIKEY AG Smart Card Reader
  • OMNIKEY CardMan 1021
  • OMNIKEY CardMan 4321
  • OMNIKEY CardMan 5321
  • Precise Biometrics Sense MC
  • Sitecom Sitecom USB simcard reader MD-010
  • THRC Smart Card Reader
  • VASCO DIGIPASS KEY 101
  • VASCO DP905v1.1
  • Watchdata W5181
  • XIRING Teo

Monday, March 24, 2014

Level 1 smart card support on GNU/Linux

As I did for Mac OS X in "Level 1 smart card support on Mac OS X" I propose to present some 1st step actions to check your smart card stack is working correctly on a GNU/Linux system.

Operating System choice

Unix is available in a lot of different versions. I will only consider a GNU/Linux system here and also only a Debian GNU/Linux distribution.

If you use Ubuntu (or another Debian derivative distribution) then the same tools are available.
If you use another GNU/Linux distribution maybe the same software are already packaged and available.

Command line tools

All the commands I will describe are command line tools. You need to start a "terminal" application also called terminal emulator to enter the commands.

I will not describe here how to start a "terminal" application. It depends too much on the graphical environment (or desktop) you are using.

pcsc_scan

pcsc_scan is a command line tool. You need to install the pcsc-tools Debian package (or recompile pcsc_scan yourself from the upstream pcsc-tools).

Normal execution

In green the commands entered by the user.

$ pcsc_scan
PC/SC device scanner
V 1.4.22 (c) 2001-2011, Ludovic Rousseau <ludovic.rousseau@free.fr>
Compiled with PC/SC lite version: 1.8.8
Using reader plug'n play mechanism
Scanning present readers...
0: Gemalto PC Twin Reader (70D7E2EE) 00 00

Mon Mar 24 15:31:17 2014
Reader 0: Gemalto PC Twin Reader (70D7E2EE) 00 00
  Card state: Card inserted, 
  ATR: 3B 7E 13 00 00 00 6A 11 63 54 05 48 05 02 C6 01 22 90 00
ATR: 3B 7E 13 00 00 00 6A 11 63 54 05 48 05 02 C6 01 22 90 00
+ TS = 3B --> Direct Convention
+ T0 = 7E, Y(1): 0111, K: 14 (historical bytes)
  TA(1) = 13 --> Fi=372, Di=4, 93 cycles/ETU
    43010 bits/s at 4 MHz, fMax for Fi = 5 MHz => 53763 bits/s
  TB(1) = 00 --> VPP is not electrically connected
  TC(1) = 00 --> Extra guard time: 0
+ Historical bytes: 00 6A 11 63 54 05 48 05 02 C6 01 22 90 00
  Category indicator byte: 00 (compact TLV data object)
    Tag: 6, len: A (pre-issuing data)
      Data: 11 63 54 05 48 05 02 C6 01
    Mandatory status indicator (3 last bytes)
      LCS (life card cycle): 22 (Proprietary)
      SW: 9000 (Normal processing.)

Possibly identified card (using /home/lroussea/.cache/smartcard_list.txt):
3B 7E 13 00 00 00 6A 11 63 54 05 48 05 02 C6 01 22 90 00
3B 7E 13 00 00 00 6A 11 63 54 05 48 .. .. .. 01 22 90 00
 Sagem Windows for smart cards

Important information your should note:
  • the reader name: "Gemalto PC Twin Reader (70D7E2EE) 00 00"
  • the card ATR: 3B 7E 13 00 00 00 6A 11 63 54 05 48 05 02 C6 01 22 90 00
  • the card description (if available): Sagem Windows for smart cards
Of course in your card the information will be different. Unless you really have a "Windows for smart card" card .

Compared to Apple pcsctest we have some differences:
  • use of colors for important information
  • no need to select a reader
  • no debug messages
  • smart card identification
  • ATR parsing

No reader connected


$ pcsc_scan
PC/SC device scanner
V 1.4.22 (c) 2001-2011, Ludovic Rousseau <ludovic.rousseau@free.fr>
Compiled with PC/SC lite version: 1.8.8
Using reader plug'n play mechanism
Scanning present readers...
Waiting for the first reader...

You do not get an error (as on Mac OS X) but the program is waiting for you to connect a smart card reader.

No smart card inserted


$ pcsc_scan
PC/SC device scanner
V 1.4.22 (c) 2001-2011, Ludovic Rousseau <ludovic.rousseau@free.fr>
Compiled with PC/SC lite version: 1.8.8
Using reader plug'n play mechanism
Scanning present readers...
0: Gemalto PC Twin Reader (70D7E2EE) 00 00

Mon Mar 24 15:36:01 2014
Reader 0: Gemalto PC Twin Reader (70D7E2EE) 00 00
  Card state: Card removed, 

The program is waiting for you to insert a smart card.

scriptor

Once you have checked your reader and your smart card are available using pcsc_scan, you can try to communicate with the card and send some APDUs.

scriptor is a command line tool also part of pcsc-tools.

$ scriptor 
No reader given: using Gemalto PC Twin Reader (70D7E2EE) 00 00
Using T=0 protocol
Reading commands from STDIN
00 A4 00 02 3F 00
> 00 A4 00 02 3F 00
< 6D 00 : Instruction code not supported or invalid.

Here we are sending the APDU "00 A4 00 02 3F 00" which is a SELECT command for the file "3F 00" i.e. the Master File.
The result of the command is "6D 00" here. This is an error code but that is not really important for our test. We just wanted to test we can communicate with the card.

gscriptor

If you really can't use command line tools you can try gscriptor. It is a graphical application also part of pcsc-tools.


Conclusion

These first steps are easy to excecute on Debian GNU/Linux, and should also be easy on another GNU/Linux system.

If you do not have the expected results then you need to contact your level 2 support team.

Sunday, March 23, 2014

New version of libccid: 1.4.16

I just released a version 1.4.16 of libccid the free software CCID class smart card reader driver.

Changes:
1.4.16 - 23 March 2014, Ludovic Rousseau
  • Add support of
    • Crypto Stick Crypto Stick v1.4
    • Hewlett Packard USB Smartcard CCID Keyboard
    • IID AT90S064 CCID READER
    • INSIDE Secure VaultIC 405 Smart Object
    • INSIDE Secure VaultIC 441 Smart Object
    • Microchip SEC1110
    • Microchip SEC1210
    • Watchdata W5181
  • Add support of DRIVER_OPTION_DISABLE_PIN_RETRIES
    The Gemalto pinpad reader sends a VERIFY command with no PIN value in order to retreive the remaining retries from the card. Some cards (like the OpenPGP card) do not support this.
    It is now possible to disable this behavior from the Gemalto Pinpad and Covadis VĂ©ga Alpha.
  • Add support of WTX received before SW during Secure Pin Entry Verify
    The Swiss health care card sends a WTX request before returning the SW code. If the reader is in TPDU and the card is in T=1 the driver must manage the request itself.

Thursday, March 20, 2014

Level 1 smart card support on Mac OS X

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.

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.

Tuesday, March 18, 2014

Differences between Apple pcsc-lite and the "official" pcsc-lite

In "Evolution of Apple pcsc-lite (from Jaguar to Mavericks)" I described the evolution of Apple version of pcsc-lite. During the same time the "official" pcsc-lite also evolved.

Terminology

  • Apple pcsc-lite
    The version of pcsc-lite provided by Apple in Mac OS X since Jaguar in 2002. It is provided as a framework and is available at /System/Library/Frameworks/PCSC.framework/.
  • "official" pcsc-lite
    The version of pcsc-lite available at http://pcsclite.alioth.debian.org/pcsclite.html for the source code and as a binary package for your preferred GNU/Linux distribution.

Features present only in Apple pcsc-lite

  • Integration with securityd
    pcscd is started by securityd when needed. From securityd(1) man page: securityd -- Security context daemon for Authorization and cryptographic operations
  • hotplug using IOKit
    a file hotplug_macosx.c is present in the "official" pcsc-lite but has not evolved since Apple forked the code in 2002. Apple made major changes to the hotplug system.
  • Suspend/resume of the computer
    in the "official" pcsc-lite no special code is used and suspend/resume works. Apple has an explicit suspend and resume of the smart card readers.
  • Rosetta support
    This may be removed in a future version since PowerPC is no more supported by Mac OS X.

Features present only in "official" pcsc-lite

Features present in both projects

Support of 32 and 64-bits applications at the same time

Both projects support the use of a 32-bits application using a 64-bits pcscd. But since the protocol between the client and server has diverged in the two projects they use different (but similar) solutions.

For Mac OS X Apple added this support for the migration from 32 to 64-bits Intel CPU.
For GNU/Linux I added this support to be able to use the same 64-bits pcscd daemon from a 64-bits client application and also from a 32-bits client application in a chroot. Now that Debian multiarch is deploying it is even easier to mix 32 and 64-bits Intel applications on the same system.

Bugs (still) present in Apple pcsc-lite


I discovered (a lot of?) bugs in the smart card components provided by Apple. Some have been fixed and some are still present:
  • Do not support USB devices with more than 1 CCID interface (bug #10469006)
  • Do not support extended APDU longer than 1958 bytes (bug #9983001 and #7334726)
  • Do not support more than 16 PCSC contexts per application (bug #10038432)
  • reader.h header file is not provided in the PCSC Framework (bug #7101554)
  • pcscd does not support TAG_IFD_THREAD_SAFE (bug #6584566)
  • pcscd crashes when the smart card reader is removed when in communication (bug #6114944)
  • PC/SC never returns the warm ATR of a dual-ATR card (bug #5964019)

Apple has a strange way to manage bugs.
  • If a bug report is a duplicate of an already known bug then the duplicate bug report is closed.
  • Even if a bug is not a duplicate the bug is sometimes closed with:
    Thank you for filing this bug report.

    We are closing this bug since our engineers are aware of the issue and will continue to track it.

So I have many bugs that are closed in the bug report tool https://bugreport.apple.com/ but that in fact still not fixed.

Bugs present in "official" pcsc-lite

None known

How to merge the two projects

The question now is what to do with these two projects that share a lot of history and common code?

Include Apple code inside the "official" pcsc-lite

This is technically possible. The source code is available and Mac OS X specific parts should not have an impact on pcsc-lite for the other systems (GNU/Linux).

It is also legally possible. The Apple license "Apple Public Source License Version 1.2" should be compatible with the BSD-like license used by the "official" pcsc-lite. But the APSL 1.2 license is not a Free Software license for the Free Software Foundation. See "The Problems with older versions of the Apple Public Source License (APSL)".

The most important issue is that Apple would not use this code and would continue to "maintain" its own version of pcsc-lite at the SmartCard Services project. So bugs fixed in this merge would not be included in the next version of Mac OS X.

Patch Apple pcsc-lite

The most effective way is to modify the SmartCard Services project to fix bugs and add features. This code may be included in the next version of Mac OS X. I fixed bugs in this code during the year 2009 and the fixes have been released in Snow Leopard and Lion versions of Mac OS X.

Conclusion

Apple version of pcsc-lite has evolved only to support new features introduced by Mac OS X (Rosetta and then 32 and 64-bits Intel codes).
Some very blocking bugs have been fixed in the early years of Apple pcsc-lite. It looks like Apple is now happy with the state of its pcsc-lite and will not invest engineering time in it.

If you are blocked by a bug or a missing feature in Apple pcsc-lite you will have to fix it yourself or recruit someone to fix it for you. You can contact me at ludovic.rousseau@free.fr.