= IND^2^UCE Policy Language Documentation - Version 3.0.25
Fraunhofer IESE
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 4
:sectlinks:
:stylesdir: ./css
:stylesheet: ind2uce.css
:linkcss:

[[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.

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.

.Final security policy:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='Tutorial policy.'>
  ...
  <detectiveMechanism id='logAccessByConstructionSiteManager'>
    <description>This mechanism logs access to effort data by construction site managers.</description>
    <event action='urn:action:cs4:showProjectEffort'/>
    <condition>
      <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='CONSTRUCTION_SITE_MANAGER'/>
      </function:equals>
    </condition>
    <executeAction name='urn:action:cs4:log'>
      <param:string name='message'>
        <function:concat>
          <constant:string value='Construction Site Manager with id '/>
          <param:string name='employeeId'/>
          <constant:string value=' accessed project with id '/>
          <param:string name='projectId'/>
          <constant:string value='.'/>
        </function:concat>
      </param:string>
    </executeAction>
  </detectiveMechanism>
</policy>
----

[[mechanism4]]
== Specifying the fourth mechanism

With the fourth mechanism of our security policy, we want to achieve the following security behavior:

 Prevent other employee roles from accessing effort data.

In this mechanism, we want to check that the requesting entity is neither a foreman nor a construction site manager. Thus, we check for those two roles with PIP requests in the condition and negate the return values. If both checks return true, then we know that another role wants to access the effort data. Those access requests can be denied with an <<authorization-decision,<authorizationDecision>>> that contains an <<inhibit,<inhibit>>> tag.

.Final security policy:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='Tutorial policy.'>
  ...
  <preventiveMechanism id='inhibitAccessFromOtherRoles'>
    <description>This mechanism prevents employees that are neither foremen nor construction site managers from accessing effort data.</description>
    <event action='urn:action:cs4:showProjectEffort'/>
    <condition>
      <and>
        <not>
          <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>
        </not>
        <not>
          <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='CONSTRUCTION_SITE_MANAGER'/>
          </function:equals>
        </not>
      </and>
    </condition>
    <authorizationDecision name='inhibitAccessFromOtherRolesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
  ...
</policy>
----


[[summary]]
== Summary

Congratulations! You successfully specified your first privacy policy. The policy contains four mechanisms:

* <<mechanism1,Mechanism 1>>: Anonymize effort data if a foreman accesses projects with at least 5 employees. Allow access only if construction site manager is notified about access.
* <<mechanism1,Mechanism 2>>: Prevent foremen from accessing effort data of projects with less than 5 employees.
* <<mechanism1,Mechanism 3>>: Log accesses to effort data by construction site managers.
* <<mechanism1,Mechanism 4>>: Prevent other employee roles from accessing effort data.

.Final security policy:
[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>

  <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>

  <preventiveMechanism id='inhibitAccessFromOtherRoles'>
    <description>This mechanism prevents employees that are neither foremen nor construction site managers from accessing effort data.</description>
    <event action='urn:action:cs4:showProjectEffort'/>
    <condition>
      <and>
        <not>
          <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>
        </not>
        <not>
          <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='CONSTRUCTION_SITE_MANAGER'/>
          </function:equals>
        </not>
      </and>
    </condition>
    <authorizationDecision name='inhibitAccessFromOtherRolesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>

  <detectiveMechanism id='logAccessByConstructionSiteManager'>
    <description>This mechanism logs access by construction site managers to effort data.</description>
    <event action='urn:action:cs4:showProjectEffort'/>
    <condition>
      <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='CONSTRUCTION_SITE_MANAGER'/>
      </function:equals>
    </condition>
    <executeAction name='urn:action:cs4:log'>
      <param:string name='message'>
        <function:concat>
          <constant:string value='Construction Site Manager 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>
  </detectiveMechanism>
</policy>
----

[[q-and-a]]
= FAQ

This section answers frequently asked questions about the specification of security policies with the IND^2^UCE security policy language.

.Where are the operators for expressing cardinal and temporal conditions?
[TIP]
===============================
These operators are currently not supported, but will be added in a later release.
===============================

.What is the distinction between event and action?
[TIP]
===============================
An event is an action that is performed at a specific point in time within a system. We are intercepting and monitoring events with the IND^2^UCE Framework. In the <<event,<event>>> declarations, we specify in the "action" attribute that we want to intercept or monitor events performing a specific action. In <<execute-action,<executeAction>>> elements, we also specify the action that the PXP must execute as an "action" attribute.
===============================


[[dos-and-donts]]
= Do's and Don'ts

This section gives you some hints, what you should and should not do with the IND^2^UCE policy language.

== Do's

.Unique identifiers
[NOTE]
===============================
* Use unique identifiers for different policies
* Use unique identifiers for all mechanisms and decisions inside a policy.
===============================

== Don'ts

.Don't Topic
[WARNING]
===============================
* Don't do that.
===============================


[[language-elements]]
= Language Elements

[[policy]]
== policy

The *<policy>* tag is the root element of an IND²UCE security policy. It has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|id           |URN       |-             |yes      |The id of the policy must be unique within its enforcement scope. The id syntax is urn:policy:_scope_:_identifier_.
|description  |String    |-             |yes      |A natural language description of the security policy
|======================================================================================================================================

The *<policy>* tag must have at least one of the following child elements:

* <<preventive-mechanism,<preventiveMechanism>>>
* <<detective-mechanism,<detectiveMechanism>>>

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:blurNames' description='This policy blurs all names in the cs4 webservice frontend.'>
  <detectiveMechanism id='monitorAccessOnNames'>
    ...
  </detectiveMechanism>
  <preventiveMechanism id='blurTheNames'>
    ...
  </preventiveMechanism>
</policy>
----

[[preventive-mechanism]]
=== preventiveMechanism

The *<preventiveMechanism>* tag is used for specifying a preventive security mechanism within a policy. Preventive mechanisms support the interception of events (declared by the <<event,Event>> tag) in event flows in the system. Depending on the policy specification and evaluation, the intercepted event can be allowed (event is sent to its destination), modified (the event content is changed, then the changed event is sent to the destination), delayed (the sending of the event to the destination is delayed by a specified amount of time), or inhibited (the event is dropped and will not reach its destination). If an event that is matching the event declaration is intercepted by a PEP, the event is sent to the PDP. The PDP checks whether the condition is satisfied. If it is satisfied, the specified <<authorization-decision,authorizationDecision>> is enforced. If the condition is not satisfied, the <<authorization-decision,<authorizationDecision>>> is not enforced. If none of the conditions is satisfied, the default <<authorization-decision,<authorizationDecision>>> is <<allow,<allow>>>.

The *<preventiveMechanism>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|id           |String    |-             |no       |A unique id for the mechanism. Can be any string value. If the id is not set, an id will be generated by the PDP during deployment.
|======================================================================================================================================

A *<preventiveMechanism>* can have the following child elements:

* <<description,<description>>>
* <<timestep,<timestep>>>
* <<event,<event>>>
* <<condition,<condition>>>
* <<authorization-decision,<authorizationDecision>>>
* <<fallback-authorization-decision,<fallbackAuthorizationDecision>>>
* <<execute-action,<executeAction>>>

.Policy Specification Rules
[CAUTION]
===============================
* The child elements <<event,<event>>>, <<condition,<condition>>>, and <<authorization-decision,<authorizationDecision>>> are mandatory.
* The child elements <<description,<description>>>, <<timestep,<timestep>>>, <<event,<event>>>, <<condition,<condition>>>, and <<authorization-decision,<authorizationDecision>>> are only allowed to be used once within a <preventiveMechanism>.
* The child elements <<fallback-authorization-decision,<fallbackAuthorizationDecision>>> and <<execute-action,<executeAction>>> may be used multiple times.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* A specified <<execute-action,<executeAction>>> inside the <preventiveMechanism> tag is executed upon satisfaction of the condition. Its return value is ignored. In contrast, the value of an <<execute-action,<executeAction>>> inside an <<allow,<allow>>> element affects the evaluation of the surrounding <<authorization-decision,<authorizationDecision>>>.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy inhibits the display of employees.'>
  <preventiveMechanism id='showEmployees'>
    <description>This mechanism inhibits the display of employees.</description>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='allowShowingEmployees'>
      <inhibit/>
    </authorizationDecision>
    <executeAction name='urn:action:cs4:log'>
      <param:string name='message' value='Displaying employee was prevented!'/>
    </executeAction>
  </preventiveMechanism>
</policy>
----

[[detective-mechanism]]
=== detectiveMechanism

The *<detectiveMechanism>* tag is used for specifying a detective security mechanism in a policy. Detective mechanisms support either the monitoring of events (declared by the <<event,<event>>> tag) in event flows in the system or the time-based evaluation (declared with the <<timestep,<timestep>>> element) of the <<condition,<condition>>>. Events are not intercepted. If the condition is satisfied, the specified <<executeAction,<executeAction>>> elements are executed; if it is not satisfied, nothing happens.

The *<detectiveMechanism>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|id           |String    |-             |no       |A unique id for the mechanism. Can be any string value. If the id is not set, an id will be generated by the PDP during deployment.
|======================================================================================================================================

A *<detectiveMechanism>* can have the following child elements:

* <<description,<description>>>
* <<timestep,<timestep>>>
* <<event,<event>>>
* <<condition,<condition>>>
* <<execute-action,<executeAction>>>

.Policy Specification Rules
[CAUTION]
===============================
* You have to add at least one of the two child elements <<timestep, <timestep>>> or <<event,<event>>>.
* The child elements <<description, <description>>>, <<timestep, <timestep>>>, <<event,<event>>>, and <<condition,<condition>>> are only allowed to be used once within a <detectiveMechanism>.
* At least one <<execute-action,<executeAction>>> element is required.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:sendMailAboutCurrentStatus' description='This policy regularly logs the current status.'>
  <detectiveMechanism id='sendMailAboutCurrentStatus'>
    <description>This mechanism regularly logs the current status.</description>
    <timestep amount='5' unit='MINUTES'/>
    <condition>
      <true/>
    </condition>
    <executeAction name='urn:action:cs4:log'>
      <param:string name='message' value='Current Status is: all ok!'/>
    </executeAction>
  </detectiveMechanism>
</policy>
----


== Mechanism Elements

[[description]]
=== description

The *<description>* tag should contain a natural language description of the mechanism's effect. This tag has no effect on the policy evaluation.

[[timestep]]
=== timestep

The *<timestep>* element can be used to refer to clock events. These events are implicitly provided by the IND²UCE framework; there is no need to implement a system clock and a PEP that intercepts clock ticks explicitly. Accordingly, the *<timestep>* element can replace a corresponding *<event>* element within a mechanism specification.

The *<timestep>* tag declares the following two evaluation properties:

* The condition state is updated once in each timestep. If the condition is satisfied, the mechanism is triggered.
* The unit in time-based operators can be set to TIMESTEP. Then it is a reference to the amount of time specified in the <timestep> element.

The *<timestep>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|amount       |Integer   |-             |yes      |Amount of time units.
|unit         |enum      |-             |yes      |Time unit. Possible units are MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:sendMailAboutCurrentStatus' description='This policy regularly logs the current status.'>
  <detectiveMechanism id='sendMailAboutCurrentStatus'>
    <description>This mechanism regularly logs the current status.</description>
    <timestep amount='5' unit='MINUTES'/>
    <condition>
      <true/>
    </condition>
    <executeAction name='urn:action:cs4:log'>
      <param:string name='message' value='Current Status is: all ok!'/>
    </executeAction>
  </detectiveMechanism>
</policy>
----

[[event]]
=== event

The *<event>* tag is used for declaring the events on which the mechanism should fire. Besides the action name, you can filter the events with additional parameters. The policy fires only if all declared parameter values match the intercepted or detected event parameter values.

The *<event>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|action       |URN       |-             |yes      |The id of the action to be intercepted. The id syntax is urn:action:_scope_:_action_.
|======================================================================================================================================

A *<event>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>
* <<param-object,<param:object>>>
* <<param-list,<param:list>>>

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy filters the events to be intercepted.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:string name='role' value='employees'/>
      <param:boolean name='onlyAdults' value='true'/>
      <param:int name='maxAge' value='65'/>
    </event>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[condition]]
=== condition

The *<condition>* element declares the condition that is evaluated each time the mechanism fires.

A *<condition>* can have the following child elements:

|======================================================================================================================================
|<<true,<true>>>|<<param-boolean,<param:boolean>>>|<<function-less,<function:less>>>
|<<false,<false>>>|<<pip-boolean,<pip:boolean>>>|<<function-less-equal,<function:lessEqual>>>
|<<not,<not>>>||<<function-greater,<function:greater>>>
|<<and,<and>>>||<<function-greater-equal,<function:greaterEqual>>>
|<<or,<or>>>||<<function-equals,<function:equals>>>
|<<implies,<implies>>>||<<function-exists,<function:exists>>>
|||<<function-regex,<function:regex>>>
|||<<function-contains,<function:contains>>>|
|======================================================================================================================================

.Policy Specification Rules
[CAUTION]
===============================
* The <condition> element must have exactly one child element. For more complex conditions, the Boolean operators (<<and,<and>>>, <<or,<or>>>, etc.) need to be used.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees that are older than 30 and in the role of a teamleader as well as from senior engineers.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
  	   <or>
  	     <and>
  	       <function:greater>
  	         <param:int name='age'/>
  	         <constant:int value='30'/>
  	       </function:greater>
  	       <function:equals>
  	         <param:string name='role'/>
  	         <constant:string value='TEAMLEADER'/>
  	       </function:equals>
  	     </and>
  	     <pip:boolean method='urn:pip:isSeniorEngineer' default='false'/>
  	   </or>
  	 </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[true]]
==== true

The *<true>* tag returns the Boolean value true for the condition evaluation.

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents the display of employee data.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[false]]
==== false

