This Time Self-Hosted
dark mode light mode Search

Additional notes about the smartcard components’ diagram

Yesterday I wrote about smartcard software for Linux providing a complex UML diagram of various components involved in accessing the cards themselves. While I was quite satisfied with the results, and I feel flattered by Alon’s appreciation of it, I’d like to write a few notes about it, since it turns out it was far from being complete.

First of all, I didn’t make it clear that not all cards and tokens allows for the same stack to be used: for instance even though the original scdaemon component of GnuPG allows using both PC/SC and CT-API to interface to the readers, it only works with cards that expose the OpenPGP application (on the card itself); this was a by-design omission, mostly because otherwise the diagram would have felt pretty much unreadable.

One particularly nasty mistake I made related to the presence of OpenSSL in that diagram; I knew that older OpenSSL versions (0.9.x) didn’t have support for PKCS#11 at all, but somehow I assumed that they added support for that on OpenSSL 1.0; turns out I was wrong, and even with the latest version you’re required to use an external engine – a plugin – that makes the PKCS#11 API accessible to OpenSSL itself, and thus the software relying on it. This plugin is as usual developed by the OpenSC project.

Interestingly enough, NSS (used by Firefox, Chromium and Evolution among others) supports PKCS#11 natively, and actually seem to use that very interface to access its internal storage. Somehow, even though it has its own share of complexity problems, it makes me feel much more confident. Unfortunately I haven’t been able to make it work with OpenCryptoki, nor I have found how to properly make use of the OpenSC-based devices to store private and public keys accessible to the browser. Ah, NSS seem also to be the only component that allows access to multiple PKCS#11 providers at once.

Also, I found myself considering the diagram confusing, as software providing similar functionality was present at different heights in the image, with interfaces consumed and provided being connected on any side of the components’ representation. I have thus decided to clean it up, giving more sense to the vertical placement of the various components, from top to bottom: hardware devices, emulators, hardware access, access mediators, API providers, abstractions, libraries and – finally – user applications.

