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 of 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". Mixing 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 accessing the requested values. If the server successfully processes the request, it MUST return a success response. If the server fails to fulfill the request, then the server MUST return an error message.

Arguments, of which path is mandatory:

• path The VSS-defined path to a node in the VSS tree.
• filter Additional parameters to refine the requested data.
• authorization The authorization token.
• data compression The compression scheme(s) used for transmitted data.

Success response, of which authorization is optional:

• data A structure containing one or more sets of a path and data point.
• path The VSS-defined path for the associated data point.
• data point A structure containing one or more value-timestamp tuples.
• 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 server execution time of the request.

Update

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

The client MAY have to obtain an authorization token before updating a vehicle signal. If the server successfully processes the request, it MUST return a success response. If it cannot, 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 VSS-defined path to a leaf node in the VSS tree.
• value The new value to update the vehicle signal at the specified path.
• authorization The authorization token.

Success response, of which authorization is optional:

• authorization A handle representing the authorization token.
• timestamp The server execution time of the request. 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 conditions for these events are determined by the filter rules.

The client MAY have to obtain an authorization token before subscribing to vehicle signal(s). The server MUST issue an event message if a trigger rule is met. If the server successfully processes the request, it MUST return a success response. If the server fails to fulfill the request, then the server MUST return an error message. If an error occurs during the subscription period, the server SHOULD return an error message.

Arguments, of which path and filter are mandatory:

• path The VSS-defined path to a node in the VSS tree.
• filter A rule set defining the triggering criteria for asynchronous event messages.
• authorization The authorization token.
• data compression The compression scheme(s) used for transmitted data.

Success response, of which authorization is optional:

• authorization A handle representing the authorization token.
• subscriptionId A unique identifier for the subscription session.
• timestamp The start time for the subscription period.

Unsubscribe

Purpose: Terminates a subscription that was previously established through a subscribe request.

If the server successfully processes the request, it MUST return a success response, and it MUST stop issuing event messages associated to the subscription handle. If the server fails to fulfill the request, then the server MUST return an error message.

Arguments, of which subscriptionId is mandatory:

• subscriptionId A unique identifier for the subscription session.

Success response:

• timestamp The time at which the subscription was terminated.

Subscription

Purpose: Sends asynchronous event messages to the client when a subscribe request trigger rule is met.

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 message and terminate the subscription.

Arguments, of which all are mandatory:

• subscriptionId A unique identifier for the subscription session.
• data A structure containing one or more sets of a path and data point.
• path The VSS-defined path for the associated data point.
• data point A structure containing one or more value-timestamp tuples.
• value The current value associated with the filter expression.
• timestamp The capture time of the value.
• timestamp The server execution time of the subscription event.

Error Information

The error information consists of three components: number, reason, and description. All the three components MUST be part of the error information.

• number Refer to the status codes defined in [[TRANSPORT]].
• reason Refer to the status codes defined in [[TRANSPORT]].
• description Refer to the status codes defined in [[TRANSPORT]].

Single Boundary Range

A single "boundary operator" evaluates the current signal value relative to a single boundary. If the condition evaluates to true, the server MUST issue an event message containing the signal value to the subscribing client. The boundary operator MUST be one of the values listed in the footer (**).
Examples
{"logic-op":"gt", "boundary": "5"} // x > 5
{"logic-op":"eq", "boundary": "5"} // x == 5

Multi Boundary Range

A multi boundary range evaluates the current signal value relative to two boundaries. The logical outcome of the two evaluations are applied as input to a logical AND/OR operation. If the condition evaluates to true, the server MUST issue an event message containing the signal value to the subscribing client. In addition to the mandatory "logic-op" and "boundary" key-value pairs in each JSON object, the first object MAY include an optional "combination-op" key-value pair, which MUST have either the value "AND" or "OR". If omitted, the result of the two boundary evaluations SHALL default to an AND operation. The JSON array MUST contain two objects. The boundary operator MUST be one of the values listed in the footer (**).
Examples
[{"logic-op":"gt", "boundary": "5"},{"logic-op":"lt", "boundary": "10"}] // x > 5 AND x < 10
[{"logic-op":"lt", "boundary": "5", "combination-op":"OR"},{"logic-op":"gt", "boundary": "10"}] // x < 5 OR x > 10

Error Handling

Error messages for multiple-signal requests are handled the same way as for single-signal requests, except when one or more signals are temporarily unavailable. In such cases, the server MAY use in-line error reporting, see In-line Error Reporting in [[TRANSPORT]] specification.

Response syntax