The *<false>* tag returns the Boolean value false for the condition evaluation.

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy allows the display of employee data as the default authorization decision in case of unsatisfied condition is allow.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <false/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[authorization-decision]]
=== authorizationDecision

For preventive mechanisms, one or more *<authorizationDecision>* blocks have to be specified in the policy. If the condition evaluates to true, the specified authorization decision is returned to the PEP which intercepted the event. Then, the PEP enforces the authorization decision.

The *<authorizationDecision>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |no       |The unique identifier of the authorization action. If the id is not set, an id will be generated by the PDP during deployment.
|fallback     |String    |-             |no       |This is a reference to the <<fallback-authorization-decision,<fallbackAuthorizationDecision>>> that is enforced if an <<execute-action,<executeAction>>> within the <authorizationDecision> cannot be successfully executed.
|======================================================================================================================================

A *<authorizationDecision>* can have the following child elements:

* <<allow,<allow>>>
* <<inhibit,<inhibit>>>
* <<execute-action,<executeAction>>>

.Policy Specification Rules
[CAUTION]
===============================
* You must either add the <<allow,<allow>>> or the <<inhibit,<inhibit>>> element.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* The execute actions specified inside the <authorizationDecision> tag are executed upon satisfaction of the condition. Their return value is ignored. Only a negative return value from execute actions specified inside the <<allow,<allow>>> element leads to the enforcement of <<fallback-authorization-decision,fallback authorization decisions>>. If the execution of such an <<execute-action,<executeAction>>> fails, further execute actions are not triggered and the defined fallback is called instead.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy only shows names if the log was successful.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision' fallback='abort'>
      <allow>
    	   <executeAction name='urn:action:cs4:log'>
    	     <param:string name='message' value='Log message'/>
    	   </executeAction>
      </allow>
    </authorizationDecision>
    <fallbackAuthorizationDecision name='abort'>
      <inhibit/>
    </fallbackAuthorizationDecision>
  </preventiveMechanism>
</policy>
----

[[allow]]
==== allow

The *<allow>* tag is part of a positive authorization decision. It informs the PEP that the intercepted event can be released for reaching its destination.

A *<allow>* can have the following child elements:

* <<modify,<modify>>>
* <<execute-action,<executeAction>>>
* <<delay,<delay>>>

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy allows showing names if the log action is successful.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
  	    <executeAction name='urn:action:cs4:log'>
  	      <param:string name='message' value='Mandatory execute action inside allow'/>
  	    </executeAction>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[inhibit]]
==== inhibit

The *<inhibit>* 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 *<inhibit>* can have the following child elements:

* <<delay,<delay>>>

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prohibits showing names.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[modify]]
==== modify

The *<modify>* element is used to specify event parameter modifications that the PEP must enforce before releasing the intercepted event.

A *<modify>* can have the following child elements:

* <<param-event,<param:event>>>

