Authority URI Component

The authority component of the URI consists of an IP address or a domain name followed by a colon and a port number.

Path URI Component

The path URI component definition differs between the three resources.
For the VISSv3 server the definition is as follows.
The path consists a sequence of VSS node names separated by a delimiter. VSS specifies the dot (.) as delimiter, which therefore is the recommended choice also in this specification. However, in HTTP URLs the conventional delimiter is slash (/), therefore also this delimiter is supported. To exemplify, the path expression from traversing the nodes Vehicle, Car, Engine, RPM can be "Vehicle.Car.Engine.RPM", or "Vehicle/Car/Engine/RPM". A mix of delimiters in the same path expression SHOULD be avoided.
The path MUST not contain any wildcard characters ("*"), for such needs see .
For the access grant token server the path is "agts".
For the access token server the path is "ats".

Read

Purpose: Get one or more values addressed by the given path.

The client MAY have to obtain an authorization token before being able to access the values. If the server is able to satisfy the request it MUST return a success response. If the server is unable to fulfil the request, then the server MUST return an error response.

Arguments, of which path is mandatory:

• path The path as defined in VSS to one or more nodes in the VSS tree.
• filter Additional information defining the requested data.
• authorization The authorization token.
• data compression The data compression scheme(s).

Success response, of which authorization is optional:

• data The data structure contains one or more sets of a path and a data point structure.
• path The path for the associated data point structure.
• data point A structure containing one or more tuplets of value and timestamp.
• value The latest available value. Please note that also for actuators this returns the current value, and not a target value that might have been set.
• timestamp The capture time of the value.
• authorization A handle representing the authorization token.
• timestamp The time of the server request execution.

Update

Purpose: Provide altered value to the vehicle signal addressed by the path

The client MAY have to obtain an authorization token before being able to update the vehicle signal. If the server is able to satisfy the request it MUST return a success response, else it MUST return an error message. Only actuator type signals can be updated. Please note that a success response does not guarantee that the actuation attempt to change to the updated target value has, or will, succeed. A client may monitor the actuation progress through subsequent reads of the actuator value.

Arguments, of which path and value are mandatory:

• path The path as defined in VSS to a single node in the VSS tree.
• value The value by which the vehicle signal addressed by the path will be updated to.
• authorization The authorization token.

Success response, of which authorization is optional:

• authorization A handle representing the authorization token.
• timestamp The time of the server request execution. This may not be the same as the final update time of the signal.

Subscribe

Purpose: Get asynchronous messages containing the value(s) addressed by the path. The triggering rules for issuing the event messages are set by the filter data.

The client MAY have to obtain an authorization token before being able to subscribe to the vehicle signal(s). The server MUST issue an event message if a trigger rule is fulfilled. If the server is able to satisfy the request it MUST return a success response. If the server is unable to fulfil the request, then the server MUST return an error response. If an error occurs during the subscription period, the server SHOULD return an error event.

Arguments, of which path and filter are mandatory:

• path The path as defined in VSS to one or more nodes in the VSS tree.
• filter The rule set describing triggering criterias for issuance of asynchronous event messages.
• authorization The authorization token.
• data compression The data compression scheme(s).

Success response, of which authorization is optional:

• authorization A handle representing the authorization token.
• subscriptionId A handle identifying event messages associated with the subscription.
• timestamp The start time for the subscription period.

Unsubscribe

Purpose: Termination of the subscription period started by a previous subscribe request.

If the server is able to satisfy the request it MUST return a success response, and it MUST stop issuing event messages associated to the subscription handle. If the server is unable to fulfil the request, then the server MUST return an error response.

Arguments, of which subscriptionId is mandatory:

• subscriptionId Handle identifying the subscription.

Success response:

• timestamp The stop time for the subscription period.

Subscription

Purpose: Asynchronous client event message according to the subscribe request trigger rules.

The server MUST issue an event message when a triggering rule associated with the subscription is met. If the server cannot fulfill the triggering rules it MUST issue an error event message and terminate the subscription.

Arguments:

• subscriptionId Handle identifying the subscription.
• data The data structure contains one or more sets of a path and a data point structure.
• path The path for the associated data point structure.
• data point A structure containing one or more tuplets of value and timestamp.
• value The value associated with the filter expression.
• timestamp The capture time of the value.
• timestamp The time of the server subscription execution.

Error Information

The error information has three components - a number, a reason, and a message. The number MUST always be part of the error information, while the reason and message components MAY be a part of it.

• number See the status codes as defined in [[viss3-transport-examples]].
• reason See the status codes as defined in [[viss3-transport-examples]].
• message See the status codes as defined in [[viss3-transport-examples]].

Single Boundary Range

