diff options
| -rw-r--r-- | BUILD.md | 12 | ||||
| -rw-r--r-- | CONFIGURE.md | 218 | ||||
| -rw-r--r-- | README.md | 6 | ||||
| -rw-r--r-- | doc/open_issues.md | 725 | ||||
| -rw-r--r-- | doc/pdf/BUILD.pdf | bin | 0 -> 295900 bytes | |||
| -rw-r--r-- | doc/pdf/CONFIGURE.pdf | bin | 0 -> 1642409 bytes | |||
| -rw-r--r-- | doc/pdf/rvi_fragmentation.pdf | bin | 0 -> 424532 bytes | |||
| -rw-r--r-- | doc/pdf/rvi_protocol.pdf | bin | 0 -> 1083617 bytes | |||
| -rw-r--r-- | doc/pdf/rvi_services.pdf | bin | 0 -> 1576836 bytes | |||
| -rw-r--r-- | doc/rvi_fragmentation.md | 22 | ||||
| -rw-r--r-- | doc/rvi_protocol.md | 745 | ||||
| -rw-r--r-- | doc/rvi_services.md | 40 |
12 files changed, 926 insertions, 842 deletions
@@ -1,3 +1,9 @@ +<style type="text/css" media="print"> + div.pagebreak + { + page-break-before: always; + } +</style> Copyright (C) 2014-2016, Jaguar Land Rover This document is licensed under Creative Commons @@ -37,6 +43,8 @@ Please note that the configuration process described in ---- +<div class="pagebreak"></div> + # INSTALLATION PROCESS # ## INSTALL DEVELOPMENT TOOLS ## @@ -91,7 +99,9 @@ top level project in the ```rvi``` directory. The local ```rebar``` command is used to retrieve the dependencies. See ```rebar.config``` and ```deps/*/rebar.config``` for a list of -dependencies. +dependencies. + +<div class="pagebreak"></div> See the [rebar](https://github.com/basho/rebar) project for a detailed description of the rebar Erlang build tool. diff --git a/CONFIGURE.md b/CONFIGURE.md index 2bc5977..d5cb540 100644 --- a/CONFIGURE.md +++ b/CONFIGURE.md @@ -1,3 +1,9 @@ +<style type="text/css" media="print"> + div.pagebreak + { + page-break-before: always; + } +</style> Copyright (C) 2014-2016, Jaguar Land Rover This document is licensed under Creative Commons @@ -19,15 +25,13 @@ The reader is assumed to be able to: 3. Edit configuration files. 4. Understand the basic concepts of IP addresses, ports and URLs. - ## PREREQUISITES 1. Erlang runtime 18.2 or later has to be installed on the hosting system. -2. The ```setup_rvi_node.sh``` tool is available to build a release. -3. ```rvi_sample.config``` is used as a starting point for a customized setup. +2. The `setup_rvi_node.sh` tool is available to build a release. +3. `rvi_sample.config` is used as a starting point for a customized setup. Root access is not needed. - ## CONFIGURATION PROCESS OVERVIEW To bring up an RVI node so that it can be used by locally @@ -58,12 +62,12 @@ have their URLs configured so that the components can locate each other and exchange commands. <b>6. Build the development release</b><br> -The ```setup_rvi_node.sh``` script is executed to read the configuration file +The `setup_rvi_node.sh` script is executed to read the configuration file and generate a development or production release. <b>7. Start the release</b><br> -The ```rvi_node.sh``` script is executed to launch the built development -release. ```$REL_HOME/rvi/bin/rvi start``` is used to launch the +The `rvi_node.sh` script is executed to launch the built development +release. `$REL_HOME/rvi/bin/rvi start` is used to launch the production release. @@ -71,13 +75,13 @@ production release. There is a single configuration file, with the setup for all components and modules in the node, used for each release. -A documented example file is provided as ```priv/config/rvi_sample.config``` +A documented example file is provided as `priv/config/rvi_sample.config` The configuration file consists of an array of erlang tuples (records -/ structs / entries), where the ```env``` tuple contains configuration data for -all components. The ```rvi``` tuple under ```env``` has all the +/ structs / entries), where the `env` tuple contains configuration data for +all components. The `rvi` tuple under `env` has all the configuration data for the RVI system. With the possible exception for -the lager logging system, only the ```rvi``` tuple needs to be edited. +the lager logging system, only the `rvi` tuple needs to be edited. The term tuple and entry will be intermixed throughout this document. @@ -85,9 +89,9 @@ The term tuple and entry will be intermixed throughout this document. For a full description of Erlang types, read [the Erlang Reference Manual](http://erlang.org/doc/reference_manual/users_guide.html). The following is a brief summary: -* Tuples, written as ```{ Elem1, ..., ElemN }``` are like arrays whose elements are accessed by position. -* Lists, written as ```[ Elem1, ..., ElemN ]``` are linked lists whose elements are accessed by iterating from the beginning of the list. Another notation is ```[ Head | Tail ]```. Strings are actually lists of integers, and ```"RVI"``` is equivalent to ```[82,86,73]```, or ```[$R,$V,$I]```. -* Numbers, e.g. ```17```, ```1.44```, ```2#101``` (binary notation), ```16#5A``` (hex notation). +* Tuples, written as `{ Elem1, ..., ElemN }` are like arrays whose elements are accessed by position. +* Lists, written as `[ Elem1, ..., ElemN ]` are linked lists whose elements are accessed by iterating from the beginning of the list. Another notation is `[ Head | Tail ]`. Strings are actually lists of integers, and `"RVI"` is equivalent to `[82,86,73]`, or `[$R,$V,$I]`. +* Numbers, e.g. `17`, `1.44`, `2#101` (binary notation), `16#5A` (hex notation). * Atoms, names starting with a lowercase letter or enclosed in single quotes, are essentially labels. * Variable names start with an uppercase letter. @@ -95,10 +99,10 @@ For a full description of Erlang types, read [the Erlang Reference Manual](http: RVI Core uses the [setup](https://github.com/uwiger/setup) tool to build from configuration files. -The files used by ```setup``` are evaluated using the [file:script/1](http://erlang.org/doc/man/file.html#script-1) function, meaning that the file can contain a sequence of executable Erlang expressions, each terminated with a full stop (```.```). Anything starting with ```%``` and to the end of the line +The files used by `setup` are evaluated using the [file:script/1](http://erlang.org/doc/man/file.html#script-1) function, meaning that the file can contain a sequence of executable Erlang expressions, each terminated with a full stop (`.`). Anything starting with `%` and to the end of the line constitutes a comment. -Example from ```rvi_core/priv/config/rvi_sample.config```: +Example from `rvi_core/priv/config/rvi_sample.config`: Env = fun(V, Def) -> case os:getenv(V) of @@ -118,21 +122,23 @@ Example from ```rvi_core/priv/config/rvi_sample.config```: BackendPort = Env("RVI_BACKEND_PORT", 8807). LogLevel = Env("RVI_LOGLEVEL", notice). -The above defines two function objects used to check for the existence of a given OS environment variable, and using the corresponding value, or else using a default value. For example, the variable ```MyPort``` is set to either the value of ```RVI_PORT``` or else to ```9000```. These variables are used further down in the configuration file. +The above defines two function objects used to check for the existence of a given OS environment variable, and using the corresponding value, or else using a default value. For example, the variable `MyPort` is set to either the value of `RVI_PORT` or else to `9000`. These variables are used further down in the configuration file. + +<div class="pagebreak"></div> -The ```setup``` utility is called when the ```rvi.sh``` script is run. To e.g. enable debug logging, you can do the following: +The `setup` utility is called when the `rvi.sh` script is run. To e.g. enable debug logging, you can do the following: $ RVI_LOGLEVEL=debug rvi.sh ... -```Setup``` expects certain configuration entries, e.g. ```{apps, [App1, ...]}```, ```{env, [{App, [{Key, Val}, ...]}, ...]}```. Most of the configuration work for RVI is done in ```{env, ...}```. +`Setup` expects certain configuration entries, e.g. `{apps, [App1, ...]}`, `{env, [{App, [{Key, Val}, ...]}, ...]}`. Most of the configuration work for RVI is done in `{env, ...}`. -It is possible to include existing configuration files and then modifying the result. For example, the ```rvi_sample.config``` file includes ```rvi_core/priv/config/rvi_common.config``` via the following line: +It is possible to include existing configuration files and then modifying the result. For example, the `rvi_sample.config` file includes `rvi_core/priv/config/rvi_common.config` via the following line: {include_lib, "rvi_core/priv/config/rvi_common.config"}, -Includes can be used at several levels. For example, ```priv/test_config/basic_backend.config``` includes ```priv/test_config/backend.config```, which in its turn includes ```priv/config/backend.config```, which, finally, includes ```priv/config/rvi_common.config```. +Includes can be used at several levels. For example, `priv/test_config/basic_backend.config` includes `priv/test_config/backend.config`, which in its turn includes `priv/config/backend.config`, which, finally, includes `priv/config/rvi_common.config`. -Other examples can be found in ```rvi_core/priv/test_config/```, where configurations used by the test suite are located: +Other examples can be found in `rvi_core/priv/test_config/`, where configurations used by the test suite are located: {ok, CurDir} = file:get_cwd(). [ @@ -146,7 +152,9 @@ Other examples can be found in ```rvi_core/priv/test_config/```, where configura ]} ]. -The ```set_env``` instruction specifically takes a list of ```{App, [{Key, Value}]}``` tuples, where the ```Key``` is either an atom or list of atoms, the latter indicating an entry in a 'tree' of entries. In the example above, the tree would look like: +<div class="pagebreak"></div> + +The `set_env` instruction specifically takes a list of `{App, [{Key, Value}]}` tuples, where the `Key` is either an atom or list of atoms, the latter indicating an entry in a 'tree' of entries. In the example above, the tree would look like: {rvi_core, [ @@ -172,10 +180,10 @@ The ```set_env``` instruction specifically takes a list of ```{App, [{Key, Value If the entry in question exists in the tree, it will be modified; if not, it will be added. -For more details about what can be done with ```setup```, see (the setup_gen manual)[https://github.com/uwiger/setup/blob/master/doc/setup_gen.md]. +For more details about what can be done with `setup`, see (the setup_gen manual)[https://github.com/uwiger/setup/blob/master/doc/setup_gen.md]. ## CONFIGURATION FILE VALUE SUBSITUTION -Some forms of substitution are supported by ```setup```, see (the docs on variable expansion)[https://github.com/uwiger/setup/blob/master/doc/setup.md#Variable_expansion]. +Some forms of substitution are supported by `setup`, see (the docs on variable expansion)[https://github.com/uwiger/setup/blob/master/doc/setup.md#Variable_expansion]. RVI Core supports some additional substitution of its own. All substitution is done automatically when RVI starts, so the running applications see the final results of the substitutions. @@ -184,53 +192,55 @@ for specific dokens during startup. If a token is found, it will be replaced with a value referenced by it. Tokens can one of the following: -* ```$rvi_file(FileName,Default)``` - File content<br> - When an ```$rvi_file()``` token is encountered, the first line of +* `$rvi_file(FileName,Default)` - File content<br> + When an `$rvi_file()` token is encountered, the first line of the referenced file is read. The line (without the newline) replaces the token.<br> Example:<br> - ```{ node_service_prefix, "jlr.com/vin/$rvi_file(/etc/vin,default_vin)"}``` + `{ node_service_prefix, "jlr.com/vin/$rvi_file(/etc/vin,default_vin)"}` will be substituted with the first line from the - file ```/etc/vin```: + file `/etc/vin`: - ```{ node_service_prefix, "jlr.com/vin/2GKEG25HXP4093669"}``` + `{ node_service_prefix, "jlr.com/vin/2GKEG25HXP4093669"}` - If ```/etc/vin``` cannot be opened, the value ```default_vin``` + If `/etc/vin` cannot be opened, the value `default_vin` will be used instead. -* ```$rvi_env(EnvironemtnName,Default)``` - Environment variable<br> - When an ```$rvi_env()``` token is encountered, the value of +<div class="pagebreak"></div> + +* `$rvi_env(EnvironemtnName,Default)` - Environment variable<br> + When an `$rvi_env()` token is encountered, the value of the Linux process environment variable (such as $HOME) is read to replace the token.<br> Example:<br> - ```{ node_service_prefix, "jlr.com/vin/$rvi_env(VIN,default_vin)"}``` + `{ node_service_prefix, "jlr.com/vin/$rvi_env(VIN,default_vin)"}` - will be substituted with the value of the ```$VIN``` environment + will be substituted with the value of the `$VIN` environment variable: - ```{ node_service_prefix, "jlr.com/vin/2GKEG25HXP4093669"}``` + `{ node_service_prefix, "jlr.com/vin/2GKEG25HXP4093669"}` If VIN is not a defined environment variable, the value - ```default_vin``` will be used instead. + `default_vin` will be used instead. -* ```$rvi_uuid(Default)``` - Unique machine identifier<br> - When an ```$rvi_uuid()``` token is encountered, the UUID of the root +* `$rvi_uuid(Default)` - Unique machine identifier<br> + When an `$rvi_uuid()` token is encountered, the UUID of the root disk used by the system is read to replace the token. - The UUID of the root disk is retrieved by opening ```/proc/cmdline``` - and extracting the ```root=UUID=[DiskUUID]``` value. + The UUID of the root disk is retrieved by opening `/proc/cmdline` + and extracting the `root=UUID=[DiskUUID]` value. This value is generated at system install time and is reasonably world wide unique. Example:<br> - ```{ node_service_prefix, "jlr.com/vin/$uuid(default_vin)"}``` + `{ node_service_prefix, "jlr.com/vin/$uuid(default_vin)"}` will be substituted with the value of the root disk UUID: - ```{ node_service_prefix, "jlr.com/vin/afc0a6d8-0264-4f8a-bb3e-51ff8655b51c"} ``` + `{ node_service_prefix, "jlr.com/vin/afc0a6d8-0264-4f8a-bb3e-51ff8655b51c"} ` - If the root UUID cannot be retrieved, the value ```default_vin``` + If the root UUID cannot be retrieved, the value `default_vin` will be used instead. # SPECIFY NODE SERVICE PREFIX # @@ -257,21 +267,23 @@ prefix identifying what their role is. Below are a few examples of prefixes: -```jaguarlandrover.com/vin/sajwa71b37sh1839/``` - A JLR vehcile with +`jaguarlandrover.com/vin/sajwa71b37sh1839/` - A JLR vehcile with the given vin.<br> -```jaguarlandrover.com/mobile/+19492947872/``` - A mobile device with +`jaguarlandrover.com/mobile/+19492947872/` - A mobile device with a given number, managed by JLR, hosting an RVI node.<br> -```jaguarlandrover.com/sota/``` - JLR's global software over the air +`jaguarlandrover.com/sota/` - JLR's global software over the air server.<br> -```jaguarlandrover.com/3rd_party/``` - JLR's 3rd party application +`jaguarlandrover.com/3rd_party/` - JLR's 3rd party application portal.<br> -```jaguarlandrover.com/diagnostic/``` - JLR's diagnostic server.<br> +`jaguarlandrover.com/diagnostic/` - JLR's diagnostic server.<br> -The prefix for an RVI node is set in the ```node_service_prefix``` tuple. +The prefix for an RVI node is set in the `node_service_prefix` tuple. + +<div class="pagebreak"></div> An example entry is given below: @@ -309,7 +321,7 @@ The defaults should *only* be used for testing and demos - never for live use. #CONFIGURE DATA LINK LAYERS -The ```data_link``` components are specified as ```{Module, Type, Options}```, e.g. +The `data_link` components are specified as `{Module, Type, Options}`, e.g. <pre> [ @@ -327,7 +339,9 @@ The ```data_link``` components are specified as ```{Module, Type, Options}```, e ] </pre> -In the data link component, ```dlink_tls_rpc```, you can specify the following options: +<div class="pagebreak"></div> + +In the data link component, `dlink_tls_rpc`, you can specify the following options: { server_opts, Opts } @@ -372,17 +386,18 @@ An example tuple is given below: ] </pre> -If ```dlink_tcp_rpc``` is to listen to the port on all network -interfaces, the ```ip``` tuple can be omitted. +If `dlink_tcp_rpc` is to listen to the port on all network +interfaces, the `ip` tuple can be omitted. -The ```persistent_connections``` section lists the IP:Port pair of all +The `persistent_connections` section lists the IP:Port pair of all remote RVI nodes that this node should maintain a connection with. If the address is not available, a reconnection attempt will be made every five seconds. This allows a solid connection between RVI nodes where only one node can initiate a connection (such as a vehicle-to-server link in a mobile network). +<div class="pagebreak"></div> # ROUTING RULES @@ -390,7 +405,7 @@ Routing rules determining how to get a message targeting a specific service to its destination. A routing rule specifies a number of different way to reach an RVI -node hosting a specific service prefix, such as ```jlr.com/vin/ABCD/sota/```. +node hosting a specific service prefix, such as `jlr.com/vin/ABCD/sota/`. Please note that if a remotely initiated (== client) data link is available and has announced that the targeted service is available, @@ -400,10 +415,10 @@ Service name prefix that rules are specified for The service prefix with the longest match against the service targeted by the message will be used. -Example: Targeted service = ```jlr.com/backend/sota/get_updates``` +Example: Targeted service = `jlr.com/backend/sota/get_updates` -Prefix 1: ```{ "jlr.com/backend", [...]}```<br> -Prefix 2: ```{ "jlr.com/backend/sota", [...]}```<br> +Prefix 1: `{ "jlr.com/backend", [...]}`<br> +Prefix 2: `{ "jlr.com/backend/sota", [...]}`<br> In this case, Prefix 2 will be used. @@ -425,8 +440,8 @@ that it can handle the targeted service. Below is an example of a default rule. This rule specifies that, unless another rule has a longer prefix -match, a request shall be encoded using ```proto_json_rpc```, and -transmitted using ```dlink_tcp_rpc```. +match, a request shall be encoded using `proto_json_rpc`, and +transmitted using `dlink_tcp_rpc`. To direct an in-vehicle RVI-node to send all its backend requests to a specific address, add the following rule. @@ -443,13 +458,15 @@ specific address, add the following rule. </pre> This rule specifies that any message to a service starting -with ```jlr.com/backend``` shall first be encoded using ```proto_json_rpc```, -and transmitted using ```dlink_tcp_rpc```. The ```dlink_tcp_rcp``` data link -module will be instructed to send all messages targeting ```jlr.com/backend/...``` to the -IP-address:port ```38.129.64.31:8807```. +with `jlr.com/backend` shall first be encoded using `proto_json_rpc`, +and transmitted using `dlink_tcp_rpc`. The `dlink_tcp_rcp` data link +module will be instructed to send all messages targeting `jlr.com/backend/...` to the +IP-address:port `38.129.64.31:8807`. + +<div class="pagebreak"></div> To setup Vehicle-to-Vehicle communication, where a vehicle can reach -services on other vehicle's starting with ```jlr.com/vin/```, add the +services on other vehicle's starting with `jlr.com/vin/`, add the following rule. <pre> @@ -471,17 +488,17 @@ following rule. This rule specifies that any message to a service starting -with ```jlr.com/vin``` shall first be encoded using the protocol - data -link pair ```proto_json_rpc``` - ```dlink_tcp_rpc```, where WiFi -broadcasts shall be used (thrugh ```wlan0``` and ```broadcast```) to +with `jlr.com/vin` shall first be encoded using the protocol - data +link pair `proto_json_rpc` - `dlink_tcp_rpc`, where WiFi +broadcasts shall be used (thrugh `wlan0` and `broadcast`) to find other vehiclces. If that does not work, a 3G connection to the vehicle shall be -attempted, through the ```proto_json_rpc``` - ```dlink_3g_rpc``` pair, +attempted, through the `proto_json_rpc` - `dlink_3g_rpc` pair, where we are allowed to initiate outbound connections to the 3G network in case a connection is not already available. -Finally, an SMS can be sent through the ```proto_sms_rpc``` - ```dlink_sms_rpc``` pair, +Finally, an SMS can be sent through the `proto_sms_rpc` - `dlink_sms_rpc` pair, maximizing message size to 140 bytes. @@ -495,10 +512,12 @@ In cases where JSON-RPC is used instead of Erlang-internal gen\_server calls, other components in the RVI node use the same URL to send traffic to Service Edge -The URL of Service Edge is specified through the ```service_edge_rpc``` -tuple's ```json_rpc_address``` entry, read by the other components in the node to +The URL of Service Edge is specified through the `service_edge_rpc` +tuple's `json_rpc_address` entry, read by the other components in the node to locate it. +<div class="pagebreak"></div> + An example entry is gven below: <pre> @@ -529,7 +548,7 @@ An example entry is gven below: # SPECIFY URLS OF RVI COMPONENTS # The remaining components in an RVI system needs to have their URLs and listening ports setup as well. It is recommended that consecutive -ports after that used for ```service_edge_rpc``` are used. +ports after that used for `service_edge_rpc` are used. Please note that if only erlang components are used (as is the case in the reference implementation), native erlang gen\_server calls can be @@ -537,9 +556,10 @@ used instead of URLs, providing a significant transactional speedup. Please see the genserver components chapter below for details. Below is an example of a complete port/url configuration for all -components, including the ```bert_rpc_server``` entry described in the +components, including the `bert_rpc_server` entry described in the external node address chapter: +<div class="pagebreak"></div> <pre> [ ... @@ -602,13 +622,13 @@ native erlang inter-process calls that are signficantly faster than JSON-RPC when transmitting large data volumes. If one or more of the RVI components are replaced with external -components, use JSON-RPC by ```json_rpc_address``` +components, use JSON-RPC by `json_rpc_address` for all components. If an all-native erlang system is configured, use gen\_server calls -by configuring ```gen_server```. +by configuring `gen_server`. -If both ```gen_server``` and ```json_rpc_address``` are specified, the +If both `gen_server` and `json_rpc_address` are specified, the gen\_server communicaiton path will be used for inter component communication. @@ -617,10 +637,10 @@ by this since data_link_bert_rpc will use the protocol and data links specified by the matching routing rule to communicate. See [Routing Rules](#ROUTING RULES) chapter for details. -Below is an example of where gen\_server is used where approrpiate. +Below is an example of where gen\_server is used where appropriate. -Please note that ```service_edge_rpc``` always need to have -its ```json_rpc_address``` specified since local services need an +Please note that `service_edge_rpc` always need to have +its `json_rpc_address` specified since local services need an HTTP port to send JSON-RPC to. However, gen\_server can still be specified in parallel, allowing for gen\_server calls to be made between Servie Edge and other RVI components. @@ -665,13 +685,15 @@ between Servie Edge and other RVI components. ] </pre> -# SETTING UP WEBSOCKET SUPPORT ON A NODE +<div class="pagebreak"></div> + +# SETTING UP WEBSOCKET SUPPORT The service edge can, optionally, turn on its websocket support in order to support locally connected services written in javascript. This allows an RVI node to host services running in a browser, on node.js or similar web environments. -Websocket support is enabled by adding a ```websocket``` entry to the configuration data -of ```servide_edge_rpc```. +Websocket support is enabled by adding a `websocket` entry to the configuration data +of `servide_edge_rpc`. Below is the previous configuration example with such a setup. @@ -698,7 +720,7 @@ Below is the previous configuration example with such a setup. Websocket clients can now connect to: -```ws://127.0.0.1:8801/websession``` and issue JSON-RPC commands to +`ws://127.0.0.1:8801/websession` and issue JSON-RPC commands to Service Edge. Outbound service invocations, sent from the RVI node to the javascript code, will be transmitted over the same socket. @@ -727,23 +749,23 @@ Each release will have a name, which will also be the name of the newly created subdirectory containing the files necessary to start the release. -If a configuration file, ```rvi_sample.config``` is to be used when building -release ```test_rel```, the following command can be run from the +If a configuration file, `rvi_sample.config` is to be used when building +release `test_rel`, the following command can be run from the build root: ./scripts/setup_rvi_node.sh -d -n test_rel -c rvi_sample.config Once executed (and no errors were found in test.config), a -subdirectory called ```test_rel``` has been created. This directory +subdirectory called `test_rel` has been created. This directory contains the erlang configuration and boot files necessary to bring up the RVI node. # STARTING A DEVELOPMENT RELEASE The newly built development release is started using the -```rvi_node.sh``` tool. +`rvi_node.sh` tool. -In order to start the test release, named ```test_rel```, created in +In order to start the test release, named `test_rel`, created in the previous chapter, the following command is run from the build root: @@ -763,27 +785,27 @@ Service Edge and start routing traffic. *Please note that a new release must be created each time the configuration file has been updated* -To create a self contained production release using ```prod.config``` -as the configuration file, and name the release ```prod_rel```, the +To create a self contained production release using `prod.config` +as the configuration file, and name the release `prod_rel`, the following command can be run from the build root: ./script/setup_rvi_node.sh -n prod_rel -c prod.config Once executed (and no errors were found in test.config), a -subdirectory called ```rel/prod_rel``` has been created. +subdirectory called `rel/prod_rel` has been created. -The ```prod_rel``` directory contains a complete erlang runtime +The `prod_rel` directory contains a complete erlang runtime system, the RVI application, and the configuration data generated from -```prod.config``` the RVI node. +`prod.config` the RVI node. -The ```prod_rel``` directory can be moved to anywhere in the file +The `prod_rel` directory can be moved to anywhere in the file system, or to another host with the same architecture and OS setup. # STARTING A PRODUCTION RELEASE The newly built product release is started using the -```rel/prod_rel/rvi``` tool: +`rel/prod_rel/rvi` tool: ./rel/prod_rel/rvi start @@ -815,7 +837,7 @@ production release, and set the log level manually: Replace debug with info, notice, warning, or error for different log levels. A production release will also produce logs to -```rel/[release]/log/erlang.log.?```. +`rel/[release]/log/erlang.log.?`. Check the file modification date to find which of the log files are currently written to. @@ -20,11 +20,11 @@ Git branch management is JLR OSTCs standard git document For build instructions, please check the build instructions: [Markdown](BUILD.md) | -[PDF](https://wiki.automotivelinux.org/_media/eg-rvi/rvi-build.pdf) +[PDF](doc/pdf/BUILD.pdf) For configuration and launch instructions, please check the configuration documentation: [Markdown](CONFIGURE.md) | -[PDF](https://wiki.automotivelinux.org/_media/eg-rvi/rvi-configure.pdf) +[PDF](doc/pdf/CONFIGURE.pdf) Technical RVI disussions are held at the GENIVI project mailing list: [GENIVI](https://lists.genivi.org/mailman/listinfo/genivi-projects) @@ -151,7 +151,7 @@ with a wide variety of hardware. ## PYTHON ## Python is used to implement all demonstrations, beginning -with the HVAC demo available in the ```hvac_demo``` subdirectory. +with the HVAC demo available in the `hvac_demo` subdirectory. By using Python for the demos, which is better known than erlang, examples are given on how to write applications and services diff --git a/doc/open_issues.md b/doc/open_issues.md new file mode 100644 index 0000000..4615f7f --- /dev/null +++ b/doc/open_issues.md @@ -0,0 +1,725 @@ +Copyright (C) 2015-16 Jaguar Land Rover + +This document is licensed under Creative Commons +Attribution-ShareAlike 4.0 International. + +## OPEN ISSUES + +### [1] Public device key exchange as a part of handshake demasks sender + +#### Issue Sending the root signed public key during handshake +identifies the sender to an unknown remote party. + + +#### Solution +TBD + +### [2] Public device key exchange as a part of allows for replay attack + +#### Issue +Sending the root signed public key during handshake allows a malicious +remote party to replay the signed key, potentially confusing the +remote part. Please note that a replay attacker still cannot sign any +subsequent commands since they do not have the private key + + +#### Solution +Have the handshake include a random number signed by the private device key +proves that the sender also posseses the private counterpart. + +### [3] Key renewal/revocation scheme needed. + +#### Issue +A generated device or root key has no way of being revoked and/or renewed today. + + +#### Solution +Have a set of services, similar to the certificate management services, to +retire old / compromised keys and distribute new ones. + + +### [4] Self provisioning process needs to be validated + +#### Issue +The self provisioing process of a device has too many steps and edge cases. + + +#### Solution +Document a number of MITM and replay attacks to identify initial set of weaknesses. +Simplify process. + + + +### [5] Link-level encryption needs to be implemented + +#### Issue +With the current solution traffic is authenticated and authorized, but not encrypted. +While an attacker cannot modify or inject traffic, they can listen in to it. + + +#### Solution +Integrate OpenSSL TLS for session encryption, and possibly also key management. + + +### [6] Ensure that each transaction sent is unique + +#### Issue +Currently the JSON-RPC payload transaction id is just a sequential +number, which allows for an easy replay attack + + + +#### Solution +Make sure that a each transaction is persistent monotonically increased +for each transaction. +Have the server ignore transactions from a device that have already been +executed. + + +### [7] Data Flow Diagrams are needed + +#### Issue +The text-only description is opaque and hard to visualize. + +#### Solution +Create Data Flow Diagrams for all major use cases. + + + +### [8] STRIDE Application is needed + +#### Issue +There is currently no formal security model, such as STRIDE, applied +to the document + +#### Solution +Expand and formalize the "Thwarting malicious RVI nodes..." chapters +to be STRIDE compliant. + + +### [9] STRIDE Application is needed + +#### Issue +Using naked, PEM-encoded root and device keys does not provide expiry time or chains. + +#### Solution +Explore possibility of implementing full-blown certificates for public key management. + + +### [10] Non-intuitive configuration parameter names + +#### Issue +key_pair and provisioning_key are not describing what they are actually +refering to. + +#### Solution +The following name changes will be done to the configuration parameters: + +key_pair - Store single device key pair used to sign outgoing transactions. + +Will be renamed device_key_pair. + +provisioning_key - Public root key used to validate incoming certificates and device signatures. + +Will be renamed public_root_key + +### [11] Self provisioning is broken. + +#### Issue +From Rudi's review. + +1. Steps 2 through 5: What purpose do steps 2 and 3 serve? You would + typically have them if the device and the server would be + exchanging session keys that they use to project all the subsequent + transactions. Since there are no session keys, for each subsequent + transaction the data exchanged has to be signed and validated with + the PKI anyway. So, in step 4 the device would have to send the + node certificate sent in step 2, since the server cannot rely on + that the two transactions are atomic and are actually sent from the + same device, even if it says so. + +2. I think step 2 must be combined with step 4 and step 3 with step 5, + otherwise there is no security. RVI is very much asynchronous and + stateless which means with every data exchange the credentials have + to be provided.Step 6: The node cert from step 2 that gives the + device the right to invoke the service must be provided, because + technically the invocation can come from a different device. RVI is + stateless, it should be for security reasons anyway. + +3. Step 8: The data sent in step 8, the device public key and the + token, have to be encrypted with the server's public key, to make + sure that only the server can read it and that the message cannot + be intercepted by mitm to retrieve the token. Otherwise, the side + band token transmission would not make any sense. + +4. Steps 9 and 10: They should be combined. The server creates the + node certificate and signs the entire certificate, not just the + key. The very reason being that the cert includes validity claims + that need to be protected from alteration such as valid_after and + valid_until time stamps. + +5. Step 10: Why would step 10, which creates and signs the node + certificate include an authorization to invoke a service on a + vehicle, such as the example jlr.com/vin/ABCD/unlock? Those are + separate certificates as they have individual validity dates etc. + +6. Steps 11 and 12: There is no point in separating the device public + key from the node certificate. After the node certificate has been + created by the server containing the device's public key in steps 9 + and 10 (which should be one step, imho), the node certificate is + sent to the device. The device receives it and validates the + signature and if ok store the cert. + +7. All of this should just be for provisioning the device with a node + certificate. Providing devices with authorization certificates that + allow them to invoke services on vehicles is separate. The + provisioning you do once (or maybe a very few times). Providing + authorization certificates is a rather frequent action and + independent. + + +#### Solution +Redesign, bottom up. + + +### [12] Python scripts should use cryptocgraphy intead of PyCrypto + +#### Issue +Today, rvi_create_certificate.py and rvi_create_device_key.py use PyCrypto while +JWT, imported by both scripts, uses cryptography. + + +#### Solution +rvi_create_certificate.py and rvi_create_device_key.py should be rewritten +to use cryptography instead of PyCrypto. + + + +## SETTING UP NODE AUTHENTICATION AND AUTHORIZATION + +This document describes the process of setting up root keys, device +keys, and certificates. + + +## TERMINOLOGY AND COMPONENTS + +### Certificate issuer +A certificate issuer is an entity that signs device keys and +certificates with a private root key. Devices with the corresponding +public root key will be able to authenticate signed device keys and +authorize signed certificates. + +### Root key +A root key, a 4096+ bit RSA key pair, is generated once for an issuer +of certificates. The private key is stored in the certificate +issuer's servers and is not shared. The public key is manually +installed on all RVI nodes that are to trust certificates from the +certificate issuer. + +### Device key +A device key is a per-RVI node 4096+ bit RSA key pair. The private part of +the device key is stored on a host (server, embedded device, mobile device, etc) +and is not shared. The public part of the key is used in two ways: + +1. **To prove the identity of an RVI node**<br> + When two RVI nodes locate each other over a data link (WiFi, 3G, + Bluetooth, etc), they exchange an authenticate ("au") packet to + prove their identity. This packet has the public part of the device + key encoded as a JSON Web Token (JWT - RFC7519) token signed by the + private part of the root key.<br> The receiver can use its locally + stored public root key to validate that the received public device is + signed by the private root key of a trusted certificate issuer. + +2. **To prove ownership of certificates.**<br> + Embdded in the authenticate packet are one or more certificates + proving the sending RVI node's right to register and invoke + services. The certificate, signed by the private root key of the + issuer, contains the public key of the sending device encoded as + JWT structure. This public device key can be used by a + receiver to verify the signature of a service invocation requests + sent by the remote RVI node. + +### Certificate + +A certificate is a JSON Web Token, signed by the private root key of +the certificate issuer, that proves that the RVI node with a given +public device key has the right to invoke a specific set of services +and to register another set of services. + +The certificate is encoded as a JSON Web Token (JWT) signed +by the private root key. The decoded payload has the following JSON +elements. + +Command line parameters to ```rvi_create_certificate.py``` given in +parenthesis. Items marked with '*' are slated for name changes to +better reflect JWT practises and RVI semantics. + +1. **```iss``` Issuer (```--issuer```)**<br> + A domain name identifying the issuer. Currently supported but not + used. + +2. **```create_timestamp```* - Creation time stamp**<br> + Unix time, UTC, when the certificate was created. + <br><i>Will be renamed ```iat``` to comply with JWT</i> + +3. **```sources```* - Right to register (```--invoke```)**<br> + A list of full service names that the certificate grants the right to + register, allowing other, credentialed RVI nodes to invoke these + services. + <br><i>Will be renamed ```register``` to better comply with semantics.</i> + +4. **```destinations```* Right to invoke (```--register```)**<br> + A list of full service names that the certificate grants the right + to invoke on other RVI nodes who have registered them + <br><i>Will be renamed ```invoke``` to better comply with semantics.</i> + +5. **```keys``` Public device keys (```--device_key```)**<br> + Contains one or more (currently only one) public device keys in JSON + Web Key (RFC7517) format. The receiver will use this key to validate + subsequent service invocations through the signatures submitted with + the invocations. + +6. **```start```* Start time of validity period (```--start```)**<br> + Stored under the ```validity``` JSON element and specifies the Unix + time stamp UTC when the certificate becomes valid. The receiving RVI node + will check that the current time is not before the ```start``` time stamp + of the certificate. + <br><i>Will be renamed ```nbf``` to comply with JWT.</i> + +7. **```stop```* Stop time of validity period (```--stop```)**<br> + Stored under the ```validity``` JSON element and specifies the Unix + time stamp UTC when the certificae expires. The receiving RVI node will + check that the current time is not after the ```stop``` time stamp + of the certificate. + <br><i>Will be renamed ```exp``` to comply with JWT.</i> + + +## ASSUMPTIONS ON EXTERNAL COMPONENTS + +### Trustworthy time source + +In order to validate the active period for certificates (and in the +future, keys) a trustworthy time source is needed. For devices time +source is provided by GPS or the mobile network. For backend servers, +the source is provided by NTP. + +It is up to the deployment project to ensure that these sources cannot be tampered with. + +### Secure key store + +Device private keys and root private keys are expected to be securerly +stored on an RVI node through a key vault to prevent unauthorized access. + + +## SETTING UP RVI NETWORK SECURITY - GENERAL FLOW + +The general flow of events for setting up security are as follows: + +1. **Create root key pair ```rvi_create_root_key.sh```**<br> + A single root key is created by the certificate issuer. Two PEM + files are created in this process. One PEM file with the + private/public key that never leaves the issuer's trusted server, + and one public-only PEM file that is installed on every RVI node + that is to accept certificates from the issuer. + +2. **Create device key pairs ```rvi_create_device_key.py```**<br> + Each RVI node need to have its own device key pair. The device key + script will create a private/public key PEM file that never leaves + the device, a public-only PEM file that is embedded into + certificates, and a JWT file with the public device key encoded as + a JSON Web Key (JWK - RFC 7159) signed by the private root key + generated in step 1. + +3. **Create certificates ```rvi_create_certificate.py```**<br> + Certificates are generated to allow a specific RVI node (with a + given device key) to register (setup) services that it wants other + RVI nodes to invoke, and to invoke serivces registered by other RVI + nodes The certificate script creates a JWT file, signed by the root + key, that encodes the certificate described in the + [Certificate](#Certificate) chapter.<br> + Certificates are stored on the credentialed RVI node. + + +### Provisioning a root key pair + +#### Creating the root key PEM files + +The root key, consisting of a private/public RSA4096 key PEM file, and +a second PEM file with only the public portion of the key, is created +by the following command: + + rvi_create_root_key.sh -b 4096 -o my_root_key + +* **```-b 4096```**<br> + Specifies the number of bits in the key. + +* **```-o my_root_key```**<br> + Specifies the file name prefix of the two created key files. + +Once executed, two files will be created: + +1. **```my_root_key_priv.pem```**<br> + This file contains the private/public key pair that must never leave + the credit issuer's trusted environment. It will be used to sign the + JWT formatted device key and all certificates created by the + certificate issuer. + +2. **```my_root_key_pub.pem```**<br> + This file contains the public-only key that is to be installed on + RVI nodes that will accept device keys and certificates signed by the + certificate issuer. + +#### Configuring RVI to use a public root key +Only ```rvi_create_device_key.py``` and ```rvi_create_certificate.py``` use the +private root key stored in ```my_root_key_priv.pem```, generated above. +The RVI node itself is never aware of that file. + +The RVI node does need the public root key, stored in ```my_root_key_pub.pem```, +is referenced from the RVI's configuration file stored +as ```{ rvi_core, { provisioning_key, "..../my_root_key_pub.pem" }}```. + + + +### Provisioning a device key pair + +#### Creating the device key PEM files +A device key, consisting of a private/public RSA4096 key PEM file, a +second PEM file with only the public portion of the key, and a third +JWT is created by the following command: + + rvi_create_device_key.py -p my_root_key_priv.pem -o my_device_key -b 4096 + +* **```-b 4096```**<br> +Specifies the number of bits in the device key.<br> + +* **```-p my_root_key_priv.pem```**<br> +Specifies the private root key to sign the device key with when it is +stored in the JWT file (see below). The root key is created by the +```rvi_create_root_key.sh``` script.<br> + +* **```-o my_device_key```**<br> +Specifies the file name prefix of the three created device key files. + + +Once executed, three files will be created: + +1. **```my_device_key_priv.pem```**<br> + This file contains the private/public key pair that must never leave + the device's trusted environment. It will be used to sign + outgoing service invocation request. + +2. **```my_device_key_pub.pem```**<br> + This file contains the public-only key that is to be added to + certificates issued for the device by a certificate issuer. + +3. **```my_device_key_pub_sign.jwt```**<br> + This file contains the public-only key, signed by the root key, + that is to be provided as authentication when an RVI node identifies + itself toward another. The file is stored in JSON Web Token format. + + +#### Configuring RVI to use a device key + +The RVI node needs the device private/public key root key, stored in +```my_device_key_priv.pem```, is referenced from the RVI's configuration +file in ```{ rvi_core, { key_pair, "..../my_device_key_priv.pem" }}```. + + +### Provisioning a certificate + +#### Creating the certificate file +A certificate is a JWT-formatted JSON structure signed by the root +private key, is stored on an RVI node to be presented to remote node +as evidence that the sender has the right to invoke and register the +specified services. + +The certificate is created by the following command + + ./rvi_create_certificate.py --id=my_cert_id \ + --device_key=my_device_key_pub.pem \ + --start='2015-12-01 00:00:00' \ + --stop='2015-12-31 23:59:59' \ + --root_key=my_root_key_priv.pem \ + --register='jlr.com/vin/abc/unlock jlr.com/vin/abc/lock' \ + --invoke='jlr.com/backend/report jlr.com/backend/set_state' \ + --jwt_out=my_cert.jwt \ + --cert_out=my_cert.json \ + --issuer=jaguarlandrover.com + +The following arguments are provided +* **```--id=my_cert_id```**<br> + System-wide unique ID to be assigned to this certificate. + +* **```--device_key=my_device_key_pub.pem```**<br> + Specifies that the public device key, generated by ```create_device_key.py``` + shall be embedded into the generated certificate as the certificate owner. + +* **```--root_key=my_root_key_priv.pem```**<br> + Specifies that the certificate shall be signed by the private root + key generated by ```create_root_key.sh```. + +* **```--invoke='jlr.com/backend/report jlr.com/backend/set_state'```**<br> + Gives the device with the certificate-embedded public key the right to invoke + the services ```jlr.com/backend/report``` and ```jlr.com/backend/set_state```. + +* **```--register='jlr.com/vin/abc/unlock jlr.com/vin/abc/lock'```**<br> + Gives the device with the certificate-embedded public key the right to register + the services ```jlr.com/backend/report``` and ```jlr.com/backend/set_state```. + +* **```--start='2015-12-01 00:00:00'```**<br> + Specifies that the certificate shall become valid Dec 1, 2015 at + midnight. + +* **```--stop='2015-12-31 23:59:59'```**<br> + Specifies that the certificate shall expire valid Dec 31, 2015 at + 11:59:59 PM. + +* **```--jwt_out=my_cert.jwt```**<br> + Specifies the name of the JWT file that is to be written with the + certificate signed by the root key in ```my_root_key_priv.pem```. + +* **```--cert_out=my_cert.json```**<br> + Specifies a file to write a JSON-formatted copy of the certificate into. + This file is for human inspection only and is not used by RVI or any other + scripts. + +* **```--issuer=jaguarlandrover.com```**<br> + Specifies that the certificate issuer is ```jaguarlandrover.com```. + This value is currently not used. + + +Once executed, one mandatory and one optional file will be created: + +1. **```my_cert.jwt```**<br> + This file contains the generated certificate, signed by the + private root key specified by ```--root_key=```. The content + of this file will be provided by an RVI node to prove its righ + to register and invoke services toward remote RVI nodes + + +2. **```my_cert.json```**<br> + Only created if ```--cert_out=``` has been give. Contains a human + readable JSON form of the generated root key. + + +#### Configuring RVI to use a certificate +The RVI node needs the certificates to prove its right to register and invoke +services toward remote nodes. The generated +certificate file, ```my_cert.jwt```, is placed in a directory with other +certificates owned by the device. + +The certificate directory itself is referenced from the RVI's +configuration file in ```{ rvi_core, { cert_dir, "...." }}```. + + + + +## DEVICE SELF PROVISIONING THROUGH ONE-TIME TOKENS + +This chapter describes a yet-to-be-implemented procedure +for provisioning new devices that are created outside +the control of the provisioning server. + +### Initial provisioning at app install +An device-specific key pair is generated by device and stored locally. + +The app has one pre-provisioned certificate, signed by the +root server, allowing it to invoke ```jlr.com/provisioning/init_setup``` +and ```jlr.com/provisioning/request_provisioning```. The certificate also +provides the right to register ```jlr.com/mobile/*/dm/cert_provision``` +and ```jlr.com/mobile/*/dm/signed_pub_key_provision``` +The certificate keys section, normally holding public device +keys, is empty. + +The device has the public root key pre-provisioned. + +The device has the BT/IP/SMS address of its provisioning server to +setup an initial contact. + +### Device self provisioning process +**BROKEN WILL BE REDESIGNED** + +1. Device connects to provisioning server<br> + The app is started for the first time and connects to the + provisioning server. + +2. Device sends authenticate to server<br> + The command contains no key, only a single pre-provisioned node certificate giving + the device the right to invoke and register the functions listed in + above.<br> + +3. Server sends authenticate to device<br> + The server's public device key, signed by the root private key, is + sent together with no node certificates, thus giving the server no + rights to register or invoke services with the device. + +4. Device sends a service announce to server<br> + After validating server authenticate package, the device + sends a service announce to the server. + The command contains the services ```jlr.com/mobile/1234/dm/cert_provision``` + and ```jlr.com/mobile/1234/dm/signed_pub_key_provision```, + which can be invoked by the provisioning service to install a new + certificate and signed public device key on the device. + +5. Server sends a service announce to device<br> + The announcement contains the services ```jlr.com/provisioning/init_setup``` + and```jlr.com/provisioning/request_provisioning``` . + +6. Device invokes ```jlr.com/provisioning/init_setup``` on server<br> + The sole argument is the device ID, e.g. 1234. The command is + validated by the server through the pre-provisioned cert. Since + the cert contains no device public key, any device can invoke it. + +7. Sideband token transmission from provisioning service to device<br> + The provisioning server transmits a 128 bit random token to the device + using a sideband channel such as SMS or similar. + +8. Device invokes ```jlr.com/provisioning/request_provisioning``` on server<br> + The device provides its public key, and the token received in step 7 as + arguments to the call. + +9. Provisioning service signs device public key<br> + The provisioning service checks that the token has not expired.<br> + The provisioning service checks that the token has not already been used.<br> + The public key provided in step 8 is signed by the root private key. + +10. Provisioning service creates node certificates<br> + The created cert gives the holder the right to invoke ```jlr.com/vin/ABCD/unlock```.<br> + The certificate also gives the holder the right to register ```jlr.com/mobile/1234/status.```<br> + The certificate includes the device public key provided in step 8. + The certificate is signed by the private root key.<br> + +11. Provisioning service invokes ```jlr.com/mobile/1234/dm/signed_pub_key_provision```<br> + The provisioning service invokes key provisioning service on + the device, announced by the device to the service in step 4, to + install the signed public device key on the device.<br> + The key, signed in step 9, is provided as a single argument. + The device matches the key with its existing key.<br> + The device validates the signature using the pre-provisioned public root key.<br> + The device stores the signed public key to be used in future authentication messages. + +12. Provisioning service invokes ```jlr.com/mobile/1234/dm/cert_provision```<br> + The provisioning service invokes certificate provisioning service on + the device, announced by the device to the service in step 4, to + install the certificate created in step 10.<br> + The device matches the public key of the certificate against its own public key<br> + The device validates the signature using the pre-provisioned public root key.<br> + The device stores the signed certificate to be used in future authentication messages. + + +## DEVICE - VEHICLE SESSION USE CASE + +In this use case, a mobile device, with ID 1234, connects to a +vehicle, with VIN ABCD, to unlock it. + +The vehicle has a service, registered as ```jlr.com/vin/ABCD/request_unlock```, which +unlocks the door. + +The mobile device has a service, registered as ```jlr.com/mobile/1234/confirm_unlock```, +which updates the UI with the current state of the door locks. + +The device will invoke ```jlr.com/vin/ABCD/request_unlock``` to unlock the +doors of the vehicle, while the vehicle will confirm its new unlocked +state through a invocation to ```jlr.com/mobile/1234/confirm_unlock``` + +1. Device 1234 connects to vehicle ABCD<br> + Connection is done over bluetooth, with no Internet connection. + +2. Device sends authenticate to vehicle<br> + The command contains the root-signed public device key from step 11 in the previous chapter.<br> + The command contains the root-signed certificate from step 12 in the previous chapter.<br> + The vehicle verifies the public device key signature using the pre-provisioned public root key.<br> + The vehicle verifies the certificate signature using the pre-provisioned public root key.<br> + The vehicle marks the device as being allowed to invoke ```jlr.com/vin/ABCD/request_unlock```<br> + The vehicle marks the device as being allowed to register ```jlr.com/mobile/1234/confirm_unlock```<br> + +3. Vehicle sends authenticate to device<br> + The command contains a root-signed public device key for the vehicle + The command contains a root-signed certificate, allowing the + vehicle to invoke ```jlr.com/vin/*/confirm_unlock```, and + register ```jlr.com/vin/ABCD/request_unlock```.<br> + The device verifies the public device key signature using the pre-provisioned public root key.<br> + The device verifies the certificate signature using the pre-provisioned public root key.<br> + The device marks the vehicle as being allowed to invoke ```jlr.com/mobile/1234/confirm_unlock```<br> + The device marks the vehicle as being allowed to register ```jlr.com/vin/ABCD/request_unlock```<br> + + +4. Device sends service announce to vehicle<br> + The command contains ```jlr.com/mobile/1234/confirm_unlock```.<br> + Vehicle validates that the vehicle has the right to register this + service against the certificate received in step 2. + +5. Vehicle sends service announce to device<br> + The command contains the service ```jlr.com/vin/ABCD/request_unlock```.<br> + Device validates the registration against right to register services + listed in certificate received in step 3.<br> + + +6. Device invokes ```jlr.com/vin/ABCD/request_unlock``` on vehicle<br> + The command, signed by the device private key, tells the + vehicle to unlock its doors.<br> + The certificate transmitted in step 2 proves that the device + has the right to invoke the command on the vehicle.<br> + The vehicle validates the signature using the public key in + the certificate transmitted in step 2.<br> + The vehicle unlocks the doors. + +7. Vehicle invokes ```jlr.com/mobile/1234/confirm_status``` on device<br> + The command, signed by the vehicle private key, acknowledges + to the device that the doors have been unlocked.<br> + The certificate transmitted in step 3 proves that the vehicle + has the right to invoke the command on the device.<br> + The device validates the signature using the public key in + the certificate transmitted in step 3.<br> + The device updates its UI with an unlocked icon. + + + +### Thwarting malicious RVI nodes - Illegal service invocation + +1. [standard session setup]<br> + +2. Device sends authenticate command to server<br> + The command contains the device key together with a certificate showing + that the device has the right to register register ```jlr.com/mobile/1234/receive_bitcoin```. + +3. [server validates and responds with its own authenticate]<br> + +4. Device sends false service announce to server<br> + The commands contains the service ```jlr.com/mobile/9999/receive_bitcoin```. + +5. Server rejects the service announce<br> + Since the announced service does not match the right-to-invoke section in the + certificate received in step 2, the announcement is rejected and no + invocations to ```jlr.com/mobile/9999/receive_bitcoin``` will be routed to + device. + +### Thwarting malicious RVI nodes - Stolen certificates +1. [standard session setup]<br> + +2. Device sends authenticate command to server<br> + The command contains the root-signed public device key together + with a *stolen* certificate, also root signed, showing that the device has the right + to register register ```jlr.com/mobile/1234/receive_bitcoin```.<br> + +3. Server fails to validate certificate<br> + Server tries to match public key in stolen, root signed certificate against the + root signed public key in the authenticate, and fails.<br> + Server disconnects. + +### Thwarting self-provisioning process - Replay TBD. + +The provisioning server, having matched the side band address (MSISDN) against an internal database of devices and their access rights, will create a specific certificate only for that device. + +Given that the side band network has not been compromised, I can't see how a MITM / replay attack can give a remote remote attacker the ability to gain access of the root-signed public device key and/or use a certificate. + +The token is sent as side band data to the correct device. + +The device presents token and public key when it invokes the server's request_provisioning service, proving that it has received the token. + +The server signs the public key, proven to be received from the correct device, and invoke the device's key_provision service to store it. The request is signed by the private root key, proving to the server is not spoofed. + +### Thwarting self-provisioning process - Cloned phone + +## KEY LIFECYCLE MANAGEMENT +TBD diff --git a/doc/pdf/BUILD.pdf b/doc/pdf/BUILD.pdf Binary files differnew file mode 100644 index 0000000..dc14200 --- /dev/null +++ b/doc/pdf/BUILD.pdf diff --git a/doc/pdf/CONFIGURE.pdf b/doc/pdf/CONFIGURE.pdf Binary files differnew file mode 100644 index 0000000..013da57 --- /dev/null +++ b/doc/pdf/CONFIGURE.pdf diff --git a/doc/pdf/rvi_fragmentation.pdf b/doc/pdf/rvi_fragmentation.pdf Binary files differnew file mode 100644 index 0000000..754566d --- /dev/null +++ b/doc/pdf/rvi_fragmentation.pdf diff --git a/doc/pdf/rvi_protocol.pdf b/doc/pdf/rvi_protocol.pdf Binary files differnew file mode 100644 index 0000000..95f72e1 --- /dev/null +++ b/doc/pdf/rvi_protocol.pdf diff --git a/doc/pdf/rvi_services.pdf b/doc/pdf/rvi_services.pdf Binary files differnew file mode 100644 index 0000000..b42829f --- /dev/null +++ b/doc/pdf/rvi_services.pdf diff --git a/doc/rvi_fragmentation.md b/doc/rvi_fragmentation.md index 78362c9..0992005 100644 --- a/doc/rvi_fragmentation.md +++ b/doc/rvi_fragmentation.md @@ -1,13 +1,21 @@ +<style type="text/css" media="print"> + div.pagebreak + { + page-break-before: always; + } +</style> # The RVI Core Fragmentation Protocol ## Abstract -The Remote Vehicle Interaction (RVI) system is a framework for secure interaction between -vehicles and other devices and/or cloud services. RVI is designed to be agnostic in regard -to connectivity options and intermittent connectivity. One consequence of this is that -large messages may have to be partially transmitted via one type of connection, and completed -on another. The fragmentation protocol described below allows for varying Message Transfer -Unit (MTU) and lets the remote client request fragments as needed. +The Remote Vehicle Interaction (RVI) system is a framework for secure +interaction between vehicles and other devices and/or cloud services. +RVI is designed to be agnostic in regard to connectivity options and +intermittent connectivity. One consequence of this is that large messages +may have to be partially transmitted via one type of connection, and completed +on another. The fragmentation protocol described below allows for varying +Message Transfer Unit (MTU) and lets the remote client request fragments +as needed. ## Status of This Memo @@ -41,6 +49,8 @@ Term | Meaning `Server` | Receiving side of the interaction `MTU` | Message Transfer Unit +<div class="pagebreak"></div> + ## System Overview The fragmentation support is intended to operate immediately on top of the transport diff --git a/doc/rvi_protocol.md b/doc/rvi_protocol.md index 13b561e..ce9c445 100644 --- a/doc/rvi_protocol.md +++ b/doc/rvi_protocol.md @@ -1,3 +1,9 @@ +<style type="text/css" media="print"> + div.pagebreak + { + page-break-before: always; + } +</style> Copyright (C) 2015-16 Jaguar Land Rover This document is licensed under Creative Commons @@ -49,6 +55,7 @@ Public Key Infrastructure and certificate distribution. 6. **RVI Node Discovery**<br> Allowing two unconnected RVI nodes to discover each other so that they can initiate connection. +<div class="pagebreak"></div> # OVERVIEW The RVI core protocol is the default protocol used between two RVI @@ -64,7 +71,6 @@ encoder/decoder to transmit JSON structures. All JSON structures described in this protocol are encoded as MessagePack prior to transmission to the remote peer. - ## Certificates and credentials Three types of certificates and credentials are used by the RVI Core protocol in conjunciton with TLS. See [6] for details on X.509. @@ -84,6 +90,7 @@ services that the device has right to register. Embeds the device X.509 certificate as a PEM-encoded string. Signed by root cert. +<div class="pagebreak"></div> ## Integration between TLS and RVI Core RVI Client and server X.509 certificates are exchanged when the original @@ -111,6 +118,8 @@ client-server terminology only denotes who initiates the connection <img src="images/rvi_protocol_flow.png" alt="RVI Core protocol Sequence Diagram" style="width:800"> +<div class="pagebreak"></div> + ## Authorize command The ```authorize``` command contains a list of RVI credentials, each specifying a set of services that the sender has the right to invoke on the receiving node, @@ -118,7 +127,6 @@ and a set of services that the sender has the right to register. Please see the "RVI Credentials" chapter for detailss on RVI credentials. - ## Service Announce command The ```service_authorize``` command contains a list of services available on the sender that match services listed in RVI credentials @@ -171,6 +179,8 @@ Node1 Address | Node2 Address | Connecting side to be terminated The connection is terminated regardless of its current protocol session state. +<div class="pagebreak"></div> + ## Chunking of large messages RVI Core is able to split large messages into fragments and deliver them @@ -211,6 +221,8 @@ fragment (with a starting offset of 1), and then wait for the receiving side to request more fragments using "frg-get" messages. When the sending side receives a "frg-end" message, it will forget about the message. +<div class="pagebreak"></div> + ### Encoding By default, the fragmentation logic will use the same encoding as the @@ -280,6 +292,8 @@ ZA2UwSzj67PBc5umDIAlhVRMX0zH/gLj54rfIkH5zLk= The root key above is checked in as ```priv/keys/insecure_root_key.pem```. +<div class="pagebreak"></div> + The content of the sample ```insecure_root_cert.crt``` file is: ``` @@ -349,6 +363,7 @@ G9jkH/AfO35GP3RiWQJBAJLWBlKpHf8TxT65jAwxBhd9ZOkC2w0WidbSYjX9wkkD -----END RSA PRIVATE KEY----- ``` +<div class="pagebreak"></div> The content of the sample ```insecure_device_cert.crt``` file is: @@ -427,6 +442,7 @@ An RVI credential has the following format in its native JSON state: } ``` +<div class="pagebreak"></div> The members are as follows: @@ -473,728 +489,3 @@ Parameter | Required | Description The generated ```insecure_credential.json``` and ```insecure_credential.jwt``` are checked into ```priv/credentials```. - - -# DOCUMENTATION ENDS HERE. EVERYTHING BELOW IS RESIDUAL - - -## OPEN ISSUES - -### [1] Public device key exchange as a part of handshake demasks sender - -#### Issue Sending the root signed public key during handshake -identifies the sender to an unknown remote party. - - -#### Solution -TBD - -### [2] Public device key exchange as a part of allows for replay attack - -#### Issue -Sending the root signed public key during handshake allows a malicious -remote party to replay the signed key, potentially confusing the -remote part. Please note that a replay attacker still cannot sign any -subsequent commands since they do not have the private key - - -#### Solution -Have the handshake include a random number signed by the private device key -proves that the sender also posseses the private counterpart. - -### [3] Key renewal/revocation scheme needed. - -#### Issue -A generated device or root key has no way of being revoked and/or renewed today. - - -#### Solution -Have a set of services, similar to the certificate management services, to -retire old / compromised keys and distribute new ones. - - -### [4] Self provisioning process needs to be validated - -#### Issue -The self provisioing process of a device has too many steps and edge cases. - - -#### Solution -Document a number of MITM and replay attacks to identify initial set of weaknesses. -Simplify process. - - - -### [5] Link-level encryption needs to be implemented - -#### Issue -With the current solution traffic is authenticated and authorized, but not encrypted. -While an attacker cannot modify or inject traffic, they can listen in to it. - - -#### Solution -Integrate OpenSSL TLS for session encryption, and possibly also key management. - - -### [6] Ensure that each transaction sent is unique - -#### Issue -Currently the JSON-RPC payload transaction id is just a sequential -number, which allows for an easy replay attack - - - -#### Solution -Make sure that a each transaction is persistent monotonically increased -for each transaction. -Have the server ignore transactions from a device that have already been -executed. - - -### [7] Data Flow Diagrams are needed - -#### Issue -The text-only description is opaque and hard to visualize. - -#### Solution -Create Data Flow Diagrams for all major use cases. - - - -### [8] STRIDE Application is needed - -#### Issue -There is currently no formal security model, such as STRIDE, applied -to the document - -#### Solution -Expand and formalize the "Thwarting malicious RVI nodes..." chapters -to be STRIDE compliant. - - -### [9] STRIDE Application is needed - -#### Issue -Using naked, PEM-encoded root and device keys does not provide expiry time or chains. - -#### Solution -Explore possibility of implementing full-blown certificates for public key management. - - -### [10] Non-intuitive configuration parameter names - -#### Issue -key_pair and provisioning_key are not describing what they are actually -refering to. - -#### Solution -The following name changes will be done to the configuration parameters: - -key_pair - Store single device key pair used to sign outgoing transactions. - -Will be renamed device_key_pair. - -provisioning_key - Public root key used to validate incoming certificates and device signatures. - -Will be renamed public_root_key - -### [11] Self provisioning is broken. - -#### Issue -From Rudi's review. - -1. Steps 2 through 5: What purpose do steps 2 and 3 serve? You would - typically have them if the device and the server would be - exchanging session keys that they use to project all the subsequent - transactions. Since there are no session keys, for each subsequent - transaction the data exchanged has to be signed and validated with - the PKI anyway. So, in step 4 the device would have to send the - node certificate sent in step 2, since the server cannot rely on - that the two transactions are atomic and are actually sent from the - same device, even if it says so. - -2. I think step 2 must be combined with step 4 and step 3 with step 5, - otherwise there is no security. RVI is very much asynchronous and - stateless which means with every data exchange the credentials have - to be provided.Step 6: The node cert from step 2 that gives the - device the right to invoke the service must be provided, because - technically the invocation can come from a different device. RVI is - stateless, it should be for security reasons anyway. - -3. Step 8: The data sent in step 8, the device public key and the - token, have to be encrypted with the server's public key, to make - sure that only the server can read it and that the message cannot - be intercepted by mitm to retrieve the token. Otherwise, the side - band token transmission would not make any sense. - -4. Steps 9 and 10: They should be combined. The server creates the - node certificate and signs the entire certificate, not just the - key. The very reason being that the cert includes validity claims - that need to be protected from alteration such as valid_after and - valid_until time stamps. - -5. Step 10: Why would step 10, which creates and signs the node - certificate include an authorization to invoke a service on a - vehicle, such as the example jlr.com/vin/ABCD/unlock? Those are - separate certificates as they have individual validity dates etc. - -6. Steps 11 and 12: There is no point in separating the device public - key from the node certificate. After the node certificate has been - created by the server containing the device's public key in steps 9 - and 10 (which should be one step, imho), the node certificate is - sent to the device. The device receives it and validates the - signature and if ok store the cert. - -7. All of this should just be for provisioning the device with a node - certificate. Providing devices with authorization certificates that - allow them to invoke services on vehicles is separate. The - provisioning you do once (or maybe a very few times). Providing - authorization certificates is a rather frequent action and - independent. - - -#### Solution -Redesign, bottom up. - - -### [12] Python scripts should use cryptocgraphy intead of PyCrypto - -#### Issue -Today, rvi_create_certificate.py and rvi_create_device_key.py use PyCrypto while -JWT, imported by both scripts, uses cryptography. - - -#### Solution -rvi_create_certificate.py and rvi_create_device_key.py should be rewritten -to use cryptography instead of PyCrypto. - - - -## SETTING UP NODE AUTHENTICATION AND AUTHORIZATION - -This document describes the process of setting up root keys, device -keys, and certificates. - - -## TERMINOLOGY AND COMPONENTS - -### Certificate issuer -A certificate issuer is an entity that signs device keys and -certificates with a private root key. Devices with the corresponding -public root key will be able to authenticate signed device keys and -authorize signed certificates. - -### Root key -A root key, a 4096+ bit RSA key pair, is generated once for an issuer -of certificates. The private key is stored in the certificate -issuer's servers and is not shared. The public key is manually -installed on all RVI nodes that are to trust certificates from the -certificate issuer. - -### Device key -A device key is a per-RVI node 4096+ bit RSA key pair. The private part of -the device key is stored on a host (server, embedded device, mobile device, etc) -and is not shared. The public part of the key is used in two ways: - -1. **To prove the identity of an RVI node**<br> - When two RVI nodes locate each other over a data link (WiFi, 3G, - Bluetooth, etc), they exchange an authenticate ("au") packet to - prove their identity. This packet has the public part of the device - key encoded as a JSON Web Token (JWT - RFC7519) token signed by the - private part of the root key.<br> The receiver can use its locally - stored public root key to validate that the received public device is - signed by the private root key of a trusted certificate issuer. - -2. **To prove ownership of certificates.**<br> - Embdded in the authenticate packet are one or more certificates - proving the sending RVI node's right to register and invoke - services. The certificate, signed by the private root key of the - issuer, contains the public key of the sending device encoded as - JWT structure. This public device key can be used by a - receiver to verify the signature of a service invocation requests - sent by the remote RVI node. - -### Certificate - -A certificate is a JSON Web Token, signed by the private root key of -the certificate issuer, that proves that the RVI node with a given -public device key has the right to invoke a specific set of services -and to register another set of services. - -The certificate is encoded as a JSON Web Token (JWT) signed -by the private root key. The decoded payload has the following JSON -elements. - -Command line parameters to ```rvi_create_certificate.py``` given in -parenthesis. Items marked with '*' are slated for name changes to -better reflect JWT practises and RVI semantics. - -1. **```iss``` Issuer (```--issuer```)**<br> - A domain name identifying the issuer. Currently supported but not - used. - -2. **```create_timestamp```* - Creation time stamp**<br> - Unix time, UTC, when the certificate was created. - <br><i>Will be renamed ```iat``` to comply with JWT</i> - -3. **```sources```* - Right to register (```--invoke```)**<br> - A list of full service names that the certificate grants the right to - register, allowing other, credentialed RVI nodes to invoke these - services. - <br><i>Will be renamed ```register``` to better comply with semantics.</i> - -4. **```destinations```* Right to invoke (```--register```)**<br> - A list of full service names that the certificate grants the right - to invoke on other RVI nodes who have registered them - <br><i>Will be renamed ```invoke``` to better comply with semantics.</i> - -5. **```keys``` Public device keys (```--device_key```)**<br> - Contains one or more (currently only one) public device keys in JSON - Web Key (RFC7517) format. The receiver will use this key to validate - subsequent service invocations through the signatures submitted with - the invocations. - -6. **```start```* Start time of validity period (```--start```)**<br> - Stored under the ```validity``` JSON element and specifies the Unix - time stamp UTC when the certificate becomes valid. The receiving RVI node - will check that the current time is not before the ```start``` time stamp - of the certificate. - <br><i>Will be renamed ```nbf``` to comply with JWT.</i> - -7. **```stop```* Stop time of validity period (```--stop```)**<br> - Stored under the ```validity``` JSON element and specifies the Unix - time stamp UTC when the certificae expires. The receiving RVI node will - check that the current time is not after the ```stop``` time stamp - of the certificate. - <br><i>Will be renamed ```exp``` to comply with JWT.</i> - - -## ASSUMPTIONS ON EXTERNAL COMPONENTS - -### Trustworthy time source - -In order to validate the active period for certificates (and in the -future, keys) a trustworthy time source is needed. For devices time -source is provided by GPS or the mobile network. For backend servers, -the source is provided by NTP. - -It is up to the deployment project to ensure that these sources cannot be tampered with. - -### Secure key store - -Device private keys and root private keys are expected to be securerly -stored on an RVI node through a key vault to prevent unauthorized access. - - -## SETTING UP RVI NETWORK SECURITY - GENERAL FLOW - -The general flow of events for setting up security are as follows: - -1. **Create root key pair ```rvi_create_root_key.sh```**<br> - A single root key is created by the certificate issuer. Two PEM - files are created in this process. One PEM file with the - private/public key that never leaves the issuer's trusted server, - and one public-only PEM file that is installed on every RVI node - that is to accept certificates from the issuer. - -2. **Create device key pairs ```rvi_create_device_key.py```**<br> - Each RVI node need to have its own device key pair. The device key - script will create a private/public key PEM file that never leaves - the device, a public-only PEM file that is embedded into - certificates, and a JWT file with the public device key encoded as - a JSON Web Key (JWK - RFC 7159) signed by the private root key - generated in step 1. - -3. **Create certificates ```rvi_create_certificate.py```**<br> - Certificates are generated to allow a specific RVI node (with a - given device key) to register (setup) services that it wants other - RVI nodes to invoke, and to invoke serivces registered by other RVI - nodes The certificate script creates a JWT file, signed by the root - key, that encodes the certificate described in the - [Certificate](#Certificate) chapter.<br> - Certificates are stored on the credentialed RVI node. - - -### Provisioning a root key pair - -#### Creating the root key PEM files - -The root key, consisting of a private/public RSA4096 key PEM file, and -a second PEM file with only the public portion of the key, is created -by the following command: - - rvi_create_root_key.sh -b 4096 -o my_root_key - -* **```-b 4096```**<br> - Specifies the number of bits in the key. - -* **```-o my_root_key```**<br> - Specifies the file name prefix of the two created key files. - -Once executed, two files will be created: - -1. **```my_root_key_priv.pem```**<br> - This file contains the private/public key pair that must never leave - the credit issuer's trusted environment. It will be used to sign the - JWT formatted device key and all certificates created by the - certificate issuer. - -2. **```my_root_key_pub.pem```**<br> - This file contains the public-only key that is to be installed on - RVI nodes that will accept device keys and certificates signed by the - certificate issuer. - -#### Configuring RVI to use a public root key -Only ```rvi_create_device_key.py``` and ```rvi_create_certificate.py``` use the -private root key stored in ```my_root_key_priv.pem```, generated above. -The RVI node itself is never aware of that file. - -The RVI node does need the public root key, stored in ```my_root_key_pub.pem```, -is referenced from the RVI's configuration file stored -as ```{ rvi_core, { provisioning_key, "..../my_root_key_pub.pem" }}```. - - - -### Provisioning a device key pair - -#### Creating the device key PEM files -A device key, consisting of a private/public RSA4096 key PEM file, a -second PEM file with only the public portion of the key, and a third -JWT is created by the following command: - - rvi_create_device_key.py -p my_root_key_priv.pem -o my_device_key -b 4096 - -* **```-b 4096```**<br> -Specifies the number of bits in the device key.<br> - -* **```-p my_root_key_priv.pem```**<br> -Specifies the private root key to sign the device key with when it is -stored in the JWT file (see below). The root key is created by the -```rvi_create_root_key.sh``` script.<br> - -* **```-o my_device_key```**<br> -Specifies the file name prefix of the three created device key files. - - -Once executed, three files will be created: - -1. **```my_device_key_priv.pem```**<br> - This file contains the private/public key pair that must never leave - the device's trusted environment. It will be used to sign - outgoing service invocation request. - -2. **```my_device_key_pub.pem```**<br> - This file contains the public-only key that is to be added to - certificates issued for the device by a certificate issuer. - -3. **```my_device_key_pub_sign.jwt```**<br> - This file contains the public-only key, signed by the root key, - that is to be provided as authentication when an RVI node identifies - itself toward another. The file is stored in JSON Web Token format. - - -#### Configuring RVI to use a device key - -The RVI node needs the device private/public key root key, stored in -```my_device_key_priv.pem```, is referenced from the RVI's configuration -file in ```{ rvi_core, { key_pair, "..../my_device_key_priv.pem" }}```. - - -### Provisioning a certificate - -#### Creating the certificate file -A certificate is a JWT-formatted JSON structure signed by the root -private key, is stored on an RVI node to be presented to remote node -as evidence that the sender has the right to invoke and register the -specified services. - -The certificate is created by the following command - - ./rvi_create_certificate.py --id=my_cert_id \ - --device_key=my_device_key_pub.pem \ - --start='2015-12-01 00:00:00' \ - --stop='2015-12-31 23:59:59' \ - --root_key=my_root_key_priv.pem \ - --register='jlr.com/vin/abc/unlock jlr.com/vin/abc/lock' \ - --invoke='jlr.com/backend/report jlr.com/backend/set_state' \ - --jwt_out=my_cert.jwt \ - --cert_out=my_cert.json \ - --issuer=jaguarlandrover.com - -The following arguments are provided -* **```--id=my_cert_id```**<br> - System-wide unique ID to be assigned to this certificate. - -* **```--device_key=my_device_key_pub.pem```**<br> - Specifies that the public device key, generated by ```create_device_key.py``` - shall be embedded into the generated certificate as the certificate owner. - -* **```--root_key=my_root_key_priv.pem```**<br> - Specifies that the certificate shall be signed by the private root - key generated by ```create_root_key.sh```. - -* **```--invoke='jlr.com/backend/report jlr.com/backend/set_state'```**<br> - Gives the device with the certificate-embedded public key the right to invoke - the services ```jlr.com/backend/report``` and ```jlr.com/backend/set_state```. - -* **```--register='jlr.com/vin/abc/unlock jlr.com/vin/abc/lock'```**<br> - Gives the device with the certificate-embedded public key the right to register - the services ```jlr.com/backend/report``` and ```jlr.com/backend/set_state```. - -* **```--start='2015-12-01 00:00:00'```**<br> - Specifies that the certificate shall become valid Dec 1, 2015 at - midnight. - -* **```--stop='2015-12-31 23:59:59'```**<br> - Specifies that the certificate shall expire valid Dec 31, 2015 at - 11:59:59 PM. - -* **```--jwt_out=my_cert.jwt```**<br> - Specifies the name of the JWT file that is to be written with the - certificate signed by the root key in ```my_root_key_priv.pem```. - -* **```--cert_out=my_cert.json```**<br> - Specifies a file to write a JSON-formatted copy of the certificate into. - This file is for human inspection only and is not used by RVI or any other - scripts. - -* **```--issuer=jaguarlandrover.com```**<br> - Specifies that the certificate issuer is ```jaguarlandrover.com```. - This value is currently not used. - - -Once executed, one mandatory and one optional file will be created: - -1. **```my_cert.jwt```**<br> - This file contains the generated certificate, signed by the - private root key specified by ```--root_key=```. The content - of this file will be provided by an RVI node to prove its righ - to register and invoke services toward remote RVI nodes - - -2. **```my_cert.json```**<br> - Only created if ```--cert_out=``` has been give. Contains a human - readable JSON form of the generated root key. - - -#### Configuring RVI to use a certificate -The RVI node needs the certificates to prove its right to register and invoke -services toward remote nodes. The generated -certificate file, ```my_cert.jwt```, is placed in a directory with other -certificates owned by the device. - -The certificate directory itself is referenced from the RVI's -configuration file in ```{ rvi_core, { cert_dir, "...." }}```. - - - - -## DEVICE SELF PROVISIONING THROUGH ONE-TIME TOKENS - -This chapter describes a yet-to-be-implemented procedure -for provisioning new devices that are created outside -the control of the provisioning server. - -### Initial provisioning at app install -An device-specific key pair is generated by device and stored locally. - -The app has one pre-provisioned certificate, signed by the -root server, allowing it to invoke ```jlr.com/provisioning/init_setup``` -and ```jlr.com/provisioning/request_provisioning```. The certificate also -provides the right to register ```jlr.com/mobile/*/dm/cert_provision``` -and ```jlr.com/mobile/*/dm/signed_pub_key_provision``` -The certificate keys section, normally holding public device -keys, is empty. - -The device has the public root key pre-provisioned. - -The device has the BT/IP/SMS address of its provisioning server to -setup an initial contact. - -### Device self provisioning process -**BROKEN WILL BE REDESIGNED** - -1. Device connects to provisioning server<br> - The app is started for the first time and connects to the - provisioning server. - -2. Device sends authenticate to server<br> - The command contains no key, only a single pre-provisioned node certificate giving - the device the right to invoke and register the functions listed in - above.<br> - -3. Server sends authenticate to device<br> - The server's public device key, signed by the root private key, is - sent together with no node certificates, thus giving the server no - rights to register or invoke services with the device. - -4. Device sends a service announce to server<br> - After validating server authenticate package, the device - sends a service announce to the server. - The command contains the services ```jlr.com/mobile/1234/dm/cert_provision``` - and ```jlr.com/mobile/1234/dm/signed_pub_key_provision```, - which can be invoked by the provisioning service to install a new - certificate and signed public device key on the device. - -5. Server sends a service announce to device<br> - The announcement contains the services ```jlr.com/provisioning/init_setup``` - and```jlr.com/provisioning/request_provisioning``` . - -6. Device invokes ```jlr.com/provisioning/init_setup``` on server<br> - The sole argument is the device ID, e.g. 1234. The command is - validated by the server through the pre-provisioned cert. Since - the cert contains no device public key, any device can invoke it. - -7. Sideband token transmission from provisioning service to device<br> - The provisioning server transmits a 128 bit random token to the device - using a sideband channel such as SMS or similar. - -8. Device invokes ```jlr.com/provisioning/request_provisioning``` on server<br> - The device provides its public key, and the token received in step 7 as - arguments to the call. - -9. Provisioning service signs device public key<br> - The provisioning service checks that the token has not expired.<br> - The provisioning service checks that the token has not already been used.<br> - The public key provided in step 8 is signed by the root private key. - -10. Provisioning service creates node certificates<br> - The created cert gives the holder the right to invoke ```jlr.com/vin/ABCD/unlock```.<br> - The certificate also gives the holder the right to register ```jlr.com/mobile/1234/status.```<br> - The certificate includes the device public key provided in step 8. - The certificate is signed by the private root key.<br> - -11. Provisioning service invokes ```jlr.com/mobile/1234/dm/signed_pub_key_provision```<br> - The provisioning service invokes key provisioning service on - the device, announced by the device to the service in step 4, to - install the signed public device key on the device.<br> - The key, signed in step 9, is provided as a single argument. - The device matches the key with its existing key.<br> - The device validates the signature using the pre-provisioned public root key.<br> - The device stores the signed public key to be used in future authentication messages. - -12. Provisioning service invokes ```jlr.com/mobile/1234/dm/cert_provision```<br> - The provisioning service invokes certificate provisioning service on - the device, announced by the device to the service in step 4, to - install the certificate created in step 10.<br> - The device matches the public key of the certificate against its own public key<br> - The device validates the signature using the pre-provisioned public root key.<br> - The device stores the signed certificate to be used in future authentication messages. - - -## DEVICE - VEHICLE SESSION USE CASE - -In this use case, a mobile device, with ID 1234, connects to a -vehicle, with VIN ABCD, to unlock it. - -The vehicle has a service, registered as ```jlr.com/vin/ABCD/request_unlock```, which -unlocks the door. - -The mobile device has a service, registered as ```jlr.com/mobile/1234/confirm_unlock```, -which updates the UI with the current state of the door locks. - -The device will invoke ```jlr.com/vin/ABCD/request_unlock``` to unlock the -doors of the vehicle, while the vehicle will confirm its new unlocked -state through a invocation to ```jlr.com/mobile/1234/confirm_unlock``` - -1. Device 1234 connects to vehicle ABCD<br> - Connection is done over bluetooth, with no Internet connection. - -2. Device sends authenticate to vehicle<br> - The command contains the root-signed public device key from step 11 in the previous chapter.<br> - The command contains the root-signed certificate from step 12 in the previous chapter.<br> - The vehicle verifies the public device key signature using the pre-provisioned public root key.<br> - The vehicle verifies the certificate signature using the pre-provisioned public root key.<br> - The vehicle marks the device as being allowed to invoke ```jlr.com/vin/ABCD/request_unlock```<br> - The vehicle marks the device as being allowed to register ```jlr.com/mobile/1234/confirm_unlock```<br> - -3. Vehicle sends authenticate to device<br> - The command contains a root-signed public device key for the vehicle - The command contains a root-signed certificate, allowing the - vehicle to invoke ```jlr.com/vin/*/confirm_unlock```, and - register ```jlr.com/vin/ABCD/request_unlock```.<br> - The device verifies the public device key signature using the pre-provisioned public root key.<br> - The device verifies the certificate signature using the pre-provisioned public root key.<br> - The device marks the vehicle as being allowed to invoke ```jlr.com/mobile/1234/confirm_unlock```<br> - The device marks the vehicle as being allowed to register ```jlr.com/vin/ABCD/request_unlock```<br> - - -4. Device sends service announce to vehicle<br> - The command contains ```jlr.com/mobile/1234/confirm_unlock```.<br> - Vehicle validates that the vehicle has the right to register this - service against the certificate received in step 2. - -5. Vehicle sends service announce to device<br> - The command contains the service ```jlr.com/vin/ABCD/request_unlock```.<br> - Device validates the registration against right to register services - listed in certificate received in step 3.<br> - - -6. Device invokes ```jlr.com/vin/ABCD/request_unlock``` on vehicle<br> - The command, signed by the device private key, tells the - vehicle to unlock its doors.<br> - The certificate transmitted in step 2 proves that the device - has the right to invoke the command on the vehicle.<br> - The vehicle validates the signature using the public key in - the certificate transmitted in step 2.<br> - The vehicle unlocks the doors. - -7. Vehicle invokes ```jlr.com/mobile/1234/confirm_status``` on device<br> - The command, signed by the vehicle private key, acknowledges - to the device that the doors have been unlocked.<br> - The certificate transmitted in step 3 proves that the vehicle - has the right to invoke the command on the device.<br> - The device validates the signature using the public key in - the certificate transmitted in step 3.<br> - The device updates its UI with an unlocked icon. - - - -### Thwarting malicious RVI nodes - Illegal service invocation - -1. [standard session setup]<br> - -2. Device sends authenticate command to server<br> - The command contains the device key together with a certificate showing - that the device has the right to register register ```jlr.com/mobile/1234/receive_bitcoin```. - -3. [server validates and responds with its own authenticate]<br> - -4. Device sends false service announce to server<br> - The commands contains the service ```jlr.com/mobile/9999/receive_bitcoin```. - -5. Server rejects the service announce<br> - Since the announced service does not match the right-to-invoke section in the - certificate received in step 2, the announcement is rejected and no - invocations to ```jlr.com/mobile/9999/receive_bitcoin``` will be routed to - device. - -### Thwarting malicious RVI nodes - Stolen certificates -1. [standard session setup]<br> - -2. Device sends authenticate command to server<br> - The command contains the root-signed public device key together - with a *stolen* certificate, also root signed, showing that the device has the right - to register register ```jlr.com/mobile/1234/receive_bitcoin```.<br> - -3. Server fails to validate certificate<br> - Server tries to match public key in stolen, root signed certificate against the - root signed public key in the authenticate, and fails.<br> - Server disconnects. - -### Thwarting self-provisioning process - Replay TBD. - -The provisioning server, having matched the side band address (MSISDN) against an internal database of devices and their access rights, will create a specific certificate only for that device. - -Given that the side band network has not been compromised, I can't see how a MITM / replay attack can give a remote remote attacker the ability to gain access of the root-signed public device key and/or use a certificate. - -The token is sent as side band data to the correct device. - -The device presents token and public key when it invokes the server's request_provisioning service, proving that it has received the token. - -The server signs the public key, proven to be received from the correct device, and invoke the device's key_provision service to store it. The request is signed by the private root key, proving to the server is not spoofed. - -### Thwarting self-provisioning process - Cloned phone - -## KEY LIFECYCLE MANAGEMENT -TBD diff --git a/doc/rvi_services.md b/doc/rvi_services.md index 74f92ee..11d77da 100644 --- a/doc/rvi_services.md +++ b/doc/rvi_services.md @@ -1,10 +1,14 @@ +<style type="text/css" media="print"> + div.pagebreak + { + page-break-before: always; + } +</style> Copyright (C) 2014, 2015 Jaguar Land Rover This document is licensed under Creative Commons Attribution-ShareAlike 4.0 International. - - Remote Vehicle Interface (RVI) Core Services ============================================ @@ -105,6 +109,7 @@ The parameters are: After receiving a key the device will typically store it in its key store. +<div class="pagebreak"></div> ##### Provision Certificate @@ -154,6 +159,8 @@ The parameters are: After receiving an erase certificate request the device must remove it from its certificate store. +<div class="pagebreak"></div> + ##### Clear Certificates Erase all certificates from the device's certificate store. @@ -207,7 +214,7 @@ reject that certificate as invalid. Services to manage device configuration. -##### Read Congfiguration Variables +##### Read Configuration Variables Retrieve the value of one or more configuration variables from the device. @@ -251,7 +258,9 @@ The parameters are: * variables - An array of dictionaries with variable names and values. * value - The value of the variable. -##### Write Congfiguration Variables +<div class="pagebreak"></div> + +##### Write Configuration Variables Set the value of one or more configuration variable in the device. @@ -305,7 +314,9 @@ Sequence of events: 5. After the server has sent the last chunk it sends `finish` to the client. 6. Once the client receives the `finish` message and has assembled and verified the download it sends `download_complete` to the server with a status indicator. - + +<div class="pagebreak"></div> + #### Notify Inform client of pending file transfer. @@ -353,6 +364,8 @@ The parameters are: match the ID from the `notify` message this message is sent in response to. +<div class="pagebreak"></div> + #### Start Download Initiate the download from the server to the client. @@ -398,6 +411,8 @@ The parameters are: may not arrive in order. * msg - File chunk encoded with base64. +<div class="pagebreak"></div> + #### Finish Transmission Indication by the server to the client that the last chunk has been sent. @@ -441,6 +456,8 @@ The parameters are: match the ID from the `notify` message this message is sent in response to. +<div class="pagebreak"></div> + #### Cancel Download Tell server to cancel the download. @@ -488,7 +505,9 @@ The parameters are: * channels - An array with the data channels to subscribe to. * reporting_interval - The reporting interval in milliseconds [ms]. - + +<div class="pagebreak"></div> + #### Unsubscribe Unsubscribe from one of more data channels. This message is typically implemented @@ -544,6 +563,8 @@ The parameters are: JSON data type. In particular `value` can be a dictionary in itself, as it is with the `location` channel. +<div class="pagebreak"></div> + Currently defined channels: | Channel | Description | Value Data Type | @@ -595,7 +616,8 @@ The parameters are: ```r2_lt``` and ```r2_rt``` are row two (rear) doors.<br> ```trunk``` is the rear trunk.<br> ```hood``` is the rear hood. - + +<div class="pagebreak"></div> #### Start / Stop Engine @@ -640,6 +662,8 @@ The parameters are: ```open``` open the trunk.<br> ```close``` close the trunk. +<div class="pagebreak"></div> + #### Horn Activate the horn. @@ -815,6 +839,8 @@ will be listed. } } +<div class="pagebreak"></div> + The parameters are: * windows - List each window with its current position. |