---
# System prepended metadata

title: Notes about sifis api

---

## Notes about sifis api and UCON

[UCON](https://github.com/sifis-home/usage-control/pkgs/container/usage-control-engine) uses the websocket so a [dht broker](https://github.com/domo-iot/sifis-dht-test) is needed.

https://github.com/sifis-home/usage-control/blob/sifis-home/UCSDht/src/main/resources/installation-request.xml
> [name=marco-rasori]Note that the above request is an *installation request*, not an *execution request*. It is generated by the Application Manager (actually by the tool [sifis-xacml](https://github.com/sifis-home/sifis-xacml)) by using the App Label (manifest).

The workflow is the following

- runtime `registers` itself to the UCON
- for each sifis-api action the runtime should
    - issue a `try` to ask if the change is allowed
    - issue a `start` to commit the action
    - issue a `end` 
- the `reevaluation` message may be sent to require rolling back to a state

### Register
At runtime start
Runtime -> https://github.com/sifis-home/json-schemas/blob/master/data/usage-control/register-instance.json
UC -> https://github.com/sifis-home/json-schemas/blob/master/data/usage-control/register-response-instance.json

---
### Try
TryAccess Request: https://github.com/sifis-home/json-schemas/blob/master/data/usage-control/try-access-instance.json
- Runtime -> Instead of `request`: 
   - app_id, 
     - app_id -> subject-id 
   - sifis_api, e.g `Lamp::turn_on, lamp_id`, or `Lamp::set_lamp_brightness, lamp_id, 100`
     - turn_on -> action-id
     - lamp_id -> resource-id
   - seq_id 

 - urn:...:action:action-id = `turn_on, lamp_id` ~> `turn, lamp_id, true`
 - urn:...:action:action-id = `set_brightness`
 - urn:...:action:action-value = `100`

https://github.com/sifis-home/usage-control/blob/sifis-home/UCSDht/src/test/python/dev-api/requests/set_brightness_95.xml

``` xml
    <Attributes Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action">
        <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" IncludeInResult="false">
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">set_{property}</AttributeValue>
        </Attribute>
        <Attribute AttributeId="eu:sifis-home:1.0:action:{property}-value" IncludeInResult="false">
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#{type}">{value}</AttributeValue>
        </Attribute>
    </Attributes>
```

`turn_on` in reality
``` xml
    <Attributes Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action">
        <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" IncludeInResult="false">
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">set_on</AttributeValue>
        </Attribute>
        <Attribute AttributeId="eu:sifis-home:1.0:action:on-value" IncludeInResult="false">
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#integer">true</AttributeValue>
        </Attribute>
    </Attributes>
```


- UC -> https://github.com/sifis-home/json-schemas/blob/master/data/usage-control/try-access-response-instance.json

---
### Start
StartAccess Request: https://github.com/sifis-home/json-schemas/blob/master/data/usage-control/start-access-instance.json
- Runtime -> json above
- UC -> https://github.com/sifis-home/json-schemas/blob/master/data/usage-control/start-access-response-instance.json

---
### End
EndAccess Request: https://github.com/sifis-home/json-schemas/blob/master/data/usage-control/end-access-instance.json
- Runtime -> json above
- UC -> https://github.com/sifis-home/json-schemas/blob/master/data/usage-control/end-access-response-instance.json

---
### Reevaluation
Reevaluation response: unsolicited sent by the UCON if a policy is not satisfied anymore: https://github.com/sifis-home/json-schemas/blob/master/data/usage-control/reevaluation-response-instance.json

Additional payload expected, the reevaluations are always of the `set` kind:

``` json
{ "action": "brightness", "value": 50 }
{ "action": "turn", "value": false }
```

- `turn: true` -> turn_on
- `turn: false` -> turn_off

``` json
{ "action": "drain", "value": true }
{ "action": "flow", "value": 0 }
{ "action": "temperature", "value": 20 }
```

- `drain: true` -> open_sink_drain
- `drain: false` -> close_sink_drain

> [name=marco-rasori] The additional payload you expect is not part of a reevaluation.
> The PEP, in this case the Runtime, should take care of remembering the `session_id` for all its "ongoing sessions", i.e., requests that received Permit both for a `try` and and a`start`.
> The PEP *must* remember the `session_ids`: at a certain point in time, the PEP will call an `end`, and to call it, it needs to specify the `session_id` related to the session it intends to terminate the access.
> The PEP is responsible of terminating the access to the resource, and the way this is achieved is a PEP decision.
> 
> I suggest you to associate the `session_id` with -- what you call -- the "additional payload expected", after you receive a `try_response` with evaluation equal to `Permit`.
> Indeed, when you receive this response, you should grant the access to the resource, and, after that, you should send a `start` message. Now, if the `start_response` is `Deny`, you *must know* how to terminate the access to the resource. This is exactly what you want me to do when sending the "additional payload expected", but this makes no sense to me.
