README file for the Jini Filter Project
=======================================

In the JiniFilter_Project you will find several directories and files which 
implement a framework in which one can demonstrate the functionality of the
jinifilter package.

The directories and files are:

JiniFilter_Project\ 	:	top level
jinifilter\		:	implementation of jinifilter
jini\			:	jini-specific interfaces and classes
userapp\		:	an example JINI client app
net\			:	simulated remote network location
net\netserver\		:	small lookup/RMI server
net\jini\		:	copy of '..\net\jini\'
net\lalaland\		:	service proxy implementations
de\			:	copy of the JavaClass library
README.txt		:	this file
makeclient.bat		:	make the jinifilter and client classes
runclient.bat		:	runs both original and modified user app
runmodified.bat		:	runs a JiniFilter-modified user app
runoriginal.bat		:	runs the original user app
DI_notes.txt		:	design and implementation notes
policy.all		:	used to set an 'all permissions' policy  

The jinifilter package can be used with any application which
uses the standard JINI framework to get access and use network services.
One needs to follow a few guidelines in order to be able to use the
jinifilter with the user app.

1. Copy all of your 'Safe*.java' classes correcting the problematic 
	 system classes' behaviour in the 'jinifilter' directory.

2. Modify the 'classnames.txt' and 'methodnames.txt' appropriately
	 so that your files replace the right system files (follow the 
	 example of the already existing files).

3. Install your user JINI-client app in such a way so that you are able to 
	 run it from within the 'JiniFilter_Project' dir. Make sure that 
	 your app uses the 'LookupLocator' and 'ServiceRegistrar' included
	 in the 'jini' package, if you don't have a running lookup server. 
	 These classes are specially tailored to talk to the local 
	 netserver.LookupServer (in the 'net' dir) which pretends to be a remote
	 host. If you have your own lookup server, you should use your own
	 versions of these classes which know how to discover and contact it. 

4. Copy the interfaces of your services to the 'jini' dir. Make sure
	 you've changed their class package to 'jini'. This is needed 
	 only for "fake" services -- if you use a well known interface 
	 (such as net.jini.core.lookup.ServiceRegistrar), you don't need 
	 to worry about this directory.

5. Copy the implementation of your service's proxy (the client side) in 
	 the 'net' directory. Make sure it is accessible from within the 'net'
	 directory (if it's in .class files, make sure that their package 
	 corresponds to their directory name; if it's in a .jar file, make
	 sure its location is specified in the CLASSPATH system variable or 
	 in the -cp option of the java interpreter running the server -- see 
	 the runserver.bat script). The LookupServer runs from the 'net\' 
	 directory, and it will try to access your classes in order to create 
	 a service object to be passed to the JINI client. 
	 If you are going to use your own lookup server, you don't need to 
	 worry about this.


The jinifilter was written in such a way so that it allows transparent
modifications to the already existing app. For example, if you are able
to run the existing app mypackage.MyProgram in the following way:

cd JiniFilter_Project
java -D... mypackage.MyProgram arg1 arg2 ... argn

then, you should be able to run a secure version of it (as implemented
by your 'Safe' classes), by doing:

cd JiniFilter_Project
java -D... -noverify jinifilter.JiniFilter mypackage.MyProgram arg1 arg2 ... argn
 

To run your application, you need to complete a few more steps:

1. Make sure your app has been compiled and is runnable from the top level.

2. Run the 'runserver' script which compiles and runs the LookupServer. 
	 You need to start this script in a separate process.

3. Run the 'makeclient' script to compile the jinifilter package and 
	 helper files.

4. Run 'runclient mypack.MyApp arg1 ... argn' to run both versions (original
	 and modified) of your application. The output is saved in 'out.txt' 
	 and 'err.txt', which are redirections respectively of stdout, and stderr.
 

This should be it.

If you have time and desire, you can look at the design and implemenation
notes included in the package.

If you decide to modify the JiniFilter code, you should be aware of a 
few things:

	* ClassFilter and MethodFilter implement the byte code modification
		(as made possible by the JavaClass libraries). I only used them, so
		don't ask me for any help with their inner workings -- I won't be
		able to help you.
	* SafeClassLoader (~500 lines) is at the core of the code implementing 
		the access to all pertinent bytecode before being defined as a class.
	* SafeURLClassLoader (~140 lines) has the code which, we expect, will
		be run every time a remote class is being loaded.
	* netserver.LookupServer (~200 lines) residing in 'net\', implements
		the Lookup/RMI-combo server which currently offers access to classes
		and dynamically-created objects from these classes.  
	* JiniFilter (~100 lines) implements the transparent wrapper around the
		user app.
	* ServiceRegistrarImpl (~90 lines) and LookupLocator (~60 lines)
		implement toy-versions of the corresponding classes in the JINI
		specs. They are made specially to be able to talk to our
		netserver.LookupServer.


