Tree elements

Addressing

Addressing of elements is done using URIs as defined in [[RFC3986]].

scheme:authority/path

The scheme describes the protocol to use to reach the addressed element. The authority describes where to reach the service holding and managing the data representation. Scheme and authority are defined within the protocol adaptation.

Path describes the location of a specific data representation within a service. It is the path through the tree, the data representation, implemented by the service.

Data Types

Service discovery

The client MAY request that the server returns the VSS tree content. The client is able to request metadata from any point in the signal tree, such that only the metadata for the nodes within the given branch of the tree is returned. For example, only metadata for the chassis branch of the VSS tree is returned when the chassis path is specified. If the path is set to the VSS root, the response contains the metadata for the entire tree. If the server is able to satisfy the request it SHALL return a Response message. If an error occurs the server SHALL return an ErrorResponse message. The key data components of these messagess are defined below:

• Request message parameters:
• Path: The address to one or more nodes in the VSS tree, followed by the path segment "$spec".
• Response message parameters:
• Metadata: The content of the VSS tree where the root is specified by the path.
• Timestamp: A timestamp associated with the request.
• ErrorResponse message parameters:
• Error: Information describing the error reason.
• Timestamp: A timestamp associated with the failed request.

Rules

A rule is an expression that describes a characteristic of nodes that shall be returned by a query. Rules are applied to a leaf and describe a desired attribute of a node. All rules MUST return either FALSE or TRUE.

These are the rules that are known to check to be used in a query to filter content responses.

It MUST be possible to combine several rules to one greater rule. This is possible with the following operators.

JWT-based access token

JSON Web Token (JWT) is an open standard RFC 7519 that defines a compact and self-contained way for transmitting authenticated information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can generally be signed using a public/private key pair using RSA or ECC.

For the application to the protocol, the token issuer (iss claim) has to provide access to its public key (sigurl claim) for token verification. At the same time, the public key references in the sigurl claim must be authenticated using appropriate PKI mechanisms. Alternatively, the public key used for verifying tokens may be exchanged (and updated) via a separate, authenticated channel.

The payload of a JWT-based access token contains all the required information like the scope (scp claim), avoiding the need to query the auth server more than once, thus they are called self-contained.

Token verification is crucial and MUST be implemented by all services handling sensitive information.

Expiry

JWT-based access tokens are stateless keys to information that needs to be protected. Therefore a token has to be revokable. As the underlying concept of self-containing tokens does not allow revocation by a central component on a request by request basis, JWT-based access tokens shall generally expire quickly. This narrows down the possible time window for using a token without permission. After a token expires, the client is forced to obtain a fresh access token and can be denied access to the service at this point in time. Additionally, if narrow time constraints must be met, the authorization server must offer a token whitelist - listing only token meta information - every service can subscribe to based on the JWT access token's identifier (jti claim).

Identification

Every JWT shall contain a jti claim in its header to allow for blacklisting, revocation notification and one time use.

Trust decisions

The contents of a JWT cannot be relied upon in a trust decision unless its contents have been cryptographically secured and bound to the context necessary for the trust decision. In particular, the key(s) used to sign and/or encrypt the JWT will typically be under the control of the party identified as the issuer of the JWT. Unsigned JWT-based access tokens MUST fail in their verification.

Every JWT shall contain an iss (issuer) claim in its header to identify the principal that issued the token by an identifier known to the party attempting to verify the token.

Authorization Process & Security (recommendation)

Applying the token mechanisms discussed earlier in this chapter allows authorization based on these tokens. This allows a central token service to enforce a policy based on flexible scopes that may or may not group several services into logical groups. In the following, we describe a reference authorization architecture based on JWTs. Using JWTs allows a server to evaluate a request in isolation, without having to query a central component repeatedly. However, to achieve timely revocation of service access without having the client obtain new tokens frequently, we propose to implement a revocation notification mechanism (see below).

Security by OSI Level

On a basic level, the system has to implement specific security related mechanisms on different layers of the network stack:

Firewall

A firewall shall ONLY let the traffic pass it is configured for. All other ports shall be blocked by default.

Transport Layer Security