One logical "boundary operator" evaluates the current signal value in relation to the boundary. If evaluated to true, the server issues an event message containing the signal value to the subscribing client. The boundary operator MUST be one of the values shown in the footer (**).
Examples
{"boundary-op":"gt", "boundary": "5"} // x > 5
{"boundary-op":"eq", "boundary": "5"} // x == 5

Multi Boundary Range

Two boundaries with respective boundary operators are evaluated relative to the current signal value. The logical outcome of the two evaluations are applied as input to a logical AND/OR operation. If evaluated to true, the server issues an event message containing the signal value to the subscribing client. Besides the mandatory "boundary-op", and "boundary" key-value pairs in each JSON object, the first object may contain a "combination-op" key value pair, which then MUST have either the value "AND", or the value "OR". If omitted, the result of the two boundary evaluations is per default applied to an AND operation. The JSON array MUST contain two objects. The boundary operator MUST be one of the values shown in the footer (**).
Examples
[{"boundary-op":"gt", "boundary": "5"},{"boundary-op":"lt", "boundary": "10"}] // x > 5 AND x < 10
[{"boundary-op":"lt", "boundary": "5", "combination-op":"OR"},{"boundary-op":"gt", "boundary": "10"}] // x < 5 OR x > 10

Error Handling

A request addressing multiple nodes may address both valid nodes, and invalid nodes. The latter case shall lead to a Forbidden error (403) response message part that contains information about which node, or nodes, that are invalid. The error response shall not contain data from any of the validly addressed nodes.

Response syntax

A response may contain multiple values, due to either that multiple nodes are addressed, or to that multiple values for one signal is returned. These two reasons can be combined, leading to four different cases.

• Request for a single value from a single node.
• Request for multiple values from a single node.
• Request for a single value from multiple nodes.
• Request for multiple values from multiple nodes.

Response for a single value from a single node:

  "data": {
    "dp": {
      "ts": "Z",
      "value": "Y"
    },
    "path": "X"
  }
                   

Response for multiple values from a single node:

  "data": {
    "dp": [
      {
        "ts": "Z1",
        "value": "Y1"
      },
      {
        "ts": "Zn",
        "value": "Yn"
      }
    ],
    "path": "X"
  }
                

Response for a single value from multiple nodes:

  "data": [
    {
      "dp": {
        "ts": "Z1",
        "value": "Y1"
      },
      "path": "X1"
    },
    {
      "dp": {
        "ts": "Zm",
        "value": "Ym"
      },
      "path": "Xm"
    }
  ]
                

Response for multiple values from multiple nodes:

  "data": [
    {
      "dp": [
        {
          "ts": "Z11",
          "value": "Y11"
        },
        {
          "ts": "Z1n",
          "value": "Y1n"
        }
      ],
      "path": "X1"
    },
    {
      "dp": [
        {
          "ts": "Zm1",
          "value": "Ym1"
        },
        {
          "ts": "Zmn",
          "value": "Ymn"
        }
      ],
      "path": "Xm"
    }
  ]
        

Subscription Event Triggering

A subscription request must always contain a filter operation that describes the trigger event that leads to that the server dispatches an asynchronous event message. For the filter variants "range" or "change", the triggering is dependent on the signal value. When the request addresses multiple signals, the triggering condition shall only be evaluated on one of the signals, which is the first signal in the parameter array of paths. The first path in the array must therefore not contain wildcards to address multiple signals. In this case one of the path addresses in the wildcard expression must be selected as the first array element, which can then be followed by the wildcard expression. The duplicate reference to one signal that this leads to shall be resolved by the server to a singleton in the event messages.

Access Grant Request

The request shall contain the Context and Proof parameters below, the others are optional:

• VIN: The vehicle identification number. Instead of the assigned VIN a generated hash can be used as a pseudo VIN, or any other identity that uniquely links to the vehicle in the access control ecosystem.
• Context: The context associated to the client. The context consists of a triplet of roles for user, app permissions, and device characteristics.
• Proof: A proof mechanism that is used by the client to attest its context to the access grant token server. This is indeed a composed proof for the User role, app permissions, and device characteristics.
• Public key: If this parameter is present, the client will receive a long term access grant token in return.

Depending on the kind of proofs included in the request, the client and the server may need to run an interactive protocol to verify them. The protocol may involve also third parties, such as the ecosystem manager or the resource owner. The protocol is out of scope for this specification.
In scenarios where both the client and the access grant token server are deployed in-vehicle the VIN parameter may be omitted, in all other deployment scenarios it shall be present.

Access Grant Response

The response shall contain the parameter below:

• Access grant token: A signed token with claims needed for the validation of the client request.

An error response shall contain the parameter:

• Error code: The error code shall be informative in order for the client to understand what it needs to correct to become successful.

