river-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From peter_firmst...@apache.org
Subject svn commit: r1634322 [25/41] - in /river/jtsk/skunk/qa_refactor/trunk: qa/src/com/sun/jini/qa/harness/ qa/src/com/sun/jini/test/impl/end2end/e2etest/ qa/src/com/sun/jini/test/impl/joinmanager/ qa/src/com/sun/jini/test/impl/mahalo/ qa/src/com/sun/jini/t...
Date Sun, 26 Oct 2014 13:17:31 GMT
Modified: river/jtsk/skunk/qa_refactor/trunk/src-doc/static/arch2_0.html
URL: http://svn.apache.org/viewvc/river/jtsk/skunk/qa_refactor/trunk/src-doc/static/arch2_0.html?rev=1634322&r1=1634321&r2=1634322&view=diff
==============================================================================
--- river/jtsk/skunk/qa_refactor/trunk/src-doc/static/arch2_0.html (original)
+++ river/jtsk/skunk/qa_refactor/trunk/src-doc/static/arch2_0.html Sun Oct 26 13:17:28 2014
@@ -1,1244 +1,1227 @@
-<!--
- ! 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>
-<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
-      vlink="#cc1877" alink="#ffffff">
-
-<title>Jini Specification Overview - Apache River Release v3.0.0</title>
-<a name="TOP">
-<center><h1>Jini Specification Overview<br>
-    Apache River Release v3.0.0</h1></center>
-
-<br>
-
-<p>This document provides an overview of the implementation details of
-Jini Specifications included in Apache River and
-explains how these components fit together.  Much of this
-information is available in the package, interface, and class
-documentation, but this document provides a higher-level overview
-and indicates where to find more information.
-
-
-<h2>1 Overview of Jini Architecture</h2>
-
-<p>The Jini system architecture consists of three categories:
-<i>programming model</i>, <i>infrastructure</i>, and <i>services</i>.
-The original <a href="../doc/specs/html/jini-spec.html"><i>Jini
-Architecture Specification Version 1.0</i></a> defines these categories as follows:
-
-<blockquote>
-    The infrastructure is the set of components that enables
-    building a federated Jini system, while the services are the
-    entities within the federation.  The programming model is a
-    set of interfaces that enables the construction of reliable
-    services, including those that are part of the infrastructure
-    and those that join into the federation.
-</blockquote>
-
-<p>Originally, the programming model defined models for leasing, event
-notification, and transactions.  The basic infrastructure consisted of
-the discovery/join protocol and the lookup service.  Previous versions
-delivered implementations of the following Jini
-technology-enabled services (Jini services):
-
-<ul>
-<li> Lookup Service (reggie)
-<li> Transaction Manager Service (mahalo)
-<li> Lease Renewal Service (norm)
-<li> Event Mailbox Service (mercury)
-<li> Lookup Discovery Service (fiddler)
-<li> JavaSpaces Service (outrigger)
-</ul>
-
-<p>Apache River releases following and including the Jini v2.0 release add
-components to the first two
-categories (programming model and infrastructure) of the Jini
-architecture, although some components span both of these categories.
-Additionally, this release provides updates to existing services to
-account for the additions to the infrastructure and the programming
-model.  The component additions can be summarized as follows:
-
-<p><i>Additions to Programming Models</i>
-<ul>
-<li><a href="api/net/jini/config/Configuration.html">Configuration</a>
-<li><a href="api/net/jini/export/Exporter.html">Exporter</a>
-<li><a href="api/net/jini/security/ProxyPreparer.html">ProxyPreparer</a>
-</ul>
-
-<p><i>Additional Infrastructure</i>
-<ul>
-<li><a href="api/net/jini/security/package-summary.html">Security</a>
-<li><a href="api/net/jini/core/constraint/package-summary.html">Invocation Constraints</a>
-<li><a href="api/net/jini/jeri/package-summary.html">Jini extensible
-remote invocation (Jini ERI)</a>
-<li><a href="api/net/jini/security/policy/package-summary.html">Dynamic Policy</a>
-<li><a href="api/net/jini/loader/pref/package-summary.html">Preferred Class Loading</a>
-<li><a href="api/com/sun/jini/discovery/package-summary.html">Discovery Protocol v2</a>
-</ul>
-
-<p><i>Configuring Services</i>
-
-<p>Each service included in Apache River supports being
-configured using a <code>Configuration</code>.  Most of the
-services were previously configured via system properties.  These
-services can now be configured via entries in the configuration.
-New types of behavior that can be configured are remote service
-exporting and proxy preparation.</p>
-
-<h3>1.1 Goals</h3>
-
-The main goals for the additions in the Jini architecture are to:
-
-<ul>
-<li> Add support for secure Jini technology-based programs (Security infrastructure)
-<li> Provide mechanisms to configure applications (<code>Configuration</code>)
-<li> Unify client-side and server-side programming models
-     (<code>ProxyPreparer</code> and <code>Exporter</code>)
-<li> Provide a Java(TM) Remote Method Invocation (Java RMI)
-     implementation that supports pluggable invocation layer behavior
-     and pluggable transport providers (Jini ERI)
-</ul>
-
-<p>The primary motivation for augmenting the Jini architecture
-is to provide the new programming models and infrastructure
-necessary to support and manage security in Jini technology-based
-distributed applications.  The previous Jini architecture lacked
-direct support for a type of security many Jini / Apache River applications
-need, namely basic network security for remote calls to
-services.  This goal is addressed by the new security
-infrastructure and constraint-based remote invocation model.
-
-<p>Another important goal for this release is to better unify the
-overall programming model for service developers, given the
-previous lack of uniformity in the APIs for implementing,
-exporting, and deploying services.  Securing remote invocation
-requires additional client-side verification steps, so this
-release introduces a uniform client-side API to handle a
-"preparation" step before remote invocation.  Additionally,
-application developers can ease deployment tasks by separating
-out deployment-time information from the application.  The
-<code>Configuration</code> API introduced in the Jini 2.0 release
-provides a simple and uniform way to obtain deployment-specific
-information.  The resulting programming model supports a uniform
-framework for pluggable security, exporter, transport, and other
-service providers.
-
-<p>A final goal is to provide an implementation of the Java RMI
-programming model that supports constraints on remote invocation
-(which is crucial to the security model), and supports pluggable
-invocation and dispatch behavior as well as pluggable transport
-providers on a per-object basis, features which are lacking in the
-JRMP implementation of Java 2 SDK, Standard Edition (J2SE(TM)) RMI.
-The Jini ERI API provides such a pluggable implementation of the Java
-RMI programming model.
-
-
-<h2>2 Programming Model</h2>
-
-<p>Before delving into the discussion of the security
-architecture, it is important to understand initially a few
-additional programming models, <code>Configuration</code>,
-<code>Exporter</code>, and <code>ProxyPreparer</code>, each of
-which simplifies application development in general and secure
-application development in particular.
-
-<h3>2.1 <code>Configuration</code> </h3>
-
-An application is much easier to test, deploy, and evolve
-when the application's source code is not tied directly to specific
-deployments, but instead uses a level of abstraction, such as
-service provider interfaces.  Such applications may separate out
-deployment-specific information from the application source code,
-allowing this information to be configured at deployment time.  The
-obvious benefit of this approach is that the application can be
-configured to use the implementations that the deployment requires
-without having to change the application source code.  If
-deployment needs change, only the configuration must change;  the
-application can remain intact.
-
-<p>The <code>net.jini.config.Configuration</code> API supports this
-approach by providing a simple, uniform way to obtain the objects
-needed to configure an application.  An application can obtain an
-object from a <code>Configuration</code> instead of explicitly
-constructing an instance to avoid tying the application to
-deployment-specific implementations.  Typical objects that should be
-obtained from a configuration are <code>Exporter</code> and
-<code>ProxyPreparer</code> instances (discussed below).
-
-<p>An application may not want to be tied to a specific implementation
-of <code>Configuration</code> either, so an application can use
-<code>net.jini.config.ConfigurationProvider</code> to obtain a
-<code>Configuration</code> implementation.  Using the
-<code>ConfigurationProvider</code> in an application allows the
-application's deployer to specify the most suitable
-<code>Configuration</code> implementation at deployment time.
-A given <code>Configuration</code> implementation might
-read configuration information from a file, a database,
-or from some other source.
-
-<p>The standard, default <code>Configuration</code> implementation is
-<code>net.jini.config.ConfigurationFile</code>.  This implementation
-reads configuration information, written in a subset of the syntax of
-the Java programming language, from files and URLs to produce objects
-from the configuration.  See the <a href="api/net/jini/config/package-summary.html"><code>net.jini.config</code> package
-documentation</a> for an example of how an application can use a
-<code>Configuration</code> and how a deployer can use a
-<code>ConfigurationFile</code> source file to configure that
-application. 
-
-<h3>2.2  <code>Exporter</code> and the Server-Side Implementation Model </h3>
-
-<p>In Jini technology-based applications, invoking a method on a
-Jini service proxy has a uniform client-side model: a client
-simply invokes a method on the service's proxy to initiate remote
-communication to the service object, an invocation that follows
-the same general semantics as the Java RMI model.
-
-<p>The server-side implementation model for Jini / Apache River applications,
-however, is not uniform.  An application developer typically
-implements a service and exports that service in a way that ties
-the service directly to a specific implementation and model of
-remote communication.  This implementation dependence requires
-that the application source code be modified if the service needs
-to be exported in a slightly different way. For example, an
-application deployment may need to export a service to use a
-different port or socket factory, or may need to export that
-service using a different implementation of remote communication
-entirely, such as a different implementation of the Java RMI
-programming model.
-
-<p>The <code>net.jini.export.Exporter</code> interface unifies the
-server-side implementation model by providing an abstraction for
-exporting and unexporting a remote object.  The details of export and
-unexport behavior, including communication protocols used for remote
-invocation and additional invocation semantics, are defined by the
-particular implementation of the <code>Exporter</code> interface.
-
-<p>Several standard <code>Exporter</code> implementations, which are
-also implementations of the Java RMI programming model, are provided.  
-The following table lists these
-implementations along with the class whose behavior the exporter is
-semantically equivalent to.
-
-<p>
-<blockquote>
-<table summary="Describes the standard Exporter implementations"
-       border=1 cellpadding=5>
-<th> <code>Exporter</code> <th>Equivalent Class
-<tr> <td> <code>net.jini.jrmp.JrmpExporter</code>
-     <td> <code>java.rmi.server.UnicastRemoteObject</code>
-<tr> <td> <code>net.jini.iiop.IiopExporter</code>
-     <td> <code>javax.rmi.PortableRemoteObject</code>
-<tr> <td> <code>net.jini.jeri.BasicJeriExporter</code>
-     <td> itself
-</table>
-</blockquote>
-
-<p>An application can use a <code>Configuration</code> together with
-the <code>Exporter</code> interface to export remote objects in a way
-that can be configured at deployment time.  The following example
-(similar to those in the <a href="api/net/jini/config/package-summary.html"><code>net.jini.config.Configuration</code>
-package documentation</a>) illustrates configurable exporting:
-
-<pre>
-    import java.rmi.*;
-    import net.jini.config.*;
-    import net.jini.export.*;
-    public class Example implements Remote {
-        public static void main(String[] args) throws Exception {
-            Configuration config = ConfigurationProvider.getInstance(args);
-            Exporter exporter = (Exporter) config.getEntry(
-                "Example", "exporter", Exporter.class);
-            Remote proxy = exporter.export(new Example());
-            System.out.println(proxy);
-            exporter.unexport(true);
-        }
-    }
-</pre>
-
-<p>This application can be configured by specifying the following
-configuration file (that uses <code>ConfigurationFile</code>
-syntax) as a command line argument.  The configuration file
-specifies the exporter to be a <code>JrmpExporter</code>, an
-exporter that produces proxies that participate in the JRMP
-protocol.
-
-<pre>
-    import net.jini.jrmp.*;
-    Example {
-        exporter = new JrmpExporter();
-    }
-</pre>
-
-<p>Alternatively, the application can be deployed to specify the
-exporter to be a <code>BasicJeriExporter</code> (an exporter for
-exporting a remote object to use Jini ERI) constructed to export the
-object on an anonymous TCP port.
-
-<pre>
-    import net.jini.jeri.*;
-    import net.jini.jeri.tcp.*;
-    Example {
-        exporter = new BasicJeriExporter(TcpServerEndpoint.getInstance(0));
-    }
-</pre>
-
-<h3>2.3  <code>ProxyPreparer</code> and the Client-Side Invocation Model </h3>
-
-<p>The new security model (discussed below) requires the application
-to perform some pre-invocation "preparation" of a service proxy before
-invoking its methods.  This is because an application may receive the
-service proxy from an untrusted source.  Therefore, before an
-application uses a proxy, that application might need to perform
-operations such as verifying trust in the proxy or granting
-permissions to the proxy once its trust has been verified.
-
-<p>These security requirements add an additional step to the
-client-side invocation model.  The
-<code>net.jini.security.ProxyPreparer</code> interface abstracts the
-operation of "proxy preparation" into a single method,
-<code>prepareProxy</code>, so that the client-side invocation model
-can be uniform across applications using secure and non-secure
-proxies.
-
-<p>A <code>ProxyPreparer</code> can be used together with a
-<code>Configuration</code> to allow configurable proxy preparation.
-The following is a code snippet from the <a
-href="../source/src/com/sun/jini/example/hello/index.html"><i>hello</i>
-example</a> client, which is part of a comprehensive example included
-in the Apache River release:
-
-<p>
-<pre>
-    ProxyPreparer preparer = (ProxyPreparer) config.getEntry(
-        "com.sun.jini.example.hello.Client",
-	"preparer", ProxyPreparer.class, new BasicProxyPreparer());
-    server = (Hello) preparer.prepareProxy(server);
-    System.out.println("Server says: " + server.sayHello());
-</pre>
-
-<p>The call to <code>getEntry</code> supplies a default (<code>new
-BasicProxyPreparer()</code>) for the entry that will be returned if
-the configuration file does not have the specified entry.  A
-<code>net.jini.security.BasicProxyPreparer</code> instance can be
-constructed with arguments specifying whether a proxy, passed to its
-<code>prepareProxy</code> method, needs to be verified or needs other
-security-related operations to be performed.  A
-<code>BasicProxyPreparer</code> constructed with no arguments, which
-is the default above, specifies a "do nothing"
-<code>ProxyPreparer</code> that simply returns the proxy passed to the
-<code>prepareProxy</code> method.
-
-<p>If an application deployment has security requirements, the
-application can be deployed with a <code>BasicProxyPreparer</code>
-constructed with the appropriate arguments or can be
-deployed with an alternate <code>ProxyPreparer</code> implementation.
-
-
-<h2>3 Security</h2>
-
-<p>In a typical Jini technology-based application, a client obtains a
-service proxy from somewhere (for example, from a lookup service or as
-a result of communicating with another service) and then invokes
-methods on that proxy to communicate with the service.  Many
-applications have a need to secure such remote communication,
-requiring one or more of the following:
-
-<ul>
-<li> Mutual authentication (client and server)
-<li> Authorization (access control)
-<li> Integrity (cryptographic checksums)
-<li> Confidentiality (encryption)
-</ul>
-
-<p>These requirements are typical for securing <i>data</i>
-communication; however, the Jini security model has an additional
-requirement: <i>code</i> integrity.  In the Jini and Java RMI model,
-an object's data is sent in a remote invocation, but its code is
-downloaded out-of-band as a result of that remote invocation.  An
-application needs to establish trust for the <i>objects</i> it
-receives, both in the integrity of an object's code as well as in its
-data.
-
-<p>This release provides a framework for trust verification as well as
-a constraint-based remote invocation model that enables an application
-to specify various requirements (such as security requirements) on
-remote invocations.  The infrastructure also provides mechanisms that
-can be used to ensure code integrity.
-
-<h3>3.1 Constraints and Remote Invocation</h3>
-
-<p>The security requirements described above can be expressed as
-<i>constraints</i> on remote invocation.  A constraint is a specific
-requirement, set by the client, on the behavior of remote invocations
-through a proxy to its associated service.  A proxy can implement the
-interface <code>net.jini.core.constraint.RemoteMethodControl</code> to
-enable a client to set constraints on remote invocation through
-that proxy.  The constraint-based remote invocation model is general,
-providing for security-related constraint types as well as other
-constraint types.
-
-<p>One example use of constraints is a client that needs to authenticate
-the identity of a service (such as a bank) before communicating with
-it through its proxy.  In this example, the service proxy can
-implement the interface <code>RemoteMethodControl</code> to enable a
-client to set a constraint requiring server authentication on any
-remote invocation through that proxy.  It is the proxy's
-responsibility to satisfy those constraints, but it is the client's
-responsibility to verify that it can trust the proxy to carry out its
-responsibility (discussed below).
-
-<p>Each constraint is represented as a
-<code>net.jini.core.constraint.InvocationConstraint</code> instance.
-An <code>InvocationConstraint</code> instance expresses "what" but not
-"how"; that is, a constraint expresses "what" the constraint
-represents, but not "how" the constraint should be satisfied.  A proxy
-is responsible for using the appropriate transport and protocols to
-satisfy the constraints set by the client.  Because constraints are
-expressed abstractly, the security implementations are pluggable and
-thus are capable of supporting a wide variety of protocols such as
-Secure Socket Layer (SSL) and Kerberos.  See the
-<a href="api/net/jini/core/constraint/package-summary.html"><code>net.jini.core.constraint</code> package documentation</a> for
-general information on constraints including a number of pre-defined
-basic constraints.
-
-<p>Before a client sets constraints on a proxy, the client first needs
-to verify that it can trust the proxy to carry out the constraints to
-be set, because the proxy may have been received from an untrusted
-source.  If the client does not verify that the proxy is trusted,
-there is a danger that the proxy could simply ignore the client's
-constraints and perform unencrypted data transfer, misrepresent the
-client's or server's identity, or worse.  After the client verifies
-trust in the proxy, it can then set constraints on the proxy to
-specify any desired security requirements, such as server
-authentication.
-
-<p>Once a client trusts a proxy, it may also need to grant additional
-permissions to the proxy, over and above the minimal permissions
-typically configured in advance for untrusted code, so that future
-invocations through the proxy function properly.  A proxy may require
-<code>net.jini.security.AuthenticationPermission</code> so that it can
-authenticate with the server, for example.  A client must not grant
-permissions to the proxy before it trusts the proxy, so that the proxy
-cannot abuse the grants in a way that might cause harm.
-
-<p>To summarize, a client receiving a proxy from an untrusted source
-needs to "prepare" the proxy in the following manner before invoking
-that proxy's methods.  The full requirements for each of these steps
-are described in the <a href="api/net/jini/security/package-summary.html"><code>net.jini.security</code> package documentation</a>:
-
-<ul>
-<li>Verify trust in the proxy
-<li>Grant permissions to the proxy
-<li>Set constraints on (a copy of) the proxy
-</ul>
-
-<p>The steps above can be encapsulated in a single operation known as
-<i>proxy preparation</i>, a term which means "preparing the proxy for
-remote invocation".  The client-side interface
-<code>net.jini.security.ProxyPreparer</code> (discussed above)
-encapsulates such proxy preparation into a single method,
-<code>prepareProxy</code>.
-
-<p>The class <code>net.jini.security.BasicProxyPreparer</code>, a
-standard implementation of the <code>ProxyPreparer</code> interface,
-performs the three necessary steps above to prepare a proxy for secure
-remote calls.  Most deployers can use a
-<code>BasicProxyPreparer</code> instance for proxy preparation and not
-worry about all the details behind trust verification (which are
-outlined in some detail below).  Other applications may need to subclass
-<code>BasicProxyPreparer</code> if verifying trust, setting
-constraints, and/or granting permissions require some customization.
-
-
-<h3>3.2 Proxy Preparation Using <code>BasicProxyPreparer</code></h3>
-
-
-<p>The <code>BasicProxyPreparer</code> class encapsulates the three steps
-of verifying trust, setting constraints, and granting permissions to a
-proxy.  A <code>BasicProxyPreparer</code> instance can be constructed
-in a variety of ways, supporting many common cases for proxy
-preparation including the following:
-
-<ul>
-
-<li> <i>Verify trust, grant permissions, and set new constraints</i>:
-to prepare a proxy received from an untrusted source.
-
-<li> <i>Set new constraints</i>: to prepare a trusted proxy received
-with integrity protection from a trusted source that is not known to
-supply the appropriate constraints.
-
-<li> <i>Grant permissions</i>: to prepare a trusted proxy received
-with integrity protection from a trusted source that supplies
-appropriate constraints, if the proxy needs permission grants.
-
-<li> <i>Do nothing</i>: to use as a default when retrieving an
-optional configuration entry, or to prepare a non-secure proxy.
-
-</ul>
-
-<p>Static methods <code>Security.verifyObjectTrust</code> and
-<code>Security.grant</code> of the
-<code>net.jini.security.Security</code> class implement the trust
-verification and permission granting mechanisms, respectively.
-Constraints can be set on the proxy implementing the
-<code>RemoteMethodControl</code> interface by calling its
-<code>setConstraints</code> method.  A
-<code>BasicProxyPreparer</code> uses these three mechanisms to
-implement the specifics of proxy preparation.
-
-<p>The next three sections describe the mechanics of proxy preparation
-using a <code>BasicProxyPreparer</code> instance that performs all three
-steps.  For the purposes of this discussion, let's assume that a
-<code>BasicProxyPreparer</code> is constructed as follows:
-
-<pre>
-    new BasicProxyPreparer(true, <i>constraints</i>, <i>permissions</i>)
-</pre>
-
-<p>where the argument <code>true</code> indicates that the proxy
-should be verified for trust, <i>constraints</i> is a
-<code>MethodConstraints</code> object (an object containing the
-per-method constraints to set on the proxy), and <i>permissions</i> is
-an array containing the <code>java.security.Permission</code>s to be
-granted to the proxy.
-
-<p>The UML sequence diagrams (PDF files) referred to in the
-next three sections illustrate the proxy preparation and trust
-verification processes.  Together, these diagrams depict a full scenario
-of verifying trust, granting permissions, and setting constraints:
-
-<ul>
-
-<li><a href="proxypreparation.pdf">Proxy Preparation (Figure 1)</a>:
-illustrates verifying trust, granting permissions, and setting new
-constraints on a proxy.
-
-<li> <a href="simpleproxyverification.pdf">Non-Smart Proxy Trust
-Verification (Figure 2)</a>: shows verifying trust of a non-smart proxy
-(for example, a simple Jini ERI proxy) using a
-<code>ProxyTrustVerifier</code>. 
-
-<li> <a href="smartproxyverification.pdf">Smart Proxy Trust
-Verification (Figure 3)</a>: shows verifying trust of a smart proxy using a
-<code>ProxyTrustVerifier</code>. 
-
-</ul>
-
-<p>Note: See this tutorial for <a
-href="http://www.togethersoft.com/services/practical_guides/umlonlinecourse/index.html#sequence-diagrams">a
-description of the syntax of UML sequence diagrams</a>.
-
-<p>Note that the <code>BasicProxyPreparer</code> class is designed to be
-subclassable, therefore the implementation of the
-<code>prepareProxy</code> method invokes <code>protected</code>
-methods on the instance (<code>verify</code>, <code>grant</code>,
-<code>setConstraints</code>, etc.) to allow a potential subclass to
-customize the instance behavior.
-
-<h4>3.2.1 Verifying Trust</h4>
-
-
-<p>The basic model for verifying trust in an object received from an
-untrusted source is to consult one or more <i>trust verifiers</i> (of
-type <code>net.jini.security.TrustVerifier</code>) that are
-essentially part of the "trusted computing base" (a term which means
-the platform's hardware and software that is fully trusted to enforce
-the security mechanisms and policies in place) to see if at least one
-of those verifiers trusts the object in question.  If one trust
-verifier is unable to verify trust, then another one is consulted.
-This trust verification process is carried out by the
-<code>static</code> method <code>Security.verifyObjectTrust</code>.
-
-<p>The <code>Security.verifyObjectTrust</code> method obtains trust
-verifiers from a resource,
-<code>META-INF/services/net.jini.security.TrustVerifier</code>, which,
-in this distribution, is part of the file
-<code>jsk-resources.jar</code>, which is referenced by
-<code>jsk-platform.jar</code>.  These built-in trust verifiers are
-provided to verify instances of classes in the Apache River release.  The
-following table lists these trust verifier implementations along with
-a description of the instances they verify:
-
-<blockquote>
-<table summary="Describes the standard TrustVerifier implementations"
-       border=1 cellpadding=5>
-<th> <code>TrustVerifier</code> <th> Verified Instances
-
-<tr> <td valign="top"> <code>net.jini.constraint.<br>ConstraintTrustVerifier</code>
-     <td valign="top"> constraint classes in <code>net.jini.core.constraint</code>
-<tr> <td valign="top"> <code>net.jini.jeri.<br>BasicJeriTrustVerifier</code>
-     <td valign="top"> proxy produced by <code>BasicJeriExporter.export</code>,
-if the proxy's invocation handler is a standard
-<code>BasicInvocationHandler</code> instance containing a
-<code>BasicObjectEndpoint</code> instance, the proxy's class
-loader is trusted, and the proxy's server constraints and
-<code>Endpoint</code> are trusted
-
-<tr> <td valign="top"> <code>net.jini.jeri.ssl.<br>SslTrustVerifier</code>
-     <td valign="top"> client-related classes in the <code>net.jini.jeri.ssl</code> package
-<tr> <td valign="top"> <code>net.jini.jeri.kerberos.<br>KerberosTrustVerifier</code>
-     <td valign="top"> client-related classes in the <code>net.jini.jeri.kerberos</code> package
-<tr> <td valign="top"> <code>net.jini.security.proxytrust.<br>ProxyTrustVerifier</code>
-     <td valign="top"> proxy that can be verified by obtaining a trust verifier from the proxy's server
-<tr> <td valign="top"> <code>net.jini.discovery.<br>ConstrainableLookupLocatorTrustVerifier</code>
-     <td valign="top"> <code>ConstraintableLookupLocator</code> instances
-<tr> <td valign="top"> <code>com.sun.jini.discovery.<br>DiscoveryConstraintTrustVerifier</code>
-     <td valign="top"> discovery constraints
-</table>
-</blockquote>
-
-<p>Most clients will use one or more of the trust verifiers above
-(indirectly) when verifying trust in a proxy.  However, a service will
-need to implement a special trust verifier for a smart proxy, or for a
-proxy produced by <code>BasicJeriExporter</code>.
-
-<p>Proxy preparation is initiated by invoking the
-<code>prepareProxy</code> method on a <code>BasicProxyPreparer</code>
-instance (constructed as above, with <i>verify</i> set to
-<code>true</code>), passing it the <i>proxy</i> to be prepared (see <a
-href="proxypreparation.pdf">Figure 1</a>).  The
-<code>BasicProxyPreparer</code> instance initiates trust verification
-by invoking the <code>Security.verifyObjectTrust</code> method,
-passing the <i>proxy</i>, the value <code>null</code> (<i>loader</i>) to
-specify the context class loader, and the <i>constraints</i> (obtained
-from the instance itself) to use on any remote communication by the
-trust verification mechanism.
-
-<p>The <code>Security.verifyObjectTrust</code> method obtains the
-trust verifiers from the resource in the specified <i>loader</i> (if
-the trust verifiers have not already been obtained) and creates a
-<code>net.jini.security.TrustVerifier.Context</code> (<i>context</i>)
-containing the ordered list of trust verifiers.  Next, the
-<code>isTrustedObject</code> method of each trust verifier is invoked,
-passing it the proxy to be verified and the trust verifier context,
-until one trust verifier returns <code>true</code>.  A given trust
-verifier will return <code>true</code> if it can verify trust in the
-object passed to it.  A trust verifier may also use the context passed
-to verify other component objects recursively, before deciding
-whether it trusts the object.
-
-<p>The <code>Security.verifyObjectTrust</code> method returns
-<code>true</code> if there is at least one trust verifier in the
-context that trusts the proxy.
-
-<p>A <code>net.jini.security.proxytrust.ProxyTrustVerifier</code>
-can verify a service proxy for which a trusted verifier can be obtained
-from the service's remote object in a pre-defined manner,
-requiring cooperation with the proxy and the service's
-remote object.  The two typical cases that
-<code>ProxyTrustVerifier</code> handles are: verifying non-smart
-proxies (for example, a simple proxy returned by
-<code>BasicJeriExporter</code>) and verifying smart proxies that
-wrap simple (non-smart) proxies.  These cases are described in
-the following two sections.
-
-<p><code>ProxyTrustVerifier</code> implements a trust verification
-mechanism that uses a trusted <i>bootstrap proxy</i> (either
-derived or obtained from the original proxy) to obtain a
-trust verifier from the server to use to verify the
-original proxy.
-
-<p>The reasoning behind this trust verification approach is as
-follows: if you trust the service (like your bank), and you
-obtain the trust verifier by communicating with the service
-through a trusted bootstrap proxy with server authentication and
-integrity, then you can trust the verifier returned by the
-service to verify the service proxy.  After all, it is the
-service that knows best how to verify its own proxies.
-
-<h4>Non-Smart Proxy Trust Verification</h4>
-
-<p>If a non-smart proxy that is a dynamic proxy would be directly
-trusted by a local trust verifier if only its proxy class were
-defined by a class loader trusted by such a verifier, then the
-non-smart proxy can implement
-<code>net.jini.security.proxytrust.ProxyTrust</code> so that it
-can be verified by a
-<code>net.jini.security.proxytrust.ProxyTrustVerifier</code>.  In
-this case, the service's remote object must also cooperate
-in <code>ProxyTrustVerifier</code>'s verification scheme by
-providing a <code>TrustVerifier</code> for its proxies as
-described in the section "Implementation Requirements for Trust
-Verification".
-
-<p>The mechanism implemented by <code>ProxyTrustVerifier</code>
-verifies non-smart proxies by performing the following:
-
-<ul>
-<li> Creates a "derivative bootstrap proxy" from the proxy,
-<li> Verifies trust in this derivative bootstrap proxy using the
-     locally trusted verifiers, and then
-<li> Uses the derivative bootstrap proxy to obtain, from the
-     service, a trust verifier for the proxy itself.
-</ul>
-
-<p>The details of this mechanism are implemented by the
-<code>ProxyTrustVerifier.isTrustedObject</code> method (depicted in <a
-href="simpleproxyverification.pdf">Figure 2</a>).
-
-The proxy itself implements <code>ProxyTrust</code> and, as such,
-is considered a bootstrap proxy.  However, this proxy is not
-typically trusted because, in most cases, the proxy's class is
-defined by an untrusted class loader when the proxy is received
-by a remote virtual machine.  In this case if certain conditions
-are met, the <code>ProxyTrustVerifier</code> creates a
-"derivative bootstrap proxy" using a dynamic proxy class defined
-by the parent class loader (which is typically a trusted class
-loader) with the identical invocation handler as the bootstrap
-proxy.  If the derivative bootstrap proxy is trusted by one of
-the locally trusted trust verifiers available in the context
-(determined by invoking <code>isTrustedObject</code> on the
-<code>TrustVerifier.Context</code>), then the derivative
-bootstrap proxy is the bootstrap proxy.
-
-<p>If the derivative bootstrap proxy is trusted, then the
-<code>ProxyTrustVerifier</code> can obtain the trust verifier
-from the service.  The <code>ProxyTrustVerifier</code> first sets
-constraints (obtained from the context) on the derivative
-bootstrap proxy so that it will obtain the trust verifier from
-the server in a secure way.  Next, the
-<code>ProxyTrustVerifier</code> invokes the
-<code>ProxyTrust.getProxyVerifier</code> method on the bootstrap
-proxy to obtain the trust verifier.  This invocation is a remote
-call to a "bootstrap remote object" that implements the
-<code>ProxyTrust</code> interface.  The
-<code>getProxyVerifier</code> implementation can then call the
- <code>ServerProxyTrust.getProxyVerifier</code> method on the
-service (which is a local method call) to obtain the trust
-verifier and then return the result.  Note that the bootstrap
-remote object and the service remote object could be the same object; that is,
-the service object can implement <code>ProxyTrust</code>.  
-If the service's remote object is exported to use
-<code>BasicInvocationDispatcher</code>, a separate bootstrap
-remote object is not needed, nor does the remote object's class
-need to implement <code>ProxyTrust</code>, because
-<code>BasicInvocationDispatcher</code> takes care of these details.
-In this case, however, the service's remote object will still
-need to implement <code>ServerProxyTrust</code> as described in
-the section  <a href="#serverProxyTrust">"Implementing
-<code>ServerProxyTrust</code>"</a>.
-
-<p>After the <code>ProxyTrustVerifier</code> obtains the trust
-verifier from the service, it can then invoke the trust verifier's
-<code>isTrustedObject</code> method, passing it the original service proxy and
-the context, to determine whether the proxy is really a proxy that the
-service trusts.
-
-<h4>Smart Proxy Trust Verification</h4>
-
-<p>Smart proxies or other proxies that do not implement
-<code>ProxyTrust</code> and that cannot be verified directly by the
-built-in trust verifiers can also be verified by
-<code>net.jini.security.proxytrust.ProxyTrustVerifier</code>.  A
-<code>ProxyTrustVerifier</code>, in verifying smart proxies, uses
-some mechanisms in addition to those described above for
-non-smart proxies that implement <code>ProxyTrust</code>
-directly.  As with non-smart proxies verified by
-<code>ProxyTrustVerifier</code>, a smart proxy and its corresponding
-remote object must cooperate in
-<code>ProxyTrustVerifier</code>'s verification mechanism.  The
-implementation requirements for service proxies and their remote objects
-are described in the section "Implementation
-Requirements for Trust Verification".
-
-<p>The mechanism implemented by <code>ProxyTrustVerifier</code>
-verifies smart proxies by performing the following:
-
-<ul>
-<li> Obtains a "bootstrap proxy" from the proxy,
-<li> Verifies trust in the bootstrap proxy using the locally trusted
-     verifiers, and then
-<li> Uses the bootstrap proxy to obtain, from the service, a trust
-     verifier for the proxy itself.
-</ul>
-
-<p>The details of this mechanism are implemented by the
-<code>ProxyTrustVerifier.isTrustedObject</code> method (depicted in <a
-href="smartproxyverification.pdf">Figure 3</a>).  The
-<code>ProxyTrustVerifier</code> uses a special iterator,
-<code>ProxyTrustIterator</code>, to obtain the bootstrap proxy.  This
-special iterator and the bootstrap proxy (from the iterator) are
-obtained as follows.
-
-<p>The <code>ProxyTrustVerifier</code> reflectively invokes a
-(typically private) method, <code>getProxyTrustIterator</code>, on the
-supplied proxy or the supplied proxy's invocation handler to obtain a
-<code>ProxyTrustIterator</code>.  This iterator is used to obtain the
-bootstrap proxy, an object that must implement the interface
-<code>ProxyTrust</code>, which is a remote interface for obtaining a
-proxy trust verifier from the service.  If the object returned from
-the iterator is not a <code>ProxyTrust</code> instance, then a
-<code>ProxyTrustIterator</code> is obtained from the returned object
-recursively.  Otherwise, if the returned object does not implement the
-interface <code>RemoteMethodControl</code>, the
-<code>ProxyTrustIterator</code> is used again to obtain another
-candidate bootstrap proxy.
-
-<p>When the iterator returns a bootstrap proxy implementing
-<code>ProxyTrust</code> and <code>RemoteMethodControl</code>,
-the <code>ProxyTrustVerifier</code>
-verifies trust in the bootstrap proxy by using the locally trusted
-trust verifiers available in the context.  This trust verification
-process is the same as described for the method
-<code>Security.verifyObjectTrust</code>.
-
-<p>If the bootstrap proxy is not trusted by the locally trusted
-verifiers available in the context (that is, the method
-<code>isTrustedObject</code> on the
-<code>TrustVerifier.Context</code> returns <code>false</code>),
-then if certain conditions are met, the
-<code>ProxyTrustVerifier</code> creates a "derivative bootstrap
-proxy" using a dynamic proxy class defined by the parent class
-loader (which is typically a trusted class loader) with the
-identical invocation handler as the bootstrap proxy.  If the
-derivative bootstrap proxy is trusted by one of the locally
-trusted verifiers (determined by invoking
-<code>isTrustedObject</code> on the
-<code>TrustVerifier.Context</code>), then the derivative
-bootstrap proxy can be used as the bootstrap proxy.
-
-<p>Once trust in the bootstrap proxy (or derivative) has been established, the
-<code>ProxyTrustVerifier</code> can obtain the trust verifier from the
-service.  The <code>ProxyTrustVerifier</code> first sets constraints
-(obtained from the context) on the bootstrap proxy so that it will
-obtain the trust verifier from the server in a secure way.  Next, the
-<code>ProxyTrustVerifier</code> invokes the
-<code>ProxyTrust.getProxyVerifier</code> method on the bootstrap proxy
-to obtain the trust verifier.  This invocation is a remote call to a
-"bootstrap remote object" that implements the <code>ProxyTrust</code>
-interface.  The <code>getProxyVerifier</code> implementation can then
-call the
- <code>ServerProxyTrust.getProxyVerifier</code> method on the service
-(which is a local method call) to obtain the trust verifier and then
-return the result.  Note that the bootstrap remote object and the
-service's remote object could be the same object; that is, the service object can
-implement <code>ProxyTrust</code>.
-
-<p>After the <code>ProxyTrustVerifier</code> obtains the trust
-verifier from the service, it can then invoke the trust verifier's
-<code>isTrustedObject</code> method, passing it the service proxy and
-the context, to determine whether the proxy is really a proxy that the
-service trusts.
-
-<h4>Implementation Requirements for Proxy Trust Verification</h4>
-
-<p>There are two main kinds of service proxies: a "simple" proxy,
-that is, a "non-smart" proxy returned from export (like a JRMP
-stub), and a smart proxy that wraps the proxy returned from
-export.  This section describes the verifiers that can be used to
-verify different categories of proxies, based on their
-characteristics, and explains the implementation requirements
-for service proxies and their respective remote objects.
-
-<p>A <code>BasicJeriTrustVerifier</code> can be used as a trust
-verifier for a Jini ERI proxy (a proxy returned by
-<code>BasicJeriExporter</code>) if that proxy's class is defined by a
-trusted class loader and uses <code>BasicInvocationHandler</code>
-and <code>BasicObjectEndpoint</code> containing locally
-verifiable endpoint instances (such as
-<code>net.jini.jeri.ssl.HttpsEndpoint</code> and
-<code>net.jini.jeri.kerberos.KerberosEndpoint</code>).  This is
-not a typical case, though, because in most cases, the class of a
-Jini ERI proxy received by a remote VM will be defined by an
-untrusted class loader.
-
-<p>If a Jini ERI proxy satisfies all of
-<code>BasicJeriTrustVerifier</code>'s conditions for trust, except
-the condition regarding its dynamic proxy class's loader, then
-(on the asumption that the parent of that loader will be locally
-trusted) the service proxy and its remote object can cooperate
-in the verification mechanism provided by
-<code>ProxyTrustVerifier</code>.  In this case, the proxy itself
-serves as the bootstrap proxy and must implement
-<code>ProxyTrust</code>.  To facilitate this, the service's
-remote object can be exported with a
-<code>net.jini.jeri.ProxyTrustILFactory</code> which ensures that
-the service proxy implements <code>ProxyTrust</code> (in addition
-to <code>RemoteMethodControl</code>).  The service's remote object
-must also implement the
-<code>ServerProxyTrust.getProxyVerifier</code> method to return a
-verifier for the proxy (as described below in the section <a
-href="#serverProxyTrust">"Implementing
-<code>ServerProxyTrust</code>"</a>).
-
-<p>If a Jini ERI proxy that could be trusted by clients (perhaps
-by <code>ProxyTrustVerifier</code> as described above) is used
-inside a smart proxy that will not be trusted directly by
-clients, a <code>ProxyTrustILFactory</code> can be used to cause
-the inner Jini ERI proxy to also be an instance of
-<code>ProxyTrust</code> (in addition to
-<code>RemoteMethodControl</code>).  To fit into the
-<code>ProxyTrustVerifier</code> mechanism, the outer proxy must
-implement the <code>getProxyTrustIterator</code> method to return
-a <code>ProxyTrustIterator</code> whose <code>next</code> method
-returns the inner proxy (referred to as the "bootstrap proxy"
-above).  The
-<code>net.jini.security.proxytrust.SingletonProxyTrustIterator</code>
-is a simple implementation of <code>ProxyTrustIterator</code>
-whose <code>next</code> method returns the object the instance is
-constructed with.  Additionally, the service's remote object must
-implement the <code>ServerProxyTrust</code> interface to return a
-trust verifier that verifies the proxy (as described below in the
-section <a href="#serverProxyTrust">"Implementing
-<code>ServerProxyTrust</code>"</a>).
-
-<p>For other smart proxies or Jini ERI proxies containing a custom
-invocation handler or custom endpoint that will not be trusted
-directly by clients, a
-<code>net.jini.security.proxytrust.ProxyTrustExporter</code> can be
-used to combine that proxy with a trustable bootstrap proxy, such that
-the client can use <code>ProxyTrustVerifier</code> to verify that the
-aggregate proxy can be trusted.  The service's remote object would
-need to implement <code>ServerProxyTrust.getProxyVerifier</code>
-to return a verifier for the aggregate proxy.
-
-
-<h5><a name="serverProxyTrust"></a>Implementing <code>ServerProxyTrust</code></h5>
-
-<p>A service's remote object should implement
-the <code>ServerProxyTrust</code> interface
-to provide a trust verifier for its proxies that simply
-compares a known canonical service proxy with the yet-to-be-trusted proxy,
-testing that the proxies are <i>trust equivalent</i>.  An object is
-considered trust equivalent to a known, trusted object if it is
-equivalent in trust, content, and function to that trusted object.  The
-<code>net.jini.security.proxytrust.TrustEquivalence</code> interface
-can be implemented by trusted objects (say component objects in the
-proxy) that need to allow other objects to be checked for trust
-equivalence.   The <code>TrustEquivalence</code> interface has a
-single method, <code>checkTrustEquivalence</code>, for checking trust
-equivalence. 
-
-<p>An implementation of a basic proxy trust verifier, which could be
-returned by an implementation of the
-<code>ServerProxyTrust.getProxyVerifier</code> method, is the <a
-href="api/com/sun/jini/proxy/BasicProxyTrustVerifier.html"><code>com.sun.jini.proxy.BasicProxyTrustVerifier</code></a>
-(see the source code <a
-href="../source/src/com/sun/jini/proxy/BasicProxyTrustVerifier.java"><code>BasicProxyTrustVerifier.java</code></a>
-for implementation details).
-
-
-<h4>3.2.2 Granting Permissions</h4>
-
-<p>Once trust in a proxy has been verified, the client may wish to
-grant permissions to the proxy so that future invocations on the proxy
-will function correctly.  This task can also be accomplished through a
-<code>BasicProxyPreparer</code>.
-
-<p>Permissions can only be granted to a proxy if dynamic
-permission grants are supported by the installed security policy
-implementation.  This release provides a
-<code>java.security.Policy</code> implementation,
-<code>net.jini.security.policy.DynamicPolicyProvider</code>, that
-supports such dynamic granting of permissions at runtime. The
-<code>DynamicPolicyProvider</code> implements the interface
-<code>net.jini.security.policy.DynamicPolicy</code>, which defines
-methods for granting permissions on the granularity of a class loader.
-For an application to grant a specific permission, the calling context
-must have <code>net.jini.security.GrantPermission</code> for the
-permission being granted.  Note that the <code>Security</code> class
-has a <code>static</code> method, <code>grantSupported</code>, that
-can be called to check whether dynamic permission grants are
-supported.
-
-<p>A <code>BasicProxyPreparer</code> grants permissions to the proxy
-on the granularity of the proxy's class loader.  The preparer invokes
-its own <code>getPermissions</code> method, passing the
-proxy, to obtain the permissions to grant.  If there are permissions
-to grant, the preparer invokes <code>Security.grant</code> with the
-proxy's class (<i>proxyClass</i>) and the <i>permissions</i> to grant
-(see Figure 1).
-
-<p>The <code>Security.grant</code> operation will delegate to the
-security policy implementation to grant the permissions if the policy
-supports dynamic permission grants via <code>DynamicPolicy</code>.
-This <code>Security.grant</code> method grants the specified
-permissions to all protection domains that are associated with the
-class loader of the given class (which, in this example, is the
-proxy's class) and passes at least the principals of the current
-subject (if any).  If grants are not supported or the calling context
-does not have the requisite <code>GrantPermission</code> for each
-permission to grant, then a <code>SecurityException</code> is thrown.
-
-<h4>3.2.3 Setting Constraints</h4>
-
-<p>Once trust is verified and permissions (if any) have been granted
-to the proxy, constraints should be set on the proxy to ensure the
-desired level of security on future remote invocations through the
-proxy.  A <code>BasicProxyPreparer</code>'s final task is to set
-constraints (if any) on the proxy, resulting in a new proxy (with the
-constraints set), and to return that proxy as the result of the
-<code>prepareProxy</code> operation (see Figure 1).
-
-<p>A proxy must implement the interface
-<code>net.jini.core.constraint.RemoteMethodControl</code> to enable
-the setting of constraints.  Constraints are set by invoking the
-proxy's <code>setConstraints</code> method, passing a
-<code>MethodConstraints</code> object containing the constraints to
-set.  A <code>BasicProxyPreparer</code> obtains the method constraints
-from itself by invoking its own <code>getMethodConstraints</code>
-method and then sets these constraints on the proxy.  The 
-copy of the proxy (<i>new proxy</i>) returned by the
-<code>setConstraints</code> method is returned as the result of
-preparing the proxy.
-
-<h3>3.3 Code Integrity</h3>
-
-The <code>net.jini.core.constraint.Integrity</code> constraint should
-be set on a proxy if remote calls through that proxy require integrity
-protection on both the in-band call data, transmitted as part of the
-remote call, and the code downloaded out-of-band as a result of the
-call.  A communication mechanism enforcing an <code>Integrity</code>
-constraint can use the <code>Security.verifyCodebaseIntegrity</code>
-method to determine if all URLs in a codebase provide content
-integrity, based on whatever
-<code>net.jini.security.IntegrityVerifier</code> instances are
-configured.
-
-<p>The application does not have to worry about verifying codebase
-integrity itself; that task is carried out by the underlying
-communication mechanism enforcing the <code>Integrity</code>
-constraint.  Such communication mechanisms should verify the
-codebase URLs for integrity when unmarshalling objects during a remote
-call. 
-
-<p>The <code>Security.verifyCodebaseIntegrity</code> method obtains
-integrity verifiers from a resource,
-<code>META-INF/services/net.jini.security.IntegrityVerifier</code>,
-which, in this distribution (and similar to trust verifiers),
-is part of the file <code>jsk-resources.jar</code>.  The following
-table lists the standard integrity verifier implementations along
-with the type of URLs they verify. <p>
-
-<blockquote>
-<table summary="Describes the standard IntegrityVerifier implementations"
-       border=1 cellpadding=5>
-<th> <code>IntegrityVerifier</code> <th> Verified URLs
-<tr> <td> <code>net.jini.url.httpmd.HttpmdIntegrityVerifier</code>
-     <td> HTTPMD
-<tr> <td> <code>net.jini.url.https.HttpsIntegrityVerifier</code>
-     <td> HTTPS
-<tr> <td> <code>net.jini.url.file.FileIntegrityVerifier</code>
-     <td> FILE
-</table>
-</blockquote>
-
-<p>The mechanism implemented by
-<code>Security.verifyCodebaseIntegrity</code> is pluggable (since it
-uses a resource), so that other <code>IntegrityVerifier</code>
-implementations can be configured if a deployment requires other URL
-types to have their integrity protection verified.
-
-<h4>HTTPMD URLs</h4>
-
-<p>A deployment requiring integrity protection for downloaded code may
-wish to make use of HTTPMD URLs, introduced in this release.  An
-HTTPMD URL includes a message digest for the data retrieved from the
-URL.  The URL input stream ensures that the data has the correct
-message digest when the end of file for the stream is reached.
-
-<p>The reasoning behind why HTTPMD URLs can be used to verify code
-integrity is as follows.  An HTTPMD URL (configured in a codebase path
-for an application and subsequently used by the underlying
-communication mechanism as a class annotation) is transmitted in band
-as part of a remote call.  Because the HTTPMD URL (both the URL and
-message digest component) is transmitted in band, the message digest
-can be trusted to the same extent as any other data transmitted in the
-call.  If the HTTPMD URL is communicated with integrity, the value of
-the message digest must be correct.  Therefore, the URL input stream
-can use the message digest to verify correctly the integrity of the
-stream contents.
-
-<p>The URL protocol handlers in J2SE can be configured with additional
-protocol handlers, over and above built-in handlers (such as for HTTP
-and FILE URLs).  To configure the use of HTTPMD URLs for an
-application, the "java.protocol.handler.pkgs" system property should
-be set to "net.jini.url".
-
-<p>For convenience, the tool <a
-href="api/com/sun/jini/tool/ComputeHttpmdCodebase.html"><code>ComputeHttpmdCodebase</code></a>
-can be used to compute message digests for a codebase with HTTPMD
-URLs.
-
-
-<h2>4 Jini Extensible Remote Invocation </h2>
-
-<p>Jini ERI, defined in the <a href="api/net/jini/jeri/package-summary.html"><code>net.jini.jeri</code> package</a>, is a
-pluggable implementation of the Java RMI programming model that
-supports the remote object export model defined in the
-<a href="api/net/jini/export/package-summary.html"><code>net.jini.export</code> package</a> and supports the security model
-described above, including invocation constraints, remote method
-control, and the trust verification model.  Jini ERI allows
-customization of client-side and server-side remote invocation
-behavior and also allows the use of a variety of communication
-transports.
-
-<p>See the <a
-href="api/net/jini/jeri/package-summary.html"><code>net.jini.jeri</code> package
-documentation</a> for more information.
-
-<h2>5 Service Providers</h2>
-
-<p>While this release provides a pluggable infrastructure with many
-avenues for customization, it also includes many provider
-implementations that are sufficient for most applications.  These
-providers are summarized in this section.
-
-<p>Many applications will use the supplied providers, having one or
-more of them specified in deployment-time information in a
-resource or configuration.  Other applications may implement one or more
-of their own providers if their application deployment requires a
-more specific feature that is not implemented by the built-in
-providers.
-
-<p>In general, an application developer or deployer does not need to
-understand all APIs used by providers.  Such APIs only need to be
-well-understood if one is developing a new service provider or
-customizing some aspect of an existing one.
-
-<h3>5.1 Providers located by resources</h3>
-
-<p>The following is a list of provider interfaces and associated
-implementations that are located via resources (and specified in
-<code>jsk-resources.jar</code>).  For the most part, these
-provider interfaces and implementations are used by other
-infrastructure implementations.  Applications generally don't
-need to program to either the interfaces or the implementations
-of these kinds of providers with some minor exceptions: to
-implement <code>TrustVerifier</code> for a smart/custom proxy,
-and to reference a <code>Configuration</code>.
-
-<blockquote>
-<p> <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/server/RMIClassLoaderSpi.html"><code>java.rmi.server.RMIClassLoaderSpi</code></a> (defined in J2SE)
-<ul>
-<li>	<code>net.jini.loader.pref.PreferredClassProvider</code>
-<li>	<code>net.jini.loader.pref.RequireDlPermProvider</code>
-</ul>
-
-<p>    <a href="api/net/jini/export/ServerContext.Spi.html"><code>net.jini.export.ServerContext.Spi</code></a>
-<ul>
-<li>	<code>net.jini.jrmp.JrmpServerContext</code>
-</ul>
-
-<p> <a href="api/net/jini/security/TrustVerifier.html"><code>net.jini.security.TrustVerifier</code></a>
-<ul>
-<li>	<code>net.jini.constraint.ConstraintTrustVerifier</code>
-<li>	<code>net.jini.jeri.BasicJeriTrustVerifier</code>
-<li>	<code>net.jini.jeri.ssl.SslTrustVerifier</code>
-<li>	<code>net.jini.jeri.kerberos.KerberosTrustVerifier</code>
-<li>	<code>net.jini.security.proxytrust.ProxyTrustVerifier</code>
-<li>	<code>net.jini.discovery.ConstrainableLookupLocatorTrustVerifier</code>
-<li>	<code>com.sun.jini.discovery.DiscoveryConstraintTrustVerifier</code>
-</ul>
-
-<p> <a href="api/net/jini/security/IntegrityVerifier.html"><code>net.jini.security.IntegrityVerifier</code></a>
-<ul>
-<li>	<code>net.jini.url.httpmd.HttpmdIntegrityVerifier</code>
-<li>	<code>net.jini.url.https.HttpsIntegrityVerifier</code>
-<li>	<code>net.jini.url.file.FileIntegrityVerifier</code>
-</ul>
-
-<p> <a href="api/net/jini/config/Configuration.html"><code>net.jini.config.Configuration</code></a>
-<ul>
-<li>	<code>net.jini.config.ConfigurationFile</code>
-</ul>
-
-<p> <a href="api/net/jini/security/policy/DynamicPolicy.html"><code>net.jini.security.policy.DynamicPolicy</code></a> and
-      <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/Policy.html"><code>java.security.Policy</code></a>
-<ul>
-<li> <code>net.jini.security.policy.DynamicPolicyProvider</code>
-</ul>
-</blockquote>
-
-<h3>5.2 Providers specified in configurations</h3>
-
-<p>The providers in this section are those that a deployer may specify
-explicitly in a configuration.  Applications typically program to the
-interfaces of these providers, but not their implementations.  Many
-applications can utilize the implementations available in the 
-Apache River release, and therefore, don't need to worry about how to implement a
-specific interface, only how to use it.
-
-<blockquote>
-<p>  <a href="api/net/jini/export/Exporter.html"><code>net.jini.export.Exporter</code></a>
-<ul>
-<li>	<code>net.jini.jeri.BasicJeriExporter</code>
-<li>	<code>net.jini.jrmp.JrmpExporter</code>
-<li>	<code>net.jini.iiop.IiopExporter</code>
-<li>	<code>net.jini.activation.ActivationExporter</code>
-<li>	<code>net.jini.security.proxytruxt.ProxyTrustExporter</code>
-</ul>
-
-<p>  <a href="api/net/jini/security/ProxyPreparer.html"><code>net.jini.security.ProxyPreparer</code></a>
-<ul>
-<li>	<code>net.jini.security.BasicProxyPreparer</code>
-</ul>
-
-<p>  <a href="api/net/jini/core/constraint/InvocationConstraint.html"><code>net.jini.core.constraint.InvocationConstraint</code></a>
-<ul>
-<li><code>net.jini.core.constraint.ClientAuthentication</code>
-<li><code>net.jini.core.constraint.ClientMaxPrincipal</code>
-<li><code>net.jini.core.constraint.ClientMaxPrincipalType</code>
-<li><code>net.jini.core.constraint.ClientMinPrincipal</code>
-<li><code>net.jini.core.constraint.ClientMinPrincipalType</code>
-<li><code>net.jini.core.constraint.Confidentiality</code>
-<li><code>net.jini.core.constraint.ConnectionAbsoluteTime</code>
-<li><code>net.jini.core.constraint.ConnectionRelativeTime</code>
-<li><code>net.jini.core.constraint.ConstraintAlternatives</code>
-<li><code>net.jini.core.constraint.Delegation</code>
-<li><code>net.jini.core.constraint.DelegationAbsoluteTime</code>
-<li><code>net.jini.core.constraint.DelegationRelativeTime</code>
-<li><code>net.jini.core.constraint.Integrity</code>
-<li><code>net.jini.core.constraint.RelativeTimeConstraint</code>
-<li><code>net.jini.core.constraint.ServerAuthentication</code>
-<li><code>net.jini.core.constraint.ServerMinPrincipal</code>
-</ul>
-
-<p> <a href="api/net/jini/jeri/ServerEndpoint.html"><code>net.jini.jeri.ServerEndpoint</code></a>
-<ul>
-<li> <code>net.jini.jeri.ssl.SslServerEndpoint</code>
-<li> <code>net.jini.jeri.ssl.HttpsServerEndpoint</code>
-<li> <code>net.jini.jeri.tcp.TcpServerEndpoint</code>
-<li> <code>net.jini.jeri.kerberos.KerberosServerEndpoint</code>
-<li> <code>net.jini.jeri.http.HttpServerEndpoint</code>
-</ul>
-</blockquote>
-
-<hr>
-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
-<ul>
-     <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
-</ul>
-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.
-
-</body>
-</html>
-
-
+<!--
+ ! 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>
+<title>Jini Specification Important Additions - Apache River Release v3.0.0</title>
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
+      vlink="#cc1877" alink="#ffffff">
+
+<a name="TOP"></a>
+<center><h1>Jini Specification Important Additions<br>
+    Apache River Release v3.0.0</h1></center>
+
+<br>
+
+<p>This document provides an overview of the implementation details of
+Jini Specification Additions included in Apache River and
+explains how these components fit together.  Much of this
+information is available in the package, interface, and class
+documentation, but this document provides a higher-level overview
+and indicates where to find more information.
+
+
+<h2>1 Overview of Jini Architecture</h2>
+
+<p>The Jini system architecture consists of three categories:
+<i>programming model</i>, <i>infrastructure</i>, and <i>services</i>.
+
+<p>Apache River provides the following Jini service implementations:
+
+<ul>
+<li> Lookup Service (reggie)
+<li> Transaction Manager Service (mahalo)
+<li> Lease Renewal Service (norm)
+<li> Event Mailbox Service (mercury)
+<li> Lookup Discovery Service (fiddler)
+<li> JavaSpaces Service (outrigger)
+</ul>
+
+<p>Apache River releases and the Jini v2.0 release provide additional
+components to the first two
+categories (programming model and infrastructure) of the Jini
+architecture.  The component additions can be summarized as follows:
+
+<p><i>Additions to Programming Models</i>
+<ul>
+<li><a href="api/net/jini/config/Configuration.html">Configuration</a>
+<li><a href="api/net/jini/export/Exporter.html">Exporter</a>
+<li><a href="api/net/jini/security/ProxyPreparer.html">ProxyPreparer</a>
+</ul>
+
+<p><i>Additional Infrastructure</i>
+<ul>
+<li><a href="api/net/jini/security/package-summary.html">Security</a>
+<li><a href="api/net/jini/core/constraint/package-summary.html">Invocation Constraints</a>
+<li><a href="api/net/jini/jeri/package-summary.html">Jini extensible
+remote invocation (Jini ERI)</a>
+<li><a href="api/net/jini/security/policy/package-summary.html">Dynamic Policy</a>
+<li><a href="api/net/jini/loader/pref/package-summary.html">Preferred Class Loading</a>
+<li><a href="api/com/sun/jini/discovery/package-summary.html">Discovery Protocol v2</a>
+</ul>
+
+<p><i>Configuring Services</i>
+
+<p>Each service included in Apache River supports being
+configured using a <code>Configuration</code>.  Most of the
+services were previously configured via system properties.  These
+services can now be configured via entries in the configuration.
+New types of behavior that can be configured are remote service
+exporting and proxy preparation.</p>
+
+<h3>1.1 Goals</h3>
+
+The main goals for the additions in the Jini architecture are to:
+
+<ul>
+<li> Add support for secure Jini technology-based programs (Security infrastructure)
+<li> Provide mechanisms to configure applications (<code>Configuration</code>)
+<li> Unify client-side and server-side programming models
+     (<code>ProxyPreparer</code> and <code>Exporter</code>)
+<li> Provide a Java(TM) Remote Method Invocation (Java RMI)
+     implementation that supports pluggable invocation layer behavior
+     and pluggable transport providers (Jini ERI)
+</ul>
+
+<p>The primary motivation for augmenting the Jini architecture
+is to provide the new programming models and infrastructure
+necessary to support and manage security in Jini technology-based
+distributed applications.  The previous Jini architecture lacked
+direct support for a type of security many Jini / Apache River applications
+need, namely basic network security for remote calls to
+services.  This goal is addressed by the new security
+infrastructure and constraint-based remote invocation model.
+
+<p>Another important goal for this release is to better unify the
+overall programming model for service developers, given the
+previous lack of uniformity in the APIs for implementing,
+exporting, and deploying services.  Securing remote invocation
+requires additional client-side verification steps, so this
+release introduces a uniform client-side API to handle a
+"preparation" step before remote invocation.  Additionally,
+application developers can ease deployment tasks by separating
+out deployment-time information from the application.  The
+<code>Configuration</code> API introduced in the Jini 2.0 release
+provides a simple and uniform way to obtain deployment-specific
+information.  The resulting programming model supports a uniform
+framework for pluggable security, exporter, transport, and other
+service providers.
+
+<p>A final goal is to provide an implementation of the Java RMI
+programming model that supports constraints on remote invocation
+(which is crucial to the security model), and supports pluggable
+invocation and dispatch behavior as well as pluggable transport
+providers on a per-object basis, features which are lacking in the
+JRMP implementation of Java 2 SDK, Standard Edition (J2SE(TM)) RMI.
+The Jini ERI API provides such a pluggable implementation of the Java
+RMI programming model.
+
+
+<h2>2 Programming Model</h2>
+
+<p>Before delving into the discussion of the security
+architecture, it is important to understand initially a few
+additional programming models, <code>Configuration</code>,
+<code>Exporter</code>, and <code>ProxyPreparer</code>, each of
+which simplifies application development in general and secure
+application development in particular.
+
+<h3>2.1 <code>Configuration</code> </h3>
+
+An application is much easier to test, deploy, and evolve
+when the application's source code is not tied directly to specific
+deployments, but instead uses a level of abstraction, such as
+service provider interfaces.  Such applications may separate out
+deployment-specific information from the application source code,
+allowing this information to be configured at deployment time.  The
+obvious benefit of this approach is that the application can be
+configured to use the implementations that the deployment requires
+without having to change the application source code.  If
+deployment needs change, only the configuration must change;  the
+application can remain intact.
+
+<p>The <code>net.jini.config.Configuration</code> API supports this
+approach by providing a simple, uniform way to obtain the objects
+needed to configure an application.  An application can obtain an
+object from a <code>Configuration</code> instead of explicitly
+constructing an instance to avoid tying the application to
+deployment-specific implementations.  Typical objects that should be
+obtained from a configuration are <code>Exporter</code> and
+<code>ProxyPreparer</code> instances (discussed below).
+
+<p>An application may not want to be tied to a specific implementation
+of <code>Configuration</code> either, so an application can use
+<code>net.jini.config.ConfigurationProvider</code> to obtain a
+<code>Configuration</code> implementation.  Using the
+<code>ConfigurationProvider</code> in an application allows the
+application's deployer to specify the most suitable
+<code>Configuration</code> implementation at deployment time.
+A given <code>Configuration</code> implementation might
+read configuration information from a file, a database,
+or from some other source.
+
+<p>The standard, default <code>Configuration</code> implementation is
+<code>net.jini.config.ConfigurationFile</code>.  This implementation
+reads configuration information, written in a subset of the syntax of
+the Java programming language, from files and URLs to produce objects
+from the configuration.  See the <a href="api/net/jini/config/package-summary.html"><code>net.jini.config</code> package
+documentation</a> for an example of how an application can use a
+<code>Configuration</code> and how a deployer can use a
+<code>ConfigurationFile</code> source file to configure that
+application. 
+
+<h3>2.2  <code>Exporter</code> and the Server-Side Implementation Model </h3>
+
+<p>In Jini technology-based applications, invoking a method on a
+Jini service proxy has a uniform client-side model: a client
+simply invokes a method on the service's proxy to initiate remote
+communication to the service object, an invocation that follows
+the same general semantics as the Java RMI model.
+
+<p>The server-side implementation model for Jini / Apache River applications,
+however, is not uniform.  An application developer typically
+implements a service and exports that service in a way that ties
+the service directly to a specific implementation and model of
+remote communication.  This implementation dependence requires
+that the application source code be modified if the service needs
+to be exported in a slightly different way. For example, an
+application deployment may need to export a service to use a
+different port or socket factory, or may need to export that
+service using a different implementation of remote communication
+entirely, such as a different implementation of the Java RMI
+programming model.
+
+<p>The <code>net.jini.export.Exporter</code> interface unifies the
+server-side implementation model by providing an abstraction for
+exporting and unexporting a remote object.  The details of export and
+unexport behavior, including communication protocols used for remote
+invocation and additional invocation semantics, are defined by the
+particular implementation of the <code>Exporter</code> interface.
+
+<p>Several standard <code>Exporter</code> implementations, which are
+also implementations of the Java RMI programming model, are provided.  
+The following table lists these
+implementations along with the class whose behavior the exporter is
+semantically equivalent to.
+
+<p>
+<blockquote>
+<table summary="Describes the standard Exporter implementations"
+       border=1 cellpadding=5>
+<th> <code>Exporter</code> <th>Equivalent Class
+<tr> <td> <code>net.jini.jrmp.JrmpExporter</code>
+     <td> <code>java.rmi.server.UnicastRemoteObject</code>
+<tr> <td> <code>net.jini.iiop.IiopExporter</code>
+     <td> <code>javax.rmi.PortableRemoteObject</code>
+<tr> <td> <code>net.jini.jeri.BasicJeriExporter</code>
+     <td> itself
+</table>
+</blockquote>
+
+<p>An application can use a <code>Configuration</code> together with
+the <code>Exporter</code> interface to export remote objects in a way
+that can be configured at deployment time.  The following example
+(similar to those in the <a href="api/net/jini/config/package-summary.html"><code>net.jini.config.Configuration</code>
+package documentation</a>) illustrates configurable exporting:
+
+<pre>
+    import java.rmi.*;
+    import net.jini.config.*;
+    import net.jini.export.*;
+    public class Example implements Remote {
+        public static void main(String[] args) throws Exception {
+            Configuration config = ConfigurationProvider.getInstance(args);
+            Exporter exporter = (Exporter) config.getEntry(
+                "Example", "exporter", Exporter.class);
+            Remote proxy = exporter.export(new Example());
+            System.out.println(proxy);
+            exporter.unexport(true);
+        }
+    }
+</pre>
+
+<p>This application can be configured by specifying the following
+configuration file (that uses <code>ConfigurationFile</code>
+syntax) as a command line argument.  The configuration file
+specifies the exporter to be a <code>JrmpExporter</code>, an
+exporter that produces proxies that participate in the JRMP
+protocol.
+
+<pre>
+    import net.jini.jrmp.*;
+    Example {
+        exporter = new JrmpExporter();
+    }
+</pre>
+
+<p>Alternatively, the application can be deployed to specify the
+exporter to be a <code>BasicJeriExporter</code> (an exporter for
+exporting a remote object to use Jini ERI) constructed to export the
+object on an anonymous TCP port.
+
+<pre>
+    import net.jini.jeri.*;
+    import net.jini.jeri.tcp.*;
+    Example {
+        exporter = new BasicJeriExporter(TcpServerEndpoint.getInstance(0));
+    }
+</pre>
+
+<h3>2.3  <code>ProxyPreparer</code> and the Client-Side Invocation Model </h3>
+
+<p>The new security model (discussed below) requires the application
+to perform some pre-invocation "preparation" of a service proxy before
+invoking its methods.  This is because an application may receive the
+service proxy from an untrusted source.  Therefore, before an
+application uses a proxy, that application might need to perform
+operations such as verifying trust in the proxy or granting
+permissions to the proxy once its trust has been verified.
+
+<p>These security requirements add an additional step to the
+client-side invocation model.  The
+<code>net.jini.security.ProxyPreparer</code> interface abstracts the
+operation of "proxy preparation" into a single method,
+<code>prepareProxy</code>, so that the client-side invocation model
+can be uniform across applications using secure and non-secure
+proxies.
+
+<p>A <code>ProxyPreparer</code> can be used together with a
+<code>Configuration</code> to allow configurable proxy preparation.
+The following is a code snippet from the <a
+href="../source/src/com/sun/jini/example/hello/index.html"><i>hello</i>
+example</a> client, which is part of a comprehensive example included
+in the Apache River release:
+
+<p>
+<pre>
+    ProxyPreparer preparer = (ProxyPreparer) config.getEntry(
+        "com.sun.jini.example.hello.Client",
+	"preparer", ProxyPreparer.class, new BasicProxyPreparer());
+    server = (Hello) preparer.prepareProxy(server);
+    System.out.println("Server says: " + server.sayHello());
+</pre>
+
+<p>The call to <code>getEntry</code> supplies a default (<code>new
+BasicProxyPreparer()</code>) for the entry that will be returned if
+the configuration file does not have the specified entry.  A
+<code>net.jini.security.BasicProxyPreparer</code> instance can be
+constructed with arguments specifying whether a proxy, passed to its
+<code>prepareProxy</code> method, needs to be verified or needs other
+security-related operations to be performed.  A
+<code>BasicProxyPreparer</code> constructed with no arguments, which
+is the default above, specifies a "do nothing"
+<code>ProxyPreparer</code> that simply returns the proxy passed to the
+<code>prepareProxy</code> method.
+
+<p>If an application deployment has security requirements, the
+application can be deployed with a <code>BasicProxyPreparer</code>
+constructed with the appropriate arguments or can be
+deployed with an alternate <code>ProxyPreparer</code> implementation.
+
+
+<h2>3 Security</h2>
+
+<p>In a typical Jini technology-based application, a client obtains a
+service proxy from somewhere (for example, from a lookup service or as
+a result of communicating with another service) and then invokes
+methods on that proxy to communicate with the service.  Many
+applications have a need to secure such remote communication,
+requiring one or more of the following:
+
+<ul>
+<li> Mutual authentication (client and server)
+<li> Authorization (access control)
+<li> Integrity (cryptographic checksums)
+<li> Confidentiality (encryption)
+</ul>
+
+<p>These requirements are typical for securing <i>data</i>
+communication; however, the Jini security model has an additional
+requirement: <i>code</i> integrity.  In the Jini and Java RMI model,
+an object's data is sent in a remote invocation, but its code is
+downloaded out-of-band as a result of that remote invocation.  An
+application needs to establish trust for the <i>objects</i> it
+receives, both in the integrity of an object's code as well as in its
+data.
+
+<p>This release provides a framework for trust verification as well as
+a constraint-based remote invocation model that enables an application
+to specify various requirements (such as security requirements) on
+remote invocations.  The infrastructure also provides mechanisms that
+can be used to ensure code integrity.
+
+<h3>3.1 Constraints and Remote Invocation</h3>
+
+<p>The security requirements described above can be expressed as
+<i>constraints</i> on remote invocation.  A constraint is a specific
+requirement, set by the client, on the behavior of remote invocations
+through a proxy to its associated service.  A proxy can implement the
+interface <code>net.jini.core.constraint.RemoteMethodControl</code> to
+enable a client to set constraints on remote invocation through
+that proxy.  The constraint-based remote invocation model is general,
+providing for security-related constraint types as well as other
+constraint types.
+
+<p>One example use of constraints is a client that needs to authenticate
+the identity of a service (such as a bank) before communicating with
+it through its proxy.  In this example, the service proxy can
+implement the interface <code>RemoteMethodControl</code> to enable a
+client to set a constraint requiring server authentication on any
+remote invocation through that proxy.  It is the proxy's
+responsibility to satisfy those constraints, but it is the client's
+responsibility to verify that it can trust the proxy to carry out its
+responsibility (discussed below).
+
+<p>Each constraint is represented as a
+<code>net.jini.core.constraint.InvocationConstraint</code> instance.
+An <code>InvocationConstraint</code> instance expresses "what" but not
+"how"; that is, a constraint expresses "what" the constraint
+represents, but not "how" the constraint should be satisfied.  A proxy
+is responsible for using the appropriate transport and protocols to
+satisfy the constraints set by the client.  Because constraints are
+expressed abstractly, the security implementations are pluggable and
+thus are capable of supporting a wide variety of protocols such as
+Secure Socket Layer (SSL) and Kerberos.  See the
+<a href="api/net/jini/core/constraint/package-summary.html"><code>net.jini.core.constraint</code> package documentation</a> for
+general information on constraints including a number of pre-defined
+basic constraints.
+
+<p>Before a client sets constraints on a proxy, the client first needs
+to verify that it can trust the proxy to carry out the constraints to
+be set, because the proxy may have been received from an untrusted
+source.  If the client does not verify that the proxy is trusted,
+there is a danger that the proxy could simply ignore the client's
+constraints and perform unencrypted data transfer, misrepresent the
+client's or server's identity, or worse.  After the client verifies
+trust in the proxy, it can then set constraints on the proxy to
+specify any desired security requirements, such as server
+authentication.
+
+<p>Once a client trusts a proxy, it may also need to grant additional
+permissions to the proxy, over and above the minimal permissions
+typically configured in advance for untrusted code, so that future
+invocations through the proxy function properly.  A proxy may require
+<code>net.jini.security.AuthenticationPermission</code> so that it can
+authenticate with the server, for example.  A client must not grant
+permissions to the proxy before it trusts the proxy, so that the proxy
+cannot abuse the grants in a way that might cause harm.
+
+<p>To summarize, a client receiving a proxy from an untrusted source
+needs to "prepare" the proxy in the following manner before invoking
+that proxy's methods.  The full requirements for each of these steps
+are described in the <a href="api/net/jini/security/package-summary.html"><code>net.jini.security</code> package documentation</a>:
+
+<ul>
+<li>Verify trust in the proxy
+<li>Grant permissions to the proxy
+<li>Set constraints on (a copy of) the proxy
+</ul>
+
+<p>The steps above can be encapsulated in a single operation known as
+<i>proxy preparation</i>, a term which means "preparing the proxy for
+remote invocation".  The client-side interface
+<code>net.jini.security.ProxyPreparer</code> (discussed above)
+encapsulates such proxy preparation into a single method,
+<code>prepareProxy</code>.
+
+<p>The class <code>net.jini.security.BasicProxyPreparer</code>, a
+standard implementation of the <code>ProxyPreparer</code> interface,
+performs the three necessary steps above to prepare a proxy for secure
+remote calls.  Most deployers can use a
+<code>BasicProxyPreparer</code> instance for proxy preparation and not
+worry about all the details behind trust verification (which are
+outlined in some detail below).  Other applications may need to subclass
+<code>BasicProxyPreparer</code> if verifying trust, setting
+constraints, and/or granting permissions require some customization.
+
+
+<h3>3.2 Proxy Preparation Using <code>BasicProxyPreparer</code></h3>
+
+
+<p>The <code>BasicProxyPreparer</code> class encapsulates the three steps
+of verifying trust, setting constraints, and granting permissions to a
+proxy.  A <code>BasicProxyPreparer</code> instance can be constructed
+in a variety of ways, supporting many common cases for proxy
+preparation including the following:
+
+<ul>
+
+<li> <i>Verify trust, grant permissions, and set new constraints</i>:
+to prepare a proxy received from an untrusted source.
+
+<li> <i>Set new constraints</i>: to prepare a trusted proxy received
+with integrity protection from a trusted source that is not known to
+supply the appropriate constraints.
+
+<li> <i>Grant permissions</i>: to prepare a trusted proxy received
+with integrity protection from a trusted source that supplies
+appropriate constraints, if the proxy needs permission grants.
+
+<li> <i>Do nothing</i>: to use as a default when retrieving an
+optional configuration entry, or to prepare a non-secure proxy.
+
+</ul>
+
+<p>Static methods <code>Security.verifyObjectTrust</code> and
+<code>Security.grant</code> of the
+<code>net.jini.security.Security</code> class implement the trust
+verification and permission granting mechanisms, respectively.
+Constraints can be set on the proxy implementing the
+<code>RemoteMethodControl</code> interface by calling its
+<code>setConstraints</code> method.  A
+<code>BasicProxyPreparer</code> uses these three mechanisms to
+implement the specifics of proxy preparation.
+
+<p>The next three sections describe the mechanics of proxy preparation
+using a <code>BasicProxyPreparer</code> instance that performs all three
+steps.  For the purposes of this discussion, let's assume that a
+<code>BasicProxyPreparer</code> is constructed as follows:
+
+<pre>
+    new BasicProxyPreparer(true, <i>constraints</i>, <i>permissions</i>)
+</pre>
+
+<p>where the argument <code>true</code> indicates that the proxy
+should be verified for trust, <i>constraints</i> is a
+<code>MethodConstraints</code> object (an object containing the
+per-method constraints to set on the proxy), and <i>permissions</i> is
+an array containing the <code>java.security.Permission</code>s to be
+granted to the proxy.
+
+<p>The UML sequence diagrams (PDF files) referred to in the
+next three sections illustrate the proxy preparation and trust
+verification processes.  Together, these diagrams depict a full scenario
+of verifying trust, granting permissions, and setting constraints:
+
+<ul>
+
+<li><a href="proxypreparation.pdf">Proxy Preparation (Figure 1)</a>:
+illustrates verifying trust, granting permissions, and setting new
+constraints on a proxy.
+
+<li> <a href="simpleproxyverification.pdf">Non-Smart Proxy Trust
+Verification (Figure 2)</a>: shows verifying trust of a non-smart proxy
+(for example, a simple Jini ERI proxy) using a
+<code>ProxyTrustVerifier</code>. 
+
+<li> <a href="smartproxyverification.pdf">Smart Proxy Trust
+Verification (Figure 3)</a>: shows verifying trust of a smart proxy using a
+<code>ProxyTrustVerifier</code>. 
+
+</ul>
+
+<p>Note: See this tutorial for <a
+href="http://www.togethersoft.com/services/practical_guides/umlonlinecourse/index.html#sequence-diagrams">a
+description of the syntax of UML sequence diagrams</a>.
+
+<p>Note that the <code>BasicProxyPreparer</code> class is designed to be
+subclassable, therefore the implementation of the
+<code>prepareProxy</code> method invokes <code>protected</code>
+methods on the instance (<code>verify</code>, <code>grant</code>,
+<code>setConstraints</code>, etc.) to allow a potential subclass to
+customize the instance behavior.
+
+<h4>3.2.1 Verifying Trust</h4>
+
+
+<p>The basic model for verifying trust in an object received from an
+untrusted source is to consult one or more <i>trust verifiers</i> (of
+type <code>net.jini.security.TrustVerifier</code>) that are
+essentially part of the "trusted computing base" (a term which means
+the platform's hardware and software that is fully trusted to enforce
+the security mechanisms and policies in place) to see if at least one
+of those verifiers trusts the object in question.  If one trust
+verifier is unable to verify trust, then another one is consulted.
+This trust verification process is carried out by the
+<code>static</code> method <code>Security.verifyObjectTrust</code>.
+
+<p>The <code>Security.verifyObjectTrust</code> method obtains trust
+verifiers from a resource,
+<code>META-INF/services/net.jini.security.TrustVerifier</code>, which,
+in this distribution, is part of the file
+<code>jsk-resources.jar</code>, which is referenced by
+<code>jsk-platform.jar</code>.  These built-in trust verifiers are
+provided to verify instances of classes in the Apache River release.  The
+following table lists these trust verifier implementations along with
+a description of the instances they verify:
+
+<blockquote>
+<table summary="Describes the standard TrustVerifier implementations"
+       border=1 cellpadding=5>
+<th> <code>TrustVerifier</code> <th> Verified Instances
+
+<tr> <td valign="top"> <code>net.jini.constraint.<br>ConstraintTrustVerifier</code>
+     <td valign="top"> constraint classes in <code>net.jini.core.constraint</code>
+<tr> <td valign="top"> <code>net.jini.jeri.<br>BasicJeriTrustVerifier</code>
+     <td valign="top"> proxy produced by <code>BasicJeriExporter.export</code>,
+if the proxy's invocation handler is a standard
+<code>BasicInvocationHandler</code> instance containing a
+<code>BasicObjectEndpoint</code> instance, the proxy's class
+loader is trusted, and the proxy's server constraints and
+<code>Endpoint</code> are trusted
+
+<tr> <td valign="top"> <code>net.jini.jeri.ssl.<br>SslTrustVerifier</code>
+     <td valign="top"> client-related classes in the <code>net.jini.jeri.ssl</code> package
+<tr> <td valign="top"> <code>net.jini.jeri.kerberos.<br>KerberosTrustVerifier</code>
+     <td valign="top"> client-related classes in the <code>net.jini.jeri.kerberos</code> package
+<tr> <td valign="top"> <code>net.jini.security.proxytrust.<br>ProxyTrustVerifier</code>
+     <td valign="top"> proxy that can be verified by obtaining a trust verifier from the proxy's server
+<tr> <td valign="top"> <code>net.jini.discovery.<br>ConstrainableLookupLocatorTrustVerifier</code>
+     <td valign="top"> <code>ConstraintableLookupLocator</code> instances
+<tr> <td valign="top"> <code>com.sun.jini.discovery.<br>DiscoveryConstraintTrustVerifier</code>

[... 644 lines stripped ...]


Mime
View raw message