-
Notifications
You must be signed in to change notification settings - Fork 244
Policy Manager Specification
Policies Manager Specification Version 1.2.1
- Revision History
- Scope
- Terminology and Abbreviations
- Feature Design Requirements
- Packaging a Policy Table
- Policy Assumptions
- System Requirements
- Transferring Policy Table
- Contents of the Policy Table
- Policy Table Exchange
- Requesting a Policy Table
- System Changes Based on Receiving a Policy Table Update
- AppID Management
- App Permissions (onPermissionsChange)
- Policy Table Details Upon Master Reset
| Version | Change Summary | Date | Author |
|---|---|---|---|
| 1.2 | Final Ford Version | 2013-12-06 | Elizabeth Halash |
| 1.2.1 | Edited for SDL | 2016-03-11 | Justin Dickow |
This specification details the core System functinality of the Policies Manager.
| Term | Description |
|---|---|
| JSON | JavaScript Object Notation |
| Proxy | The mobile library running within an SDL Enabled Mobile Application |
| US | United States |
| HMI | Human Machine Interface |
| TTS | Text To Speech |
| RPC | Remote Procedure Call |
In order to enabled advanced functionality and protect SDL APIs from unauthorized use, it is necessary to implement a policy mechanism that allows mobile applications to be granted elevated privileges, while providing usage data to a backend server.
Policies are intended to remotely managed SDL-enabled apps, including app-sepcific and device-specific access to system functionality.
All mobile apps must be issued an AppID from SHAID in order to use SDL in policies-enabled modules. All mobile apps shall send the AppID in the registerAppInterface RPC request.
TODO: Link to policy flows
The paired mobile device must contain a mobile app that leverages the policies-enabled SDL API. The system communicates with the backend using RPC calls contained within the SDL API running on the mobile device.
The mobile device must have an active data connection through which the system will send and receive policy tables.
#System Requirements
In preparation for a Policy Table Exchange, the system must have enough memory to hold a Policy Table Snapshot in memory. Policy Tables (Local, Snapshot, and Update) have an artificial upper file size limit of 200 kilobytes.
A local Policy Table will be baked into each System image. It is an administrator's role to generate an appropriate Policy Table from the cloud backend, which includes the actual messages within the consumer_friendly_messages section. Additionally, the administrator will have to manually insert preloaded_pt:true to the module_config section. Finally, the admin should deliver the resulting JSON to the appropriate vendor to be incorporated into the System software image.
The system will communicate policy table data over the same transport layer SDL uses.
TODO: Link to policy flows
The mobile device and the System shall communicate in such a way that the user shall see no discernible difference in system operation
The only confirmation that the module successfully sent a message to the backend is the receipt of a packet from the cloud.
Refer to TODO: for a list and details of all elements in the policy table
The policy table variations described below with be authored in JSON (UTF-8 encoded). They represent the information at rest on the Policies Manager
This file shall be incorporated into the System image itself. It reflects a Policy Table Update with no app-specific policies and includes a flag to identify it as a preloaded version. It shall include the standard format of the table and the static field names.
The Preload will not include the following policies Manager-authored portions of the table: module_meta, device_data, and usage_and_error_counts. However, the Preload, will include keys for Policies Manager-authored sections (as appropriate). The app_policies section in the Preload shall only include the policy for the key default.
After a successful Policy Table Exchange with the backend, a Preloaded table is known as a Local Policy Table
The local Policy Table shall include all sections once policies are enabled on the system.
The policy table variations described below will be authored in JSON (UTF-8 encoded). They contain the information sent to the policies manger from the backend server.
Source: Policies Manager running on the System
Destination: Policies Cloud
The snapshot represents a Local Policy Table at a particular moment in time. This delivers a snapshot of the local policy table to the backend. The backend responds with a Policy Table update based on the contents of the Policy Table Snapshot.
The Policy Table Snapshot shall include all sections in the policy table. However, the consumer_friendly_messages section is versioned to limit the size of a request payload, so a snapshot only includes the messages' version, but not the messages themselves.
If the consumer_friendly_messages section is populated, ie it contains:
"consumer_friendly_messages":{
"messages": {…}
}
it will replace the current section onboard the module. If there is no messages key, the current local consumer_friendly_messages section shall be maintained in the policy table.
Source: Policies Cloud
Destination: Policies Manager running on the System
This represents only the backend-authored portions of the table, including the latest application policies. The update will not include the following policies Manager-authored portions of the table: module_meta, device_data, and usage_and_error_counts.
The Policy Table Update shall replace the backend-authored portions of the Local Policy Table: module_config, functional_groupings, consumer_friendly_messages, and app_policies. The other sections are unchanged.
This section is authored by the backend. The module_config section specified values that can and shall effect the configuration of the System related to policies. For example, it includes destination URLs that the mobile app proxy shall use as a destination to send the policy table. Accordingly, the Policies Manager passes the destination URL to the mobile app proxy along with the policy table packet itself.
This section is authored by the backend. This section lists all RPCs used by any and all SDL apps and groups them to simplify assignment and implementation.
This section is authored by the backend. This section lists any necessary TTS prompt or display text in all needed languages.
This section is authored by the backend. Note that although an Application-specific Policy is authored by the backend, the Policies Manager will insert an AppID (key) during an app’s first use. This section specifies the specific permissions and functions for each appID.
Mandatory app_policies keys:
-
default- specifies the default app policy -
device- specifies the associated functional group and requiredconsumer_friendly_messagesfor user consent associated with a device.
This section is authored by the Policies Manager. The section provides information about the System to the backend upon a policy table exchange.
This section is authored by the Policies Manager. The sections provide usage and error tracking to the backend upon a policy table exchange.
This section is authored by the Policies Manager. It also includes user consent records, which need to be populated before a policy table exchange, if applicable. The keys of this section are a unique device identifier, which is added by the Policies Manager. A user’s nomadic device is generally a proxy for his identity.
An exchange involves a request (Policy Table Snapshot - PTS) and a response (Policy Table Update - PTU) and several facilitating systems that make up a secure communication channel. Details below are limited to the System and nomadic device (Proxy).
Policies Manager - Prepare and execute the request as follows:
- Copy the Local Policy Table into Memory (Policy Table Snapshot - PTS refers to this copy)
- Remove the messages portion of the
consumer_friendly_messagessection (See data dictionary) from PTS - Select an app (at random) through which to send the policy table packet
- Lookup the appropriate destination URL for the service type
- Lookup the appropriate timeout
- Base64 encode the Local Policy Table Snapshot and use as payload. Send local policy table snapshot to proxy via
onSystemRequest(). - Send [PTS] and a URL (where applicable) to the Proxy using an SDL RPC request.
- Start the timeout countdown
Nomadic Device (Proxy) – Handle the request as follows
- If the URL is blank or not present in the RPC notification, pass the blob to the mobile application.
- If the URL is provided send it to the specified URL.
Nomadic Device (Proxy) – Handle the response as follows
- Receive packet from backed.
- Send as hybrid message (as expected by the Policies Manager) using an SDL API.
Policies Manager – Upon receiving the response (before timeout) from the nomadic device (Proxy), process it as follows
- Base64-decode the payload, which is the Policy Table Update.
- Validate the Policy Table Update. The validation will not reject tables that include fields with a status of ‘omitted,’ it will assume these are to be ignored. Validation will reject a policy table update if it does not include fields with a status of ‘required.’ If validation fails, log the error locally and discard the policy table update.
- Replace the following sections of the Local Policy Table with the corresponding sections from PTU:
module_config,functional_groupings,app_policies - If the
consumer_friendly_messagessection of PTU contains a messages subsection, replace theconsumer_friendly_messagesportion of the Local Policy Table with the same section from PTU
Before requesting a policy table, the Policies Manager shall check that the device is connected and that a mobile application is connected.
The Policies Manager shall request an update to its local policy table only through apps that have an HMI status of Background, Limited, and Full. If there are no mobile apps with any of these statuses, the system shall use an app with an HMI Level of NONE and ensure only that particular app is being used to request a policy table update.
Before requesting a policy table update, the System shall ensure an sdp query has been completed and all mobile apps on the phone have successfully registered with the System and their appIDs have been added to the local policy table.
The policies manager shall request an update to its local policy table in the following scenarios:
- When an appID of a registered app is not listed on the Local Policy Table.
- When the user starts a mobile app that requires a policy table update and the policies manager never received an updated table over the initial request sequence.
- After n ignition cycles . N shall be defined within the Local Policy Table under
exchange_after_x_ignition_cycles. - After n kilometers, based on the odometer. N shall be defined within the Local Policy Table under
exchange_after_x_kilometers. - After n elapsed time. N shall be defined within the Local Policy Table under
exchange_after_x_days. (This rule shall only apply if the system provided time is available).
If the policies manager does not receive an updated table within a certain timeframe, it shall send a new request for a Policy table update.
The number of times the system retries to retrieve a policy table is defined within the Policy table. The timeout and request sequence is defined as an array in the policy table.
The policy table also includes a timeout value, timeout_after_x_seconds, that specifies the seconds to wait for a response. The timeout value shall be added to the total time between retries, i.e., time of 2nd retry = 1st retry + timeout.
Regardless of the sequence, each request shall attempt to use a different mobile app as the pass-through if multiple mobile apps are available. This provides a work-around in case a particular mobile app is somehow blocking requests from the system.
If a policy table exchange is unsuccessful after the retry strategy is complete, the system shall wait until an ignition cycle before attempting again.
Retry sequence in the policy table:
"timeout_after_x_seconds":60,
"seconds_between_retries":[1, 5, 25, 125, 625]
An example request sequence:
t0 = send 1st policy table request
t1 = t0+30s (timeout) + 1s (retry wait) = 31s = send 2nd request (1st retry)
- uses 2nd url listed in policy table, if more than one exists
t2 = t1+30s (timeout) + 5s (retry wait) = 35s+31s = 66s = send 3rd request (2nd retry)
The retry sequence should be restarted if anything triggers a policy table request, including a user requesting an update.
There shall be 3 internal flags to indicate the status of the ongoing policy request.
This flag shall indicate System is waiting to receive something from policies cloud
Operation:
Set to true when a snapshot is sent
Set to false when an update is received or times out
This flag shall be checked on ignition and app registration in order to start an exchange if the previous one failed(e.g. ignitions exceeded, but no app registered to use for exchange)
Operation:
Set to true when an event happens that requires an exchange
Set to false when an update occurs(unless one is pending)
This flag shall indicate the system is waiting to send something to the policies cloud
Operation:
Set to true if an exchange is requested while another one is in progress
Set to false when a snap shot is sent out
getPolicyTableStatus from Policies Manager to HMI returns the status of the request so the HMI can be updated, if applicable. For example:
| exchangeInprogress | updateRequired | Status |
|---|---|---|
| 0 | 0 | Up To Date |
| 0 | 1 | Update Required |
| 1 | 0 | Pending |
| 1 | 1 | Pending |
If the system does not receive an updated table during a key-on session, it shall restart the request sequence during the next key-on. Example scenarios when the system may be unable to receive a request include, but are not limited to:
- App unexpectedly crashes/is removed from System
- App is blocking requests
- Phone unexpectedly disconnects from System
- Ignition off
- Backend server error
- Poor/no phone data connection
- Customer receives a phone call while the policy table is being downloaded into the vehicle. (CDMA, Edge)
Based on the updated table, the system shall instantly apply the app policies as listed in the table. For example, the HMI Status of certain apps may change from HMI_NONE to the HMI_BACKGROUND as defined under default_hmi in the app-specific policies within the Policy Table Update.
The system shall send an `onPermissionsChange()`` notification to any connected mobile apps whose permissions were changed in the updated table.
When an exchange occurs, policy table shall be compared against current paired devices. If a device is no longer listed as a paired device, the Policies Manager shall also remove the device's info from the policy table. This shall only occur after a policy table exchange occurs to ensure information about a device is not lost
Regardless of HMI state, when a Policy Table update occurs or a user changes permissions:
-
onPermissionsChangeshall be sent to the app - Permission changes are enforced immediately
appID shall be a required parameter of `RegisterAppInterface()``. This enables the system to identify an app and apply an app’s policy from the table.
The Policies Manager shall check for any mobile app nicknames associated with an appID. If the registered name of the mobile app does not match an associated nickname, the mobile app shall be unregistered from the System.
Nickname check must be done before duplicate app check, ie, a second app attempts to register with same appName.
If the appID of a registered app is listed in the table, the Policies Manager shall apply the policy as dictated in the local policy table.
If the appID is not listed in the local policy table, the mobile app shall remain registered and continue to operate using default permissions. The Policies Manager shall insert the appID in the policy table and assign a default policy in the app_policies section: "someAppId": "default"
If an appID has a policy of appID: ”null”`` in the policy table, the mobile app shall remain registered in the mobile apps menu with an HMI State of NONE, but the Policies Manager shall reject any rpc requests from the mobile app. If the mobile app is selected by the user, the system shall issue HMI messaging as defined in the HMI flow and the app shall remain in HMI_NONE`.
A revoked mobile app with permissions of NULL shall never be granted new permissions. Such an app would be given a new appID.
After the System sends the registerAppInterface response, the system shall also send a notification, `onPermissionsChange()``, which includes a JSON object of the current permission status, as defined by the policy table, to the mobile app that just registered. Additionally, this notification is sent whenever a permissions change occurs, including:
- a policy table update occurs that either adds or removes backend-defined permissions
- a user changes their consent settings
When an app sends an RPC request, the system must check the following:
- If the app policy lists the functional group that includes the requested RPC
- HMI status of app vs. allowed HMI for RPC
To determine consent for a particular RPC in a particular HMI level with particular parameters (if applicable), the system shall find all of the functional groups the RPC is included in. If user consent is needed as listed within the functional group in the policy table, the system shall use a logical AND: backend permissions AND User permissions. If the RPC is listed under more than one group, the system shall perform a logical OR amongst all of the possible allowed permissions scenarios for the RPC (and parameter/or HMI level) defined by each of the functional groups.
The System shall assign a value of allowed to an RPC request if it is allowed by both the backend and the user. The System shall perform the desired operation.
It shall assign a value of userDissallowed to an RPC request if the request is allowed by the backend, but disallowed by the user.
It shall assign a value of disallowed to an RPC request if the request is not allowed by the backend.
It shall assign a value of pending to an RPC request if it is allowed by the backend, but the user has not been prompted yet. The System shall send a failure with the message of pending in response to the RPC request.
The policy tables provides for records of user consent for app-specific permissions.
The mobile app is sent onPermissionsChange containing the current permissions statuses, including the latest user changes. The mobile app proceeds to HMI_FULL
Mobile App is sent onPermissionsChange containing the current permissions statuses, including the latest user changes. The mobile app proceeds to HMI_FULL.
If the system supports a user changing a mobile app’s permissions via an app settings menu, the onPermissionsChange() notification shall be sent to the corresponding app.
In onPermissionsChange notification: list all RPCs, parameters, and HMI statuses under appID:groups => groups:”rpcs”:”paramerters”
For the “status” value, go to deviceID: "user_consent_records":appID: "consent_groups": <groupName>:<value>
The structure of the json within onPermissionsChange(jsonObject):
{
"notification": {
"correlationID": 0,
"parameters": {
"permissionItem": [{
"hmiPermissions": {
"userDisallowed": [],
"allowed": ["BACKGROUND",
"LIMITED",
"FULL"]
},
"parameterPermissions": {
"userDisallowed": [],
"allowed": []
},
"rpcName": "AddCommand"
},
"hmiPermissions": {
"userDisallowed": [BACKGROUND],
"allowed": [
"LIMITED",
"FULL"]
},
"parameterPermissions": {
"userDisallowed": [],
"allowed": []
},
"rpcName": "alert"
},
"hmiPermissions": {
"userDisallowed": [],
"allowed": ["BACKGROUND",
"LIMITED",
"FULL"]
},
"parameterPermissions": {
"userDisallowed": ["GPS", "speed"],
"allowed":["FUELLEVEL", 'FUELECONOMY", "ENGINERPM", "BATTVOLTS", "ODOMETER", "VIN"],
},
"rpcName": "getVehicleData"
}
}
}
}
}
JSON Object getPermissions(json object)
Request 1:
getPermissions({“rpc”: {“getVehicleData”:{}}})
Response 1:
{
"notification": {
"correlationID": 0,
"parameters": {
"permissionItem": [{
"hmiPermissions": {
"userDisallowed": [],
"allowed": ["BACKGROUND",
"LIMITED",
"FULL"]
},
"parameterPermissions": {
"userDisallowed": ["GPS", "speed"],
"allowed":["FUELLEVEL", 'FUELECONOMY", "ENGINERPM", "BATTVOLTS", "ODOMETER", "VIN"],
},
"rpcName": "getVehicleData"
}
}
}
}
}
Request 2:
getPermissions("rpcs": {"Alert":{}}})
Response 2:
{
"notification": {
"correlationID": 0,
"parameters": {
"permissionItem": [{
"hmiPermissions": {
"userDisallowed": [BACKGROUND],
"allowed": [
"LIMITED",
"FULL"]
},
"parameterPermissions": {
"userDisallowed": [],
"allowed": []
},
"rpcName": "alert"
}
}
}
}
}
The Basic strategy is for the policy table to match the current paired device list of the system. (Upon a master reset all device are unpaired). Upon a master reset, revert the local policy table back to the preload policy table.