From a113e726ec071e248f465f026d09747171d0672b Mon Sep 17 00:00:00 2001 From: Magnus Feuer Date: Tue, 10 Nov 2015 10:42:59 -0800 Subject: First stab at new protocol documentation --- doc/rvi_core.msc | 38 ++ doc/rvi_core.png | Bin 0 -> 49909 bytes doc/rvi_core_double_connect.msc | 24 ++ doc/rvi_core_double_connect.png | Bin 0 -> 19004 bytes doc/rvi_protocol.md | 814 ++++++++++++++++++++++++++++++++++++++++ doc/rvi_protocol_stack.png | Bin 0 -> 12693 bytes 6 files changed, 876 insertions(+) create mode 100644 doc/rvi_core.msc create mode 100644 doc/rvi_core.png create mode 100644 doc/rvi_core_double_connect.msc create mode 100644 doc/rvi_core_double_connect.png create mode 100644 doc/rvi_protocol.md create mode 100644 doc/rvi_protocol_stack.png (limited to 'doc') diff --git a/doc/rvi_core.msc b/doc/rvi_core.msc new file mode 100644 index 0000000..e443535 --- /dev/null +++ b/doc/rvi_core.msc @@ -0,0 +1,38 @@ +# +# +# 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 swm.msc +# + +msc { + width="1024"; + "Client", "Server"; + "Client" -> "Server" [ label = "connect" ]; + "Client" -> "Server" [ label = "authenticate( JWT ( client_pub_key, root_sign ) )" ]; + "Server" abox "Server" [ label = "Validate client public key signature using root public key" ] ; + "Client" <- "Server" [ label = "authenticate( JWT ( server_pub_key, root_sign ) )" ]; + "Client" abox "Client" [ label = "Validate server public key signature using root public key" ] ; + + "Client" -> "Server" [ label = "authorize( JWT ( [JWT (certificate, root_sign), ...] ), device_sign ) )" ]; + "Server" abox "Server" [ label = "Validate authorize signature using client public key" ] ; + "Server" abox "Server" [ label = "Validate each certificate using root public key" ] ; + "Client" <- "Server" [ label = "authorize( JWT ( [JWT (certificate, root_sign), ...] ), device_sign ) )" ]; + "Client" abox "Client" [ label = "Validate authorize signature using client public key" ] ; + "Client" abox "Client" [ label = "Validate each certificate using root public key" ] ; + + "Client" abox "Client" [ label = "Create list of services matching server certificates" ] ; + "Client" -> "Server" [ label = "service_announce( [service_name, ... ])" ]; + "Server" abox "Server" [ label = "Create list of services matching client certificates" ] ; + "Client" <- "Server" [ label = "service_announce( [service_name, ... ])" ]; + + "Client" -> "Server" [ label = "message( service_name, arguments)" ]; + + "Server" -> "Client" [ label = "message( service_name, arguments)" ]; +} + diff --git a/doc/rvi_core.png b/doc/rvi_core.png new file mode 100644 index 0000000..e696abc Binary files /dev/null and b/doc/rvi_core.png differ diff --git a/doc/rvi_core_double_connect.msc b/doc/rvi_core_double_connect.msc new file mode 100644 index 0000000..7f098e2 --- /dev/null +++ b/doc/rvi_core_double_connect.msc @@ -0,0 +1,24 @@ +# +# +# 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 swm.msc +# + +msc { + width="1024"; + "Client", "Server"; + "Client" -> "Server" [ label = "connect" ]; + "Server" -> "Client" [ textcolor="gray", linecolor="gray", label = "connect" ]; + "Client" -> "Server" [ label = "authenticate( JWT ( client_pub_key, root_sign ) )" ]; + "Client" <- "Server" [ textcolor="gray", linecolor="gray",label = "authenticate( JWT ( server_pub_key, root_sign ) )" ]; + "Client" <- "Server" [ label = "authenticate( JWT ( server_pub_key, root_sign ) )" ]; + "Client" -> "Server" [ textcolor="gray", linecolor="gray", label = "authenticate( JWT ( client_pub_key, root_sign ) )" ]; + "Client" abox "Server" [ label = "Race Condition" ] ; +} + diff --git a/doc/rvi_core_double_connect.png b/doc/rvi_core_double_connect.png new file mode 100644 index 0000000..c1dae9f Binary files /dev/null and b/doc/rvi_core_double_connect.png differ diff --git a/doc/rvi_protocol.md b/doc/rvi_protocol.md new file mode 100644 index 0000000..70e75d3 --- /dev/null +++ b/doc/rvi_protocol.md @@ -0,0 +1,814 @@ +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] +[2] JSON Web Token RFC7519- JWT (link)[https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32] +[3] MessagePack - (link)[http://msgpack.org/index.html] +[4] base64url - (link)[https://en.wikipedia.org/wiki/Base64) +# PROTOCOL FEATURES COVERED +Authentication +Authorization +Service Discovery +Service Invocation + +# PROTOCOL FEATURES NOT COVERED +Node discovery +(Use TLS) +Encryption +Replay attacks +MITM attacks +Key revocation (hiher service) +Key distribution (highger service) + + +# 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. + +RVI Core Protocol Stack + +## Encryption +The RVI Core protocol does not provide encryption, replay attack protection, +or any other features normally associated with a secure data link. +It is recommended that TLS 2.0 or similar standard is used to ensure +communication privacy. + +## 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. + +## JSON Web token usage +JSON Web Tokens (JWT) [2] are used to encode signed device keys exchanged during +the ```authentication``` and ```authorization``` phase. + +# 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). + +RVI Core Protocol Sequence Diagram + +## Double connect resolution +There is a risk that both parties try to initiate a connection in a race condition, creating +double connections between them, as shown below with one connection in gray, and the other in black. + +RVI Core Protocol Double Connect + + +The double connect can be detected by either side by checking if the +remote public key has already been receieved on another connection +over the same data link (WiFi, TCP/IP, Bluetooth, etc), indicating +that the ```authenticate``` phase has been executed twice. + + +If, during the ```authenticaiton``` phase, the receiver detects that +the public key has already been received thro + +device key sort to determine which +Find sorting algorithm +Device key +IP address +Peer port number +Conflict resolution for other protocols + +# No signatures on RCV + + + + +## 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**
+ 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 diff --git a/doc/rvi_protocol_stack.png b/doc/rvi_protocol_stack.png new file mode 100644 index 0000000..043beaa Binary files /dev/null and b/doc/rvi_protocol_stack.png differ -- cgit v1.2.1 From b2a8f0deaa1da9b90e7ab59a801325a707d2967d Mon Sep 17 00:00:00 2001 From: Magnus Feuer Date: Tue, 10 Nov 2015 16:53:07 -0800 Subject: Started to modify documentation to match agreement reached on RVI meeting 2015-11-10 --- doc/rvi_protocol.md | 97 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 71 insertions(+), 26 deletions(-) (limited to 'doc') diff --git a/doc/rvi_protocol.md b/doc/rvi_protocol.md index 70e75d3..8b4b696 100644 --- a/doc/rvi_protocol.md +++ b/doc/rvi_protocol.md @@ -11,46 +11,91 @@ This document describes the core protocol between two RVI nodes. [2] JSON Web Token RFC7519- JWT (link)[https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32] [3] MessagePack - (link)[http://msgpack.org/index.html] [4] base64url - (link)[https://en.wikipedia.org/wiki/Base64) -# PROTOCOL FEATURES COVERED -Authentication -Authorization -Service Discovery -Service Invocation - -# PROTOCOL FEATURES NOT COVERED -Node discovery -(Use TLS) -Encryption -Replay attacks -MITM attacks -Key revocation (hiher service) -Key distribution (highger service) +[5] Transport Layer Security (TLS) - (link)[https://en.wikipedia.org/wiki/Transport_Layer_Security] +[6] X.509 Certificates - (link)[https://en.wikipedia.org/wiki/X.509] +# FEATURES COVERED BY PROTOCOL +1. **Authroization**
+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. -# OVERVIEW +2. **Service Discovery**
+Announce to the remote RVI node local RVI services which the remote node +is authorized to invoke. + +3. **Service Invocation**
+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**
+Prove the identity of a local RVI node to the remote RVI node. + +2. **Encryption**
+Encrypt data between two RVI nodes to avoid eavesdropping. + +3. **Replay attack protection**
+Replay an earlier RVI Core protocol session to engage with an RVI node again. + +4. **Man in the middle attack protection**
+Terminate an RVI Core protocol connection, modify incoming data and forward it +to its original destination. + +5. **Key Management**
+Public Key Infrastructure and certificate distribution. + +6. **RVI Node Discovery**
+Allowing two unconnected RVI nodes to discover each other, allowing +them to connect. + +# 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. -RVI Core Protocol Stack +RVI Core protocol Stack + + +## Certificates +Three types of certificates are used by the RVI Core protocol in conjunciton with TLS. +See [6] for details on X.509. + +1. **Root cert [X.509]**
+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 cert (X.509)**
+Per-device certificate. Signed by root cert. Used by TLS for initial +authentication. + +3. **RVI cert (JWT)**
+Describes the services that the device has the right to invoke and the +services that the device has right to register. +Embeds the public key from the device cert. 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 the X.509 certificates have +validated by the remote party, their public keys will be used to match +against RVI certificates. -## Encryption -The RVI Core protocol does not provide encryption, replay attack protection, -or any other features normally associated with a secure data link. -It is recommended that TLS 2.0 or similar standard is used to ensure -communication privacy. +The RVI certificates will embed the public key from the sender's X.509 +device certificate. -## RVI Core protocol codec +## protocol 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. ## JSON Web token usage -JSON Web Tokens (JWT) [2] are used to encode signed device keys exchanged during -the ```authentication``` and ```authorization``` phase. +JSON Web Tokens (JWT) [2] are used to encode RVI certificates, which are +signed by the root certificate. # Protocol flow @@ -61,13 +106,13 @@ 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). -RVI Core Protocol Sequence Diagram +RVI Core protocol Sequence Diagram ## Double connect resolution There is a risk that both parties try to initiate a connection in a race condition, creating double connections between them, as shown below with one connection in gray, and the other in black. -RVI Core Protocol Double Connect +RVI Core protocol Double Connect The double connect can be detected by either side by checking if the -- cgit v1.2.1 From 965276f9c8fd2514a39a676ba27d6ca3a05307f6 Mon Sep 17 00:00:00 2001 From: Magnus Feuer Date: Fri, 13 Nov 2015 09:27:46 -0800 Subject: Added image generation script. Elaborated on protocol --- doc/generate_msc_images.sh | 8 ++ doc/rvi_core.msc | 38 ----- doc/rvi_core.png | Bin 49909 -> 0 bytes doc/rvi_core_double_connect.msc | 24 ---- doc/rvi_core_double_connect.png | Bin 19004 -> 0 bytes doc/rvi_protocol.md | 271 +++++++++++++++++++++++++++++------ doc/rvi_protocol_double_connect1.msc | 23 +++ doc/rvi_protocol_double_connect1.png | Bin 0 -> 8253 bytes doc/rvi_protocol_double_connect2.msc | 10 ++ doc/rvi_protocol_double_connect2.png | Bin 0 -> 8286 bytes doc/rvi_protocol_flow.msc | 32 +++++ doc/rvi_protocol_flow.png | Bin 0 -> 33520 bytes doc/rvi_protocol_x509_credential.png | Bin 0 -> 17933 bytes doc/rvi_protocol_x509_pub_key.png | Bin 0 -> 17539 bytes doc/rvi_security.md | 2 + 15 files changed, 301 insertions(+), 107 deletions(-) create mode 100644 doc/generate_msc_images.sh delete mode 100644 doc/rvi_core.msc delete mode 100644 doc/rvi_core.png delete mode 100644 doc/rvi_core_double_connect.msc delete mode 100644 doc/rvi_core_double_connect.png create mode 100644 doc/rvi_protocol_double_connect1.msc create mode 100644 doc/rvi_protocol_double_connect1.png create mode 100644 doc/rvi_protocol_double_connect2.msc create mode 100644 doc/rvi_protocol_double_connect2.png create mode 100644 doc/rvi_protocol_flow.msc create mode 100644 doc/rvi_protocol_flow.png create mode 100644 doc/rvi_protocol_x509_credential.png create mode 100644 doc/rvi_protocol_x509_pub_key.png (limited to 'doc') diff --git a/doc/generate_msc_images.sh b/doc/generate_msc_images.sh new file mode 100644 index 0000000..cee5f23 --- /dev/null +++ b/doc/generate_msc_images.sh @@ -0,0 +1,8 @@ +#!/bin/sh +# +# Convert msc files to png +# + +mscgen -T png -i rvi_protocol_double_connect1.msc -o rvi_protocol_double_connect1.png +mscgen -T png -i rvi_protocol_double_connect2.msc -o rvi_protocol_double_connect2.png +mscgen -T png -i rvi_protocol_flow.msc -o rvi_protocol_flow.png diff --git a/doc/rvi_core.msc b/doc/rvi_core.msc deleted file mode 100644 index e443535..0000000 --- a/doc/rvi_core.msc +++ /dev/null @@ -1,38 +0,0 @@ -# -# -# 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 swm.msc -# - -msc { - width="1024"; - "Client", "Server"; - "Client" -> "Server" [ label = "connect" ]; - "Client" -> "Server" [ label = "authenticate( JWT ( client_pub_key, root_sign ) )" ]; - "Server" abox "Server" [ label = "Validate client public key signature using root public key" ] ; - "Client" <- "Server" [ label = "authenticate( JWT ( server_pub_key, root_sign ) )" ]; - "Client" abox "Client" [ label = "Validate server public key signature using root public key" ] ; - - "Client" -> "Server" [ label = "authorize( JWT ( [JWT (certificate, root_sign), ...] ), device_sign ) )" ]; - "Server" abox "Server" [ label = "Validate authorize signature using client public key" ] ; - "Server" abox "Server" [ label = "Validate each certificate using root public key" ] ; - "Client" <- "Server" [ label = "authorize( JWT ( [JWT (certificate, root_sign), ...] ), device_sign ) )" ]; - "Client" abox "Client" [ label = "Validate authorize signature using client public key" ] ; - "Client" abox "Client" [ label = "Validate each certificate using root public key" ] ; - - "Client" abox "Client" [ label = "Create list of services matching server certificates" ] ; - "Client" -> "Server" [ label = "service_announce( [service_name, ... ])" ]; - "Server" abox "Server" [ label = "Create list of services matching client certificates" ] ; - "Client" <- "Server" [ label = "service_announce( [service_name, ... ])" ]; - - "Client" -> "Server" [ label = "message( service_name, arguments)" ]; - - "Server" -> "Client" [ label = "message( service_name, arguments)" ]; -} - diff --git a/doc/rvi_core.png b/doc/rvi_core.png deleted file mode 100644 index e696abc..0000000 Binary files a/doc/rvi_core.png and /dev/null differ diff --git a/doc/rvi_core_double_connect.msc b/doc/rvi_core_double_connect.msc deleted file mode 100644 index 7f098e2..0000000 --- a/doc/rvi_core_double_connect.msc +++ /dev/null @@ -1,24 +0,0 @@ -# -# -# 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 swm.msc -# - -msc { - width="1024"; - "Client", "Server"; - "Client" -> "Server" [ label = "connect" ]; - "Server" -> "Client" [ textcolor="gray", linecolor="gray", label = "connect" ]; - "Client" -> "Server" [ label = "authenticate( JWT ( client_pub_key, root_sign ) )" ]; - "Client" <- "Server" [ textcolor="gray", linecolor="gray",label = "authenticate( JWT ( server_pub_key, root_sign ) )" ]; - "Client" <- "Server" [ label = "authenticate( JWT ( server_pub_key, root_sign ) )" ]; - "Client" -> "Server" [ textcolor="gray", linecolor="gray", label = "authenticate( JWT ( client_pub_key, root_sign ) )" ]; - "Client" abox "Server" [ label = "Race Condition" ] ; -} - diff --git a/doc/rvi_core_double_connect.png b/doc/rvi_core_double_connect.png deleted file mode 100644 index c1dae9f..0000000 Binary files a/doc/rvi_core_double_connect.png and /dev/null differ diff --git a/doc/rvi_protocol.md b/doc/rvi_protocol.md index 8b4b696..707da9d 100644 --- a/doc/rvi_protocol.md +++ b/doc/rvi_protocol.md @@ -27,11 +27,11 @@ is authorized to invoke. 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 +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**
-Prove the identity of a local RVI node to the remote RVI node. +Prove the identity oof a local RVI node to the remote RVI node. 2. **Encryption**
Encrypt data between two RVI nodes to avoid eavesdropping. @@ -47,8 +47,7 @@ to its original destination. Public Key Infrastructure and certificate distribution. 6. **RVI Node Discovery**
-Allowing two unconnected RVI nodes to discover each other, allowing -them to connect. +Allowing two unconnected RVI nodes to discover each other so that they can initiate connection. # OVERVIEW @@ -59,45 +58,49 @@ The stack schematics is shown below. 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 -Three types of certificates are used by the RVI Core protocol in conjunciton with TLS. -See [6] for details on X.509. +## 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 cert [X.509]**
+1. **Root certificate [X.509]**
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 cert (X.509)**
+2. **Device certificate (X.509)**
Per-device certificate. Signed by root cert. Used by TLS for initial authentication. -3. **RVI cert (JWT)**
+3. **RVI credentials (JWT)**
Describes the services that the device has the right to invoke and the services that the device has right to register. -Embeds the public key from the device cert. Signed by root cert. +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 the X.509 certificates have -validated by the remote party, their public keys will be used to match -against RVI certificates. +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 RVI certificates will embed the public key from the sender's X.509 -device certificate. +The figure below shows how this is done. -## protocol 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. +X.509 - RVI Protocol integration ## JSON Web token usage -JSON Web Tokens (JWT) [2] are used to encode RVI certificates, which are -signed by the root certificate. +JSON Web Tokens (JWT) [2] are used to encode RVI credentials, which are +signed by the root x.509 certificate. -# Protocol flow +# PROTOCOL FLOW ## Sequence Diagram @@ -106,32 +109,211 @@ 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). -RVI Core protocol Sequence Diagram +RVI Core protocol Sequence Diagram + +## 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 both parties try to initiate a connection in a race condition, creating -double connections between them, as shown below with one connection in gray, and the other in black. +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 +:------:|:------: +RVI Core protocol Double Connect | RVI Core protocol Double Connect + +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 +TBD: Ulf Wiger + +# 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: + +## Reference root certificate +The self signed root certificate used in the examples throughout this +document was generated using the following commands: + + + # Create root key and cert signing request + openssl req -new -newkey rsa:1024 -nodes -out root.csr -keyout root.key + + # Create the CA-like root cert, + openssl x509 -trustout -signkey root.key -days 365 -req -in root_cert.csr -out root_cert.pem +FIXME: FILENAMES + +The content of the reference ```root_key.pem``` private key file is: + +``` +-----BEGIN PRIVATE KEY----- +MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAKWVa8gzbvqtOBgK +D7G78ssyGzxv3+NU5u+g7ylPrhTrTAne3+xwkUJDBphcLq1R1bMBQukShIJ6lyBU +jA6L1J6eP2U6hDNgPIBoQ1Ew9DuurPmUV0Ww8oqiTo+M6XhsZgrXtuRVlOkLaYuL +x1/3VxqbafUJlUvsX2KUT5QUzgmhAgMBAAECgYEAlDIiUADwf7zOan1+xGThjUjg +JXw/VjgjpC5WPpQIysI4wNDPes7YwwQ3/97pC8glSduEJhOjsx/C6HWjEFXHyWoV +If735X8zmPxmpUBH/8BAlLKWeLJPeJcOYhqe9Fmmq3ePFJVzm27G9rtBcAGf01F1 +MZvlGpSMnM54ysDvCAECQQDXJMptGlBNVJnW1MnTClVPMPStQtExawazoK0AE2u6 +ESp9dzCVTVKClSsQFvtgtOzq3jTaPvVOCB1lli3xD7VBAkEAxQdFBIL3wKA1X6OD +78mThCG5/DZL04hA3pMHiy1nwCiAf5AeFebStwfPcyEnMnA1ottI6DA4l51GfLTh +d/dcYQJBAL90hRN8VDPM8q4kZIqC6pHzffnluSXiGW+mr+2eWsKVXhuTAtAKpD+C +oXTLDt7rgt4r6hrB5iiPviFV+QJJuUECQHs/xOjBlIGmtjyRaOMC0YiCIHmo7V3x +icKxbrKdQJ1vuJITcP56Wa2s8RQv1Pk0QBkT21ODdqNA+urfq3sD/YECQQCsk8Zn +uljcpN1aORD5NOgbf8gUc2XrKs0PUMdj69ABfL83RRGxuht5RadT3t0tMvWfEqGy +kK8ylWnEL9PkGH4d +-----END PRIVATE KEY----- +``` + +The root private key has no password protection. + +The content of the reference ```root_cert.pem``` file is: + +``` +-----BEGIN TRUSTED CERTIFICATE----- +MIIB+zCCAWQCCQCVOgc/WIzYGjANBgkqhkiG9w0BAQsFADBCMQswCQYDVQQGEwJV +UzEPMA0GA1UECAwGT3JlZ29uMREwDwYDVQQHDAhQb3J0bGFuZDEPMA0GA1UECgwG +R0VOSVZJMB4XDTE1MTExMzAwMzczNloXDTE2MTExMjAwMzczNlowQjELMAkGA1UE +BhMCVVMxDzANBgNVBAgMBk9yZWdvbjERMA8GA1UEBwwIUG9ydGxhbmQxDzANBgNV +BAoMBkdFTklWSTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEApZVryDNu+q04 +GAoPsbvyyzIbPG/f41Tm76DvKU+uFOtMCd7f7HCRQkMGmFwurVHVswFC6RKEgnqX +IFSMDovUnp4/ZTqEM2A8gGhDUTD0O66s+ZRXRbDyiqJOj4zpeGxmCte25FWU6Qtp +i4vHX/dXGptp9QmVS+xfYpRPlBTOCaECAwEAATANBgkqhkiG9w0BAQsFAAOBgQBk +b9xhPC0ylvYwhnn2F9rF7SvKCQ9mMyNjWy3aIkv0pXUsdgX4TQ1ocTlohQZyhSvl +8wj0Sh/jsDWQsczXLpeGP+D1TV9mvYeFuey5cWGjtd8fUYY1bx81RNRowX+uphCZ +5s0vtHXqNz9FQWl75qnIc7/UwlF73YO1UozX6jqpwg== +-----END TRUSTED CERTIFICATE----- +``` + +## Reference device certificate -RVI Core protocol Double Connect +The reference device x.509 certificate, signed by the root certificate above, +was generated with the following command: + openssl genrsa -out device_key.pem 1024 + openssl req -new -key device_key.pem -out device_cert.csr + openssl x509 -req -days 365 -in device_cert.csr -CA root_cert.pem -CAkey root_key.pem -set_serial 01 -out device_cert.crt -The double connect can be detected by either side by checking if the -remote public key has already been receieved on another connection -over the same data link (WiFi, TCP/IP, Bluetooth, etc), indicating -that the ```authenticate``` phase has been executed twice. +FIXME FILENAMES +## RVI Credentials -If, during the ```authenticaiton``` phase, the receiver detects that -the public key has already been received thro +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. The sender is linked to the remote node by comparing the device X.509 +certificate, sent during TLS upgrade, with the X.509 certificate +embedded in the RVI credentials transmitted over the same TLS +connection. + +The TLS upgrade process of the connection will have the local node +receive and validate the remote party's X.509 device certificate. The +received certificate is signed by the root X.509 certificate, which is pre-provisioned +at the receiving local node. + +Thus, the local node can validate that the remote node is who it claims to be, +and that it has been provisioned by the same entity that pre-provisioned the +root certificate in the local node. + +When the remote node sends one or more RVI credentials, each encoded as +JWT and signed by the root certificate, the receiving local node can +compare the device X.509 certificate embedded in the RVI credential with +that received from the remote party during the TLS upgrade. + +If the two device X.509 certificates match, the local party has validated that the +remotenode has the rights claimed by the RVI credentials due to the following +two facts: + +1. The root certificate signature of the credentials proves that it has +been generated by the same entity that installed the root certificate +in the local node. + +2. The matching device X.509 certificates proves that the RVI credential +is owned by the remote node, whose identity was validated during the TLS upgrade +procedure. + +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", + "x509_cert": "MIIDNDCCAhwCCQCCuRFrfxk3vjANBgkqhkiG9w0BAQsFADBcMQswCQYDVQQGEwJVUzEPMA0GA1UECAwGT3JlZ29uMREwDwYDVQQHDAhQb3J0bGFuZDEaMBgGA1UECgwRSmFndWFyIExhbmQgUm92ZXIxDTALBgNVBAsMBE9TVEMwHhcNMTUxMTEyMjI0OTE4WhcNMTYxMTExMjI0OTE4WjBcMQswCQYDVQQGEwJVUzEPMA0GA1UECAwGT3JlZ29uMREwDwYDVQQHDAhQb3J0bGFuZDEaMBgGA1UECgwRSmFndWFyIExhbmQgUm92ZXIxDTALBgNVBAsMBE9TVEMwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDOXh4q7f/kwUfpxs/vT1U0eSMEuJvDttQhIhLY+U4EEfayIlBq4PhFlzt4AIHi8WSAjuK2mCpbzEbkSpZbaMgKktaLONSFxdINrgXMVth/J5KVCibt8ode86tdTIgDMBFTNviG7SyQYbC7Dxpm/N1r9L7j3Ey9FethIqBfROmWFzTO8SGa6suUtSorP6XFxVgg4F0a/1D63d4ih2x0qOMnbWbp1cTI5HQMIXIsURcatJwONZlHCVN+ZndG7KzZHsKyCBfWluXCVHtuCYPREPEBZvcEotZT6S1F5F1y9wFGXzhGlxCmvg8u8Vz7Zs2Mxug6HU7qx0/qDRN4r9X1YX8lAgMBAAEwDQYJKoZIhvcNAQELBQADggEBADSerkw6kheJnvecrAMCIPq0ljCVgumg1Bh+5iQNc6BaTZoRgFMbtoxIXmW5iPOjhId+vnw4Pv8AShn6Yer5K0AFxkCVWzYSzeGUbCoHJphcZ/Y3+9BCl6o75Fzj0K/lMfwQY+Eqal53tCuHGH8qj4C2mkas8SGT7NB0nx4j+MRgq6YYpylfC6jvXttbUkhu+OfezfU1gxhiWi3VbOQ5mlxdt1nOxAkvWFQ4XF89Z8N/+m9YouNsWiu1NenoAJXRWABSqe0Qd2pzowDf8GQGZEePw5Egvy+0tD0qi0af7+NYftx1pno4YsUiluiVEmbCk+G6C9MLpQeRYnwDWv97yuk=", + "validity": { + "start": 1420099200, + "stop": 1925020799 + } +} +``` + + +This credential is then JWT-encoded with a root certificate signature: + +The X.509 certificates are used by TLS, which is outside the scope of this specification. + +However, the RVI protocol will extract the PEM (base64) encoded X.509 certificate from +the TLS API (such as OpenSSL) and compare it with the PEM encoded X.509 certificate embedded +inside the RVI credentials. + +As an example + + +# END OF DRAFT. EVERYTHING BELOW IS RESIDUAL -device key sort to determine which -Find sorting algorithm -Device key -IP address -Peer port number -Conflict resolution for other protocols -# No signatures on RCV @@ -140,9 +322,8 @@ Conflict resolution for other protocols ### [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. +#### Issue Sending the root signed public key during handshake +identifies the sender to an unknown remote party. #### Solution diff --git a/doc/rvi_protocol_double_connect1.msc b/doc/rvi_protocol_double_connect1.msc new file mode 100644 index 0000000..eb22f83 --- /dev/null +++ b/doc/rvi_protocol_double_connect1.msc @@ -0,0 +1,23 @@ +# +# +# 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 rvi_core_double_connect.msc +# + +msc { + width="400"; + "Client", "Server"; + "Client" -> "Server" [ label = "Connect" ]; + "Client" <-> "Server" [ label = "TLS Upgrade" ]; + "Client" -> "Server" [ label = "authorize(...)" ]; + "Client" <- "Server" [ label = "authorize(...)" ]; + "Client" abox "Server" [ label = "Race Condition" ] ; +} + + diff --git a/doc/rvi_protocol_double_connect1.png b/doc/rvi_protocol_double_connect1.png new file mode 100644 index 0000000..21ad892 Binary files /dev/null and b/doc/rvi_protocol_double_connect1.png differ diff --git a/doc/rvi_protocol_double_connect2.msc b/doc/rvi_protocol_double_connect2.msc new file mode 100644 index 0000000..0240df5 --- /dev/null +++ b/doc/rvi_protocol_double_connect2.msc @@ -0,0 +1,10 @@ +msc { + width="400"; + "Client", "Server"; + "Server" -> "Client" [ label = "Connect" ]; + "Server" <-> "Client" [ label = "TLS Upgrade" ]; + "Client" <- "Server" [ label = "authorize(...)" ]; + "Client" -> "Server" [ label = "authorize(...)" ]; + "Client" abox "Server" [ label = "Race Condition" ] ; +} + diff --git a/doc/rvi_protocol_double_connect2.png b/doc/rvi_protocol_double_connect2.png new file mode 100644 index 0000000..d14f92d Binary files /dev/null and b/doc/rvi_protocol_double_connect2.png differ diff --git a/doc/rvi_protocol_flow.msc b/doc/rvi_protocol_flow.msc new file mode 100644 index 0000000..f4a84b3 --- /dev/null +++ b/doc/rvi_protocol_flow.msc @@ -0,0 +1,32 @@ +# +# +# 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 swm.msc +# + +msc { + width="1024"; + "Client", "Server"; + "Client" -> "Server" [ label = "connect" ]; + "Client" -> "Server" [ label = "TLS Upgrade using X.509 certificates" ]; + "Client" -> "Server" [ label = "authorize( [JWT (credential, root_sign), ...] )" ]; + "Server" abox "Server" [ label = "Validate each credential using root public key" ] ; + "Client" <- "Server" [ label = "authorize( [JWT (credential, root_sign), ...] ) )" ]; + "Client" abox "Client" [ label = "Validate each crential using root public key" ] ; + + "Client" abox "Client" [ label = "Create list of services matching server credentials" ] ; + "Client" -> "Server" [ label = "service_announce( [service_name, ... ])" ]; + "Server" abox "Server" [ label = "Create list of services matching client credentials" ] ; + "Client" <- "Server" [ label = "service_announce( [service_name, ... ])" ]; + + "Client" -> "Server" [ label = "message( service_name, arguments)" ]; + + "Server" -> "Client" [ label = "message( service_name, arguments)" ]; +} + diff --git a/doc/rvi_protocol_flow.png b/doc/rvi_protocol_flow.png new file mode 100644 index 0000000..eb06363 Binary files /dev/null and b/doc/rvi_protocol_flow.png differ diff --git a/doc/rvi_protocol_x509_credential.png b/doc/rvi_protocol_x509_credential.png new file mode 100644 index 0000000..d63bb24 Binary files /dev/null and b/doc/rvi_protocol_x509_credential.png differ diff --git a/doc/rvi_protocol_x509_pub_key.png b/doc/rvi_protocol_x509_pub_key.png new file mode 100644 index 0000000..f685ad7 Binary files /dev/null and b/doc/rvi_protocol_x509_pub_key.png differ diff --git a/doc/rvi_security.md b/doc/rvi_security.md index 11d57e7..e51a18f 100644 --- a/doc/rvi_security.md +++ b/doc/rvi_security.md @@ -3,6 +3,8 @@ Copyright (C) 2015 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 + ## OPEN ISSUES ### [1] Public device key exchange as a part of handshake demasks sender -- cgit v1.2.1