Author: claude
Date: Sat Jan 24 21:44:05 2015
New Revision: 1654582
URL: http://svn.apache.org/r1654582
Log:
Updated security documentation.
Modified:
jena/site/trunk/content/documentation/security/assembler.mdtext
jena/site/trunk/content/documentation/security/evaluator.mdtext
jena/site/trunk/content/documentation/security/index.mdtext
Modified: jena/site/trunk/content/documentation/security/assembler.mdtext
URL:
http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/security/assembler.mdtext?rev=1654582&r1=1654581&r2=1654582&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/security/assembler.mdtext (original)
+++ jena/site/trunk/content/documentation/security/assembler.mdtext Sat Jan 24
21:44:05 2015
@@ -1,21 +1,57 @@
Title: Jena Security - Assembler For a Secured Model
-Jena Security provides a standard Jena assembler making it easy to use the
SecuredModel in an Assembler based
-environment. To use the security assembler the assembler file must contain
the lines:
+Jena Security provides a standard Jena assembler making it easy to use the
`SecuredModel` in an Assembler based environment. To use the security
assembler the assembler file must contain the lines:
- <>; ja:loadClass "org.apache.jena.security.SecuredAssembler" .
- sec:Model rdfs:subClassOf ja:NamedModel .
-
-and a model definition something like:
-
- [] a ja:Model ;
- sec:baseModel jena:model ;
- ja:modelName "modelName";
- sec:evaluatorFactory "javaclass";
- .
-where:
-- `jena:model` is a model defined in the assembler file. In this example
there would be a like in the file
-something like `jena:model a ja:Model`.
-- `modelName` is the name of the model as identified in the security manager.
-- `javaclass` is the java class name that implements an Evaluator Factory.
The Factory must have static method
-`getInstance()` that returns a SecurityEvaluator instance.
+ [] ja:loadClass "org.apache.jena.security.SecuredAssembler" .
+ sec:Model rdfs:subClassOf ja:NamedModel .
+
+The secured assembler provides XXXXXXXXXXXx properties for the assembler files.
+
+Assuming we define
+
+ @prefix sec: <http://apache.org/jena/security/Assembler#> .
+
+Then the following resources are defined
+
+`sec:Model` - A secured model. One against which the security evaluator is
running access checks. All sec:Model instances must have a ja:ModelName to
identify it to the `SecurityEvaluator`
+
+`sec:Evaluator` - An instance of `SecurityEvaluator`.
+
+The following are properties are also defined:
+
+`sec:evaluatorFactory` - Identifies the class name of a factory class that
implements a no-argument `getInstance()` method that returns an instance of
`SecurityEvaluator`.
+
+`sec:baseModel` - Identifies the ja:Model that is to have security applied to
it.
+
+`sec:evaluatorImpl` - Identifies an instance of `SecurityEvaluator`.
+
+`sec:evaluatorClass` - Identifies a class that implements `SecurityEvaluator`
+
+`sec:args` - Identifies arguments to the sec:evaluatorClass constructor.
+
+The secured assembler provides two (2) mechanisms to create a secured graph.
The first is to use a `SecurityEvaluator` factory
+
+ my:securedModel rdf:type sec:Model ;
+ sec:baseModel my:baseModel ;
+ ja:modelName "https://example.org/securedBaseModel"; ;
+ sec:evaluatorFactory "the.evaluator.factory.class.name" .
+
+In the above example static method `getInstance()` is called on
the.evaluator.factory.class.name and the result is used as the
SecurityEvaluator. This is used to create a secured model (`my:securedModel`)
that wraps the model `my:baseModel` and identifies itself to the
`SecurityEvaluator` with the URI `"https://example.org/securedBaseModel"`.
+
+The second mechanism is to use the `sec:Evaluator` method.
+
+ my:secEvaluator rdf:type sec:Evaluator ;
+ sec:args [
+ rdf:_1 my:secInfoModel ;
+ ] ;
+ sec:evaluatorClass "your.implementation.SecurityEvaluator"
+ .
+
+ my:securedModel rdf:type sec:Model ;
+ sec:baseModel my:baseModel ;
+ ja:modelName "https://example.org/securedBaseModel"; ;
+ sec:evaluatorImpl my:secEvaluator .
+
+In the above example `my:secEvaluator` is defined as a `sec:Evaluator`
implemented by the class `"your.implementation.SecurityEvaluator"`. When the
instance is constructed the constructor with one (1) argument is used and it is
passed `my:secInfoModel` as an argument. `my:secInfoModel` may be any type
supported by the assembler. If more than one argument is desired then
`rdf:_2`, `rdf:_3`, `rdf:_4`, etc. may be added to the `sec:args` list. The
`"your.implementation.SecurityEvaluator"` with the proper number of arguments
will be called. It is an error to have more than one argument with the proper
number of arguments.
+
+After constructon the value of `my:securedModel` is used to construct the
`my:securedModel` instance. This has the same properties as the previous
example other than that the `SecurityEvaluator` instance is different.
Modified: jena/site/trunk/content/documentation/security/evaluator.mdtext
URL:
http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/security/evaluator.mdtext?rev=1654582&r1=1654581&r2=1654582&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/security/evaluator.mdtext (original)
+++ jena/site/trunk/content/documentation/security/evaluator.mdtext Sat Jan 24
21:44:05 2015
@@ -41,29 +41,29 @@ triple:
### Evaluator Methods
- public boolean evaluate( Action action, SecNode graphIRI );
+ public boolean evaluate( Object principal, Action action, SecNode graphIRI
);
Determine if the action is permitted within the graph.
- public boolean evaluate( Action action, SecNode graphIRI, SecTriple triple
);
+ public boolean evaluate( Object principal, Action action, SecNode
graphIRI, SecTriple triple );
Determine if the action is allowed on the triple within the graph.
- public boolean evaluate( Set<Action> actions, SecNode graphIRI );
+ public boolean evaluate( Object principal, Set<Action> actions, SecNode
graphIRI );
Determine if all actions are allowed on the graph.
- public boolean evaluate( Set<Action> actions, SecNode graphIRI, SecTriple
triple );
+ public boolean evaluate( Object principal, Set<Action> actions, SecNode
graphIRI, SecTriple triple );
Determine if all the actions are allowed on the triple within the graph.
- public boolean evaluateAny( Set<Action> actions, SecNode graphIRI );
+ public boolean evaluateAny( Object principal, Set<Action> actions, SecNode
graphIRI );
Determine if any of the actions are allowed on the graph.
- public boolean evaluateAny( Set<Action> actions, SecNode graphIRI,
SecTriple triple );
+ public boolean evaluateAny( Object principal, Set<Action> actions, SecNode
graphIRI, SecTriple triple );
Determine if any of the actions are allowed on the triple within the graph.
- public boolean evaluateUpdate( SecNode graphIRI, SecTriple from, SecTriple
to );
+ public boolean evaluateUpdate( Object principal, SecNode graphIRI,
SecTriple from, SecTriple to );
Determine if the user is allowed to update the "from" triple to the "to"
triple.
- public Principal getPrincipal();
-returns the current principal or null if there is no current principal.
+ public Object getPrincipal();
+Returns the current principal or null if there is no current principal.
## Sample Implementation
@@ -74,6 +74,8 @@ user principal or name from the authenti
model to determine if the user has access, however, that is not a requirement
of the SecurityEvaluator in general.
Determining access from the information provided is an exercise for the
implementer.
+See the example jar for another implementation example.
+
<!-- language: lang-java -->
public class ExampleEvaluator implements SecurityEvaluator {
@@ -94,13 +96,14 @@ Determining access from the information
}
@Override
- public boolean evaluate(Action action, SecNode graphIRI) {
+ public boolean evaluate(Object principal, Action action, SecNode
graphIRI) {
// we allow any action on a graph.
return true;
}
- private boolean evaluate( Resource r )
+ private boolean evaluate( Object principalObj, Resource r )
{
+ Principal principal = (Principal)principalObj;
// a message is only available to sender or recipient
if (r.hasProperty( RDF.type, msgType ))
{
@@ -110,7 +113,7 @@ Determining access from the information
return true;
}
- private boolean evaluate( SecNode node )
+ private boolean evaluate( Object principal, SecNode node )
{
if (node.equals( SecNode.ANY )) {
return false; // all wild cards are false
@@ -118,11 +121,11 @@ Determining access from the information
if (node.getType().equals( SecNode.Type.URI)) {
Resource r = model.createResource( node.getValue() );
- return evaluate( r );
+ return evaluate( principal, r );
}
else if (node.getType().equals( SecNode.Type.Anonymous)) {
Resource r = model.getRDFNode( NodeFactory.createAnon( new
AnonId( node.getValue()) ) ).asResource();
- return evaluate( r );
+ return evaluate( principal, r );
}
else
{
@@ -131,42 +134,42 @@ Determining access from the information
}
- private boolean evaluate( SecTriple triple ) {
- return evaluate( triple.getSubject()) &&
- evaluate( triple.getObject()) &&
- evaluate( triple.getPredicate());
+ private boolean evaluate( Object principal, SecTriple triple ) {
+ return evaluate( principal, triple.getSubject()) &&
+ evaluate( principal, triple.getObject()) &&
+ evaluate( principal, triple.getPredicate());
}
@Override
- public boolean evaluate(Action action, SecNode graphIRI, SecTriple
triple) {
- return evaluate( triple );
+ public boolean evaluate(Object principal, Action action, SecNode
graphIRI, SecTriple triple) {
+ return evaluate( principal, triple );
}
@Override
- public boolean evaluate(Set<Action> actions, SecNode graphIRI) {
+ public boolean evaluate(Object principal, Set<Action> actions, SecNode
graphIRI) {
return true;
}
@Override
- public boolean evaluate(Set<Action> actions, SecNode graphIRI,
+ public boolean evaluate(Object principal, Set<Action> actions, SecNode
graphIRI,
SecTriple triple) {
- return evaluate( triple );
+ return evaluate( principal, triple );
}
@Override
- public boolean evaluateAny(Set<Action> actions, SecNode graphIRI) {
+ public boolean evaluateAny(Object principal, Set<Action> actions,
SecNode graphIRI) {
return true;
}
@Override
- public boolean evaluateAny(Set<Action> actions, SecNode graphIRI,
+ public boolean evaluateAny(Object principal, Set<Action> actions,
SecNode graphIRI,
SecTriple triple) {
- return evaluate( triple );
+ return evaluate( principal, triple );
}
@Override
- public boolean evaluateUpdate(SecNode graphIRI, SecTriple from,
SecTriple to) {
- return evaluate( from ) && evaluate( to );
+ public boolean evaluateUpdate(Object principal, SecNode graphIRI,
SecTriple from, SecTriple to) {
+ return evaluate( principal, from ) && evaluate( principal, to );
}
public void setPrincipal( String userName )
@@ -182,4 +185,4 @@ Determining access from the information
return principal;
}
- }
+ }
\ No newline at end of file
Modified: jena/site/trunk/content/documentation/security/index.mdtext
URL:
http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/security/index.mdtext?rev=1654582&r1=1654581&r2=1654582&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/security/index.mdtext (original)
+++ jena/site/trunk/content/documentation/security/index.mdtext Sat Jan 24
21:44:05 2015
@@ -8,7 +8,7 @@ framework for developers or integrators
- [Overview](#overview)
- [Usage Notes](#usage-notes)
-- [How it Works](#how-it-works)
+- [Jena Security Design](design.html)
- [Security Evaluator](evaluator.html)
- [Assembler](assembler.html)
@@ -28,6 +28,8 @@ optionally triples within the graphs.
The javadocs have additional annotations that specify what permissions at
graph and triple levels are required for
the user to execute the method.
+There is an example jar that contains configuration examples for both a stand
alone application and a fuseki configuration option.
+
## Usage Notes
When the system is correctly configured the developer creates a SecuredGraph
by calling
@@ -51,117 +53,3 @@ the result is a tighter security definit
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.
-## How it Works
-
-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.
-
-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.
-
-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).
-
-Conceptually the framework implements 2 levels of security: graph and triple.
-
-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 `evaluate(
Action.READ, X )`.
-
-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
-`evaluate( Action.READ, X, SecTriple.ALL )`.
-
-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 `evaluate( Action.READ, X, <triple> )`.
-
-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.
-
-### Use of special nodes
-
-Jena-security provides three special nodes to facilitate evaluation of
security policy constraints.
-
-#### SecNode.ANY
-
-This is similar to the Jena `Node.ANY` 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
`evaluate` with some constant
-nodes.
-
-- `<SecNode.ANY, SecNode.ANY, SecNode.ANY>` - Asks if the user may perform the
action on any triple.
-
-- `<X, SecNode.ANY, SecNode.ANY>` - Asks if the user may perform the action
against
-any triple where X is the subject.
-
-- `<SecNode.ANY, X, SecNode.ANY>` - Asks if the user may perform the action
against
-any triple where X is the predicate.
-
-- `<SecNode.ANY, SecNode.ANY, SecNode.X>` - Asks if if the user may perform
the action against
-any triple where X is the object.
-
-The `SecNode.ANY` node may occur multiple times and may occur with the
`SecNode.VARIABLE` and/or
- `SecNode.FUTURE` nodes.
-
-#### SecNode.VARIABLE
-
-This differs from `SecNode.ANY` in that the system is asking "if there are any
prohibitions" not "if the user
-may perform". Thus queries with the `SecNode.VARIABLE` nodes should return
`true` where `SecNode.ANY` returns
-`false`. In general this type is used in the query to determine if triple
level filtering of results must be
-performed.
-
-- `<SecNode.VARIABLE, X, Y>` - Asks if there are any prohibitions against the
user seeing all subjects
-that have property X and object Y.
-
-- `<X, SecNode.VARIABLE, Y>` - Asks if there are any prohibitions against the
user seeing all predicates
-hat have subject X and object Y.
-
-- `<X, Y, SecNode.VARIABLE>` - Asks if there are any prohibitions against the
user seeing all objects
-that have subject X and predicate Y.
-
-The `SecNode.VARIABLE` may occur multiple times and may occur with the
`SecNode.ANY` node.
-
-#### SecNode.FUTURE
-
-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
(`rdfList.concatenate( rdfList2 )`) the system
-will create a series of anonymous nodes. To check for these the
`SecNode.FUTURE` 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 `rdfList2`
-the system will call
-
- evaluate( Action.CREATE, X, <SecNode.FUTURE, RDF.first, node> )
-
-where `node` is the node from `rdfList2` to be added.
-
-
-
-
-
