diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/images/frag-overview.png | bin | 0 -> 63851 bytes | |||
-rw-r--r-- | doc/images/rvi_protocol_double_connect1.png (renamed from doc/rvi_protocol_double_connect1.png) | bin | 8253 -> 8253 bytes | |||
-rw-r--r-- | doc/images/rvi_protocol_double_connect2.png (renamed from doc/rvi_protocol_double_connect2.png) | bin | 8286 -> 8286 bytes | |||
-rw-r--r-- | doc/images/rvi_protocol_flow.png (renamed from doc/rvi_protocol_flow.png) | bin | 33520 -> 33520 bytes | |||
-rw-r--r-- | doc/images/rvi_protocol_frag1.png (renamed from doc/rvi_protocol_frag1.png) | bin | 16359 -> 16359 bytes | |||
-rw-r--r-- | doc/images/rvi_protocol_stack.png (renamed from doc/rvi_protocol_stack.png) | bin | 12693 -> 12693 bytes | |||
-rw-r--r-- | doc/images/rvi_protocol_x509_credential.png (renamed from doc/rvi_protocol_x509_credential.png) | bin | 17933 -> 17933 bytes | |||
-rw-r--r-- | doc/images/rvi_protocol_x509_pub_key.png (renamed from doc/rvi_protocol_x509_pub_key.png) | bin | 17539 -> 17539 bytes | |||
-rw-r--r-- | doc/msc/rvi_protocol_double_connect1.msc (renamed from doc/rvi_protocol_double_connect1.msc) | 0 | ||||
-rw-r--r-- | doc/msc/rvi_protocol_double_connect2.msc (renamed from doc/rvi_protocol_double_connect2.msc) | 0 | ||||
-rw-r--r-- | doc/msc/rvi_protocol_flow.msc (renamed from doc/rvi_protocol_flow.msc) | 0 | ||||
-rw-r--r-- | doc/msc/rvi_protocol_frag1.msc (renamed from doc/rvi_protocol_frag1.msc) | 0 | ||||
-rw-r--r-- | doc/rvi_fragmentation.md | 122 | ||||
-rw-r--r-- | doc/rvi_protocol.md | 12 |
14 files changed, 128 insertions, 6 deletions
diff --git a/doc/images/frag-overview.png b/doc/images/frag-overview.png Binary files differnew file mode 100644 index 0000000..ad866c4 --- /dev/null +++ b/doc/images/frag-overview.png diff --git a/doc/rvi_protocol_double_connect1.png b/doc/images/rvi_protocol_double_connect1.png Binary files differindex 21ad892..21ad892 100644 --- a/doc/rvi_protocol_double_connect1.png +++ b/doc/images/rvi_protocol_double_connect1.png diff --git a/doc/rvi_protocol_double_connect2.png b/doc/images/rvi_protocol_double_connect2.png Binary files differindex d14f92d..d14f92d 100644 --- a/doc/rvi_protocol_double_connect2.png +++ b/doc/images/rvi_protocol_double_connect2.png diff --git a/doc/rvi_protocol_flow.png b/doc/images/rvi_protocol_flow.png Binary files differindex eb06363..eb06363 100644 --- a/doc/rvi_protocol_flow.png +++ b/doc/images/rvi_protocol_flow.png diff --git a/doc/rvi_protocol_frag1.png b/doc/images/rvi_protocol_frag1.png Binary files differindex aedb46e..aedb46e 100644 --- a/doc/rvi_protocol_frag1.png +++ b/doc/images/rvi_protocol_frag1.png diff --git a/doc/rvi_protocol_stack.png b/doc/images/rvi_protocol_stack.png Binary files differindex 043beaa..043beaa 100644 --- a/doc/rvi_protocol_stack.png +++ b/doc/images/rvi_protocol_stack.png diff --git a/doc/rvi_protocol_x509_credential.png b/doc/images/rvi_protocol_x509_credential.png Binary files differindex d63bb24..d63bb24 100644 --- a/doc/rvi_protocol_x509_credential.png +++ b/doc/images/rvi_protocol_x509_credential.png diff --git a/doc/rvi_protocol_x509_pub_key.png b/doc/images/rvi_protocol_x509_pub_key.png Binary files differindex f685ad7..f685ad7 100644 --- a/doc/rvi_protocol_x509_pub_key.png +++ b/doc/images/rvi_protocol_x509_pub_key.png diff --git a/doc/rvi_protocol_double_connect1.msc b/doc/msc/rvi_protocol_double_connect1.msc index eb22f83..eb22f83 100644 --- a/doc/rvi_protocol_double_connect1.msc +++ b/doc/msc/rvi_protocol_double_connect1.msc diff --git a/doc/rvi_protocol_double_connect2.msc b/doc/msc/rvi_protocol_double_connect2.msc index 0240df5..0240df5 100644 --- a/doc/rvi_protocol_double_connect2.msc +++ b/doc/msc/rvi_protocol_double_connect2.msc diff --git a/doc/rvi_protocol_flow.msc b/doc/msc/rvi_protocol_flow.msc index f4a84b3..f4a84b3 100644 --- a/doc/rvi_protocol_flow.msc +++ b/doc/msc/rvi_protocol_flow.msc diff --git a/doc/rvi_protocol_frag1.msc b/doc/msc/rvi_protocol_frag1.msc index 11d467f..11d467f 100644 --- a/doc/rvi_protocol_frag1.msc +++ b/doc/msc/rvi_protocol_frag1.msc diff --git a/doc/rvi_fragmentation.md b/doc/rvi_fragmentation.md new file mode 100644 index 0000000..077cb49 --- /dev/null +++ b/doc/rvi_fragmentation.md @@ -0,0 +1,122 @@ +# The RVI Core Fragmentation Protocol + +## Abstract + +The Remote Vehicle Interaction (RVI) system is a framework for secure interaction between +vehicles and other devices and/or cloud services. RVI is designed to be agnostic in regard +to connectivity options and intermittent connectivity. One consequence of this is that +large messages may have to be partially transmitted via one type of connection, and completed +on another. The fragmentation protocol described below allows for varying Message Transfer +Unit (MTU) and lets the remote client request fragments as needed. + +## Status of This Memo + +This document is not an Internet Standards Track specification; it is +published for informational purposes. + +## Copyright Notice + +Copyright (C) 2016 Jaguar Land Rover + +This document is licensed under Creative Commons +Attribution-ShareAlike 4.0 International. + +## Table of Contents + +1. [Introduction](#introduction) +2. [Terminology](#terminology) +3. [System Overview](#system-overview) +4. [Notation](#notation) +5. [References](#references) + +## Introduction + + + +## Terminology + +Term | Meaning +----------|-------------------------------- +`Client` | Sending side of the interaction +`Server` | Receiving side of the interaction +`MTU` | Message Transfer Unit + +## System Overview + +The fragmentation support is intended to operate immediately on top of the transport +layer. In + +<img src="images/frag-overview.png" alt="Overview" style="width:600"> + +## Notation + +The fragmentation protocol does not specify any particular encoding method. +In this document, JSON notation is used. In practice, a byte-oriented JSON-like +encoding, like msgpack [MSGP] would be more suitable. + +## Messages + +The fragment messages are deliberately compact, in order to steal as little of +the available transfer window from the fragment itself. + +**Fragment message:** + + { "frg": [ id, size, offset, fragment ] } + +The sending side initiates fragment transfer by sending a first fragment. The +size of the first fragment is determined by the sending side. Subsequent fragments +are requested by the receiver, in which case the receiver also decides how large +a fragment it wants. The sender is allowed to send a smaller fragment, but not +a larger one. + +Note that `size` denotes the size of the *whole* message, not the fragment. + +**Fragment request message:** + + { "frg-get": [ id, offset, size ] } + +This message is sent by the receiving side in order to request the next fragment. +The `offset` will typically be the position following the most recently received +fragment, but could also represent a "hole" in the message from a missing fragment. + +**Fragment acknowledgement message:** + + { "frg-end": [ id, result_code ] } + +**Fragment error message:** + + { "frg-err": [ id, result_code ] } + +`id` (string): Message identity. This value needs to be unique within the scope +of the current connection. + +`size` (integer): A positive integer denoting either the size of the whole message +(as in the `"frg"` message) or the size of the requested fragment (as in the `"frg-get"` +message). + +`offset` (integer): A positive integer denoting the starting byte of the fragment, +relative to the whole message. The first fragment starts at `1`. + +`fragment` (binary): A byte sequence denoting the current fragment. Note that the +`"frg"` message doesn't contain a size indicator for the fragment. However an +encoding such as [MSGP] does include a size indicator. + +`result_code` (integer): A number denoting the outcome of the transfer and reassembly. +A zero (`0`) means all went well; a negative number indicates failure. Predefined values +are: + +Code or range | Definition +--------------| ---------------------- +`0` | Message was successfully transfered and reassembled +`-99 ... -1` | Reserved for standard error codes +`-1` | Unknown message (i.e. in a `"frg-err"` response to a `"fgr-get"` message) +`-2` | Protocol error +`-3` | Timeout error +`< -99` | Application-defined error codes + +## References + +[RVI] Remote Vehicle Interaction (RVI) + https://github.com/PDXOstc/rvi_core +[MSGP] msgpack encoding + http://msgpack.org
\ No newline at end of file diff --git a/doc/rvi_protocol.md b/doc/rvi_protocol.md index 1d3f566..13b561e 100644 --- a/doc/rvi_protocol.md +++ b/doc/rvi_protocol.md @@ -1,4 +1,4 @@ -Copyright (C) 2015 Jaguar Land Rover +Copyright (C) 2015-16 Jaguar Land Rover This document is licensed under Creative Commons Attribution-ShareAlike 4.0 International. @@ -56,7 +56,7 @@ 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="images/rvi_protocol_stack.png" alt="RVI Core protocol Stack"> ## RVI Core protocol codec The RVI core protocol uses MessagePack [3] as its @@ -94,7 +94,7 @@ RVI credentials. The figure below shows how this is done. -<img src="rvi_protocol_x509_credential.png" alt="X.509 - RVI Protocol integration"> +<img src="images/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 @@ -109,7 +109,7 @@ 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"> +<img src="images/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 @@ -138,7 +138,7 @@ 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"> +<img src="images/rvi_protocol_double_connect1.png" alt="RVI Core protocol Double Connect" style="width:400"> | <img src="images/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. @@ -181,7 +181,7 @@ fragmented. The protocol is as follows: -<img src="rvi_protocol_frag1.png" alt="RVI Core fragmentation Sequence Diagram" style="width:800"> +<img src="images/rvi_protocol_frag1.png" alt="RVI Core fragmentation Sequence Diagram" style="width:800"> ### Enabling fragmentation |