OpenSC Manual

The following people provided inspiration, moral support and/or valuable information during the development of OpenSC:

OpenSC did neither invent the wheel nor write all code from scratch. We could reuse some code from other projects mostly to interface with these projects. Thanks to the original authors:

libopensc is the basic library used by everything else. It offer basic functionality like talking to smart cards, but also advances functions like generating RSA keys on a smart card.

libopensc has several layers of functionality, each implemented by one or several drivers. The layers are:

PC/SC Lite is well known as smart card middleware. It interacts with drivers for the smart card readers on the bottom, and with smart card applications on the top. OpenSC can use PC/SC Lite via the pcsc reader module, but also supports a number of alternatives.

PC/SC is a standard with interfaces between applications, a resource manager and drivers for smart card readers. This standard is very popular on the Windows operating System. The documents are available from http://www.pcscworkgroup.com/ .

PC/SC Lite is an implementation of the PC/SC standard for Linux, Unix, Mac OS X and Windows by David Corcoran < corcoran@linuxnet.com > . The software is available with full source code and available for free. To download the software, please visit the website of the Movement for the use of smart cards in a Linux environment (M.U.S.C.L.E.) at http://www.linuxnet.com/ .

To install OpenSC with support for PC/SC Lite, please install PC/SC Lite first. Then configure OpenSC to use PC/SC Lite and specify the location where PC/SC Lite is installed like this:

                  $ cd opensc-<version>
                  $ ./configure --with-pcsclite=/path/to/pcsclite
                                                  
                

OpenCT is a new framework for accessing smart cards, card readers and card terminals. It was written from scratch, already includes all drivers, and is very lightweight. OpenCT is available for Linux, but if you want to use it on other Unix or BSD operating systems, please ask for help on the opensc-devel mailing list.

OpenCT is open source software. As such it is available with full source code for free. OpenCT is a software companion to OpenSC and the preferred way of accessing smart cards under Linux. OpenCT is available from the OpenSC website http://www.opensc.org/ and questions go to the < opensc-devel@opensc.org > mailing list.

To compile OpenSC with support for OpenCT, please install OpenCT first. Documentation on OpenCT is part of the source code, and also available online at http://www.opensc.org/files/doc/openct.html . Then configure OpenSC to use OpenCT and specify the location where OpenCT is installed like this:

                  $ cd opensc-<version>
                  $ ./configure --with-openct=/path/to/openct
                                                  
                

CT-API is a standard format for drivers for smart card readers. It was invented in the eighties for DOS applications and is maybe not very fit for todays multiuser multitasking applications. However CT-API is still quite popular, and many smart card readers have drivers in CT-API format even for Linux. It is recommended to use these drivers if the PC/SC Lite middleware described above.

But OpenSC can also use CT-API drivers directly. This is meant for debugging mostly and not recommended in a multi user or multi application environment.

OpenSC includes always support for drivers in CT-API format, you don't need to do anything special for compiling. See the opensc.conf configuration file on how to configure an CT-API driver with OpenSC.

Type "nmake -f makefile.mak" in the opensc\ dir to compile.

You need also perl and flex installed for the compile process to complete successfully.

No installation script has been provided, so you have to do this manually:

This adds extended functionality. E.g. the pkcs15-init tool, PKCS #11 hash mechanisms and more PKCS #11 signature mechanisms.

To add the OpenSSL code to the DLLs (so you won't need libeay32.dll anymore): statically compile OpenSSL and add gdi32.lib next to libeay32.lib in the 3 Makefile.mak files above.

At the moment only libopensc.dll, pkcs11-spy.dll opensc-pkcs11.dll, and most executables in the tools\ and tests\ dir have been ported. They are tested on Win98, WinNT, Win2000 and WinXP.

Netscape seems to show more information about the security module than Mozilla. Otherwise all stuff is untested.

Thread safety on Linux and Mac OS X: Netscape/Mozilla uses the CKF_OS_LOCKING_OK flag in C_Initialize(). The result is that the browser process doesn't end when closing the browser, so you have to kill the process yourself. (If the browser would do a C_Finalize, the sc_pkcs11_free_lock() would be called and there wouldn't be a problem.)

Therefore, we don't use the PTHREAD locking mechanisms, even if they are requested. This seems to work fine for Mozilla, BUT will cause problems for apps that use multiple threads to access this lib simultaneously.

If you do want to use OS threading, compile with -DPKCS11_THREAD_LOCKING On Windows, no PTHREAD lib is used and there the problem doesn't occur. So there the OS locking is enabled.

For proper operation, you also need to configure the module: In the Cryptographic Modules dialog, select the OpenSC card, and click on the "Config" button to the right. Select the "Enable this token" radio button, and select the "Publicly readable Certs" button.

This will ensure that Netscape uses the card when trying to display encrypted messages in Netscape messenger. Setting "Publicly readable Certs" will also stop a pretty annoying habit of Netscape which is to ask for all PINs when browsing sites requiring client authentication.

