Accessing the Cambride University Card under Linux <author>Rich Wareham, <tt><richwareham@users.sourceforge.net></tt> <date>v0.3alpha, 2001 September 21 <abstract> This mini-HOWTO outlines the steps required to install and configure the PC/SC smartcard resource manager middleware under Linux. </abstract> <toc> <sect>Introduction This document has been written to provide Systems Administrators and privileged users with information on how to access the Cambride University Card under the Linux operating system. Although untested on other platforms, there is nothing particularly Linux specific about the software described here and it should be poossible to install it under many flavours of Unix. <sect1>New versions of this document New versions of this document can be obtained from <htmlurl url="http://www.srcf.ucam.org/~rjw57/sc/pcsc_lite" name="http://www.srcf.ucam.org/~rjw57/sc/pcsc_lite">. <sect1>Feedback All comments, error reports, additional information and criticism of all sorts should be directed to: <verb> richwareham@users.sourceforge.net </verb> <sect1>Disclaimer No liability for the contents of this documents can be accepted. Use the concepts, examples and other content at your own risk. Additionally, this is an early version, with many possibilities for inaccuracies and errors. One of many possible setups will be described. In the Linux world, there is usually a number of ways in which to accomplish things. As far as I know, all of the programs mentioned here are released under the GNU General Public License or the Lesser GNU Public License. <sect1>Copyright information This document is copyrighted ©2001 Richard Wareham and distributed under the following terms: <itemize> <item>This document may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies. Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions. <item>All translations, derivative works, or aggregate works incorporating any parts of this document must be covered under this copyright notice. That is, you may not produce a derivative work from this HOWTO and impose additional restrictions on its distribution. </itemize> <sect1>How do I submit changes or additions to the HOWTO? The preferred method is to edit the file <tt>howto.sgml</tt> to incorporate the changes, create a diff file by typing something like <verb> diff -uw original-file new-file </verb> and send it to <tt>richwareham@users.sourceforge.net</tt>. If you do not know SGML, that's ok. Changes or new information in any form will be accepted. Creating the diff file just makes it easier on the HOWTO maintainer. <tt>:-)</tt> <sect>About the University of Cambridge Card The University card is described in detail on <htmlurl url="http://www.admin.cam.ac.uk/offices/misd/univcard/" name="http://www.admin.cam.ac.uk/offices/misd/univcard/">. This document will only deal with the use of the smart chip on the card rather than the TDSi Infrared strip or the barcode. From the above site: <quote> The smart chip is a microprocessor embedded in the card. The chip is able to store a small amount of information and to control the conditions under which the information can be accessed or modified. The chip is also able to perform some cryptographic functions such as creating or checking a digital signature. The primary purpose of the chip is to authenticate the identity of the cardholder. For this purpose, the chip holds a public/private key pair together with a digital certificate. The certificate asserts that the public key on the card belongs to the person associated with a particular identifier; this assertion is made by a Certificate Authority run by the University Card Services. The corresponding private key remains on the card: it cannot normally be extracted, but is used by the card's own cryptographic functions. The private key on the card is protected by a PIN (personal identification number). PINs are assigned at random when the cards are issued; it may also be possible for individuals to change their PINs at a later date. Cardholders must never reveal their PIN to anyone else, even to members of staff at the card office. If the PIN is entered incorrectly three times in succession, the card becomes 'blocked' and cannot then be used for authentication. The card must then be returned to the card office where it can be 'unblocked' if staff are assured that it is in the hands of the rightful owner. </quote> The University Card uses an IBM MFC 4.22 chip. Technical details on this chip are available at <htmlurl url="http://vertebra.cbcu.cam.ac.uk/" name="http://vertebra.cbcu.cam.ac.uk/">. <sect>Programming Interfaces to Smartcards There exists a widely used Application Programmers Interface (API) called PC/SC which abstracts the various Smartcard readers available. In this document, the <htmlurl url="http://www.gemplus.com" name="GemPlus"> GemPC410 reader will be used as an example, although there are many other readers which may work (see the Resources at the end of this document). Under Linux, this API is implemented as a two tier system; your application uses the PC/SC API to talk to a middleware resource manager. The resource manager then talks to one or more readers using reader specific drivers. In this way the middleware need be set up only once for each reader and all applications are reader agnostic. Linux implements a subset of PC/SC called PC/SC lite. Details of this API may be obtained from the MUSCLE web-site (see Resources). For most uses, existing PC/SC programs may be ported simply to the PC/SC lite API. It is outside the scope of this document to provide a tutorial on PC/SC lite programming although many such documents can be found on the Internet. <sect>Obtaining and Installing the Software <sect1>Obtaining the software The main source of software is the <htmlurl url="http://www.linuxnet.com" name="MUSCLE web-site">. The PC/SC lite middleware should be downloaded from <htmlurl url="http://www.linuxnet.com/middle.html" name="http://www.linuxnet.com/middle.html"> and drivers from <htmlurl url="http://www.linuxnet.com/sourcedrivers.html" name="http://www.linuxnet.com/sourcedrivers.html">. <bf>Note:</bf> The GemPlus reader driver available from the above sites does not work well with the University Card. Instead, you should use the modified version available from <htmlurl url="http://www.srcf.ucam.org/~rjw57/sc" name="http://www.srcf.ucam.org/~rjw57/sc">. <sect1>Installing the software <sect2>PC/SC lite middleware Download the <tt>pcsc-lite-x.x.x.tar.gz</tt> file to a convenient location. The <tt>x.x.x</tt> denotes the version number of the software. The latest version at the time of writing is 0.9.3. Open a terminal and change to the directory the file was downloaded to. Enter the following commands: <verb> $ gunzip -c pcsc-lite-*.tar.gz | tar xv $ cd pcsc-lite-x.x.x # Replace x.x.x with version $ ./configure --prefix=/usr/local/pcsc $ make $ su Password: (enter root password) # make install # exit $ </verb> The PC/SC lite software will then be installed to <tt>/usr/local/pcsc</tt>. Note: Under Solaris, you may have to modify the Makefile to add the following linker flags: <verb> -lsocket -lnsl -lrt </verb> <sect2>Reader drivers Download the reader drivers and install as per instructed by files which came with the driver. If you have the GemPlus serial reader driver note that the GemPlus readers have problems understanding the Answer to Reset (ATR) response of the card. To use the card with GemPlus readers, you must download the correct driver from this site and perform the following steps. Open a terminal and change to the directory you downloaded the <tt>libgemcore-hacked.tar.gz</tt> file to and enter the following commands: <verb> $ gunzip -c libcamgemcore-x.x.x.tar.gz | tar xv $ cd libcamgem* $ ./configure $ make $ su Password: (enter root password) # make install # exit $ </verb> Then edit <tt>/etc/reader.conf</tt> to point to the <tt>libcamgemcore.so.0.0.0</tt> file which has been created as per the next section. <sect3>Configuration The main configuration file is <tt>/etc/reader.conf</tt>. This file should contain an entry for each driver of the following form: <verb> FRIENDLYNAME "FooBar Inc. FB100 reader" DEVICENAME FOOBAR_FB100 LIBPATH /usr/lib/libfoobar.so.1.0.0 CHANNELID 0x0102F8 </verb> Where the fields have the following meanings: <itemize> <item><tt>FRIENDLYNAME</tt> -- Any descriptive name for the reader. <item><tt>DEVICENAME</tt> -- Any shorter name. <item><tt>LIBPATH</tt> -- <bf>Full</bf> path to the driver library. <item><tt>CHENNELID</tt> -- The serial port the reader is connected to, taken from the following table: <itemize> <item><tt>0x0103F8</tt> -- COM1 or <tt>/dev/ttyS0</tt> <item><tt>0x0102F8</tt> -- COM2 or <tt>/dev/ttyS1</tt> <item><tt>0x0103E8</tt> -- COM3 or <tt>/dev/ttyS2</tt> <item><tt>0x0102E8</tt> -- COM4 or <tt>/dev/ttyS3</tt> </itemize> </itemize> <sect3>Invocation To launch the PC/SC middleware, you may need to set some environment variables. If you are using the Bash shell then the following commands should launch the PC/SC middleware: <verb> $ su Password: (enter root password) # export PATH=$PATH:/usr/local/pcsc/bin # export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pcsc/lib # pcscd </verb> <sect>Testing A simple program to test the card reader with a University Card is available at <htmlurl url="http://www.srcf.ucam.org/~rjw57/sc/software/kpcsctest.html" name="http://www.srcf.ucam.org/~rjw57/sc/software/kcardtest.html"> <sect>Using the Cambridge Smartcard with Netscape/Mozilla The University SmartCard has the ability to securely authenticate itself to a remote server by use of a suitable `plugin' for the Netscape/Mozilla browsers. The plugin conforms to the PKCS#11 Cryptoki interface standard so may also be used by other software which can make use of such plugins. The plugin is available from <htmlurl url="http://www.srcf.ucam.org/~rjw57/sc" name="http://www.srcf.ucam.org/~rjw57/sc">. To use it, one must download both the <tt>libcamcard</tt> and <tt>campkcs</tt> tar-balls. Also the PCSC-lite middleware must be correctly set-up as in the above sections. Both <tt>libcamcard</tt> and <tt>campkcs</tt> must be unpacked and installed in the usual manner (<tt>libcamcard</tt> is required for <tt>campkcs</tt> and so must be built first). When you have built <tt>campkcs</tt>, a new library will be installed on your system, <tt>libcampkcs11.so.x.x.x</tt>. It is this file which is the PKCS#11 module. Full installation instructions are available at <htmlurl name="http://vertebra.cbcu.cam.ac.uk/pkcs-install.html" url="http://vertebra.cbcu.cam.ac.uk/pkcs-install.html"> (except replace the Windows DLL available there for the <tt>libcampkcs11.so.x.x.x</tt> file). <tt>campkcs</tt> adds some extra functionality to the one available from the above site. Firstly, it supports the newer (layout) Version 1 Univeristy Smartcard. Also Logout and Change PIN functions are supported. Finally, the module also adds support for multiple certificates on one card. <sect>Resources <sect1>General resources <itemize> <item>MUSCLE homepage -- <htmlurl url="http://www.linuxnet.com" name="http://www.linuxnet.com"> </itemize> </article>