
		Belgian EID PKCS11 library
		==========================

Version: 1.3
Date: 16/09/2003

Gratefully based on
- OpenSC (see http://www.opensc.org), licence: see COPYING
- OpenSSL (see http://www.openssl.org), licence: see LICENCE

Platforms:
- Windows 98, Windows NT4 (SP6), Windows 2000 (SP2) and Windows XP


Installation
============

It is assumed that a working card reader is installed.

Windows:
  Copy the files in the bin directory to your execution path.
  (e.g. C:\WINNT\system32\ or C:\WINDOWS\System32\)


How to use the PKCS11 library
=============================

The pkcs11 DLL is opensc-pkcs11.dll

Some test tools can be found in the tools\ directory
E.g. belpic-tool -l             (to see if a card reader is present)
     belpic-pkcs11-tool -L      (to list the available PKCS11 slots)
     belpic-pkcs11-tool -O      (to view the objects in the first PKCS11 slot)
     belpic-pkcs11-tool -t -l   (to test the PKCS11 library)


Configuration file
==================

There is an optional configuration file that can be used to e.g.
- set GUI options
- add pin pad readers
- add new ATRs
- set error logging

The config file is called opensc.conf and should be placed in
your windows home directory (usually C:\WINNT or C:\WINDOWS).
An example is provided in this directory

About pin pad support
=====================

To add a support for a pin pad reader, add the following in
the opensc.conf file:
- the PC/SC reader name (not the trailing number)
- the name of the corresponding pin pad library (DLL)

The following reader/lib pairs are hardcoded:
- reader = "Xiring X Pass Serial", lib = "xireid"

There is a special pin pad library, "pinpad_emulator.dll",
that can be used on most readers in order to emulate a
pin pad reader: the PINs are then asked on the PC's screen
and then sent to the reader.
To use this pin pad emulator, add the reader name in the
opensc.conf file. The reader name can be obtained by
doing "opensc-tool -l", but the trailing 0 (or 1) should
be discarded.


Some technical notes about this PKCS11 library
==============================================

1. About the pin dialog

Normally, a pkcs#11 library doesn't ask for PINs because:
- either the appliciation will do this and then give the PIN
  to the pkcs#11 lib (who will send it to the card)
- or, if a PIN pad reader is used, the PIN will be entered on
  the PIN pad reader.

However, the Belgian EID card enforces the following rules:
- Once the user PIN has been given, the Authentication key can
  allways be used.
- The Signature key can only be used if the user PIN have been
  given just before doing a signature. This means that you have
  to supply your PIN for each signature you do with that key.

The pkcs#11 standard does not support this behaviour: once you
logged in using a PIN, you are assumed to have access to all
the private keys protected by that PIN.

Therefore, this pkcs#11 library itself asks for the user PIN
each time a signature with the Signature key will be done.
(In the case no PIN pad reader is present.)

If a PIN pad reader is present, no PIN dialog will appear,
but to alert the user that a PIN has to be entered on the
PIN pad reader, the pkcs#11 lib will show a message box.
You can disable this default behaviour by setting the values
in the belpic_pin_pad section to false.

2. Private key objects are visible without logging in

Most pkcs#11 implementation only show info about the private
key objects after a PIN has been supplied (though there is
no reason for this, because all the info can be read from
the card without supplying a PIN).

However, this would have the consequence that you would have
to supply your PIN twice before using the Signature key: the
first to view the Signature key object, and the second time
because the card requires a PIN just before using the Signature
key.

Therefore, in order to have only 1 PIN login, this pkcs#11 lib
shows info about the private key objects without supplying a PIN.
