{ "jlr.com/backend/", [
+ { "genivi.org/backend/", [
{ proto_json_rpc, { dlink_tcp_rpc, [ { target, "38.129.64.31:8807" } ]}}
]}
]}
This rule specifies that any message to a service starting
-with `jlr.com/backend` shall first be encoded using `proto_json_rpc`,
+with `genivi.org/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
+module will be instructed to send all messages targeting `genivi.org/backend/...` to the
IP-address:port `38.129.64.31:8807`.
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 `genivi.org/vin/`, add the
following rule.
@@ -474,10 +484,10 @@ following rule.
{ "", [
{ proto_json_rpc, dlink_tcp_rpc}
]},
- { "jlr.com/backend/", [
+ { "genivi.org/backend/", [
{ proto_json_rpc, { dlink_tcp_rpc, [ { target, "38.129.64.31:8807" } ]}}
]},
- { "jlr.com/vin/", [
+ { "genivi.org/vin/", [
{ proto_json_rpc, { dlink_tcp_rpc, [ broadcast, { interface, "wlan0" } ] } },
{ proto_json_rpc, { dlink_3g_rpc, [ initiate_outbound ]} },
{ proto_sms_rpc, { dlink_sms_rpc, [ { max_msg_size, 140 } ] } }
@@ -487,10 +497,10 @@ following rule.
-This rule specifies that any message to a service starting
-with `jlr.com/vin` shall first be encoded using the protocol - data
+This rule specifies that any message to a service starting
+with `genivi.org/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
+broadcasts shall be used (through `wlan0` and `broadcast`) to
find other vehiclces.
If that does not work, a 3G connection to the vehicle shall be
@@ -506,7 +516,7 @@ maximizing message size to 140 bytes.
# SPECIFY SERVICE EDGE URL #
The Service Edge URL is that which will be used by locally connected
-services to interact, through JSON-RPC, with the RVI node.
+services to interact, through JSON-RPC, with the RVI node.
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
@@ -529,8 +539,8 @@ An example entry is gven below:
...
{ components, [
...
- { service_edge, [
- { service_edge_rpc, json_rpc, [
+ { service_edge, [
+ { service_edge_rpc, json_rpc, [
{ json_rpc_address, { "127.0.0.1", 8801 } },
{ websocket, [ { port, 8808}]}
]}
@@ -570,8 +580,8 @@ external node address chapter:
{ components, [
...
- { service_edge, [
- { service_edge_rpc, json_rpc, [
+ { service_edge, [
+ { service_edge_rpc, json_rpc, [
{ json_rpc_address, { "127.0.0.1", 8801 } },
...
]}
@@ -587,7 +597,7 @@ external node address chapter:
]}
]},
{ authorize, [
- { authorize_rpc, json_rpc, [
+ { authorize_rpc, json_rpc, [
{ json_rpc_address, { "127.0.0.1", 8804 } }
]}
]},
@@ -597,7 +607,7 @@ external node address chapter:
]}
]},
{ data_link, [
- { dlink_tcp_rpc, json_rpc, [
+ { dlink_tcp_rpc, json_rpc, [
{ json_rpc_address, { "127.0.0.1", 8806 } },
...
]}
@@ -655,8 +665,8 @@ between Servie Edge and other RVI components.
{ components, [
...
- { service_edge, [
- { service_edge_rpc, gen_server, [
+ { service_edge, [
+ { service_edge_rpc, gen_server, [
{ json_rpc_address, { "127.0.0.1", 8801 } },
...
]}
@@ -674,7 +684,7 @@ between Servie Edge and other RVI components.
{ proto_json_rpc, gen_server, [] }
]},
{ data_link, [
- { dlink_tcp_rpc, gen_server, [
+ { dlink_tcp_rpc, gen_server, [
...
]}
]}
@@ -706,8 +716,8 @@ Below is the previous configuration example with such a setup.
...
{ components, [
...
- { service_edge, [
- { service_edge_rpc, json_rpc, [
+ { service_edge, [
+ { service_edge_rpc, json_rpc, [
{ json_rpc_address, { "127.0.0.1", 8801 } },
{ websocket, [ { port, 8808}]}
]}
@@ -792,7 +802,7 @@ 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
system, the RVI application, and the configuration data generated from
@@ -808,16 +818,16 @@ The newly built product release is started using the
`rel/prod_rel/rvi` tool:
./rel/prod_rel/rvi start
-
+
Stopping is done in a similar manner:
./rel/prod_rel/rvi stop
-
+
To check if a node is up, retrieve its process ID with:
./rel/prod_rel/rvi getpid
-
+
To attach to the console of a started node in order to inspect it run:
@@ -825,7 +835,7 @@ To attach to the console of a started node in order to inspect it run:
*Note that you need to exit from the console with Ctrl-d. Pressing
-Ctrl-c will bring down the node itself.*
+Ctrl-c will bring down the node itself.*
# Loggings
@@ -834,7 +844,7 @@ To get debug output on a console, start a development release, or attach to a
production release, and set the log level manually:
1> lager:set_loglevel(lager_console_backend, debug)
-
+
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.?`.
@@ -847,16 +857,15 @@ You can configure the log level through the lager configuration entry:
{env,
[
- {lager,
- [ { handlers,
+ {lager,
+ [ { handlers,
[ {lager_console_backend, debug} ]
}
]}
...
-Additional handlers can also be added for different log destinations.
+Additional handlers can also be added for different log destinations.
See Basho's lager documentation at
[github](https://github.com/basho/lager) for details on logging.
-
diff --git a/README.md b/README.md
index ef8e0c3..485d746 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ choices.
# ADDITIONAL DOCUMENTATION AND RESOURCES#
For a high level description, with an exhaustive master use-case
-walkthrough, please see the High Level Design document
+walkthrough, please see the High Level Design document
[here](https://wiki.automotivelinux.org/_media/eg-rvi/15-456-poc-rvi-hld_reva.pdf) (**NOTE: HLD not updated to reflect RVI Core 0.5.0**)
Packages are available for some distributions. See installation
@@ -20,11 +20,11 @@ instructions for [Ubuntu](INSTALL_ubuntu.md), [Debian](INSTALL_debian.md),
and [Raspbian](INSTALL_raspbian.md).
For build instructions, please check the **build instructions**:
-[Markdown](BUILD.md) |
+[Markdown](BUILD.md) |
[PDF](doc/pdf/BUILD.pdf)
For configuration and launch instructions, please check the **configuration documentation**:
-[Markdown](CONFIGURE.md) |
+[Markdown](CONFIGURE.md) |
[PDF](doc/pdf/CONFIGURE.pdf)
For instructions on how to create RVI Core certificates, keys and credentials, please check the **certificates documentation**:
@@ -39,6 +39,9 @@ For a detailed description of the RVI Core Peer-to-peer protocol, please check t
[Markdown](doc/rvi_protocol.md) |
[PDF](doc/pdf/rvi_protocol.pdf)
+For a summary of RVI security aspects, please read the **rvi_security documentation**:
+[Markdown](doc/rvi_security.md) | [PDF](doc/pdf/rvi_security.pdf)
+
Technical RVI disussions are held at the GENIVI project mailing list:
[GENIVI](https://lists.genivi.org/mailman/listinfo/genivi-projects)
@@ -98,7 +101,7 @@ own technology.
## INTERCHANGEABILITY ##
The only fixed parts of the entire RVI project are the JSON-RPC
protocol specifications used between the components themselves and
-their connected services.
+their connected services.
GENIVI provides an RVI implementation as a starting point and a
reference. The adopting organization is free to use, rewrite, or
@@ -156,7 +159,7 @@ The robustness and scalability, in conjunction with the built-in
Erlang feature of runtime code upgrades, is a part of Erlang's
five-nines uptime design that is rapidly becoming a core requirement
of the automotive industry.
-
+
* **Proven embedded system solution**
Erlang has been adapted to operate well in embedded environments
with unreliable power, limited resources, and the need to integrate
@@ -174,7 +177,7 @@ interfacing with the RVI system.
Performance is **not** a goal of the RVI reference
implementation. Instead, code readability and component
interchangeability takes priority in order to ease design
-understanding and adoption.
+understanding and adoption.
One example is the use of JSON-RPC (over HTTP) to handle internal
communication between components in a single Erlang node.
@@ -186,29 +189,6 @@ however, would force all components of the RVI system to be
implemented in Erlang, thus severely limiting an organization's
abilities to replace individual components with their own versions.
-
-## CODE STRATEGY ##
-All code in the RVI reference implementation and its demonstrations are
-written with a minimum of complexity and "magic". Readability is
-paramount, even if it severely impacts performance and memory usage.
-
-
-All components in the RVI are kept small and distinct, with a
-well-defined JSON-RPC external interface and simple call flows.
-
-Only three external modules (lager, bert and exo) are used by the
-code, with two more (setup and edown) used for release and
-documentation management.
-
-The reason for minimizing external module usage is to make the code
-comprehensible and minimize the time a developer has to traverse
-through obscure libraries trying to understand what a specific call
-flow actually does.
-
-The entire reference implementation (as of the first alpha release) is
-2800 lines of code, broken down into six standalone modules and one
-library of shared primitive functions.
-
## JSON-RPC ##
JSON-RPC is used for all communication between components in an RVI
system, and also to communicate with services connected to it. The
diff --git a/doc/images/rvi_provisioning.png b/doc/images/rvi_provisioning.png
new file mode 100644
index 0000000..468555a
Binary files /dev/null and b/doc/images/rvi_provisioning.png differ
diff --git a/doc/msc/rvi_provisioning.msc b/doc/msc/rvi_provisioning.msc
new file mode 100644
index 0000000..ecfcf02
--- /dev/null
+++ b/doc/msc/rvi_provisioning.msc
@@ -0,0 +1,29 @@
+# Sequence diagram description
+#
+# The sequence diagram description below is translated to
+# a PNG image by mscgen (http://www.mcternan.me.uk/mscgen/)
+#
+# Recompile updated diagrams to a png image with:
+#
+# mscgen -T png -o images/rvi_provisioning.png msc/rvi_provisioning.msc
+#
+
+msc {
+ width="800";
+ "Vehicle", "Guest", "PS";
+ "Guest" => "Guest" [ label = "Create unsigned cert", ID="1" ];
+ "Guest" => "PS" [ label = "HTTPS POST: CSR(Cert) -> Signed_Cert + Cred", ID="2" ];
+ --- [ label = "Guest able to connect", ID="3" ];
+ ...;
+ "Vehicle" => "PS" [ label = "Authorize Guest [Services]", ID="4" ];
+ ...;
+ "Guest" <-> "PS" [ label = "RVI connect", ID="5" ];
+ ...;
+ "Guest" -> "PS" [ label = "{cmd:sa,stat:av,svcs:[Guest/creds]}", ID="6" ];
+ "Guest" <- "PS" [ label = "{cmd:sa,stat:av,svcs:[PS/get_creds]}", ID="7" ];
+ "Guest" -> "PS" [ label = "PS/get_creds []", ID="8" ];
+ "Guest" <- "PS" [ label = "Guest/creds [C1,...Cn]", ID="9" ];
+ --- [ label = "Guest provisioned", ID="10" ];
+ "Vehicle" <-> "Guest" [ label = "RVI Connect", ID="11" ];
+ ...;
+}
diff --git a/doc/pdf/rvi_security.pdf b/doc/pdf/rvi_security.pdf
new file mode 100644
index 0000000..8645829
Binary files /dev/null and b/doc/pdf/rvi_security.pdf differ
diff --git a/doc/rvi_protocol.md b/doc/rvi_protocol.md
index e001499..01301bd 100644
--- a/doc/rvi_protocol.md
+++ b/doc/rvi_protocol.md
@@ -133,6 +133,7 @@ and a set of services that the sender has the right to have invoked.
```json
{"cmd" : "au",
"ver" : "1.1",
+ "id" : "genivi.org/mobile/c60465c4-6324-11e6-b617-000c29690f82",
"creds": [ "eyJhbGci..." ]
}
```
@@ -149,12 +150,24 @@ received from the remote party.
```json
{"cmd" : "sa",
"stat" : "av" | "un",
+ "cost" : 1,
"svcs" : [ "genivi.com/vin/d32cef88-.../hvac/seat_heat_left", ... ]
}
```
The `"stat"` attribute can have the value `"av"` (available) or `"un"` (unavailable) and indicates the status of all services listed in `"svcs"`.
+The `"cost"` argument reflects the number of hops traversed, possibly also
+including link cost and routing cost. Normally, link cost and routing cost
+will be 1 each. An RVI node may relay a service announcement message to other
+connected nodes, provided they are authorized to invoke the services listed.
+Note that each connected node may be authorized to see a different subset of
+the included services. When relaying an announcement, the node should add
+link cost and routing cost to the received cost.
+
+A max cost should be configured, to e.g. avoid routing loops. Any service
+announcements that would exceed the max cost should not be sent.
+
## Message command
The ```message``` command contains a service name and a number of
arguments to be presented to the corresponding service at the
@@ -173,12 +186,18 @@ functions are (for now) outside the scope of the RVI Core protocol.
Note: The `"tid"` attribute is currently not checked by RVI.
The content of `Data` is parsed and then encoded according to the
-protocol used to forward the message. The modules `proto_json_rpc` and
-`proto_msgpack` expect it to be a 'struct' (or corresponding), as follows:
+protocol used to forward the message. The module `"rvi"` expects it to be
+a 'struct' (or corresponding), as follows:
```json
{"service" : ServiceName,
"timeout" : Timeout,
+ "synch" : Synch,
+ "reply_id" : ReplyId,
+ "route" : Route,
+ "files" : [F1, ... Fn],
+ "max_msg_size" : Sz,
+ "reliable" : true | false,
"parameters: Parameters
}
```
@@ -187,11 +206,44 @@ protocol used to forward the message. The modules `proto_json_rpc` and
(unix time) in seconds.
`Parameters` is a 'struct' containing named arguments to be passed to the
-service. It _can_ also contain RVI-specific arguments, named as `"rvi.Opt"`.
-Currently supported RVI options are
+service.
+
+`Synch` is a boolean, where `true` means that the service reply shall be
+routed back to the client. This is accomplished by the client-side RVI
+node creating a temporary "service" on the form `Id/rvi/int/reply/Seq`, and
+passing it along as `ReplyId`, where `Id` is the unique node id provided
+in the `"au"` message, and `Seq` uniquely allows the client node to pair
+the reply to the corresponding request.
+
+`Route` is a list (array) of node identifiers, representing the reply
+path of the message. If `Synch = false`, there is no need to maintain
+the route entry, but if it is present, any relay node should prepend
+its node id to the list before relaying the message.
+
+The `"files"` entry contains a list (array) of file objects, representing
+any attachments included in the request/message.
+
+```json
+{"cid" : Filename,
+ "hdrs" : [ { Key: Value }, ...],
+ "data" : Data
+}
+```
+
+If the client needs to refer to an attached file inside the request body,
+it can use the pattern `file:Filename`. The `"hdrs"` list, if present,
+contains HTTP headers used to pass the attachments via JSON-RPC (HTTP).
+If the target service also uses HTTP, it can elect to receive exactly the
+headers used by the client.
+
+`MaxMsgSize` indicates if the message needs to be fragmented. Note that
+the connection used may have its own `max_msg_size` setting; in that case,
+the smallest value is used.
-* `"rvi.max_msg_size"` (integer > 0)
-* `"rvi.reliable"` (true | false)
+`Reliable` indicates that, regardless of max message size setting, the
+fragmentation protocol should be used for reliable delivery, even if it
+means sending only one fragment. This offers protection against packet
+loss and message retransmission.
@@ -265,7 +317,7 @@ will currently be unreliable when using JSON encoding, due to escaping of
binary data.
When including these options in the "parameters" list of a message invocation,
-the names can be prefixed with "rvi.", e.g. "rvi.max_msg_size", or
+the names can be prefixed with "rvi.", e.g. "rvi.max_msg_size", or
"rvi.reliable".
**TODO**: Introduce timers. Currently there are none.
diff --git a/doc/rvi_security.md b/doc/rvi_security.md
index e51a18f..c97ea0a 100644
--- a/doc/rvi_security.md
+++ b/doc/rvi_security.md
@@ -1,728 +1,155 @@
-Copyright (C) 2015 Jaguar Land Rover
+
+Copyright (C) 2015-16 Jaguar Land Rover
This document is licensed under Creative Commons
Attribution-ShareAlike 4.0 International.
-# NEEDS TO BE UPDATED! TEMPORARILY SUPERSEEDED BY RVI_PROTOCOL.MD
+# RVI SECURITY
-## OPEN ISSUES
+This document summarizes security aspects of the RVI protocol and,
+in particular, the RVI Core implementation.
-### [1] Public device key exchange as a part of handshake demasks sender
+## Service Edge
-#### Issue
-Sending the root signed public key during handshake identifies the
-sender to an unknown remote party.
+The Service Edge presents an API to applications using RVI, including
+both services and service users. RVI Core supports the following
+communication methods:
+* JSON-RPC/HTTP
-#### Solution
-TBD
+* JSON-RPC/Websocket
-### [2] Public device key exchange as a part of allows for replay attack
+* DBUS
-#### 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
+Currently, no security measures are implemented on the RVI Core side,
+except for a simple peer IP whitelist in the HTTP server, which by default
+allows connections only via loopback.
+The Service Edge is responsible for validating incoming requests, as
+well as authorizing service invocations, both received via the RVI
+protocol and received via the Service Edge API.
-#### Solution
-Have the handshake include a random number signed by the private device key
-proves that the sender also posseses the private counterpart.
+RVI reserves the service prefix `NodeId/rvi/int` for internal services.
+These should not be accessible via the Service Edge.
-### [3] Key renewal/revocation scheme needed.
+## RVI Protocol
-#### Issue
-A generated device or root key has no way of being revoked and/or renewed today.
+### Legacy data link components
+Previous RVI Core versions had a number of different, mostly unsecure,
+data link components: dlink_tcp, dlink_bt (Bluetooth), dlink_sms.
+These will be removed, and only the TLS version kept.
-#### Solution
-Have a set of services, similar to the certificate management services, to
-retire old / compromised keys and distribute new ones.
+### Authentication
+RVI relies on TLS 1.2 and X.509 certificates, supporting partial-chain
+validation provided that the provisioning server's public key is installed
+on the node.
-### [4] Self provisioning process needs to be validated
+An experimental configuration option exists to support anonymous
+clients.
-#### Issue
-The self provisioing process of a device has too many steps and edge cases.
+### Authorization
+After a successful TLS upgrade, nodes exchange authorization (`"au"`)
+messages. Apart from the `"id"` attribute, which uniquely identifies the node
+(not enforced), the message includes credentials, defining which services
+the node is allowed to invoke, and which services it can accept
+invocations for.
-#### Solution
-Document a number of MITM and replay attacks to identify initial set of weaknesses.
-Simplify process.
+Each credential includes the node's public key (PEM formatted), and
+is encoded as a JSON Web Token (JWT), signed using the provisioning
+server's private key. This combination is used to ensure that the
+credential belongs to the node, and hasn't been modified since it was
+issued.
+### Service announcement
+Each node shall announce services to its connected peers, but only
+services which a peer is allowed to invoke. Service announcements from
+connected peers are forwarded to other peers which are allowed to
+invoke those services (note that the forwarded announcements may
+include only a subset of the original services).
-### [5] Link-level encryption needs to be implemented
+A hop count (`"cost"`) is included in the announcement to avoid
+announcement loops.
-#### 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.
+RVI-internal services, starting with the prefix `NodeId/rvi/int`,
+are never announced.
+### Service invocation
-#### Solution
-Integrate OpenSSL TLS for session encryption, and possibly also key management.
+When receiving a service invocation via RVI, the node must check whether
+the peer is allowed to invoke the service.
+RVI-internal services, starting with the prefix `NodeId/rvi/int`,
+are implicitly allowed. These are normally used e.g. for service
+invocation replies, are short-lived, not accessible via the
+Service Edge, and not announced.
-### [6] Ensure that each transaction sent is unique
+## Provisioning
-#### Issue
-Currently the JSON-RPC payload transaction id is just a sequential
-number, which allows for an easy replay attack
+A typical user/service provisioning flow may look like this.
+
+Detailed description:
-#### 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.
+1. Guest creates an unsigned X.509 certificate
+2. Guest sends a Certificate Signing Request (CSR) to the Provisioning Server (PS), passing the unsigned cert for signing. PS returns the cert, signed with its private key, and also creates and signs a credential file authorizing Guest to fetch further credentials from PS via the RVI protocol.
+3. Guest is now able to connect to any device that recognizes PS as Root CA, but is not yet authorized to do anything except fetch more credentials.
+4. Vehicle (owner) authorizes Guest to access certain services.
+(if supported, and so configured, PS could in the future push credentials to Guest)
+5. Guest connects to PS using RVI, authenticating itself with the newly signed certificate
+7. Since PS is authorized to use the Guest/creds service, Guest announces its availability.
+7. Since Guest has been authorized to use the PS/get_creds service, PS announces its availability.
+8. Guest calls PS/get_creds, asking for new credentials.
+9. PS calls Guest/creds, passing found credentials for Guest.
+10. Guest can now connect to Vehicle and use the authorized services.
+11. Guest connects to vehicle ...
+### Provisioning delegates
-### [7] Data Flow Diagrams are needed
+It is possible to delegate authority via the credentials:
-#### Issue
-The text-only description is opaque and hard to visualize.
+```json
+"right_to_delegate": [
+ {"right_to_invoke": ["InvPat1"],
+ "right_to_receive": ["RcvPat1"]}
+ ]
+```
-#### Solution
-Create Data Flow Diagrams for all major use cases.
+The device identified in the credential (via the `"device_cert"`) will be able to generate credentials authorizing access to services matching the given patterns. The delegation patterns themselves must be strict subsets of the patterns authorized to the device. (ISSUE: given regexp patterns, this may not be trivial to check).
+A peer receiving such a credential, needs to be prepared to accept the credential owner as a signing authority for other credentials, and must also verify that any patterns given in such credentials are proper subsets of the delegation patterns.
-### [8] STRIDE Application is needed
+## Erlang implementation
-#### Issue
-There is currently no formal security model, such as STRIDE, applied
-to the document
+Erlang relies on a virtual machine, wich 'ports' to the outside world.
+The VM is generally considered secure, except for the Distributed Erlang
+protocol, which allows any node with knowledge of a secret cookie to
+connect and essentially perform any operation on the node (i.e. no
+sandboxing).
-#### Solution
-Expand and formalize the "Thwarting malicious RVI nodes..." chapters
-to be STRIDE compliant.
+Any open ports are of course potentially insecure, although Erlang
+data types are unbounded and memory management automatic, so some
+conventional attack vectors (e.g. buffer overrun) are ineffective.
+### Distributed Erlang
-### [9] STRIDE Application is needed
+RVI Core currently uses Distributed Erlang for the `ctl` script,
+mainly to check whether a node is running, and to stop it.
+The node 'cookie' is set to a convenient value, which is a security
+issue. Any user who gains access to the Linux shell can enter the
+Erlang console with unlimited privileges.
-#### Issue
-Using naked, PEM-encoded root and device keys does not provide expiry time or chains.
+### RVI Component ports
-#### 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**
- 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.
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.**
- 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```)**
- A domain name identifying the issuer. Currently supported but not
- used.
-
-2. **```create_timestamp```* - Creation time stamp**
- Unix time, UTC, when the certificate was created.
-
Will be renamed ```iat``` to comply with JWT
-
-3. **```sources```* - Right to register (```--invoke```)**
- A list of full service names that the certificate grants the right to
- register, allowing other, credentialed RVI nodes to invoke these
- services.
-
Will be renamed ```register``` to better comply with semantics.
-
-4. **```destinations```* Right to invoke (```--register```)**
- A list of full service names that the certificate grants the right
- to invoke on other RVI nodes who have registered them
-
Will be renamed ```invoke``` to better comply with semantics.
-
-5. **```keys``` Public device keys (```--device_key```)**
- 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```)**
- 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.
-
Will be renamed ```nbf``` to comply with JWT.
-
-7. **```stop```* Stop time of validity period (```--stop```)**
- 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.
-
Will be renamed ```exp``` to comply with JWT.
-
-
-## 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```**
- 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```**
- 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```**
- 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.
- 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```**
- Specifies the number of bits in the key.
-
-* **```-o my_root_key```**
- Specifies the file name prefix of the two created key files.
-
-Once executed, two files will be created:
-
-1. **```my_root_key_priv.pem```**
- 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```**
- 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```**
-Specifies the number of bits in the device key.
-
-* **```-p my_root_key_priv.pem```**
-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.
-
-* **```-o my_device_key```**
-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```**
- 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```**
- 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```**
- 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```**
- System-wide unique ID to be assigned to this certificate.
-
-* **```--device_key=my_device_key_pub.pem```**
- 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```**
- 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'```**
- 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'```**
- 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'```**
- Specifies that the certificate shall become valid Dec 1, 2015 at
- midnight.
-
-* **```--stop='2015-12-31 23:59:59'```**
- Specifies that the certificate shall expire valid Dec 31, 2015 at
- 11:59:59 PM.
-
-* **```--jwt_out=my_cert.jwt```**
- 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```**
- 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```**
- 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```**
- 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```**
- 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
- The app is started for the first time and connects to the
- provisioning server.
-
-2. Device sends authenticate to server
- 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.
-
-3. Server sends authenticate to device
- 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
- 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
- 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
- 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
- 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
- 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
- The provisioning service checks that the token has not expired.
- The provisioning service checks that the token has not already been used.
- The public key provided in step 8 is signed by the root private key.
-
-10. Provisioning service creates node certificates
- The created cert gives the holder the right to invoke ```jlr.com/vin/ABCD/unlock```.
- The certificate also gives the holder the right to register ```jlr.com/mobile/1234/status.```
- The certificate includes the device public key provided in step 8.
- The certificate is signed by the private root key.
-
-11. Provisioning service invokes ```jlr.com/mobile/1234/dm/signed_pub_key_provision```
- 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.
- The key, signed in step 9, is provided as a single argument.
- The device matches the key with its existing key.
- The device validates the signature using the pre-provisioned public root key.
- 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```
- 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.
- The device matches the public key of the certificate against its own public key
- The device validates the signature using the pre-provisioned public root key.
- 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
- Connection is done over bluetooth, with no Internet connection.
-
-2. Device sends authenticate to vehicle
- The command contains the root-signed public device key from step 11 in the previous chapter.
- The command contains the root-signed certificate from step 12 in the previous chapter.
- The vehicle verifies the public device key signature using the pre-provisioned public root key.
- The vehicle verifies the certificate signature using the pre-provisioned public root key.
- The vehicle marks the device as being allowed to invoke ```jlr.com/vin/ABCD/request_unlock```
- The vehicle marks the device as being allowed to register ```jlr.com/mobile/1234/confirm_unlock```
-
-3. Vehicle sends authenticate to device
- 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```.
- The device verifies the public device key signature using the pre-provisioned public root key.
- The device verifies the certificate signature using the pre-provisioned public root key.
- The device marks the vehicle as being allowed to invoke ```jlr.com/mobile/1234/confirm_unlock```
- The device marks the vehicle as being allowed to register ```jlr.com/vin/ABCD/request_unlock```
-
-
-4. Device sends service announce to vehicle
- The command contains ```jlr.com/mobile/1234/confirm_unlock```.
- 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
- The command contains the service ```jlr.com/vin/ABCD/request_unlock```.
- Device validates the registration against right to register services
- listed in certificate received in step 3.
-
-
-6. Device invokes ```jlr.com/vin/ABCD/request_unlock``` on vehicle
- The command, signed by the device private key, tells the
- vehicle to unlock its doors.
- The certificate transmitted in step 2 proves that the device
- has the right to invoke the command on the vehicle.
- The vehicle validates the signature using the public key in
- the certificate transmitted in step 2.
- The vehicle unlocks the doors.
-
-7. Vehicle invokes ```jlr.com/mobile/1234/confirm_status``` on device
- The command, signed by the vehicle private key, acknowledges
- to the device that the doors have been unlocked.
- The certificate transmitted in step 3 proves that the vehicle
- has the right to invoke the command on the device.
- The device validates the signature using the public key in
- the certificate transmitted in step 3.
- The device updates its UI with an unlocked icon.
-
-
-
-### Thwarting malicious RVI nodes - Illegal service invocation
-
-1. [standard session setup]
-
-2. Device sends authenticate command to server
- 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]
-
-4. Device sends false service announce to server
- The commands contains the service ```jlr.com/mobile/9999/receive_bitcoin```.
-
-5. Server rejects the service announce
- 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]
-
-2. Device sends authenticate command to server
- 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```.
-
-3. Server fails to validate certificate
- Server tries to match public key in stolen, root signed certificate against the
- root signed public key in the authenticate, and fails.
- 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
+Early versions of RVI Core have supported replacing sub-components
+(e.g. service discovery, routing, authentication) using JSON-RPC
+interfaces for inter-component communication. These interfaces are
+unprotected, and unlikely to be useful due to the relatively high
+communication overhead. They also complicate the code. For these
+reasons, they will be removed, and components will be Erlang-only,
+relying on conventional Erlang interaction techniques.