Skip to content

Commit

Permalink
Merge pull request #483 from UlfBj/issue474
Browse files Browse the repository at this point in the history 
Consent support chapter.
  • Loading branch information
@tguild
tguild authored Nov 14, 2023
2 parents ac6000e + 5b021d1 commit 65b7766
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 8 deletions.
88 changes: 80 additions & 8 deletions spec/VISSv2_Core.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1002,7 +1002,7 @@ <h2>Protocol Messages</h2>
<section id="access-grant-request">
<h2>Access Grant Request</h2>
<p>
The request shall contain the Context and Proof parameters below, the other two are optional:
The request shall contain the Context and Proof parameters below, the others are optional:
<ul>
<li>VIN: The vehicle identification number. Instead of the
assigned VIN a generated hash can be used as a pseudo VIN,
Expand All @@ -1024,7 +1024,7 @@ <h2>Access Grant Request</h2>
The protocol may involve also third parties, such as the <a href="#ecosystem-manager-def">ecosystem manager</a> or the
<a href="#resource-owner-def">resource owner</a>. The protocol is out of scope for this specification.<br>
In scenarios where both the client and the <a href="#access-grant-server-def">access grant token server</a>
are deployed in-vehicle the VIN parameter may be omitted, in all other deployment scenarios it shall be present.
are deployed in-vehicle the VIN parameter may be omitted, in all other deployment scenarios it shall be present.<br>
</p>
</section>