A response MAY contain multiple values, due to either that multiple nodes were addressed or that multiple values for one signal are 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 include a filter operation that defines the trigger event causing the server to dispatch an asynchronous event message. For "range" and "change" filter variants, triggering depends on the signal value. When a request addresses multiple signals, the triggering condition SHALL be evaluated for only one signal, specifically the first signal in the paths parameter array. The first path in the array MUST NOT contain wildcards, as it determines the triggering signal. If a wildcard expression is used, one of the resolved path addresses MUST be explicitly selected as the first array element, followed by the wildcard expression. If this results in a duplicate reference to the same signal, the server SHALL resolve it into a singleton in the event messages.

Access Grant Request

The request SHALL contain the Context and Proof parameters listed below. The other parameters are optional:

• VIN: The vehicle identification number. Instead of the assigned VIN, a generated hash may be used as a pseudo-VIN, or any other unique identifier that links the vehicle within the access control ecosystem.
• Context: The context associated with the client, consisting of three key roles: user roles, application roles, and device roles.
• Proof: A verification mechanism used by the client to prove its context to the Access Grant Token Server. This is a composite proof that includes user roles, application roles, and device roles.
• Public key: If this parameter is present, the client will receive a long-term Access Grant Token in return.

Depending on the type of proofs included in the request, the client and the server MAY need to run an interactive protocol to verify them. The protocol MAY also involve third parties, such as the ecosystem manager or the resource owner. The verification protocol itself is out of scope for this specification.
In scenarios where both the client and the Access Grant Token Server are deployed inside the vehicle, the VIN parameter MAY be omitted. In all other deployment scenarios, the VIN parameter SHALL be included.

Access Grant Response

The response SHALL contain the parameter below:

• Access Grant Token: A signed token that includes claims required to validate the client request.

If the request fails, the response SHALL contain the following parameter:

• Error code: A error code that provides the client with clear guidance on what must be corrected for the request to succeed.

Access Token Request

The client may need to send multiple requests before receiving an access token, even when a valid Access Grant Token is available. This is because, if consent is required, the Access Token Server (ATS) will forward the consent request to the External Consent Framework (ECF), and an immediate response from the ECF may not be available. In such cases, the ATS will respond to the initial access token request with a session handle, which the client MUST use in subsequent requests for the access token. Once the ATS receives a response from the ECF, it will process the client’s follow-up request in one of two ways:

• If consent is granted, the ATS will return the access token.
• If consent is denied, the ATS will return a response indicating the negative consent result only.

Access Token Response

Protected Resource Request

This is a VISSv3 request including an access token as described in general in the Chapter 5.1 Methods, and in detail for various transport protocols in the [[TRANSPORT]] document. The first time a token is submitted in a request, it MUST be included in full. If the server supports access token caching and returns a token handle to the client, then subsequent requests MAY use the token handle instead of the complete access token.

Protected Resource Response

This is a VISSv3 response as described in general in the Chapter 5.1 Methods, and in detail for various transport protocols in the [[TRANSPORT]] document. It is identical to the response for an unprotected resource request, with no differences in structure or content.

Client

The client is an abstract representation of three sub-actors:

• Device: It is responsible for running the applications that make requests to the VISSv3 server.
• Application: It runs requests on behalf of the user.
• User: It delegates access rights to the application.

Access Grant Token Server

The Access Grant Token Server is responsible for issuing access grant tokens to clients.
Depending on the capabilities of the client, the specification supports two types of access grant tokens as short-term and long-term access grant tokens.
Long-term access grant tokens, are recommended for clients that support public key cryptographic primitives (e.g., key pair generation and digital signatures), and that have access to a trusted execution environment (TEE) where private keys are securely protected from the regular execution environment. Short-term access grant tokens are intended for clients without such cryptographic capabilities. However, due to their shorter expiry times, they require the client to contact the Access Grant Token Server more frequently when requesting an access token from the Access Token Server.

A client request to the Access Grant Token Server SHALL contain:

• A client context.
• A set of proofs.
• A VIN(Vehicle Identification Number).
• If the client and the Access Grant Token Server are both deployed in-vehicle, the VIN MAY be omitted.
• In all other cases, the VIN SHALL be included.
• When the VIN is included in the request, the vehicle identity (vin) claim SHALL be present in the resulting access grant token.

• A public key.
• The public key MUST be generated by client, and the associated private key MUST be securely controlled by the client.

• Verifying the client context, and determining if the requested roles can be granted.
• Validating that the vehicle identified by the VIN belongs to the ecosystem and is accessible.
• Issuing the access grant token.

Access Token Server

After a successful interaction with the Access Grant Token Server, the client SHALL request an access token from the Access Token Server. The client request SHALL include at least the following two parameters:

• Access grant token.
• Purpose.

• Validating the the access grant token.
• Verifying that the client context is authorized for the requested purpose.
• Creating and issuing the access token.

• Signature verification (using the public key of the Access Grant Token Server).
• Expiry time check.

Access Control Server