.Policy Specification Rules
[CAUTION]
===============================
* A <modify> tag must at least contain one <<param-event,<param:event>>> element.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:anonymizeNamesOfEmployees' description='This policy anonymizes last names.'>
  <preventiveMechanism id='anonymizeTheNames'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='replacementCharacter' value='X'/>
              <param:int name='visibleCharacters' value='2'/>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[delay]]
==== delay

The *<delay>* element is used to delay the releasing of the intercepted event by the PEP.

The *<delay>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|amount       |Integer   |-             |yes      |Amount of time units.
|unit         |enum      |TIMESTEP      |yes      |Time unit. Possible units are TIMESTEPS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* The unit TIMESTEPS is a reference to the specified <<timestep,<timestep>>> element. In this case, the amount value in the delay element is multiplied by the time frame set in the <<timestep,<timestep>>> element.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:delayShowingEmployeeNames' description='This policy delays the displaying of names by 30 SECONDS.'>
  <preventiveMechanism id='delayShowingEmployeeNames'>
    <timestep  amount='10' unit='SECONDS'/>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <delay amount='3' unit='TIMESTEPS'/>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[fallback-authorization-decision]]
=== fallbackAuthorizationDecision

Preventive mechanisms can contain multiple *<fallbackAuthorizationDecision>* blocks. If an authorization decision fails due to unsuccessful <<execute-action,<executeAction>>> elements, the referenced fallback authorization decision is enforced. The default fallback is <<inhibit,<inhibit>>>. The structure of the <fallbackAuthorizationDecision> is identical to the <<authorization-decision,<authorizationDecision>>>.

The *<fallbackAuthorizationDecision>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The unique identifier of the fallback authorization action.
|fallback     |String    |-             |no       |This is a reference to the fallback authorization decision that is enforced if a mandatory <executeAction> within the <fallbackAuthorizationDecision> cannot be successfully executed.
|======================================================================================================================================

A *<fallbackAuthorizationDecision>* can have the following child elements:

* <<allow,<allow>>>
* <<inhibit,<inhibit>>>
* <<execute-action,<executeAction>>>

.Policy Specification Rules
[CAUTION]
===============================
* You must either add the <allow> or the <inhibit> element.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* The execute actions specified inside the <fallbackAuthorizationDecision> tag are executed if the fallback is called. Their return value is ignored. Only a negative return value from execute actions specified inside the <<allow,<allow>>> element leads to the enforcement of another fallback authorization decision.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy only shows names if the log was successful.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision' fallback='log2'>
      <allow>
    	   <executeAction name='urn:action:cs4:log'>
    	     <param:string name='message' value='Log message'/>
    	   </executeAction>
      </allow>
    </authorizationDecision>
    <fallbackAuthorizationDecision name='log2' fallback='abort'>
      <allow>
    	   <executeAction name='urn:action:cs4:log2'>
    	     <param:string name='message' value='Log message'/>
    	   </executeAction>
      </allow>
    </fallbackAuthorizationDecision>
    <fallbackAuthorizationDecision name='abort'>
      <inhibit/>
    </fallbackAuthorizationDecision>
  </preventiveMechanism>
</policy>
----


[[execute-action]]
=== executeAction

Execute Actions are compensating actions that security policies can trigger in the system. They are specified using the *<executeAction>* tag inside <<preventive-mechanism,<preventiveMechanism>>>, <<detective-mechanism,<detectiveMechanism>>>, <<authorization-decision,<authorizationDecision>>>, or <<allow,<allow>>> elements. Execute actions return a Boolean value indicating the execution success.

The *<executeAction>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The id of the action to be executed. The id syntax is urn:action:_scope_:_action_.
|======================================================================================================================================

A *<executeAction>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>
* <<param-object,<param:object>>>

.Policy Evaluation Rules
[IMPORTANT]
===============================
* The execution time of execute actions and their effect on the policy evaluation depends on their location inside the security policy:
** <executeAction> elements inside <<allow,<allow>>> are mandatory. They are executed when the surrounding (fallback) authorization decision is evaluated. The authorization decision is only sent to the PEP for enforcement if all execute actions inside the <<allow,<allow>>> tag are returning true indicating their successful execution. If one or more execute actions fail with return value false, the specified fallback authorization action is evaluated or, if none is specified, an <<inhibit,<inhibit>>> is sent to the PEP as the default fallback.
** <executeAction> elements inside <<authorization-decision,<authorizationDecision>>> are optional. They are executed when the authorization decision is evaluated, but their return value is ignored.
** <executeAction> elements inside <<fallback-authorization-decision,<fallbackAuthorizationDecision>>> are optional. They are executed when the authorization decision is evaluated, but their return value is ignored.
** <executeAction> elements inside <<preventive-mechanism,<preventiveMechanism>>> or <<detective-mechanism,<detectiveMechanism>>> are optional. They are executed after each positive condition evaluation, but their return value is ignored.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy writes different log messages.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
  	    <executeAction name='urn:action:cs4:log'>
  	      <param:string name='message' value='Mandatory execute action inside allow'/>
  	    </executeAction>
      </allow>
      <executeAction name='urn:action:cs4:log'>
  	    <param:string name='message' value='Optional execute action inside authorizationDecision'/>
  	  </executeAction>
    </authorizationDecision>
    <fallbackAuthorizationDecision name='abort'>
      <inhibit/>
      <executeAction name='urn:action:cs4:log'>
        <param:string name='message' value='Optional execute action in fallback authorizationDecision'/>
      </executeAction>
    </fallbackAuthorizationDecision>
    <executeAction name='urn:action:cs4:log'>
      <param:string name='message' value='Optional execute action outside authorizationDecision'/>
    </executeAction>
  </preventiveMechanism>
</policy>
----

[[parameters]]
== Parameters

[[param-string]]
=== param:string

The *<param:string>* tag is used for describing or referencing event parameters of type String. Each *<param:string>* element returns its value as a String.

The *<param:string>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The name of the parameter.
|value        |String    |-             |no       |The value of the parameter.
|expression   |String    |-             |no       |The JSONPath expression to be executed on the parameter value (the value assumed to be a complex object in JSON notation).
|======================================================================================================================================

A *<param:string>* can have the following child elements:

|======================================================================================================================================
|<<param-string,<param:string>>>|<<pip-string,<pip:string>>>|<<function-less,<function:less>>>
|<<param-boolean,<param:boolean>>>|<<pip-boolean,<pip:boolean>>>|<<function-less-equal,<function:lessEqual>>>
|<<param-int,<param:int>>>|<<pip-int,<pip:int>>>|<<function-greater,<function:greater>>>
|<<param-long,<param:long>>>|<<pip-long,<pip:long>>>|<<function-greater-equal,<function:greaterEqual>>>
|<<param-float,<param:float>>>|<<pip-float,<pip:float>>>|<<function-equals,<function:equals>>>
|<<param-double,<param:double>>>|<<pip-double,<pip:double>>>|<<function-exists,<function:exists>>>
|<<param-object,<param:object>>>|<<pip-object,<pip:object>>>|<<function-regex,<function:regex>>>
|<<param-list,<param:list>>>|<<pip-list,<pip:list>>>|<<function-contains,<function:contains>>>
|||<<function-size,<function:size>>>
|||<<function-concat,<function:concat>>>
|======================================================================================================================================

.Policy Specification Rules
[CAUTION]
===============================
* The *<param:string>* tag can be specified in three different modes:
** The *<param:string>* tag has a value attribute specified and no child elements: The specified value in the value attribute is used.
** The *<param:string>* tag has no value attribute specified and one child element: The return value of the child element is used.
** The *<param:string>* tag has no value attribute specified and no child element: This is a reference to the event parameter with the specified name. The value of the current event parameter is used.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the attribute *expression* is used, the PDP tries to execute the JSONPath expression on the value (which is assumed to be a complex object in JSON notation). The PDP expects the result of the executed expression to be of type String. It is not possible to determine the return value type during the specification.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the different parameter modes.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:string name='role' value='employees'/>
    </event>
    <condition>
      <and>
        <function:equals>
          <param:string name='lastName'/>
          <constant:string value='Smith'/>
        </function:equals>
        <function:equals>
          <param:string name='user' expression='$.addresses[1].type'/>
          <constant:string value='WORK'/>
        </function:equals>
      </and>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='anonmyizationMethod' value='replace'/>
              <param:string name='replacementCharacter'>
                <pip:string method='getCurrentReplacementCharacter'/>
              </param:string>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[param-boolean]]
=== param:boolean

The *<param:boolean>* tag is used for describing or referencing event parameters of type Boolean. Each *<param:boolean>* element returns its value as a Boolean flag.

