First shot at security

1 files changed, 106 insertions, 68 deletions

diff --git a/doc/rvi_security.md b/doc/rvi_security.md
index 9690c6e..700040a 100644
--- a/doc/rvi_security.md
+++ b/doc/rvi_security.md
@@ -138,10 +138,10 @@ by the following command:
     rvi_create_root_key.sh -b 2048 -o my_root_key
 
 * ```-b 2048```<br>
-Specifies the number of bits in the key.
+  Specifies the number of bits in the key.
 
- ```-o my_root_key``` specifies the file name prefix of the two
-created key files.
+* ```-o my_root_key```<br>
+  Specifies the file name prefix of the two created key files.
 
 Once executed, three files will be created:
 
@@ -306,29 +306,29 @@ configuration file in ```{ rvi_core, { cert_dir, "...." }}```.
 This chapter describes a yet-to-be-implemented procedure
 for provisioning new devices 
 
-#### Initial provisioning at app install
+## Initial provisioning at app install
 An device-specific key pair is generated by device and stored locally.
-The public part of the key will be signed by its private counterpart.
 
 The app has one pre-provisioned node certificate, signed by the
-root server, allowing it to invoke jlr.com/provisioning/setup.
-The certificate has an empty keys section, normally used to hold
-public device keys.
+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/key_provision``` 
+The certificate keys section, normally holding public device
+keys, is empty.
 
 The device has the IP address of its provisioning server.
 
-#### Device setup process
+## Device setup process
 
 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 public device keykey and the single,
-   pre-provisioned node certificate giving the device the right to
-   invoke ```jlr.com/provisioning/setup``` and the
-   right to register ```jlr.com/mobile/123456/dm/cert_provision```.<br>
-   See [Device Management](#device-management) for details.
+   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
@@ -338,99 +338,137 @@ The device has the IP address of its provisioning server.
 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 single service ```jlr.com/mobile/123456/dm/cert_provision```,
+   The command contains the services ```jlr.com/mobile/1234/dm/cert_provision```
+   and  ```jlr.com/mobile/1234/dm/key_provision```,
    which can be invoked by the provisioning service to install a new
-   certificate on the device. 
+   certificate and signed public device key on the device. 
 
 5. Server sends a service announce to device<br>
-   The command contains the service ```jlr.com/provisioning/setup```.
+   The announcement contains the services ```jlr.com/provisioning/init_setup```
+   and```jlr.com/provisioning/request_provisioning``` .
 
-6. Device invokes ```jlr.com/provisioning/setup``` on server<br>
+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.
-
-7. 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 is signed by root cert and encrypted with device public key from step 2.<br>
-   The certificate includes the device public key provided in step 2.
+   validated by the server through the pre-provisioned cert. Since
+   the cert contains no device public key, any device can invoke it.
 
-8. Sideband token transmission from provisioning service to device<br>
+7. Sideband token transmission from provisioning service to device<br>
    The provsioning server transmits a 128 bit random token to the device
    using a sideband channel such as SMS or similar.
 
-10. Device invokes ```jlr.com/provisioning/request_certificate``` on server<br>
-   The device provides its public key and the token received in step 9 as
+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.
 
-11. Provisioning service invokes ```jlr.com/mobile/123456/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 7.
+9. Provisioning service signs device public key<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>
 
-12. Device unpacks and stores certificate<br>
-The device decrypts the certificate using its private key, validates
-the signature against a locally installed root certificate.
+11. Provisioning service invokes ```jlr.com/mobile/1234/dm/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 authentication / authorization.<br>
+# DEVICE 
 
 1. Device connects to vehicle ABCD<br>
-Connection is done over bluetooth, with no Internet connection.
+   Connection is done over bluetooth, with no Internet connection.
 
 2. Device sends authenticate to vehicle<br>
-The command contains the auth cert together with the received node
-certificate, proving that it has the right to invoke  ```jlr.com/vin/ABCD/unlock```.
-It also proves that the device has the right to register
-<br> ```jlr.com/mobile/1234/status```.
+   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/unlock```<br>
+   The vehicle marks the device as being allowed to register ```jlr.com/mobile/1234/status```<br>
 
 3. Vehicle sends authenticate to device<br>
-The server's auth cert (server public key) is sent, together with a
-pre-provisioned node certificate giving it the rights to register  ```jlr.com/vin/ABCD/unlock```.<br>
-The certificate also gives the vehicle the right to invoke ```jlr.com/mobile/*/status```.
+   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/*/status```, and register ```jlr.com/vin/ABCD/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/status```<br>
+   The device marks the vehicle as being allowed to register ```jlr.com/vin/ABCD/unlock```<br>
+
 
 4. Device sends service announce to vehicle<br>
-The command contains ```jlr.com/mobile/1234/status```.<br>
-Vehicle validates that the vehicle has the right to register this
-service against the certificate received in step 2.
+   The command contains ```jlr.com/mobile/1234/status```.<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/unlock```.<br>
-Device validates the registration against right to register services
-listed in certificate received in step 3.
+   The command contains the service ```jlr.com/vin/ABCD/unlock```.<br>
+   Device validates the registration against right to register services
+   listed in certificate received in step 3.
 
 6. Device sends service announce to vehicle<br>
-The command contains the service ```jlr.com/mobile/1234/status```.<br>
-Vehicle validates the registration against right to register services
-listed in certificate received in step 2.
+   The command contains the service ```jlr.com/mobile/1234/status```.<br>
+   Vehicle validates the registration against right to register services
+   listed in certificate received in step 2.
 
 7. Vehicle invokes ```jlr.com/mobile/1234/status``` on device<br>
-Command contains current state (locked/unlocked, etc) that is used to
-update device UI.
+   The command, signed by the vehicle private key, contains current
+   state (locked/unlocked, etc) that is used to update device UI.<br>
+   The device validates the signature using the public key in
+   the certificate transmitted in step 3.<br>
+   The device updates its status with the received state.
+
 
 8. Device invokes ```jlr.com/vin/ABCD/unlock``` on vehicle<br>
-Vehicle validates the right to invoke against certificate received in
-step 2.
+   The command, signed by the device private key, tells the
+   vehicle to unlock its doors.<br>
+   The vehicle validates the signature using the public key in
+   the certificate transmitted in step 2.<br>
+   The vehicle unlocks the doors.
 
-### Thwarting malicious RVI nodes
+## Thwarting malicious RVI nodes - Illegal service invocation
 
-1. [standard session setup]
+1. [standard session setup]<br>
 
 2. Device sends authenticate command to server<br>
-The command contains the auth cert together with a node cert showing
-that the device has the right to register register ```jlr.com/mobile/1234/receive_bitcoin```.
+   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 responds with its own authenticate]
+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```.
+   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 service 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.
+5. Server rejects the service announce<br>
+   Since the announced service does not match the service 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.