OpenSC Development Team opensc-devel@opensc.org libopensc is a library for accessing SmartCard devices using PC/SC Lite middleware package. It is also the core library of the OpenSC project. Basic functionality (e.g. SELECT FILE, READ BINARY) should work on any ISO 7816-4 compatible SmartCard. Encryption and decryption using private keys on the SmartCard is at the moment possible only with PKCS#15 compatible cards, such as the FINEID (Finnish Electronic IDentity) card manufactured by Setec. Here is a list of all Authors and Contributors of OpenSC in alphabetical order: Robert Bihlmeyer robbe@orcus.priv.at Stef Hoeben Hoeben.S@Zetes.com Andreas Jellinghaus aj@dungeon.inka.de Olaf Kirch okir@suse.de Nils Larsch larsch@trustcenter.de Kevin Stefanik kstef@mtppi.org Antti Tapaninen aet@cc.hut.fi Timo Teräs timo.teras@iki.fi Juha Yrjölä juha.yrjola@iki.fi Jörn Zukowski zukowski@trustcenter.de

The following people provided inspiration, moral support and/or valuable information during the development of OpenSC: Antti Partanen antti.partanen@vrk.intermin.fi David Corcoran corcoran@linuxnet.com 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: Matthias Brüstle Markus Friedl Geoff Thrope geoff@geoffthorpe.net

OpenSC smart card library Copyright (C) OpenSC developers 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 OpenSC is a large toolkit. The main building block is the opensc library. It has three layers of code, each with several drivers in it. Other libraries are the pkcs11 module, a pam module, two engines for openssl. In addition there are several tools to test and use these tools and libraries. Purpose of this chapter is to give an overview of the inner workings of the opensc library, to give a short presentation what the other libraries do, and finaly what the opensc toolchest has to offer. Each tool has it's own man page, each library it's own section in this document.

libopensc is the basic library used by everthing 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: reader OpenSC needs some way to talk to smart card readers and cards in the smart card readers. Different software can be used for that purpose, each software has it's own reader module so OpenSC can use that software. card In a perfect world all smart cards would implement ISO 7816 standard, and thus accept the same commands and give the same answers. Unfortunatly most cards have their own commands, syntax and responses. The card modules in libopensc implement these different commands. pkcs15init Smart cards usualy have a file system. To store or create keys or certiticates on a smart card one needs to format the card, create directories and objects and set permissions in a secure way. Not only are the commands to do this different from card to card, also the security model is often very different. These pkcs15init modules implement these differences. pkcs15 framework PKCS#15 is the standard on how to store certificates and keys on a smart card or crypto token. But many vendors have their own proprietory mechanism for storing these informations, for example in different directories. OpenSC implements the PKCS#15 standard, but there is also an emulation module for a slightly incompatible storage mechanism in the works. It should be possible to implement a completely differennt framework for compatiblity with a non pkcs#15 way of storing and accessing keys and certificates.

PC/SC-Lite is well known as smart card middleware. It interacts with drivers for the smart card readers on the buttom, 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 betweens 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 the . 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 . 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-0.8.0 $ ./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 lightwight. 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 availble with full source code for free. OpenCT is a software companion to OpenSC and the prefered way of accessing smart cards under linux. OpenCT is available from the OpenSC website 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 . Then configure OpenSC to use OpenCT and specify the location where OpenCT is installed like this: Usbtoken is a small driver for usb crypto devices only. It does not need any other helper software and is included in OpenSC for convinience. However Usbtoken is deprecated, the new OpenCT software is now the recommended way to access usb crypto tokens. Usbtoken is no longer activly developed, but bugs are still fixed and help is provided on the OpenSC mailing list at opensc-devel@opensc.org. If you still want to use OpenSC with Usbtoken, please configure OpenSC like this: $ cd opensc-0.8.0 $ ./configure --enable-usbtoken Documentation on Usbtoken is in the file . 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.

See the INSTALL file for instructions. If you are using the CVS version, you have to run the 'bootstrap' script before running configure. Please note, that for bootstrap to work, you have to have the correct versions of Autoconf, Automake and Libtool installed.

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: Copy opensc.conf to your Windows directory (usually C:\WINDOWS or C:\WINNT). This is optional. Copy opensc.dll and opensc-pkcs11.dll to your path. If you want to use pkcs15-init.exe, make sure the *.profile files in the pkcs15-init\ dir are in the same directory as pkcs15-init.exe.

This adds extended functionality. E.g. the pkcs15-init tool, pkcs11 hash mechanisms and more pkcs11 signature mechs. download and compile the openssl sources from Add the inc32\ dir to your include path, the out32dll\ to your lib path and your executable path set include=%include%;.....\inc32 set lib=%lib%;.....\out32dll set path=%path%;....\out32dll In src/tools/Makefile.mak uncomment pkcs15-init.exe in the "TARGETS" line (optionally) and add libeay32.lib (and gdi32.lib) to the "link" line In src/libopensc/Makefile.mak add libeay32.lib (and gdi32.lib) to the "link" line In src/pkcs11/Makefile.mak add libeay32.lib (and gdi32.lib) to the "link" line In win32/Make.rules.mak add /DHAVE_OPENSSL to the "COPTS" line 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.

CryptoFlex Support signing/decrypting, and initialization Gemplus PK 4K, 8K, 16K Support signing/decrypting, and initialization. NOTE: You will not be able to initialize a GemSafe cards - these card already have been personalized by Gemplus, and you cannot erase them or create new key files on them. Aladdin eToken PRO Support signing/decrypting, and initialization. NOTE: CardOS only supports keys for decryption or signing, but not both. If you create/store keys with "--split-keys" OpenSC will work around this limitation. Eutron CryptoIdendity IT-SEC Support signing/decrypting, and initialization. NOTE: CardOS only supports keys for decryption or signing, but not both. If you create/store keys with "--split-keys" OpenSC will work around this limitation. Micardo Supported - need to fill in the details Miocos Supported - need to fill in the details Setcos Supported - need to fill in the details Tcos Supported - need to fill in the details

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.