The *<param:boolean>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The name of the parameter.
|value        |Boolean   |-             |no       |The value of the parameter.
|expression   |String    |-             |no       |The JSONPath expression to be executed on the parameter value, if the value is a complex object.
|======================================================================================================================================

A *<param:boolean>* can have the following child elements:

* <<param-boolean,<param:boolean>>>
* <<pip-boolean,<pip:boolean>>>
* <<function-less,<function:less>>>
* <<function-less-equal,<function:lessEqual>>>
* <<function-greater,<function:greater>>>
* <<function-greater-equal,<function:greaterEqual>>>
* <<function-equals,<function:equals>>>
* <<function-exists,<function:exists>>>
* <<function-regex,<function:regex>>>
* <<function-contains,<function:contains>>>

.Policy Specification Rules
[CAUTION]
===============================
* The *<param:boolean>* tag can be specified in three different modes:
** The *<param:boolean>* tag has a value attribute specified and no child elements: The specified value in the value attribute is used.
** The *<param:boolean>* tag has no value attribute specified and one child element: The return value of the child element is used.
** The *<param:boolean>* tag has no value attribute specified and no child element: This is a reference to the event parameter with the specified name. The value of the current event parameter is used.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the attribute *expression* is used, the PDP tries to execute the JSONPath expression on the value (which is assumed to be a complex object in JSON notation). The PDP expects the result of the executed expression to be of type Boolean. It is not possible to determine the return value type during the specification.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the different parameter modes'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:boolean name='retired' value='false'/>
    </event>
    <condition>
      <param:boolean name='employeeOfTheMonth'/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='anonmyizationMethod' value='replace'/>
              <param:boolean name='fullAnonymization'>
                <pip:boolean method='isFullAnonymizationNecessary' default='true'/>
              </param:boolean>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[param-int]]
=== param:int

The *<param:int>* tag is used for describing or referencing event parameters of type Integer. Each *<param:int>* element returns its value as an Integer.

The *<param:int>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The name of the parameter.
|value        |Integer   |-             |no       |The value of the parameter.
|expression   |String    |-             |no       |The JSONPath expression to be executed on the parameter value, if the value is a complex object.
|======================================================================================================================================

A *<param:int>* can have the following child elements:

* <<param-int,<param:int>>>
* <<pip-int,<pip:int>>>
* <<function-size,<function:size>>>

.Policy Specification Rules
[CAUTION]
===============================
* The *<param:int>* tag can be specified in three different modes:
** The *<param:int>* tag has a value attribute specified and no child elements: The specified value in the value attribute is used.
** The *<param:int>* tag has no value attribute specified and one child element: The return value of the child element is used.
** The *<param:int>* tag has no value attribute specified and no child element: This is a reference to the event parameter with the specified name. The value of the current event parameter is used.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the attribute *expression* is used, the PDP tries to execute the JSONPath expression on the value (which is assumed to be a complex object in JSON notation). The PDP expects the result of the executed expression to be of type Integer. It is not possible to determine the return value type during the specification.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the different parameter modes.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:int name='department' value='30'/>
    </event>
    <condition>
      <function:greater>
        <param:int name='age'/>
        <constant:int value='30'/>
      </function:greater>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='anonmyizationMethod' value='replace'/>
              <param:int name='replaceEachXCharacter'>
                <pip:int method='getReplacementDensity' default='2'/>
              </param:int>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[param-long]]
=== param:long

The *<param:long>* tag is used for describing or referencing event parameters of type Long. Each *<param:long>* element returns its value as a Long.

The *<param:long>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The name of the parameter.
|value        |Long      |-             |no       |The value of the parameter.
|expression   |String    |-             |no       |The JSONPath expression to be executed on the parameter value, if the value is a complex object.
|======================================================================================================================================

A *<param:long>* can have the following child elements:

* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<pip-int,<pip:int>>>
* <<pip-long,<pip:long>>>
* <<function-size,<function:size>>>

.Policy Specification Rules
[CAUTION]
===============================
* The *<param:long>* tag can be specified in three different modes:
** The *<param:long>* tag has a value attribute specified and no child elements: The specified value in the value attribute is used.
** The *<param:long>* tag has no value attribute specified and one child element: The return value of the child element is used.
** The *<param:long>* tag has no value attribute specified and no child element: This is a reference to the event parameter with the specified name. The value of the current event parameter is used.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the attribute *expression* is used, the PDP tries to execute the JSONPath expression on the value (which is assumed to be a complex object in JSON notation). The PDP expects the result of the executed expression to be of type Long. It is not possible to determine the return value type during the specification.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the different parameter modes.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:long name='department' value='30'/>
    </event>
    <condition>
      <function:greater>
        <param:long name='age'/>
        <constant:long value='30'/>
      </function:greater>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='anonmyizationMethod' value='replace'/>
              <param:long name='replaceEachXCharacter'>
                <pip:long method='getReplacementDensity' default='2'/>
              </param:long>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[param-float]]
=== param:float

The *<param:float>* tag is used for describing or referencing event parameters of type Float. Each *<param:float>* element returns its value as a Float.

The *<param:float>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The name of the parameter.
|value        |Float     |-             |no       |The value of the parameter.
|expression   |String    |-             |no       |The JSONPath expression to be executed on the parameter value, if the value is a complex object.
|======================================================================================================================================

A *<param:float>* can have the following child elements:

* <<param-int,<param:int>>>
* <<param-float,<param:float>>>
* <<pip-int,<pip:int>>>
* <<pip-float,<pip:float>>>
* <<function-size,<function:size>>>

.Policy Specification Rules
[CAUTION]
===============================
* The *<param:float>* tag can be specified in three different modes:
** The *<param:float>* tag has a value attribute specified and no child elements: The specified value in the value attribute is used.
** The *<param:float>* tag has no value attribute specified and one child element: The return value of the child element is used.
** The *<param:float>* tag has no value attribute specified and no child element: This is a reference to the event parameter with the specified name. The value of the current event parameter is used.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the attribute *expression* is used, the PDP tries to execute the JSONPath expression on the value (which is assumed to be a complex object in JSON notation). The PDP expects the result of the executed expression to be of type Float. It is not possible to determine the return value type during the specification.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the different parameter modes.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:float name='bodyHeight' value='6.4'/>
    </event>
    <condition>
      <function:greater>
        <param:float name='experienceInYears'/>
        <constant:float value='4.5'/>
      </function:greater>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='anonmyizationMethod' value='replace'/>
              <param:float name='anonymizationQuota'>
                <pip:float method='getAnonymizationQuota' default='0.8'/>
              </param:float>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[param-double]]
=== param:double

The *<param:double>* tag is used for describing or referencing event parameters of type Double. Each *<param:double>* element returns its value as a Double.

The *<param:double>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The name of the parameter.
|value        |String    |-             |no       |The value of the parameter.
|expression   |String    |-             |no       |The JSONPath expression to be executed on the parameter value, if the value is a complex object.
|======================================================================================================================================

A *<param:double>* can have the following child elements:

* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>
* <<pip-int,<pip:int>>>
* <<pip-long,<pip:long>>>
* <<pip-float,<pip:float>>>
* <<pip-double,<pip:double>>>
* <<function-size,<function:size>>>

.Policy Specification Rules
[CAUTION]
===============================
* The *<param:double>* tag can be specified in three different modes:
** The *<param:double>* tag has a value attribute specified and no child elements: The specified value in the value attribute is used.
** The *<param:double>* tag has no value attribute specified and one child element: The return value of the child element is used.
** The *<param:double>* tag has no value attribute specified and no child element: This is a reference to the event parameter with the specified name. The value of the current event parameter is used.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the attribute *expression* is used, the PDP tries to execute the JSONPath expression on the value (which is assumed to be a complex object in JSON notation). The PDP expects the result of the executed expression to be of type Double. It is not possible to determine the return value type during the specification.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the different parameter modes.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:double name='bodyHeight' value='6.4'/>
    </event>
    <condition>
      <function:greater>
        <param:double name='experienceInYears'/>
        <constant:double value='4.5'/>
      </function:greater>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='anonmyizationMethod' value='replace'/>
              <param:double name='anonymizationQuota'>
                <pip:double method='getAnonymizationQuota' default='0.8'/>
              </param:double>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[param-object]]
=== param:object

The *<param:object>* tag is used for describing or referencing complex object parameters.

The *<param:object>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The name of the parameter.
|value        |String    |-             |no       |The value of the parameter encoded as JSON string.
|expression   |String    |-             |no       |The JSONPath expression to be executed on the parameter value, if the value is a complex object.
|======================================================================================================================================