Access Token Request

The client may have to issue several requests before an access token can be obtained, even in the case of having a valid access grant token. The reason for this is that if consent is required, the ATS will forward the consent request to the External Consent Framework, and it is likely that there will not be an immediate response from the ECF. The ATS will then on the initial access token request respond to the client with a session handle that the client must use in subsequent requests for the access token. When the ATS has obtained a consent reply from the ECF it can thereafter following client inquiry request in the case of a positive consent respond with the access token, or in the case of a negative consent respond with only the negative consent result.

Access Token Response

Protected Resource Request

This is a VISSv3 request including an access token as described in general in the chapter, and for different transport protocols in the [[viss3-transport-examples]] document. The first time a token is submitted in a request it must be provided in its entirety. If a server supports caching of access tokens and returns a token hanle to the client, then any following requests may provide the token handle instead of the complete access token.

Protected Resource Response

This is a VISSv3 response as described in general in the chapter, and for different transport protocols in the [[viss3-transport-examples]] document. It does not differ from the response to an unprotected resource request.

Client

This section is non-normative.
The client is an abstract representation of three sub-actors:

• The device. It is in charge of running the Apps that make requests to the VISSv3 server
• The app. It runs requests on behalf of the user.
• The user. It delegates access rights to the app.

Access Grant Token Server

This section is non-normative.
The access grant token server is in charge of producing access grant tokens to clients.
Depending on the capabilities of the client, the specification supports two types of access grant tokens: Short term and long term access grant tokens.
Long term access grant tokens, are supported for those clients able to run public key cryptographic primitives, i.e. key pair generation and signatures, and is the recommended choice for clients with access to a trusted execution environment where private keys are protected from the regular execution environment. The specification also supports short term access grant tokens that require no extra capabilities in the client, but due to its shorter expiry time it forces the client to contact the access grant token server more often before access token server requests for an access token.
The client request shall contain the following:

• A client context.
• A set of proofs.

• A VIN.

• A public key.

• To verify the client context, and assess that their respective role request can be granted.
• To check that the vehicle represented by the VIN belong to this Ecosystem, and is accessible.
• To create an access grant token.

Access Token Server

This section is non-normative.
The client shall after a successful interaction with the access grant token server request an access token from the access token server. The client request shall contain at least these two parameters below.

• Access grant token.
• Purpose.

• To validate the access grant token.
• To validate that the client context provides permission for the requested purpose.
• To create an access token.

• Signature validation.
• Expiry time check.

Access Control Server

The VISSv3 server MUST support validation of access tokens. The functionality needed for this is decribed in this chapter. This includes validation of at least the following:

• Token signature.
• Token expiry time.

The access token need to be refreshed periodically, which is controlled by the expiry time. If the access grant token that the client used to obtain the now expired access token is not expired, then the client can revisit the access token server with this access grant token to obtain a new access token.
If the access grant token is expired, then the client must obtain a new access grant token first, before revisiting the access token server.
The server SHOULD support caching of a limited number of access tokens. The access token MUST be included in the cache after a first successful request and MUST be removed once they expire. If an access token is cached then the server shall return a token handle of at least 24 bytes long. The client may then use this instead of the complete access token in following requests that require this access token. If the client decides to include the access token handle in a request, the server must then fetch the corresponding access token from the cache, and verify its validity before deciding to grant the request.
The server might decide to remove any token from the cache. In the case this token is then referred to with a token handle the client will get a "401, missing_token" error and will be forced to send the whole access token again. For client requests that are not granted due to access control, the VISSv3 server MUST return one of the error codes shown in the table below.

Resource Owner

This section is non-normative.
The resource owner is typically the owner and/or driver of the vehicle. If Consent is required for granting access to the protected resource, then it should be directed to the resource owner. The process for this is out of scope for this specification.

Ecosystem Manager

This section is non-normative.
The Ecosystem manager is the entity responsible for the functionality of the access control system. This typically includes the management of the access grant token server, and the access token server, the Policy documents, and that there is a PKI domain for the other actors to utilize.

Client Authentication

This section is non-normative.
The three client sub-actors must provide authentication credentials to the access grant token server. This may be certificates that the sub-actors have obtained from a Certificate Authority that is known by the access grant token server. The interactions related to this are out of scope.

Access Grant Token

This section is non-normative.

          {
            "alg": "ES256",
            "typ": "JWT"
          },
          {
            "vin": "vehicle-id",
            "iat": 1609452095,
            "exp": 1609459199,
            "clx": "user+app+dev",
            "aud": "covesa.global/VISSv3",
            "jti": "5967e92e-40e8-5f39-892d-cc0da890db1d"
          }
          

          {
            "alg": "ES256",
            "typ": "JWT"
          },
          {
            "vin": "vehicle-id",
            "iat": 1609452095,
            "exp": 1609459199,
            "clx": "user+app+dev",
            "pub": client_pub_key,
            "aud": "covesa.global/VISSv3",
            "jti": "5967e92e-40e8-5f39-892d-cc0da890db1d"
          }
          