The VISSv3 server MUST support validation of access tokens. The functionality required for this validation is described in this chapter. This includes, at a minimum, validation of the following elements:

• Token signature.
• Token expiry time.

• If the scope claim of the access token contains a purpose short-name, successful validation requires that all the nodes addressed by the path in the request MUST be matched by the paths associated with the purpose in the purpose list .
• If the scope claim of the access token contains a explicit list of signals, successful validation requires that all the nodes addressed by the path in the request MUST be matched by the one of the signals included in the token.
  

• MAC address checks.
• message round-trip measurements.

The access token needs to be refreshed periodically, which is determined by the expiry time. If the access grant token that the client originally used to obtain the now-expired access token is still valid, then the client can revisit the access token server with this access grant token to obtain a new access token.
However, if the access grant token is also 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 added to the cache after a first successful request and it 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 MAY decide to remove any token from the cache at any time. If the client later references a removed token using its handle, the server WILL return a "401, invalid_token" error, and the client MUST resend the whole access token.
For any client request denied due to access control, the VISSv3 server MUST return a "401, invalid_token" error message.

Resource Owner

The resource owner is typically the owner and/or driver of the vehicle. If consent is required to grant access to the protected resource, then the request SHOULD be directed to the resource owner. The process of obtaining consent is out of scope for this specification.

Ecosystem Manager

The Ecosystem manager is the entity responsible for managing the access control system. This typically includes managing the Access Grant Token Server, and the Access Token Server, maintaining the Policy documents, and ensuring that a PKI domain is available for use by other actors in the ecosystem. .

Client Authentication

The three client sub-actors must provide authentication credentials to the Access Grant Token Server. These credentials MAY be certificates issued by a Certificate Authority (CA) recognized by Access Grant Token Server.
The details of these interactions are out of scope for this specification.

Access Grant Token

          {
            "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, which are optional, the Access token SHALL include the following claims in both the header and the 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"
          }
          

• The alg (algorithm) claim SHALL be set to a valid algorithms according to [[RFC7518]].
• The typ (type) claim SHALL be set to "JWT".
• The vin (vehicle identity) claim MAY be present or not, depending on input to the Access Grant Token Server.
• The iat (issued at) claim SHALL be set to the Unix timestamp representing the token’s issuance time.
• The exp (expiry) claim SHALL be set to the Unix timestamp when the token expires.
• The scp (scope) claim SHALL be set to either a purpose list short name, which logically links to the signal scope as defined in the purpose list, or to a set of signals that the token permits access to. Each signal is defined as a JSON object containing the signal path, and the signal permission as shown below.
  {"path":"vss-path", "access_permission":"permission"}
  If the scope claim is set to a purpose, the client context claim MUST be present in the token.
• The clx (Client context) SHALL be set to the client’s assigned role triplet (user, app, device), with each role separated by a plus sign (+).
• The aud (audience) claim SHALL be set to the URL: "covesa.global/VISSv3".
• The jti (JSON Web Token identity) claim SHALL be set to an unguessable UUID that is unique within the domain controlled by the ecosystem manager.

Proof of Possession

Long-term access grant tokens MUST 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 several 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]]. In essence, PoP enables the requester to proof to the server that it has access to a private key, without disclosing it. Traditionally, this is done by the server generating 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.

To avoid this extra step, the client MAY generate the nonce itself. In this case, the server must ensure that nonces are not reused. While logging previously used nonces on the server may work in small-scale environments, a more scalable approach is to use an incremental nonce based on a timestamp. 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.

If PoP freshness is a critical requirement, the nonce could be derived from a public source of randomness, such as the 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 defines the following minimum set of roles for applications:

• OEM
• Third party

Device Roles

VISSv3 defines the following minimum set of roles for devices:

• Vehicle
• Nomadic
• Cloud

Purpose List

A client SHALL provide a purpose as input when requesting an access token. To support this, a predefined list of supported purposes MUST exist, allowing the client to select the purpose that matches its use case. The ecosystem manager SHALL provide a mechanism for clients to access and review this list.
Each entry in the purpose list includes the following:

• A short description of the purpose, which the client uses as input when requesting an access token.
• A long description, which MAY be used in consent dialogs when applicable.
• A list of valid client context (i.e., combinations of user, app, and device roles) that may be granted access for this purpose.
• A list of signals accessible under this purpose, along with the associated access permissions and any consent requirements.

        {"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 defines the VSS tree nodes to which access SHALL be prohibited for specific client context, regardless of whether the client possesses a valid access token.
In addition to access control, the scope list MAY also be used to restrict metadata visibility when a client sends a signal discovery request.
Each entry in the list contains:

• A list of node paths to be excluded, and
• A list of client contexts (i.e., sub-actor role triplets) for which this exclusion applies.

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