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 ...]
