This documentation is about the specification of *privacy policies with the IND^2^UCE policy language* regulating security-relevant system events.
The IND^2^UCE policy language is designed to express restrictions on data usage.
This documentation is about the specification of *privacy policies with the MYDATA policy language* regulating security-relevant system events.
The MYDATA policy language is designed to express restrictions on data usage.
It is an XML-based language, based on *boolean logic, arithmetics, temporal information based on an event history*.
Furthermore, it allows for evaluations based on push (event-triggered) or pull (timer-triggered).
Connection to external systems for information retrieval is fully supported.
...
...
@@ -58,11 +58,11 @@ Enforcement decisions can be specified by means of *event inhibition, data modif
[[eca]]
== The Event-Condition-Action Schema
IND^2^UCE defines policies based security-relevant link:../api-core/de/fraunhofer/iese/ind2uce/api/policy/Event.html[*events*] that are occurring at a certain time in a system and are intercepted by *"Policy Enforcement Point" (PEP)*.
MYDATA defines policies based security-relevant link:../api-core/de/fraunhofer/iese/ind2uce/api/policy/Event.html[*events*] that are occurring at a certain time in a system and are intercepted by *"Policy Enforcement Point" (PEP)*.
These events are sent to a *"Policy Decision Point" (PDP)*, which evaluates the policies and returns an link:../api-core/de/fraunhofer/iese/ind2uce/api/policy/AuthorizationDecision.html[*Authorization Decision*] based on the policies.
This decision is then enforced by the PEP.
.Basic IND^2^UCE flow
.Basic MYDATA flow
image::PEP.png[cwidth="75%"]
Depending on the system and PEP type, events can highly differ.
...
...
@@ -87,15 +87,15 @@ Parameters:
IND^2^UCE policies are based on the *Event-Condition-Action* (ECA).
MYDATA policies are based on the *Event-Condition-Action* (ECA).
If a system *event E* (see above) is fetched and a *condition C* is satisfied, then *action A* (authorization decision) is performed.
IND^2^UCE follows a blacklisting approach.
MYDATA follows a blacklisting approach.
Events that are not covered by policies are allowed by default.
The following policy shows a simple example.
It translates to: "*Inhibit* the event *urn:action:banking-demo:get-transactions* if it is *after 3pm* (i.e., if the external information source getCurrentHour returns a value below or equal to 15)"
The *<policy>* tag must have at least one *<<mechanism,mechanism>>* child and can optionally contain *<<variableDeclaration-group,variableDeclarations>>*.
The *<policy>* tag must have at least one *<<mechanism,mechanism>>* child and can optionally contain *<<working-with-variables,variableDeclarations>>*.
[[mechanism]]
=== Mechanisms
...
...
@@ -168,9 +168,9 @@ Thus, a *<mechanism>* tag can have the following children:
.Policy Specification Rules
[CAUTION]
===============================
* The child element <<if,<if>>> is mandatory and only allowed to be used once within a <<mechanism,<mechanism>>>.
* The child element <<else,<else>>> is optional but only allowed to be used once within a <<mechanism,<mechanism>>> also.
* The child elements <<elseif,<elseif>>> and <<execute,<execute>>> may be used multiple times.
* The child element <<if_elseif,<if>>> is mandatory and only allowed to be used once within a <<mechanism,<mechanism>>>.
* The child element <<then_else,<else>>> is optional but only allowed to be used once within a <<mechanism,<mechanism>>> also.
* The child elements <<if_elseif,<elseif>>> and <<execute,<execute>>> may be used multiple times.
===============================
.Policy Evaluation Rules
...
...
@@ -217,7 +217,7 @@ The *<if>* and the *<elseif>* elements declare the condition that is evaluated e
A condition must have the following child elements:
* A <<boolean-functions,boolean-function>> that defines the condition
* A <<decision, <then>>> that defines an authorization decision that the mechanism enforces if the condition matches
* A <<then_else, <then>>> that defines an authorization decision that the mechanism enforces if the condition matches
.Policy Specification Rules
...
...
@@ -285,16 +285,16 @@ A condition must have the following child elements:
Decisions are defined inside a *<then>* element inside a <<if_elseif,condition>> (<if> or <elseif>), or in an *<else>* element, which is used if no condition is fulfilled.
These two elements can have the following child elements:
* <<allow,<allow>>>: The event will be allowed
* <<then_else,<allow>>>: The event will be allowed
* <<modify,<modify>>>: The event is allowed, but modified before further execution
* <<inhibit,<inhibit>>>: The event will be inhibited
* <<then_else,<inhibit>>>: The event will be inhibited
* <<execute,<execute>>>: Additional actions are executed, independent of the event allowance
.Policy Specification Rules
[CAUTION]
===============================
* The <then> and the <else> elements must have at either
** exactly one <<allow,binary decision>> (<allow>, <inhibit>), or
** exactly one <<then_else,binary decision>> (<allow>, <inhibit>), or
** at least one <<modify, event modification>> (<modify>), and
** multiple <<execute,executes>>, which are executed in the specified order.
===============================
...
...
@@ -369,7 +369,7 @@ A reason can be added to both elements:
[[modify]]
==== Complex Decisions with Event Modifications
In addition to basic access control mechanisms, IND^2^UCE allows the modification of the intercepted event.
In addition to basic access control mechanisms, MYDATA allows the modification of the intercepted event.
The *<modify>* element is used to specify event modifications that the PEP must enforce before releasing the intercepted event.
It has the following attributes:
...
...
@@ -385,7 +385,7 @@ It has the following attributes:
Some modification methods ("modifiers") require additional parameters.
For example, the "replace" modifier gives you the option to replace a certain string (either the event parameter or part of a complex object) with another String.
This String has to be provided as a <<parameter, parameter>>, as the following example shows.
This String has to be provided as a <<parameter-group, parameter>>, as the following example shows.
Our editor will automatically add stubs for all required parameters.
.Example: Replace the bank code number before showing it
...
...
@@ -410,7 +410,7 @@ Our editor will automatically add stubs for all required parameters.
===============================
JSONPath is an instrument to query JSON structures, similar to XPath for XML.
JSONPath uses special notation to represent nodes and their connections to adjacent nodes in a JsonPath path.
Plese refer to http://goessner.net/articles/JsonPath/ for a full documentation on JsonPath.
Plese refer to https://github.com/json-path/JsonPath for a full documentation on JsonPath.
===============================
.Policy Evaluation Rules
...
...
@@ -432,7 +432,7 @@ See chapter <<working-with-variables, Working with Variables>>.
[[data-types]]
== Data Types
IND^2^CE works with five data types: *String, Number, Boolean, Object and List*.
MYDATA works with five data types: *String, Number, Boolean, Object and List*.
All operators can be combined only depending on their type.
For example, if you have a boolean <and> operator, any kind of boolean children can be attached (e.g., <variable:boolean>, <constant:boolean>, <event:boolen>, <not>, <execute>).
...
...
@@ -441,7 +441,7 @@ For example, if you have a boolean <and> operator, any kind of boolean children
=== Basic Operators
For each of the five <<data-types, data types>>, IND^2^UCE provides five basic operators: *Constants, Variables, Event References, Parameters, and PIPs*.
For each of the five <<data-types, data types>>, MYDATA provides five basic operators: *Constants, Variables, Event References, Parameters, and PIPs*.
These operators will be explained in the following.
[[constant-group]]
...
...
@@ -513,7 +513,7 @@ The elements have the following attributes:
|Attribute |Type |Required |Meaning
|eventParameter |String |required |The name of an event parameter.
|default |same as the event parameter type (string, number, boolean) |required |The value that is returned if the parameter does not exist in the event.
|jsonPathQuery |String |optional |The JSONPath expression to be executed on the parameter value, if the value is a complex object. Please refer to http://goessner.net/articles/JsonPath/ for more information about JsonPath.
|jsonPathQuery |String |optional |The JSONPath expression to be executed on the parameter value, if the value is a complex object. Please refer to https://github.com/json-path/JsonPath for more information about JsonPath.
@@ -693,7 +693,7 @@ Number operators are all operators that have a number as return value.
[[basic-number-operators]]
==== Basic Number Operators
The basic number operators are <<variable-group,<variable:number>>>, <<constant-group,<constant:number>>>, <<parameter-group,<parameter:number>>>, <<event-group,<event:number>>>, and <<pip-group,<pip:number>>>.
The basic number operators are <<working-with-variables,<variable:number>>>, <<constant-group,<constant:number>>>, <<parameter-group,<parameter:number>>>, <<event-group,<event:number>>>, and <<pip-group,<pip:number>>>.
[[arithmetic-functions]]
==== Arithmetic functions
...
...
@@ -746,7 +746,7 @@ Further boolean functions are:
[[basic-boolean-operators]]
==== Basic Boolean Operators
The basic number operators are <<variable-group,<variable:boolean>>>, <<constant-group,<constant:boolean>>>, <<parameter-group,<parameter:boolean>>>, <<event-group,<event:boolean>>>, and <<pip-group,<pip:boolean>>>.
The basic number operators are <<working-with-variables,<variable:boolean>>>, <<constant-group,<constant:boolean>>>, <<parameter-group,<parameter:boolean>>>, <<event-group,<event:boolean>>>, and <<pip-group,<pip:boolean>>>.
[[basic-boolean-functions]]
==== Basic Boolean Functions
...
...
@@ -798,7 +798,7 @@ Child elements can be all elements with boolean return value (e.g. <constant:tru
==== Comparison Functions
The functions *<less>, <lessEqual>, <greater>* and *<greaterEqual>* are used to compare different numbers.
For instance if you want to compare the number of usages with a constant number ("must not be used more than 3 times").
These functions don't have attributes and child elements can be elements with a number return value (like <<pip:number, <pip:number>>>)
These functions don't have attributes and child elements can be elements with a number return value (like <<pip-group, <pip:number>>>)
and the <<number-functions, number-functions>>.
The function *<equals>* is different, because besides numbers other values can be compared with each other. For example, it is possible to compare strings like a constant string and a user name.
...
...
@@ -1128,7 +1128,7 @@ Because <eventHasParameter> refers to a name of an event parameter, it can only
[[basic-string-operators]]
==== Basic String Operators
The basic string operators are <<variable-group,<variable:string>>>, <<constant-group,<constant:string>>>, <<parameter-group,<parameter:string>>>, <<event-group,<event:string>>>, and <<pip-group,<pip:string>>>.
The basic string operators are <<working-with-variables,<variable:string>>>, <<constant-group,<constant:string>>>, <<parameter-group,<parameter:string>>>, <<event-group,<event:string>>>, and <<pip-group,<pip:string>>>.
[[concat]]
...
...
@@ -1183,7 +1183,7 @@ To work with complex objects, you can use link:http://goessner.net/articles/Json
To simplify the handling of these objects, our policy editor supports auto completion to navigate the Json structure.
Direct comparison can be done using <equals>.
The object operators are <<variable-group,<variable:object>>>, <<constant-group,<constant:object>>>, <<parameter-group,<parameter:object>>>, <<event-group,<event:object>>>, and <<pip-group,<pip:object>>>.
The object operators are <<working-with-variables,<variable:object>>>, <<constant-group,<constant:object>>>, <<parameter-group,<parameter:object>>>, <<event-group,<event:object>>>, and <<pip-group,<pip:object>>>.
[[list-functions]]
=== List Operators
...
...
@@ -1194,7 +1194,7 @@ Furthermore, you can use the <<contains, <contains>>> function to check if a lis
The list operators are <<variable-group,<variable:list>>>, <<constant-group,<constant:list>>>, <<parameter-group,<parameter:list>>>, <<event-group,<event:list>>>, and <<pip-group,<pip:list>>>.
The list operators are <<working-with-variables,<variable:list>>>, <<constant-group,<constant:list>>>, <<parameter-group,<parameter:list>>>, <<event-group,<event:list>>>, and <<pip-group,<pip:list>>>.
[[working-with-variables]]
...
...
@@ -1250,7 +1250,7 @@ This is especially important if you are using <<pip-group,PIPs>> or <<execute,PX
This means for example: If a policy contains 5 mechanisms referencing a variable based on a PIP, this PIP is only queried once and the result is used by all mechanisms.
===============================
To reference a variable value inside a <<if_else, condition>> or <<parameter-group, parameter>>, the following variables can be used:
To reference a variable value inside a <<if_elseif, condition>> or <<parameter-group, parameter>>, the following variables can be used:
* <variable:string>
* <variable:number>
...
...
@@ -1264,7 +1264,7 @@ Every element has the reference attribute:
Child elements can be all elements with matching return value (e.g. <constant:true>, <event:boolean> for valueChanged:boolean, <constant:string>, <event:string> for valueChanged:string) or elements of the <<boolean-functions>,boolean-functions>>, <<string-functions>,string-functions>>, <<number-functions,number-functions>>.
Child elements can be all elements with matching return value (e.g. <constant:true>, <event:boolean> for valueChanged:boolean, <constant:string>, <event:string> for valueChanged:string) or elements of the <<boolean-functions,<boolean-functions>>, <<string-functions,<string-functions>>, <<number-functions,number-functions>>.
