
		Belgian EID PKCS#11 library
		===========================

Version: 1.4
Date: 10/12/2003

This software makes use of the following open source projects:
- OpenSC (see http://www.opensc.org), licence: see the file "COPYING" in this package
- OpenSSL (see http://www.openssl.org), licence: see the file "LICENCE" in this package


Platforms:
- GNU/Linux with glibc v2.2 or v2.3 and PC/SC Lite v1.1.1 or higher


Installation in Mozilla
=======================

To install:
  mozilla pkcs11_install_netsc_moz.htm

To uninstall:
  mozilla pkcs11_uninstall_netsc_moz.htm

(The .htm pages are in the same directory as this readme file.)


How to use the PKCS#11 library
==============================

The PKCS#11 library is located in /usr/local/lib.
There are 2 tools: belpic-tool and belpic-pkcs11-tool. They are located
in /usr/local/bin, see the 'man-pages' for more info.

Before you can use it, a PC/SC smart card reader should have been installed.
See http://www.linuxnet.com/middle.html for some PC/SC drivers.

With the tools, you can check the following:
     belpic-tool -l   		  (to see if a card reader is present and installed)
     belpic-pkcs11-tool -L        (to list the available pkcs11 slots and tokens)
     belpic-pkcs11-tool -0        (to view the pkcs11 objects on the first token)
     belpic-pkcs11-tool -t -l     (to test the pkcs11 library and the Belgiam EID card)

To change your PIN, use the command:
     belpic-pkcs11-tool -c


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

There is an optional configuration file that can be used to e.g.
- set error logging
- set the language of the PIN dialog: see the 'force_language' option

NOTE: some readers require the 'apdu_fix' option to be set to 'true'.
To do this, replace the line
	#apdu_fix = false;
into
	apdu_fix = true;

The config file is /usr/local/etc/belpic.conf.


Some technical notes about this PKCS#11 library
===============================================

1. About the pin dialog

Normally, a PKCS#11 library doesn't ask for PINs because the
appliciation does and then gives the PIN to the pkcs#11 lib
(that will send it to the card).

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 has 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 has to be done.

2. Visibility of private key objects

Most PKCS#11 implementations only show info about the private
key objects after a PIN has been supplied.

For the Belgian EID card, there is no need to do so since
only public information is given.
Therefore, this PKCS#11 lib shows info about the private key
objects without a PIN being supplied first.
