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