A *<param:object>* can have the following child elements:

* <<param-object,<param:object>>>
* <<pip-object,<pip:object>>>

.Policy Specification Rules
[CAUTION]
===============================
* The *<param:object>* tag can be specified in three different modes:
** The *<param:object>* tag has a value attribute specified and no child elements: The specified value in the value attribute is used.
** The *<param:object>* tag has no value attribute specified and one child element: The return value of the child element is used.
** The *<param:object>* tag has no value attribute specified and no child element: This is a reference to the event parameter with the specified name. The value of the current event parameter is used.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the attribute *expression* is used, the PDP tries to execute the JSONPath expression on the value (which is assumed to be a complex object in JSON notation). The PDP expects the result of the executed expression is a complex object in JSON notation. It is not possible to determine the return value type during the specification.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the use of the <param:object> element.'>
  <preventiveMechanism>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:equals>
        <param:object name='user' expression='$.addresses[1]'/>
        <constant:object value='{"street":{"streetName":"Fraunhofer-Platz","number":1},"city":"Kaiserslautern","zip":"67663","type":"WORK"}'/>
      </function:equals>
    </condition>
    <authorizationDecision>
      <allow>
        <modify>
          <param:event name='user' expression='$.addresses[:2].city'>
            <function:engine method='replace'>
              <param:string name='replacement' value='XXXXX'/>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[param-list]]
=== param:list

The *<param:list>* tag is used for describing or referencing event parameters of type List. Each *<param:list>* element returns its value as a List.

The *<param:list>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The name of the parameter.
|value        |List      |-             |no       |The value of the parameter.
|expression   |String    |-             |no       |The JSONPath expression to be executed on the parameter value, if the value is a complex object.
|======================================================================================================================================

A *<param:list>* can have the following child elements:

* <<param-list,<param:list>>>
* <<pip-list,<pip:list>>>

.Policy Specification Rules
[CAUTION]
===============================
* The *<param:list>* tag can be specified in three different modes:
** The *<param:list>* tag has a value attribute specified and no child elements: The specified value in the value attribute is used.
** The *<param:list>* tag has no value attribute specified and one child element: The return value of the child element is used.
** The *<param:list>* tag has no value attribute specified and no child element: This is a reference to the event parameter with the specified name. The value of the current event parameter is used.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the attribute *expression* is used, the PDP tries to execute the JSONPath expression on the value (which is assumed to be a complex object in JSON notation). The PDP expects the result of the executed expression to be of type List. It is not possible to determine the return value type during the specification.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the different parameter modes.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:double name='bodyHeight' value='6.4'/>
    </event>
    <condition>´
      <and>
        <function:greater>
          <param:double name='experienceInYears'/>
          <constant:double value='4.5'/>
        </function:greater>
        <function:greaterEqual>
          <function:size>
            <param:list name='user' expression='$.addresses'/>
          </function:size>
          <constant:int value='2'/>
        </function:greaterEqual>
        <function:contains>
          <param:list name='user' expression='$.addresses'/>
          <constant:object value='{"street":{"streetName":"Fraunhofer-Platz","number":1},"city":"Kaiserslautern","zip":"67663","type":"WORK"}'/>
        </function:contains>
      </and>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='anonmyizationMethod' value='replace'/>
              <param:double name='anonymizationQuota'>
                <pip:double method='getAnonymizationQuota' default='0.8'/>
              </param:double>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[param-event]]
=== param:event

The *<param:event>* tag is used to declare event parameters that must be modified inside the <<modify,<modify>>> element.

The *<param:event>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|name         |String    |-             |yes      |The name of the event parameter to be modified.
|expression   |String    |-             |no       |The JSONPath expression to be executed on the selected event parameter, if the event parameter is a complex object.
|======================================================================================================================================

A *<param:event>* can have the following child elements:

* <<function-engine,<function:engine>>>

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the param:event element usage.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='person' expression='$.lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='anonmyizationMethod' value='replace'/>
              <param:string name='replacementCharacter'>
                <pip:string method='getCurrentReplacementCharacter' default='X'/>
              </param:string>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[operators]]
== Operators

[[and]]
=== and

The *<and>* tag is used in the condition to aggregate Boolean expressions with the logical AND operator.

A *<and>* can have the following child elements:

|======================================================================================================================================
|<<true,<true>>>|<<param-boolean,<param:boolean>>>|<<function-less,<function:less>>>
|<<false,<false>>>|<<pip-boolean,<pip:boolean>>>|<<function-less-equal,<function:lessEqual>>>
|<<not,<not>>>||<<function-greater,<function:greater>>>
|<<and,<and>>>||<<function-greater-equal,<function:greaterEqual>>>
|<<or,<or>>>||<<function-equals,<function:equals>>>
|<<implies,<implies>>>||<<function-exists,<function:exists>>>
|||<<function-regex,<function:regex>>>
|||<<function-contains,<function:contains>>>|
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees that are older than 30, in the role of a team leader, and senior engineers.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
       <and>
         <function:greater>
           <param:int name='age'/>
           <constant:int value='30'/>
         </function:greater>
         <function:equals>
           <param:string name='role'/>
           <constant:string value='TEAMLEADER'/>
         </function:equals>
         <pip:boolean method='urn:pip:isSeniorEngineer' default='false'/>
       </and>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[or]]
=== or

The *<or>* tag is used in the condition to aggregate Boolean expressions with the logical OR operator.

A *<or>* can have the following child elements:

|======================================================================================================================================
|<<true,<true>>>|<<param-boolean,<param:boolean>>>|<<function-less,<function:less>>>
|<<false,<false>>>|<<pip-boolean,<pip:boolean>>>|<<function-less-equal,<function:lessEqual>>>
|<<not,<not>>>||<<function-greater,<function:greater>>>
|<<and,<and>>>||<<function-greater-equal,<function:greaterEqual>>>
|<<or,<or>>>||<<function-equals,<function:equals>>>
|<<implies,<implies>>>||<<function-exists,<function:exists>>>
|||<<function-regex,<function:regex>>>
|||<<function-contains,<function:contains>>>|
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees that are older than 30, in the role of a team leader, or senior engineers.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
       <or>
         <function:greater>
           <param:int name='age'/>
           <constant:int value='30'/>
         </function:greater>
         <function:equals>
           <param:string name='role'/>
           <constant:string value='TEAMLEADER'/>
         </function:equals>
         <pip:boolean method='urn:pip:isSeniorEngineer' default='false'/>
       </or>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[not]]
=== not

The *<not>* tag is used in the condition to negate a Boolean expression. The element implements a logical NOT operator.

A *<not>* can have the following child elements:

|======================================================================================================================================
|<<true,<true>>>|<<param-boolean,<param:boolean>>>|<<function-less,<function:less>>>
|<<false,<false>>>|<<pip-boolean,<pip:boolean>>>|<<function-less-equal,<function:lessEqual>>>
|<<not,<not>>>||<<function-greater,<function:greater>>>
|<<and,<and>>>||<<function-greater-equal,<function:greaterEqual>>>
|<<or,<or>>>||<<function-equals,<function:equals>>>
|<<implies,<implies>>>||<<function-exists,<function:exists>>>
|||<<function-regex,<function:regex>>>
|||<<function-contains,<function:contains>>>|
|======================================================================================================================================

.Policy Specification Rules
[CAUTION]
===============================
* The *<not>* element must have exactly one child element.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees that not in the role of a team leader.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:equals>
          <param:string name='role'/>
          <constant:string value='TEAMLEADER'/>
        </function:equals>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[implies]]
=== implies

The *<implies>* tag is used in the condition to specify a logical IMPLIES operator.

A *<implies>* can have the following child elements:

|======================================================================================================================================
|<<true,<true>>>|<<param-boolean,<param:boolean>>>|<<function-less,<function:less>>>
|<<false,<false>>>|<<pip-boolean,<pip:boolean>>>|<<function-less-equal,<function:lessEqual>>>
|<<not,<not>>>||<<function-greater,<function:greater>>>
|<<and,<and>>>||<<function-greater-equal,<function:greaterEqual>>>
|<<or,<or>>>||<<function-equals,<function:equals>>>
|<<implies,<implies>>>||<<function-exists,<function:exists>>>
|||<<function-regex,<function:regex>>>
|||<<function-contains,<function:contains>>>|
|======================================================================================================================================

