blob: e7674a0df3e39792089ef3cc1a970240069eb1a5 [file] [log] [blame]
<!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&nbsp;Package</a></li>
<li><a href="../../../net/jini/security/policy/package-summary.html">Next&nbsp;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&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../allclasses-noframe.html">All&nbsp;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&nbsp;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:&nbsp;<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">&nbsp;</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">&nbsp;</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&nbsp;Package</a></li>
<li><a href="../../../net/jini/security/policy/package-summary.html">Next&nbsp;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&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../allclasses-noframe.html">All&nbsp;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>