Commit fbb2a21c authored by Raj Shah's avatar Raj Shah
Browse files

Release 3.2.51

parent 7f5e9d2c
# Compiled class file
*.class
# Log file
*.log
# BlueJ files
*.ctxt
# Mobile Tools for Java (J2ME)
.mtj.tmp/
# Package Files #
*.jar
*.war
*.ear
*.zip
*.tar.gz
*.rar
# IDE files
.settings
.project
.classpath
.checkstyle
*.iml
.idea
# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*
.metadata
bin/
tmp/
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup
pom.xml.next
release.properties
dependency-reduced-pom.xml
buildNumber.properties
.mvn/timing.properties
# Avoid ignoring Maven wrapper jar file (.jar files are usually ignored)
!/.mvn/wrapper/maven-wrapper.jar
*.tmp
*.bak
*.swp
*~.nib
local.properties
.settings/
.loadpath
.recommenders
# External tool builders
.externalToolBuilders/
# Locally stored "Eclipse launch configurations"
*.launch
# PyDev specific (Python IDE for Eclipse)
*.pydevproject
# CDT-specific (C/C++ Development Tooling)
.cproject
# Java annotation processor (APT)
.factorypath
# PDT-specific (PHP Development Tools)
.buildpath
# sbteclipse plugin
.target
# Tern plugin
.tern-project
# TeXlipse plugin
.texlipse
# STS (Spring Tool Suite)
.springBeans
# Code Recommenders
.recommenders/
# Scala IDE specific (Scala & Java development for Eclipse)
.cache-main
.scala_dependencies
.worksheet
# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
# User-specific stuff:
.idea/**/workspace.xml
.idea/**/tasks.xml
.idea/dictionaries
# Sensitive or high-churn files:
.idea/**/dataSources/
.idea/**/dataSources.ids
.idea/**/dataSources.xml
.idea/**/dataSources.local.xml
.idea/**/sqlDataSources.xml
.idea/**/dynamic.xml
.idea/**/uiDesigner.xml
# Gradle:
.idea/**/gradle.xml
.idea/**/libraries
# CMake
cmake-build-debug/
# Mongo Explorer plugin:
.idea/**/mongoSettings.xml
## File-based project format:
*.iws
## Plugin-specific files:
# IntelliJ
out/
# mpeltonen/sbt-idea plugin
.idea_modules/
# JIRA plugin
atlassian-ide-plugin.xml
# Cursive Clojure plugin
.idea/replstate.xml
# Crashlytics plugin (for Android Studio and IntelliJ)
com_crashlytics_export_strings.xml
crashlytics.properties
crashlytics-build.properties
fabric.properties
/.classpath
/.settings
/.project
/.classpath
/internal.iml
/maven-central-deployment-pom.xml
......@@ -3,13 +3,12 @@
<parent>
<groupId>de.fraunhofer.iese.ind2uce</groupId>
<artifactId>parent</artifactId>
<version>3.1.33</version>
<version>3.2.51</version>
</parent>
<artifactId>core</artifactId>
<packaging>jar</packaging>
<version>3.1.33</version>
<version>3.2.51</version>
<name>IND2UCE :: Core</name>
<description>IND2UCE :: Core</description>
<url>https://git.iese.fraunhofer.de/ind2uce/core</url>
......@@ -64,7 +63,11 @@
<groupId>org.hibernate</groupId>
<artifactId>hibernate-entitymanager</artifactId>
</dependency>
<dependency>
<groupId>xerces</groupId>
<artifactId>xercesImpl</artifactId>
<version>2.11.0</version>
</dependency>
</dependencies>
......@@ -74,9 +77,6 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
<configuration>
<tagBase>
https://ind2uce.iese.de/svn/ind2uce/dev2/core/tags/
</tagBase>
<useReleaseProfile>false</useReleaseProfile>
</configuration>
</plugin>
......@@ -130,42 +130,36 @@
</execution>
</executions>
</plugin>
<!-- <plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.5</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>-->
</plugins>
</build>
<distributionManagement>
<snapshotRepository>
<id>ossrh</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
<repository>
<id>ossrh</id>
<url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
<id>deployment</id>
<name>Internal Releases</name>
<url>http://ind2uce-nexus.iese.de/nexus/content/repositories/releases/</url>
</repository>
<snapshotRepository>
<id>deployment</id>
<name>Internal Snapshots</name>
<url>http://ind2uce-nexus.iese.de/nexus/content/repositories/snapshots/</url>
</snapshotRepository>
</distributionManagement>
<scm>
<url>scm:svn:https://ind2uce.iese.de/svn/ind2uce/dev2/core/tags/3.1.33-RELEASE</url>
<connection>scm:svn:https://ind2uce.iese.de/svn/ind2uce/dev2/core/tags/3.1.33-RELEASE</connection>
<developerConnection>scm:svn:https://ind2uce.iese.de/svn/ind2uce/dev2/core/tags/3.1.33-RELEASE
</developerConnection>
<connection>scm:git:http://ind2uce-git.iese.de/ind2uce/dev/core.git</connection>
<developerConnection>scm:git:http://ind2uce-git.iese.de/ind2uce/dev/core.git</developerConnection>
<tag>3.2.51-RELEASE</tag>
</scm>
<licenses>
<license>
<name>The Apache License, Version 2.0</name>
......
= IND^2^UCE Policy Language Documentation - Version 3.0.25
= IND^2^UCE Policy Language Documentation - Version 3.2.46
Fraunhofer IESE
:doctype: book
:icons: font
......@@ -13,2379 +13,564 @@ Fraunhofer IESE
[[introduction]]
= Introduction
This documentation is about the definition of *privacy policies* regulating what must (not) happen to data after its distribution.
Two different methods for enforcing privacy policies exist: preventive and detective enforcement. The former ensures the adherence to obligations by preventing undesired events, such as the redistribution of data. Preventive enforcement can be employed, for example, for digital rights management, which is commonly used by music, video, or eBook download shops. Using preventive mechanisms, the vendor may prevent data consumers from copying a song or a book to more than two devices, for example.
This documentation is about the definition of *privacy policies* regulating security-relevant system events.
In contrast, detective mechanisms are purely reactive. They cannot prevent undesired events, but only ensure the detection of violations and (optionally) the execution of compensating actions or penalties. This principle is comparable with the enforcement of speed limits. While the police cannot prevent drivers from driving too fast, they can detect violations and impose a speeding fine or revoke the driver's license.
Both kinds of mechanisms have advantages and disadvantages in different application scenarios, hence, the optimal solution depends on the field of operation. Preventive mechanisms have the advantage that the adherence to polices can be guaranteed. However, enforcing policy compliance may result in a low acceptance level, since users are generally mistrusted and strictly limited in their actions. On the other hand, integration of preventive mechanisms is often simpler and less invasive in terms of implementation effort. Unlike preventive enforcement, detective policy enforcement lets the user decide whether to adhere to the policy or whether to violate it for good reason. Thus, detective enforcement puts more trust in the rationality of the user and grants more latitude to respond to extraordinary circumstances.
Currently, our policy language supports the declaration of the following features:
* Preventive enforcement
** Inhibition of system event
** Modification of system events
** Delaying of system events
** Execution of compensating actions
* Detective enforcement
** Execution of compensating actions
To express their requirements and enforcement strategies, policies may resort to
* External data sources (e.g., LDAP)
* Boolean and arithmetic expressions
* Fallback strategies
[IMPORTANT]
===============================
* Cardinality and temporal operators are not yet supported in Version 3.0.23 and will be added in the future.
===============================
In general, a *policy* consists of one or more *mechanisms*. These mechanisms (which can be either preventive or detective) describe, what may (not) happen to the affected data item in a specific situation. They are specified as *Event-Condition-Action* rules (ECA): If a system *event E* is detected and *condition C* is satisfied, then *action A* is performed. The IND^2^UCE framework follows a blacklisting approach. Events that do not match a mechanism are allowed by default.
.Example IND^2^UCE security policy:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='Prohibits access to employees after 3pm'>
<preventiveMechanism id='showEmployees'>
<event action='urn:action:cs4:showEmployees'/>
<condition>
<function:lessEqual>
<constant:int value='15'/>
<pip:int method='getCurrentHour' default='0' />
</function:lessEqual>
</condition>
<authorizationDecision name='showEmployeesDecision'>
<inhibit/>
</authorizationDecision>
</preventiveMechanism>
</policy>
----
[[tutorial]]
= Tutorial
This tutorial guides you step-by-step through the specification process of a policy. For easy specification, we recommend using our policy editor in the Management Service.
In this tutorial, we are specifying a security policy for the following scenario:
At a construction site, the employees report their hours worked on different projects. Each project is assigned to a foreman. The foreman is only allowed to see aggregated reported efforts per project, but only if the project teams contain at least 5 employees. Otherwise, if the project team has less than 5 employees, he is not allowed to see efforts as he could maybe extract efforts of individual persons. Every access to the aggregated efforts by the foreman needs to be reported to the construction site manager. If this reporting fails, access is prohibited. Employees with other roles are not allowed to see any effort data. The construction site manager gets full access to employee efforts, but access needs to be logged.
We will now specify the appropriate security policy step-by-step and link to the corresponding language constructs. The final security policy can be found in the <<summary,Summary>> subsection.
In this scenario, the response message from the server is intercepted or monitored by a PEP, which also defines the event structure.
In general, an event has an action name and a list of parameters (key-value pairs). In our case, the event structure is as follows:
* Action name: urn:action:cs4:showProjectEffort
* Parameters:
** employeeId: id of the requesting employee
** projectId: id of the project for which effort numbers are requested
** effortData: the requested effort data
First, we need to identify the mechanisms that we have to specify within our security policy. Remember that each mechanism follows the Event-Condition-Action paradigm (if a system event *E* is detected and condition *C* is satisfied, then action *A* is performed). Thus, the following four mechanisms need to be specified:
* <<mechanism1,Mechanism 1>>: Anonymize effort data if foreman accesses projects with at least 5 employees. Allow access only if construction site manager is notified about access.
* <<mechanism2,Mechanism 2>>: Prevent foremen from accessing effort data of projects with less than 5 employees.
* <<mechanism3,Mechanism 3>>: Log access to effort data by construction site managers.
* <<mechanism4,Mechanism 4>>: Prevent other employee roles from accessing effort data.
[TIP]
===============================
* Read the <<mechanism1,specification of the first mechanism>> first as it describes more details than the other three examples.
===============================
[[mechanism1]]
== Specifying the first mechanism
With the first mechanism, we want to achieve the following security behavior:
Anonymize effort data if foremen accesses projects with at least 5 employees. Allow access only if construction site manager is notified about access.
First of all, we need to decide whether our mechanism is preventive (<<preventive-mechanism,<preventiveMechanism>>>), i.e., intercepting events, or detective (<<detective-mechanism,<detectiveMechanism>>>), i.e., only detecting events. As we want to anonymize data, we need to intercept and modify an event. Thus, we need a preventive mechanism.
.Preventive mechanism construct:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='Tutorial policy.'>
<preventiveMechanism id='anonymizeEffortsIfEmployeesGreaterEqual5'>
<description>This mechanism anonymizes effort data if a foreman accesses projects with at least 5 employees.</description>
...
</preventiveMechanism>
...
</policy>
----
Next, we need to declare which type of <<event,event>> we want to analyze with this mechanism. We choose one of the actions that the available PEPs can provide. In our case, all events with action "urn:action:cs4:showProjectEffort" are intercepted and sent to the PDP for evaluation. If it was necessary, we could further filter the events by matching against specific event parameter values.
.Security policy with added event declaration:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='Tutorial policy.'>
<preventiveMechanism id='anonymizeEffortsIfEmployeesGreaterEqual5'>
<description>This mechanism anonymizes effort data if a foreman accesses projects with at least 5 employees.</description>
<event action='urn:action:cs4:showProjectEffort'/>
...
</preventiveMechanism>
...
</policy>
----
In the condition, we have to check two different facts linked with the <<and,<and>>> operator. The first check is about the role of the accessing entity. However, this information is not apparent from the event and needs to be retrieved from external sources. For this scenario, let us assume that the following information sources are available, which we can retrieve via a PIP:
[options='header']
|======================================================================================================================================
|Method |Return Type |Parameters |Meaning
|getEmployeeRole |String |<param:string name='id'/> |Returns the role of an employee with the id entered as a parameter of type String. Possible return values are EMPLOYEE, FOREMAN, or CONSTRUCTION_SITE_MANAGER.
|getAllEmployees |List |<param:string name='projectId'/> |Returns a list with all project members.
|======================================================================================================================================
We request the role of a user from PIP (<<pip-string,<pip:string>>>) using the method "getEmployeeRole" and compare it to the constant value "FOREMAN" (<<constant-string,<constant:string>>>) using the <<function-equals,<function:equals>>> operator. If the information cannot be retrieved from the PIP, we assume the default value "EMPLOYEE".
The method "getEmployeeRole" requires the provision of a parameter "id" that represents the id of the requesting user. We can retrieve this information from the event, where it is stored under the key "employeeId".
Thus, we need to do a relabeling (described in more detail in Subsection <<parameters,Parameters>>). In general, for every parameter, the following priorities apply for the resolution of the parameter value:
1. the value of the "value" attribute
2. the value of the child attribute
3. the value of the event parameter with the same name
The <<param-string,<param:string>>> element inside the <<pip-string,<pip:string>>> does not have a value and is thus using the value of its child element. This child element has neither a value nor a child, so it refers to the event parameter with the name "employeeId".
.Security policy with added string comparison of role requested from a PIP:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='Tutorial policy.'>
<preventiveMechanism id='anonymizeEffortsIfEmployeesGreaterEqual5'>
<description>This mechanism anonymizes effort data if a foreman accesses projects with at least 5 employees.</description>
<event action='urn:action:cs4:showProjectEffort'/>
<condition>
<and>
<function:equals>
<pip:string method='getEmployeeRole' default='EMPLOYEE' ttl='600'>
<param:string name='id'>
<param:string name='employeeId'/>
</param:string>
</pip:string>
<constant:string value='FOREMAN'/>
</function:equals>
...
</and>
</condition>
</preventiveMechanism>
...
</policy>
----
The second check evaluates whether the number of employees in the project is greater or equal to five. We request the list of employees with the <<pip-list,<pip:list>>> operator and count the elements of this list with the <<function-size,<function:size>>> function. The result is then compared with a <<constant-int,<constant:int>>> using the <<function-greater-equal,<function:greaterEqual>>> function. In combination, the first and the second check imply that the condition is satisfied if the requesting entity is a foreman and the number of employees in the requested project is at least five.
.Security policy with added second check for employee count within project:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='Tutorial policy.'>
<preventiveMechanism id='anonymizeEffortsIfEmployeesGreaterEqual5'>
<description>This mechanism anonymizes effort data if a foreman accesses projects with at least 5 employees.</description>
<event action='urn:action:cs4:showProjectEffort'/>
<condition>
<and>
<function:equals>
<pip:string method='getEmployeeRole' default='EMPLOYEE' ttl='600'>
<param:string name='id'>
<param:string name='employeeId'/>
</param:string>
</pip:string>
<constant:string value='FOREMAN'/>
</function:equals>
<function:greaterEqual>
<function:size>
<pip:list method='getAllEmployees' default='[]' ttl='600'>
<param:string name='projectId'/>
</pip:list>
</function:size>
<constant:int value='5'/>
</function:greaterEqual>
</and>
</condition>
...
</preventiveMechanism>
...
</policy>
----
After having the event and the condition specified, we need to specify what should happen when a matching event occurs that meets the condition. This is done inside the <<authorization-decision,<authorizationDecision>>> tag.
In our scenario, we basically want to allow the event, but anonymize the event data. Thus, we add an <<allow,<allow>>> tag. For applying an anonymization, we need to add a <<modify,<modify>>> tag inside the <<allow,<allow>>>. Inside the <<modify,<modify>>> tag, we can define a list of event parameters to be changed with the <<param-event,<param:event>>> tag. We add one list element with a reference to the event parameter "effortData". Next, we specify the kind of modification with the <<function-engine,<function:engine>>> tag including the required parameters. The information about available modifiers is provided by the PEPs.
Besides the modification obligation, we only want to allow the access if the construction site manager is informed about the access. This is achieved via a PXP. In our scenario, the following PXP functionality is available:
[options='header']
|======================================================================================================================================
|Action |Parameters |Meaning
|urn:action:cs4:sendNotificationToConstructionSiteManager |<param:string name='message'/> |Sends a notification to the construction site manager
|urn:action:cs4:log |<param:string name='message'/> |Writes a log entry
|======================================================================================================================================
Accordingly, we place an <<execute-action,<executeAction>>> inside the <<allow,<allow>>> element. The notification message shall contain information from the current event. Therefore, we concatenate information from the event with constant strings using the <<function-concat,<function:concat>>> function.
.Security policy with added authorization action:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='Tutorial policy.'>
<preventiveMechanism id='anonymizeEffortsIfEmployeesGreaterEqual5'>
<description>This mechanism anonymizes effort data if a foreman accesses projects with at least 5 employees.</description>
<event action='urn:action:cs4:showProjectEffort'/>
<condition>
...
</condition>
<authorizationDecision name='anonymizeEffortsIfEmployeesGreaterEqual5Decision' fallback='notificationNotSentToConstructionSiteManager'>
<allow>
<modify>
<param:event name='effortData'>
<function:engine method='anonymizeNames'>
<param:string name='replacementCharacter' value='X'/>
</function:engine>
</param:event>
</modify>
<executeAction name='urn:action:cs4:sendNotificationToConstructionSiteManager'>
<param:string name='message'>
<function:concat>
<constant:string value='Foreman with id '/>
<param:string name='employeeId'/>
<constant:string value=' accessed project with id '/>
<param:string name='projectId'/>
<constant:string value=' with anonymized effort data.'/>
</function:concat>
</param:string>
</executeAction>
</allow>
</authorizationDecision>
...
</preventiveMechanism>
...
</policy>
----
But what happens if the notification fails? In this case, the authorizationAction (allow but modify) is not accomplishable and a fallback authorization action will be enforced instead. The default fallback prevents access completely (= <<inhibit,<inhibit>>>), thus ensuring that policy enforcement fails securely.
If we want to customize the fallback (e.g., by adding an additional log entry), we add the <<fallback-authorization-decision,<fallbackAuthorizationDecision>>> with the name "notificationNotSentToConstructionSiteManager" to the mechanism and add a reference to this fallback in the "fallback" attribute of the previously specified <<authorization-decision,<authorizationDecision>>>. The <<fallback-authorization-decision,<fallbackAuthorizationDecision>>> prevents the access with an <<inhibit,<inhibit>>> tag. In addition, a log entry is written using the <<execute-action,<executeAction>>> "urn:action:cs4:log".
The complete specification of the first mechanism is as follows:
.Security policy with mechanism for anonymizing effort data if foremen accesses projects with at least 5 employees:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='Tutorial policy.'>
<preventiveMechanism id='anonymizeEffortsIfEmployeesGreaterEqual5'>
<description>This mechanism anonymizes effort data if a foreman accesses projects with at least 5 employees.</description>
<event action='urn:action:cs4:showProjectEffort'/>
<condition>
<and>
<function:equals>
<pip:string method='getEmployeeRole' default='EMPLOYEE' ttl='600'>
<param:string name='id'>
<param:string name='employeeId'/>
</param:string>
</pip:string>
<constant:string value='FOREMAN'/>
</function:equals>
<function:greaterEqual>
<function:size>
<pip:list method='getAllEmployees' default='[]' ttl='600'>
<param:string name='projectId'/>
</pip:list>
</function:size>
<constant:int value='5'/>
</function:greaterEqual>
</and>
</condition>
<authorizationDecision name='anonymizeEffortsIfEmployeesGreaterEqual5Decision' fallback='notificationNotSentToConstructionSiteManager'>
<allow>
<modify>
<param:event name='effortData'>
<function:engine method='anonymizeNames'>
<param:string name='replacementCharacter' value='X'/>
</function:engine>
</param:event>
</modify>
<executeAction name='urn:action:cs4:sendNotificationToConstructionSiteManager'>
<param:string name='message'>
<function:concat>
<constant:string value='Foreman with id '/>
<param:string name='employeeId'/>
<constant:string value=' accessed project with id '/>
<param:string name='projectId'/>
<constant:string value=' with anonymized effort data.'/>
</function:concat>
</param:string>
</executeAction>
</allow>
</authorizationDecision>
<fallbackAuthorizationDecision name='notificationNotSentToConstructionSiteManager'>
<inhibit/>
<executeAction name='urn:action:cs4:log'>
<param:string name='message' value='Inhibit access as notification was not sent to Construction Site Manager'/>
</executeAction>
</fallbackAuthorizationDecision>
</preventiveMechanism>
...
</policy>
----
[[mechanism2]]
== Specifying the second mechanism
With the second mechanism of our security policy, we want to achieve the following security behavior:
Prevent foremen from accessing effort data of projects with less than 5 employees.
This mechanism differs from the <<mechanism1,first specified mechanism>> in two aspects. First, the condition needs to be adapted so that it is satisfied if the number of employees in the project is less than five. Therefore, we take the same condition and replace the <<function-greater-equal,<function:greaterEqual>>> function by the <<function-less,<function:less>>> function. As we just want to prevent the access, we simply add an <<authorization-decision,<authorizationDecision>>> that contains an <<inhibit,<inhibit>>> tag. Moreover, we add an <<execute-action,<executeAction>>> with the action "urn:action:cs4:log" because we want to log all security decisions.
.Second mechanism:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='Tutorial policy.'>
...
<preventiveMechanism id='inhibitDetailedViewLessThan5Employees'>
<description>This mechanism prevents foremen from accessing effort data of projects with less than 5 employees.</description>
<event action='urn:action:cs4:showProjectEffort'/>
<condition>
<and>
<function:equals>
<pip:string method='getEmployeeRole' default='EMPLOYEE' ttl='600'>
<param:string name='id'>
<param:string name='employeeId'/>
</param:string>
</pip:string>
<constant:string value='FOREMAN'/>
</function:equals>
<function:less>
<function:size>
<pip:list method='getAllEmployees' default='[]' ttl='600'>
<param:string name='projectId'/>
</pip:list>
</function:size>
<constant:int value='5'/>
</function:less>
</and>
</condition>
<authorizationDecision name='inhibitAccessOnEffortData'>
<inhibit/>
<executeAction name='urn:action:cs4:log'>
<param:string name='message' value='Access to effort data not allowed due to too few employees in project.'/>
</executeAction>
</authorizationDecision>
</preventiveMechanism>
...
</policy>
----
[[mechanism3]]
== Specifying the third mechanism
With the third mechanism of our security policy, we want to achieve the following security behavior:
Log access to effort data by construction site managers.
This mechanism shall only monitor access to effort data. Therefore, we use a <<detective-mechanism,<detectiveMechanism>>> instead of a preventive one. Each time the event is detected, a log entry is written.