This is a brief set of notes about the PAM-CLIENT library.
----------------------------------------------------------

This library is an attempt to provide an API for pluggable client-side
authentication to complement the PAM-API.

The development and success of PAM has lead to the need to build extra
flexibility into clients for flexible authentication mechanisms.  This
library is an attempt to address that need.

<** WARNING **>
Do not use the pam_testing.so module for anything other than testing
in a secured environment.  This module offers ABSOLUTELY NO SECURITY
WHATSOEVER so use with care!!
</** WARNING **>

Functions:
=========


extern pamc_handle_t pamc_set_path(const char *path)
.................................................

  This function is used to initiate the PAM-CLIENT library.  For the
moment, 'path' needs to be NULL, and the function returns a
'pamc_handle_t' handle.

[  Eventually, the 'path' will be of the form "dir1:dir2:...", and will
indicate where to look for client authentication agents like the $PATH
variable.  ]



extern int pamc_end(pamc_handle_t *pch)
.......................................

  This function is used to terminate the PAM-CLIENT library.  The
argument is a pointer to a valid pamc_handle_t.  Upon return, the 
pamc_handle_t is set to NULL.  The return value of the function
instructs the client of an impression of whether the server is to be
trusted.  Currently, there are two states: PAMC_CONTROL_OK (server
seemed to correctly interact with the agents) and PAMC_CONTROL_BUSY
(server and agents have disagreed on the correct execution of their
protocol and one or more agents have not completed).  This latter case
makes trusting the server risky to say the least....



extern int pamc_set_agent(pamc_handle_t pch, const char *agent_id)
..................................................................

[This function is not necessarily needed.  My current thoughts are
that this might be used by the client to demand that an agent be
satisfied during an authentication exchange.  Otherwise, it will be
demoted to being an internal function of the library.]

  This function is used to set (and load) the current agent which is
recorded in the 'pamc_handle_t'.  The function returns PAMC_CONTROL_OK
if the agent is found and PAMC_CONTROL_FAIL otherwise.



extern void pamc_delete_packet(pamc_packet_t *datum_pp)
.......................................................

  This function is used to liberate the memory associated with a data
packet.



extern void pamc_new_packet(pamc_packet_t *datum_pp, int length)
................................................................

  This function is used to create a new data (exchange) packet that
can hold data of specified 'length'.



extern int pamc_exch_packet(pamc_handle_t pch, unsigned int control,
			    pamc_packet_t *datum_pp)
.....................................................................

  This function is used to submit a packet to and receive a packet
from an agent.

If the control is PAMC_CONTROL_SELECT, the action of this function is
to load the agent named in the full length of the packet.  Note, that
the packet is not expected to be <NUL> terminated.  When the agent is
loaded, the first packet of data passed to it is automatically the
same packet as was used to identify the agent.  In this way, the agent
is given the opportunity to check that it has been invoked correctly.



void pamc_scrub(void **data, int length)
........................................

  This function overwrites 'length' bytes of '*data' and then sets
'*data' to NULL.



int pamc_push_data(int fd, const void *data, int length)
........................................................

  This function forces (looping until complete) 'length' bytes from
'data' into file descriptor 'fd'.  On success, PAMC_CONTROL_OK is
returned, on failure PAMC_CONTROL_ABORT is returned.



int pamc_pull_data(int fd, void *data, int length)
..................................................

  This function draws (looping until complete) 'length' bytes from
'fd' into the buffer 'data'.  On success, PAMC_CONTROL_OK is
returned, on failure PAMC_CONTROL_ABORT is returned.



int pamc_silent_fd(int fd)
..........................

  This function returns PAMC_CONTROL_OK if there is no data waiting to
be read from 'fd' and PAMC_CONTROL_FAIL if there is data waiting.


Notes:
=====

  This library is designed to be simple.  No policy is stated about
what authentication schemes are to be supported.  It is hoped that the
lack of definitions is a strength and not a weakness.

This library is actually intended to be "stealthfully" compatible with
the X/Open implementation of libpam (Solaris 2.6).  All you need is is
to support it in your application and your modules.  Libpam shouldn't
need to care about it.

Future:
======

  This library may need to evolve.  Email me if you think it needs
something added!

Andrew G. Morgan <morgan@linux.kernel.org>
