++++
[[introduction]]
== Introduction
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.
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.
Enforcement decisions can be specified by means of *event inhibition, data modification using JsonPath (via PEP modifier plugins) and via the execution of actions (via PXP plugins)*.
[[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)*.
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
image::PEP.png[cwidth="75%"]
Depending on the system and PEP type, events can highly differ.
In general, events contain:
* An action name that defines the type of the event
* The time the event occurred
* A key-value list with event parameters
The following example shows an event we will refer to multiple times in this documentation.
It shows an event that is executed when someone reads bank transactions in a web service.
.Example Event for Banking
----
Event ID: "urn:action:banking-demo:get-transactions"
Time: 1533545200
Parameters:
- "customerID" (Number)
- "psd2Id" (Number)
- "transactions" (List of Transaction Objects)
----
IND^2^UCE 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.
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)"
.Example IND^2^UCE security policy
[source,xml]
----
----
[[language-elements]]
== Policy Structure
A *<>* consists of one or more *<>* that are based on the *Event-Condition-Action* (ECA) schema.
IND^2^UCE follows a blacklisting approach.
Events that are not covered by policies are allowed by default.
[[policy]]
=== Policy
The ** tag is the root element of an IND^2^UCE security policy. It has the following attributes:
.Policy attributes
[width="100%",cols="2,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|id |URN |required |The unique id of the policy. The id syntax is urn:policy::. The matches your solution ID and defines the range of effect. The uniquely identifies the policy within the scope.
|name |String |optional |A human readable (short) name for the policy.
|description |String |optional |A more detailed natural language description of the security policy.
|======================================================================================================================================
The ** tag must have at least one *<>* child and can optionally contain *<>*.
[[mechanism]]
=== Mechanisms
A ** tag describes a rule of a policy based on a monitored, intercepted or <> event.
An intercepted event can be allowed (event is released and executed normally),
modified (the event is changed according to the modifiers specified in the mechanism before it is executed) or
inhibited (the event is dropped and will not be executed). A time triggered or monitored event cannot be inhibited or modified - thus, are always allowed.
You can use <> to react on these events.
The ** element has the following attributes:
.Mechanism attributes
[width="100%",cols="2,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|event |URN |required |Specifies the event by which the mechanism is triggered and for which the mechanism provides a security rule. The event follows this pattern: urn:action::
|id |String |optional |A unique id for the mechanism, used for logging purposes only.
|description |String |optional |A natural language description of the mechanism.
|======================================================================================================================================
Mechanisms follow the *if-then-else* schema.
Thus, a ** tag can have the following children:
* <>>: A condition that leads to an authorization decision if it matches
* <>>: A condition that leads to an authorization decision if it matches and the previous if or else-ifs did not match
* <>>: A condition that leads to an authorization decision if none of the previous if or else-ifs matched
* <>>: The unconditional execution of an action
.Policy Specification Rules
[CAUTION]
===============================
* The child element <>> is mandatory and only allowed to be used once within a <>>.
* The child element <>> is optional but only allowed to be used once within a <>> also.
* The child elements <>> and <>> may be used multiple times.
===============================
.Policy Evaluation Rules
[IMPORTANT]
===============================
* A specified <>> as a direct child of the <>> tag is triggered independently of the satisfaction of a condition.
===============================
.Example: Inhibits access to transactions after 3pm and log the event
[source,xml]
----
----
[[if_elseif]]
=== Conditions
The ** and the ** elements declare the condition that is evaluated each time the mechanism fires.
A condition must have the following child elements:
* A <> that defines the condition
* A <>> that defines an authorization decision that the mechanism enforces if the condition matches
.Policy Specification Rules
[CAUTION]
===============================
* The and the must have exactly one boolean function and one child
===============================
.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the condition is not satisfied, then the first condition will be evaluated.
* Only the element of the *first* satisfied or condition will be enforced.
* If no condition is satisfied, then the action defined in the element will be executed.
* If no condition is satisfied and no element is specified, then the event will be allowed (blacklisting).
===============================
.Example: Prohibit access to transactions after 3pm and log access to transactions between 2pm and 3pm
[source,xml]
----
----
[[then_else]]
=== Decisions
Decisions are defined inside a ** element inside a <> ( or ), or in an ** element, which is used if no condition is fulfilled.
These two elements can have the following child elements:
* <>>: The event will be allowed
* <>>: The event is allowed, but modified before further execution
* <>>: The event will be inhibited
* <>>: Additional actions are executed, independent of the event allowance
.Policy Specification Rules
[CAUTION]
===============================
* The and the elements must have at either
** exactly one <> (, ), or
** at least one <> (), and
** multiple <>, which are executed in the specified order.
===============================
.Example: If the role of the user is "ROLE_USER" *then* modify task desricption, name and budget; *else* inhibit
[source,xml]
----
----
[[allow_inhibit]]
==== Simple Decisions
Similar to basic access control mechanisms, an event can be allowed or inhibited.
The ** tag is part of a positive authorization decision. It informs the PEP that the intercepted event can be released for reaching its destination.
The ** tag is part of a negative authorization decision. It informs the PEP that the intercepted event must be dropped so that it never reaches its destination.
A reason can be added to both elements:
.Allow and inhibit attributes
[width="100%",cols="2,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|reason |String |optional |The description or rationale for the decision.
|======================================================================================================================================
.Example: If role is banker then *allow* the event "get transactions" else *inhibit* the event
[source,xml]
----
----
[[modify]]
==== Complex Decisions with Event Modifications
In addition to basic access control mechanisms, IND^2^UCE allows the modification of the intercepted event.
The ** element is used to specify event modifications that the PEP must enforce before releasing the intercepted event.
It has the following attributes:
.Allow and inhibit attributes
[width="100%",cols="2,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|eventParameter |String |required |The name of the event parameter that should be modified.
|method |String |required |The name of the modification that should be applied (e.g., delete, anonymize). This depends on the capabilities of the PEP. Available modifier methods can be checked in your component overview and are proposed by the policy editor.
|jsonPathQuery |String |optional |If the parameter contains a complex object, modifications can be applied to specific parts of the data structure. For example a query "$.firstName" of a parameter "user" will result in the modification of the first name of the user object only.
|reason |String |optional |The description or rationale for the event modification.
|======================================================================================================================================
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 <>, as the following example shows.
Our editor will automatically add stubs for all required parameters.
.Example: Replace the bank code number before showing it
[source,xml]
----
----
.JSONPath
[TIP]
===============================
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.
===============================
.Policy Evaluation Rules
[IMPORTANT]
===============================
When you are using JsonPath, *type safety cannot be guaranteed*.
This means for example that you can overwrite a Number with a String or List.
While this is not a problem for Json / JsonPath, it can (and most likely will) cause problems when deserializting the Json back to an Object at the PEP side.
Thus, you need to take care that all modifications you are doing preserve the type.
Our editor will show corresponding warnings.
===============================
=== Variable Declarations
See chapter <>.
[[data-types]]
== Data Types
IND^2^CE 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 operator, any kind of boolean children can be attached (e.g., , , , , ).
== Operators
=== Basic Operators
For each of the five <>, IND^2^UCE provides five basic operators: *Constants, Variables, Event References, Parameters, and PIPs*.
These operators will be explained in the following.
[[constant-group]]
==== Constants
Constants are used to define a string, number, object, list or boolean that does not depend on any external factor, i.e. cannot change at runtime.
Thus, the value is set during policy specification and does never change.
The following constants are available:
*
*
*
*
*
*
Constants (except and ) have the following attributes:
.Constant attributes
[width="100%",cols="2,4,2,5",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|value |depends on constant type (string, number, boolean) |required |The value of the constant.
|======================================================================================================================================
.Example: If Role is Banker, then inhibit action
[source,xml]
----
----
.Policy Specification Rules
[CAUTION]
===============================
Boolean constants do not have a value. They are explicitly available as and .
===============================
==== Variables
See chapter <>.
[[event-group]]
==== Event references
The event elements are used to reference an event parameter.
The following event elements are available:
*
*
*
*
*
The elements have the following attributes:
.Event attributes
[width="100%",cols="2,4,2,5",options="header"]
|======================================================================================================================================
|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.
|======================================================================================================================================
Remember our example event:
.Example Event
----
Event ID: "urn:action:banking-demo:get-transactions"
Time: 1533545200
Parameters:
- "customerID" (Number)
- "psd2Id" (Number)
- "transactions" (List of Transaction Objects)
----
.Example Policy
[source,xml]
----
----
[[parameter-group]]
==== Parameters
The parameter elements are used for parameterized methods.
In our case this can be either
* a <> or
* an <> or
* an event <>
The following parameter-elements are available:
*
*
*
*
*
Parameters always have a name and a value.
.Parameter attributes
[width="100%",cols="2,4,2,5",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|name |String |required |The name of the parameter.
|value |String |optional |The value of the parameter.
|======================================================================================================================================
Parameters can have one child of the same type (e.g., a string parameter can have a string child).
.Policy Specification Rules
[CAUTION]
===============================
A parameter must have either a value attribute or a child
===============================
.Policy Evaluation Rules
[IMPORTANT]
===============================
* If a parameter has child, the value of the child is used
* If a paramter has a value attribute, this attribute is used as a value
* If a parameter has both, value attribute and child, the child is ignored and the value attribute is used as a value.
===============================
.Example: String parameter inside a PIP
[source,xml]
----
----
[[pip-group]]
==== External Information Sources (PIPs)
The pip elements are used to request information from a link:../sdk/howto_pip.html[PIP]. Each element returns their value (String, number, object, list, boolean). The parameters that can be added as child elements are sent to the PIP as request parameters.
The following pip elements are available:
*
*
*
*
*
The elements have the following attributes:
.PIP attributes
[width="100%",cols="2,4,2,5",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|method |String |required |The name of a PIP method.
|default |same as the pip type (string, number, boolean) |required |The value that is returned if the PIP is not reachable.
|ttl |time interval notation |optional |The "time to live" value sets the time interval that the response value of the PIP is cached. The ttl follows the following syntax: (([0-9]+y)?([0-9]+w)?([0-9]+d)?([0-9]+h)?([0-9]+m)?([0-9]+s)?) (e.g., 1y), where y = years, w = weeks, d = days, h = hours, m = minutes, s = seconds. For example if the pip value should be cached for 1 week, 4 days and 2 hours it would look like "1w4d2h".
|======================================================================================================================================
.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the pip-elements only returns the cached value. When the time to live has elapsed, the cache is refreshed by the current value retrieved by the PIP for the next interval.
* If the "time to live" caching time interval is not set, then the PIP is requested on each PIP element evaluation.
===============================
.Example: PIP to check a role of a user
[source,xml]
----
----
[[number-functions]]
=== Number Operators
Number operators are all operators that have a number as return value.
[[basic-number-operators]]
==== Basic Number Operators
The basic number operators are <>>, <>>, <>>, <>>, and <>>.
[[arithmetic-functions]]
==== Arithmetic functions
The functions *, , * and ** are available to perform the arithmetical operations (addition, subtraction, multiplication, division).
These four functions don't have any attributes and have at least two number children (e.g. , , ).
The ** function is used to count the number of elements in a list or the number of characters in a string.
It doesn't have any attributes, either. You can assign all child elements with a list or string return value.
==== Counting of Events
<>.
==== Continuous Occurrence of Events
<>.
[[boolean-functions]]
=== Boolean Operators
Number operators are all operators that have a boolean as return value.
////
The boolean functions are needed to process boolean values or compare and evaluate other values. The functions can be divided into three different groups:
The following elements are used to compare numbers, strings, objects, lists and boolean:
* (number, string, object, list, boolean)
* (number)
* (number)
* (number)
* (number)
These elements are used to aggregate boolean expressions:
*
*
*
*
*
Further boolean functions are:
* : evaluates if a value has changed
* : evaluates whether the value of the child elements match a given regular expression
* : evaluates whether the declared values are contained in a list
* : evaluates whether the event contains a specified parameter
* : triggers an action in the system and returns a boolean value indicating the execution success
* : evaluates if an event occurs in a certain time frame (minimum and maximum occurrences optional)
////
[[basic-boolean-operators]]
==== Basic Boolean Operators
The basic number operators are <>>, <>>, <>>, <>>, and <>>.
[[basic-boolean-functions]]
==== Basic Boolean Functions
The elements *, , , * and ** aggregate the values of the child elements according to Boolean logic.
The following attribute can be added:
.Basic Boolean Attributes
[width="100%",cols="2,4,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Default Value |Required |Meaning
|mode |String (LAZY, EAGER) |LAZY |optional | It is possible to choose the mode lazy or eager. Lazy evaluation means that an evaluation is stopped as soon as the result cannot change anymore. For example, as soon as the first child of an is false, the other children are not evaluated. If you want to force the evalution of all children (e.g., to eventually execute a PXP), you have to set the mode to EAGER.
|======================================================================================================================================
Child elements can be all elements with boolean return value (e.g. , ) or elements of the <>.
.Policy Specification Rules
[CAUTION]
===============================
* The *, , * and ** elements must have at least one child element.
* The ** element must have exactly one child element.
===============================
.Example: Inhibit transaction if user has id 1 *and* the transaction amount value is greater than 10.000
[source,xml]
----
----
[[comparison-functions]]
==== Comparison Functions
The functions *, , * and ** 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 <>>)
and the <>.
The function ** 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.
** doesn't have an attribute, either.
And besides child elements with a number return value, also elements with string, object, list and boolean return value as well as boolean-functions can be added to .
.Policy Specification Rules
[CAUTION]
===============================
* The elements , , , and must have at least two child elements.
* The order is essential, e.g. for the child elements values A, B and C specified in this order, the ** element evaluates A < B < C.
//* In all child values have to be the same. (It is only possible to compare number with number, string with string,...).
===============================
////
.Example: Inhibit the event "get transactions" if the event already occurred more than 10 times today
[source,xml]
----
----
////
[[regex]]
==== Regular Expressions
A regular expression (regex) is a formal language to describe a certain pattern or a sequence of characters.
If the regex pattern matches to the child-elements value the element returns true otherwise it would return false.
The ** element has the following attributes:
.Regex Attributes
[width="100%",cols="2,4,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Default Value |Required |Meaning
|regex |String |- |required |The String defines the regex that is applied for matching the values of child elements. link:https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java notation is used].
|mode |enum (ALL, EXACTLY_ONE, AT_LEAST_ONE, NONE) |ALL |optional |The mode declares which or how many child element must match.
|======================================================================================================================================
A ** can have the child elements with string return value and elements from the <>.
.Policy Specification Rules
[CAUTION]
===============================
* The element must have at least one child.
===============================
.Policy Evaluation Rules
[IMPORTANT]
===============================
* The ** element has four evaluation modes:
** ALL: Regex must match all of the child element values.
** EXACTLY_ONE: Regex must match exactly one of the child element values, but not more than one.
** AT_LEAST_ONE: Regex must at least match one of the child element values.
** NONE: Regex must not match any of the child element values.
===============================
.Example: If the transaction purpose matches to "Gehalt", "Lohn", "salary" or "pay" than replace the amount
[source,xml]
----
----
[[date-functions]]
==== Date functions
The date functions *,