README
------

This package provides a number of plugins for handling GDM PAM prompts. 

These plugins are called when a username or password/PIN are required in GDM 
for authentication. Typically the plugin will wait for a external event (such 
as inserting or removing a smartcard) and return an empty username/password 
back to GDM.

Plugins are installed into the /usr/lib/gdm/plugins directory.

Note that a specially-modified version of GDM is required to load and handle 
any prompt plugins. 

TODO specify where to download modified GDM
 

1. PKCS#11 Plugin
-----------------

Provides     : /usr/lib/gdm/plugins/libpromptpkcs11.so
Configuration: /etc/gdm/plugins/pkcs11.conf

This plugin monitors PKCS#11 events. A PKCS#11 event includes token inserted
into a slot, and token removde from a slot.

If the prompt is PAM_PROMPT_ECHO_ON, then the plugin will wait until a token
has been inserted. It will then return an empty string. Typically, this will
represent an empty username.

If the prompt is PAM_PROMPT_ECHO_OFF, then the plugin will wait until a token 
has been removed. It will then return an empty string. Typically, this will
represent an empty PIN.

The configuration file /etc/gdm/plugins/pkcs11.conf must be modified so 
that the location of the PKCS#11 library is specified. See the comments in
the configuration file for further details.

It is recommended that the PKCS#11 plugin should be used if the application
that calls GDM (typically, a PAM module) is also making PKCS#11 calls. 

2. PC/SC Plugin
---------------

Provides     : /usr/lib/gdm/plugins/libpromptpcsc.so
Configuration: /etc/gdm/plugins/pcsc.conf

This plugin monitors PC/SC events. A PC/SC event includes card inserted into
a reader, and card removed from a reader. The PC/SC plugin may be used for
recognizing lower-level events than the PKCS#11 plugin, and may (for some
implementations) be faster. However, the PKCS#11 plugin is recommended.

If the prompt is PAM_PROMPT_ECHO_ON, then the plugin will wait until a card
has been inserted into a reader. It will then return an empty string. 
Typically, this will represent an empty username.

If the prompt is PAM_PROMPT_ECHO_OFF, then the plugin will wait until a card
has been removed from a reader. It will then return an empty string. Typically,
this will represent an empty PIN.

The configuration file /etc/gdm/plugins/pcsc.conf must be modified so 
that the location of the PC/SC library is specified. See the comments in
the configuration file for further details.

It is recommended that the PC/SC plugin should be used if the application that
calls GDM (typically, a PAM module) is also making PC/SC calls. If the
application uses a PKCS#11 library that relies on a PC/SC daemon, then PC/SC
events may be communicated back to the application before the underlying 
PKCS#11 library receives notification of these events. This may lead to 
inconsistencies between the application and the PKCS#11 library.


Installation
------------

Add the following option in the [greeter] section of the GDM configuration 
file:

  PromptPlugin=<plugin.so>

where <plugin.so> is the location of the PKCS#11 prompt plugin or the PC/SC
prompt plugin.  

GDM may need to be restarted.