To secure the transfer of messages and tokens, transport layer security shall be established through the TLS protocol. For more detailed requirements on the required TLS version and cipher suites see Section #ref. Whether a concrete interface needs to be encrypted is subject of the security specification. However, all requests that include tokens MUST be made through an encrypted TLS channel. All necessary measures to allow TLS must be implemented, such as reliable time and secure certificate storage on the device using the certificate to authenticate. In case of mutual authentication, the client also needs to have appropriate key material.

Communication types

There are two different types of communication – public and confidential. The differentiation between these two types of communication is rather a project oriented than a security oriented. Communication is considered confidential when two trusted devices communicate with each other, e.g., the communication between two ECUs that are under full control (quality, security, testing etc.) of the vendor is considered confidential while the communication with at least one 3rd party client is considered public (e.g. cloud based client, smartphone client,…).

An internal communication is between a service/server and a - in an OAuth sense - confidential confidential client (i.e., one that can be securely provisioned with cryptographic key material). Internal communication will usually rely on a mutually authenticated TLS channel to establish a client identity for issuing tokens. See OAuth 2.0 - RFC6749 Section 2.1 for details.

Conversely, public communication occurs between a service/server and a - in the OAuth sense - public client. A public client cannot have reliable key material and can therefore not be authenticated directly. Instead, the protocol relies on a trusted system to attest the authenticity of a user identity on that client. The client then forwards a proof of authentication (e.g. an Authorization Grant Token cf. RFC7523) from the trusted system to the in-vehicle authorization server to attest the clients identity.

Use Cases

For the different use case for API usage, different cipher suites are recommended:

Authorization Grant Token (AGT)

