@(#)README	1.8 96/11/25

I.   How to run the Java applet securty tests
II.  Examples of attacks - past security bugs (examples directory)
III. JDK 1.0.2 Addendum 


I. How to run the Java applet security tests
____________________________________________

You can either use the supplied Makefile, or run the tests by hand,
whichever is easier.     



To run the tests using the supplied Makefile, 

1.  Modify the Makefile to suit your test environment.  You will want
    to set the five macros BIN, INSTALL, DESTDIR, URL and TMP, which
    are described in the Makefile. 

2.  Just type make!     If you've run the tests before, first 
	"make clobber" and then "make" 

3.  Examine the log file which by default ends up in /tmp/log. 
    grep for FAILED, and grep for "SecurityTest done"
    You shouldn't see any FAILED messages, and you should see
    "SecurityTest done (all tests passed)"

4.  Quit the appletviewer manually





To run the tests by hand, 

1.  Compile the tests

	% cd <test_source_directory>
	% javac *.java 
	% javac java/io/java.* 
	% javac java/net/java.*

2.  Install the tests, and .html file, in your ~/public_html area 

	% cd <test_source_directory>
	% cp *.class ~/public_html
	% mkdir -p ~/public_html/java/{io,net}
	% cp java/io/*.class ~/public_html/java/io
	% cp java/net/*.class ~/public_html/java/net
	% cp securityTest.html ~/public_html

3.  (Optional) Customize the <param>s for the tests that use resources on the
network.  There are three:

imageURL 	 	This should be a simple image
audioURL 		This should be a simple audio file
illegalRedirectURL 	This should be a redirect of an image to a host
			from which the applet is not allowed to connect.

		
4.  Invoke the appletviewer on the securityTest.html URL, but
    don't run the tests from the same directory as the 
    classes have just been installed in. 

	% cd /tmp
	% appletviewer http://yourserver/~yourUserID/securityTest.html >& /tmp/log

5.  Examine log file

	% grep FAILED /tmp/log

   There should be no FAILED messages.   The log file should say

	   ** SecurityTest done (all tests passed) **		


6.  Kill the appletviewer

    You need to quit the appletviewer manually, since applets aren't
    allowed to invoke System.exit() on either the appletviewer or
    on the browser.   This is a feature, not a bug...





In addition to the above tests, there is one test that needs to be run
manually.

Run the trustProxyTest by hand. Do the following:
   1. Make sure that the trustProxy property is NOT set in the
      properties file. (for appletviewer/hotjava this is
     ~/.hotjava/properties)

   2. Make sure that the system property 'proxyHost' is set to point
      to the internal proxy server.

   3. Access an applet outside of the firewall by doing the following:
      > java -DtrustProxy=true sun.applet.AppletViewer 
	     http://java.sun.com/applets/applets/SortDemo/example1.html

	This should cause appletviewer to load the applet. Clicking on
	each of the three sort graphs will cause appletviewer to bring
	over the necessary classes and run them.

   4. Now run the same applet with a different 'trustProxy' value:
      > java -DtrustProxy=false sun.applet.AppletViewer 
	     http://java.sun.com/applets/applets/SortDemo/example1.html

	This should cause appletviewer to load the applet. However
	clicking on any of the three sort graphs will cause a
	sun.applet.AppletSecurityException to be thrown



If you run into problems, 

1.  Is . on your CLASSPATH?  DOT (current working directory) needs to
be on your CLASSPATH in order for the modifed java/io and java/net classes
to be used as part of the test. 

2.  Are you running the test from a directory other than the directory
that the test classes are in?    Be sure to do that. 

3.  Do you have JAVA_HOME set?  If you have JAVA_HOME set to a Java
development area that isn't in sync with the area that you're trying
to test, this can lead to error messages like "ld.so.1: the_mtoolkit:
referenced not found"

4. Is the system property 'trustProxy' set to anything in
~UserID/.hotjava/properties file?

5. Is proxyHost set to point to the local proxy server?





Description of Java applet security tests
_________________________________________

The test harness is implemented by SecurityTestApplet.java,
SecurityTest.java, and securityTest.html.  Each of the security tests
described below is invoked by the test harness.  The security tests
each attempt to break some aspect of Java security or applet security.
If a test generates a SecurityException, then security held up in the
face of that test's challenge, and the test PASSES.  If a test doesn't
generate the expected SecurityException, then security is breached,
and the test FAILED.

AddProviderTest
_______________

Untrusted applets may not add a security provider to the runtime. This
test defines a bogus provider, then attempts to add that provider to
the runtime using the Security.addProvider(Provider) method.

ClassLoaderTest
_______________

Applets are loaded by the applet class loader,
sun.applet.AppletClassLoader, which extends the Java ClassLoader.
Applets may not extend or override the prevailing ClassLoader, and any
attempt to do so raises the SecurityException.  The reason for this is
apparent; if an applet can define its own policies for loading
classes, then it can effectively redefine the entire security policy
of the browser.

ClipboardAccessTest (JDK 1.1)
_____________________________

Assertion: downloaded applets cannot acquire a handle on the AWT
toolkit's clipboard.  Any attempt to access the clipboard should raise
a security exception.

EventQueueAccessTest (JDK 1.1)
_______________________________

Assertion: downloaded applets cannot acquire a handle on the AWT
toolkit's event queue.  Any attempt to access the event queue should
raise a security exception.

ExecTest
________

The "exec test" tries to use an applet as an agent for executing a
unix shell command on the underlying runtime system.  In this case,
the applet tries to run the command "ls", which if it succeeded, would
reveal the contents of the current working directory to the applet.
Applets are simply not allowed to execute any process like this on the
underlying runtime system, and so this test raises SecurityException.
The command exec("ls") fails when the "ls" command is passed to exec
directly, as well as when the "ls" command is stored in an array that
is then passed to exec.

ExitTest
________

An applet may not kill its parent browser or its parent appletviewer.
It could try to do that by invoking the exit() system call.  This test
checks to make sure that instead of being allowed to invoke exit(),
this raises the SecurityException.


FactoryTest
___________

FactoryTest tries to establish a new factory for socket
implementations.  Sockets are used as communication channels by
processes on networked computers.

The socket factory is used by the socket class to create new
implementations of sockets.  The socket classes are designed this way
so that you can change socket implementations via the factory
depending on the security policies you need.

In Java, the socket class implementation defines which aspects of
sockets can be read and written by the user of the socket class.  The
socket class thus defines some aspects of its own security policy.
For this reason, it's important to ensure that the system
implementation of sockets can not be overridden by an applet.  In
fact, until we are certain that the system implementation of sockets
is secure enough that an applet using a socket cannot breach security,
applets running in the Netscape2.0 beta browser may not even use
sockets (let alone redefine the socket implementation.)  Netscape is
planning to loosen this restriction with time, when we are satisfied
we have adequately tested and secured the underlying socket class
implementation.

In FactoryTest, the applet tries to provide its own implementation of
the SocketImplFactory, and use it to override socket functions like
"create", "bind" and "listen."  The JDK-beta appletviewer raises a
SecurityException.   The Netscape 2.0beta2 Navigator does not raise
a SecurityException; probably it should. 



FileTest
________

An applet is constrained from reading files unless

	* the access control list for reading files is null
	* the file is explicitly named on the access control list
	* the file lives in the same directory as an applet that
		was loaded from a file: URL

Attempting to read any other file raises a SecurityException. 

The same policies hold for writing files.   

FileTest checks to make sure that any of these actions raises a
SecurityException, for a file not on the access control list: 

	* checking for the existence of the file
	* reading the file 
	* writing the file 
	* checking the file type
	* checking if the file is a directory
	* checking the timestamp when the file was last modified
	* checking the file's size
	* creating a directory 
	* renaming the file
	* listing the files in this file (as if it were a directory)

FileTest also checks that an applet cannot

	* create a FileInputStream 
	* create a RandomAccessFile, either for reading or writing


GetenvTest
__________

Alpha3 Java included the method System.getenv(string s) which is
discontinued and obsolete.  This test just makes sure that in fact an
applet cannot read environment variables from the user's system, using
the System.getenv method.

getLocalHostTest
________________

This is a test to fix the problem of untrusted applets getting to know
the hostname/IP address of a machine behind the firewall by running the
InetAddress.getLocalHost() method. In JDK1.0.2 this was fixed by having
getLocalHost() method return 'localhost/127.0.0.1' to any applet loaded
over the net. For locally loaded applets, the method will return the
proper 'hostname/IPaddress' pair.


These two methods are new to JDK1.1.  The intent is to allow
downloaded applets to access java classes that have been installed as
part of the trusted local system, via CLASSPATH.  

Applets may not use the getResource* methods to
	alter the contents of a .class file
	remove a .class file
	replace a .class file


GetResourceTest (JDK 1.1)
_________________________

Assertion: an applet should not be able to bypass the restrictions on
reading/writing a file on the client side by using
java.Class.getResource*.   The two methods new to JDK1.1 are

 	java.Class.getResourceAsStream(String name)
 	java.Class.getResourceAsName(String name)

As of Nov 96, only the JavaBeans Development Kit and the JavaBeans
spec depends on these new features.  The intent is to allow downloaded
applets to access data that are used by classes that the applet may
access.  The getResource method allows a downloaded applet to access a
"system resource" (== any java class that is part of the system or
accessible via CLASSPATH) but it does not allow it access to any other
file.  The path/filename check is performed in native code.  Data that
a downloaded applet might want to access include

	images (for icons, animation, whatever)
	audio (for audioclips)
	localization strings
	help data

The security test is:
      Try to read/write a file using these new methods
      Make sure this raises a security exception, or, that
	the system returns NULL as the handle to the resource.
      If it raises a security exception, or the resource handle
	is NULL, the test passes


ImageTest
__________

Assertion: a downloaded applet cannot get an image from any host other
than the server that hosts the applet.

The test tries to get an image from a 3rd host, using each of the many
different ways to get an image.

  1 - use Applet.getImage(URL httpname)
  2 - use Applet.getImage(URL filename)
  3 - use sun.awt.Image.URLImageSource.createImage(String http_protocol)
  4 - use sun.awt.Image.FileImageSource.createImage(String file_protocol)
  5 - use sun.awt.Image.URLImageSource.createImage(URL url)
  6 - use sun.awt.Image.FileImageSource.createImage(String file_name)

Each attempt to load an image should raise a security exception. 

NetworkTest
___________

At present, applets are not allowed to open sockets to arbitrary
machines on the network.  An attempt to establish a socket connection
raises the SecurityException.  NetworkTest tries to open a socket
connection, and it also tries to get the internet address of a host on
the internet.  Both tests are expected to raise the SecurityException.

OverflowTest
____________

OverflowTest is a collection of miscellaneous test that attempt to 
stress system limits.   

   1.  Try to overflow the stack by calling a method repeatedly.
       A stack overflow should happen, rather than the program crashing.

   2.  Try to overflow the stack by tripping over an exception.
       A stack overflow should happen, rather than the program crashing.
   
   3.  Try to build a string that is too big for the runtime.
       An out of memory error should happen, rather than the program crashing.
 
   4.  Try to crash AWT by asking it to paint that huge string
       See bugid 1225156 which is fixed in JDK-beta. 
       AWT just draws the string silently.  No error or exception
       is expected.   If AWT generates a large number of XErrors, that
       should be investigated. 

For each of the first 3 tests, if the expected exception is raised,
then OverflowTest throws a SecurityException, to indicate that the
security test is passed. 
 

PackageDefineTest
_________________

PackageDefineTest attempts to define a new class in the java.net
hierarchy.  This is not allowed, an it should raise SecurityException.
If (as expected) the applet cannot define a new java.net class, then
this test's attempt to load that class raises the "NoClassDefFound"
error.

PackageImportTest
_________________

Make sure that applets cannot instantiate classes in sun.* [Note: it
would be better if we could implement a security policy that could
ensure that applets cannot instantiate classes in a class hierarchy
that is specified by the provider of that class hierarchy.  For
example, The vendor named "vendor" might want to disallow instantition
in vendor.foo.bar, but allow it in vendor.foo.clue.]

Patricide (JDK 1.1)
___________________

Assertion: downloaded applets may not examine or change the state of
its grandparents.  Downloaded applets are allowed to get a handle on
their parent, but not on their grandparent.  Attempting to do so
should raise a security exception.  This is an open bug against
HotJava as of Nov 1996.

What we want to avoid is the situation where people go up the
containment hierarchy and change the menus in a browser from an
applet.  They probably can't do anything much aside from change the
names, since any event handling for new menu items will still be
subject to security manager restrictions, but we think we should
prevent applets from crawling up the AWT ancestor tree.

PropertiesTest
______________

Make sure that applets cannot read system properties.  System
properties are:

     java.version	Java version number
     java.vendor	Java vendor specific string
     java.vendor.url	Java vendor URL
     java.home		Java installation directory
     java.class.version	Java class version number
     java.class.path	Java classpath
     os.name		Operating System Name
     os.arch		Operating System Architecture
     os.version		Operating System Version
     file.separator	File separator ("/" on Unix)
     path.separator	Path separator (":" on Unix)
     line.separator	Line separator ("\n" on Unix)
     user.name		User account name
     user.home		User home directory
     user.dir		User's current working directory


RemoveProviderTest
_______________

Untrusted applets may not remove a security provider to the
runtime. This test attempts to remove the default provider, "SUN".,
using the Security.removeProvider(Provider) method.


SecurityExceptionTest
_____________________

Make sure than an applet cannot instantiate a class in the sun.applet
hierarchy.  Specifically, make sure it cannot instantitate the
AppletSecurityException class (since if an applet could override the
applet security exceptions, it could wreak havoc with any parts of the system
that relied on being able to catch SecurityException.) 


SecurityManagerTest
___________________

Make sure that an applet cannot set the SecurityManager.   If it could,
it could redefine the entire security policy and have its way with the
platform that it runs on. 


SetIdentityScopeTest
____________________

Applets may not set the system's identity scope. This method defines 
a bogus scope (EvilScope), instantiate it and tries to set it using
the IdentityScope.setSystemScope(IdentityScope) method.


ThreadGroupTest
_______________

An applet cannot manipulate threads outside the applet thread group,
and it cannot manipulate other thread groups, either.  ThreadGroupTest
makes sure a SecurityException is raised when an applet tries to start
a new thread outside of its group.

URLTest
_______

Applets cannot open a URL connection to some arbitrary host on the
internet.  URLTest tries to open a socket to http://netcom.com, and
checks that SecurityException is raised.

WindowTest
__________

Applets cannot create ordinary toplevel windows on the client. Any
windows created by the applet will have a telltale RED BANNER BAR
across the top of the window, as a warning to the user that this
window was created by an applet.  WindowTest creates two windows, a
FRAME and a DIALOG, and each should display with a red banner bar
across the top.


VerifierTest
____________

VerifierTest tries to create a new object for special methods used by
the Verifier: FinalCheck, FinalMethodCheck, PrivateCheck and
PrivateStaticCheck.  Trying to create an instance of any of these
classes should raise an error.  If for some reason VerifierTest
succeeds in creating one of these objects, then SecurityException is
raised.



II. Examples of attacks - Past Security Bugs (examples directory)
_________________________________________________________________

This is the examples directory. It contains example of attacks which are
not readily adapted in the regular test suite but which are intended to
help testing engineers design test for potential security holes. It
contains examples of past security bugs, as well as examples on how
sensitive functionality is handled in the existing system.

It has its own README file.



III. JDK 1.0.2 Addendum
________________________

The security suite has some new tests for bugs fixed in
JDK1.0.2. The following are two bug fixes introduces among
others. The two tests validate the behavior of these two
fixes. Additional tests for the other fixes in JDK1.0.2 are
in development. Since security tests require a lot of special
setup in general, the test harness herein is not powerful
enough to handle such requirements. The harness is being reworked
in a major way to make it more flexible. Future releases will have
more up-to-date tests as well as a more powerful test harness.

The security bugs fixed/enhancements (among others) in JDK1.0.2 are:

1. addition of a boolean valued trustProxy system property to
   appletviewer and hotjava to handle cases where the loaded
   applet (originating from a remote machine whose IP address
   is unavailable locally) needs to establish connection back
   to the host from which it originated. Setting the trustProxy
   to false labels the proxy server as untrusted and will disallow
   the communication back to the host.

2. InetAddress.getLocalHost() now returns localhost/127.0.0.1
   if the applet is loaded over the net. It will correctly
   return the hostname and IP address of the local machine if
   the applet originates locally.


