Provide documentation for UM owner's approval mechanism

docs/owner-consent-agent-api.md

@@ -0,0 +1,32 @@
+### Overview
+The Update Manager interacts with a Human Machine Interface(HMI) application using MQTT messages with JSON payload. These messages implement the designs described in [Owner Consent Specification](./owner-consent-specification.md). 
+
+### Message Format
+The messages for the bidirectional exchange between the Update Manager and the HMI application are carried in the following format:
+
+```
+{
+  "activityId": "123e4567-e89b-12d3-a456-426614174000",
+  "timestamp": 123456789,
+  "payload": {} // actual message content as per message specification
+}
+```
+
+### Message Data Model
+The message data model has the following three metadata elements:
+
+- `activityId` [string]: UUID generated by the backend which is used for correlating a set of device / backend messages with an activity entity (e.g. a desired state application process) on system level
+
+- `timestamp` [int64]: Message creation timestamp. Number of milliseconds that have elapsed since the Unix epoch (00:00:00 UTC on 1 January 1970)
+
+- `payload` [object]: Custom, unstructured message payload per message specification
+
+### MQTT Topics
+The Update Manager and the connector component bidirectionally exchange messages in the previously described format using the following MQTT topics:
+
+| Topic | Direction | Purpose |
+| - | - | - |
+| `${some-optional-prefix}update/ownerconsent` | Update Manager -> HMI | Informing the HMI application that an owner consent is needed to proceed with the update process |
+| `${some-optional-prefix}update/ownerconsentfeedback` | HMI -> Update Manager | Informing the Update Manager that the owner approved / denied the update |
+
+`${some-optional-prefix}` can be any string defined for the concrete deployment, e.g. `device`, `vehicle`, etc.

docs/owner-consent-specification.md

@@ -0,0 +1,50 @@
+### Owner Consent
+Sometimes an update comes with a down time or legal obligations and the device owner should be asked for a consent. For this case the Update Manager(UM) has the ability to request the owner's consent at single or multiple phases during the update process. When the owner approves the update through a Human Machine Interface(HMI), the UM continues to orchestrate it across the Update Agents(UAs). However, when the update gets denied the UM commands the UAs to rollback to the state before the update.
+
+### Owner Consent Data Model
+
+The following table describes all supported properties and sections of the Owner Consent specification:
+
+| Property | Type | Description |
+| - | - | - |
+| **Consent properties** | | |
+| command | string | [Command UM is about to issue to the UAs, for which an owner's consent is needed ](#supported-owner-consent-commands) |
+| **Consent Feedback properties** | | |
+| status | string | [Status of the consent feedback](#supported-owner-consent-statuses) |
+
+### Supported Owner Consent commands
+
+The list of the supported UM->UA commands for which the owner's approval could be requested :
+
+| Status | Description |
+| - | - |
+| DOWNLOAD | Denotes that the owner consent is requested before download phase |
+| UPDATE | Denotes that the owner consent is requested before the update phase |
+| ACTIVATE | Denotes that the owner consent is requested before the activation phase |
+
+### Supported Owner Consent statuses
+
+The list of the supported feedback statuses :
+
+| Status | Description |
+| - | - |
+| APPROVED | Denotes that the owner approved the update operation |
+| DENIED | Denotes that the owner has denied the update operation |
+
+### Owner Consent Data Model Example
+
+This is a full example of a owner consent message for a device that is currently applying a desired state. In this example, the owner consent is done before the `DOWNLOAD` command, the UM needs consent to instruct the UAs to download the needed artifacts for the update:
+```json
+{
+	"command": "DOWNLOAD"
+}
+```
+
+### Owner Consent Feedback Data Model Example
+
+This is a full example of a owner consent feedback message for a device that is currently applying a desired state. In this example, the owner has approved the update and the Update Manager will proceed to orchestrate the update on the device:
+```json
+{
+	"status": "APPROVED"
+}
+```