<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | |
<!-- NewPage --> | |
<html lang="en"> | |
<head> | |
<!-- Generated by javadoc (1.8.0) on Sun Aug 28 20:41:46 EST 2016 --> | |
<title>net.jini.security (Apache River v3.0.0 Specification-only API Documentation)</title> | |
<meta name="date" content="2016-08-28"> | |
<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style"> | |
<script type="text/javascript" src="../../../script.js"></script> | |
</head> | |
<body> | |
<script type="text/javascript"><!-- | |
try { | |
if (location.href.indexOf('is-external=true') == -1) { | |
parent.document.title="net.jini.security (Apache River v3.0.0 Specification-only API Documentation)"; | |
} | |
} | |
catch(err) { | |
} | |
//--> | |
</script> | |
<noscript> | |
<div>JavaScript is disabled on your browser.</div> | |
</noscript> | |
<!-- ========= START OF TOP NAVBAR ======= --> | |
<div class="topNav"><a name="navbar.top"> | |
<!-- --> | |
</a> | |
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> | |
<a name="navbar.top.firstrow"> | |
<!-- --> | |
</a> | |
<ul class="navList" title="Navigation"> | |
<li><a href="../../../overview-summary.html">Overview</a></li> | |
<li class="navBarCell1Rev">Package</li> | |
<li>Class</li> | |
<li><a href="package-use.html">Use</a></li> | |
<li><a href="package-tree.html">Tree</a></li> | |
<li><a href="../../../deprecated-list.html">Deprecated</a></li> | |
<li><a href="../../../index-all.html">Index</a></li> | |
<li><a href="../../../help-doc.html">Help</a></li> | |
</ul> | |
</div> | |
<div class="subNav"> | |
<ul class="navList"> | |
<li><a href="../../../net/jini/loader/pref/package-summary.html">Prev Package</a></li> | |
<li><a href="../../../net/jini/security/policy/package-summary.html">Next Package</a></li> | |
</ul> | |
<ul class="navList"> | |
<li><a href="../../../index.html?net/jini/security/package-summary.html" target="_top">Frames</a></li> | |
<li><a href="package-summary.html" target="_top">No Frames</a></li> | |
</ul> | |
<ul class="navList" id="allclasses_navbar_top"> | |
<li><a href="../../../allclasses-noframe.html">All Classes</a></li> | |
</ul> | |
<div> | |
<script type="text/javascript"><!-- | |
allClassesLink = document.getElementById("allclasses_navbar_top"); | |
if(window==top) { | |
allClassesLink.style.display = "block"; | |
} | |
else { | |
allClassesLink.style.display = "none"; | |
} | |
//--> | |
</script> | |
</div> | |
<a name="skip.navbar.top"> | |
<!-- --> | |
</a></div> | |
<!-- ========= END OF TOP NAVBAR ========= --> | |
<div class="header"> | |
<h1 title="Package" class="title">Package net.jini.security</h1> | |
<div class="docSummary"> | |
<div class="block">Provides mechanisms and abstractions for managing security, especially in the | |
presence of dynamically downloaded code.</div> | |
</div> | |
<p>See: <a href="#package.description">Description</a></p> | |
</div> | |
<div class="contentContainer"> | |
<ul class="blockList"> | |
<li class="blockList"> | |
<table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Interface Summary table, listing interfaces, and an explanation"> | |
<caption><span>Interface Summary</span><span class="tabEnd"> </span></caption> | |
<tr> | |
<th class="colFirst" scope="col">Interface</th> | |
<th class="colLast" scope="col">Description</th> | |
</tr> | |
<tbody> | |
<tr class="altColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/IntegrityVerifier.html" title="interface in net.jini.security">IntegrityVerifier</a></td> | |
<td class="colLast"> | |
<div class="block">Defines the interface for integrity verifiers used by | |
<a href="../../../net/jini/security/Security.html#verifyCodebaseIntegrity-java.lang.String-java.lang.ClassLoader-"><code>Security.verifyCodebaseIntegrity</code></a>, | |
allowing the URLs that provide content integrity to be extended.</div> | |
</td> | |
</tr> | |
<tr class="rowColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/ProxyPreparer.html" title="interface in net.jini.security">ProxyPreparer</a></td> | |
<td class="colLast"> | |
<div class="block">Performs operations on a newly unmarshalled remote proxy to prepare it for | |
use.</div> | |
</td> | |
</tr> | |
<tr class="altColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/SecurityContext.html" title="interface in net.jini.security">SecurityContext</a></td> | |
<td class="colLast"> | |
<div class="block">Interface implemented by objects representing security contexts, returned | |
from the <a href="../../../net/jini/security/Security.html#getContext--"><code>getContext</code></a> method of the <a href="../../../net/jini/security/Security.html" title="class in net.jini.security"><code>Security</code></a> class, which in turn may obtain them from a security manager or | |
policy provider implementing the | |
<a href="../../../net/jini/security/policy/SecurityContextSource.html" title="interface in net.jini.security.policy"><code>SecurityContextSource</code></a> interface.</div> | |
</td> | |
</tr> | |
<tr class="rowColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/TrustVerifier.html" title="interface in net.jini.security">TrustVerifier</a></td> | |
<td class="colLast"> | |
<div class="block">Defines the interface for trust verifiers used by | |
<a href="../../../net/jini/security/Security.html#verifyObjectTrust-java.lang.Object-java.lang.ClassLoader-java.util.Collection-"><code>Security.verifyObjectTrust</code></a>, allowing | |
the objects that are trusted to be extended.</div> | |
</td> | |
</tr> | |
<tr class="altColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/TrustVerifier.Context.html" title="interface in net.jini.security">TrustVerifier.Context</a></td> | |
<td class="colLast"> | |
<div class="block">Defines the context for trust verification used by | |
<a href="../../../net/jini/security/TrustVerifier.html" title="interface in net.jini.security"><code>TrustVerifier</code></a> instances and <a href="../../../net/jini/security/Security.html#verifyObjectTrust-java.lang.Object-java.lang.ClassLoader-java.util.Collection-"><code>Security.verifyObjectTrust</code></a>.</div> | |
</td> | |
</tr> | |
</tbody> | |
</table> | |
</li> | |
<li class="blockList"> | |
<table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation"> | |
<caption><span>Class Summary</span><span class="tabEnd"> </span></caption> | |
<tr> | |
<th class="colFirst" scope="col">Class</th> | |
<th class="colLast" scope="col">Description</th> | |
</tr> | |
<tbody> | |
<tr class="altColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/AccessPermission.html" title="class in net.jini.security">AccessPermission</a></td> | |
<td class="colLast"> | |
<div class="block">Represents permission to call a method.</div> | |
</td> | |
</tr> | |
<tr class="rowColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/AuthenticationPermission.html" title="class in net.jini.security">AuthenticationPermission</a></td> | |
<td class="colLast"> | |
<div class="block">Represents permission to use the private credentials of subjects for the | |
purpose of authenticating as any subset of the local principals specified | |
in the target name, during secure remote calls with any peer that | |
authenticates as at least the set of peer principals specified in the | |
target name.</div> | |
</td> | |
</tr> | |
<tr class="altColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/BasicProxyPreparer.html" title="class in net.jini.security">BasicProxyPreparer</a></td> | |
<td class="colLast"> | |
<div class="block">A <code>ProxyPreparer</code> for verifying that proxies are trusted, | |
granting them dynamic permissions, and setting their constraints, as well as | |
for creating other proxy preparer subclasses that include those | |
operations.</div> | |
</td> | |
</tr> | |
<tr class="rowColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/GrantPermission.html" title="class in net.jini.security">GrantPermission</a></td> | |
<td class="colLast"> | |
<div class="block">Permission required to dynamically grant permissions by security policy | |
providers which implement the <a href="../../../net/jini/security/policy/DynamicPolicy.html" title="interface in net.jini.security.policy"><code>DynamicPolicy</code></a> interface.</div> | |
</td> | |
</tr> | |
<tr class="altColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/Security.html" title="class in net.jini.security">Security</a></td> | |
<td class="colLast"> | |
<div class="block">Provides methods for executing actions with privileges enabled, for | |
snapshotting security contexts, for verifying trust in proxies, for | |
verifying codebase integrity, and for dynamically granting permissions.</div> | |
</td> | |
</tr> | |
<tr class="rowColor"> | |
<td class="colFirst"><a href="../../../net/jini/security/VerifyingProxyPreparer.html" title="class in net.jini.security">VerifyingProxyPreparer</a></td> | |
<td class="colLast"> | |
<div class="block">A <code>ProxyPreparer</code> for verifying that proxies are trusted, | |
dynamically granting permissions to trusted proxies, and optionally | |
setting the client constraints on trusted proxies.</div> | |
</td> | |
</tr> | |
</tbody> | |
</table> | |
</li> | |
</ul> | |
<a name="package.description"> | |
<!-- --> | |
</a> | |
<h2 title="Package net.jini.security Description">Package net.jini.security Description</h2> | |
<div class="block">Provides mechanisms and abstractions for managing security, especially in the | |
presence of dynamically downloaded code. The mechanisms include: | |
<ul> | |
<li>A provider-based mechanism for clients to verify that proxies can be | |
trusted | |
<li>A provider-based mechanism for verifying code integrity | |
<li>A provider-based mechanism for clients to dynamically grant permissions | |
to proxies | |
</ul> | |
<a name="programming_model"></a><h2>Programming Model</h2> | |
When a client obtains a proxy from somewhere, normally the client should | |
follow these three steps before making any remote calls through the proxy or | |
handing any sensitive data to the proxy: | |
<ul> | |
<li>Verify that the proxy can be <a href="#proxy_trust">trusted</a> | |
<li>Attach client | |
<a href="../core/constraint/package-summary.html#constraints">constraints</a> | |
to (a copy of) the proxy | |
<li><a href="#dynamic_grants">Grant</a> permissions (such as | |
<a href="../../../net/jini/security/AuthenticationPermission.html" title="class in net.jini.security"><code>AuthenticationPermission</code></a>) to the | |
proxy | |
</ul> | |
The first step can be accomplished using | |
<a href="../../../net/jini/security/Security.html#verifyObjectTrust-java.lang.Object-java.lang.ClassLoader-java.util.Collection-"><code>Security.verifyObjectTrust</code></a>. The second step can be accomplished using | |
<a href="../../../net/jini/core/constraint/RemoteMethodControl.html#setConstraints-net.jini.core.constraint.MethodConstraints-"><code>RemoteMethodControl.setConstraints</code></a>; | |
<a href="../../../net/jini/constraint/BasicMethodConstraints.html" title="class in net.jini.constraint"><code>BasicMethodConstraints</code></a> is a basic | |
implementation of | |
<a href="../../../net/jini/core/constraint/MethodConstraints.html" title="interface in net.jini.core.constraint"><code>MethodConstraints</code></a>. The last | |
step can be accomplished using | |
<a href="../../../net/jini/security/Security.html#grant-java.lang.Class-java.security.Permission:A-"><code>Security.grant</code></a>. | |
<p> | |
Normally the client should be written in such a way that it can be configured | |
to allow for variations in the steps used to prepare a proxy for subsequent | |
use. The usual way is to obtain a | |
<a href="../../../net/jini/security/ProxyPreparer.html" title="interface in net.jini.security"><code>ProxyPreparer</code></a> from a | |
<a href="../../../net/jini/config/Configuration.html" title="interface in net.jini.config"><code>Configuration</code></a>, using as a default value | |
a <a href="../../../net/jini/security/BasicProxyPreparer.html" title="class in net.jini.security"><code>BasicProxyPreparer</code></a> that simply | |
returns the proxy. The client can then be configured at deployment time to | |
perform whatever steps are desired. | |
<pre> | |
Configuration config = ...; | |
SomeService proxy = ...; | |
ProxyPreparer preparer = (ProxyPreparer) config.getEntry( | |
"MyClient", "someServicePreparer", | |
ProxyPreparer.class, new BasicProxyPreparer()); | |
proxy = (SomeService) preparer.prepareProxy(proxy); | |
</pre> | |
<p> | |
<a href="../../../net/jini/security/BasicProxyPreparer.html" title="class in net.jini.security"><code>BasicProxyPreparer</code></a> can be used to | |
perform all combinations of these three common steps of proxy preparation. | |
<a name="proxy_trust"></a><h2>Proxy Trust</h2> | |
The basic proxy trust issue can be seen with an example. Suppose the client | |
wants to make a remote call through a proxy. The proxy implements the | |
<a href="../../../net/jini/core/constraint/RemoteMethodControl.html" title="interface in net.jini.core.constraint"><code>RemoteMethodControl</code></a> interface, | |
and the client attaches constraints to the proxy, requiring the server to | |
authenticate as a particular principal. If the proxy code has been dynamically | |
downloaded, and the client does nothing to verify that it trusts the proxy, | |
then the downloaded code might simply ignore the client's constraints and | |
perform no authentication at all. The proxy code might also corrupt the data | |
being passed in the call, or perform some other unintended operation. | |
<p> | |
The client needs some way to decide that it trusts a proxy. Rather than | |
mandating any specific mechanism(s), a pluggable framework is provided. | |
The client calls | |
<a href="../../../net/jini/security/Security.html#verifyObjectTrust-java.lang.Object-java.lang.ClassLoader-java.util.Collection-"><code>Security.verifyObjectTrust</code></a>, passing the proxy and a caller context collection | |
that typically contains a | |
<a href="../../../net/jini/core/constraint/MethodConstraints.html" title="interface in net.jini.core.constraint"><code>MethodConstraints</code></a> instance. | |
This method uses whatever | |
<a href="../../../net/jini/security/TrustVerifier.html" title="interface in net.jini.security"><code>TrustVerifier</code></a> instances have been | |
configured to determine if the proxy can be trusted; if any verifier says | |
that it trusts the proxy, then the proxy is assumed to be trusted. If no | |
verifier trusts the proxy, a <code>SecurityException</code> is thrown. The | |
caller context collection contains whatever context information might be | |
required by verifiers; a <code>MethodConstraints</code> element in the | |
collection is typically used to control any calls to the remote server that | |
are made by verifiers. | |
<p> | |
A baseline for deciding a proxy can be trusted is to examine the proxy and | |
all of its constituent objects, excluding the client constraints, to ensure | |
that they are all instances of locally trusted (typically, not downloaded) | |
classes, containing trusted data. For example, | |
<a href="../../../net/jini/jeri/BasicJeriTrustVerifier.html" title="class in net.jini.jeri"><code>BasicJeriTrustVerifier</code></a> provides this | |
baseline for basic dynamic proxies of remote objects exported to use Jini | |
extensible remote invocation (Jini ERI), in conjunction with | |
<a href="../../../net/jini/constraint/ConstraintTrustVerifier.html" title="class in net.jini.constraint"><code>ConstraintTrustVerifier</code></a>, which | |
verifies the standard constraints. | |
<a href="../../../net/jini/security/proxytrust/ProxyTrustVerifier.html" title="class in net.jini.security.proxytrust"><code>ProxyTrustVerifier</code></a> depends | |
on this baseline as a bootstrap, but ultimately asks the server if it trusts | |
the proxy. | |
<p> | |
The client constraints are excluded from the trust verification of a proxy | |
because it is assumed that the caller will subsequently either replace them | |
with its own constraints that are known to be trusted, or has independently | |
decided to trust the existing client constraints. | |
<p> | |
Note that trust verification does not prevent denial-of-service attacks. If a | |
proxy that uses untrusted code is unmarshalled, the untrusted code can execute | |
before trust verification takes place. In deployments where the trusted | |
sources of downloaded code are known in advance, the | |
<a href="../../../net/jini/loader/pref/RequireDlPermProvider.html" title="class in net.jini.loader.pref"><code>RequireDlPermProvider</code></a> can be used | |
to prevent code downloading from untrusted sources. | |
<a name="dynamic_grants"></a><h2>Dynamic Permission Grants</h2> | |
Once a client decides that it trusts a proxy, it may need to grant additional | |
permissions (such as | |
<a href="../../../net/jini/security/AuthenticationPermission.html" title="class in net.jini.security"><code>AuthenticationPermission</code></a>) to that | |
proxy, so that subsequent calls to the proxy operate correctly. It is | |
important to delay granting such permissions until after the trust decision, | |
so that an untrusted proxy cannot abuse the grants in a way that might cause | |
harm. | |
<p> | |
Dynamic grants require support from the <a href="http://docs.oracle.com/javase/6/docs/api/java/security/Policy.html?is-external=true" title="class or interface in java.security"><code>Policy</code></a> provider. | |
The <a href="../../../net/jini/security/policy/package-summary.html"><code>net.jini.security.policy</code></a> package provides a standard | |
interface for security policy providers capable of dynamic permission grants, | |
as well as a set of composable security policy providers supporting dynamic | |
permission grants and aggregation of multiple security policies in a single | |
virtual machine. | |
<p> | |
<a href="../../../net/jini/security/Security.html#grantSupported--"><code>Security.grantSupported</code></a> can be used to determine if the installed security | |
policy supports dynamic grants, and | |
<a href="../../../net/jini/security/Security.html#grant-java.lang.Class-java.security.Permission:A-"><code>Security.grant</code></a> can | |
be used to make dynamic permission grants. The typical use is to grant | |
permissions to the class loader of the proxy object's top-level class, | |
coupled with the principals of the currently executing subject: | |
<pre> | |
SomeService proxy = ...; | |
Permission[] grants = ...; | |
Security.grant(proxy.getClass(), grants); | |
</pre> | |
In order to dynamically grant a permission, the client itself must have the | |
corresponding <a href="../../../net/jini/security/GrantPermission.html" title="class in net.jini.security"><code>GrantPermission</code></a>. | |
Because the dynamic grant is coupled with the current subject, proxy code must | |
assume that actions executed using | |
<a href="http://docs.oracle.com/javase/6/docs/api/java/security/AccessController.html?is-external=true#doPrivileged-java.security.PrivilegedAction-" title="class or interface in java.security"><code>AccessController.doPrivileged</code></a> will not have the granted permissions (because | |
that method executes the action with no subject); | |
<a href="../../../net/jini/security/Security.html#doPrivileged-java.security.PrivilegedAction-"><code>Security.doPrivileged</code></a> should be used instead to maintain the current subject | |
and thereby enable privileges in a way that retains the granted permissions. | |
<a name="code_integrity"></a><h2>Code Integrity</h2> | |
As described in the <a href="../../../net/jini/core/constraint/Integrity.html" title="class in net.jini.core.constraint"><code>Integrity</code></a> | |
constraint class, for a remote call to have integrity, both code and data must | |
have integrity, and a common technique is to use codebase URLs that provide | |
content integrity. Rather than mandating which URLs provide content integrity, | |
a pluggable framework is provided, and | |
<a href="../../../net/jini/security/Security.html#verifyCodebaseIntegrity-java.lang.String-java.lang.ClassLoader-"><code>Security.verifyCodebaseIntegrity</code></a> can be used to determine if all of the | |
URLs in a codebase provide content integrity, based on whatever | |
<a href="../../../net/jini/security/IntegrityVerifier.html" title="interface in net.jini.security"><code>IntegrityVerifier</code></a> instances | |
have been configured. Application code normally does not call this method | |
directly; rather, it is called by the input streams (such as | |
<a href="../../../net/jini/io/MarshalInputStream.html" title="class in net.jini.io"><code>MarshalInputStream</code></a>) used to unmarshal | |
objects during a remote call. The | |
<a href="../../../net/jini/url/httpmd/HttpmdIntegrityVerifier.html" title="class in net.jini.url.httpmd"><code>HttpmdIntegrityVerifier</code></a>, | |
<a href="../../../net/jini/url/https/HttpsIntegrityVerifier.html" title="class in net.jini.url.https"><code>HttpsIntegrityVerifier</code></a>, and | |
<a href="../../../net/jini/url/file/FileIntegrityVerifier.html" title="class in net.jini.url.file"><code>FileIntegrityVerifier</code></a> classes are | |
provided to verify the integrity of HTTPMD, HTTPS, and FILE URLs, respectively.</div> | |
<dl> | |
<dt><span class="simpleTagLabel">Since:</span></dt> | |
<dd>2.0</dd> | |
<dt><span class="simpleTagLabel">Version:</span></dt> | |
<dd>2.0 | |
<!-- | |
<h2>Package Specification</h2> | |
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT ##### | |
<ul> | |
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a> | |
</ul> | |
<h2>Related Documentation</h2> | |
For overviews, tutorials, examples, guides, and tool documentation, please see: | |
<ul> | |
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a> | |
</ul> | |
--></dd> | |
</dl> | |
</div> | |
<!-- ======= START OF BOTTOM NAVBAR ====== --> | |
<div class="bottomNav"><a name="navbar.bottom"> | |
<!-- --> | |
</a> | |
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> | |
<a name="navbar.bottom.firstrow"> | |
<!-- --> | |
</a> | |
<ul class="navList" title="Navigation"> | |
<li><a href="../../../overview-summary.html">Overview</a></li> | |
<li class="navBarCell1Rev">Package</li> | |
<li>Class</li> | |
<li><a href="package-use.html">Use</a></li> | |
<li><a href="package-tree.html">Tree</a></li> | |
<li><a href="../../../deprecated-list.html">Deprecated</a></li> | |
<li><a href="../../../index-all.html">Index</a></li> | |
<li><a href="../../../help-doc.html">Help</a></li> | |
</ul> | |
</div> | |
<div class="subNav"> | |
<ul class="navList"> | |
<li><a href="../../../net/jini/loader/pref/package-summary.html">Prev Package</a></li> | |
<li><a href="../../../net/jini/security/policy/package-summary.html">Next Package</a></li> | |
</ul> | |
<ul class="navList"> | |
<li><a href="../../../index.html?net/jini/security/package-summary.html" target="_top">Frames</a></li> | |
<li><a href="package-summary.html" target="_top">No Frames</a></li> | |
</ul> | |
<ul class="navList" id="allclasses_navbar_bottom"> | |
<li><a href="../../../allclasses-noframe.html">All Classes</a></li> | |
</ul> | |
<div> | |
<script type="text/javascript"><!-- | |
allClassesLink = document.getElementById("allclasses_navbar_bottom"); | |
if(window==top) { | |
allClassesLink.style.display = "block"; | |
} | |
else { | |
allClassesLink.style.display = "none"; | |
} | |
//--> | |
</script> | |
</div> | |
<a name="skip.navbar.bottom"> | |
<!-- --> | |
</a></div> | |
<!-- ======== END OF BOTTOM NAVBAR ======= --> | |
</body> | |
</html> |