PCSC/Ada README
===============

This is the README file for the PCSC/Ada library. In this file, you'll find
information on how to compile, test, install the PCSC/Ada library and use the
example applications. For the latest information to PCSC/Ada, visit the website
at http://www.codelabs.ch/pcscada.


Download
--------

Release version
~~~~~~~~~~~~~~~
The current release version of PCSC/Ada is available at
http://www.codelabs.ch/download. The API documentation of the current release
can be found at http://www.codelabs.ch/pcscada/api.

Verify a Release
~~~~~~~~~~~~~~~~
To verify the integrity and authenticity of the distribution tarball, import
the key http://www.codelabs.ch/keys/0x3DC359DEpub.asc and type the following
command:

  $ gpg --verify libpcscada-{version}.tar.bz2.sig

The key fingerprint of the public key ('0x3DC359DE') is:

  Key fingerprint = 752C 4EBC 115D 5EAD 75F7  0F34 A0AE 8AD7 3DC3 59DE

Development version
~~~~~~~~~~~~~~~~~~~
The current development version of PCSC/Ada is available through its git
repository http://git.codelabs.ch/git/pcscada.git. A browsable version of the
repository is also available here: http://git.codelabs.ch/?p=pcscada.git


Build PCSC/Ada
--------------
To compile PCSC/Ada on your system, you need the following libraries/frameworks
installed:

* GNAT (version >= 4.1):
  http://www.gnu.org/software/gnat/gnat.html

* Ahven (Test-Framework, version >= 1.3):
  http://ahven.stronglytyped.org/

* PC/SC development files and libraries:
  e.g. pcsc-lite from http://pcsclite.alioth.debian.org (version >= 1.4.0)

The build process of PCSC/Ada is quite easy and straightforward. Just type in
the following commands:

  $ tar xjf libpcscada-{revision}.tar.bz2
  $ cd libpcscada-{revision}
  $ make

If no errors occur during the build process, you have now successfully built
the PCSC/Ada library from sources.


Testing
-------
Before you install PCSC/Ada on your system, you might want to test the library
and verify that everything works as expected. PCSC/Ada contains both a unit test
suite and an integration test application. To run the unit tests of PCSC/Ada,
just type:

  $ make utests

This will run all Ahven based unit tests. All tests should be marked with *PASS*
behind the test name. To run the integration tests of PCSC/Ada, you need to have
at least one smart card reader and one smart card ready. Type the following
command to run the integration tests:

  $ make itests

This will run an Ada implementation of the pcsc-lite `testpcsc` binary used to
test the pcsc-lite framework. If no exception arises, you should be good to go.
If you really want make sure everything is alright, compare the output of
`make itests` with the output when running `testpcsc` for a given card / reader
combination.


Installation
------------
To install PCSC/Ada on your system, type the following:

  $ make PREFIX=/usr/local install

You must be `root` to install the library system wide. If no `PREFIX` is
specified, `$(HOME)/libraries` is used as install destination.


Examples
--------
PCSC/Ada provides some example code to demonstrate the usage of the PCSC/Ada
API. To build all example apps, type the following:

  $ make examples

You can start an example application like so: `obj/examples/pinpad`

examples/cardd
~~~~~~~~~~~~~~
This example application is a simple implementation of a reader monitor using
the `Reader_Monitor` task provided by PCSC/Ada. After startup, `cardd` will
observe all smart card readers of a system for status changes (e.g. card
inserted, card removed). It will print out information if states of readers
change.

examples/pinvery/pinpad
~~~~~~~~~~~~~~~~~~~~~~~
This small application will perform a SPE (secure pin entry) operation with
a given card / reader. It will first check if the reader supports this operation
and will exit if not. If it does support SPE, the user is asked to enter the PIN
of a given smart card by using the pinpad of the smart card reader. The result
of the operation is displayed after completion.

examples/thin
~~~~~~~~~~~~~
The thin_example binary (`obj/examples/thin_example`) can be used to test the
thin binding of PCSC/Ada. You need to adopt the reader name `Reader_Name` in
`examples/thin/thin_example.adb` to make this test app work.
