Started to modify documentation to match agreement reached on RVI meeting 2015-11-10

1 files changed, 71 insertions, 26 deletions

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**<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.
 
-# OVERVIEW
+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 of 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, 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.
 
-<img src="rvi_protocol_stack.png" alt="RVI Core Protocol Stack">
+<img src="rvi_protocol_stack.png" alt="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]**<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 cert (X.509)**<br>
+Per-device certificate.  Signed by root cert. Used by TLS for initial
+authentication.
+
+3. **RVI cert (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 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).
 
-<img src="rvi_core.png" alt="RVI Core Protocol Sequence Diagram" style="width:800">
+<img src="rvi_core.png" alt="RVI Core protocol Sequence Diagram" style="width:800">
 
 ## 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.
 
-<img src="rvi_core_double_connect.png" alt="RVI Core Protocol Double Connect" style="width:800">
+<img src="rvi_core_double_connect.png" alt="RVI Core protocol Double Connect" style="width:800">
 
 
 The double connect can be detected by either side by checking if the