Creating applications with smart card support

Frank Morgner edited this page Aug 27, 2018 · 6 revisions

Creating applications with smart card support

If you, as a developer, want to write software that can work with cryptographic smart cards, you need to orientate in the maze of different APIs.

Platform crypto interfaces


PKCS#11 is the only universal, cross-platform cryptography interface, defined by RSA Laboratories. OpenSC and almost all hardware cryptography device vendors (smart cards, HSM-s) provide one with their hardware. PKCS#11 is the most universal and flexible API, but it also has a major drawback: applications need to be manually configured to use a specific PKCS#11 module. Choose PKCS#11 as your primary interface if you are writing a specialized crypto application or universality and portability are very important to you. PKCS#11 only provides cryptographic primitives, it does not provide X509 and trust management features. OpenSC provides a PKCS#11 module which should be usable by any software claiming PKCS#11 support.

Tools and libraries

These tools and libraries help in talking to PKCS#11 modules or integrate PKCS#11 with other frameworks.

  • C
    • libp11 is a wrapper library for PKCS#11 modules which includes an OpenSSL engine for using PKCS#11 tokens
    • pkcs11-helper Library that simplifies the interaction with PKCS#11 providers for end-user applications using a simple API and optional OpenSSL engine
    • gp11 is a GObject based wrapper for PKCS#11, distributed with gnome-keyring.
    • PaKChoiS aims to provide a thin wrapper over the PKCS#11 interface.
    • p11-kit eases working with multiple PKCS#11 modules and includes support for PKCS#11 URI scheme.
  • Python
    • PyKCS11 is a python wrapper (SWIG) for PKCS#11 modules.
  • Java

CryptoAPI (Windows)

Windows applications use CryptoAPI to do native SSL connections and to use the Windows certificate store. All applications using CryptoAPI (or CryptoAPI-NG) can transparently use all smart cards that provide a full CSP or a smart card BaseCSP module. Most card vendors provide one such driver. OpenSC has a rudimentary BaseCSP module (a MiniDriver), but it is still work in progress. Use CryptoAPI if you are writing a Windows-only application or if you want a well functioning and integrated experience for your users. CryptoAPI provides trust management (user has a centralized location to set the trust bits for various X509 certificates) in addition to basic cryptographic operations and windows API provides higher level functions that are CAPI enabled (TODO: OpenURL example/link)

CDSA/Keychain (Mac OS X)

Mac OS X implements CDSA as the cryptography API for the Mac platform (in theory it is a universal specification but in practice only implemented by Apple). OS X 10.4 and above implement Tokend, what is similar in nature to BaseCSP on Windows – it provides a plugin architecture to add support for smart cards into the system. Applications using CDSA can then transparently make use of smart cards. Applications usually use higher level API-s (like Keychain or SSL socket API-s) that internally make use of CDSA. Trust management is exposed centrally via Use Keychain API-s if writing a native application for Mac OS X or if you want to have a smooth “Mac style” user experience.

Java Cryptography Architecture (JCA)

SSL/TLS toolkit integration


OpenSSL has an easy way to integrate smart card support. libp11 has code to make using OpenSC PKCS#11 module with OpenSSL quite easy and includes example code for using SSL with client certificate authentication using a smart card too (FIXME: link). engine_pkcs11 project has an OpenSSL engine implementation so you can change any code using OpenSSL to move the crypto operation from your CPU to your smart card with only a few small changes. Wpa_supplicant is an example of an application using OpenSSL and this engine for smart card support.


NSS (Network Security Services) is used by Mozilla products (Firefox, Thunderbird) and many applications in Fedora, like mod_nss. NSS supports PKCS#11 for SSL.


QCA (Qt Cryptographic Architecture) adds cryptography support into Qt applications. QCA has PKCS#11 support since v2.0. See for more information.


GnuTLS includes native PKCS#11 smart card support using the PKCS#11 URI scheme..
See for more information.


cryptlib is a library by Peter Gutmann and claims support for SSL and PKCS#11 modules.

Low level smart card access

OpenSC is for cryptographic smart cards and the preferred method for accessing such cards is via one of the high level cryptographic API-s listed above, which hides the details of actual card reader access via one of the interfaces described below. As a general rule, don’t use the low level smart card API-s if the necessary functionality is implemented via a cryptographic API.


PC/SC is a standard from PC/SC Workgroup but the “reference implementation” is still Windows winscard.dll. Linux uses the open source pcsc-lite package. And Mac OS X uses a fork of pcsc-lite included in the SmartCardServices project.

Tools and libraries


CT-API is an API for accessing smart card readers that is mostly used in Germany. It is not suited for modern multi-user environments, is not portable and not always available. New projects should avoid using CT-API and use PC/SC instead.


OpenCT, like CT-API, is a Linux only API for accessing USB tokens (and smart card readers). Very few applications beside OpenSC can make use of OpenCT readers. New projects should try to avoid building against OpenCT and use PC/SC instead.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.