The Vehicle Information Service Specification (VISS) is a service for accessing vehicle information, signals from sensors on control units within a vehicle's network. It exposes this information using a hierarchical tree like taxonomy defined in COVESA Vehicle Signal Specification (VSS). The service provides this information in JSON format. The service may reside in the vehicle, or on servers in the internet with information already brought off the vehicle.
This specification describes a second version of VISS which has been implemented and deployed on production vehicles. It adds major new capabilities and improvements to the earlier version. The first version of VISS only supported WebSocket as a transport protocol, the second version is generalized to work across different protocols as some are better suited for different use cases. HTTP and MQTT are now supported with additional protocols used within the automotive industry being evaluated for inclusion. Subscription capabilities have been improved and access control has been added.
There are two parts to this specification, CORE and [[viss2-transport]]. This document, the VISS version 2 CORE specification, describes the VISSv2 messaging layer. The companion specification for the VISSv2 transport protocols detail the mapping of the messaging layer to selected transports. The ontologies based on the VISSv2 core specification are defined in documents for each specific domain (e.g. navigation, media, vehicle data).
This document describes the messaging API for VISS protocol. This includes the messaging layer and set of rules for structuring data. The separation between payload encoding ([[viss2-transport]]) and messaging API (CORE) improves adaptability. Extending and describing multiple transport protocols becomes possible.
The messages are exchanged between a server implementation holding the representation of data and a client using the data.
The VISSv2 messaging layer uses a RESTful design for all methods exchanged via the interface ().
The VISSv2 data structuring rules (VSS Rule set) are the same through all transport protocols. The basis for structuring data hold by a server is a tree.
The acronym 'VISSv2' is used to refer to this document, the VISS version 2 specification. The acronym 'VSS' is used to refer to the 'Vehicle Signal Specification' which is hosted by COVESA. The term 'WebSocket' when used in this document, is as defined in the W3C WebSocket API and [[RFC6455]], the WebSocket Protocol.
The service is intended for use with a tree-like logical taxonomy to represent the vehicle data.
An illustrative example of such a tree structure is shown in Figure 1.
While it is meant to support conforming taxonomies it was created principally with the
Vehicle Signal Specification (VSS) in mind.
For more details, see the VSS documentation.
Depending on how VISS is being used, for instance to serve data already off-boarded and residing in the cloud,
it may make sense to allow sensor values to be updated by sending a 'set' request.
When VISS is directly on the vehicle, values reported by sensors are authoritative and should be read-only within VISS.
Implementations should handle set requests appropriately for their situation and give appropriate success or error responses accordingly.
Addressing of resources is done using URIs as defined in [[RFC3987]].
scheme://authority/path?queryThe scheme describes the protocol to use to reach the addressed resource. For supported protocols, see the transport protocols in [[viss2-transport]] specification.
The path URI component definition differs between the three resources.
For the VISSv2 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".
A single data point is in the message payload represented by a value and an associated timestamp,
in JSON represented by two key-value pairs with the key names "value" and "ts".
The "ts" value MUST be a string as specified in , while the "value" value MUST be a string,
an array of strings for array type signals, or an object for complex datatypes,
see VSS Data Types.
In the case of the value being a number, it MUST follow the number formats as specified in [[RFC8259]].
A boolean value is represented by "true" or "false".
In the case of the value being a complex datatype represented by a struct, it is represented as a JSON object as shown below.
A struct with the following declaration
struct {
field1 datatype
field2 datatype
}
is represented by the following JSON objectThis chapter describes the different methods and its arguments that govern the communication between a client and the server.
The transport protocols used to implement these methods MUST implement the Read and Update methods, and MAY implement the Subscribe, Unsubscribe, and Subscription methods.
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:
Success response, of which authorization is optional:
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:
Success response, of which authorization is optional:
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:
Success response, of which authorization is optional:
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:
Success response:
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:
The server MUST inform a client about errors ocurring in interactions between the two, whether it is in a synchronous error response, or an asynchronous error event as a result of a previous subscribe. For transport protocols which do not control the logical linking between request and response messages it may not be possible to link an error message to the correct client request. In cases like this the server may omit sending an error message. The error message has three arguments, of which subscriptionId is mandatory only for error events. In the case of an error event being issued by the server, the associated subscription session SHALL thereafter be terminated by the server.
Arguments:
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.
Timestamps in transport payloads MUST conform to the [[ISO8601]] standard, using the UTC format with a trailing Z.
Time resolution SHALL at least be seconds, with subsecond resolution as an optional degree of precision when desired.
The time and date format shall be as shown below, where the sub-second data and delimiter is optional.
YYYY-MM-DDTHH:MM:SS.ssssssZ
The exception to this is timestamps within tokens, which MUST conform to Unix time.
Transport protocols supported by this specification MUST make use of TLS v1.2 as defined in [[RFC5246]].
The makes it possible to apply restrictions on the data access for clients that are granted access on the transport protocol level.
In addition to some privacy provisions within the specification itself, the W3C Automotive Working Group is creating an accompanying In-Vehicle Application Best Practices document to provide further considerations for handling of information. These Best Practices go beyond the narrow scope of this specification and addresses several of the concerns for the broader telematics ecosystems it is a part of. These practices include reducing ability to fingerprint an individual or vehicle from its data, providing data use consent, revokation, integrity and use audit accountability.
For some uses, such as when information is only referenced within the vehicle not sent off nor persisting between restarts, there should be little to no privacy concerns.
This specification, unlike its predecessor, has granular access control capabilities to limit what information an application may access. All information sent from a VISS service to client application must be transported over an encrypted protocol to help protect privacy.
For an application to be installed and permitted to run on a vehicle it should have consent from whoever is deemed authoritative for a given jurisdiction and ownership situation. That consent should be revocable. Consent and revoking it are outside the scope of this specification, it is expected to be handled out of band and in some cases by regulations and contractual commitments. Future version of this specification however may provide mechanism for enabling and suspending application authorization to access information.
Filtering is a mechanism to refine a client request, in order to more precisely control what is returned in a response. Filtering can be applied in read requests and in subscribe requests. A request where filtering is applied has the following structure
The paths filter operation is used when a single request is used to retrieve signal data from multiple data points in the VSS tree.
The vsspath shall point to the last node in the tree that is common for the relative paths in the filter parameter object,
that start off from this node.
If the end point of a path in the filter value is a branch, then all leaf nodes in the sub-tree below this branch are addressed.
A path in the filter value may contain the wildcard character (*) as a representative for a single path segment.
Every path element in an value array must address at least one node in the tree, or else an error response is returned.
Different elements of the value array may address the same node,
in which case it is the responsibility of the server to resolve this to a singleton in the event messages.
Examples can be found in the search read on HTTPS and
search read on WebSocket in [[viss2-transport]] specification.
The server typically have access only to the latest, most fresh data point representing a signal.
However, it may for various reasons at least temporarily have access to also older data points.
A scenario where this could occur is when a vehicle temporarily loses its connectivity,
maybe because it enters into a tunnel. Assuming that the vehicle detects the loss of connectivity, it may then start to record data.
If recorded, this data may then be accessed using the history type.
The vehicle system makes its own decision whether to record any data, and for how long this data will be kept in storage.
The period in the filter expression goes from current time, excluding the current value, and backwards in time.
The number of data points in the response depends on the period size, and the sample frequency.
The latter can not be set by the client,
so the client should have some understanding of its value to estimate the amount of data it may receive.
A request for historic data will return a Not found error (404) if historic data is unavailable.
The period must conform to the [[ISO8601]] duration format, expressed with days, hour, minute,
and second data, i. e. "parameter": "PdddDThhHmmMssS".
The number of days shall be less than 999. Only a single period can be expressed.
Examples can be found in the history read on HTTPS and
history read on WebSocket in [[viss2-transport]] specification.
The parameter object contains the period time X in between captures, {"period":"X"}. X is an integer and represents the period time in milliseconds. Example can be found in the subscribe section in [[viss2-transport]] specification.
The range filter operation supports two types of ranges, see the following sub chapters.
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 (**).
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 (**).
Single Boundary Range
Examples
{"boundary-op":"gt", "boundary": "5"} // x > 5
{"boundary-op":"eq", "boundary": "5"} // x == 5
Multi Boundary Range
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
Examples can be found in the authorized subscribe and
range subscribe in [[viss2-transport]] specification.
The parameter object contains the logical operator for comparison of previous and current values, {"logic-op":"X", "diff":"Y"},
where X is one of the supported logical operators (**), and Y is the value of the required change.
For boolean values the following expressions shall be supported:
"parameter":{"logic-op":"gt", "diff": "0"} This leads to a trigger event when the value goes false->true.
"parameter":{"logic-op":"lt", "diff": "0"} This leads to a trigger event when the value goes true->false.
"parameter":{"logic-op":"ne", "diff": "0"} This leads to a trigger event when the value goes true->false OR false->true.
(**)The supported logic operators are ["eq", "ne", "gt", "gte", "lt", "lte"],
where "eq" is "equal", "ne" is "not equal", "gt" is "greater than", "gte" is "greater than or equal",
"lt" is "less than", "lte" is "less than or equal".
Example can be found in the Change Subscribe
in [[viss2-transport]] specification.
The parameter object contains the maximum error limit, and the buffer size, {"maxerr": "X", "bufsize":"Y"},
where X is a float value setting the max allowed error between any data sample and the simplified curve,
and Y is the number of buffer elements. Data is processed when the buffer becomes full,
and the essential data points are returned as a time series per signal.
Example can be found in the curve logging subscribe
in [[viss2-transport]] specification.
The static metadata request is used when the client instead of the data associated to VSS node(s)
wants to retrieve meta data associated to the VSS node(s).
The metadata is retrieved from the VSS tree that is deployed in the vehicle.
This type of request is sometimes referred to as a signal discovery request.
If the "parameter" object contains an empty string, then all metadata that the server can retrieve for the for the addressed node(s) are returned,
while if it contains a metadata key name, or an array of key names, then only the selected metadata is returned.
For the set of static metadata key names,
see the Vehicle Signal Specification.
The vsspath in the request may point to either a leaf node, or to a branch node.
In the latter case then the response will contain static metadata from the entire sub-tree having this branch as the root.
A static metadata request can be combined with a paths filter operation to address multiple nodes,
but cannot be combined with any other filter type.
The response is a JSON formatted object with corresponding key-value pairs per addressed node.
The server MAY support the static metadata request.
Example can be found in the signal discovery read on HTTPS in [[viss2-transport]] specification.
Dynamic metadata requests are used when the client instead of the data associated to VSS node(s) wants to
retrieve metadata that is additional to the VSS specification.
The dynamic metadata may change over time.
The request filter "parameter" object MUST only contain one of the metadata key names from the list of dynamic metadata key names below.
The filtering operations may be used to address multiple tree nodes in one request. This may lead to specific issues in certain situations, as described below.
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.
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.
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" } ]In the case of a request for multiple values from multiple nodes, the datapoint for different paths may contain single or multiple objects, as the vehicle system may not have multiple values recorded for all requested signals.
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 types "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 control MUST be supported. However, in this chapter only the sections that describe the interactions between the
client and the VISSv2 server are mandatory.
Access control SHALL not be applied to the VSS nodes containing the VSS version data,
and not to client requests for dynamic metadata about the server capabilities,
or about the access control selection tags applied to the VSS tree.
This section is non-normative.
The VISSv2 access control model is inspired by the concepts of OAuth2.0 [[RFC6749]],
but some deviations exist as is described in the following chapters.
Four actors are defined:
Client
An application making protected and authorized resource requests on behalf of its
user.
Access grant token server
The server issuing the Access Grant credential after successfully authenticating the client.
Access token server
The server issuing the access token to the client
after successfully validating the request and obtaining authorization.
VISSv2 server
The server hosting the protected resources, capable of accepting and responding to protected resource requests using
access tokens.
The abstract protocol flow illustrated in the figure below describes the interaction between the four actors.
Besides the four actors directly involved in the abstract flow, there are two more actors.
Resource owner
This is typically the driver of the vehicle, who may be asked for consent before access is granted.
Ecosystem manager
The entity managing the access control ecosystem. It controls the Policy documents,
and manages the PKI ecosystem that the other actors may utilize.
The abstract protocol flow is implemented by two different flows, as will be described in the following chapters.
The process to obtain the credentials needed for client authentication is out-of-scope,
as well as the installation procedures for the applications.
This section is non-normative.
Two different flows are described. Which flow to use depends on the capabilities of the client.
If a client is able to run public key cryptographic primitives,
i.e. key pair generation and signatures,
and has access to some kind of trusted execution environment where private keys are protected from the regular execution environment,
then it can use the long term flow. Clients that do not have access to these capabilities,
or do not want to use them, must select the short term flow.
The advantage of using the long term flow is that the client can be trusted with longer expiry times of
access grant tokens.
In the short term flow the client must due to a shorter expiry time contact the
access grant token server more often to obtain a new
access grant token.
A client selects the type of flow by either submitting a public key in the
access grant request, or not. The latter leading to an short term flow.
The request shall contain the Context and Proof parameters below, the others are optional:
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.
The response shall contain the parameter below:
An error response shall contain the parameter:
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.
The request shall contain at least these two parameters below:
Initial Access Token Request
Short term access grant tokens can be used as direct input to the
access token server, but long term access grant tokens
should be accompanied by a proof of possession (PoP)
for the private key corresponding to the public key included in the token.
The access token server acts as a Policy Enforcement Point, making decisions on whether to grant access to the protected resource based on the provided access grant token and purpose.
This request can be issued by the client after a session handle has been received in a response to an initial access token request.
The request shall contain at least the parameter below:
In the case that the access control is not combined with a requirement for obtaining consent from the data owner,
an immediate response is possible, and in the case of a successful response it shall contain the parameter:
Access Token Response Consent Not Required
An error response shall contain the parameter:
In the case that the access control is combined with a requirement for obtaining consent from the data owner,
an immediate response is not possible, and the response to an initial access token request shall contain the parameter:
Access Token Response To Initial Access Token Request
There are three different responses possible to an inquiry access token request.
In the case that there is still no consent reply available from the ECF, the response is identical to the response to the initial access token response, see above.
In the case that there is a negative consent reply from the ECF, the response shall contain the parameter:
This is a VISSv2 request including an access token as described in general in the chapter, and for different transport protocols in the [[viss2-transport]] 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.
This is a VISSv2 response as described in general in the chapter, and for different transport protocols in the [[viss2-transport]] document. This is a VISSv2 response that optionally may include an access token handle.
This section is non-normative.
The client is an abstract representation of three sub-actors:
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:
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.
The VISSv2 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:
Permission | read-only | read-write |
---|---|---|
get set subscribe |
||
Ok | Ok | |
Nok | Ok | |
Ok | Ok |
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 VISSv2 server MUST return one of the error codes shown in the table below.
Error Number (Code) | Error Reason | Error Message |
---|---|---|
401 (Unauthorized) | missing_token | One or more of the requested signals are access controlled, an access token or its jti, must be included in the request. |
406 (Not Acceptable) | invalid_token | In case the request included an access token, a fresh one must be obtained. In case the request included just the jti, the whole access token needs to be send again. |
406 (Not Acceptable) | insufficient_priviledges | The priviledges represented by the access token are not sufficient. |
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.
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.
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.
This section is non-normative.
The short term access grant token shall have the following claims in header and payload,
where all but the vehicle identity (vin) claim are mandatory.
{ "alg": "ES256", "typ": "JWT" }, { "vin": "vehicle-id", "iat": 1609452095, "exp": 1609459199, "clx": "user+app+dev", "aud": "w3.org/VISSv2", "jti": "5967e92e-40e8-5f39-892d-cc0da890db1d" }The algorithm (alg) claim shall be set to a valid RSA or ECDSA algorithms according to [[RFC7518]].
Except for the vehicle identity (vin) claim that is optional,
the long term access grant token SHALL have the following claims in header and payload.
{ "alg": "ES256", "typ": "JWT" }, { "vin": "vehicle-id", "iat": 1609452095, "exp": 1609459199, "clx": "user+app+dev", "pub": client_pub_key, "aud": "w3.org/VISSv2", "jti": "5967e92e-40e8-5f39-892d-cc0da890db1d" }The algorithm (alg) claim shall be set to a valid RSA or ECDSA algorithms according to [[RFC7518]].
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": "w3.org/VISSv2", "jti": "5967e93f-40f9-5f39-893e-cc0da890db2e" }The algorithm (alg) claim shall be set to any valid algorithms according to [[RFC7518]].
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.
This section is non-normative.
The client context contains a client actor that is characterized by three subactors:
VISSv2 specifies the following minimum set of roles for users:
VISSv2 specifies the following minimum set of roles for applications:
VISSv2 specifies the following minimum set of roles for devices:
This section is non-normative.
The Policy documents are typically owned and created by the ecosystem manager.
They need to be handled securely to protect their integrity.
The ecosystem manager shall securely provision them to the
access token servers in the access control ecosystem.
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"}]
},
{}]
}
The purpose list shall be securely provisioned to the access token server.
The protocol for this is out-of-scope.
The access token server must reject all requests for access tokens
if it is not in possession of a purpose 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"]
},
{}]
}
The scope list shall be securely provisioned to the access token server.
The protocol for this is out-of-scope.
The access token server shall not restrict the scope for any
client context if it is not in possession of a scope list.
This section is non-normative.
This chapter describes a complementary functionality to the access control model, the ability to apply it selectively to parts of the tree.
It can be used in cases where not all nodes of the tree are believed to require access control,
or where write-only validation is sufficient instead of read-write validation for certain nodes.
This functionality requires that the access token specifies whether the access permission granted to the
client to a signal is read-only, or read-write.
It also requires that the metadata for the node in the VSS tree contains data specifying whether
the access control verification should be carried out only for write request, or for both read and write requests.
The former requirement is realized as described in earlier chapters by that the access token
scope claim links to a purpose where the signals and their respective access permission are found.
The latter requirement is realized by adding to nodes in the VSS tree the key-value pair "validate":'access-control-mode',
where 'access-control-mode' is either the string "write-only", or "read-write".
The figure above shows an example where both read and write requests to the three leftmost leaf nodes will be access controlled,
while the two rightmost leaf nodes only will be access controlled for write requests.
An inheritance rule leads to that any nodes below a tagged node are assigned the same access control, if they are untagged.
This metadata is not likely to be applied to the standardised VSS tree,
as different implementers of this standard may have different views on which nodes to apply it to.
Instead it is anticipated that it is applied at a "deployment" stage, possibly using the VSS layering concept.
The inheritance model, which says that if access-control-mode data is added to a node,
then all nodes in the subtree for which this node is the root inherits the setting,
unless there is access-control-mode data added to any node in this subtree,
makes possible a reduction of the number of nodes this metadata have to be added to.
This allows for example an entire VSS tree to be assigned an access-control-mode by merely applying it in the root of the tree.
The figure below shows an overview of the access control selection model,
and a table showing the required access control tagging of a node for the VISSv2 server to grant the requested access.
If the VSS tree used by a VISSv2 server contains access control selection tags,
then the server MUST support their usage as described in this chapter.
If it is not used, then a server may implement access control for the entire tree.
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 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.
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,
event based update, consent status removal.
The consent status can be set to any of the following values:
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 data shown in the table above. This communication shall be carried out using a secure channel (e.g. TLS).
On receiving a dynamic-metadata request on server capabilities the server SHALL respond with a JSON object that for each of the keys
in the list below contains the associated values in the list that the server supports.
Both the keys and the values are represented as strings, if a key has more than one value, these are represented as an array.
A key name refers to a functional domain of the specification, and the tables below contain the capabilities of these domains.
The ones marked as underlined are mandatory, the others are optional.
Key name | Description |
---|---|
filter | |
access_ctrl | |
transport_protocol | [[viss2-transport]], Transport Protocols chapter |
filter | Description |
---|---|
timebased | |
change | |
paths | |
range | |
curvelog | |
history | |
static_metadata | |
dynamic_metadata |
access_ctrl | Description |
---|---|
short_term | |
long_term | |
signalset_claim |
transport_protocol | Description |
---|---|
https | [[viss2-transport]], Transport Protocols:HTTPS chapter |
wss | [[viss2-transport]], Transport Protocols:Secure Websocket chapter |
mqtts | [[viss2-transport]], Transport Protocols:MQTT chapter |