You should _not_ select the "RSA" button. If this option is selected, Netscape will try to use the card for all public key operations, and will fail horribly.

FIXME: this is for which versions of Netscape?

OpenSSL is a robust, full-featured toolkit implementing the SSL protocols as well as a general purpose cryptography library. It features a so called engine interface to combine the toolkit with the cryptographic abilities of some hardware.

OpenSC includes an engine for OpenSSL. This allows to use the OpenSSL library and command line utilities in combination with smart card cryptography.

Here is an example how it works with the command line tool openssl . You need to load the opensc engine first, and then can enter any command as usual (e.g. create or sign a certificate).

Here is an example of how to load the engine.

                  aj@simulacron:~$ openssl
                  OpenSSL> engine dynamic -pre
                  SO_PATH:/home/aj/opensc/lib/opensc/engine_opensc.so
                  -pre ID:opensc -pre LIST_ADD:1 -pre LOAD
                  (dynamic) Dynamic engine loading support
                  [Success]:
                  SO_PATH:/home/aj/opensc/lib/opensc/engine_opensc.so
                  [Success]: ID:opensc
                  [Success]: LIST_ADD:1
                  [Success]: LOAD
                  Loaded: (opensc) opensc engine
                  OpenSSL> 
                                                  
                

A typical OpenSSL command might be to make a certificate request: req -engine opensc -new -key key -keyform engine -out req.pem -text . See the OpenSSL documentation for details.

- key can specify the ID of a key in hex, - e.g. "45" would be key 0x45. -

Actually OpenSC has even two engines for OpenSSL: engine_opensc.so and engine_pkcs11.so .

The opensc engine does only work with OpenSC. It will not work, if several applications try to use the smart card at the same time or one applications tries to use several smart cards at the same time. Or several certificates or keys within one card. But for the simple case (one app, one cert, one smart card) it is working very fine.

The PKCS #11 engine is very generic and flexible. It will always work, even in complex situations involving several cards, keys, objects, certificates or concurrent applications. Also it is fully based on PKCS #11 and that way it can use the OpenSC PKCS #11 library (and does so by default), but it will work with any other PKCS #11 library, too.

To load the PKCS #11 engine, issue this command:

                  aj@simulacron:~$ openssl
                  OpenSSL> engine dynamic -pre
                  SO_PATH:/home/aj/opensc/lib/opensc/engine_pkcs11.so
                  -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD -pre
                  MODULE_PATH:/home/aj/opensc/lib/pkcs11/opensc-pkcs11.so
                  (dynamic) Dynamic engine loading support
                  [Success]:
                  SO_PATH:/home/aj/opensc/lib/opensc/engine_pkcs11.so
                  [Success]: ID:pkcs11
                  [Success]: LIST_ADD:1
                  [Success]: LOAD
                  [Success]:
                  MODULE_PATH:/home/aj/opensc/pkcs11/opensc-pkcs11.so
                  Loaded: (pkcs11) pkcs11 engine
                  OpenSSL> 
                                                  
                

and then proceed as normal.

A typical OpenSSL command might be to make a certificate request: req -engine pkcs11 -new -key key -keyform engine -out req.pem -text . See the OpenSSL documentation for details.

key has the format [slot_<slotNr>][-][id_<keyID>], in which

Examples:

For Windows, only the PKCS #11 engine (not the OpenSC engine) has been ported; use "engine_pkcs11" instead of "engine_pkcs11.so".

Version 3.6.1p2 of OpenSSH needs a patch to compile with OpenSC. You will find this patch in src/openssh/.

When compiling OpenSSH you need to run configure like this: ./configure --with-opensc=/path/to/opensc

You need to have a certificate on your smart card. A key is not enough. Download the public key of your certificate in Openssh format with this command: ssh-keygen -D reader [ : certificate ID ] > file

Replace reader with the number of the reader you want to use, default it 0. opensc-tool -l will give you a list of available readers. Add the certificate ID if you need to select one. Default is 45. pkcs11-tool -O will give you a list of available certificates and their IDs.

Then transfer the public key to the desired server and add it to ~/.ssh/authorized_keys as usual.

To use a smart card with Openssh run ssh -I reader [ : certificate ID ]

You can also use the OpenSSH ssh-agent tool with OpenSC. If you want to do so, use ssh-add -s reader

Pluggable authentication modules (PAM) is the default way under Linux and other Unix operating systems to configure authentication. OpenSC includes a module to allow smart card based authentication: pam_opensc.

The following options are recognized:

Generic options:

PKCS #11 is a standard API for accessing cryptographic tokens such as smart cards, Hardware Security Modules, ... It contains functions like C_GetSlotList(), C_OpenSession(), C_FindObjects(), C_Login(), C_Sign(), C_GenerateKeyPair(), ...

