You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by jc...@apache.org on 2009/09/27 02:15:08 UTC
svn commit: r819236 [4/6] - in /incubator/river/jtsk/trunk: ./ examples/
examples/hello/ examples/hello/config/ examples/hello/config/META-INF/
examples/hello/prebuiltkeys/ examples/hello/scripts/ examples/hello/src/
examples/hello/src/com/ examples/he...
Added: incubator/river/jtsk/trunk/examples/hello/index.html
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/trunk/examples/hello/index.html?rev=819236&view=auto
==============================================================================
--- incubator/river/jtsk/trunk/examples/hello/index.html (added)
+++ incubator/river/jtsk/trunk/examples/hello/index.html Sun Sep 27 00:15:03 2009
@@ -0,0 +1,2248 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing, software
+ ! distributed under the License is distributed on an "AS IS" BASIS,
+ ! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ! See the License for the specific language governing permissions and
+ ! limitations under the License.
+ !-->
+
+<html>
+<head>
+<title>Hello Example</title>
+</head>
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc" vlink="#cc1877"
+ alink="#ffffff">
+
+<h1>Hello Example</h1>
+
+<h2>Introduction</h2>
+<p>
+The Hello example was created to illustrate how a typical Jini
+technology-based application can be configured and optionally secured
+using the configuration and Jini extensible remote invocation (Jini ERI)
+facilities that arrived in version 2.0 of the Jini Technology Starter Kit
+. The components built from the files making up this example
+are a <i>server</i> component that implements a <code>Hello</code>
+interface with a <code>sayHello()</code> method, and a <i>client</i>
+component that employs a <i>lookup service</i> to obtain a reference to
+the server through which the client invokes the <code>sayHello()</code>
+method.
+<p>
+One of the primary purposes of this example is to demonstrate how an
+application can be written in such a way that it needs to be built
+only once, but can be run to use various communication protocols and
+security policies by merely deploying under different configurations
+<i>without having to change a single line of Java(TM) programming
+language source code</i>! Thus, although there is only a single example
+presented in this document, there are a number of scenarios under
+which this example can be run. The first part of this document
+provides instructions for <a href="#quick-start">getting started quickly</a>,
+and the second part provides <a href="#deeper">more detailed descriptions</a>
+of each scenario.
+<p>
+The combinations of ways in which the components of this simple
+example can be configured are derived from options like the following:
+
+<ul>
+ <li>Secure or non-secure?</li>
+ <li>Activatable or non-activatable?</li>
+ <li>If non-secure then using JRMP or Jini ERI?</li>
+ <li>If secure then secured through an SSL provider or a Kerberos provider?</li>
+ <li>If non-secure and activatable then using a JRMP-configured Phoenix or
+ using a Jini ERI-configured Phoenix?</li>
+ <li>Does it use a customized invocation handler?</li>
+ <li>etc.</li>
+</ul>
+
+When run under any of the configurations provided in this example,
+the application simply says, "Hello, world!".
+<p>
+This example also demonstrates the use of the
+<a href="../../../../../../../doc/specs/api/net/jini/config/Configuration.html"><code>Configuration</code></a>,
+<a href="../../../../../../../doc/specs/api/net/jini/export/Exporter.html"><code>Exporter</code></a>,
+and
+<a href="../../../../../../../doc/specs/api/net/jini/security/ProxyPreparer.html"><code>ProxyPreparer</code></a>
+interfaces to configure the client, server, lookup service, and
+activation system
+(<a href="../../../../../../../doc/api/com/sun/jini/phoenix/package-summary.html"><i>Phoenix</i></a>)
+for the desired remote communication and security. Additionally,
+references to the source files for the application as well as the
+various configuration and policy files that can be used to run the
+application in different ways are also presented.
+<p>
+To aid in working with the example, this page is divided into the
+following sections:
+
+<ul>
+ <li><a href="#setup">Setup</a></li>
+ <li><a href="#quick-start">Quick Start</a></li>
+ <li><a href="#changes">Making Changes</a></li>
+ <li><a href="#troubleshooting">Troubleshooting</a></li>
+ <li><a href="#deeper">Looking Deeper</a></li>
+</ul>
+
+Although running the example under the secure configurations requires
+a little bit of one-time <a href="#setup">setup</a>, you should be able
+to run each of the non-secure configurations "out of the box", with
+no setup at all. For those who wish to jump right in, the
+<a href="#quick-start">quick start</a> section presents the basic
+steps necessary to run the example under each of the possible
+configurations without a lot of additional explanation. That section
+also contains a convenient <a href="#config-table">table</a> that
+presents the various scripts one can use to run the example. In that
+table, the scripts are organized in a fashion that is intended to
+make it obvious which scripts should be executed for a particular
+configuration.
+<p>
+If, after acquiring some experience with running the example, you would
+like to experiment with modifying the example's source code, the section
+on <a href="#changes">making changes</a></li> presents a set of steps
+that can be followed to rebuild the example to include those changes.
+Should problems be encountered while running the example, a small of
+set of <a href="#troubleshooting">troubleshooting tips</a> are presented
+that may be helpful in diagnosing and solving some of the more common
+problems.
+Finally, for those who desire a deeper understanding and are looking
+for a starting point for designing and configuring applications, the
+contents of the source code, configuration files, and policy files
+employed in this example can be explored by accessing the references
+contained in the section that takes a <a href="#deeper">deeper look</a>.
+<p>
+<hr>
+
+<a name="setup">
+<h2>Setup (Secure Configurations Only)</h2>
+</a>
+
+To run this example under the secure configurations that are provided,
+one can choose to use either the
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jsse/JSSERefGuide.html#SSLOverview">Secure Sockets Layer Protocol (SSL)</a>
+as provided by the
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jsse/JSSERefGuide.html">Java Secure Socket Extension (JSSE)</a>,
+or the Kerberos provider through the
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jgss/tutorials">Java GSS-API</a>.
+Additionally, when run under any of the secure configurations, this
+example exploits the
+<a href="../../../../../../../doc/specs/api/net/jini/security/policy/DynamicPolicyProvider.html">dynamic permission granting</a>
+features of the
+<a href="../../../../../../../doc/specs/api/net/jini/security/policy/package-summary.html">security policy provider</a>
+included in the Apache River release.
+
+<h4>SSL setup</h4>
+
+No setup is necessary to run this example when configured to use
+SSL through JSSE. This is because the example comes with a set of
+pre-generated private keystores with associated passwords and
+self-signed public key certificates (<i>certificates</i>), as
+well as a public keystore (<i>truststore</i>) that contains the
+certificate from each of the private keystores. Whereas each
+keystore is intended to represent private information associated
+with a particular component of the example, the truststore file
+that aggregates all of the public key certificates is treated as
+public information, shared by each component. Using this
+pre-generated data, the various SSL configurations can be run
+out of the box, with no setup required.
+<p>
+Please note that the keystores, truststore, and associated
+certificates are provided only for convenience. Using those
+items in anything but an example environment could pose a
+security risk because all parties who obtain this example have
+access to the same information; in particular, the same set of
+pre-generated private keys and passwords. To address any concerns
+one might have regarding this situation, the pre-generated
+keystores, password files, and truststore can be replaced with
+new versions in which the old private keys and passwords are
+replaced with different values that you supply, and the
+associated certificates are replaced with new certificates that
+are either self-signed or are signed by a valid certificate
+authority (<i>CA</i>). To generate your own private keys, as well
+as to create your own self-signed certificates, you can use the
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jsse/JSSERefGuide.html#CreateKeystore">keytool</a>
+provided in the JDK(TM) software.
+
+<h4>Kerberos setup</h4>
+
+Unlike the SSL configurations that are provided, some setup must be
+performed to run this example under the configurations that use
+Kerberos through the Java GSS-API.
+<p>
+A Kerberos environment typically includes not only the clients
+and servers wishing to securely communicate with each other, but
+also an authentication server referred to as a <i>Key Distribution Center</i>,
+or <i>KDC</i>. The KDC runs on a <i>KDC host</i> and belongs to a
+<i>realm</i>. Each client and server - referred to as <i>Kerberos servers</i>
+for the purposes of this discussion - is associated with a
+Kerberos principal name as well as a
+<a href="http://java.sun.com/j2se/1.4/docs/api/javax/security/auth/kerberos/KerberosKey.html">key</a>.
+Using its principal name, each Keberos server retrieves its
+associated key from a <i>keytab</i> file and uses that key to request
+the services of the authentication server running on the KDC host.
+This example assumes that either a new or pre-existing authentication
+server, with the appropriate principal names, is operational in
+the environment in which the example runs.
+<p>
+In addition to an authentication server, the following steps must
+be taken to set up this example to run under the configurations that
+use Kerberos:
+
+<ul>
+ <li>In the example's <code>config</code> directory, create a
+ keytab file named <code>krb-servers.keytab</code> that
+ contains the keys associated with each principal name
+ registered in the authentication server for this example.
+ </li>
+ <li>In the example's <code>scripts</code> directory, edit the file
+ </code>krb-setenv.sh</code> (or </code>krb-setenv.bat</code>
+ if on Windows). Set the realm name, the KDC host name, and each
+ principal name to the appropriate values. (Note that if any
+ of the environment variables being set in the script have
+ already been defined in the environment, the current values
+ of those variables override the values being specified in the
+ script.)
+ </li>
+</ul>
+
+For more information on Kerberos and
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Introduction">JAAS</a>,
+see the
+<a href="http://java.sun.com/j2se/1.4/docs/guide/security/jgss/tutorials/ClientServer.html">Kerberos tutorial</a>.
+For instructions on how to create keytab files and TGT caches, see
+<a href="krb-setup.html">krb-setup.html</a>.
+<p>
+
+<h4>Installing the security policy provider for dynamic permission granting</h4>
+
+In order to enable
+<a href="../../../../../../../doc/specs/api/net/jini/security/policy/DynamicPolicyProvider.html">dynamic permission granting</a>,
+the
+<a href="../../../../../../../doc/specs/api/net/jini/security/policy/package-summary.html">security policy provider</a>
+included in the Apache River release must be installed as an extension
+in the Java 2 SDK (or JRE) used to run this example. Although the
+<a href="../../../../../../../doc/info-index.html#install">top level documentation</a>
+of the Apache River release discusses two different strategies for installing
+the policy provider, the strategy that this example <b>requires</b>
+is the strategy in which the JAR file <code>jsk-policy.jar</code>
+is copied into the Java extensions directory; specifically:
+<p>
+<ol>
+ <li>Locate the <code>jsk-policy.jar</code> file in the
+ <code>lib-ext</code> directory of the Apache River release.
+ </li>
+ <li>Locate the <code>jre/lib/ext</code> directory inside your
+ Java 2 SDK (or JRE) distribution.
+ </li>
+ <li>Copy the <code>jsk-policy.jar</code> file from the Apache River release
+ to the <code>jre/lib/ext</code> directory as located in step 2.
+ </li>
+</ol>
+<p>
+After following the steps outlined above, if the virtual machine
+for the Java platform associated with the <code>ext</code> directory
+is available in your path, then the features provided by the security
+policy provider included in the Apache River release will be available when
+running the example.
+<p>
+<hr>
+
+<a name="quick-start">
+<h2>Quick Start</h2>
+</a>
+This example can be run on a single machine or distributed among
+multiple machines. The client, server, and lookup service can each
+be run on separate machines if desired, but the activatable form
+of the server and the activation system
+(<a href="../../../../../../../doc/api/com/sun/jini/phoenix/package-summary.html">Phoenix</a>)
+must run on the
+same machine. Note also that when the example is distributed among
+multiple machines, a class server must be run on each machine
+in the system. For simplicity, the instructions below will
+assume the example is run in separate command windows
+<i>on a single machine</i>.
+<p>
+To start, open five command windows, one for each of the following:
+
+<ol type=a start=1>
+ <li>httpd</li>
+ <li>phoenix</li>
+ <li>lookup service</li>
+ <li>server</li>
+ <li>client</li>
+</ol>
+
+That is, the instructions below assume the class server will be
+run in window a., Phoenix in window b., the lookup service in
+window c., etc. Note also that the instructions assume the operating
+system is UNIX, Linux, or OS X. If running on Windows, simply
+replace the file separator '/' with '\', and either remove the
+UNIX shell script suffix '.sh', or replace it with the Windows
+command file suffix '.bat'. For example, based on the instructions
+below, to start the lookup service using JRMP on UNIX, Linux,
+or OS X, one would type the following at the prompt ('<code>>></code>')
+in the c. window,
+
+<pre>
+ c. >> scripts/jrmp-reggie.sh
+</pre>
+
+whereas on Windows, one would type one of the following:
+
+<pre>
+ c. >> scripts\jrmp-reggie
+ c. >> scripts\jrmp-reggie.bat
+</pre>
+
+Upon opening the five command windows described above, in each
+window, change the directory to the hello directory. That is,
+
+<pre>
+ a. >> cd <<code>jiniDir</code>>/source/src/com/sun/jini/example/hello
+ b. >> cd <<code>jiniDir</code>>/source/src/com/sun/jini/example/hello
+ c. >> cd <<code>jiniDir</code>>/source/src/com/sun/jini/example/hello
+ d. >> cd <<code>jiniDir</code>>/source/src/com/sun/jini/example/hello
+ e. >> cd <<code>jiniDir</code>>/source/src/com/sun/jini/example/hello
+</pre>
+
+<h3>Running the class server</h3>
+
+To run this example under any of the possible configurations, a single
+class server should be started to serve up files from both the example's
+<code>lib</code> directory and the Apache River release <code>lib-dl</code>
+directory. The
+<a href="../../../../../../../doc/api/com/sun/jini/tool/ClassServer.html">class server</a>
+provided in the Apache River release is used for this purpose. Note that once
+started, there is no need to shut down the class server (cntrl-c) until
+it is no longer needed. This is because that single class server can be
+shared by each configuration. To start the class server, type the
+following in the a. command window:
+
+<pre>
+ a. >> <code><a href="scripts/httpd.sh">scripts/httpd.sh</a></code>
+</pre>
+
+<h3>Running the configurations</h3>
+
+This example presents eleven different configurations that can be run.
+
+The primary characteristic that distinguishes one configuration
+from another is the protocol used for communication by the example's
+server application; that is,
+
+<ol type=A start=1>
+ <li>JRMP</li>
+ <li>Jini ERI (JERI)</li>
+ <li>SSL (JSSE)</li>
+ <li>Kerberos (GSS)</li>
+</ol>
+
+In some cases, the protocols can be mixed. For example, in each of the
+non-secure configurations, the lookup service uses only JRMP for its
+remote communication, even when the server and the client use Jini ERI.
+For the secure configurations, all parties must use the same
+communication protocol; that is, SSL or Kerberos.
+<p>
+For each primary characteristic, there are secondary characteristics
+associated with a particular configuration that further distinguishes
+one configuration from the others. As with the primary characteristic,
+the secondary characteristics are generally related to behavior
+demonstrated by the example's server. For example, is the server
+activatable or non-activatable? Are remote calls confirmed or not?
+<p>
+The quick start instructions in the table below are organized and
+presented based on these primary and secondary characteristics.
+Each row represents one of the configurations under which the
+example may be run. The column labelled <b><i>Execution</i></b>
+presents the scripts that must be executed to run the example
+under that particular configuration. The column labelled
+<b><i>Upon Completion</i></b> presents what must be done to
+"clean up" and prepare for executing another configuration. The
+indicated letters refer to the window in which the associated
+script or command should be executed.
+<p>
+Note that with respect to the username that must be provided in
+the Kerberos configurations, as well as the password that is
+required by both the Kerberos and the SSL configurations, the
+values shown in the table do not necessarily represent the
+actual values that must be input by the user. The password that
+the table shows for the SSL configurations is the same as the
+password used when generating the private keystore supplied
+with this example for the client component. Thus, as long as
+the client's keystore is not replaced with a new keystore with
+a different password, the password shown below can be used as
+shown.
+<p>
+With respect to the Kerberos configurations, the actual values
+to input for the username and password, are the Kerberos principal
+name and corresponding password that are registered with the
+particular Kerberos authentication server (KDC) that will be
+used when running the example; and which are associated with
+the client component through the krb-setenv.sh script
+(or krb-setenv.bat command file).
+<p>
+
+<a name="config-table"></a>
+
+<table border="1" cellpadding="5"
+ summary="Describes how to execute each of the configurations
+ under which the hello example can be run">
+ <caption halign="center" valign="top"><b>Running Each Configuration of the Hello Example</b></caption>
+
+ <tr>
+ <th>ID</th>
+ <th>Distinguishing Characteristic(s)</th>
+ <th>Execution</th>
+ <th>Upon Completion</th>
+ </tr>
+
+ <tr>
+ <th>A-1</th>
+ <td>JRMP server</td>
+ <td>c. >> <code><a href="scripts/jrmp-reggie.sh">scripts/jrmp-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/jrmp-server.sh">scripts/jrmp-server.sh</a></code><br>
+ e. >> <code><a href="scripts/client.sh">scripts/client.sh</a></code>
+ </td>
+ <td>d. >> cntrl-c<br>
+ c. >> cntrl-c
+ </td>
+ </tr>
+
+ <tr>
+ <th>B-2</th>
+ <td>Jini ERI server</td>
+ <td>c. >> <code><a href="scripts/jrmp-reggie.sh">scripts/jrmp-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/jeri-server.sh">scripts/jeri-server.sh</a></code><br>
+ e. >> <code><a href="scripts/client.sh">scripts/client.sh</a></code>
+ </td>
+ <td>d. >> cntrl-c<br>
+ c. >> cntrl-c
+ </td>
+ </tr>
+
+ <tr>
+ <th>B-3</th>
+ <td>Jini ERI server<br>
+ <br>
+ client displays call-confirming dialog box<br>
+ server displays call-confirming dialog box<br>
+ </td>
+ <td>c. >> <code><a href="scripts/jrmp-reggie.sh">scripts/jrmp-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/confirming-jeri-server.sh">scripts/confirming-jeri-server.sh</a></code><br>
+ e. >> <code><a href="scripts/client.sh">scripts/client.sh</a></code><br>
+ <br>
+ click "OK" in dialog displayed by client<br>
+ click "OK" in dialog displayed by server<br>
+ </td>
+ <td>d. >> cntrl-c<br>
+ c. >> cntrl-c
+ </td>
+ </tr>
+
+ <tr>
+ <th>B-4</th>
+ <td>Activatable Jini ERI server<br>
+ JRMP Phoenix
+ </td>
+ <td>b. >> <code><a href="scripts/jrmp-phoenix.sh">scripts/jrmp-phoenix.sh</a></code><br>
+ c. >> <code><a href="scripts/jrmp-reggie.sh">scripts/jrmp-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/activatable-jeri-server.sh">scripts/activatable-jeri-server.sh</a></code><br>
+ e. >> <code><a href="scripts/client.sh">scripts/client.sh</a></code>
+ </td>
+ <td>c. >> cntrl-c<br>
+ b. >> cntrl-c<br>
+ <b><i>-- UNIX/Linux/OS X --</i></b><br>
+ b. >> rm -rf lib/phoenix-log<br>
+ <b><i>-- windows --</i></b><br>
+ b. >> rmdir /S /Q lib\phoenix-log
+ </td>
+ </tr>
+
+ <tr>
+ <th>B-5</th>
+ <td>Activatable Jini ERI server<br>
+ Jini ERI Phoenix
+ </td>
+ <td>b. >> <code><a href="scripts/jeri-phoenix.sh">scripts/jeri-phoenix.sh</a></code><br>
+ c. >> <code><a href="scripts/jrmp-reggie.sh">scripts/jrmp-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/activatable-jeri-server.sh">scripts/activatable-jeri-server.sh</a></code><br>
+ e. >> <code><a href="scripts/client.sh">scripts/client.sh</a></code>
+ </td>
+ <td>c. >> cntrl-c<br>
+ b. >> cntrl-c<br>
+ <b><i>-- UNIX/Linux/OS X --</i></b><br>
+ b. >> rm -rf lib/phoenix-log<br>
+ <b><i>-- windows --</i></b><br>
+ b. >> rmdir /S /Q lib\phoenix-log
+ </td>
+ </tr>
+
+ <tr>
+ <th>C-6</th>
+ <td>SSL<br>
+ <br>
+ client displays login dialog box
+ </td>
+ <td>c. >> <code><a href="scripts/ssl-reggie.sh">scripts/ssl-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/ssl-server.sh">scripts/ssl-server.sh</a></code><br>
+ e. >> <code><a href="scripts/ssl-client.sh">scripts/ssl-client.sh</a></code><br>
+ <br>
+ Keystore password: clientpw
+ </td>
+ <td>d. >> cntrl-c<br>
+ c. >> cntrl-c
+ </td>
+ </tr>
+
+ <tr>
+ <th>C-7</th>
+ <td>SSL<br>
+ <br>
+ client displays login dialog box<br>
+ <br>
+ client displays call-confirming dialog box<br>
+ server displays call-confirming dialog box<br>
+ </td>
+ <td>c. >> <code><a href="scripts/ssl-reggie.sh">scripts/ssl-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/confirming-ssl-server.sh">scripts/confirming-ssl-server.sh</a></code><br>
+ e. >> <code><a href="scripts/ssl-client.sh">scripts/ssl-client.sh</a></code><br>
+ <br>
+ Keystore password: clientpw<br>
+ <br>
+ click "OK" in dialog displayed by client<br>
+ click "OK" in dialog displayed by server<br>
+ </td>
+ <td>d. >> cntrl-c<br>
+ c. >> cntrl-c
+ </td>
+ </tr>
+
+ <tr>
+ <th>C-8</th>
+ <td>SSL<br>
+ <br>
+ Activatable SSL server<br>
+ SSL Phoenix<br>
+ <br>
+ client displays login dialog box
+ </td>
+ <td>b. >> <code><a href="scripts/ssl-phoenix.sh">scripts/ssl-phoenix.sh</a></code><br>
+ c. >> <code><a href="scripts/ssl-reggie.sh">scripts/ssl-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/activatable-ssl-server.sh">scripts/activatable-ssl-server.sh</a></code><br>
+ e. >> <code><a href="scripts/ssl-client.sh">scripts/ssl-client.sh</a></code><br>
+ <br>
+ Keystore password: clientpw
+ </td>
+ <td>c. >> cntrl-c<br>
+ b. >> cntrl-c<br>
+ <b><i>-- UNIX/Linux/OS X --</i></b><br>
+ b. >> rm -rf lib/phoenix-log<br>
+ <b><i>-- windows --</i></b><br>
+ b. >> rmdir /S /Q lib\phoenix-log
+ </td>
+ </tr>
+
+ <tr>
+ <th>D-9</th>
+ <td>Kerberos<br>
+ <br>
+ client displays login dialog box
+ </td>
+ <td>c. >> <code><a href="scripts/krb-reggie.sh">scripts/krb-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/krb-server.sh">scripts/krb-server.sh</a></code><br>
+ e. >> <code><a href="scripts/krb-client.sh">scripts/krb-client.sh</a></code><br>
+ <br>
+ Kerberos username[<<i>default</i>>]: client<br>
+ Kerberos password for client: clientpw
+ </td>
+ <td>d. >> cntrl-c<br>
+ c. >> cntrl-c
+ </td>
+ </tr>
+
+ <tr>
+ <th>D-10</th>
+ <td>Kerberos<br>
+ <br>
+ client displays login dialog box<br>
+ <br>
+ client displays call-confirming dialog box<br>
+ server displays call-confirming dialog box<br>
+ </td>
+ <td>c. >> <code><a href="scripts/krb-reggie.sh">scripts/krb-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/confirming-krb-server.sh">scripts/confirming-krb-server.sh</a></code><br>
+ e. >> <code><a href="scripts/krb-client.sh">scripts/krb-client.sh</a></code><br>
+ <br>
+ Kerberos username[<<i>default</i>>]: client<br>
+ Kerberos password for client: clientpw
+ <br>
+ click "OK" in dialog displayed by client<br>
+ click "OK" in dialog displayed by server<br>
+ </td>
+ <td>d. >> cntrl-c<br>
+ c. >> cntrl-c
+ </td>
+ </tr>
+
+ <tr>
+ <th>D-11</th>
+ <td>Kerberos<br>
+ <br>
+ Activatable Kerberos server<br>
+ Kerberos Phoenix<br>
+ <br>
+ client displays login dialog box
+ </td>
+ <td>b. >> <code><a href="scripts/krb-phoenix.sh">scripts/krb-phoenix.sh</a></code><br>
+ c. >> <code><a href="scripts/krb-reggie.sh">scripts/krb-reggie.sh</a></code><br>
+ d. >> <code><a href="scripts/activatable-krb-server.sh">scripts/activatable-krb-server.sh</a></code><br>
+ e. >> <code><a href="scripts/krb-client.sh">scripts/krb-client.sh</a></code><br>
+ <br>
+ Kerberos username[<<i>default</i>>]: client<br>
+ Kerberos password for client: clientpw
+ </td>
+ <td>c. >> cntrl-c<br>
+ b. >> cntrl-c<br>
+ <b><i>-- UNIX/Linux/OS X --</i></b><br>
+ b. >> rm -rf lib/phoenix-log<br>
+ <b><i>-- windows --</i></b><br>
+ b. >> rmdir /S /Q lib\phoenix-log
+ </td>
+ </tr>
+
+</table>
+
+<p>
+<center><b><i>Table 1: Quick Start Table</i></b></center>
+<p>
+<hr>
+
+<a name="changes">
+<h2>Making Changes</h2>
+</a>
+
+Out of the box, this example includes prebuilt class and JAR
+files. If you wish to experiment with modifying and rebuilding
+this example, the following files are provided to allow you to
+recompile the source and rebuild the JAR files:
+<p>
+<ul>
+ <li>
+ <code><a href="build.xml">build.xml</a></code> -
+ build script for recompiling the source and regenerating the example
+ JAR files using <a href="http://ant.apache.org/">Apache Ant</a>
+ </li>
+ <li>
+ <code><a href="server.mf">server.mf</a></code> - Manifest for server.jar,
+ the non-activatable server
+ </li>
+ <li>
+ <code><a href="server-act.mf">server-act.mf</a></code> - Manifest for
+ server-act.jar, the activatable server
+ </li>
+ <li>
+ <code><a href="client.mf">client.mf</a></code> - Manifest for client.jar
+ </li>
+</ul>
+
+To use <code>build.xml</code>, two environment variables must be
+set: <code>JAVA_HOME</code> and <code>ANT_HOME</code>. These
+environment variables must each be set to reference a valid version
+of the Java 2 SDK (or JRE) and Ant respectively. The version of the
+Java operating environment referenced must be at least 1.4. The
+version of Ant referenced must be at least 1.6.2.
+<p>
+Note that all operations shown below are performed from the
+<code>hello</code> directory of the example, and assume a UNIX,
+Linux, or OS X operating system. If the operating system is
+Windows, then replace <code>$ANT_HOME</code> with <code>%ANT_HOME%</code>,
+and replace all instances of the UNIX file separtor '/' with the
+Windows file separator '\'.
+<p>
+
+<h4>Compiling the source</h4>
+
+If you edit one or more of the source files belonging to this
+example, typing the following will cause the appropriate file(s)
+to be automatically recompiled:
+
+<pre>
+ >> $ANT_HOME/bin/ant
+</pre>
+
+<h4>Generating the JAR files</h4>
+
+The JAR files associated with this example can be generated
+individually, in selected subsets, or all in a single command.
+For example, the following commands will separately generate
+all of the example's JAR files:
+
+<pre>
+ >> $ANT_HOME/bin/ant client.jar
+ >> $ANT_HOME/bin/ant server.jar
+ >> $ANT_HOME/bin/ant server-act.jar
+ >> $ANT_HOME/bin/ant server-dl.jar
+ >> $ANT_HOME/bin/ant mdprefld.jar
+</pre>
+
+The following command will generate a selected subset
+of the JAR files:
+
+<pre>
+ >> $ANT_HOME/bin/ant client.jar server.jar mdprefld.jar
+</pre>
+
+Finally, the following command will generate all of the
+JAR files of the example in a single command:
+
+<pre>
+ >> $ANT_HOME/bin/ant this.jars
+</pre>
+
+<h4>Clean builds</h4>
+
+To remove all class files, recompile all source files, and then
+generate all of the JAR files of the example, type the following:
+
+<pre>
+ >> $ANT_HOME/bin/ant clean
+ >> $ANT_HOME/bin/ant
+ >> $ANT_HOME/bin/ant this.jars
+</pre>
+
+<hr>
+
+<a name="troubleshooting">
+<h2>Troubleshooting</h2>
+</a>
+
+While running the example, you may encounter problems. This
+section attempts to describe some of the more common problems
+and their possible causes and solutions. Please note that
+the information contained in this section is by no means
+complete or exhaustive.
+
+<h4>Class server not started or improperly configured</h4>
+
+If you encounter output containing information like the
+following, you should verify that you have started a
+class server listening on the correct port and serving
+classes from the correct directories.
+
+<pre>
+java.lang.ClassNotFoundException: com.sun.jini.reggie.RegistrarProxy
+ (could not obtain preferred value)
+</pre>
+
+<h4>Dynamic permission grants not supported</h4>
+
+If you encounter a stack trace that contains information like that
+shown below, the problem is usually related to the security policy
+provider for dynamic permission granting.
+
+<pre>
+java.lang.SecurityException: Dynamic permission grants are not supported
+....
+Caused by: java.lang.UnsupportedOperationException: grants not supported
+</pre>
+
+The cause of the above problem is typically an incorrectly installed
+(or not installed at all) <code>jsk-policy.jar</code> file. Another
+(only slightly) less common cause is a 'typo' in the system property
+<code>java.security.properties</code> referenced on the command line.
+For example,
+
+<pre>-Djava.security.properties=config/dynamic-policy.security-properties</pre>
+
+If the file referenced in the property above does not exist or is
+unreachable, or if there is a typo in either the property name or
+the file name, an exception trace like that above will occur.
+
+<h4>No trusted certificates found</h4>
+
+<pre>
+INFO: exception while preparing lookup service proxy
+java.rmi.ConnectIOException: I/O exception connecting to BasicObjectEndpoint[...];
+ nested exception is: net.jini.io.UnsupportedConstraintException:
+ sun.security.validator.ValidatorException: No trusted certificate found
+</pre>
+
+This problem occurs when running the SSL configurations and is
+typically encountered when one or more public key certificates
+cannot be found. A common cause of this problem is an incorrect
+<code>javax.net.ssl.trustStore</code> system property. For example,
+
+<pre>-Djavax.net.ssl.trustStore=prebuiltkeys/truststore</pre>
+
+Although a missing or inaccessible file can cause this problem,
+one of the most common mistakes made regarding this property
+is to not capitalize the second '<code>S</code>' in the
+'<code>trustStore</code>' component of
+<code>javax.net.ssl.trust<b>S</b>tore</code>.
+
+<h4>Mixing protocols</h4>
+
+Although protocols can be mixed when using JRMP and Jini ERI,
+protocols usually cannot be mixed when using the secure protocols.
+Depending on which party is running securely and which is not,
+different exception conditions will be encountered. For example,
+if the lookup service is run under a secure configuration, and
+the client or server is run under one of the basic configurations,
+output like the following may be encountered:
+
+<pre>java.net.MalformedURLException: unknown protocol: httpmd</pre>
+
+On the other hand, if the lookup service is run under one of the
+basic configurations, but the client or server is run under a
+secure configuration, the output will probably contain information
+like the following:
+
+<pre>
+INFO: exception while preparing lookup service proxy
+java.lang.SecurityException: object is not trusted: com.sun.jini.reggie.RegistrarProxy[...]
+ at net.jini.security.Security.verifyObjectTrust(Security.java:<<code>lineNo</code>>)
+</pre>
+
+<h4>Unsynchronized clocks</h4>
+
+When running the example under one of the Kerberos configurations,
+an exception indicating something like the following may be
+encountered:
+
+<pre>
+Pre-authentication information was invalid (24) - Preauthentication failed.
+</pre>
+
+Often this is an indication of skew between the clock on the
+KDC host (running the authentication server) and the clock on
+the host running the Kerberos server wishing to authenticate.
+Those clocks should be set to the same time zones and
+synchronized to be within 5 minutes of each other.
+<p>
+<hr>
+
+<a name="deeper">
+<h2>Looking Deeper</h2>
+</a>
+
+Once again, although only one example is being presented, that
+single example can be run under a variety of configurations to
+behave in ways that satisfy different requirements; requirements
+such as,
+
+<ul>
+ <li>How remote communication is performed</li>
+ <li>Whether and how remote communication is controlled</li>
+ <li>Whether and how access in the system is controlled</li>
+ <li>Whether and how authentication is performed</li>
+</ul>
+
+This section goes a bit beyond what was presented in the
+<a href="#quick-start">quick start</a> section by diving a little
+deeper, analyzing the purpose and contents of the various files
+provided with this example; source, configuration and policy files,
+manifests, preferred lists, etc.
+
+<h3>Overview</h3>
+
+The example presented here consists of distributed components
+that are federated by a Jini technology infrastructure to interact
+in a service-oriented manner. One of the components making up the
+example is a Jini technology lookup service, through which the
+example's client and service components are federated. Note
+that for the purposes of this discussion, the term <b><i>service</i></b>
+and the term <b><i>server</i></b> will often be used interchangably,
+with server referring to the actual incarnation of the service.
+<p>
+Recall that a common way to view a service is as a <i>provider</i>
+of some sort of resource. A <i>client</i> of a service can
+then be viewed as a <i>user</i> (or consumer) of the resource
+provided by the service. For example, consider the Jini technology
+lookup service itself. The lookup service provides multiple
+resources that can be useful to both clients and other services.
+One resource provided by the lookup service is "residency" in
+the lookup service. Through the residency a lookup service
+provides to another service, that other service advertises the
+availability of its own resource(s). Another resource provided by
+the lookup service is a "query resource". Clients can query the
+lookup service for, and obtain references to, other services
+having resources the client wishes to use.
+<p>
+For each and every configuration in this example, the service
+component of the example discovers the lookup service and then
+requests and is granted residency in the lookup service.
+The client also discovers the lookup service, but rather than
+requesting residency, the client queries the lookup service
+for a service of type <code>Hello</code>, and the lookup service
+provides the client with a reference (a <i>proxy</i>) to that
+service. Once the client has obtained a proxy to the service
+of interest, through that proxy, the client <i>uses</i> the
+service to display a greeting, which is the resource the service
+provides. To see the implementation details, examine the contents
+of the following source files. Note that it is the proxy object
+that implements the <code>Hello</code> interface, which is the
+service type the client requests from the lookup service.
+
+<ul>
+ <li><code><a href="Hello.java">Hello.java</a></code> - the interface which represents the service type</li>
+ <li><code><a href="Server.java">Server.java</a></code> - the server component that exports the remote object</li>
+ <li><code><a href="Proxy.java">Proxy.java</a></code> - the proxy object obtained by the client from the lookup service</li>
+ <li><code><a href="Client.java">Client.java</a></code> - the client component</li>
+</ul>
+
+<h3>Understanding the configurations</h3>
+
+To understand the differences in the various configurations
+under which this example can be run, it's important to first
+recognize that interactions between the components in the
+federation occur primarily through remote invocations. Recall
+that when a remote invocation is made from one component to
+another, the call is <i>initiated</i> in the first component's
+virtual machine (VM), then communication occurs from one VM to the
+other, with the call ultimately executing in the second component's
+VM. In particular, when a service requests residency in the
+lookup service, when a client queries the lookup service for
+a service of interest, and when a client uses (the remote
+methods of) that service (for example, to display the greeting
+in this example), remote calls are made. Because communication
+is occurring between remote, possibly untrusted, parties, the
+ability to configure and control how that communication occurs
+can be important.
+<p>
+The point of this example is to show how the source can be
+written and built only once, yet executed using different
+(possibly mixed) remote communication mechanisms with different
+controls and constraints placed on how that communication occurs;
+by merely running under different configurations that are
+specified at runtime. No matter what configuration is used to
+run the example, the client's goal is always the same: to use
+a lookup service to find a <code>Hello</code> service, and
+then to use the <code>Hello</code> service to display a greeting.
+As will be further explained in the sub-sections below, the
+differences in the configurations lie in how the remote calls
+between the components are implemented and controlled.
+<p>
+
+<i>
+<b>Tip:</b>
+ with respect to the emphasis on remote communication between
+ the components of the system, if the example is being run on a
+ single machine, it might help to view the separate windows as
+ separate machines on which each component runs and communicates
+ with the others.
+</i>
+
+<h3>Basic configurations</h3>
+
+Consider the configurations A-1, B-2, B-4, and B-5 as presented
+in the <a href="#config-table">quick start table</a>. For the
+purposes of this discussion, those configurations will be
+referred to as the <i>basic</i> configurations because no
+access control (either manual or provided through the protocol)
+and no authentication occurs when two components in the system
+attempt to communicate with each other. These configurations
+demonstrate the basic operation of the example, highlighting the
+ability of the JRMP and Jini ERI protocols to coexist in a system.
+With any of these configurations, one should simply see the
+"Hello, world!" greeting displayed in the command window from
+which the client was run.
+<p>
+<h4>Configuration files</h4>
+
+Because this example emphasizes the concept of
+"one source, different configurations", it may be helpful to examine
+and compare the contents of the basic configuration files that are
+provided.
+<p>
+
+<b><i>Basic configuration files</i></b>
+ <ul>
+ <li><code><a href="config/jrmp-reggie.config">config/jrmp-reggie.config</a></code></li>
+ <li><code><a href="config/jrmp-server.config">config/jrmp-server.config</a></code></li>
+ <li><code><a href="config/jeri-server.config">config/jeri-server.config</a></code></li>
+ <li><code><a href="config/client.config">config/client.config</a></code></li>
+ </ul>
+
+Recall that remote objects must be
+<a href="../../../../../../../doc/specs/api/net/jini/export/package-summary.html"><i>exported</i></a>.
+The process of
+exporting a remote object results in the creation of a <i>proxy</i>
+object, which is passed to other components so that those other
+components may communicate with (make remote calls on) the component
+that was exported. When examining the configuration files above, notice
+that the configuration files for the lookup service
+(<a href="../../../../../../../doc/api/com/sun/jini/reggie/package-summary.html"><code>Reggie</code></a>)
+and the server each specifies an
+<a href="../../../../../../../doc/specs/api/net/jini/export/Exporter.html"><i>exporter</i></a>.
+From this, one can conclude that the lookup service as well as the
+server each export a remote object. Note that although the client's
+configuration file doesn't specify an exporter, it happens that a remote
+object actually is exported by the client component. Upon examining
+the client's configuration file, one can see that the client specifies
+a
+<a href="../../../../../../../doc/api/net/jini/lookup/ServiceDiscoveryManager.html"><code>ServiceDiscoveryManager</code> (SDM)</a>.
+The SDM utility exports a remote listener object, using a default
+exporter if no exporter is specified in the configuration. Of course,
+the client configuration file above could have explicitly specified an
+exporter in a way similar to what is done in the client's secure
+configurations, which can be seen by examining the files in the next
+section.
+<p>
+Through the configured exporter, one can specify the protocol to
+use for remote communication; in this case, JRMP or Jini ERI. Thus,
+when the remote object is exported using the exporter specified in the
+configuration, a proxy is created through which the other components
+in the system can communicate with the remote object using the protocol
+that is specified with that exporter. For example, to configure a basic
+exporter that will create a proxy that communicates back to the remote
+object using JRMP, the configuration would contain an entry like the
+following:
+
+<pre>
+ exporter = new JrmpExporter();
+</pre>
+
+Compare this with an exporter that specifies its remote communication
+to occur over Jini ERI,
+
+<a name="basic-jeri-exporter"></a>
+<pre>
+ private static endPoint = TcpServerEndpoint.getInstance(0);
+ private static ilFactory = new BasicILFactory();
+
+ exporter = new BasicJeriExporter(endPoint, ilFactory);
+</pre>
+
+Note that the values of the private entries in the configuration
+snippet above will be automatically substituted for the parameters
+of the exporter specification when the exporter is instantiated. Using
+substitution in this way is not required; that is, the private values
+could have been entered directly in the exporter specification. Private
+entries are used here and in the other snippets presented in this
+document to aid in readability.
+<p>
+From the snippets above, it should be clear that one specifies the
+use of JRMP or Jini ERI by configuring either a "JRMP exporter" or a
+"Jini ERI exporter" respectively. As will be further demonstrated in the
+<a href="#secure-config-files">Secure configuration files</a> section
+below, when using a
+<a href="../../../../../../../doc/specs/api/net/jini/jeri/BasicJeriExporter.html"><code>BasicJeriExporter</code></a>,
+one has additional flexibility with respect to the <i>transport</i> over
+which communication will occur. Through the <code>endPoint</code>
+parameter of <code>BasicJeriExporter</code>, one can specify non-secure
+transports such as TCP (as was done above) and HTTP, or transports
+that support security, such as SSL, HTTPS, and Kerberos.
+
+<h3>Secure configurations</h3>
+
+The configurations with IDs that begin with 'C' or 'D' from the
+<a href="#config-table">quick start table</a> will be referred to
+as <i>secure</i> configurations because access control, integrity,
+and authentication are enforced when components of the system
+communicate with each other under those configurations.
+
+<h4>Dynamic permissions, integrity, access control</h4>
+
+To install the security policy provider included in the Apache River
+release (to enable dynamic permission granting) the secure configurations
+of the lookup service, the server, and Phoenix each use the
+security properties file,
+<code><a href="config/dynamic-policy.security-properties">config/dynamic-policy.security-properties</a></code>.
+<p>
+With respect to the example's server component, each of that
+component's secure configurations employs a specially defined
+<code><a href="MdClassAnnotationProvider.java">preferred class provider</a></code>,
+which uses
+<a href="../../../../../../../doc/specs/api/net/jini/url/httpmd/package-summary.html"><i>HTTPMD URL</i>s</a>
+to ensure integrity of data and downloaded
+code. Additionally, each secure configuration of the server component
+specifies a <code><a href="ServerPermission.java">ServerPermission</a></code>
+to control access to the resource(s) the server provides.
+
+<h4>Principals</h4>
+
+Whether running one of the SSL configurations or one of the
+Kerberos configurations, each component is associated with a
+<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/Principal.html"><i>principal</i></a>
+- an
+<a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/x500/X500Principal.html">X500Principal</a>
+in the case of SSL, or a
+<a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/kerberos/KerberosPrincipal.html">KerberosPrincipal</a>
+in the case of Kerberos. A principal essentially represents a
+component's identity; that is, "who" the component is.
+<a href="../../../../../../../doc/specs/api/net/jini/constraint/package-summary.html">Constraints</a>
+can then be imposed and permissions can be granted based on a
+component's identity.
+
+<h4>Constraints</h4>
+
+One way to view constraints is as a mechanism - in conjunction
+with the standard
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/spec/security-spec.doc3.html#20128">Java security policy mechanism</a>
+- for expressing what a principal
+<b><i>can do</i></b>, what it <b><i>cannot do</i></b>, and/or
+what it <b><i>must do</i></b>. In particular, through constraints
+and Java security policy, the components of the example can be
+configured so that the desired security is enforced when the
+components attempt to communicate with each other. For example,
+before communication between two components is allowed, one
+(or both) component(s) may be required to authenticate itself
+to the other component; that is, the component may be required
+to not only tell the other component <i>who</i> it is, but also
+<i>prove</i> who it is. Based on who the component authenticates
+as, access to the resources of the component with which it is
+communicating is either granted or refused; that is, access
+is controlled based on who (what principal) is asking for that
+access.
+
+<h4>Login configuration files</h4>
+
+Each component of the example is associated with a different
+principal representing who that component is while it executes.
+Each principal is associated with a corresponding password.
+Take a look at the files in the example's
+<code><a href="./prebuiltkeys">prebuiltkeys</a></code> directory
+that have names of the form <code>*.password</code>. Notice that
+the <code>prebuiltkeys</code> directory contains no password files
+associated with the client component of the example. When running
+the example, you should observe that only the client component
+prompts for a password; thus, no password file is required for the
+client in the <code>prebuiltkeys</code> directory. This is because,
+unlike the client, the lookup service, the server, and Phoenix are
+each configured to automatically retrieve their respective passwords
+from a file, rather than from an interactive dialog box in which
+a human user supplies the principal name and appropriate password.
+<p>
+Whether running an SSL configuration or a Kerberos configuration,
+the authentication mechanism used is the
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASRefGuide.html">Java Authentication and Authorization Service (JAAS)</a>.
+To use JAAS, a component "logs in"; a process that requires configuration.
+To understand how each component of the example is configured for
+JAAS login, compare the contents of the following files:
+<p>
+<b><i>JAAS login configuration files for SSL configurations</i></b>
+ <ul>
+ <li><code><a href="config/ssl-phoenix.login">config/ssl-phoenix.login</a></code></li>
+ <li><code><a href="config/ssl-reggie.login">config/ssl-reggie.login</a></code></li>
+ <li><code><a href="config/ssl-server.login">config/ssl-server.login</a></code></li>
+ <li><code><a href="config/ssl-client.login">config/ssl-client.login</a></code></li>
+ </ul>
+<b><i>JAAS login configuration files for Kerberos configurations</i></b>
+ <ul>
+ <li><code><a href="config/krb-phoenix.login">config/krb-phoenix.login</a></code></li>
+ <li><code><a href="config/krb-reggie.login">config/krb-reggie.login</a></code></li>
+ <li><code><a href="config/krb-server.login">config/krb-server.login</a></code></li>
+ <li><code><a href="config/krb-client.login">config/krb-client.login</a></code></li>
+ </ul>
+
+If you compare these files, you will see some parallels between
+the SSL login configuration files and the Kerberos login
+configuration files. For example, there is an indication of the
+principal name for the corresponding component (<code>keyStoreAlias</code>
+for SSL, <code>principal</code> for Kerberos), where to find the
+credentials that will be used for authentication (<code>keyStoreURL</code>
+and <code>keyTab</code>), and for SSL, the location from which to
+retrieve the associated password (<code>keyStorePasswordURL</code>).
+If you examine the client's SSL login configuration file, you will
+see that there is no <code>keyStorePasswordURL</code>, and its
+Kerberos login configuration file sets <code>doNotPrompt</code> to
+<code>false</code> (by default); both of which will cause the client's
+<a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/spi/LoginModule.html"><i>login module</i></a>
+to prompt for a password.
+
+<a name="secure-config-files"><h4>Configuration files</h4></a>
+
+As discussed previously, the secure configurations of this example
+emphasize security in the face of <b><i>remote calls and downloaded code</i></b>.
+Furthermore, when security is introduced into the system, it is
+introduced through a mechanism of constraints in conjunction with
+the standard security policy mechanism. Concrete examples of this
+can be seen when examining and comparing the contents of the
+following configuration files:
+<p>
+
+<b><i>SSL configuration files</i></b>
+ <ul>
+ <li><code><a href="config/ssl-reggie.config">config/ssl-reggie.config</a></code></li>
+ <li><code><a href="config/ssl-server.config">config/ssl-server.config</a></code></li>
+ <li><code><a href="config/ssl-client.config">config/ssl-client.config</a></code></li>
+ </ul>
+<b><i>Kerberos configuration files</i></b>
+ <ul>
+ <li><code><a href="config/krb-reggie.config">config/krb-reggie.config</a></code></li>
+ <li><code><a href="config/krb-server.config">config/krb-server.config</a></code></li>
+ <li><code><a href="config/krb-client.config">config/krb-client.config</a></code></li>
+ </ul>
+
+While examining the above configuration files, one should notice the
+relationship between the export process, the proxies that result from
+exporting, and the constraint mechanism in conjunction with the
+standard security policy mechanism. As with the basic configurations,
+each component in the example exports a remote object; thus, each
+secure configuration specifies an exporter. Furthermore, the exporter
+that is configured is the mechanism through which one can specify
+the security requirements that will be enforced from the point of
+view of the exported remote object.
+<p>
+Because components that <i>receive</i> a proxy produced by an exporter
+will use the proxy to communicate with the exported remote object,
+those components will want to specify the security requirements
+that will be enforced from the point of view of the component that
+receives and uses the proxy. Additionally, because acquisition and
+reconstruction of the proxy, as well as the invocation of any remote
+methods on the proxy, typically involve not only data transmitted
+in-band as part of the remote call, but also code downloaded
+out-of-band, enforcing <i>object</i> integrity (both <b>data</b>
+and <b>code</b>) will become a priority for many components that
+interact with the proxies they receive.
+<p>
+Note that whether viewing constraints from the point of view of an
+exported remote object, or from the point of view of a component
+that receives and uses the proxy associated with a remote object,
+when a set of constraints specify integrity
+(<a href="../../../../../../../doc/specs/api/net/jini/core/constraint/Integrity.html"><code>Integrity.YES</code></a>)
+on the remote calls between a proxy and its remote object,
+the integrity of both the data and any downloaded code must be
+verified. That is, during the execution of a remote call in which
+serialized objects are transmitted and reconstructed, it must be
+verified that neither the serialized data that is tranmitted in-band,
+nor the code defining each object's behavior that is downloaded
+out-of-band (if any), has not been compromised.
+<p>
+Whereas security requirements are specified through an exporter
+for a remote object's communication, the security requirements
+for communication through a proxy are specified through what is
+referred to as a
+<a href="../../../../../../../doc/specs/api/net/jini/security/ProxyPreparer.html"><i>proxy preparer</i></a>.
+Thus, while examining the contents of the secure configuration
+files above, you will notice not only exporters being specified,
+but also proxy preparers. For a particular configuration file,
+the exporters are specified for the remote objects that are
+exported by the specific component associated with that configuration;
+whereas the proxy preparers are specified for the proxies that
+that component receives from the other components in the system.
+<p>
+Upon examining the exporters specified in the secure configurations,
+you will see that in addition to specifying the transport to
+use, through the <i>invocation layer</i>, constraints can be
+set and aspects of access control can be specified. Compare this
+to the security-related items that are specified for the proxy
+preparers. When configuring a proxy preparer, the following
+is specified:
+
+<ul>
+ <li>Whether or not to verify that the proxy is trusted</li>
+ <li>The constraints (if any) to attach to the proxy</li>
+ <li>The permissions (if any) to dynamically grant to the proxy</li>
+</ul>
+
+<p><b><i>Exporters and security</i></b><p>
+
+To make this discussion regarding exporters and proxy preparers
+more concrete, first consider the following snippet showing the
+configuration of an exporter one might wish to use to export the
+remote object defined by the example's server. This exporter is
+configured for SSL. Note that, as before, private entries are used
+for readability.
+
+<pre>
+ private static endPoint = SslServerEndpoint.getInstance(0);
+ private static integrityOnly = new InvocationConstraints(Integrity.YES, null);
+ private static constraints = new BasicMethodConstraints(integrityOnly);
+ private static ilFactory = new ProxyTrustILFactory(constraints, ServerPermission.class);
+
+ exporter = new BasicJeriExporter(endPoint, ilFactory);
+</pre>
+
+This exporter is similar to the <a href="#basic-jeri-exporter">Jini ERI exporter</a>
+presented in the basic configurations section. Note the
+differences though. This exporter specifies the use of
+secure sockets (SSL) for communication and, through the
+invocation layer factory, specifies that when a component
+attempts to invoke a remote method on the exported object,
+integrity must be enforced, and the component must have
+permission - specifically, a
+<a href="ServerPermission.java"><code>ServerPermission</code></a> -
+to access the particular method on which the invocation is
+being attempted.
+<p>
+There are a couple of additional things to note about the
+configuration of the exporter above. First, with respect to
+the exporter's constraints, the only constraint that is
+specified is integrity. This is not an uncommon security model
+for remote server objects. Rather than using additional
+constraints to enforce access control, the strategy demonstrated
+here is to exploit the standard Java security policy mechanism
+to control access to the exported object's remote methods using
+a <a href="ServerPermission.java"><code>ServerPermission</code></a>.
+The second thing to note is that to change the above SSL exporter
+to a Kerberos exporter, one merely has to change the endpoint
+to a Kerberos endpoint. That is,
+
+<pre>
+ private static endPoint = KerberosServerEndpoint.getInstance(0);
+</pre>
+
+<p><b><i>Proxy preparers</i></b><p>
+
+Next, consider a snippet showing the configuration of the proxy
+preparer one might wish to apply to the proxy the client receives
+from the server (by way of the lookup service):
+
+<pre>
+ private static verifyTrust = true;
+ private static requirements = new InvocationConstraint[]
+ { Integrity.YES,
+ ClientAuthentication.YES,
+ ServerAuthentication.YES,
+ new ServerMinPrincipal(serverUser) };
+ private static preferences = null;
+ private static invocationConstraints = new InvocationConstraints(requirements,preferences);
+ private static methodConstraints = new BasicMethodConstraints(invocationConstraints);
+ private static dynamicPermissions =
+ new Permission[] { new AuthenticationPermission(clientUser,serverUser,"connect") };
+
+ preparer = new BasicProxyPreparer(verifyTrust, methodConstraints, dynamicPermissions);
+</pre>
+
+Upon examining the snippet above, one can see that before the
+proxy of interest can be used, it must be verified that the
+proxy can be trusted. That is, the first step in proxy preparation
+is trust verification (if requested). Once it is known that the
+proxy can be trusted, constraints can be attached to the proxy.
+This example presents four constraints that represent a common
+model for proxy preparation:
+
+<ul>
+ <li>Integrity must be enforced -
+ <a href="../../../../../../../doc/specs/api/net/jini/core/constraint/Integrity.html"><code>Integrity.YES</code></a>
+ </li>
+ <li>The client must tell the server not only "who" it is when it attempts
+ to communicate with the server, but must also <i>prove</i> to the
+ server that it is who it says it is -
+ <a href="../../../../../../../doc/specs/api/net/jini/core/constraint/ClientAuthentication.html"><code>ClientAuthentication.YES</code></a>
+ <li>Likewise, the server must tell the client who it is and prove it -
+ <a href="../../../../../../../doc/specs/api/net/jini/core/constraint/ServerAuthentication.html"><code>ServerAuthentication.YES</code></a>
+ </li>
+ <li>Although the server may prove itself to be multiple principals
+ when the server proves who it is to the client, one of those
+ principals must be the principal named <code>serverUser</code> -
+ <a href="../../../../../../../doc/specs/api/net/jini/core/constraint/ServerMinPrincipal.html"><code>ServerMinPrincipal(serverUser)</code></a>
+ </li>
+</ul>
+
+After trust has been established and constraints have been set,
+the required permissions that allow the proxy to communicate with
+the remote object must be granted to the proxy. Although the
+remote server from which the proxy originated authenticates as the
+principal <code>serverUser</code>, when the proxy is used to
+communicate back to that server, the proxy is granted
+permission to <code>connect</code> to the server as the principal
+<code>clientUser</code>. Think of the proxy as <b><i>foreign code</i></b>
+executing in the client's environment; code produced by an
+entity - the server - that authenticates as the server's principal.
+The value of the last argument of the proxy preparer configuration
+shown above specifies that the proxy is allowed to communicate back
+to that server under the client's principal; as if it were the
+client itself. The proxy is allowed to do this because the first
+step in the proxy preparation process established that the client
+trusts that proxy to act on the client's behalf.
+<p>
+In addition to exporters and proxy preparers, there are a number
+of other items specified in the configuration files, along with
+some in-line explanatory documentation. You should examine and
+compare the contents of all the configuration files.
+
+<h3>Call confirming configurations</h3>
+
+An additional set of configurations under which this example can be
+run are what will be referred to as the <i>call confirming</i>
+configurations. Each of the call confirming configurations employs
+the Jini ERI protocol for communication, using a custom invocation
+layer factory to produce a custom invocation handler paired with a
+custom invocation dispatcher. When the client component, through the
+proxy, attempts to make a remote call to the server component, the
+custom invocation handler causes a dialog window to pop up so that
+manual confirmation from the client side of the call can be performed
+before allowing the call to proceed. Similarly, after allowing the
+call to proceed from the client side, when the call is dispatched
+on the server side, the dispatcher also displays a dialog window
+so that manual confirmation from the server side of the call can be
+performed before allowing the call to complete.
+<p>
+To see the details of how the custom invocation layer factory, the
+custom dispatcher, and the custom invocation handler are implemented,
+examine the contents of the following source files.
+
+<ul>
+ <li><code><a href="ConfirmingILFactory.java">ConfirmingILFactory.java</a></code> - custom IL factory with dispatcher</li>
+ <li><code><a href="ConfirmingInvocationHandler.java">ConfirmingInvocationHandler.java</a></code> - custom invocation handler</li>
+</ul>
+
+Note that the call confirming configurations span both the basic
+and secure configurations described above. That is, like the
+basic configurations, there is a call confirming configuration
+that specifies basic TCP/IP as the transport and, like the secure
+configurations, there are two call confirming configurations that
+specify SSL and Kerberos (configurations with IDs B-3, C-7, and D-10
+respectively from the <a href="#config-table">quick start table</a>).
+To see the details, examine the contents of the following
+configuration files:
+
+<ul>
+ <li><code><a href="config/confirming-jeri-server.config">config/confirming-jeri-server.config</a></code></li>
+ <li><code><a href="config/confirming-ssl-server.config">config/confirming-ssl-server.config</a></code></li>
+ <li><code><a href="config/confirming-krb-server.config">config/confirming-krb-server.config</a></code></li>
+</ul>
+
+<h3>Activatable configurations</h3>
+
+Another set of configurations provided with this example are what
+will be referred to as the <i>activatable</i> configurations. The
+distinguishing feature of the activatable configurations is that
+the server component is
+<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/activation/Activatable.html"><i>activatable</i></a>;
+that is, the server is configured to be executed by the
+<a href="../../../../../../../doc/api/com/sun/jini/phoenix/package-summary.html">Phoenix</a>
+implementation of the
+<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/activation/ActivationSystem.html"><i>activation system</i></a>.
+<p>
+To understand the explanations below, it might be instructive
+to review some terminology. As described previously, when a
+remote object is exported, a proxy object is produced. Through
+a reference to that proxy object, other components of an
+application can communicate with the exported remote object (the
+server). The proxy object is often referred to as the <i>front end</i>
+of the server, and the various aspects of its communication
+with the remote object are referred to as the <i>client side</i>
+communication. As one might expect, when the proxy is referred
+to as the front end of the server, the associated remote object
+with which that proxy communicates is referred to as the
+<i>back end</i> of the server, and its communication with the
+proxy is referred to as the <i>server side</i> communication.
+Additionally, the term <i>client</i> is generally used to
+refer to the component holding the reference to the proxy,
+but can also refer to the proxy object itself (depending on
+context). Similarly, the term <i>server</i> generally refers
+to the remote object that was exported, or the component that
+performed the export and holds the remote object. Given this
+terminology, it should come as no surprise then that this
+example provides a class named
+<a href="Client.java"><code>Client</code></a> and a class
+named <a href="Server.java"><code>Server</code></a>.
+<p>
+With the above terms in mind, one way to view the activation system
+is as a "container" that can be used to execute server back ends in
+shared or separate virtual machines embodied as
+<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/activation/ActivationGroup.html"><i>activation groups</i></a>.
+That is, the activation system (Phoenix) is started, and then
+the server one wishes to execute is registered with the
+activation system, which ultimately executes the server in a VM that
+the activation system spawns and maintains. As one might expect,
+for the example being described in this document, the only
+component with a configuration that supports this model is the
+server component. To support the server component's interaction
+with activation, the following class is provided:
+
+<ul>
+ <li><a href="ActivatableServer.java"><code>ActivatableServer.java</code></a></li>
+</ul>
+
+<a href="ActivatableServer.java"><code>ActivatableServer</code></a>
+extends <a href="Server.java"><code>Server</code></a>, providing
+additional functionality for registering the server with the
+activation system. Thus, <code>ActivatableServer</code> acts as
+both the server component of this example and the mechanism used
+to register the server with the activation system. Note that this
+strategy of combining server functionality with the activation
+registration mechanism is just one possible strategy for
+implementing the activatable form of the server component.
+Another common strategy is to provide a separate registration
+mechanism (for example, the class
+<a href="../../../../../../../doc/api/com/sun/jini/start/SharedActivatableServiceDescriptor.html"><code>SharedActivatableServiceDescriptor</code></a>
+from the Apache River release's
+<a href="../../../../../../../doc/api/com/sun/jini/start/package-summary.html"><i>service starter framework</i></a>).
+<p>
+As with the confirming configurations, the activatable configurations
+associated with <code>ActivatableServer</code> span both the
+basic and secure configurations described above. For the details,
+see the configurations with IDs B-4, B-5, C-8, and D-11 from the
+<a href="#config-table">quick start table</a>, and examine the
+contents of the following configuration files:
+<p>
+
+<b><i>Configuration files for <a href="ActivatableServer.java">ActivatableServer</a></i></b>
+ <ul>
+ <li><code><a href="config/start-activatable-jeri-server.config">config/start-activatable-jeri-server.config</a></code></li>
+ <li><code><a href="config/start-activatable-ssl-server.config">config/start-activatable-ssl-server.config</a></code></li>
+ <li><code><a href="config/start-activatable-krb-server.config">config/start-activatable-krb-server.config</a></code></li>
+ </ul>
+<b><i>Configuration files for the server component when activated</i></b>
+ <ul>
+ <li><code><a href="config/activatable-jeri-server.config">config/activatable-jeri-server.config</a></code></li>
+ <li><code><a href="config/activatable-ssl-server.config">config/activatable-ssl-server.config</a></code></li>
+ <li><code><a href="config/activatable-krb-server.config">config/activatable-krb-server.config</a></code></li>
+ </ul>
+
+The lists above reveal an interesting pattern for configuration
+when Phoenix is used to execute a server's back end. Notice that for
+each configuration represented in the lists above (Jini ERI, SSL,
+Kerberos), there are two configuration files: one that specifies the
+configuration of the mechanism used to register the server with
+Phoenix, and one that specifies the configuration of the server
+itself. It is important to understand that each of the
+<i>start configuration</i> files from the first list specifies how
+<code>ActivatableServer</code> is to interact with Phoenix to
+register the server (in this case, to register itself) for activation,
+<b><i>not</i></b> how either Phoenix or the server are themselves
+configured. For example, if you examine
+<code><a href="config/start-activatable-jeri-server.config">config/start-activatable-jeri-server.config</a></code>,
+you will see that it is in this file that one specifies the
+actual configuration to use for the server that is to be registered
+and ultimately activated (look for the entry that references
+<code><a href="config/start-activatable-jeri-server.config">config/activatable-jeri-server.config</a></code>).
+When the server is activated, the server configures itself from the
+entries it retrieves from that second configuration. Note that it
+is also in that start configuration file that options and system
+properties can be specified for the VM in which the server runs.
+<p>
+To specifically configure Phoenix, for each configuration under which
+Phoenix may be run in this example (JRMP, Jini ERI, SSL, Kerberos), there
+are Phoenix-specific configuration file pairs: one for configuring the
+activation group created by Phoenix, and one that specifies the actual
+configuration of Phoenix itself. That is,
+<p>
+
+<b><i>Configuration files for activation group, created by Phoenix, in which server runs</i></b>
+ <ul>
+ <li><code><a href="config/jrmp-phoenix-group.config">config/jrmp-phoenix-group.config</a></code></li>
+ <li><code><a href="config/jeri-phoenix-group.config">config/jeri-phoenix-group.config</a></code></li>
+ <li><code><a href="config/ssl-phoenix-group.config">config/ssl-phoenix-group.config</a></code></li>
+ <li><code><a href="config/krb-phoenix-group.config">config/krb-phoenix-group.config</a></code></li>
+ </ul>
+<b><i>Configuration files for Phoenix itself</i></b>
+ <ul>
+ <li><code><a href="config/jrmp-phoenix.config">config/jrmp-phoenix.config</a></code></li>
+ <li><code><a href="config/jeri-phoenix.config">config/jeri-phoenix.config</a></code></li>
+ <li><code><a href="config/ssl-phoenix.config">config/ssl-phoenix.config</a></code></li>
+ <li><code><a href="config/krb-phoenix.config">config/krb-phoenix.config</a></code></li>
+ </ul>
+
+This pattern of configuration file pairs, where one configuration
+specifies how a server is to be started and the other configuration
+specifies the behavior of the server itself, does not apply only in
+activatable scenarios. This pattern often occurs whenever any sort
+of container-type facility is used to initiate the execution of
+another component. For example, consider the lookup service
+implementation employed in this example
+(<a href="../../../../../../../doc/api/com/sun/jini/reggie/package-summary.html"><code>Reggie</code></a>).
+To start Reggie under any of the configurations of this example,
+a container-type application, referred to as the
+<a href="../../../../../../../doc/api/com/sun/jini/start/package-summary.html"><i>service starter framework</i></a>,
+is used. As when Phoenix, through the
+<code><a href="ActivatableServer.java">ActivatableServer</a></code>
+class, is used to start the activatable form of the server
+component of this example, when the service starter framework is
+used to start a server such as Reggie, each configuration is
+represented by a pair of configuration files. Specifically,
+<p>
+
+<b><i>Configuration files for service starter framework used to start Reggie</i></b>
+ <ul>
+ <li><code><a href="config/start-reggie.config">config/start-reggie.config</a></code></li>
+ <li><code><a href="config/start-ssl-reggie.config">config/start-ssl-reggie.config</a></code></li>
+ <li><code><a href="config/start-krb-reggie.config">config/start-krb-reggie.config</a></code></li>
+ </ul>
+<b><i>Configuration files for Reggie itself</i></b>
+ <ul>
+ <li><code><a href="config/jrmp-reggie.config">config/jrmp-reggie.config</a></code></li>
+ <li><code><a href="config/ssl-reggie.config">config/ssl-reggie.config</a></code></li>
+ <li><code><a href="config/krb-reggie.config">config/krb-reggie.config</a></code></li>
+ </ul>
+
+Finally, note that because the activatable form of the server
+component actually runs in a VM (activation group) spawned by
+Phoenix, the mechanism for stopping the activatable server is
+to actually stop Phoenix. This is why the instructions in the
+<a href="#config-table">quick start table</a> indicate that a
+<i>cntrl-c</i> (kill signal) should be executed in the command
+window in which Phoenix was started, rather than the server's
+command window. Additionally, also note that to support the
+management of the environment in which the activatable server
+runs, Phoenix persists certain state. Thus, for convenience, and
+to avoid unnecessary attempts at restarting any old, unwanted
+configurations of the server component, the instructions in the
+<a href="#config-table">quick start table</a> also recommend removing
+the current persisted state (log files and directory) whenever
+Phoenix is shut down.
+
+<h3>Security policy and access control</h3>
+
+In the
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/spec/security-spec.doc1.html#21150">Java security architecture</a>,
+an
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/spec/security-spec.doc4.html#20389">access control mechanism</a>
+is presented in which the concept of a <i>protection domain</i>,
+encapsulated by the
+<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/ProtectionDomain.html"><code>ProtectionDomain</code></a>
+class, is discussed. Through the
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/spec/security-spec.doc3.html#20128"><b><i>security policy</i></b></a>,
+a protection domain is mapped to a desired set of
+<b><i>permissions</i></b>, and based on the particular security policy in place, the
+access control mechanism can be used to allow or deny
+access to various resources. To understand security policy and its relation to the protection
+domain of currently executing code, one can view it as a mechanism in which a
+set of permissions are granted to:
+
+<ul>
+ <li><i>Who</i> the code is being executed on behalf of - <b><i>principal(s)</i></b></li>
+ <li><i>What</i> <b><i>class loader</i></b> has loaded the code being executed</li>
+ <li><i>Where</i> the code being executed was obtained from - <b><i>code source</i></b></li>
+</ul>
+
+Note that code source is characterized not only by a
+<i>location</i> - a <code>URL</code> - but also by any
+possible <i>signers</i>.
+<p>
+Through the security policy, permissions may be granted to
+any combination of the items in the list above. That is,
+whereas permissions may certainly be granted to a set of
+classes signed by some set of signers, obtained from a
+particular <code>URL</code> and loaded by a given class loader,
+and running as a particular set of principals, permisssions
+may also be granted to code simply executing on behalf of
+a set of principals, with no regard to class loader or code
+source; or to code based on only the location from which the
+code was obtained, etc.
+<p>
+
+<h4>Security policy file format</h4>
+
+Security policy
+<a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/spec/security-spec.doc3.html#20131">file format</a>
+provides the mechanism for specifying the "who" and "where" to
+which permissions will be granted. With respect to the "what"
+of the protection domain, note that class loaders provide no
+means for unique identification; therefore, there is no way to
+reference a specific class loader in a security policy file.
+For example, consider the following <i>grant entries</i> that
+might appear in a security policy file:
+
+<pre>
+ grant codeBase "file:lib/phoenix.jar" principal "phoenix" {
+ permission java.lang.RuntimePermission "accessDeclaredMembers";
+ permission java.lang.RuntimePermission "shutdownHooks";
+ };
+
+ grant principal "phoenix" {
+ permission com.sun.jini.phoenix.SystemPermission "com.sun.jini.phoenix.activeGroup";
+ permission com.sun.jini.phoenix.SystemPermission
+ "java.rmi.activation.ActivationSystem.activeGroup";
+ permission com.sun.jini.phoenix.SystemPermission
+ "java.rmi.activation.ActivationSystem.shutdown";
+ };
+
+ grant codebase "file:lib/phoenix.jar" {
+ permission java.lang.RuntimePermission "getClassLoader";
+ permission java.lang.RuntimePermission "getProtectionDomain";
+ };
+
+ grant {
+ permission java.util.PropertyPermission "customProp1", "read";
+ permission java.util.PropertyPermission "customProp2", "read";
+ };
+
+ grant codebase "file:lib/jsk-platform.jar" {
+ permission java.security.AllPermission;
+ };
+
+ grant {
+ permission java.security.AllPermission;
+ };
+</pre>
+
+Because security policy file format does not allow one to
+specifically indicate a class loader to which to grant permissions,
+the above grant entries present examples of permissions being
+granted to various combinations of principal(s) and code source.
+For example, the first entry grants the indicated permissions to
+only the code from the local JAR file indicated in the
+<code>file:</code> URL, with the additional restriction that the
+code from that source must be executing as the indicated principal.
+Compare this with the second entry. That entry grants the indicated
+permissions to code from <i>any source</i>, so long as that code is
+running as the given principal. Alternatively, in the third entry,
+the indicated permissions are granted to code running as
+<i>any principal</i>, but only so long as the code was obtained from
+the indicated code source location.
+<p>
+Moving down the list, the fourth entry grants the indicated permissions
+(but only those specific permissions) to code from <i>any source</i>,
+running as <i>any principal</i>, and the entry after that, grants
+<i>all permissions</i>
+(<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/AllPermission.html"><code>java.security.AllPermission</code></a>)
+to specific code with no restriction on principal; that is, code from
+the specific source indicated, executing as any principal. Finally,
+the last entry grants <i>all permissions</i> to <i>all code</i>, no
+matter what principal(s) that code may, or may not, be running as.
+<p>
+
+<h4>Terminology</h4>
+
+In the discussions below, the term <i>party</i> (or <i>parties</i>) may
+be used at times to generally refer to the entities to which a particular
+set of permissions are granted. For example, when discussing a grant
+entry like the first one above, one might refer to granting the
+permissions contained in that entry to the <i>party</i> who is both
+located at <code>lib/phoenix.jar</code>, and who has logged in (or
+authenticated) as the principal <code>phoenix</code>. Similarly, when
+discussing the second grant entry, one might talk about granting
+the indicated permissions to any parties who have simply authenticated
+as the principal <code>phoenix</code>.
+
+<h4>Security policy principles</h4>
+
+The following principles embody the general philosophy of the
+security policy demonstrated in this example through the configurations
+and security policy files discussed below. The model presented here
+is general in nature and fairly broad in its applicability. Therefore,
+your own applications may require the specification of a different set
+of principles.
+
+<ol>
+ <li><i>All permissions</i> is <b><i>never ever</i></b> granted to all
+ parties (any code source, any principal).
+ </li>
+ <li><i>All permissions</i> is only granted to parties from <i>local</i>,
+ trusted sources.
+ </li>
+ <li>For non-secure configurations, under certain conditions,
+ <i>specific permissions</i> may be granted to all parties
+ (all code, any principal).
+ </li>
+ <li>For secure configurations, server-side access control is provided
+ through security policy. That is, from the <i>server side</i> of a
+ remote call, <i>access permission</i> allowing the invocation of
+ a remote method should only be granted to parties who are trusted
+ to make use of that method.
+ </li>
+</ol>
+
+Recall that the security model specified by Jini technology
+provides mechanisms that emphasize security in the face of
+<b><i>remote calls and downloaded code</i></b>. Each of the
+principles above attempts to acknowledge this aspect of security
+policy in a Jini technology-based application.
+
+<p>
+<b><i>Principle 1 - never grant "all permissions" to all parties</i></b>
+<p>
+To understand the importance of the first principle, consider the
+situation where that principle is violated. When an entity grants
+"all permissions" to all code, the code to which "all permissions" is
+granted will include any code that is downloaded from remote sources;
+that is, <i>foreign</i> code, which is not necessarily trusted. This
+can pose a significant security risk because access to all of the
+granting entity's resources is being provided to parties that may
+be both unknown and untrusted. Thus, to prevent exposure to the
+risks presented when "all permissions" is granted to all code, each
+of the <a href="#all-policy-files">policy files</a> provided with
+this example satisfies the first principle.
+<p>
+<b><i>Principle 2 - only grant "all permissions" to local code</i></b>
+<p>
+The second principle is designed to provide some flexibility to the
+policy, without sacrificing security. What is meant by the term
+<i>local code</i>, as it is used in that principle, is code that has
+been obtained from a trusted source and that has been installed locally
+on your system. For example, consider the JDK (or JRE) code you are
+running. Presumably, you obtained this code from a vendor that you
+trust will not supply a JDK or JRE that does "bad things". Even if
+the version of Java you are using was not installed by you, it was
+probably pre-installed by the (trusted) vendor who supplied your
+system. Similarly, the Apache River release itself was obtained from a
+trusted source (the Jini team), and was installed by someone you must
+certainly trust - you! Code that is installed and runs locally (including
+your own application code) can be safely granted "all permissions"
+because you know its source, and you trust that it will not behave
+badly.
+<p>
+Another way of viewing local code is as "code that is <b><i>not downloaded</i></b>
+during the execution of the application". To understand this, consider
+the policy file for both the
+<a href="config/reggie.policy">basic configuration</a> and the
+<a href="config/ssl-reggie.policy">SSL configuration</a> of Reggie
+from the <a href="#all-policy-files">lists below</a>. In both files,
+you will see that "all permissions" is granted to the JAR files from only
+the <a href="../../../../../../../lib"><code>lib</code></a> directory
+of the Apache River release, with no entries granting "all permissions" to
+<code>http: URL</code>s referencing any of the JAR files from the
+<a href="../../../../../../../lib-dl"><code>lib-dl</code></a> directory.
+Recall that files such as <code>jsk-platform.jar</code>,
+<code>reggie.jar</code>, etc. are contained in the Apache River release's
+<code>lib</code> directory whereas only <i>downloadable</i> JAR
+files (such as <code>jsk-dl.jar</code>, <code>reggie-dl.jar</code>, etc.)
+are contained in the <code>lib-dl</code> directory. The pattern
+promoted by the Apache River release is that the JAR files from the
+<code>lib</code> directory are expected to be locally installed,
+not downloaded; whereas the JAR files contained in the <code>lib-dl</code>
+directory are expected to be downloaded. Thus, another way of stating
+the second principle is, "never grant <i>all permissions</i> to downloaded code".
+<p>
+<b><i>Principle 3 - specific permissions may be granted to all parties (non-secure configurations)</i></b>
+<p>
+With respect to an application of the third principle, one might
+wonder why configurations that are labelled as "non-secure" are
+concerned with fine grained security such as that expressed in the
+principle; or any security at all for that matter. It should be
+clear from the first two principles that the term "non-secure",
+as it is applied to the configurations described in this document,
+does not equate with "no security at all". Rather, that term is
+meant to imply that the mechanisms of the Jini technology security
+model, mechanisms that provide items such as authentication, authorization,
+confidentiality, integrity, and trust verification, are not employed
+when remote calls are made and code is downloaded. But this does
+not mean that access to all other aspects of an entity's resources
+should be granted to other parties. The position taken by this
+example, as expressed in the third principle, is that it still
+makes good sense to use the mechanisms of the standard Java
+security model to allow open access to only those resources that
+are necessary and can be considered low risk. In this way,
+functionality can be provided while minimizing one's vulnerability
+to attacks from third parties.
+<p>
+A concrete example of the third principle above can be seen in the
+<a href="config/phoenix.policy">policy file</a> for the basic
+configuration of Phoenix. In that file you will notice an
+entry that grants various instances of
+<a href="../../../../../../../doc/api/com/sun/jini/phoenix/ExecOptionPermission.html"><code>ExecOptionPermission</code></a>
+to all parties. To understand the need for that permission, recall
+that Phoenix spawns a VM, referred to as an
+<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/activation/ActivationGroup.html"><i>activation group</i></a>,
+in which the server to be activated will be executed. When starting
+the activation group, a number of options and properties are usually
+set. To see the properties and options that are set for the activation
+group under the basic configuration, examine the contents of the
+<a href="config/start-activatable-jeri-server.config">configuration file</a>
+for the class that is used to start the activatable form of the
+server under Jini ERI. To see how those options and properties
[... 414 lines stripped ...]