.Policy Specification Rules
[CAUTION]
===============================
* The *<implies>* element must have exactly two child elements.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees that not in the role of a team leader.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <implies>
        <pip:boolean method='urn:pip:isSeniorEngineer' default='false'/>
        <function:equals>
          <param:string name='role'/>
          <constant:string value='TEAMLEADER'/>
        </function:equals>
      </implies>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[functions]]
== Functions

[[function-less]]
=== function:less

The *<function:less>* tag implements the less-than comparison operator (<).

A *<function:less>* can have the following child elements:

|======================================================================================================================================
|<<param-int,<param:int>>>|<<pip-int,<pip:int>>>|<<function-size,<function:size>>>|<<constant-int,<constant:int>>>
|<<param-long,<param:long>>>|<<pip-long,<pip:long>>>||<<constant-long,<constant:long>>>
|<<param-float,<param:float>>>|<<pip-float,<pip:float>>>||<<constant-float,<constant:float>>>
|<<param-double,<param:double>>>|<<pip-double,<pip:double>>>||<<constant-double,<constant:double>>>
|======================================================================================================================================

.Policy Specification Rules
[CAUTION]
===============================
* For the child elements values A, B, and C specified in this order, the *<function:less>* element evaluates A < B < C.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees that with the age between 21 and 29.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:less>
        <constant:int value='20'/>
        <param:int name='age'/>
        <constant:int value='30'/>
      </function:less>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-less-equal]]
=== function:lessEqual

The *<function:lessEqual>* tag is implemented as a less-or-equal comparison operator (\<=).

A *<function:lessEqual>* can have the following child elements:

|======================================================================================================================================
|<<param-int,<param:int>>>|<<pip-int,<pip:int>>>|<<function-size,<function:size>>>|<<constant-int,<constant:int>>>
|<<param-long,<param:long>>>|<<pip-long,<pip:long>>>||<<constant-long,<constant:long>>>
|<<param-float,<param:float>>>|<<pip-float,<pip:float>>>||<<constant-float,<constant:float>>>
|<<param-double,<param:double>>>|<<pip-double,<pip:double>>>||<<constant-double,<constant:double>>>
|======================================================================================================================================

.Policy Specification Rules
[CAUTION]
===============================
* For the child elements values A, B, and C specified in this order, the *<function:lessEqual>* element evaluates A \<= B \<= C.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees that with the age between 20 and 30.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:lessEqual>
        <constant:int value='20'/>
        <param:int name='age'/>
        <constant:int value='30'/>
      </function:lessEqual>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-greater]]
=== function:greater

The *<function:greater>* tag implements the greater-than comparison operator (>).

A *<function:greater>* can have the following child elements:

|======================================================================================================================================
|<<param-int,<param:int>>>|<<pip-int,<pip:int>>>|<<function-size,<function:size>>>|<<constant-int,<constant:int>>>
|<<param-long,<param:long>>>|<<pip-long,<pip:long>>>||<<constant-long,<constant:long>>>
|<<param-float,<param:float>>>|<<pip-float,<pip:float>>>||<<constant-float,<constant:float>>>
|<<param-double,<param:double>>>|<<pip-double,<pip:double>>>||<<constant-double,<constant:double>>>
|======================================================================================================================================

.Policy Specification Rules
[CAUTION]
===============================
* For the child elements values A, B, and C specified in this order, the *<function:greater>* element evaluates A > B > C.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees that with the age between 21 and 29.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:greater>
        <constant:int value='30'/>
        <param:int name='age'/>
        <constant:int value='20'/>
      </function:greater>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-greater-equal]]
=== function:greaterEqual

The *<function:greaterEqual>* tag implements the greater-or-equal comparison operator (>=).

A *<function:greaterEqual>* can have the following child elements:

|======================================================================================================================================
|<<param-int,<param:int>>>|<<pip-int,<pip:int>>>|<<function-size,<function:size>>>|<<constant-int,<constant:int>>>
|<<param-long,<param:long>>>|<<pip-long,<pip:long>>>||<<constant-long,<constant:long>>>
|<<param-float,<param:float>>>|<<pip-float,<pip:float>>>||<<constant-float,<constant:float>>>
|<<param-double,<param:double>>>|<<pip-double,<pip:double>>>||<<constant-double,<constant:double>>>
|======================================================================================================================================

.Policy Specification Rules
[CAUTION]
===============================
* For the child elements values A, B, and C specified in this order, the *<function:greaterEqual>* element evaluates A >= B >= C.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees that with the age between 20 and 30.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:greaterEqual>
        <constant:int value='30'/>
        <param:int name='age'/>
        <constant:int value='20'/>
      </function:greaterEqual>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-equals]]
=== function:equals

The *<function:equals>* tag implements the equal comparison operator (==).

A *<function:equals>* can have the following child elements:

|======================================================================================================================================
|<<param-string,<param:string>>>|<<pip-string,<pip:string>>>|<<function-less,<function:less>>>|<<constant-string,<constant:string>>>
|<<param-boolean,<param:boolean>>>|<<pip-boolean,<pip:boolean>>>|<<function-less-equal,<function:lessEqual>>>|<<constant-int,<constant:int>>>
|<<param-int,<param:int>>>|<<pip-int,<pip:int>>>|<<function-greater,<function:greater>>>|<<constant-long,<constant:long>>>
|<<param-long,<param:long>>>|<<pip-long,<pip:long>>>|<<function-greater-equal,<function:greaterEqual>>>|<<constant-float,<constant:float>>>
|<<param-float,<param:float>>>|<<pip-float,<pip:float>>>|<<function-equals,<function:equals>>>|<<constant-double,<constant:double>>>
|<<param-double,<param:double>>>|<<pip-double,<pip:double>>>|<<function-exists,<function:exists>>>|<<constant-object,<constant:object>>>
|<<param-object,<param:object>>>|<<pip-object,<pip:object>>>|<<function-regex,<function:regex>>>|<<constant-list,<constant:list>>>
|<<param-list,<param:list>>>|<<pip-list,<pip:list>>>|<<function-contains,<function:contains>>>|
|||<<function-size,<function:size>>>|
|||<<function-concat,<function:concat>>>|
|======================================================================================================================================

.Policy Specification Rules
[CAUTION]
===============================
* For the child elements values A, B, and C specified in this order, the *<function:equals>* element evaluates A == B == C.
* The return value of each child element is converted to a string before comparison.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:equals>
        <constant:long value='30'/>
        <param:int name='age'/>
        <constant:int value='30'/>
      </function:equals>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-exists]]
=== function:exists

The *<function:exists>* elements evaluates whether the event contains a specified parameter. The values of the child elements declare the expected parameters (identified by their name attributes).

The *<function:exists>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|mode         |enum      |ALL           |no       |The mode declares how many child element must match. Possible modes are ALL, EXACTLY_ONE, AT_LEAST_ONE, NONE.
|======================================================================================================================================

A *<function:exists>* can have the following child elements:

* <<param-string,<param:string>>>
* <<pip-string,<pip:string>>>
* <<function-concat,<function:concat>>>
* <<constant-string,<constant:string>>>

.Policy Evaluation Rules
[IMPORTANT]
===============================
* The *<function:exists>* element has four evaluation modes:
** ALL: All declared parameters must be present in the event.
** EXACTLY_ONE: Exactly one of the declared parameters must be present in the event; the others must not be present.
** AT_LEAST_ONE: At least one of the declared parameters must be present in the event.
** NONE: None of the declared parameters must be present in the event.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data from employees if the parameters age or body height are missing.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:exists mode='ALL'>
          <constant:string value='age'/>
          <constant:string value='bodyHeight'/>
        </function:exists>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-regex]]
=== function:regex

The *<function:regex>* elements evaluates whether the values of the child elements match a given regular expression.

The *<function:regex>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|regex        |String    |-             |yes      |The String defines the regex that is applied for matching the values of child elements.
|mode         |enum      |ALL           |no       |The mode declares how many child element must match. Possible modes are ALL, EXACTLY_ONE, AT_LEAST_ONE, NONE.
|======================================================================================================================================

A *<function:regex>* can have the following child elements:

* <<param-string,<param:string>>>
* <<pip-string,<pip:string>>>
* <<function-concat,<function:concat>>>
* <<constant-string,<constant:string>>>

.Policy Evaluation Rules
[IMPORTANT]
===============================
* The *<function:regex>* 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:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if email addresses are syntactically invalid.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:regex regex='^[_A-Za-z0-9-\\+]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9]+)*(\\.[A-Za-z]{2,})$'>
          <param:string name='email'/>
        </function:regex>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-contains]]
