path: root/doc/rvi_protocol.md

Copyright (C) 2015 Jaguar Land Rover

This document is licensed under Creative Commons
Attribution-ShareAlike 4.0 International.

# RVI CORE PROTOCOL
This document describes the core protocol between two RVI nodes.

# STANDARDS USED
[1] Transport Layer Security - TLS (link)[https://tools.ietf.org/html/rfc5246]<br>
[2] JSON Web Token RFC7519- JWT (link)[https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32]<br>
[3] MessagePack - (link)[http://msgpack.org/index.html]<br>
[4] base64url - (link)[https://en.wikipedia.org/wiki/Base64)<br>
[5] Transport Layer Security (TLS) - (link)[https://en.wikipedia.org/wiki/Transport_Layer_Security]<br>
[6] X.509 Certificates - (link)[https://en.wikipedia.org/wiki/X.509]<br>

# FEATURES COVERED BY PROTOCOL
1. **Authroization**<br>
Prove to the remote RVI node that the local RVI node has the right to
invoke a set of services, and the right to register another set of services.

2. **Service Discovery**<br>
Announce to the remote RVI node local RVI services which the remote node
is authorized to invoke.

3. **Service Invocation**<br>
Invoke services on remote RVI nodes.

# FEATURES NOT COVERED BY PROTOCOL
For all but the last item, TLS 1.2 [5] an be used as an underlying
protocol to provide the features lacking in RVI Core protocol.

1. **Authentication**<br>
Prove the identity oof a local RVI node to the remote RVI node.

2. **Encryption**<br>
Encrypt data between two RVI nodes to avoid eavesdropping.

3. **Replay attack protection**<br>
Replay an earlier RVI Core protocol session to engage with an RVI node again.

4. **Man in the middle attack protection**<br>
Terminate an RVI Core protocol connection, modify incoming data and forward it
to its original destination.

5. **Key Management**<br>
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.


# OVERVIEW
The RVI core protocol is the default protocol used between two RVI
nodes once they have become aware of each other's presence.

The stack schematics is shown below.

<img src="rvi_protocol_stack.png" alt="RVI Core protocol Stack">

## RVI Core protocol codec
The RVI core protocol uses MessagePack [3] as its
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.

1. **Root certificate [X.509]**<br>
Generated by a trusted provisioning server and pre-provisioned on all
RVI nodes. Self signed. Used to sign all RVI certificates.
Used to sign all device certs.

2. **Device certificate (X.509)**<br>
Per-device certificate.  Signed by root cert. Used by TLS for initial
authentication.

3. **RVI credentials (JWT)**<br>
Describes the services that the device has the right to invoke and the
services that the device has right to register.
Embeds the device X.509 certificate as a PEM-encoded string.
Signed by root cert.


## Integration between TLS and RVI Core RVI
Client and server X.509 certificates are exchanged when the original
TCP connection is upgraded to TLS.  Once a X.509 certificate has
been validated by the receiving party party, it will be matched
against the PEM-encoded X.509 certificate embedded in received
RVI credentials.

The figure below shows how this is done.

<img src="rvi_protocol_x509_credential.png" alt="X.509 - RVI Protocol integration">

## JSON Web token usage
JSON Web Tokens (JWT) [2] are used to encode RVI credentials, which are
signed by the root x.509 certificate.

# PROTOCOL FLOW

## Sequence Diagram

The diagram below outlines the sequence between the client and the server.
Please note that the protocol is fully symmetrical and that the
client-server terminology only denotes who initiates the connection
(client), and who receives that connection (server).

<img src="rvi_protocol_flow.png" alt="RVI Core protocol Sequence Diagram" style="width:800">

## 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,
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
received from the remote party.

## Message command
The ```message``` command contains a service name and a number of
arguments to be presented to the corresponding service at the
receiving end.  This is an asynchronous command that does not expect
an answer. Replies, publish/subscribe, and other higher-level
functions are (for now) outside the scope of the RVI Core protocol.

## Double connect resolution
There is a risk that two parties try to initiate a connection to each
other in a race condition, creating two connections between them, as
shown below.

Connection 1 | Connection 2
:------:|:------:
<img src="rvi_protocol_double_connect1.png" alt="RVI Core protocol Double Connect" style="width:400"> | <img src="rvi_protocol_double_connect2.png" alt="RVI Core protocol Double Connect" style="width:400">

A double connect can be detected by either side by checking if the
remote peer address already has a connection established.

In the diagram above, both the client and the server will initite a connection
to the other node at the same time.

Shortly afterwards, both will receive an incoming connection from the
other node.

By comparing the incoming connection's peer address against all other
connections' peer addresses, a match will be found in the outbound
connection just initiated.

Once a double connect has been detected, an implicit agreement is
reached to abort the connection initiated by the RVI node with the highest
address. If both RVI nodes share the same address (i.e. they
run on the same host), the connection with the highest source port is
aborted.

Below is a table with a number of double connect scenarios, showing which
connection would be termianted.

Node1 Address         | Node2 Address       | Connecting side to be terminated
----------------------|---------------------|------------------------------------
23.200.227.113:12831  | 144.63.252.10:33829 | Node2
192.26.92.30:11102    | 192.52.92.31:9884   | Node2
192.26.92.30:11102    | 192.52.92.30:11101  | Node1

The connection is terminated regardless of its current protocol
session state.

## Chunking of large messages

RVI Core is able to split large messages into fragments and deliver them
reliably to the receiver; if the receiving end is an RVI node, re-assembly
is performed automatically. The fragmentation logic is called at the data link
level, so all messages, including RVI Core handshake messages, can be
fragmented.

The protocol is as follows:

<img src="rvi_protocol_frag1.png" alt="RVI Core fragmentation Sequence Diagram" style="width:800">

### Enabling fragmentation

Fragmentation can be turned on either per data link type, or per message.

The two options that affect fragmentation are

* "reliable" (true | false): One fragment containing the whole message is
sent, and acknowledged with a "frg-end" message. This effectively enables
reliable message delivery.

* "max_msg_size" (Bytes): this specifies a maximum window size. RVI Core will
try to stay within the window size including the framing overhead, but this
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".

**TODO**: Introduce timers. Currently there are none.

### Re-assembly

The receiving side is responsible for re-assembling the message and detect
holes (missing fragments). The sending side will only the first
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.

### Encoding

By default, the fragmentation logic will use the same encoding as the
data link layer, but this is configurable. RVI Core currently supports
JSON and msgpack encoding. Of these two, msgpack is more efficient and
predictable for encoding binary data.

The RVI Core data link layers detect the encoding on a per-message basis.
This is possible, as all RVI Core messages are either structs (JSON) or
maps (msgpack), and these encodings are distinguishable on the first
non-whitespace byte.

Configuring fragmentation encoding in RVI Core is done for the specific
data link module, e.g.

```
	{ data_link,
	  [ { dlink_tcp_rpc, gen_server,
	      [
                { frag_opts, {rvi_data_msgpack, []} },
		{ json_rpc_address, { 192.168.1.32, 8806 } },
		{ server_opts, [ { port, 8807 }]},
		{ persistent_connections, [ "192.168.1.10:8807" ]}
	      ]
	    }
	  ]
	}
```

# PROTOCOL DEFINITION
This chapter describes the protocol message formats and how the various fields are used.

For all examples below the following certifcates are used:

## Sample root certificate
The self signed root certificate used in the examples throughout this
document was generated using the following commands:

```Shell
# Create root key and cert signing request
openssl genrsa -out insecure_root_key.pem 1024

# Create a self-signed root CA certificate, signed by the root key created above
openssl req -x509 -new -nodes -key insecure_root_key.pem -days 365 -out insecure_root_cert.crt
```

The content of the sample ```insercure_root_key.pem``` private key
file, which has no password protection, is:

```
-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQDg5A1uZ5F36vQEYbMWCV4wY4OVmicYWEjjl/8YPA01tsz4x68i
/NnlMNalqpGCIZ0AwqGI5DZAWWoR400L3SAmYD6sWj2L9ViIAPk3ceDU8olYrf/N
wj78wVoG7qqNLgMoBNM584nlY4jy8zJ0Ka9WFBS2aDtB3Aulc1Q8ZfhuewIDAQAB
AoGAfD+C7CxsQkSc7I7N0q76SuGwIUc5skmUe6nOViVXZwXH2Or55+qqt+VzsbO7
EJphk7n0ZR0wm/zKjXd3acaRq5j3fOyXip9fDoNj+oUKAowDJ9vub0NOPpU2bgb0
xDnDeR0BRVBOTWqrkDeDPBSxw5RlJunesDkamAmj4VXHHgECQQDzqDtaEuEZ7x7d
kJKCmfGyP01s+YPlquDgogzAeMAsz17TFt8JS4RO0rX71+lmx7qqpRqIxVXIsR58
NI2Th7tRAkEA7Eh1C1WahLCxojQOam/l7GyE+2ignZYExqonOOvsk6TG0LcFm7W9
x39ouTlfChM26f8VYAsPxIrvsDlI1DDCCwJBAITmA8lzdrgQhwNOsbrugLg6ct63
kcuZUqLzgIUS168ZRJ1aYjjNqdLcd0pwT+wxkI03FKv5Bns6sGgKuhX3+KECQFm/
Z93HRSrTZpViynr5R88WpShNZHyW5/eB1+YSDslB1FagvhuX2570MRXxybys8bXN
sxPI/9M6prI8AALBBmMCQD+2amH2Y9ukJy10WuYei943mrCsp1oosWjcoMADRCpj
ZA2UwSzj67PBc5umDIAlhVRMX0zH/gLj54rfIkH5zLk=
-----END RSA PRIVATE KEY-----
```

The root key above is checked in as ```priv/sample_keys/insecure_root_key.pem```.

The content of the sample ```insecure_root_cert.crt``` file is:

```
-----BEGIN CERTIFICATE-----
MIICUjCCAbugAwIBAgIJAMI080XZPsPUMA0GCSqGSIb3DQEBCwUAMEIxCzAJBgNV
BAYTAlVTMQ8wDQYDVQQIDAZPcmVnb24xETAPBgNVBAcMCFBvcnRsYW5kMQ8wDQYD
VQQKDAZHRU5JVkkwHhcNMTUxMTI3MjMxMTQ0WhcNMTYxMTI2MjMxMTQ0WjBCMQsw
CQYDVQQGEwJVUzEPMA0GA1UECAwGT3JlZ29uMREwDwYDVQQHDAhQb3J0bGFuZDEP
MA0GA1UECgwGR0VOSVZJMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDg5A1u
Z5F36vQEYbMWCV4wY4OVmicYWEjjl/8YPA01tsz4x68i/NnlMNalqpGCIZ0AwqGI
5DZAWWoR400L3SAmYD6sWj2L9ViIAPk3ceDU8olYrf/Nwj78wVoG7qqNLgMoBNM5
84nlY4jy8zJ0Ka9WFBS2aDtB3Aulc1Q8ZfhuewIDAQABo1AwTjAdBgNVHQ4EFgQU
4Sz8rAMA+dHymJTlZSkap65qnfswHwYDVR0jBBgwFoAU4Sz8rAMA+dHymJTlZSka
p65qnfswDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQsFAAOBgQDFOapf3DNEcXgp
1u/g8YtBW24QsyB+RRavA9oKcFiIaHMkbJyUsOergwOXxBYhduuwVzQQo9P5nR0W
RdUfwtE0GuaiC8WUmjR//vKwakj9Bjuu73ldYj9ji9+eXsL/gtpGWTIlHeGugpFs
mVrUm0lY/n2ilJQ1hzBZ9lFLq0wfjw==
-----END CERTIFICATE-----
```

The root certificate above is checked in as ```priv/sample_certificates/insecure_root_key.pem```.


**DO NOT USE THE KEYS AND CERTIFICATES ABOVE IN PRODUCTION!<br>
ANY PRODUCTION KEYS SHOULD BE GENERATED BY THE ORGANIZATION AND BE 4096 BITS LONG.**

## Sample device certificate

The sample device x.509 certificate, signed by the root certificate above,
was generated with the following command:

```Shell
# Create the device key. In production, increase the bit size to 4096+
openssl genrsa -out insecure_device_key.pem 1024

# Create a certificate signing requestsigning request
openssl req -new -key insecure_device_key.pem -out insecure_device_cert.csr

# Sign the signing request and creaqte the root_cert.crt file
openssl x509 -req -days 365 -in insecure_device_cert.csr \
             -CA insecure_root_cert.crt -CAkey insecure_root_key.pem \
             -set_serial 01 -out insecure_device_cert.crt
```


The ```insecure_device_cert.csr``` intermediate certificate signing
request can be deleted once the three steps above have been executed.

The content of the sample ```insercure_device_key.pem``` private key
file, which has no password protection, is:

```
-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQCbb4jPAESKxarj3NJsgfQbhfTHZAP9kmram2TFnkzlCRxq4wQx
BDC0O85PAMgZou0armGGbOu0si4cpVRioerCQJXnMWx1MI+3GUktW5ijI3ui+tYC
sMQZtjSBVNXFZdoyZU2lPVWITOMZOe8o9vJ5DcUmFj9b2xV9jQ19oh+2+QIDAQAB
AoGAVCYV0rs6YEaTNbke0k+ocB4dXrTu1CCoaKEn9TS2PGiqUdOFOWQjWe/myS6L
JhXmd0Ng2P2uvayY+jknbh5qkNeEgTDhXJlAjiXlCADYArhgib+evRHgKz7RLTjX
tGklbmc7oECTEpjkchJC5XcJhXzHCIjroyOJvBuAVa+SeAECQQDNC+KW7fTKQpiG
YNGIt5MxCMjRparLz0fWod9J9U56wrWzU9Rnb7h9iwzTEJUEcVl9z8rnUdWtYQ8X
3lsz5cDhAkEAwg+kDWbLtXWlIvXhhla7q0+RfKb8vu/gXnkXJa6rcJdJztKRbP3b
9fehVeu9m+1+abahjC1zmQimwd2QVc8BGQJADbtfCGaVPzpoho9TWQmaRO1mrYuf
vZh7IiejEYvpHpWNn53cmrTDsTyvti7lG/APYzqYRxeW7M6UOS/+AaLAYQJAJbEW
AwhZPphoB59MO2RzNPXSYyyn4IoEwTSxuz7uy4KG8mXRmyK/a0m6i06rWDLLn8q6
G9jkH/AfO35GP3RiWQJBAJLWBlKpHf8TxT65jAwxBhd9ZOkC2w0WidbSYjX9wkkD
38K7ZDm1LSIR69Ut6tdwotkytXvDniOMPY6ENar5IUs=
-----END RSA PRIVATE KEY-----
```


The content of the sample ```insecure_device_cert.crt``` file is:

```
-----BEGIN CERTIFICATE-----
MIIB8zCCAVwCAQEwDQYJKoZIhvcNAQELBQAwQjELMAkGA1UEBhMCVVMxDzANBgNV
BAgMBk9yZWdvbjERMA8GA1UEBwwIUG9ydGxhbmQxDzANBgNVBAoMBkdFTklWSTAe
Fw0xNTExMjcyMzE0NTJaFw0xNjExMjYyMzE0NTJaMEIxCzAJBgNVBAYTAlVTMQ8w
DQYDVQQIDAZPcmVnb24xETAPBgNVBAcMCFBvcnRsYW5kMQ8wDQYDVQQKDAZHRU5J
VkkwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJtviM8ARIrFquPc0myB9BuF
9MdkA/2SatqbZMWeTOUJHGrjBDEEMLQ7zk8AyBmi7RquYYZs67SyLhylVGKh6sJA
lecxbHUwj7cZSS1bmKMje6L61gKwxBm2NIFU1cVl2jJlTaU9VYhM4xk57yj28nkN
xSYWP1vbFX2NDX2iH7b5AgMBAAEwDQYJKoZIhvcNAQELBQADgYEAhbqVr9E/0M72
9nc6DI+qgqsRSMfoyvA3Cmn/ECxl1ybGkuzO7sB8fGjgMQ9zzcb6q1uP3wGjPioq
MymiYYjUmCTvzdvRBZ+6SDjrZfwUuYexiKqI9AP6XKaHlAL14+rK+6HN4uIkZcIz
PwSMHih1bsTRpyY5Z3CUDcDJkYtVbYs=
-----END CERTIFICATE-----
```

These files are checked into ```priv/sample_certifcates``` and ```priv/sample_keys```.

**DO NOT USE THE KEYS AND CERTIFICATES ABOVE IN PRODUCTION!<br>
ANY PRODUCTION KEYS SHOULD BE GENERATED BY THE ORGANIZATION AND BE 4096 BITS LONG.**


## RVI credentials format

A credential is a JWT-encoded JSON structure, signed by the root X.509
certificate's private key, describing the rights that the sender
has. A received RVI credential is validated as follows.

1. **Receive remote party's X.509 device certificate**<br>
The TLS handshake process will exchange the X.509 certificates setup in
the previous chapter.

2. **Validate remote party's X.509 device certificate**<br>
The received device X.509 certificate has its signature validated by the
root X.509 certificate that is pre-provisioned in all RVI nodes.<br>
The receiver now knows that the remote RVI node has an identiy
generated by a trusted provsioning server using the private root key.

3. **Receive one or more RVI credentials**<br>
Each credential is encoded as JWT, signed by the root X.509 certificate.

4. **Validate each RVI credential signature**<br>
The root X.509 certificate is used to validate the signature of each
received RVI credential. <br>
A successful validation proves that the certificate was generated by a
trusted provisioning server using the private root key.

5. **Validate the credential-embedded X.509 device certificate**<br>
Each received RVI credential will have its embedded device X.509
certificate compared with the device X.509 certificate received in
step 1 above.<br>
A match proves that the certificate was generated by a trusted provisioning
server explictly for the RVI node at the remote end.

An RVI credential has the following format in its native JSON state:

```JSON
{
    "create_timestamp": 1439925416,
    "right_to_invoke": [
        "jlr.com/vin/"
    ],
    "right_to_register": [
        "jlr.com/backend/sota"
    ],
    "id": "insecure_cert",
    "iss": "jaguarlandrover.com",
    "device_cert": "",
    "validity": {
        "start": 1420099200,
        "stop": 1925020799
    }
}
```


The members are as follows:

Member              | Description
--------------------|---------------------
create\_timestamp   | Unix timestamp of when the credential was created
right\_to\_invoke   | A list of service prefixes that the sender has the right to invoke on any node that has registered matching services that start with the given string(s).
right\_to\_register | A list of services that the sender has the right to to register for other nodes to invoke.
id                  | A system-wide unique identifier for the credential.
iss                 | The issuing organization.
device_certificate  | The PEM-encoded device X.509 certificate to match against the sender's TLS certificate.
validity.start      | The Unix timestamps when the credential becomes active.
validity.stop       | The Unix timestamps when the credential becomes inactive.

## Generating RVI credentials

To create a credential, tie it to a device X.509 certificate, and sign it with a root X.509 certificate private key, the following command is used:


```Shell
rvi_create_credential.py --cred_out="insecure_credential.json" \
                         --jwt_out='insecure_credential.jwt' \
                         --id="xxx" \
                         --issuer="genivi.org" \
                         --root_key=insecure_root_key.pem \
                         --device_cert=insecure_device_cert.crt \
                         --invoke='genivi.org/' \
                         --register='genivi.org/'
```

The following command line parameters are accepted:

Parameter      | Required | Description
-------------- | -------- | ---------
--cred\_out    | No       | Output file containing the JSON-formatted un-encoded credential.
--jwt\_out     | Yes      | JWT-encoded, JSON-formatted, root keyp-signed credential.
--issuer       | Yes      | Organization that issued the credential.
--root\_key    | Yes      | Private, PEM-encoded root key to sign the credential. Must be the same key used to sign the root X.509 certificate.
--device\_cert | Yes      | The PEM-encoded device X.509 certificate to embed into the credential as the device_cert member.
--invoke       | Yes      | Space separated list (within quotes) of RVI service prefixes that the owner of the credential has the right to invoke.
--register     | Yes      | Space separated list (within quotes) of RVI service prefixes that the owner of the credential has the right to register for others to call (with the right credential).
--start        | No       | The Unix timestamps when the credential becomes active.
--stop         | No       | The Unix timestamps when the credential becomes inactive.

The generated ```insecure_credential.json```
and ```insecure_credential.jwt``` are checked into ```priv/sample_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