Access Token

Except for the vehicle identity (vin), and client context (clx) claims that are optional, the Access token SHALL have the following claims in header and payload.

          {
            "alg": "HS256",
            "typ": "JWT"
          },
          {
            "vin": "vehicle-id",
            "iat": 1609452095,
            "exp": 1609459199,
            "scp": "PurposeX" || signal-set,
            "clx": "user+app+dev",
            "aud": "covesa.global/VISSv3",
            "jti": "5967e93f-40f9-5f39-893e-cc0da890db2e"
          }
          

Proof of Possession

Long term access grant tokens need to be accompanied by a Proof of Possession (PoP) for the private key corresponding to the public key included in the access grant token. This requirement enables a longer validity for this kind of tokens, ranging from a few days to a even a year. By adding the PoP, an eavesdropper is prevented to reuse an access token request, impersonating the client. Without a PoP, the longer the validity of an access grant token, the higher the risk an attacker could intercept and reuse it. PoP for JWT are defined in [[RFC7800]], but in essence, a PoP enables the requester to proof to the server that it has access to a private key, without disclosing it. Traditionally that would require the server to create a random challenge, or nonce, and ask the client to sign it with its private key. Along with the public key, the server would be able to verify the PoP. This scheme would require an extra step in the protocols, where the client ask for the nonce.

In order to avoid this extra step, the client can generate the nonce itself. The server would need to check that nonces are not reused. Although logging previous nonces at the server side would work for small environments, the use of an incremental nonce in the form of a timestamp is proposed. One of the drawbacks of this proposal is that the server has no means to check whether the PoP has been precomputed or not. However, this is irrelevant from the eavesdropper point of view.

In case freshness of the PoP was a critical requirement, a public source of randomness to obtain the nonce could be used, e.g. Leage of Entropy or Interoperable Randomness Beacons. That would provide the server a mean to check freshness of the PoP but on the other hand, it would require the client to access the public source of randomness every time it needs to create a PoP which is against the main design goals for the long term access grant token.

User Roles

VISSv3 specifies the following minimum set of roles for users:

• OEM
• Dealer
• Independent
• Owner
• Driver
• Passenger

Application Roles

VISSv3 specifies the following minimum set of roles for applications:

• OEM
• Third party

Device Roles

VISSv3 specifies the following minimum set of roles for devices:

• Vehicle
• Nomadic
• Cloud

Purpose List

A client shall provide a purpose as input to a request for an access token. A list of supported purposes needs to exist for a client to select from. The ecosystem manager shall therefore provide means for clients to survey the list to find a purpose that fits its use case.
Each entry in the list contains a short description of the purpose, which is what the client shall provide as input to its request for an access token. 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 client context, 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 access control and consent requirements. The list shall use a JSON format as shown in the example below.

        {"purposes":
            [{"short": "fuel-status",
            "long": "Fuel level and remaining range.",
            "contexts":[{"user":"Independent","app":["OEM", "Third party"], "device":"Cloud"}, {"user":"Owner", "app":"Third party", "device":"Nomadic"}, {"user":"Driver", "app":"OEM", "device":"Vehicle"}],
            "signal_access":
                [{"path": "Vehicle.Powertrain.FuelSystem.Level", "access_permission": "read-only"},
                {"path": "Vehicle.Powertrain.FuelSystem.Range", "access_permission": "read-only"}]
            },
            {}]
        }
        

Scope List

The scope list contains a list of the VSS tree nodes for which access shall be prohibited, per client context. This prohibition is regardless of whether the client has a valid access token or not.
The scope list can also be used to limit the node metadata that is returned on a signal discovery request.
Each entry in the list contains a list of paths to nodes that should be excluded, and a list of the client contexts, i. e. the sub-actor role triplet, for which this exclusion should be made.
The scope list may contain an entry for a context with all three Roles set to "Undefined". The no-access scope of this entry shall then be used for signal discovery requests where no token is included. An entry in the no_access array that addresses a branch results in no access to the subtree of this branch.
The list shall use a JSON format as shown in the example below.

        {"scope":
            [{"contexts":[ { "user":["Driver", "Passenger"], "app":"Third party", "device":"Vehicle"}, { } ],
            "no_access":
                ["Vehicle.Drivetrain.Transmission.Speed",
                "Vehicle.CurrentLocation.Latitude",
                "Vehicle.CurrentLocation.Longitude"]
            },
            {}]
        }