CCID free software driver for Unix

CCID/ICCD readers #

Not all the CCID are supported at the same level. I greatly suggest you to use a reader found in the supported list.

You can also use one from the Should work list.

I do not recommand readers from the Unsupported or Disabled lists. You should avoid them.

All the readers are also included in a big matrix.

Reader selection

You can use an interactive reader selection tool at: Reader selection.

See Reader Selection: find the smart card reader you search for a presentation of the search tool.

Download #

Binary

I do not provide binary packages on this web site.

Look for a package called libccid (Debian, Ubuntu, etc.) or pcsc-lite-ccid (RedHat, Fedora, etc.) in your distribution package repository. See Supported Operating Systems.

Get released/stable source code versions

Go in the Download section. I provide .tar.bz2 archives ready to be built using:

tar xzvf ccid-*.tar.xz
cd ccid-*
meson setup builddir
cd builddir
meson compile
sudo meson install

The latest README is at README.md.

Get the current source code from git #

If you are a C-language developer (or you know what you are doing), you can also access the git development version. You may need to use the git version to support the latest added readers.

git clone https://salsa.debian.org/rousseau/CCID.git
cd CCID
meson setup builddir
cd builddir
meson compile

Dependencies

You will need to also install:

• flex
• libusb-1
• meson

Main CCID/ICCD features supported #

• Exchange levels
  • short APDU
  • extended APDU (with some limitations and lack of support from PC/SC)
  • TPDU
  • character
• card protocols
  • T=0
  • T=1
• Protocol Parameter Selection (PPS)
  • negotiation made by the driver if needed
  • highest card/reader communication speed selected
  • specific mode supported
• multi-slot readers
• composite CCID devices
• PC/SC v2 part 10 features:
  • GET_FEATURE_REQUEST
  • secure PIN verify (FEATURE_VERIFY_PIN_DIRECT)
  • modify PIN entry (FEATURE_MODIFY_PIN_DIRECT)
  • reader PIN properties (FEATURE_IFD_PIN_PROPERTIES)
  • Multifunctional Card Terminal reader direct (FEATURE_MCT_READER_DIRECT)
  • retrieve reader properties in TLV form (FEATURE_GET_TLV_PROPERTIES)
    • bMinPINSize and bMaxPINSize: How to know the PIN sizes supported by a pinpad reader?
    • bEntryValidationCondition
    • bPPDUSupport
    • sFirmwareID
    • bTimeOut2
    • wLcdMaxCharacters and wLcdMaxLines
    • wLcdLayout
    • dwMaxAPDUDataSize
    • wIdVendor and wIdProduct
  • send CCID escape commands (FEATURE_CCID_ESC_COMMAND)
• Data rates list
• Localize LCD display messages (Gemalto GemPC PIN PAD, Covadis Véga-Alpha)
• Extended APDU (for T=1 cards only and if your reader is in TPDU mode or extended APDU mode. For T=0 cards this is managed by the application itself.)
• SCardGetAttrib() attributes
• ICCD versions A and B
• USB selective suspend
• RAM consumption efficiency for embedded systems using --enable-embedded
• CCID descriptor statistics

CCID features not yet supported #

• Manage suspend/resume (for example in a laptop)
• Reader clock frequency change

Contact me if you want to see the support of the above not yet supported features and you have a budget.

Non CCID features that I do not plan to support

• read/write on memory cards

In fact I may implement one of these features if you have a budget.

How to get support #

If you have a problem and want to get support from me you shall include the following information:

Versions

• CCID driver version
• pcsc-lite version
• the output of the command "/usr/sbin/pcscd --version"

Platform

• Operating system or GNU/Linux distribution name and version
• Hardware details: Standard compatible PC, special board, Raspberry Pi, etc.
• Smart card middleware name and version
• Smart card reader manufacturer name and reader model name
• Smart card name

Log

Then you shall generate a complete log (do not truncate it).

• If you need to enter the smart card PIN to reproduce the problem then consider changing your PIN before generating the logs as the PIN value will be included in the logs.
• Kill any running pcscd process
• (re)start pcscd exactly as described below:

  sudo LIBCCID_ifdLogLevel=0x000F pcscd --foreground --debug --apdu --color | tee -i log.txt

• Stop pcscd (using Control-C) after the problem occurred and send me the generated log.txt file

gdb backtrace

If you experience a crash of pcscd it is useful for me to have a backtrace.

$ gdb pcscd
(gdb) set args --foreground --debug --apdu
(gdb) run
wait for the crash to happen
(gdb) backtrace

Then copy/paste the complete output in your bug report.

Mailing list #

If you have general questions or bug reports you should use the Pcsclite-muscle mailing list.

First search the mailing list archives. Maybe your problem has already been reported and solved. If you have not found a solution then subscribe to the Pcsclite-muscle mailing list and send your request to pcsclite-muscle@lists.infradead.org..

Check reader's compliance to CCID specification #

To know if a smart card reader is CCID compliant and should be supported by this driver but is not listed below

Just get the source code of this driver, install the build dependencies (see Build-Depends: for Debian systems) and do:

tar xjvf ccid-*.tar.xz
cd ccid-*
meson setup builddir
cd builddir
meson compile
sudo ./src/parse

or if you do not want to compile the program yourself you can use:

curl https://ccid.apdu.fr/files/parse.sh | bash - 

and send me (ludovic.rousseau@free.fr) the generated output.bin file.

If your reader is CCID compliant and you would like to add it to the list of readers I would also need:

• The URL of a web page describing the reader. Typically the web page of the reader description on the manufacturer web site.
• A picture of the reader. In general a picture is already available on the manufacturer web page described above.

Authors #

The main author is Ludovic Rousseau <ludovic.rousseau@free.fr>.

I reused source code from other free software projects whose authors are:

• Carlos Prados for the PPS and ATR parsing code (taken from his towitoto driver) in towitoko/ directory.
• Olaf Kirch for the T=1 TPDU code (from the OpenCT package) in openct/ directory. I (Ludovic Rousseau) greatly improved this code.

Licence #

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

The complete licence is available at GNU Lesser General Public License, version 2.1

Supported Operating Systems #

GNU/Linux

Any GNU/Linux distribution.

MacOS #

Apple includes my CCID driver (version 1.3.8, released in June 2008) since Leopard 10.5.6.

See the evolutions of the CCID driver in Lion (10.7), Mountain Lion (10.8), Mavericks (10.9), Yosemite (10.10), El Capitan (10.11), Sierra (10.12), High Sierra (10.13), Mojave (10.14), Catalina (10.15), Big Sur (11.0), Monterey (12.0), Ventura (13.0).

Mac OS X Snow Leopard (10.6) and later are supported without patches.

If you need to build a custom version of my driver for macOS you can contact me.

FreeBSD

The driver is available in the freshport.

NetBSD (pkgsrc)

The driver is available in pkgsrc as security/ccid.

Other operating systems

It may or may not work.

Available binaries #

I do maintain the package libccid.