Select menu: Communicator -> Tools -> Security Info Select Cryptographic Modules Click: Add Fill in module name: "OpenSC PKCS#11 Module" and module file: /path/to/opensc/lib/pkcs11/opensc-pkcs11.so 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?

Make sure Personal Security Manager (PSM) is installed (eg. mozilla-psm package is installed). Select menu: Edit -> Preferences Select category: Privacy & Security -> Certificates Click: Manage Security Devices Click: Load Fill in module name: "OpenSC PKCS#11 Module" and module file: /path/to/opensc/lib/pkcs11/opensc-pkcs11.so

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 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. - 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. 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 ][-][id_]]]>, in which the optional slotNr indicates which pkcs11 slot to take (starting from 0, which is also the default) keyID is the key ID in hex notation Examples: id_45 => private key with ID = 0x45 in the first 'suited' slot slot_2-id_46 => private key with ID = 0x46 in the third slot For Windows, only the pkcs11 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 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: debug log more debugging info audit a little more extreme than debug use_first_pass don't prompt the user for passwords, take them from PAM_ items insteat try_first_pass don't prompt the user for passwords unless PAM_(OLD)AUTHTOK in unsed use_authtok require PAM_AUTHTOK set, use it, fail otherwise set_pass set the PAM_ item swith the passwords used by this module nodelay used to prevent failed authentication resulting in a delay of about 1 second. auth_method=X choose either pkcs15-ldap or pkcs15-eid authentication. pkcs15-eid is the default. Generic options: -h Show help -r reader Reader name (FIXME: not number?)

This is the default authentication method. Create a directory .eid in your home directory and copy your PEM encoded certificat to the file .eid/authorized_certificates. Note: pkcs15-tool -c will show you all certificates and their ID, pkcs15-tool -r ID -o ~/.eid/authorized_certificates will save the certificate ID to that file.

Setting auth_method to pkcs15-ldap will enable ldap based authenticaton. These options are supported: -L ldap.conf Configuration file to load -A entry Add new entry -E entry Set current entry -H hostname hostname of ldap server -P port port or ldap server -S scope scope of ldap server -b binddn binddn for ldap connection -p passwd password for ldap bind -B base base for ldap bind -a attributes attributes to fetch -f filter filter in ldap search FIXME: provide an example of ldap data structure, config file etc.

PKCS11 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_Decrypt(), ... Some core concepts of pkcs11 are: slot: the place in which a smart card can be put. Usually this corresponds with a card reader (but: see below, Virtual slots). token: the thing that is put in a slot. Usually this corresponds with a smart card (but: see below, virtual slots). object: a key, a certificate, some data, ... Is either a token object (if it resides on the card) or a session object (if it doesn't reside on the card, e.g. a certificate given to the pkcs11 library to do a verification). session: before you can do anything with a token, you have to open a session on it. operation: a signature, decryption, digest, ... operation, that can consist of multiple function calls. Example: C_SignInit(), C_SignUpdate(), C_SignFinal(); here the first function starts the operation, the third one ends it. Only one operation can be done in the same session, but multiple sessions can be opened on the same token.

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 pkcs11 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: token in slot 4: PIN 1, key 1, cert chain 1 token in slot 5: PIN 2, key 2, cert chain 2 token in slot 6: the 3 other root certs token in slot 7: no data 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.

* Debian packaging * GUI applications * Ports to MacOS X (jey) and Win32 (fabled?) * Add support for EMV and GSM (anyone?) * Pin pad support * Merge DODF patches (mostly done) * put generic PEM encoding/decoding functions into libopensc? * Merge pkcs11 proxy from Zetes * pkcs11: support decrypt for those cards that have it * pkcs11: make sure all PIN ops work through pkcs11 * pkcs11: unblock pins: check for unblock pins in AODF * all: support for RSA-PSS * pkcs15-init: support SOPIN on Cryptoflex * pkcs15-init: use max. possible usage by default * pkcs15-init: during keygen, make sure the pubkey usage is right * pkcs15-init: when using an unblock PIN, write an AODF entry for it (alternatively: set unblockDisabled flag for those PINs that have no PUK?) * pkcs15: fix sc_pkcs15_change_reference_data; add unblock function * pkcs11: make sure all PIN ops work through pkcs11

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.

A mailing-list has been set up for support and discussion about the OpenSC project. Additional info is available at OpenSC web site. See the OpenSC web site at Information about Assuan and project Ägypten: OpenSC Signer is a Netscape plugin that will generate digital signatures using facilities on PKI-capable smartcards.

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.

This document is maintained as docbook xml document. Here are some hints and links for newcomers. This document is written in XML not SGML. To convert it, use a XSL stylesheet, not an DSSSL stylesheet. Ignore all tools and webpages talking about SGML or DSSSL, those talk about legecy technology no longer used and no longer up to date. The Docbook Project at Sourceforge has the XSL stylshet used to convert this XML document to other formats. Docbook, the definite Guide (O'Reilly Book) documents Docbook, is very handy as reference and available Online for free. Online Book on Docbook, XML and XSL is a book with a greate introduction on how to create a document, how to convert it, where to get the software, tools and everything. It you a fast road to editing this document, look at this book. THis document might be ugly. If you know html, please help us to improve it. Some stuff can be tuned in the xsl stylesheet (see Reference for the HTML stylesheet parameters), but most stuff can be improved via CSS styles. We need help on this !