Dynamic Registry

To enable e. g. after-market services it SHALL be possible to dynamically add new branches to the VSS tree, and if requested also to delete them at a later point.
Requests of this type are not expected to be frequent for the type of data that is represented in the "vehicle signal domain", which is the current scope of VSS. These requests are therefore partitioned in a separate API, which is described in "Appendix: Dynamic registry API".

Service Discovery Filter

The service discovery query has the structure
$spec EQ depth
where
- $spec is the reserved word for service discovery filtering.
- the equal sign (EQ) is the only allowed comparison operator for service discovery filtering.
- depth sets the maximum branch depth that is returned in the response, counted from the root node given by the path component in the request. Depth MUST be a positive integer. If set to zero, it is replaced by the max depth of the subtree.

Search Filter

If the path in a read request does not terminate in a leaf node, then the response will contain values from all leaf nodes in the subtree given by the path. The search filter makes it possible to tailor a subset of this response. The search query has the structure
$path EQ search-expression
where
- $path is the reserved word for search filtering.
- the equal sign (EQ) is the only allowed comparison operator for search filtering.
- search-expression is a path expression that may contain the wildcard character (*) for representation of an unknown node name.

The search-expression is relative to the root node given by the path component in the request. An example could be "*/*/isOpen", which, preceded with a slash, and concatenated with the request root-path "Vehicle/Cabin/Door" would generate the absolute search expression "Vehicle/Cabin/Door/*/*/isOpen", in which case the response would contain all values from the isOpen nodes in that subtree, but not from the other possible leaf nodes in it.

The search filter can be used also in subscribe requests, see chapter .
The response message on a request addressing multiple signals contains all the matching signal values. Notifications from a subscription addressing multiple signals contain one signal value per notification.

Data Value Filter

If a request, typically when it is addressing a subtree, is only interested in response data with a specific value, then a data value filter can be used. The data value query has the structure
$data comparison-operator value
where
- $data is the reserved word for data value filtering.
- comparison-operator is one of either the equal sign (EQ), the greater than sign (GT), or the less than sign (LT).
- value is a number following Javascript syntax rules, or a boolean value.

If the data type of the value-expression is different from the data type of the node matching the path, then an error response is returned.

Interval Filter

An interval filter is used in a subscribe request when the client wants subscription notifications to be issued by the server at a regular time interval. The interval query has the structure
$interval EQ value
where
- $interval is the reserved word for interval filtering.
- the equal sign (EQ) is the only allowed comparison operator for interval filtering.
- value is an integer value in milliseconds representing the interval between issued notifications.

Range Filter

A range filter is used when the client wants subscription notifications to be issued by the server when a value enters/exits the defined range. The range query has the structure
$range comparison-operator value
where
- $range is the reserved word for range filtering.
- comparison-operator is one of either the greater than sign (GT), or the less than sign (LT).
- value is a number following Javascript syntax rules.

Change Filter

A change filter is used when the client wants subscription notifications to be issued by the server when a value has changed more than a defined value since last notification. The change query has the structure
$change comparison-operator value
where
- $change is the reserved word for change filtering.
- comparison-operator is one of either the greater than sign (GT), or the not equal sign (NEQ).
- value is a number following Javascript syntax rules.

When using the not equal comparison operator it MUST have the value zero, all other values lead to an error response. The usage is interpreted as "for any change", and also supports boolean changes.

Access Grant Request

The request shall contain the first three parameters below, the last is optional:

• VIN: The vehicle identification number. This may be 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 AG 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.

Access Grant Response

The response shall contain the parameter below:

• AG 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 request shall contain at least these two parameters below:

• AG token: A signed token with claims needed for the validation of the Client request.
• Purpose: The Purpose shall be one of the short text entries from the .

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 AG Token and Purpose.

Access Token Response

A successful response shall contain the parameter:

• Access token: The Access token to be used in Client requests to the Gen2 server for Protected Resources.

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

Protected Resource Request

This is the Gen2 request including an Access token that is described in general in the chapter, and for different transport protocols in the Gen2 CORE document.

Protected Resource Response

This is the Gen2 response that is described in general in the chapter, and for different transport protocols in the Gen2 CORE document.

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 Gen2 server
• The App. It runs requests on behalf of the User.
• The User. It delegates access rights to the App.

Access Grant Server

This section is non-normative.
The Access Grant server (AGS) is in charge of producing Access Grants to Clients.
Depending on the capabilities of the Client, the specification supports two types of Access Grant Tokens: Short term and Long term AG 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 AGS more often before Access Token Server (ATS) requests for an Access Token.
The Client request shall contain the following:

• A VIN.
• A Context.
• A set of Proofs.

• A public key.

• To verify the , 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 AG 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.

Gen2 Access Control Server

The Gen2 server MUST support validation of Access tokens. This includes validation of at least the following:

• Token signature.
• Token expiry time.
• Token scope.
• Token access mode.