The AGT is a JWT (https://jwt.io, https://tools.ietf.org/html/rfc7519) Token, profiled according to RFC7523 (JWT OAuth 2.0 Client Authorization Grant profile). The token MUST be signed by a trusted entity. The auth server uses the AGT to establish a client user identity (if any). An AGT shall only be valid for presentation at a particular vehicle's authorization server and shall thus contain a vehicle identifier (e.g., the VIN). The auth server must have access to an authentic public key to verify the AGT signature. The auth server must also be able to obtain updated public key material from the backend for AGT validation.

AGTs shall only be valid for a limited amount of time (several days). Checking revocation is impractical for the auth server as limited connectivity would negatively impact the user experience when attempting to access services in a vehicle. Instead, the client shall fetch new AGTs when the existing copies are about to expire. Under adversarial conditions, this would mean that an attacker can abuse e. g. a stolen portable device to access services in the name of the original user. This issue could however be mitigated by the portable device locking mechanisms as well as the ability to remove a user identity from a vehicle remotely using other frontends. Exfiltrating an AGT from a device or the communication channel would require a much higher effort, if platform and transport security are intact.

The AGT shall contain at least the following claims:

• Issuer (iss)
• Issuing date (iat)
• Expiration Time (exp)
• JWT identifier (jti)
• Client User ID being attested (uid)
• Audience (aud)

Creating the token

The client requests the AGT from the backend, specifying a target audience (a VIN), alongside backend authentication information (e.g., a backend access token). The backend system shall create and sign the desired AGT only if the user authentication is or was previously successful. Additional authorization checks MAY occur in the backend system. The signature MUST only be applied when all checks are positive. After this step a signed AGT is available for presentation to the auth server.

Token Header

Claims in the AGT header are – find the claim key for JSON in parentheses:

Issuer (iss)

The iss (issuer) claim identifies the principal that issued the JWT. The processing of this claim is generally application specific. The "iss" value is a case-sensitive string containing a String or URI value. This claim is MANDATORY and allows the token consumer to select appropriate key material for validation.

Link to public key used for signature (sigurl)

The sigurl claim (signature url) contains an url pointing to the public key to be applied for token signature verification. This public key has to be assigned to and issued by a trusted source (i.e., the consumer of the token must be able to authenticate the public key obtained from the sigurl, for example by pinning a specific root or intermediate certificate for a certificate in the sigurl). This claim is OPTIONAL, as the auth server may obtain the necessary public key through another suitable (authenticated, updatable) channel.

Issuing date (iat)

The iat (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT. Its value MUST be a unix timestamp and MUST be validated to be in the past. This claim is MANDATORY.

Expiration time (exp)

The exp (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of the exp claim requires that a reliable time source is available and that the current date/time MUST be before the expiration date/time listed in the exp claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a unix timestamp. This claim is MANDATORY.

JWT identifier (jti)

The jti (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object. The jti claim can be used to prevent the JWT from being replayed. The jti value is a case-sensitive string, it SHALL be used to revoke a token. This claim is MANDATORY.

Token payload

Mandatory claims in the AGT payload – find the claim key for JSON in parentheses:

Username/Userid (uid)

The uid (User Id) claim provides a unique identifier for the user the client is requesting authorization for. Usually the uid claim will hold a system-wide user identifier. The uid claim is used by the auth server to inform authorization decisions (e.g., whether an additional permission popup is necessary). The uid value is a case-sensitive string. The uid will be compared to the user logged in on the main unit. This claim is MANDATORY.

Audience (aud)

The aud (Audience) claim shall indicate which vehicle this AGT was issued for. Usually, the aud claim will contain a VIN. The token consumer MUST ensure that the audience string matches the expected value, i.e. that the token was issued for this vehicle.

Auth Server

The Access-Token issuer Service (auth server) is in charge of deciding over access requests submitted by a client. The client will request access to a given scope. A scope usually comprises access to one or more services. The server will validate an access token issued by the auth server, checking - among other things - that the token carries the expected scope. Below, relevant identities, scopes, policies and how tokens are issued are described.

The client request for an access token shall include the following information:

• client ID
• client user ID attestation (AGT), if available
• TLS client identity, if mutual TLS was used
• desired scope
• human-readable identifier

The auth server shall then decide whether or not to issue an access token based on this information, obtaining consent from the current vehicle user, if necessary. This process will be detailed in the following.

Types of Identities for Authorization decisions

Several identities need to be considered for authorization decisions and therefore be used by the authorization server. These identities are listed in the following.

Client Identity

The client requesting a service may have an identity itself. In this context, the term client usually refers to the device a piece of software is running on. The identity of this client (device) is generally only ascertainable if cryptographic key material is securely available on the device. Hence, the OAuth 2.0 standard distinguishes confidential and public clients. A confidential client is more tightly controlled in terms of software as well as hardware and can thus be securely provisioned with key material, which can be used to run cryptographic authentication protocols. In turn, a public client (e.g., a smartphone app on a smartphone without a trust store for secure certificate storage) comes with no such guarantees and is assumed to be more easily compromised by an adversary.

A confidential client shall be able to establish a mutually authenticated TLS channel with the auth server and the service server, providing a trusted identity, usually in the form of a certificate signed by a trusted authority. A confidential client can thus provide a proof of possession for a certain client identifier (client ID). After establishing a mutually authenticated channel with such a client, the server can be reasonably sure to be communicating with the same client as before. Confidential clients are therefore extended a client-level trust.

In contrast, a public client cannot provide any reliable identification information. Instead, public clients shall generate a unique identifier (UUID, client ID), for which it is very unlikely that another client chooses the same value. The client ID is thus only a weak identifier, which shall be used with care. In most cases, public clients shall provide a user identity that is asserted by a trusted backend on top of the client ID. It is this client user identity (that must have been previously authenticated between client, user and backend) which shall be the main source of a trust decision.

Client User Identity

The client user identity is a user identity that has been authenticated by a trusted backend systems towards the client. The auth server may choose to make authorization decisions based on this identity, for example comparing the client user identity with the system user identity (see below). If these two identities match, the auth server might conclude that the user in the vehicle is the same as the user that is logged in on the client and therefore grant a request. For the purposes of this protocol, the client user identity shall be communicated using JWT authorization grant tokens (AGT, see above).

System User Identity

The system user identity corresponds to the identity of the user currently active inside the vehicle. It is assumed that this identity belongs to the user currently in charge of operating the vehicle (i.e., the driver). The system will usually have credentials to act as this user with respect to other backend systems (e.g., to access personalized navigation functionality). The system user identity shall be available to the auth server from the environment (i.e., the platform the auth server is running on, e.g., the main unit).

In the future, there may be situations where more than one user identity is considered active on the system (i.e., the vehicle is personalized for multiple users, including potential passengers). In this case, additional metadata about the system users (e.g., which screen belongs to their seat) may be required for making authorization decisions. This use case, however, is not covered by the current version of this specification.

Scopes

When requesting access to services, the client must specify a scope it wants to get access to. A scope describes a logical set of services. This facilitates the specification of policies as well as describing the current state of authorization to users, if need be. Clients request access to a certain scope and a service expects an access token for a certain scope. Similarly, the authorization server is not concerned with particular services but just with more abstract scopes. Using scopes allows the reuse of an access token for multiple services, which reduces the burden on client-side token management as well as requests against the auth server. Additionally, scopes also allow more fine-grained access control, where one service might expect different scopes for operations of different sensitivity (e.g., read vs. write).

There shall be two types of scopes: internal scopes are granted based on client properties (e.g. client identity or client type) without user interaction; conversely, user scopes may be granted through user interaction, i.e. a popup asking the user to decide whether or not a certain client should be able to use certain functionality. These user-scopes shall be defined in a way that facilitates understanding of a grant decision when being presented to a user, i.e., so that the set of services grouped into the scope carries meaning to a user. Otherwise, users are not able to effectively exercise the control that is expected by the system to protect them from unwanted accesses.

Every client has to know which scopes to request access á priori, i.e. the scope usually are to be known at implementation time.

User Scopes

As a reference, the following set of scopes shall be used to govern access:

New services may require the definition of additional scopes. However, the list of scopes that can be presented to the user for grating authorization must remain as low as possible to avoid user confusion.

Internal Scopes

Internal scopes are scopes that can only be granted to clients based on their properties (client type, client id, client user type, etc.) and not by user interaction. The granularity of such scopes shall be flexible and up to the implementer as well as the desired control over internal service access. They can range from one single scope for all internal services to one scope per service operation.

Policies

Based on the requested scope, the client type, the client user identity, the current system user identity as well as previously granted permissions, the authorization server will search for a policy match. If a match is found, an access token matching the requested scope is issued.

A policy may additionally specify that user interaction is necessary to grant a certain scope. An example policy may state: "If the client user identity does not match the current system user identity, display a popup asking for permission to access scope X". This decision shall be remembered, in the context of the current system user identity, by the authorization server. It is important to note that each system user identity shall be able to grant or deny permissions individually. This means that a system user A may grant permission P to client user Z, while system user B denies P to Z. Implementations must choose to grant (or deny) requested scopes indefinitely (until revocation) or for a certain (potentially user-chosen) amount of time. This choice may be made on a scope-by-scope basis.

On the other hand, the authorization server shall be able to deny access to certain (more sensitive) services under certain conditions. For example, only a client in the body control ECU shall be able to update the status of the vehicle's doors and windows or all write access shall be denied to public clients.

Requesting Permission from the User

A policy may defer an authorization decision to the current system user, as only the user currently in control of the vehicle shall be able to decide whether or not a certain client shall be able to access certain functionality.

There shall only be a small number of scopes (likely less than 10) that a user can ever be asked to grant for a given client. The interface presented to the user for making the authorization decision shall be presented when the client in question is making the request to access a service associated to the scope in question. The interface shall present a meaningful description of the extent of the scope to be granted. It shall also present a meaningful identifier for the client to be authorized. Lacking a reliable identifier, clients shall be allowed to provide a human-readable name when requesting access at the auth server.

It may be beneficial to allow the user making the authorization decision to specify additional constraints. The interface may choose to offer options to grant the permission until a certain time or event. Examples include until the permission is explicitly revoked, until the end of the current drive, for the next month, etc. Useful options should be determined from user research and must be enforced by the auth server.

All permission decisions shall be stored on a per-system-user basis in a consent service within the auth server. This only concerns permission decisions made by the user. Decisions made by the auth server by policy only shall not be documented in this table (as they should be stateless). The consent service shall store decisions as follows:

• System User ID
• Client ID (+ human-readable name)
• Client User ID
• Scope
• Decision (access/deny)
• Expiry (e.g. driving cycle, timestamp, never)
• JWT-ID: The ID of the token issued based on this consent

This information shall also be available to the system user in order to manage permissions.

Access token

An access token is needed to access the APIs of services. These tokens are issued as JWT based on RFC7523 (OAuth 2.0 profile for client authorization grants). The accessToken is issued to the client by the auth server after the policy checks described above have been successfully passed. The client then sends the token with each request where it is required. The recipient/service MUST deny any API access without a valid token being provided. The token's validity MUST be checked for each request. Additionally, after receiving a token for the first time, the service must subscribe to notifications of revocation for this token's identifier. The accessToken is a JWT-type token with a signature provided by the issuer. The token SHALL be as small as possible to avoid excessive communication overhead.

accessTokens are strictly bound to the system user identity who granted access (if any). This means that in a single user system they are only valid for the services of the currently active system user identity.

AccessToken validity must begin with issuance. AccessTokens shall be issued for a certain vehicle (VIN) and system user identity (uid). Expiration may be indefinite (until revocation) or shorter, based on the configured policy or user decision. It is important to note that meaningful expiration requires a reliable source of date and time information (authenticated time).

If an accessToken is not valid anymore, all API access MUST be prohibited. On expiration or revocation, the client MUST request a new accessToken and satisfy the corresponding auth server policy. An appropriate status code MUST be sent as a response.

Revocation

The vehicle token server shall maintain a list of access token identifiers issued based on a certain user decision (see [Requesting Permission from the User] above). Once an access decision is revoked, the vehicle token server must notifiy all services consuming these access tokens of the revocation. It is the responsibility of the service to register for revocation notification of known token identifiers.

Access Token Content

• expiry (exp): timestamp after which this token shall be considered invalid
• audience (aud): The type of service/protocol this token was issued for.
• scopes (scp): the scope(s) requested by the client. It shall be possible to issue one token for multiple scopes
• token id (jti)
• system user ID (uid): the system user ID in which context this token should be considered valid.
• issuer (iss): the identity of the vehicle this token was issued for (e.g. the VIN). Services must be able to check that the token was issued for this vehicle to prevent attackers from reusing tokens across vehicles.
• public key (sigurl): the url to access the public key used to sign the access token

Note It is left to the client application to decide whether to request a single accessToken with multiple scopes multiple access accessTokens with just a single scope or anything in between, dependeing on client needs. Client developers need to be aware that each accessToken request might throw a dedicated popup.

Access Token Signature

The accessToken will be signed with the issuers public certificate. Therefore, the public key of the issuer needs to be accessible by any client during runtime.

API access

The client MUST send the accessToken with each request. API access MUST be denied if no token is given or it is found to be invalid for any reason.

Access Token Validation

Services MUST be able to perform validation steps for access tokens in isolation, i.e. without having to contact the auth server on every presentation of an access token. Therefore, services shall be able to parse and validate JWT-based access tokens.

The following properties of an access token shall be verified in the following order:

• Token expiry: A reliable time MUST be available to the service server to check validity/expiration.
• Token signature: Services MUST have authenticated access to a public key that can be used to validate token signatures. It must also be possible to update this public key periodically.
• Token scope: Services MUST know which scope to expect for a given client request.
• Token audience: Services MUST check that the token was issued for the purposes of this protocol.
• Token system user ID: The system user ID provided in the token MUST match the current system user known to the service. Services MUST be able to have authenticated access to the current system user ID.
• Token issuer: Services MUST be able to check that the token was issued by the auth server in the same vehicle as this service. For one, the issuer identifier MUST match a previously obtained value for this system. Second, the key material used to sign the token must of course also match this vehicle identity.

Once these validation steps are completed successfully, the service shall use the token identifier to subscribe to a revocation status for this identifier at the auth server. As long as local validation is successful and no revocation notification is sent by the auth server, the service shall assume that the token is valid. Once a revocation notification is sent, the service shall cache this information for an appropriate amount of time.

Token sequence overview

The following diagram shows a brief overview of the authorization flow, omitting details like the actual HTTPS calls and WebSocket message syntax.

Methods

A timeout for the response of all methods with responses MUST be defined. This timeout is transport protocol specific to reflect the normal behaviour of the transport protocol.

Arguments and Responses

Meta-Data

For the communication between service and client several key/value pairs can be given to describe the environment in what the methods () are called. The string describing the key MUST be the same structure as name.