=== function:contains

The *<function:contains>* elements evaluates whether the declared values are contained in a list that is provided by a PIP.

The *<function:contains>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|mode         |enum      |ALL           |no       |The mode declares how many values must match. Possible modes are ALL, EXACTLY_ONE, AT_LEAST_ONE, NONE.
|======================================================================================================================================

A *<function:contains>* can have the following child elements:

|======================================================================================================================================
|<<param-string,<param:string>>>|<<pip-string,<pip:string>>>|<<function-less,<function:less>>>|<<constant-string,<constant:string>>>
|<<param-boolean,<param:boolean>>>|<<pip-boolean,<pip:boolean>>>|<<function-less-equal,<function:lessEqual>>>|<<constant-int,<constant:int>>>
|<<param-int,<param:int>>>|<<pip-int,<pip:int>>>|<<function-greater,<function:greater>>>|<<constant-long,<constant:long>>>
|<<param-long,<param:long>>>|<<pip-long,<pip:long>>>|<<function-greater-equal,<function:greaterEqual>>>|<<constant-float,<constant:float>>>
|<<param-float,<param:float>>>|<<pip-float,<pip:float>>>|<<function-equals,<function:equals>>>|<<constant-double,<constant:double>>>
|<<param-double,<param:double>>>|<<pip-double,<pip:double>>>|<<function-exists,<function:exists>>>|<<constant-object,<constant:object>>>
|<<param-object,<param:object>>>|<<pip-object,<pip:object>>>|<<function-regex,<function:regex>>>|<<constant-list,<constant:list>>>
|<<param-list,<param:list>>>|<<pip-list,<pip:list>>>|<<function-contains,<function:contains>>>|
|||<<function-size,<function:size>>>|
|||<<function-concat,<function:concat>>>|
|======================================================================================================================================

.Policy Specification Rules
[IMPORTANT]
===============================
* The *<function:contains>* element must have at least two child elements.
* The first child element of *<function:contains>* must be a <<pip-list,<pip:list>>> element.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* The *<function:contains>* element has four evaluation modes:
** ALL: List must contain all of the child element values.
** EXACTLY_ONE: List must contain exactly one of the child element values, but not more than one.
** AT_LEAST_ONE: List must at least contain one of the child element values.
** NONE: List must not contain any of the child element values.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if employee id is not on the list of priviledged employees.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:contains>
          <pip:list method='getAllPriviledgedEmployees' default='[]'/>
          <param:int name='employeeId'/>
        </function:contains>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-size]]
=== function:size

The *<function:size>* counts the number of elements in a list or the number of characters in a string.

A *<function:size>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-list,<param:list>>>
* <<pip-string,<pip:string>>>
* <<pip-list,<pip:list>>>
* <<function-concat,<function:concat>>>

.Policy Specification Rules
[IMPORTANT]
===============================
* The *<function:size>* element must have exactly one child element.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if less than 5 employees exist.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:less>
          <function:size>
            <pip:list method='getAllPriviledgedEmployees' default='[]'/>
          </function:size>
          <constant:int value='5'/>
        </function:less>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-concat]]
=== function:concat

The *<function:concat>* elements concatenates all values of child elements to a string.

A *<function:concat>* can have the following child elements:

|======================================================================================================================================
|<<param-string,<param:string>>>|<<pip-string,<pip:string>>>|<<function-less,<function:less>>>|<<constant-string,<constant:string>>>
|<<param-boolean,<param:boolean>>>|<<pip-boolean,<pip:boolean>>>|<<function-less-equal,<function:lessEqual>>>|<<constant-int,<constant:int>>>
|<<param-int,<param:int>>>|<<pip-int,<pip:int>>>|<<function-greater,<function:greater>>>|<<constant-long,<constant:long>>>
|<<param-long,<param:long>>>|<<pip-long,<pip:long>>>|<<function-greater-equal,<function:greaterEqual>>>|<<constant-float,<constant:float>>>
|<<param-float,<param:float>>>|<<pip-float,<pip:float>>>|<<function-equals,<function:equals>>>|<<constant-double,<constant:double>>>
|<<param-double,<param:double>>>|<<pip-double,<pip:double>>>|<<function-exists,<function:exists>>>|<<constant-object,<constant:object>>>
|<<param-object,<param:object>>>|<<pip-object,<pip:object>>>|<<function-regex,<function:regex>>>|<<constant-list,<constant:list>>>
|<<param-list,<param:list>>>|<<pip-list,<pip:list>>>|<<function-contains,<function:contains>>>|
|||<<function-size,<function:size>>>|
|||<<function-concat,<function:concat>>>|
|======================================================================================================================================

.Policy Specification Rules
[IMPORTANT]
===============================
* The *<function:concat>* element must have at least one child element.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if complete employee name is not on the list of priviledged employees.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:contains>
          <pip:list method='getAllPriviledgedEmployees' default='[]'/>
          <function:concat>
            <param:string name='firstName'/>
            <constant:string value=' '/>
            <param:string name='lastName'/>
          </function:concat>
        </function:contains>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[function-engine]]
=== function:engine

The *<function:engine>* tag is used to declare the modifier method that has to be executed on the event parameter declared in the parent element <<param-event,<param:event>>>.

The *<param:event>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|method       |String    |-             |yes      |The name of the modifier method to be executed.
|======================================================================================================================================

A *<param:event>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the param:event element usage.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <true/>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <allow>
        <modify>
          <param:event name='lastName'>
            <function:engine method='anonymizeName'>
              <param:string name='anonmyizationMethod' value='replace'/>
              <param:string name='replacementCharacter'>
                <pip:string method='getCurrentReplacementCharacter' default='X'/>
              </param:string>
            </function:engine>
          </param:event>
        </modify>
      </allow>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[pip-requests]]
== PIP Requests

[[pip-string]]
=== pip:string

The *<pip:string>* element is used to request information from a PIP. The *<pip:string>* element returns a String value. The parameters that can be added as child elements are sent to the PIP as request parameters.

The *<pip:string>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|method       |String    |-             |yes      |The name of a PIP method.
|default      |String    |-             |yes      |The value that is returned if the PIP is not reachable.
|ttlAmount    |Integer   |0             |no       |The "time to live" value sets the time interval that the response value of the PIP is cached.
|ttlUnit      |enum      |SECONDS       |no       |Time unit of "time to live". Possible units are TIMESTEPS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

A *<pip:string>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>

.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the <pip:string> element 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:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if requesting entity is not in the role of a team leader.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:equals>
          <pip:string method='getRole' default='EMPLOYEE' ttlAmount='10' ttlUnit='MINUTES'>
            <param:string name='employeeId'/>
          </pip:string>
          <constant:string value='TEAMLEADER'/>
        </function:equals>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[pip-boolean]]
=== pip:boolean

The *<pip:boolean>* element is used to request information from a PIP. The *<pip:boolean>* element returns a Boolean value. The parameters that can be added as child elements are sent to the PIP as request parameters.

The *<pip:boolean>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|method       |String    |-             |yes      |The name of a PIP method.
|default      |Boolean   |-             |yes      |The value that is returned if the PIP is not reachable.
|ttlAmount    |Integer   |0             |no       |The "time to live" value sets the time interval that the response value of the PIP is cached.
|ttlUnit      |enum      |SECONDS       |no       |Time unit of "time to live". Possible units are TIMESTEPS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

A *<pip:boolean>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>

.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the <pip:boolean> element 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:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if requests are currently now allowed.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <pip:boolean method='accessIsCurrentlyAllowed' default='false' ttlAmount='30' ttlUnit='SECONDS'/>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[pip-int]]
=== pip:int

The *<pip:int>* element is used to request information from a PIP. The *<pip:int>* element returns an Integer value. The parameters that can be added as child elements are sent to the PIP as request parameters.

The *<pip:int>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|method       |String    |-             |yes      |The name of a PIP method.
|default      |Integer   |-             |yes      |The value that is returned if the PIP is not reachable.
|ttlAmount    |Integer   |0             |no       |The "time to live" value sets the time interval that the response value of the PIP is cached.
|ttlUnit      |enum      |SECONDS       |no       |Time unit of "time to live". Possible units are TIMESTEPS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

A *<pip:int>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>

.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the <pip:int> element 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:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if less than 5 employees exist.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:less>
          <pip:int method='getNumberOfEmployees' default='0'/>
          <constant:int value='5'/>
        </function:less>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[pip-long]]
=== pip:long