Some core concepts of PKCS #11 are:

Per token, only 2 PINs can be given: the SO (Security Officer) PIN and the user PIN. However, smart cards can have more than 1 user PIN. A way to this solve problem is to have multiple 'virtual' slots, as explained in appendix D of the PKCS #11 standard . So per physical reader, you have a number of virtual slots. If you insert a card in the reader, a token will appear in all the virtual slots, and each token will contain 1 PIN along with the private keys it protects and certificates corresponding to those private keys.

Because OpenSC supports multiple cards, it is not known in advance how many PINs a smart card will have. Therefore, a default number of 4 virtual slots is used. You can change this default in the pkcs11 section of opensc.conf: num_slots.

OpenSC implements the following behaviour: for each PIN, its private keys and corresponding certs, there is 1 virtual slot allocated. If there are any objects left, they are put in the next free virtual slot. And if there are some virtual slots left, an 'empty' token is 'put' in them; on this empty token a PIN and data can then be put. If you find this too confusing, you can hide empty tokens with the hide_empty_tokens option in the config file.

Example: Take a card with 2 PINs. Each PIN protects a private key and each private key has a corresponding cert chain. And then there are 3 other roots certs that have nothing to do with the other data. Now if num_slots = 4, hide_empty_tokens = false; and if you put the card your second card reader, you'll get the following:

If hide_empty_tokens would have been true, slot 7 wouldn't show a token.

Note: if in the example the 2 cert chain would have common certificates, those certificates would appear in the tokens in slots 4 and 5. (Which would cause a problem if those certs were deleted, this hasn't been solved yet in OpenSC).

Another good-to-know: the number of virtual slots has been hard-coded (it is 8 at the moment). So if num_slots = 4, only the first 2 readers will be visible. Or if you'd put num_slots to 3, the first 2 readers will have 3 virtual slots and the third reader will have 2.

The OpenSC tools allow you to specify PINs and keys on the command line. This is only suitable for testing or when you are the only user of the machine. If there are multiple users, other users usually are able to run things like 'ps' or 'top', and probably are able to see the arguments given to some process, too. Also, the arguments probably get logged to some shell history file like ~/.bash_history.

The solution is to use a script or, in the case of the pkcs15-init tool to put PINS and keys into a file and used through the --options-file options.

Some other problems if multiple users have access to the reader(s):

A solution is to add the user to a specific "scard" group after they've logged in through xdm. pcsc-lite's pcscd runs as pseudouser/group scard/scard, and limit the access to the server socket (pcscd.comm) as 770 scard:scard. This way, other possible users that may have logged in through ssh won't have any access to the local card readers. Not a perfect solution, but works for single-reader workstations well enough.

In case your application uses the pkcs11 library, that application will have, exclusive access access to the card once you provided a PIN. This is the default setting. If you would like multiple apps to use the pkcs11 library, you can set 'lock_login = false;' in the opensc.conf file, but this leaves your card open to other user's applications as well.

Other tools/libs (signer, openssh, pam) don't provide unique access once you are logged in.

Most cards have a default transport key that is used to create a pkcs15 directory on the card. Within the pkcs15 directory, files and keys are protected by PINs so the transport key has no power there.

This means that your keys and sensitive data are safe against others (who know the default transport key), in the sense that they can't be read or used.

However,anyone knowing the transport key and who has access to your card can delete the pkcs15 directory with all its keys, certs, data, ...

On itself, that may be a good thing if you lost your card, but there's another problem: If your card contains trusted certificates, and an adversary steals your card, puts another pkcs15 dir with other certs on the card and puts it back without you knowing, you may not find out until you put trust in those untrusted certs. Bottomline: be very carefull when using the card as a tamper-resistant storage -- make them PIN-protected for example. (Note: this if often not the case: the trusted certificates are stored usually stored in the application using them.)

While the opensc.conf and xxx.profile files don't contain any sensitive information, it is very important that they are not tampered with.

Some examples of what an adversary with write access to those files or an absent-minded administrator could do:

By default, the config and profile files can only be written by root/Adminstrator and the cache files are in the user home dir, so this is OK. Note however, that if there are profile files in the current dir, it will be those files that are used instead of the ones that were installed in a system dir!

From the above, it follows that you can't protect your card, nor use your card to protect something against someone with root access or who can change the config/profile files, binaries or sniff/modify the communication with the card.

Other parts of OpenSC be should ported as well. Also we should implement native Win32 APIs such as CryptoAPI Provider, some login stuff and ActiveX plugin for Internet Explorer to do the signing.

You should specify your plugin directory with: $ configure --with-plugin-dir= <directory>

Common plugin directories are /usr/lib/mozilla/plugins and /usr/lib/netscape/plugins.

See the INSTALL file for more instructions.

NOTE: PIN code dialog is done through libassuan from Project Ägypten. If you don't have it installed already, download it from the link below.