How to set up a pkcs#11 crypto environment with IBM JCOP Cards and an SCM Card
reader (last change 2004-04-01)
About
Author: Christian Schneider
You can always find the current version of this Howto on
http://www.liquidreality.de
E-Mail: c.schneider<at>scram.de
Special Thanks go to:
Marcus Oestreicher from IBM in Zuerich for answering my many Mails while I
tried to figure out the installation.
Axel Heider from SCM who sent me the SPR 532 reader for my diploma and also
helped me quite a lot.
What can you do with it
-----------------------
- Sign E-Mails
- Access to SSL Webservers with client certificate authentication
- Store ssh private keys on smartcard and activate the key in ssh-agent
- Smartcard based access to Linux computers and applications via pam
- Smartcard based access to Windows computers
- Sign documents. Technically you can do a qualified signature in europe.
(More about this at the end). Of course the Musclecard is not yet certified
but all requirements should already be met.
Some standards supported
------------------------
pc/sc Card Reader driver framework
pkcs#11 (Cryptographic Token Interface Standard)
pkcs#7 (Cryptographic Message Syntax Standard)
RSA For signatures and encryption
DSA Hashing
X509 Certificates
What you need
-------------
Remark: The versions I mention are the ones I used. You should be able to use
newer versions of the modules too.
- Operating System
(Fedore Core 1)
Windows 2000 as I was not able to install the applet in Linux eclipse. But
this is probably not a common requirement.
Technically every card reader that supports ccid should work
- IBM JCOP tools (3.0) development environment (costs about 70 CHF)
http://www.zurich.ibm.com/jcop
Best order the set with 2 Cards (1 JCOP 21id and 1 JCOP 30bio)
- A Javacard 2.1 compliant smartcard (I got mine with the Jcop development
environment)
I used the JCOP 21id card for the Musclecard applet
- CCID Driver (0.4.1) for the card reader.
This driver is open source and supports several USB card readers like
Gemplus GemPC 433 SL, Gemplus GemPC Key, Gemplus GemPC Twin, LTC31 from C3PO,
OmniKey CardMan 3121, SCM Micro SCR 331, SCM Micro SCR 335,
SCM Micro SCR 331-DI, SCM Micro SPR 532, ActivCard USB reader 2.0,
Silitek SK-3105 keyboard
http://pcsclite.alioth.debian.org/
How it all works together
-------------------------
Let's view it from the outside.
An application like mozilla accesses a crypto library. This is done with the
pkcs#11 standard. The muscleframework contains a pkcs#11 library that can be
used with mozilla.
The pkcs#11 library then accesses the pcsc driver to communicate with the card.
pcsc is a standard driver framework that makes all card reader drivers look
the same to applications.
The pcsc driver has configured what readers are attached to your system and
which card drivers to use for them.
The card driver accesses the Smartcard. For our purposes it is a Javacard.
Javacards can contain java packages, java applets and data like keys or pins.
Packages and Applets are identified by AIDs.
The Musclecard contains an applet called cardedge it has the AID A00000000101
the package itself has the AID A000000001. As you see they only differ in the
last two digits. The applet does the cryptographic function and forwards the
response back through the layers.
You now should know what the components are and what they do. I consider this
very important for the start as all these layers, drivers and libraries can be
quite confusing.
Install
-------
Before you install make sure you have the necessary libraries and their
development packages installed.
Some packages needed are flex, openssl-devel, qt-devel, libusb-devel. If you
encounter more packages you needed to install please let me know so I can list
them here.
Of course you also need the gcc compiler, make and so on.
If you encounter problems please let me know.
Install PCSC lite
-----------------
Unpack pcsc lite.
./configure
make
make install
You now should have installed pcsc in /usr/local/pcsc
As the pcsc library is installed to /usr/local/lib you eventually have to
add this dir to /etc/ld.so.conf
Then type
ldconfig
Install the card reader driver
------------------------------
Unpack ccid.
./configure
make
make install
You should now have the ccid driver in /usr/local/pcsc/drivers/ifd-ccid.bundle
Configure the card reader driver
--------------------------------
Call lsusb
You should see the list of usb devices connected to your system.
The line with my scr 532 looked like this
Bus 001 Device 003: ID 04e6:e003 SCM Microsystems, Inc.
04e6 is the vendor id
e003 is the product id
Perhaps you need a firmware upgrade from SCM. This should be done in windows.
Add the vendor and product ids to the following file if not yet present
/usr/local/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist
Configure the pcsc lite driver
------------------------------
Edit the /etc/reader.conf
FRIENDLYNAME "Generic CCID reader v0.4.1"
DEVICENAME /dev/pcsc/1
LIBPATH /usr/local/pcsc/drivers/ifd-ccid.bundle/Contents/Linux/libccid.so.0.4.1
CHANNELID 0x000001
In theory you should be able to use bundleTool to configure the driver but it
did not work for me.
I just got a mail from Ludovic Rousseau one of the main developers of ccid and pcsc
that the reader.conf should be empty for usb readers. PCSC should find the
reader without any configuration. I tried this but my reader was not installed.
So perhaps you should start with an empty reader.conf and if it does not work
try to use the above. Perhaps I need the config because I use the kernel 2.6.
Start the pcsc daemon
---------------------
pcscd
Verify that the daemon is loaded
ps ax | grep pcscd
Verify driver installation
--------------------------
To test the installation you can use the utility testpcsc that is locate in the
src subdirectory of pcsc-lite.
I get the following output:
./testpcsc
MUSCLE PC/SC Lite Test Program
Testing SCardEstablishContext : Command successful.
Testing SCardGetStatusChange
Please insert a working reader : Command successful.
Testing SCardListReaders : Command successful.
Reader 01: Generic CCID reader v0.4.1 0 0
Enter the reader number : 01
Waiting for card insertion
: Command successful.
Testing SCardConnect : Command successful.
Testing SCardStatus : Command successful.
Current Reader Name : Generic CCID reader v0.4.1 0 0
Current Reader State : 34
Current Reader Protocol : 1
Current Reader ATR Size : f
Current Reader ATR Value : 3B E6 00 FF 81 31 FE 45 4A 43 4F 50 32 31 07
Testing SCardDisconnect : Command successful.
Testing SCardReleaseContext : Command successful.
PC/SC Test Completed Successfully !
Installation of the applet on a Gemplus GemXpresso Card
-------------------------------------------------------
See the file 'Mcardapplet-0.9.8/GemXpressoRADIII/README.GXPRADIII'.
This will load the class and install the applet.
Installation of the applet with IBM JCOP Tools
----------------------------------------------
The following instructions are only needed if you want to install the applet
on an IBM JCOP Card. If you have another card skip to Install Muscelcard
Framework.
Install JDK
-----------
Just use the installer. Then set the JAVA_HOME environment variable to
the installation dir.
Install Eclipse
---------------
Quite easy. Just unpack to /usr/local/eclipse or c:\programme.
Install The JCOP Tools from IBM
-------------------------------
Open Eclipse.
In the main menu: Help / Software Updates / Update Manager.
Inside the Feature Updates view rightclick and select New / Site Bookmark.
Enter http://www.zurich.ibm.com/jcop/download/eclipse as a new Update site.
You then have a new entry in the view named jcop. There you can select the
JCOP Tools for installation. The Demos are not usefull as they contain no
source code.
Register the Tools
------------------
When you use the JCOP Tools the first time you have to provide an
authentication so they know you bought the tools. If you have ordered the
cards you can use them to authenticate to the Tools. ( If you are doing this
in Linux you have to complete the card reader installation first)
Compile and install Musclecard Applet
-------------------------------------
Open eclipse
New / Projects / IBM JCOP Development Tools / Javacard project
As project name I use musclecard
Select the API for your card (This selects the right java libraries)
Create a blank project
Outside Eclipse
Extract MCardApplet
copy the contents of the src directory to the project src directory
Inside Eclipse do a refresh with right mouse click in the Package Explorer.
You now should see the source package inside eclipse and two errors.
The errors appear because we have not yet set the AIDs.
Now set the package AID to A000000001 and the AID for cardedge.java to
A00000000101.
Then select run.. / IBM JCOP Card Simulator / new
Verify the project is set to your project
Set the JCOP target to Card Reader. This confused me first as the whole thing
is called Card Simulator but you can write real cards too.
Now let it run...
Eclipse should now automatically compile the java files, create a cap file and
upload it to the card.
You see the upload status in the JCOP Shell view on the right side.
At the end it does a card-info. For me it looks like this:
Card Manager AID : A000000003000000
Card Manager state : OP_READY
Application: SELECTABLE (--------) A00000000101
Load File : LOADED (--------) A0000000620001 (java.lang)
Load File : LOADED (--------) A0000000620101 (javacard.framework)
Load File : LOADED (--------) A0000000620102 (javacard.security)
Load File : LOADED (--------) A0000000620201 (javacardx.crypto)
Load File : LOADED (--------) A0000000030000 (visa.openplatform)
Load File : LOADED (--------) A000000167413001 (FIPS 140-2)
Load File : LOADED (--------) A0000001320001 (org.javacardforum.javacard.biometry)
Load File : LOADED (--------) A0000000035350 (Security Domain)
Load File : LOADED (--------) A000000063 (PKCS15)
Load File : LOADED (--------) A000000001
If you do not see the Application, type
select A00000000101
The work inside eclipse is now done and you should be ready to format the
token.
I had problems running the JCOP project on linux as I got the message
Exception occured during launch. VM launch failed
On the console where I started eclipse I saw:
Unhandled exception caught in event loop.
Reason: java.lang.ExceptionInInitializerError
Unhandled exception caught in event loop.
Reason: java.lang.NoClassDefFoundError
My IBM contact explained me that some files needed to be set executable. This
solved the problem.
cd /usr/local/eclipse
find . -name "*.sh" -exec chmod a+x {} \;
find . -name "*.exe" -exec chmod a+x {} \;
find . -name "*.so" -exec chmod a+x {} \;
You should also be able to compile and upload the applet in the command line.
The neccessary command line tools from the IBM plugin reside in:
/usr/local/eclipse/plugins/com.ibm.bluez.jcop.eclipse_1.0.1.a/prebuilt/bin/linux/
The relevant Tools are:
converter (To convert the class files to a cap file)
jcshell to upload the cap file to the card
I have not yet done the install with command line tools. If someone has done
this please send me a script or explanations so I can add them here. In
general I think IBM should also release the command line tools separate from
the eclipse plugin so people can do the complete install on a server without X.
Install the muscle framework
----------------------------
extract the muscleframework
cd MCardPlugin
./configure
make
make install
This installs the MuscleCard plugin into
/usr/local/pcsc/services/mscMuscleCard.bundle/
As the IBM JCOP21id is not yet known to the MuscleCard plugin we have to get
the ATR of the card and add it to the following file
/usr/local/pcsc/services/mscMuscleCard.bundle/Contents/Info.plist
You can get your card's ATR in the JCShell e.g. from inside Eclipse by typing
/term
/card
I got:
ATR: 3BE600FF8131FE454A434F50323107
T=1, II=0/PI1=0, N=255, IFSC=254, BWI=4/CWI=5, Hist="JCOP21"
Enter the ATR in the file
<key>spAtrValue</key>
<string>3BE600FF8131FE454A434F50323107</string>
Install libmusclepkcs11
-----------------------
cd to your muscleframework source
cd libmusclepkcs11
./configure
make
make install
You have now installed the library to
/usr/local/lib/libmusclepkcs11.so
This is the library we later use for mozilla.
Install XCardII
---------------
extract XCardII
cd src
Edit the Makefile if necessary. I had to set the correct path to qt.
The lines I changed now look like:
INC = -I/usr/lib/qt-3.1/include/
LIBS = -L/usr/lib/qt-3.1/lib -lqt -lmusclecard -lpthread
make
make install
Install muscleTools
-------------------
This is only necessary if you have problems with xcard.
extract muscleTools
make
make install
Format the token and create keys
--------------------------------
Start xcard
xcard
You should now see a window with
Tokens
MuscleCard Applet
If you see something like no tokens or no valid tokens you either have not
correctly installed the card reader, the MuscleCard plugin or the Applet.
Select the applet and call Options / Format Card
You see a dialog card personalization
Select use factory default. Btw. the initial Admin PIN for a MuscleCard is
Muscle00. Enter desired USER pin and unblock code.
Then select Create. The Applet is now initialized. All eventually existing
keys are deleted. So use with care later.
You can then generate an RSA key and export the public key to a file.
If you get invalid parameter you perhaps tried to reserve too much memory.
Use Mozilla Firefox to Access an SSL Webserver with Client certificate
----------------------------------------------------------------------
Tools / Options... / Advanced / Certificates / Security Devices /
Manage Security Devices
Load
Name: MuscleCard
Filename: /usr/local/lib/libmusclepkcs11.so
You now have the new crypto Module installed.
Login
Type your pin
If you have a certificate in form of a pkcs#12 keystore (normally .p12) you can
simply import it into the keystore.
By integrating openssl with muscle it should also be possible to generate the
key directly on the card and issue a csr, but I have not yet managed to do
this. But the pkcs12 solution works very well.
You can use the imported certificate and key to sign mails, encrypt/decrypt
mails and access ssl Webservers that require a client certificate.
todo: Link to Webserver Configuration, Example protected directory on
www.liquidreality.de, With key import
Install openssl with musclecard support
---------------------------------------
todo
Install openssh with musclecard support
---------------------------------------
todo
Install the pam module
----------------------
todo
Configure pam for ssh access with smartcard
-------------------------------------------
todo
Install the Austrian Security Kapsel
------------------------------------
todo
Use the Security Kapsel to sign documents
-----------------------------------------
todo
Links
Muscle Movement for use of Smartcards in a linux environment
http://www.musclecard.com/
Javacard Specification from sun
http://java.sun.com/products/javacard/
Public-Key Cryptography Standards (pkcs)
http://www.rsasecurity.com/rsalabs/pkcs/
XML Signature Standard
http://www.w3.org/Signature/
----------------------
Copyright (c) 2004 Christian Schneider
Permission is granted to copy, distribute and/or modify
this document under the terms of the GNU Free Documentation
License, Version 1.2 or any later version published by the
Free Software Foundation.
See http://www.gnu.org/copyleft/fdl.html for the full license text
Add Comment