The *<pip:long>* element is used to request information from a PIP. The *<pip:long>* element returns a Long value. The parameters that can be added as child elements are sent to the PIP as request parameters.

The *<pip:long>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|method       |String    |-             |yes      |The name of a PIP method.
|default      |Long      |-             |yes      |The value that is returned if the PIP is not reachable.
|ttlAmount    |Integer   |0             |no       |The "time to live" value sets the time interval that the response value of the PIP is cached.
|ttlUnit      |enum      |SECONDS       |no       |Time unit of "time to live". Possible units are TIMESTEPS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

A *<pip:long>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>

.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the <pip:long> element 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:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if less than 5 employees exist.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:less>
          <pip:double method='getNumberOfEmployees' default='0' ttl='300'/>
          <constant:double value='5'/>
        </function:less>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[pip-float]]
=== pip:float

The *<pip:float>* element is used to request information from a PIP. The *<pip:float>* element returns a Float value. The parameters that can be added as child elements are sent to the PIP as request parameters.

The *<pip:float>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|method       |String    |-             |yes      |The name of a PIP method.
|default      |Float     |-             |yes      |The value that is returned if the PIP is not reachable.
|ttlAmount    |Integer   |0             |no       |The "time to live" value sets the time interval that the response value of the PIP is cached.
|ttlUnit      |enum      |SECONDS       |no       |Time unit of "time to live". Possible units are TIMESTEPS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

A *<pip:float>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>

.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the <pip:float> element 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:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if employee is smaller than 5 feet.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:less>
        <pip:float method='getBodyHeight' default='0'>
          <param:float name='bodyHeight'/>
        </pip:float>
        <constant:float value='5.0'/>
      </function:less>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[pip-double]]
=== pip:double

The *<pip:double>* element is used to request information from a PIP. The *<pip:double>* element returns a Double value. The parameters that can be added as child elements are sent to the PIP as request parameters.

The *<pip:double>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|method       |String    |-             |yes      |The name of a PIP method.
|default      |Double    |-             |yes      |The value that is returned if the PIP is not reachable.
|ttlAmount    |Integer   |0             |no       |The "time to live" value sets the time interval that the response value of the PIP is cached.
|ttlUnit      |enum      |SECONDS       |no       |Time unit of "time to live". Possible units are TIMESTEPS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

A *<pip:double>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>

.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the <pip:double> element 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:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if employee is smaller than 5 feet.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:less>
        <pip:double method='getBodyHeight' default='0'>
          <param:double name='bodyHeight'/>
        </pip:double>
        <constant:float value='5.0'/>
      </function:less>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[pip-object]]
=== pip:object

The *<pip:object>* element is used to request information from a PIP. The *<pip:object>* element returns an complex object. The parameters that can be added as child elements are sent to the PIP as request parameters.

The *<pip:double>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|method       |String    |-             |yes      |The name of a PIP method.
|default      |String    |-             |yes      |The value that is returned if the PIP is not reachable in JSON notation.
|ttlAmount    |Integer   |0             |no       |The "time to live" value sets the time interval that the response value of the PIP is cached.
|ttlUnit      |enum      |SECONDS       |no       |Time unit of "time to live". Possible units are TIMESTEPS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

A *<pip:double>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>

.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the <pip:double> element only returns the cached value. Once in the beginning each defined time interval, the cache is refreshed by the current value retrieved by the PIP.
* If the "time to live" caching time interval is not set, then the PIP is requested on each PIP element evaluation.
===============================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if address does not match.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:equals>
        <pip:object method='getAddress' default='{}'>
          <param:string name='user'>
            <param:string name='userId'/>
          </param:string>
        </pip:double>
        <constant:object value='{"street":{"streetName":"Fraunhofer-Platz","number":1},"city":"Kaiserslautern","zip":"67663","type":"WORK"}'/>
      </function:equals>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[pip-list]]
=== pip:list

The *<pip:list>* element is used to request information from a PIP. The *<pip:list>* element returns a list of objects. The parameters that can be added as child elements are sent to the PIP as request parameters.

The *<pip:list>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|method       |String    |-             |yes      |The name of a PIP method.
|default      |String    |-             |yes      |The value that is returned if the PIP is not reachable. Must be in the following array notation: ["Blue", "Green"].
|ttlAmount    |Integer   |0             |no       |The "time to live" value sets the time interval that the response value of the PIP is cached.
|ttlUnit      |enum      |SECONDS       |no       |Time unit of "time to live". Possible units are TIMESTEPS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.
|======================================================================================================================================

A *<pip:list>* can have the following child elements:

* <<param-string,<param:string>>>
* <<param-boolean,<param:boolean>>>
* <<param-int,<param:int>>>
* <<param-long,<param:long>>>
* <<param-float,<param:float>>>
* <<param-double,<param:double>>>

.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the <pip:list> element 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:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy prevents showing data if employee id is not on the list of priviledged employees.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <not>
        <function:contains>
          <pip:list method='getAllPriviledgedEmployees' default='[]'/>
          <param:int name='employeeId'/>
        </function:contains>
      </not>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[parameters]]
== Constants

[[constant-string]]
=== constant:string

The *<constant:string>* tag is used for defining a String constant that returns the specified value as a String.

The *<constant:string>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|value        |String    |-             |yes      |The value of the parameter.
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the the use of a constant.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:string name='role' value='employees'/>
    </event>
    <condition>
      <function:equals>
        <param:string name='lastName'/>
        <constant:string value='Smith'/>
      </function:equals>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[constant-int]]
=== constant:int

The *<constant:int>* tag is used for defining an Integer constant that returns the specified value as an Integer.

The *<constant:int>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|value        |Integer   |-             |yes      |The value of the parameter.
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the the use of a constant.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:string name='role' value='employees'/>
    </event>
    <condition>
      <function:less>
        <param:int name='age'/>
        <constant:int value='30'/>
      </function:less>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[constant-long]]
=== constant:long

The *<constant:long>* tag is used for defining a Long constant that returns the specified value as a Long.

The *<constant:long>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|value        |Long      |-             |yes      |The value of the parameter.
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the the use of a constant.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:string name='role' value='employees'/>
    </event>
    <condition>
      <function:less>
        <param:long name='age'/>
        <constant:long value='30'/>
      </function:less>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[constant-float]]
=== constant:float

The *<constant:float>* tag is used for defining a Float constant that returns the specified value as a Float.

The *<constant:float>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|value        |Float     |-             |yes      |The value of the parameter.
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showEmployees' description='This policy shows the the use of a constant.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:string name='role' value='employees'/>
    </event>
    <condition>
      <function:less>
        <param:float name='bodyHeight'/>
        <constant:float value='5.0'/>
      </function:less>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[constant-double]]
=== constant:double

The *<constant:double>* tag is used for defining a Double constant that returns the specified value as a Double.

The *<constant:double>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|value        |Double      |-             |yes      |The value of the parameter.
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='This policy shows the the use of a constant.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:string name='role' value='employees'/>
    </event>
    <condition>
      <function:less>
        <param:double name='bodyHeight'/>
        <constant:double value='30'/>
      </function:less>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[constant-object]]
=== constant:object

The *<constant:object>* tag is used for defining a complex object in JSON notation.

The *<constant:object>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|value        |String    |-             |yes      |The value of the complex object in JSON notation.
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='This policy shows the the use of a constant.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'>
      <param:string name='role' value='employees'/>
    </event>
    <condition>
      <function:contains>
        <param:object name='user' expression='$.addresses'/>
        <constant:object value='{"street":{"streetName":"Fraunhofer-Platz","number":1},"city":"Kaiserslautern","zip":"67663","type":"WORK"}'/>
      </function:contains>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----

[[constant-list]]
=== constant:list

The *<constant:list>* tag is used for defining a complex object in JSON notation.

The *<constant:list>* element has the following attributes:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|value        |String    |-             |yes      |The list.
|======================================================================================================================================

.Example:
[source,xml]
----
<policy id='urn:policy:cs4:showProjectEffort' description='This policy shows the the use of a constant.'>
  <preventiveMechanism id='showEmployees'>
    <event action='urn:action:cs4:showEmployees'/>
    <condition>
      <function:equals>
        <pip:list method='getUserRoles' default='[]'/>
        <constant:list value='["TEAMLEADER","FOREMAN","CONSTRUCTION_SITE_MANAGER"]'/>
      </function:equals>
    </condition>
    <authorizationDecision name='showEmployeesDecision'>
      <inhibit/>
    </authorizationDecision>
  </preventiveMechanism>
</policy>
----