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:

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

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

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

This adds extended functionality. E.g. the pkcs15-init tool, pkcs11 hash mechanisms and more pkcs11 signature mechs.

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 and 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 Crypthographic 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 allowes 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 how to load the engine and create a new certificate.

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> 
				

For Windows use "engine_opensc" instead of "engine_opensc.so".

A typical OpenSSL command might be req -engine pkcs11 -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 with an optional prefix of the slot to use. Slots are counted starting with 0. "45" would be key 0x45 in the first slot, S2-46 would be key 0x56 in the third slot.

Actualy 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 pkcs11 engine is very generic and flexible. It will always work, even in complex situations involiving several cards, keys, objects, certificates or concurrent applications. Also it is fully based on pkcs11 and that way it can use the Opensc pkcs11 library (and does so per default), but it will work with any other pkcs11 library, too.

To load the pkcs11 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.

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 authantication modules or 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:

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 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.