You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by th...@apache.org on 2010/12/08 13:23:32 UTC
svn commit: r1043382 -
/incubator/river/site/trunk/content/river/docs/arch2_0.mdtext
Author: thobbs
Date: Wed Dec 8 12:23:32 2010
New Revision: 1043382
URL: http://svn.apache.org/viewvc?rev=1043382&view=rev
Log:
Changed page to mdtext format
Modified:
incubator/river/site/trunk/content/river/docs/arch2_0.mdtext
Modified: incubator/river/site/trunk/content/river/docs/arch2_0.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/arch2_0.mdtext?rev=1043382&r1=1043381&r2=1043382&view=diff
==============================================================================
--- incubator/river/site/trunk/content/river/docs/arch2_0.mdtext (original)
+++ incubator/river/site/trunk/content/river/docs/arch2_0.mdtext Wed Dec 8 12:23:32 2010
@@ -1,32 +1,6 @@
-<!--
- ! 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 Architecture Specification Version 2.0 Overview - Apache River Release v2.1.2</title>
-<a name="TOP">
-<center><h1>Jini<font><sup>TM</sup></font> Architecture Specification Version 2.0 Extensions Overview<br>
- Apache River Release v2.1.2</h1></center>
+# Jini Architecture Specification Version 2.0 Overview - Apache River Release v2.1.2
-<br>
-
-<p>This document provides an overview of the new components of
+This document provides an overview of the new components of
the Jini<font size="-1"><sup>TM</sup></font> v2.0 Architecture included in Apache River and
explains how the components fit together and fit within the
existing Jini<font size="-1"><sup>TM</sup></font> technology infrastructure. Much of this
@@ -35,229 +9,89 @@ documentation, but this document provide
and indicates where to find more information.
-<h2>1 Overview of Jini<font size="-1"><sup>TM</sup></font> Architecture</h2>
+##1 Overview of Jini<font size="-1"><sup>TM</sup></font> Architecture
+
+The Jini system architecture consists of three categories: _programming model_, _infrastructure_, and _services_. The original [Jini Architecture Specification Version 1.0_](../doc/specs/html/jini-spec.html) defines these categories as follows:
+
+>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.
+
+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):
+
+ - Lookup Service (reggie)
+ - Transaction Manager Service (mahalo)
+ - Lease Renewal Service (norm)
+ - Event Mailbox Service (mercury)
+ - Lookup Discovery Service (fiddler)
+ - JavaSpaces Service (outrigger)
+
+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:
+
+_Additions to Programming Models_
+
+ - [Configuration](api/net/jini/config/Configuration.html)
+ - [Exporter](api/net/jini/export/Exporter.html)
+ - [ProxyPreparer](api/net/jini/security/ProxyPreparer.html)
+
+
+_New Infrastructure_
-<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>New 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>Updates to Services</i>
-
-<p>Each service has been updated to support 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.
+ - [Security](api/net/jini/security/package-summary.html)
+ - [Invocation Constraints](api/net/jini/core/constraint/package-summary.html)
+ - Jini extensible remote invocation (Jini ERI)
+ - [Dynamic Policy](api/net/jini/security/policy/package-summary.html)
+ - [Preferred Class Loading](api/net/jini/loader/pref/package-summary.html)
+ - [Discovery Protocol v2](api/com/sun/jini/discovery/package-summary.html)
-<h3>1.1 Goals</h3>
+_Updates to Services_
+
+Each service has been updated to support being configured using a `Configuration`. 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.
+
+###1.1 Goals
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:
+ - Add support for secure Jini technology-based programs (Security infrastructure)
+ - Provide mechanisms to configure applications (`Configuration`)
+ - Unify client-side and server-side programming models `ProxyPreparer` and `Exporter`)
+ - Provide a Java(TM) Remote Method Invocation (Java RMI) implementation that supports pluggable invocation layer behavior and pluggable transport providers (Jini ERI)
+
+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.
+
+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 `Configuration` 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.
+
+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.
+
+##2 Programming Model
+
+Before delving into the discussion of the security architecture, it is important to understand initially a few additional programming models, `Configuration`, `Exporter`, and `ProxyPreparer`, each of which simplifies application development in general and secure application development in particular.
+
+###2.1 `Configuration`
+
+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.
+
+The `net.jini.config.Configuration` 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 `Configuration` 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 `Exporter` and `ProxyPreparer` instances (discussed below).
+
+An application may not want to be tied to a specific implementation of `Configuration` either, so an application can use `net.jini.config.ConfigurationProvider` to obtain a `Configuration` implementation. Using the `ConfigurationProvider` in an application allows the application's deployer to specify the most suitable `Configuration` implementation at deployment time. A given `Configuration` implementation might read configuration information from a file, a database, or from some other source.
+
+The standard, default `Configuration` implementation is `net.jini.config.ConfigurationFile`. 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">`net.jini.config` package documentation</a> for an example of how an application can use a `Configuration` and how a deployer can use a `ConfigurationFile` source file to configure that application.
+
+###2.2 `Exporter` and the Server-Side Implementation Model
+
+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.
+
+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. The `net.jini.export.Exporter` 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 `Exporter` interface.
+
+Several standard `Exporter` 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.
+
+Describes the standard Exporter implementations
+|`Exporter`|Equivalent Class|
+|`net.jini.jrmp.JrmpExporter`| java.rmi.server.UnicastRemoteObject`|
+|`net.jini.iiop.IiopExporter` |`javax.rmi.PortableRemoteObject`|
+|`net.jini.jeri.BasicJeriExporter`itself|
+
+An application can use a `Configuration` together with the `Exporter` interface to export remote objects in a way that can be configured at deployment time. The following example (similar to those in the [`net.jini.config.Configuration`](api/net/jini/config/package-summary.html) package documentation) illustrates configurable exporting:
-<pre>
import java.rmi.*;
import net.jini.config.*;
import net.jini.export.*;
@@ -271,976 +105,327 @@ package documentation</a>) illustrates c
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.
+This application can be configured by specifying the following configuration file (that uses `ConfigurationFile` syntax) as a command line argument. The configuration file specifies the exporter to be a `JrmpExporter`, 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.
+Alternatively, the application can be deployed to specify the exporter to be a `BasicJeriExporter` (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>
+###2.3 `ProxyPreparer` and the Client-Side Invocation Model
-<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:
+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.
+
+These security requirements add an additional step to the client-side invocation model. The `net.jini.security.ProxyPreparer` interface abstracts the operation of "proxy preparation" into a single method, `prepareProxy`, so that the client-side invocation model can be uniform across applications using secure and non-secure proxies.
+
+A `ProxyPreparer` can be used together with a `Configuration` to allow configurable proxy preparation. The following is a code snippet from the _hello_ example 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());
+ "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.
+The call to `getEntry` supplies a default (`new BasicProxyPreparer()`) for the entry that will be returned if the configuration file does not have the specified entry. A `net.jini.security.BasicProxyPreparer` instance can be constructed with arguments specifying whether a proxy, passed to its `prepareProxy` method, needs to be verified or needs other security-related operations to be performed. A `BasicProxyPreparer` constructed with no arguments, which is the default above, specifies a "do nothing" `ProxyPreparer` that simply returns the proxy passed to the `prepareProxy` method.
+
+If an application deployment has security requirements, the application can be deployed with a `BasicProxyPreparer` constructed with the appropriate arguments or can be deployed with an alternate `ProxyPreparer` implementation.
+
+##3 Security
+
+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:
+ - Mutual authentication (client and server)
+ - Authorization (access control)
+ - Integrity (cryptographic checksums)
+ - Confidentiality (encryption)
+
+These requirements are typical for securing _data_ communication; however, the Jini security model has an additional requirement: _code_ 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 _objects_ it receives, both in the integrity of an object's code as well as in its data.
+
+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.
+
+###3.1 Constraints and Remote Invocation
+
+The security requirements described above can be expressed as _constraints_ 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 `net.jini.core.constraint.RemoteMethodControl` 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.
+
+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 `RemoteMethodControl` 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).
+
+Each constraint is represented as a `net.jini.core.constraint.InvocationConstraint` instance. An `InvocationConstraint` 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 [`net.jini.core.constraint` package documentation](api/net/jini/core/constraint/package-summary.html) for general information on constraints including a number of pre-defined basic constraints.
+
+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.
+
+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 `net.jini.security.AuthenticationPermission` 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.
+
+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 [`net.jini.security` package documentation](api/net/jini/security/package-summary.html):
+
+ - Verify trust in the proxy
+ - Grant permissions to the proxy
+ - Set constraints on (a copy of) the proxy
+
+The steps above can be encapsulated in a single operation known as _proxy preparation_, a term which means "preparing the proxy for remote invocation". The client-side interface `net.jini.security.ProxyPreparer` (discussed above) encapsulates such proxy preparation into a single method, `prepareProxy`.
+
+The class `net.jini.security.BasicProxyPreparer`, a standard implementation of the `ProxyPreparer` interface, performs the three necessary steps above to prepare a proxy for secure remote calls. Most deployers can use a `BasicProxyPreparer` 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 `BasicProxyPreparer` if verifying trust, setting constraints, and/or granting permissions require some customization.
+
+###3.2 Proxy Preparation Using `BasicProxyPreparer`
+
+The `BasicProxyPreparer` class encapsulates the three steps of verifying trust, setting constraints, and granting permissions to a proxy. A `BasicProxyPreparer` instance can be constructed in a variety of ways, supporting many common cases for proxy preparation including the following:
+
+ - _Verify trust, grant permissions, and set new constraints_: to prepare a proxy received from an untrusted source.
+ - _Set new constraints_: to prepare a trusted proxy received with integrity protection from a trusted source that is not known to supply the appropriate constraints.
+ - _Grant permissions_: to prepare a trusted proxy received with integrity protection from a trusted source that supplies appropriate constraints, if the proxy needs permission grants.
+ - _Do nothing_: to use as a default when retrieving an optional configuration entry, or to prepare a non-secure proxy.
+
+Static methods `Security.verifyObjectTrust` and `Security.grant` of the `net.jini.security.Security` class implement the trust verification and permission granting mechanisms, respectively. Constraints can be set on the proxy implementing the `RemoteMethodControl` interface by calling its `setConstraints` method. A `BasicProxyPreparer` uses these three mechanisms to implement the specifics of proxy preparation.
+
+The next three sections describe the mechanics of proxy preparation using a `BasicProxyPreparer` instance that performs all three steps. For the purposes of this discussion, let's assume that a `BasicProxyPreparer` is constructed as follows:
+
+ new BasicProxyPreparer(true, _constraints_, _permissions_)
+
+where the argument `true` indicates that the proxy should be verified for trust, _constraints_ is a `MethodConstraints` object (an object containing the per-method constraints to set on the proxy), and _permissions_ is an array containing the `java.security.Permission`s to be granted to the proxy.
+
+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:
+
+ - [Proxy Preparation (Figure 1)](proxypreparation.pdf): illustrates verifying trust, granting permissions, and setting new constraints on a proxy.
+ - [Non-Smart Proxy Trust Verification (Figure 2)](simpleproxyverification.pdf): shows verifying trust of a non-smart proxy (for example, a simple Jini ERI proxy) using a `ProxyTrustVerifier`.
+ - [Smart Proxy Trust Verification (Figure 3)](smartproxyverification.pdf): shows verifying trust of a smart proxy using a `ProxyTrustVerifier`.
+
+> Note: See this tutorial for [a description of the syntax of UML sequence diagrams](href="http://www.togethersoft.com/services/practical_guides/umlonlinecourse/index.html#sequence-diagrams).
+
+Note that the `BasicProxyPreparer` class is designed to be subclassable, therefore the implementation of the `prepareProxy` method invokes `protected` methods on the instance (`verify`, `grant`, `setConstraints`, etc.) to allow a potential subclass to customize the instance behavior.
+
+####3.2.1 Verifying Trust
+
+The basic model for verifying trust in an object received from an untrusted source is to consult one or more _trust verifiers_ (of type `net.jini.security.TrustVerifier`) 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 `static` method `Security.verifyObjectTrust`.
+
+The `Security.verifyObjectTrust` method obtains trust verifiers from a resource, `META-INF/services/net.jini.security.TrustVerifier`, which, in this distribution, is part of the file `jsk-resources.jar`, which is referenced by `jsk-platform.jar`. 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:
+
+Describes the standard TrustVerifier implementations
+|`TrustVerifier`|Verified Instances|
+|`net.jini.constraint.<br>ConstraintTrustVerifier`|constraint classes in `net.jini.core.constraint`|
+|`net.jini.jeri.<br>BasicJeriTrustVerifier`|proxy produced by `BasicJeriExporter.export`, if the proxy's invocation handler is a standard `BasicInvocationHandler` instance containing a `BasicObjectEndpoint` instance, the proxy's class loader is trusted, and the proxy's server constraints and `Endpoint` are trusted|
+|`net.jini.jeri.ssl.SslTrustVerifier`|client-related classes in the `net.jini.jeri.ssl` package|
+|`net.jini.jeri.kerberos.KerberosTrustVerifier` |client-related classes in the `net.jini.jeri.kerberos` package|
+|`net.jini.security.proxytrust.ProxyTrustVerifier` |proxy that can be verified by obtaining a trust verifier from the proxy's server|
+|`net.jini.discovery.ConstrainableLookupLocatorTrustVerifier` |`ConstraintableLookupLocator` instances|
+|`com.sun.jini.discovery.DiscoveryConstraintTrustVerifier` |discovery constraints|
+
+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 `BasicJeriExporter`.
+
+Proxy preparation is initiated by invoking the `prepareProxy` method on a `BasicProxyPreparer` instance (constructed as above, with _verify_ set to `true`), passing it the _proxy_ to be prepared (see [Figure 1](proxypreparation.pdf")). The`BasicProxyPreparer` instance initiates trust verification by invoking the `Security.verifyObjectTrust` method, passing the _proxy_, the value `null` (_loader_) to specify the context class loader, and the _constraints_ (obtained from the instance itself) to use on any remote communication by the trust verification mechanism.
+
+The `Security.verifyObjectTrust` method obtains the trust verifiers from the resource in the specified _loader_ (if the trust verifiers have not already been obtained) and creates a `net.jini.security.TrustVerifier.Context` (_context_) containing the ordered list of trust verifiers. Next, the `isTrustedObject` method of each trust verifier is invoked, passing it the proxy to be verified and the trust verifier context, until one trust verifier returns `true`. A given trust verifier will return `true` 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.
+
+The `Security.verifyObjectTrust` method returns `true` if there is at least one trust verifier in the context that trusts the proxy.
+
+A `net.jini.security.proxytrust.ProxyTrustVerifier` 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 `ProxyTrustVerifier` handles are: verifying non-smart proxies (for example, a simple proxy returned by `BasicJeriExporter`) and verifying smart proxies that wrap simple (non-smart) proxies. These cases are described in the following two sections.
+
+`ProxyTrustVerifier` implements a trust verification mechanism that uses a trusted _bootstrap proxy_ (either derived or obtained from the original proxy) to obtain a trust verifier from the server to use to verify the original proxy.
+
+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.
+
+####Non-Smart Proxy Trust Verification
+
+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 `net.jini.security.proxytrust.ProxyTrust` so that it can be verified by a `net.jini.security.proxytrust.ProxyTrustVerifier`. In this case, the service's remote object must also cooperate in `ProxyTrustVerifier`'s verification scheme by providing a `TrustVerifier` for its proxies as described in the section "Implementation Requirements for Trust Verification".
+
+The mechanism implemented by `ProxyTrustVerifier` verifies non-smart proxies by performing the following:
+
+ - Creates a "derivative bootstrap proxy" from the proxy,
+ - Verifies trust in this derivative bootstrap proxy using the locally trusted verifiers, and then
+ - Uses the derivative bootstrap proxy to obtain, from the service, a trust verifier for the proxy itself.
+
+The details of this mechanism are implemented by the `ProxyTrustVerifier.isTrustedObject` method (depicted in [Figure 2](simpleproxyverification.pdf)).
+
+The proxy itself implements `ProxyTrust` 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 `ProxyTrustVerifier` 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 `isTrustedObject` on the `TrustVerifier.Context`), then the derivative bootstrap proxy is the bootstrap proxy.
+
[... 189 lines stripped ...]