I also decided to change the colour of three interface connections: the one between applications and NSS, the new one between OpenSSL and its engines, and the one between OpenCryptoki and the ICA library (which now has an interface with a “S390” hardware device: I don’t know the architecture enough to understand what it accesses, and IBM documentation leaves a lot to be desired, but it seems to be something limited to their systems). These three are in-process interfaces (like PKCS#11 and, theoretically, PCS/SC and CT-API, more to that in a moment), while SCD, agent interfaces, Trousers and and TPM are out-of-process interfaces (requiring inter-process communication, or communication between the userland process and the kernel services) — I don’t know ICA to tell whether it uses in or out of process communication.

Unfortunately to give the proper details of in-process versus out of process communication, I would need to split up a number of those components in multiple ones, as all three of pcsc-lite and OpenCT use multiple interfaces: an in-process interface to provide the public interface to the application, and an out-of-process interface to access the underlying abstraction; the main difference between the two is where this happens (OpenCT implements all the drivers as standalone processes, and the in-process library accesses those; pcsc-lite instead has a single process that loads multiple driver plugins).

In the new diagram, I have detailed more the interaction between GnuPG, OpenSSH and their agents, simply because that situation is quite complex and even I strained to get it right: GnuPG never speaks directly with either of the SCD implementations: there is always another process, gpg-agent that interfaces them with GnuPG proper, and it is this agent to provide support for OpenSSH as well. The distinction is fundamental to show off that it is quite possible to have the PKCS#11-compatible SCD implementation provide keys for OpenSSH, even though the original ssh-agent (as well as ssh itself) have support for the PKCS#11 interface. And also, the original scdaemon implementation can, in very few cases, speak directly with the USB device via CCID.

I have decided to extend the diagram to incorporate the TPM engine for OpenSSL while at it, making it much more explicit that there is a plugin interface between OpenSSL and PKCS#11. This engine access trousers directly, without going trhough OpenCryptoki.

Speaking about OpenCryptoki, of which I’ll try to write about tomorrow, I decided to expose its internals a bit more than I have done for the rest of the packages for now. Mostly because it’ll make it much easier tomorrow to explain how it works, if I split it out this way. In particular, though, I’d like to note that it is the only component that does not expose a bridge between a daemon process and the applications using it; instead it uses an external daemon to regulate access to the devices, and then users in-process plugin-based communication to abstract access to different source of secure key storage.

OpenCT could use a similar split up, but since I’m not going to write about it for now, I don’t think I’ll work more on this. At any rate, I’m very satisfied with the new diagram. It has more details, and is thus more complex, but it also makes it possible to follow more tightly the interaction between various software, and why it is always so difficult to set up smartcard-based authentication (and hey, I still haven’t added PAM to the mix!)

Comments 7
  1. Thanks for the great effort in putting together such an inclusive architecture diagram of a snapshot of the hardware crypto stack.I work with smart-cards/tokens for a living and have rarely seen a good diagram showing the very deep stack that making smart cards work with applications is.I routinely work with some devices on a Gentoo development box at work and can perform tests to make sure that the Gentoo stack works well. I’ve found that some devices are quite finicky and should or should not use the manufacturer’s driver. The alternative to not using the manufacturer’s driver being editing the CCID driver’s plist file to recognize the device as something it supports.

  2. Again, great work!I think one more dimension that should be added… exclusive and shared applications.For example, as far as I remember, if you use gnupg with CCID, you cannot use the reader for any other application at the same time.Or OpenSC that requires locking the reader for single application to not expose key to other applications (This can be fixed but none trivial).So unlike plain design of PKCS#11 or Windows crypto, we have fundamental problem in POSIX OSS. No decent frameworks and drivers to make it actually work in a secure real user environment.I know of only one proprietary (Athena) PKCS#11 driver that actually deliver the proper functionality in Linux. Although I helped them, I dislike using closed source.For OpenSSL – there is a major issue with the engine interface. The engine interface is a very low level interface to OpenSSL, it only provides access to low level crypto operations. Modern applications need to load X.509 certificates and other objects into the application, while the OpenSSL engine interface does not have any integration with higher level interfaces such as certificate store or chain. So there cannot be a plain engine implementation into OpenSSL which can provide decent external crypto store without modifying the application. This is why pkcs11-helper is not packaged as external engine, but provide internal engine implementation for OpenSSL enabled applications.For NSS – yes, it is the first library that actually allowed full integration with PKCS#11, including multiple provides, it also allows FIPS complaint. However, NSS is not a library, it is a framework, it requires configuration and stores, which makes it very hard to use. Also, as far as PKCS#11 is concerned, it forces providers to implement a very large portion of the specification, while most smartcard PKCS#11 implementation implements only fraction of the specification. As a result most PKCS#11 providers do not work with NSS. NSS also has some long opened bugs concerting the user experience [1][2].So the problem with OpenSSL and NSS lead me to implement the pkcs11-helper library which may be used in order to abstract the application interaction with PKCS#11 implementations. As NSS provides PKCS#11 implementation to its functionality it may be used as a provider.[1]…[2] https://bugzilla.mozilla.or

  3. ICA notes.I worked with ICA on both AIX and Windows. I always preferred to use the PKCS#11->ICA bridge that IBM provides.I was extremely satisfied with IBM’s PKCS#11 implementation. The problem is that it was provided only for AIX and Windows.In Windows it installed a device drivers and two applets on the IBM cryptographic processor. All communications were in-process.Application->PKCS#11->ICA->Driver->Device->Applet->Crypto servicesBut as far as heard IBM stopped manifacturing these devices to Windows, left with PCI implementation for System P and System Z (AIX, Z/OS).At Z/OS as far as I know application in enabled mode can access the cryptographic CPU using special instruction set. The co-processor is activated as a slave. But I am not sure. Or you mean the usage of the crypto processor in Z/Linux environment… never seen this.

  4. Indeed, a nice diagram. Not really relevant for the accuracy of the diagram, but just FYI:The lack of “organization” in Linux/OSS POSIX crypto software stack was discussed at FOSDEM. Have a look at and specifically While I’m not 100% convinced that p11-kit is the right thing in the long perspective for end-user applications, it does provide interesting technical plumbing capabilities to play with in the short term, as currently the only common nominator seems to be PKCS#11.Nor am I convinced that anything except PC/SC survives long enough for smart card access, if you mention CCID, you should only mention pcsc-lite and PC/SC (CT-API? The manuals of software capable of dealing with CT-API tend to be in German only) OpenCT is not really maintained nor is it easily usable with all devices or interfaces, to my knowledge the bridges for ifdhandler and ct-api are there only for “because you can” not because they should be used by default. I don’t know a distro that would try to provide pcsc-lite+openct+libccid in a reasonable combined package. OpenSSL engine interface is probably not really relevant here either (only if you want to run your mod_ssl against an accelerator card), the number of software plugins/libraries/api-s is virtually endless. For example OpenSC could load a .so implementing a card driver (probably, that interface is deprecated for good) but that does not mean would actually make much sense or should be plotted to the diagram.I might be harsh, but some things should die so that others could benefit. Like for GnuPG to try to be relevant for a wider audience, insisting on a) directly accessing a smart card reader device or b) using an OpenPGP card applet and building the host side card interface against it s just not reasonable. Last time I checked it did not work for me exactly for these reasons (I wanted to use my reader and card with other applications as well)So to get the userland to a state similar on Windows (with CryptoAPI and/or minidrivers) or OS X (Keychain/CDSA) there are two options in Linux world: “patch everything to use a single library and declare that the winner” (Fedora crypto consolidation and NSS), provide somsething like QCA (Qt Cryptography Architecture) and a competing one for Gnome (what Ubuntu would fork, of course) or actually raise the awareness of the choices and consequences (walled gardens and bad interoperability) and leave room for choice, which has always been both the strength and weakness of Linux world 😉 PKCS#11 is thus the best we have at the moment.Anyway, a nice diagram, will add a link to it in OpenSC wiki.

  5. As above, thank you for all you hard work in this area. I was pleasantly surprised to find you working on this not long after I ordered my OpenPGP cards a year-or-so ago. It’s mind boggling how complex an ecosystem this is.I first started out using US government Common Access Cards (CAC). They use X.509 keys but the protocol is somewhat non-standard and requires the app-crypt/coolkey package. You might consider adding that to your diagram, if you plan to maintain it. dev-libs/libassuan is another one, used in the GnuPG paradigm.Speaking of which, it seems the OpenPGP Card is really a whole other bag of worms compared to most of the commercially supported smartcards. v1.x didn’t support X.509 but apparently v2 does via an undocumented quirk I found burred in the mailing lists:… I’ve yet to experiment with that functionality, but I’m wondering if it’s PKCS#15 compatible– speaking of standards.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.