This subdirectory contains source c files, header files, a makefile, and other
files that can be used in creating user exit functions callable from
pre-determined points during the execution of the aproxy.  Example c source
files are also provided in this subdirectory to help illustrate how user
code can be incorporated into aproxy.

Performing a make in this subdirectory with the provided Makefile should
result in two library files - libuser_exits.a and libexits.a.  Since some
operating systems prefer to work with .so files rather than .a, a .so
alias will be created by the Makefile for each of these two libraries.


Contents of this subdirectory

Files that are required AND should not be changed by the user:

user_exits.exp	AIX export file for use in building libuser_exits.a.
		This file is required only on AIX.

user_exits.h	header file the user will have to include in his exit
		function.  It contains structures and defines used by
		the aproxy user exit interface.  It also describes the
		prototype of each of the user exits.

Files that should be modified by the user:

user_exits.c	This defines an extern table whose entries represent sets
		of user exit functions.  Each entry is identified by a
		string of characters assocaited with a permit statement.
		The user should add his exit functions to one or more
		entries in this table.  The entries for the example code
		can be removed if not needed.

Output from the make:

libuser.a	A user provided library that contains the user exit functions.
		A libuser.a is supplied with aproxy and contains example
		user exit functions.

libuser_exits.a	contains the object from user_exits.c.  It references
		libuser.a for all the user exit functions.  The only exported
		symbol in the libraray is the u_exits table which is
		referenced by aproxy to indirectly call the user provided
		functions.

Example exit functions:

addcrlf.c	Example user exit function that scans the input buffer and
		replaces all occurences of '\n' with '\r\n'.

rmcrlf.c	Example user exit function that scans the input and strips
		all occurences of '\r'.

auth.c		Example user exit that simulates an authentication sequence.

Other example files.  These files can be used to drive and test the example
user exits.  They act as client and server code to be placed on different
sides of the firewall running aproxy:

serverget.c	Example program that pairs with clientput.c to transfer a
		file from the client to the server.

clientput.c	Example program that pairs with serverget.c to transfer a
		file from the client to the server.

serverput.c	Example program that pairs with clientget.c to transfer a
		file from the server to the client.

clientget.c	Example program that pairs with serverput.c to transfer a
		file from the server to the client.

Note that the example programs (clientput.c, serverget.c, clientget.c and
serverput.c) have not been tested on Windows.


There are three exit points provided in aproxy:

1. The Auth exit is called just after aproxy has verified that the client system
   making the connection request is allowed by the permit rules in the config
   file to connect to the requested server.  This call is made before a
   connection request is sent to the requested server.
2. The CtoSBuf exit is called just after aproxy read in a buffer of data from
   the client.  The output from CtoSBuf will be sent to the server.
3. The StoCBuf exit is called just after aproxy read in a buffer of data from
   the server.  The output from StoCBuf will be sent to the client.

To activate a new user exit

1. Write the functions.
2. Add an extern declaration for each function in user_exits.c
3. Add entries in the u_exits table.  Each entry contains:
      id-string that's up to 15 characters long
      pointer to the Auth exit or NULL if none
      pointer to the CtoSBuf exit or NULL if none
      pointer to the StoCBuf exit or NULL if none
4. Modify Makefile to add to and/or remove from the USER_OBJS and USER_SRCS
   macros.
5. Run make in the directory
6. Copy libuser_exits.a (or libuser_exits.so) to /usr/lib or somewhere else
   on the user's LIBPATH or LD_LIBRARY_PATH.  Alternatively, on Linux, the
   directory where libuser_exits.so resides can be added to /etc/ld.so.conf.
   The new directory will be recognized as part of shared library path at the
   next reboot (or the ldconfig command can be used to effect the change
   immediately).
7. Add permit statements in /etc/firewall/aproxy.conf that each contains the
   "userexit" keyword with an exitname that matches an id-string in one
   of the u_exits entries in user_exits.c
