Author: buildbot
Date: Tue Sep 10 19:27:55 2013
New Revision: 877952
Log:
Staging update by buildbot for jena
Modified:
websites/staging/jena/trunk/content/ (props changed)
websites/staging/jena/trunk/content/documentation/security/index.html
Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Sep 10 19:27:55 2013
@@ -1 +1 @@
-1520738
+1521598
Modified: websites/staging/jena/trunk/content/documentation/security/index.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/security/index.html
(original)
+++ websites/staging/jena/trunk/content/documentation/security/index.html Tue
Sep 10 19:27:55 2013
@@ -127,11 +127,13 @@
<div id="breadcrumbs"></div>
<h1 class="title">Jena Security - A Security (Permissions) wrapper
around Jena RDF implementation.</h1>
<p>JenaSecurity is a SecurityEvaluator interface and a set of dynamic
proxies that apply that interface to Jena Graphs,
-Models, and associated methods and classes.</p>
+Models, and associated methods and classes. It does not implement any
specific security policy but provides a
+framework for developers or integrators to implement any desired policy.</p>
<h2 id="documentation">Documentation</h2>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#usage-notes">Usage Notes</a></li>
+<li><a href="#how-it-works">How it Works</a></li>
<li><a href="evaluator.html">Security Evaluator</a></li>
<li><a href="assembler.html">Assembler</a></li>
</ul>
@@ -165,6 +167,113 @@ permissions, not the <strong>update</str
the result is a tighter security definition than was requested. For simplicity
sake we recommend that the wrapped
secured graph only be used in cases where access to the graph as a whole is
granted/denied. In these cases the user
either has all CRUD capabilities or none.</p>
+<h2 id="how-it-works">How it Works</h2>
+<p>Jena-security does not specify how to determine who the user is, just that
a Principal identifying the user is
+available. It does not specify how to determine what the user has access
to.</p>
+<p>It does require that a developer or integrator implement the
SecurityEvaluator so that when the
+system asks if the current user can perform an action (say read graph X) there
is a yes or no answer.</p>
+<p>The framework does all the work of intercepting the calls to the graph (or
model) and making appropriate calls
+to the Evaluator before allowing the call to go ahead. There are numerous
unit tests to ensure that
+this is done correctly. The required permissions are specified in the javadoc
for object classes
+(e.g. SecuredGraph, SecuredModel).</p>
+<p>Conceptually the framework implements 2 levels of security: graph and
triple.</p>
+<p>The graph restrictions are applied before triple restrictions. So the
system will call
+ evaluate( Action action, SecNode graphIRI );
+to ask can the current user "Read" (Action) graph X (graphIRI) as
<code>evaluate( Action.READ, X )</code>.</p>
+<p>if the answer is yes then the system will call
+ evaluate( Action action, SecNode graphIRI, SecTriple triple );
+to ask if the current user can "Read" (Action) from graph X (graphIRI) all
triples (SecTriple) as
+<code>evaluate( Action.READ, X, SecTriple.ALL )</code>.</p>
+<p>if the answer is yes then the system will execute the call, if the answer
is no then for each
+potential triple the user might read the system will call
+ evaluate( Action action, SecNode graphIRI, SecTriple triple );
+to ask if the current user can "Read" (Action) from graph X (graphIRI) the
triple in question
+(<triple>) as <code>evaluate( Action.READ, X, <triple> )</code>.</p>
+<p>Jena-security performs similar checks for all creates, reads, updates and
deletes. (CRUD). It also does this
+for all classes that can be returned from the secured classes. For example an
RDFList returned
+from a SecuredModel is secured so that the filtering above is performed
against the items in the
+list.</p>
+<h3 id="use-of-special-nodes">Use of special nodes</h3>
+<p>Jena-security provides three special nodes to facilitate evaluation of
security policy constraints.</p>
+<h4 id="secnodeany">SecNode.ANY</h4>
+<p>This is similar to the Jena <code>Node.ANY</code> node. It matches any
node. In general the system will ask if
+the user can access a graph by executing
+ evaluate( Action, GraphIRI )
+if the user can access the graph then the system will execute
+ evaluate( Action, GraphIRI, <SecNode.ANY, SecNode.ANY, SecNode.ANY )
+to determine if the user can perform the action on all triples. If not then
the system will attempt to
+determine if the user perform the action on each specific triple. In some
cases the system can determine that
+the range of nodes involved in the action a sub set of all nodes and will call
<code>evaluate</code> with some constant
+nodes.</p>
+<ul>
+<li>
+<p><SecNode.ANY, SecNode.ANY, SecNode.ANY) - Asks if the user may perform
the action on any triple. </p>
+</li>
+<li>
+<p><X, SecNode.ANY, SecNode.ANY> - Asks if the user may perform the action
against
+any triple where X is the subject.</p>
+</li>
+<li>
+<p><SecNode.ANY, X, SecNode.ANY) - Asks if the user may perform the action
against
+any triple where X is the predicate.</p>
+</li>
+<li>
+<p><(SecNode.ANY, SecNode.ANY, SecNode.X> - Asks if if the user may
perform the action against
+any triple where X is the object.</p>
+</li>
+</ul>
+<p>The <code>SecNode.ANY</code> node may occur multiple times and may occur
with the <code>SecNode.VARIABLE</code> and/or
+ <code>SecNode.FUTURE</code> nodes.</p>
+<h4 id="secnodevariable">SecNode.VARIABLE</h4>
+<p>This differs from <code>SecNode.ANY</code> in that the system is asking "if
there are any prohibitions" not "if the user
+may perform". Thus queries with the <code>SecNode.VARIABLE</code> nodes should
return <code>true</code> where <code>SecNode.ANY</code>> returns
+<code>false</code>. In general this type is used in the query to determine if
triple level filtering of results must be
+performed.</p>
+<ul>
+<li>
+<p><SecNode.VARIABLE, X, Y> - Asks if there are any prohibitions against the
user seeing all subjects
+that have property X and object Y.</p>
+</li>
+<li>
+<p><X, SecNode.VARIABLE, Y> - Asks if there are any prohibitions against the
user seeing all predicates
+hat have subject X and object Y.</p>
+</li>
+<li>
+<p><X, Y, SecNode.VARIABLE> - Asks if there are any prohibitions against the
user seeing all objects
+that have subject X and predicate Y.</p>
+</li>
+</ul>
+<p>The <code>SecNode.VARIABLE</code> may occur multiple times and may occur
with the <code>SecNode.ANY</code> node.</p>
+<h4 id="secnodefuture">SecNode.FUTURE</h4>
+<p>This node indicates a variable in the triple. This differs from
<code>SecNode.ANY</code> in that the system is asking
+"if there are any prohibitions" not "if the user may perform". Thus queries
with the <code>SecNode.VARIABLE</code> type
+node should return <code>true</code> where <code>SecNode.ANY</code> returns
<code>false</code>. In general this type is used in the query to
+determine if triple level filtering of results must be performed.</p>
+<ul>
+<li>
+<p><SecNode.VARIABLE, X, Y> - Asks if there are any prohibitions against the
user seeing all subjects
+that have property X and object Y.</p>
+</li>
+<li>
+<p><X, SecNode.VARIABLE, Y> - Asks if there are any prohibitions against the
user seeing all predicates
+that have subject X and object Y.</p>
+</li>
+<li>
+<p><X, Y, SecNode.VARIABLE> - Asks if there are any prohibitions against the
user seeing all objects
+that have subject X and predicate Y.</p>
+</li>
+</ul>
+<p>The <code>SecNode.VARIABLE</code> may occur multiple times and may occur
with the <code>SecNode.ANY</code> node.</p>
+<p>Insertions pose a different set of problems in that in some cases the
system does not know what value will be
+inserted. For example when concatenating one RDFList with another
(<code>rdfList.concatenate( rdfList2 )</code>) the system
+will create a series of anonymous nodes. To check for these the
<code>SecNode.FUTURE</code> is used. Initially the system will
+call
+ evaluate( Action.CREATE, X, <SecNode.FUTURE, RDF.first, SecNode.ANY )
+to ascertain if the user can create a triple in graph X that has an anonymous
node (SecNode.FUTURE) as the subject,
+RDF.first as the predicate and any node as the object. If this is not allowed
then for every node in <code>rdfList2</code>
+the system will call
+ evaluate( Action.CREATE, X, <SecNode.FUTURE, RDF.first, node )
+where <code>node</code> is the node from <code>rdfList2</code> to be added.</p>
</div>
</div>
