diff --git a/vss_layers/README.md b/vss_layers/README.md new file mode 100644 index 000000000..530f71cc1 --- /dev/null +++ b/vss_layers/README.md @@ -0,0 +1,255 @@ +# VSS-Layers + +VSS layers is an extension mechanism that has been implicitly included since +the VSS development started, and now more formally defined. + +Even before the concept had a name it was in practice implemented in the +initial tools because they behaved like layers in the following ways: + +1. Overriding definitions was possible with subsequent re-definition of + the same signal + +2. It was possible to add custom metadata fields to each signal, in + addition to the VSS "core" model metadata ("name", "type", "datatype", + "description", and in recent editions "instances", "deprecation" etc.) + +Later on, tools were written to warn about unknown metadata as a quality +measure, but this needs to be adjusted when layers are used. + +There is one main way to add a metadata relationship in the plain VSS +(meta)model. In the VSSo (ontology) environment there may also be additional +ways. + + +Example how to list new metadata below a signal definition: + +VSS core model metadata: +``` +Motor.CoolantTemperature: + datatype: int16 + type: sensor + unit: celsius + description: Motor coolant temperature (if applicable). +``` + +### Removal of nodes + +Various ideas: + +Removal example, using empty value = removal +``` +Motor.CoolantTemperature: + datatype: int16 + type: <- removes "type:" entirely (*if* we allow type to be removed) + unit: celsius + description: Motor coolant temperature (if applicable). +``` + +Removal example, using no meta-data = remove signal +``` +Motor.CoolantTemperature: <- removed because meta-data is empty + +Vehicle.Powertrain.Transmission.Speed: + datatype: int32 <- modified +``` + +Removal example, requires all signals to be named in "deployment file" otherwise they are not included +(in a code generator for example): + +"deployment file" +``` +Motor.CoolantTemperature: <- signal mentioned, therefore included + deployment_stuff: foo +``` + +### Tool invocation + +Example with flags to define if it's a (m)odel or (R)emoval file: +``` + $ mytool -m vss_rel_2.yaml -m privacy_layer.yaml -m deployment_info.yaml -R stuff_to_remove.yaml +``` +... in this case nodes listed in stuff_to_remove.yaml gets removed. + + +Example with flags to define if it's a (m)odel or (I)nclusion file: +``` + $ mytool -m vss_rel_2.yaml -m privacy_layer.yaml -m deployment_info.yaml -I deployment_whitelist.yaml +``` +... in this case any node NOT listed in deployment_whitelist.yaml gets removed (not used in output). + +Proposal: "Allow" tools to include equivalent of -R and -I flags, one or the +other or both, depending on need. + +Also support a manifest file instead of listing on command line +``` + $ mytool -f filelist.txt +``` + +filelist.txt example 1: +``` + vss_rel_2.2 + +vss_privacy_info + +deployment + -removed_signals +``` + +filelist.txt example 2: +``` + basemodel: vss_rel_2.2 + layer: vss_privacy_info + modification: ... + deployment: mydepl.yaml +``` + +filelist.txt example 3: +``` + model: vss_rel_2.2 + model: vss_privacy_info + model: ... + Removal: mydepl.yaml +``` + + +TODO: +- Define how to modify instances + + +Example of layered additional metadata: +``` +Motor.CoolantTemperature: + my_unique_concept: true +``` + +### A note about signal names and paths + +The VSS is defined by a hierarchy of sub-trees each defined in their own file. + +An example file (ElectricMotor.vspec) may include: + +``` +Motor.CoolantTemperature + ... + ... +``` + +but since this information is in the file ElectricMotor.vspec, and +that file was included at the location of Vehicle.Powertrain.ElectricMotor, +the above shortened definition actually spells out the following full-path +signal: + +`Vehicle.Powertrain.ElectricMotor.Motor.CoolantTemperature` + + +This principle for file-inclusions and namespacing applies to VSS-layers in +the same way as the core VSS. For full details, refer to the VSS +documentation. Note however, that later examples in this text will use the +full path for clarity. E.g.: `Vehicle.Chassis.Wheel.Brake.Fluidlevel` + +## Usage of VSS-layers + +VSS-layers is a fully generic extension mechanism that is likely to find new +uses over time, but some of the primary drivers are: + +1. The general separation of a "deployment model" that is not included in the core definition. +1. Defining supplementary layers that deal with, for example, data classification. +1. Ability for companies to tie VSS into existing software and processes that needs additional concepts or information + +Some of these usages may lead to agreed-upon layers used by the whole industry, a.k.a. standard layers. +Others will be system, product, or company specific. + +### Deployment model + +This concept, also provided by Franca IDL, is very powerful as it +ensures that the basic interface definition (in this case the VSS signals) is +not encumbered by details that are unique to a particular usage of the +information. + +A Deployment Model keeps the information necessary to realize the +described interface in a particular environment, platform, or even programming +language. Anything that is not related to the interface (data) description +itself, but rather to how it is used, should be separated into a deployment +model outside of the main definition file. + +This makes the data or interface definition more reusable because the same +definition can be used in many different environments and situations. + +As an example, in a local request, the name of the data or function might be +enough to address it. When the same definition is to be used in a distributed +system, the data access or function invocation may need some kind of +address of the location to find this particular item. In some environments, +this could be a logical Node name it belongs to, or an IP-address in +another environment, or a numeric service ID in another. A particular +protocol may offer data requests to be synchronous or asynchronous, or cached +or on-demand. While that is a feature and is likely part of the request sent +via the protocol, it may be that some data items can support only one or the +other, and that must then be defined for each data item. + +Whatever they may be, such details are deployment-specific and should be +layered on top of the core model and catalog, not included in it. + +### Data classification + +An example of information that would be applicable only in some situations is +to classify data into privacy sensitivity categories. Other classification +reasons can be envisioned as well. + +Noteworthy for this example, and likely many others: + +1. What falls into each privacy category differs depending on country + jurisdiction, and perhaps sometimes on the usage situation. The way data is + classified might differ between car brands. +1. The same vehicle model may be sold in different markets and the same + product would then need different definitions on the individual level. + +The nature of local privacy laws (and likely many other examples) shows that +such information cannot be defined as part of the common model or catalog -- +it simply differs too often between usage situations. Sometimes it is +required to view the system's data model with different layer configurations +even within a single implementation. Therefore, a layered approach is needed +in the creation of a standard data model and data catalog. + +The fact that this may differ even on instances of vehicles of the same make +shows that the ability to add/remove layers dynamically might be needed in the +technology stack implementation. Another consideration is for layers to be +individually updated during software updates. + +### Access control + +A frequent augmentation of the data model information is definition of access +permission rules. These boil down to specific signals that a specific actor +is allowed or not allowed to access. Once again, this differs depending on +the situation and should be defined as a separate layer. + +## General definition of VSS-layers + +The layer concept definition should impose very little restrictions. +Conventions and particular tools may introduce their own restrictions +for certain usage, at a later time. + +The layer concept itself is able to do all of the following: + +1. Modify existing metadata and ultimately redefine any signal (i.e. change + its metadata) compared to a previous definition for example the definition + in the standard catalog. +1. Add new signals. It can be done in the private/ branch as recommended but the + mechanism allows adding them anywhere. +1. Add new metadata, or relationships to new concepts for the purpose of + creating deployment-models, bindings to existing technology, classification + and many other things. +1. Remove signals from the final data model (SYNTAX TO BE DEFINED) + +VSS-layers can also define new concepts as described in the following +scenarios: + +## Tool support + +VSS Layer general concept shall be supported in vss-tools, wherever it is +applicable. + +VSS processing tools shall generally support any number of input layers of the +supported type, and if nothing else is documented then tools shall process the +layers in the given order (later layers redefine or override earlier layers). +Tools may optionally provide information (warning or other logs) when +information is redefined. + + diff --git a/vss_layers/android_permissions_layer_using_directories/Attribute/Attributes.apspec b/vss_layers/android_permissions_layer_using_directories/Attribute/Attributes.apspec new file mode 100644 index 000000000..ac76dd756 --- /dev/null +++ b/vss_layers/android_permissions_layer_using_directories/Attribute/Attributes.apspec @@ -0,0 +1,5 @@ +#include Drivetrain/Engine.aperms Drivetrain.InternalCombustionEngine +#include Transmission.aperms Drivetrain.Transmission +#include FuelSystem.aperms Drivetrain.FuelSystem +#include ADAS.aperms ADAS +#include Vehicle.aperms Vehicle diff --git a/vss_layers/android_permissions_layer_using_directories/Attribute/Drivetrain/Engine.apspec b/vss_layers/android_permissions_layer_using_directories/Attribute/Drivetrain/Engine.apspec new file mode 100644 index 000000000..734343692 --- /dev/null +++ b/vss_layers/android_permissions_layer_using_directories/Attribute/Drivetrain/Engine.apspec @@ -0,0 +1,27 @@ +# FILE: Attribute.vspec +# INCLUDES Drivetrain/Engine.vspec as "Drivetrain.InternalCombustionEngine" +# and in file Engine.vspec: +# ENTRY: InternalCombustionEngine.Configuration --> Full path is Attribute.Drivetrain.InternalCombustionEngine.Configuration +# ENTRY: InternalCombustionEngine.Displacement --> Full path is Attribute.Drivetrain.InternalCombustionEngine.Displacement +# ENTRY: InternalCombustionEngine.FuelType --> Full path is Attribute.Drivetrain.InternalCombustionEngine.FuelType +# ENTRY: InternalCombustionEngine.MaxPower --> Full path is Attribute.Drivetrain.InternalCombustionEngine.MaxPower +# ENTRY: InternalCombustionEngine.MaxTorque --> Full path is Attribute.Drivetrain.InternalCombustionEngine.MaxTorque +# +# Similarly, +# FILE: Attributes/Attribute.apersms +# INCLUDES Drivetrain/Engine.aperms (this file) as "Drivetrain.InternalCombustionEngine" +# +# Therefore this file can use local signal names, and will refer to the *.Drivetrain.InternalCombustionEngine.* path + + +# +# START OF ANDROID PERMISSIONS METADATA +# (VSS LAYER) +# + +# Matching all signals under Drivetrain.InternalCombustionEngine? ? +.*: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + + + diff --git a/vss_layers/android_permissions_layer_using_directories/Attribute/Transmission.apspec b/vss_layers/android_permissions_layer_using_directories/Attribute/Transmission.apspec new file mode 100644 index 000000000..8742d962b --- /dev/null +++ b/vss_layers/android_permissions_layer_using_directories/Attribute/Transmission.apspec @@ -0,0 +1,28 @@ +# FILE: Attribute.vspec +# INCLUDES Transmission.vspec as "Drivetrain.Transmission" +# and in file Transmission.vspec: +# ENTRY: DriveType --> Full path is Attribute.Drivetrain.Transmission.DriveType +# ENTRY: GearCount --> Full path is Attribute.Drivetrain.Transmission.GearCount +# ENTRY: Type --> Full path is Attribute.Drivetrain.Transmission.Type + +# Similarly, +# FILE: Attributes/Attribute.apersms +# INCLUDES Transmission.aperms (this file) as "Dreivetrain.Transmission" +# +# Therefore this file can use local signal names, and will refer to the *.Drivetrain.Transmission.* path + +# +# START OF ANDROID PERMISSIONS METADATA +# (VSS LAYER) +# + +DriveType: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + +GearCount: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + +Type: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + + diff --git a/vss_layers/android_permissions_layer_using_directories/Attribute/Vehicle.apspec b/vss_layers/android_permissions_layer_using_directories/Attribute/Vehicle.apspec new file mode 100644 index 000000000..a042ba822 --- /dev/null +++ b/vss_layers/android_permissions_layer_using_directories/Attribute/Vehicle.apspec @@ -0,0 +1,30 @@ +# FILE: Attribute/Attribute.vspec +# INCLUDES Vehicle.vspec as "Vehicle" + +# and in file Vehicle.vspec: +# ENTRY: VehicleIdentification.Model --> Full path is Attribute.Vehicle.VehicleIdentification.Model +# ENTRY: VehicleIdentification.Year --> Full path is Attribute.Vehicle.VehicleIdentification.Year +# ENTRY: VehicleIdentification.VIN --> Full path is Attribute.Vehicle.VehicleIdentification.VIN + +# Similarly Attribute/Attribute.aperms +# INCLUDES Vehicle.aperms (this file) as "Vehicle" +# Therefore, this file can also use local (non fully qualified) paths to the signals when adding metadata. +# and it will be referring to the *.Vehicle.* tree + +# +# START OF ANDROID PERMISSIONS METADATA +# (VSS LAYER) +# + +# The following 2 signals are included in the permission group android.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VEHICLETYPE +VehicleIdentification.Model: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VEHICLETYPE + +VehicleIdentification.Year: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VEHICLETYPE + +# VIN is however sensitive because it is a unique identifier of the vehicle: +# So it should have its own permission +VehicleIdentification.VIN: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VIN + diff --git a/vss_layers/android_permissions_layer_using_directories/FuelSystem.apspec b/vss_layers/android_permissions_layer_using_directories/FuelSystem.apspec new file mode 100644 index 000000000..aed1e955d --- /dev/null +++ b/vss_layers/android_permissions_layer_using_directories/FuelSystem.apspec @@ -0,0 +1,18 @@ +# FILE: Attribute/Attribute.vspec +# INCLUDES FuelSystem.vspec as "Drivetrain.Fuelsystem" +# and in file FuelSystem.vspec: +# ENTRY: TankCapacity --> Full path is Attribute.Drivetrain.FuelSystem.TankCapacity + +# Similarly Attribute/Attribute.aperms +# INCLUDES FuelSystem.aperms (this file) as "Drivetrain.Fuelsystem" +# Therefore, this file can also use local (non fully qualified) paths to the signals when adding metadata. +# and it will be referring to the *.Drivetrain.Fuelsystem.* tree + +- TankCapacity: # refers to Attribute.Drivetrain.FuelSystem.TankCapacity + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + +# or: Permission_Read: + +# 1. android.car.permission is a prefix that might be added by generator +# 2. There is no generic access-control methodology for VSS but we could generalize the concept maybe +# 3. Permissions need more metadata, like "dangerous" in the current android permissions diff --git a/vss_layers/android_permissions_layer_using_directories/Signal/ADAS/ADAS.apspec b/vss_layers/android_permissions_layer_using_directories/Signal/ADAS/ADAS.apspec new file mode 100644 index 000000000..451725ed2 --- /dev/null +++ b/vss_layers/android_permissions_layer_using_directories/Signal/ADAS/ADAS.apspec @@ -0,0 +1,37 @@ + +# FILE: Signal/Signal.vspec +# INCLUDES ADAS/ADAS.vspec as "ADAS" +# and in file ADAS.vspec: +# ENTRY: CruiseControl.IsActive: --> Full path is Signal.ADAS.CruiseControl.Error: +# ENTRY: CruiseControl.SpeedSet: --> Full path is Signal.ADAS.CruiseControl.IsActive: +# ENTRY: CruiseControl.Error: --> Full path is Signal.ADAS.CruiseControl.SpeedSet: + +# Similarly, this file ADAS/ADAS.aperms was included by Signal.aperms in the hierarchy + +# Therefore, it can use local (not fully qualified) signal names when adding metadata to +# the signals, and they will refer to the *.ADAS.* hierarchy + + +# +# START OF ANDROID PERMISSIONS METADATA +# (VSS LAYER) +# + +CruiseControl.Error: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_CRUISECONTROL_STATUS + +CruiseControl.IsActive: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_CRUISECONTROL_STATUS + +#??? What is the meaning of not defining AndroidPermission_Write -- does it mean it is never allowed +#??? Does WRITE permission automatically imply that you have READ permission. + +# Speed setting is security sensitive. Probably NO application should have write access! +# But for an example's sake, let's put it in and make it a unique permission! +CruiseControl.SpeedSet: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_CRUISECONTROL_STATUS + AndroidPermission_Write: android.car.permission.VEHICLESIGNALS_CRUISECONTROL_SPEED + +# should we allow arrays here? [ android.car.permission.VEHICLESIGNALS_CRUISECONTROL_STATUS, +# android.car.permission.VEHICLESIGNALS_CRUISECONTROL_SPEED ] + diff --git a/vss_layers/android_permissions_layer_using_directories/all.txt b/vss_layers/android_permissions_layer_using_directories/all.txt new file mode 100644 index 000000000..c41006607 --- /dev/null +++ b/vss_layers/android_permissions_layer_using_directories/all.txt @@ -0,0 +1,145 @@ +# FILE: Attribute/Attribute.vspec +# INCLUDES FuelSystem.vspec as "Drivetrain.Fuelsystem" +# and in file FuelSystem.vspec: +# ENTRY: TankCapacity --> Full path is Attribute.Drivetrain.FuelSystem.TankCapacity + +# Similarly Attribute/Attribute.aperms +# INCLUDES FuelSystem.aperms (this file) as "Drivetrain.Fuelsystem" +# Therefore, this file can also use local (non fully qualified) paths to the signals when adding metadata. +# and it will be referring to the *.Drivetrain.Fuelsystem.* tree + +- TankCapacity: # refers to Attribute.Drivetrain.FuelSystem.TankCapacity + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + +# or: Permission_Read: + +# 1. android.car.permission is a prefix that might be added by generator +# 2. There is no generic access-control methodology for VSS but we could generalize the concept maybe +# 3. Permissions need more metadata, like "dangerous" in the current android permissions + +# FILE: Signal/Signal.vspec +# INCLUDES ADAS/ADAS.vspec as "ADAS" +# and in file ADAS.vspec: +# ENTRY: CruiseControl.IsActive: --> Full path is Signal.ADAS.CruiseControl.Error: +# ENTRY: CruiseControl.SpeedSet: --> Full path is Signal.ADAS.CruiseControl.IsActive: +# ENTRY: CruiseControl.Error: --> Full path is Signal.ADAS.CruiseControl.SpeedSet: + +# Similarly, this file ADAS/ADAS.aperms was included by Signal.aperms in the hierarchy + +# Therefore, it can use local (not fully qualified) signal names when adding metadata to +# the signals, and they will refer to the *.ADAS.* hierarchy + + +# +# START OF ANDROID PERMISSIONS METADATA +# (VSS LAYER) +# + +CruiseControl.Error: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_CRUISECONTROL_STATUS + +CruiseControl.IsActive: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_CRUISECONTROL_STATUS + +#??? What is the meaning of not defining AndroidPermission_Write -- does it mean it is never allowed +#??? Does WRITE permission automatically imply that you have READ permission. + +# Speed setting is security sensitive. Probably NO application should have write access! +# But for an example's sake, let's put it in and make it a unique permission! +CruiseControl.SpeedSet: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_CRUISECONTROL_STATUS + AndroidPermission_Write: android.car.permission.VEHICLESIGNALS_CRUISECONTROL_SPEED + +# should we allow arrays here? [ android.car.permission.VEHICLESIGNALS_CRUISECONTROL_STATUS, +# android.car.permission.VEHICLESIGNALS_CRUISECONTROL_SPEED ] + +# FILE: Attribute.vspec +# INCLUDES Transmission.vspec as "Drivetrain.Transmission" +# and in file Transmission.vspec: +# ENTRY: DriveType --> Full path is Attribute.Drivetrain.Transmission.DriveType +# ENTRY: GearCount --> Full path is Attribute.Drivetrain.Transmission.GearCount +# ENTRY: Type --> Full path is Attribute.Drivetrain.Transmission.Type + +# Similarly, +# FILE: Attributes/Attribute.apersms +# INCLUDES Transmission.aperms (this file) as "Dreivetrain.Transmission" +# +# Therefore this file can use local signal names, and will refer to the *.Drivetrain.Transmission.* path + +# +# START OF ANDROID PERMISSIONS METADATA +# (VSS LAYER) +# + +DriveType: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + +GearCount: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + +Type: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + + +# FILE: Attribute.vspec +# INCLUDES Drivetrain/Engine.vspec as "Drivetrain.InternalCombustionEngine" +# and in file Engine.vspec: +# ENTRY: InternalCombustionEngine.Configuration --> Full path is Attribute.Drivetrain.InternalCombustionEngine.Configuration +# ENTRY: InternalCombustionEngine.Displacement --> Full path is Attribute.Drivetrain.InternalCombustionEngine.Displacement +# ENTRY: InternalCombustionEngine.FuelType --> Full path is Attribute.Drivetrain.InternalCombustionEngine.FuelType +# ENTRY: InternalCombustionEngine.MaxPower --> Full path is Attribute.Drivetrain.InternalCombustionEngine.MaxPower +# ENTRY: InternalCombustionEngine.MaxTorque --> Full path is Attribute.Drivetrain.InternalCombustionEngine.MaxTorque +# +# Similarly, +# FILE: Attributes/Attribute.apersms +# INCLUDES Drivetrain/Engine.aperms (this file) as "Drivetrain.InternalCombustionEngine" +# +# Therefore this file can use local signal names, and will refer to the *.Drivetrain.InternalCombustionEngine.* path + + +# +# START OF ANDROID PERMISSIONS METADATA +# (VSS LAYER) +# + +# Matching all signals under Drivetrain.InternalCombustionEngine? ? +.*: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_DRIVETRAININFORMATION + + + +#include Drivetrain/Engine.aperms Drivetrain.InternalCombustionEngine +#include Transmission.aperms Drivetrain.Transmission +#include FuelSystem.aperms Drivetrain.FuelSystem +#include ADAS.aperms ADAS +#include Vehicle.aperms Vehicle +# FILE: Attribute/Attribute.vspec +# INCLUDES Vehicle.vspec as "Vehicle" + +# and in file Vehicle.vspec: +# ENTRY: VehicleIdentification.Model --> Full path is Attribute.Vehicle.VehicleIdentification.Model +# ENTRY: VehicleIdentification.Year --> Full path is Attribute.Vehicle.VehicleIdentification.Year +# ENTRY: VehicleIdentification.VIN --> Full path is Attribute.Vehicle.VehicleIdentification.VIN + +# Similarly Attribute/Attribute.aperms +# INCLUDES Vehicle.aperms (this file) as "Vehicle" +# Therefore, this file can also use local (non fully qualified) paths to the signals when adding metadata. +# and it will be referring to the *.Vehicle.* tree + +# +# START OF ANDROID PERMISSIONS METADATA +# (VSS LAYER) +# + +# The following 2 signals are included in the permission group android.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VEHICLETYPE +VehicleIdentification.Model: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VEHICLETYPE + +VehicleIdentification.Year: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VEHICLETYPE + +# VIN is however sensitive because it is a unique identifier of the vehicle: +# So it should have its own permission +VehicleIdentification.VIN: + AndroidPermission_Read: android.car.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VIN + diff --git a/vss_layers/new_permissions_layer_type.perms b/vss_layers/new_permissions_layer_type.perms new file mode 100644 index 000000000..1c83693c9 --- /dev/null +++ b/vss_layers/new_permissions_layer_type.perms @@ -0,0 +1,76 @@ + +# EXAMPLE OF NEW ENTITY DEFINED AS A VSS LAYER +# +# An "entity" is a new subject. (In addition to signals that vspec defines) +# +# It can, like signals, be instantiated with entries on the YAML file top level +# +# Each entry can have metadata. +# +# Comparison, the original VSS has "Attributes" and "Signals" as entities, and in those fiules +# each attribute/signal is named, and then its attributes (metadata) is mapped below + +# In this file, the entity being instantiated is: Named Permission groups (roles) +# Android app permissions, for example, act like this. + +# NOTICE: This file "flips" the definition mapping compared to .apspec files, +# by naming the permission first, then (as metadata below) define which signals +# are included in each permission This makes signals group together in one +# place. It also makes it easier to include signals in more than one +# permission. + +# Structure: +# PermissionName: +# read_permission: +# write_permission: +# protection_level: Mirroring protection level in Android + +vss.permission.VEHICLESIGNALS_BODYINFORMATION: + read_permission: [ Attribute.Body.RefuelPosition ] + protection_level: 'dangerous' + +vss.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VEHICLETYPE: + read_permission: [ Attribute.Vehicle.VehicleIdentification.Model, + Attribute.Vehicle.VehicleIdentification.Year ] + protection_level: '...' + +vss.permission.VEHICLESIGNALS_VEHICLEINFORMATION_VIN: + read_permission: [ Attribute.Vehicle.VehicleIdentification.VIN ] + protection_level: '...' + +vss.permission.VEHICLESIGNALS_ADASSTATUS: + read_permission: [ Signal.ADAS.CruiseControl.Error, + Signal.ADAS.CruiseControl.IsActive, + Signal.ADAS.CruiseControl.SpeedSet ] + protection_level: '...' + +vss.permission.VEHICLESIGNALS_DRIVETRAININFORMATION: + read_permission: [ Attribute.Drivetrain.FuelSystem.TankCapacity, + Attribute.Drivetrain.InternalCombustionEngine.*, # Note the wildcards + Attribute.Drivetrain.Transmission.* ] + protection_level: '...' + +# or alternatively (if addressing a branch is equal to wildcard) +# Attribute.Drivetrain.InternalCombustionEngine: # (branch name) +# AndroidPermission_Read: vss.signalpermission.drivetraininformation +# vss.signalpermission.drivetraininformation +# read_permission: [ Attribute.Drivetrain.FuelSystem.TankCapacity, +# Attribute.Drivetrain.InternalCombustionEngine, +# Attribute.Drivetrain.Transmission ] + + +vss.permission.VEHICLESIGNALS_ADAS_SPEED: + read_permission: [ Signal.ADAS.CruiseControl.SpeedSet ] + protection_level: '...' + +# WRITE PERMISSION EXAMPLE +vss.permission.VEHICLESIGNALS_ADAS_SPEED: + write_permission: [ Signal.ADAS.CruiseControl.SpeedSet ] + protection_level: '...' + +# For some permission models (e.g. Android) each permission group is unique, +# thus the example vss.permission.VEHICLESIGNALS_ADAS_SPEED cannot deal with +# read and write differently. you would need to generate two actual versions +# in that case: vss.permission.VEHICLESIGNALS_ADAS_SPEED_READ: +# vss.permission.VEHICLESIGNALS_ADAS_SPEED_WRITE: + diff --git a/vss_layers/permissions_as_vss_layer_one_file.pspec b/vss_layers/permissions_as_vss_layer_one_file.pspec new file mode 100644 index 000000000..1537bae15 --- /dev/null +++ b/vss_layers/permissions_as_vss_layer_one_file.pspec @@ -0,0 +1,122 @@ + +# EXAMPLE ATTRIBUTES AND SIGNALS IN FOUR GROUPS + +# ------------------------------------------------------------------------------------------------------------ +# # Group 1: Refuel position (Where on the car is the refueling located?) +# FILE: Attribute/Body.vspec +# ENTRY: RefuelPosition --> Full path is Attribute.Body.RefuelPosition + +# ------------------------------------------------------------------------------------------------------------ +# # Group 2: Vehicle type & identity + +# FILE: Attribute/Vehicle.vspec +# INCLUDES Vehicle.vspec as "Vehicle" +# and in file Vehicle.vspec: +# ENTRY: VehicleIdentification.Model --> Full path is Attribute.Vehicle.VehicleIdentification.Model +# ENTRY: VehicleIdentification.Year --> Full path is Attribute.Vehicle.VehicleIdentification.Year +# ENTRY: VehicleIdentification.VIN --> Full path is Attribute.Vehicle.VehicleIdentification.VIN + +# ------------------------------------------------------------------------------------------------------------ +# # Group 3: Information about engine + +# FILE: Attribute.vspec +# INCLUDES Drivetrain/Engine.vspec as "Drivetrain.InternalCombustionEngine" +# and in file Engine.vspec: +# ENTRY: InternalCombustionEngine.Configuration --> Full path is Attribute.Drivetrain.InternalCombustionEngine.Configuration +# ENTRY: InternalCombustionEngine.Displacement --> Full path is Attribute.Drivetrain.InternalCombustionEngine.Displacement +# ENTRY: InternalCombustionEngine.FuelType --> Full path is Attribute.Drivetrain.InternalCombustionEngine.FuelType +# ENTRY: InternalCombustionEngine.MaxPower --> Full path is Attribute.Drivetrain.InternalCombustionEngine.MaxPower +# ENTRY: InternalCombustionEngine.MaxTorque --> Full path is Attribute.Drivetrain.InternalCombustionEngine.MaxTorque +# +# INCLUDES FuelSystem.vspec as "Drivetrain.FuelSystem" +# and in file FuelSystem.vspec: +# ENTRY: TankCapacity --> Full path is Attribute.Drivetrain.FuelSystem.TankCapacity +# +# INCLUDES Transmission.vspec as "Drivetrain.Transmission" +# and in file Transmission.vspec: +# ENTRY: DriveType --> Full path is Attribute.Drivetrain.Transmission.DriveType +# ENTRY: GearCount --> Full path is Attribute.Drivetrain.Transmission.GearCount +# ENTRY: Type --> Full path is Attribute.Drivetrain.Transmission.Type + +# ------------------------------------------------------------------------------------------------------------ +# # Group 4: Cruise Control signals + +# FILE: Signal/Signal.vspec +# INCLUDES ADAS/ADAS.vspec as "ADAS" +# and in file ADAS.vspec: +# ENTRY: CruiseControl.IsActive: --> Full path is Signal.ADAS.CruiseControl.Error: 941 +# ENTRY: CruiseControl.SpeedSet: --> Full path is Signal.ADAS.CruiseControl.IsActive: 939 +# ENTRY: CruiseControl.Error: --> Full path is Signal.ADAS.CruiseControl.SpeedSet: 940 + + + +# +# START OF ANDROID PERMISSIONS METADATA +# (VSS LAYER) +# + + +# EXAMPLE - TOP LEVEL FILE AT ROOT, USING FULL PATH DEFINITIONS +# +# e.g. /vss_rel0.aperms contains: + +Attribute.Body.RefuelPosition: + Permission_Read: vss.permission.BODYINFORMATION +# (NOTE: a write permission makes no sense for for attributes because they are constants) + +# The following 2 signals are included in the permission group vss.permission.vehicleinformation.vehicletype + +Attribute.Vehicle.VehicleIdentification.Model: + Permission_Read: vss.permission.VEHICLEINFORMATION_VEHICLETYPE + +Attribute.Vehicle.VehicleIdentification.Year: + Permission_Read: vss.permission.VEHICLEINFORMATION_VEHICLETYPE + +# VIN is however sensitive because it is a unique identifier of the vehicle: +# So it should have its own permission +Attribute.Vehicle.VehicleIdentification.VIN: + Permission_Read: vss.permission.VEHICLEINFORMATION_VIN + +# Information about Cruisecontrol (varying, i.e. it is a signal) +Signal.ADAS.CruiseControl.Error: + Permission_Read: vss.permission.ADASSTATUS + +Signal.ADAS.CruiseControl.IsActive: + Permission_Read: vss.permission.ADASSTATUS + +# Speed setting is security sensitive. Probably NO application should have write access! +# But for an example's sake, let's put it in and make it a unique permission! +Signal.ADAS.CruiseControl.SpeedSet: + Permission_Read: vss.permission.ADASSTATUS + Permission_Write: vss.permission.ADAS_SPEED + + +# Let's also put all of the drivetrain *AND* Fuel attributes in one common +# permission group: +# +# Attribute.Drivetrain.FuelSystem.TankCapacity +# Attribute.Drivetrain.InternalCombustionEngine.Configuration +# Attribute.Drivetrain.InternalCombustionEngine.Displacement +# Attribute.Drivetrain.InternalCombustionEngine.FuelType +# Attribute.Drivetrain.InternalCombustionEngine.MaxPower +# Attribute.Drivetrain.InternalCombustionEngine.MaxTorque +# Attribute.Drivetrain.Transmission.DriveType +# Attribute.Drivetrain.Transmission.GearCount +# Attribute.Drivetrain.Transmission.Type +# +Attribute.Drivetrain.FuelSystem.TankCapacity: + Permission_Read: vss.permission.DRIVETRAININFORMATION + +# We can use some wildcards: +Attribute.Drivetrain.InternalCombustionEngine.*: + Permission_Read: vss.permission.DRIVETRAININFORMATION + +# or alternatively (if addressing a branch is equal to wildcard) +# Attribute.Drivetrain.InternalCombustionEngine: # (branch name) +# Permission_Read: vss.permission.drivetraininformation + +Attribute.Drivetrain.Transmission.*: + Permission_Read: vss.permission.DRIVETRAININFORMATION + + +