The Access Token need to be refreshed periodically, which is controlled by the expiry time. If the AG token that the Client used to obtain the now expired Access token is not expired, then the Client can revisit the AT server with this AG token to obtain a new Access token.
If the AG token is expired, then the Client must obtain a new AG token first, before revisiting the AT server.
For Client requests that are not granted due to access control, the Gen2 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 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 AG server. This may be certificates that the sub-actors have obtained from a Certificate Authority that is known by the AG server. The interactions related to this are out of scope.

Access Grant Token

This section is non-normative.

          
	  {
            "alg": "ES256",
            "typ": "JWT"
          },
          {
            "iat": 1609452095,
            "exp": 1609459199,
            "clx": "user+app+dev",
            "aud": "w3.org/gen2",
            "jti": "5967e92e-40e8-5f39-892d-cc0da890db1d"
          }
	  

          
	  {
            "alg": "ES256",
            "typ": "JWT"
          },
          {
            "iat": 1609452095,
            "exp": 1609459199,
            "clx": "user+app+dev",
            "pub": client_pub_key
            "aud": "w3.org/gen2",
            "jti": "5967e92e-40e8-5f39-892d-cc0da890db1d"
          }
	  

Access Token

The Access token SHALL have the following claims in header and payload.

          
	  {
            "alg": "HS256",
            "typ": "JWT"
          },
          {
            "iat": 1609452095,
            "exp": 1609459199,
            "scp": "PurposeX",
            "clx": "user+app+dev",
            "aud": "w3.org/gen2",
            "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, we prevent an eavesdropper 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, we propose the use of an incremental nonce in the form of 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.

In case freshness of the PoP was a critical requirement, we could use a public source of randomness to obtain the nonce, 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 designs goal of the Long term Access Token grant.

Device Roles

Gen2 specifies the following minimum set of roles for devices:

• Vehicle
• Nomadic
• Cloud

Application Roles

Gen2 specifies the following minimum set of roles for applications:

• OEM
• Third party

User Roles

Gen2 specifies the following minimum set of roles for users:

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

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 description, which may be used in the dialogue for consent, if needed. Then there is a list of the Client contexts, i. e. the sub-actor role triplet, that can be granted this access, and last there is a list of the signals that the client is given access to for this purpose, with the allowed access mode. The list shall use a JSON format as shown in the example below.

        {"purposes":
            [{"short": "Pay as you drive", 
            "long": "Insurance cost based on drive data.", 
            "contexts":[ ["OEM", ["OEM", "Third party"], "Vehicle"], [ ] ], 
            "signal_access":
                [{"path": "Vehicle.Drivetrain.Transmission.Speed", "access_mode": "read-only"}, 
                {"path": "Vehicle.Cabin.Infotainment.Navigation.CurrentLocation.Latitude", "access_mode":"read-only"}, 
                {"path": "Vehicle.Cabin.Infotainment.Navigation.CurrentLocation.Longitude", "access_mode": "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 Client service 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 list shall use a JSON format as shown in the example below.

        {"scope":
            [{"contexts":[ [ ["Driver", "Passenger"], "Third party", "Vehicle"], [ ] ], 
            "no_access":
                ["Vehicle.Drivetrain.Transmission.Speed", 
                "Vehicle.Cabin.Infotainment.Navigation.CurrentLocation.Latitude", 
                "Vehicle.Cabin.Infotainment.Navigation.CurrentLocation.Longitude"]
            }, 
            {}] 
        }
        

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:

• 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.

Success response:

• value The value(s) associated with the addressed VSS nodes.
• timestamp The sample time of the value.

Update

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

The client MAY have to obtain an authorization token before being able to update the vehicle signal(s). 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:

• path The path as defined in VSS to one or more nodes in the VSS tree.
• value The value by which the vehicls signals addressed by the path will be updated to.
• authorization The authorization token.

Success response:

• timestamp The time for updating of the vehicle signals.

Subscribe

Purpose: Get asynchronous messages containing the value(s) addressed by the path. The triggering rules for issuing the notification 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 a notification 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 notification.

Arguments:

• 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 notification messages.
• authorization The authorization token.

Success response:

• subscriptionId A handle identifying notification 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 notifications associated to the subscription handle. If the server is unable to fulfil the request, then the server MUST return an error response.

Arguments:

• subscriptionId Handle identifying the subscription.

Success response:

• subscriptionId Handle identifying the subscription.
• timestamp The stop time for the subscription period.

Subscription

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

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

Arguments:

• subscriptionId Handle identifying the subscription.
• value The value(s) associated with the node(s) being addressed in the subscribe request.
• timestamp The time for the trigger activation.

Error Format

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 Gen2:TRANSPORT, "Status code" chapter.
• reason See Gen2:TRANSPORT, "Status code" chapter.
• message See Gen2:TRANSPORT, "Status code" chapter.