Expand Down Expand Up @@ -1129,7 +1129,7 @@ <h2>Client</h2>
<li>The <a href="#device-roles-def">device</a>. It is in charge of running the Apps that make requests to the VISSv2 server</li>
<li>The <a href="#application-roles-def">app. </a>It runs requests on behalf of the user.</li>
<li>The <a href="#user-roles-def">user</a>. It delegates access rights to the app.</li>
</ul>
</ul>
All the information regarding the client is encoded in the <a href="#client-context-def">context</a> of the request.
</p>
</section>
Expand Down Expand Up @@ -1403,7 +1403,7 @@ <h2>Short Term Access Grant Token</h2>
<a href="#access-grant-server-def">access grant token server</a>.<br>
The issued at (iat) claim shall be set to the time of token issuance, in Unix time.<br>
The expiry (exp) claim shall be set to the time when the token expires, in Unix time.<br>
The <a href="#client-context-def">Client context</a> (clx) claim shall be set to the role triplet the client has been assigned.
The <a href="#client-context-def">Client context</a> (clx) claim shall be set to the role triplet that the client has been assigned.
The delimiter separating the roles is a plus sign (+).<br>
The audience (aud) claim shall be set to the URL "w3.org/VISSv2".<br>
The JSON Web Token identity (jti) claim shall be set to a UUID that is unique within the domain controlled by the
Expand Down Expand Up @@ -1437,7 +1437,7 @@ <h2>Long Term Access Grant Token</h2>
<a href="#access-grant-server-def">access grant token server</a>.<br>
The issued at (iat) claim shall be set to the time of token issuance, in Unix time.<br>
The expiry (exp) claim shall be set to the time when the token expires, in Unix time.<br>
The <a href="#client-context-def">Client context</a> (clx) claim shall be set to the role triplet the client has been assigned.
The <a href="#client-context-def">Client context</a> (clx) claim shall be set to the role triplet that the client has been assigned.
The delimiter separating the roles is a plus sign (+).<br>
The public key (pub) claim shall be set to the public key that the <a href="#client-def">client</a> provided in the
<a href="#access-grant-request-def">access grant request</a>, using the JSON Web Key (JWK) data structure [[RFC7517]].<br>
Expand Down Expand Up @@ -1481,7 +1481,7 @@ <h2>Access Token</h2>
Each signal is defined as a JSON object containing the signal path, and the signal permission as shown below.<br>
{"path":"vss-path", "access_permission":"permission"}<br>
If the scope claim is set to a purpose, the client context claim MUST be present in the token.<br>
The <a href="#client-context-def">Client context</a> (clx) claim shall be set to the role triplet the client has been assigned.
The <a href="#client-context-def">Client context</a> (clx) claim shall be set to the role triplet that the client has been assigned.
The delimiter separating the roles is a plus sign (+).<br>
The audience (aud) claim shall be set to the URL "w3.org/VISSv2".<br>
The JSON Web Token identity (jti) claim shall be set to an unguessable UUID that is unique within the domain controlled by the
Expand Down Expand Up @@ -1531,7 +1531,7 @@ <h2>Proof of Possession</h2>
<h2>Client Context</h2>
<p>
<em>This section is non-normative.</em><br>
The <a href="#client-def">client</a> actor is characterized by three subactors:
The client context contains a <a href="#client-def">client</a> actor that is characterized by three subactors:
<ul>
<li>The <a href="#user-roles-def">user</a> of the application.</li>
<li>The <a href="#application-roles-def">application</a>.</li>
Expand Down Expand Up @@ -1636,7 +1636,7 @@ <h2>Purpose List</h2>
There is also a long purpose description, which may be used in the dialogue for consent, if needed.
Then there is a list of the <a href="#client-context-def">client context</a>, i. e. the sub-actor role triplet,
that can be granted this access, and last there is a list of the signals that the client is given access to for this purpose,
with the allowed access permission. The list shall use a JSON format as shown in the example below.
with the access control and consent requirements. The list shall use a JSON format as shown in the example below.
<pre><code>
{"purposes":
[{"short": "fuel-status",
Expand Down Expand Up @@ -1732,6 +1732,78 @@ <h2>Access Control Selection</h2>
</section>
</section>

<section id="consent-support">
<h2>Consent support</h2>
<em>This section is non-normative.</em><br>
<p>
Handling of consent involves vehicle and cloud architectural subsystems that is out of scope in VISSv2.
However, a VISSv2 vehicle server has a capability to enforce consent results, i. e. to allow or block access to requested data.
This can be leveraged in a model where the server receives consent results from an “External Consent Framework” (ECF) and uses that information to either grant client requests,
or not, for data that is consent protected. How the ECF obtains the consent status is out-of-scope in this specification.
A secure, local communication channel exists between the in-vehicle ECF and the server as shown in the figure below,
over which the server can inquire about the consent status for data requested by a client.
<figure id="fig-consent-architecture">
<img src="images/consent-architecture.jpg" alt="Consent architecture.">
<figcaption> <span class="fig-title">Consent architecture.</span></figcaption>
</figure>
The ECF is responsible for the lifetime management of the consent status for all data that is managed by the server, which may involve initialization,
expiry update, event based update, consent status removal.
The consent status that the ECF provides to the server is associated with an expiry time, which when reached leads to that the status shall be treated as NOT_SET,
which must be enforced by the server.<br>
The consent status can be set to any of the following values:<br>
<ul>
<li>NOT_SET // the server must request the ECF for the status. Unless an immediate ECF response is given,
the server must deny any client request with an error code that shows the reason.</li>
<li>NO // the server must deny any client request with an error code that shows the reason.</li>
<li>IN_VEHICLE // the server shall serve the client request. The client is not allowed to off-board the data.</li>
<li>YES // the server shall serve the client request. The client is allowed to off-board the data.</li>
</ul>
Regardless of the value of the consent status, if the associated expiry time is exceeded, the server shall treat the consent status as if it had the value NOT_SET.
It shall be possible for the ECF to cancel a valid consent, which shall lead to the consent status being set to NOT_SET.
Any consequences to the data provided to the client prior to the cancelling is out of scope.
The expiry time shall have the timestamp format defined in chapter 5.3 Timestamps.<br>
In the case of a client request requiring a consent for data to be returned, it is the responsibility of the
<a href="#access-token-server-def">access token server</a> to obtain it from the ECF during the dialogue with a client requesting an access token.
This is done by issuing a request to the ECF which shall contain the following information:
<ul>
<li>The requested data.</li>
<li>The purpose of the request.</li>
<li>The client context.</li>
</ul>
The response from the ECF shall contain:
<ul>
<li>Consent status.</li>
<li>Expiry time of the consent.</li>
</ul>
If the received consent status is set to NO or NOT_SET, then the access token server must not provide a valid access token to the requesting client.
The server must store the consent status that it receives from the ECF, together with the data from the request, for the duration set by the expiry time.<br>
Whether a server shall take action to obtain a consent or not shall be signalled in the VSS tree.
This is done by tagging appropriate nodes in the VSS tree extending the model used for access control selection.
The key-value pair used for tagging of access control is suffixed with "+consent" as shown in the example below:
<ul>
<li>"validate":"read-write+consent"</li>
</ul>
The consent tagging follows the same inheritance rules as defined for the access control tagging.
</p>

<section id="external-consent-framework-interface">
<h2>External Consent Framework Interface</h2>
<p>
A server receiving a client request that involves obtaining a consent status shall send a request to the ECF
on which it shall receive a response cintaining the consent status.

The request shall contain the data from the list in the previous chapter.

The response shall contain the following data:
<ul>
<li>The consent status.</li>
<li>The expiry time of the consent status.</li>
</ul>
This communication shall be carried out using a secure channel (e.g. TLS).
</p>
</section>
</section>

<section id="tof" class="appendix"></section>

<section id="server-capabilities" class="appendix">
Expand Down
Binary file added spec/images/consent-architecture.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 65b7766

Please sign in to comment.