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

Version: 1.4
Date: 01/09/2004

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
- Mac OS X


Installation on Mac OS X
========================

Note: before you can use this middleware, a PC/SC smart card reader should 
be installed. See http://www.linuxnet.com/middle.html for some PC/SC drivers.
See the reader vendors' installation guide for info on how to do this.

1. To install this middleware, open a Terminal window.
To do this, open Finder, then click on Applications, click on
Utilities and then double-click on Terminal.

2. In the Terminal window: go to the installation directory,
this is the same directory where this readme file is.
(For example, to go to the Desktop directory, type in "cd Desktop".)
In the installation directory should be a file "install.sh".
(You can get the file listing of a directory by typing in "ls".)

3. Run the install.sh file as root (administrator).
To 'log in' as root: type in "sudo /bin/bash" and
enter the root password.
To run the install.sh file: type in "./install.sh".

4. Test (in the Terminal window)
First, you must start the pcsc service if you haven't done so
already by typing in "pcscd" as root.
- To test if the reader has been installed correctly, run
    /usr/local/bin/belpic-tool -l
  This should list all the available readers
- To test if the Belgium EID card works with the reader, insert
  your EID card in the reader and run:
   /usr/local/bin/belpic-tool -a
  This should give the ATR of the EID card
- To test the middelware, insert the EID card and run:
   /usr/local/bin/belpic-pkcs11-tool -t -l
  You will be asked to enter your PIN 3 times: the first time
  in the Terminal window, the other 2 times in a PIN dialog
  (which may be hidden behind the Terminal window).
  After that, press "x" twice to stop.

To change your PIN, use the command:
     /usr/local/bin/belpic-pkcs11-tool -c


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

To install:
  Open Mozilla, and type in
     file:///Users/
  in the URL bar.
  Then go to the file pkcs11_install_netsc_moz.htm

  Open Mozilla, and type in
     file:///Users/
  in the URL bar.
  Then go to the file pkcs11_uninstall_netsc_moz.htm

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


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.
