From f490d5a35ae1776f15b8e3a485b406797e838b87 Mon Sep 17 00:00:00 2001 From: Ulf Wiger Date: Fri, 29 Jan 2016 20:18:41 +0100 Subject: moved files to subdirs, w.i.p. on fragmentation --- doc/images/frag-overview.png | Bin 0 -> 63851 bytes doc/images/rvi_protocol_double_connect1.png | Bin 0 -> 8253 bytes doc/images/rvi_protocol_double_connect2.png | Bin 0 -> 8286 bytes doc/images/rvi_protocol_flow.png | Bin 0 -> 33520 bytes doc/images/rvi_protocol_frag1.png | Bin 0 -> 16359 bytes doc/images/rvi_protocol_stack.png | Bin 0 -> 12693 bytes doc/images/rvi_protocol_x509_credential.png | Bin 0 -> 17933 bytes doc/images/rvi_protocol_x509_pub_key.png | Bin 0 -> 17539 bytes doc/msc/rvi_protocol_double_connect1.msc | 23 ++++++ doc/msc/rvi_protocol_double_connect2.msc | 10 +++ doc/msc/rvi_protocol_flow.msc | 32 ++++++++ doc/msc/rvi_protocol_frag1.msc | 23 ++++++ doc/rvi_fragmentation.md | 122 ++++++++++++++++++++++++++++ doc/rvi_protocol.md | 12 +-- doc/rvi_protocol_double_connect1.msc | 23 ------ doc/rvi_protocol_double_connect1.png | Bin 8253 -> 0 bytes doc/rvi_protocol_double_connect2.msc | 10 --- doc/rvi_protocol_double_connect2.png | Bin 8286 -> 0 bytes doc/rvi_protocol_flow.msc | 32 -------- doc/rvi_protocol_flow.png | Bin 33520 -> 0 bytes doc/rvi_protocol_frag1.msc | 23 ------ doc/rvi_protocol_frag1.png | Bin 16359 -> 0 bytes doc/rvi_protocol_stack.png | Bin 12693 -> 0 bytes doc/rvi_protocol_x509_credential.png | Bin 17933 -> 0 bytes doc/rvi_protocol_x509_pub_key.png | Bin 17539 -> 0 bytes 25 files changed, 216 insertions(+), 94 deletions(-) create mode 100644 doc/images/frag-overview.png create mode 100644 doc/images/rvi_protocol_double_connect1.png create mode 100644 doc/images/rvi_protocol_double_connect2.png create mode 100644 doc/images/rvi_protocol_flow.png create mode 100644 doc/images/rvi_protocol_frag1.png create mode 100644 doc/images/rvi_protocol_stack.png create mode 100644 doc/images/rvi_protocol_x509_credential.png create mode 100644 doc/images/rvi_protocol_x509_pub_key.png create mode 100644 doc/msc/rvi_protocol_double_connect1.msc create mode 100644 doc/msc/rvi_protocol_double_connect2.msc create mode 100644 doc/msc/rvi_protocol_flow.msc create mode 100644 doc/msc/rvi_protocol_frag1.msc create mode 100644 doc/rvi_fragmentation.md delete mode 100644 doc/rvi_protocol_double_connect1.msc delete mode 100644 doc/rvi_protocol_double_connect1.png delete mode 100644 doc/rvi_protocol_double_connect2.msc delete mode 100644 doc/rvi_protocol_double_connect2.png delete mode 100644 doc/rvi_protocol_flow.msc delete mode 100644 doc/rvi_protocol_flow.png delete mode 100644 doc/rvi_protocol_frag1.msc delete mode 100644 doc/rvi_protocol_frag1.png delete mode 100644 doc/rvi_protocol_stack.png delete mode 100644 doc/rvi_protocol_x509_credential.png delete mode 100644 doc/rvi_protocol_x509_pub_key.png (limited to 'doc') diff --git a/doc/images/frag-overview.png b/doc/images/frag-overview.png new file mode 100644 index 0000000..ad866c4 Binary files /dev/null and b/doc/images/frag-overview.png differ diff --git a/doc/images/rvi_protocol_double_connect1.png b/doc/images/rvi_protocol_double_connect1.png new file mode 100644 index 0000000..21ad892 Binary files /dev/null and b/doc/images/rvi_protocol_double_connect1.png differ diff --git a/doc/images/rvi_protocol_double_connect2.png b/doc/images/rvi_protocol_double_connect2.png new file mode 100644 index 0000000..d14f92d Binary files /dev/null and b/doc/images/rvi_protocol_double_connect2.png differ diff --git a/doc/images/rvi_protocol_flow.png b/doc/images/rvi_protocol_flow.png new file mode 100644 index 0000000..eb06363 Binary files /dev/null and b/doc/images/rvi_protocol_flow.png differ diff --git a/doc/images/rvi_protocol_frag1.png b/doc/images/rvi_protocol_frag1.png new file mode 100644 index 0000000..aedb46e Binary files /dev/null and b/doc/images/rvi_protocol_frag1.png differ diff --git a/doc/images/rvi_protocol_stack.png b/doc/images/rvi_protocol_stack.png new file mode 100644 index 0000000..043beaa Binary files /dev/null and b/doc/images/rvi_protocol_stack.png differ diff --git a/doc/images/rvi_protocol_x509_credential.png b/doc/images/rvi_protocol_x509_credential.png new file mode 100644 index 0000000..d63bb24 Binary files /dev/null and b/doc/images/rvi_protocol_x509_credential.png differ diff --git a/doc/images/rvi_protocol_x509_pub_key.png b/doc/images/rvi_protocol_x509_pub_key.png new file mode 100644 index 0000000..f685ad7 Binary files /dev/null and b/doc/images/rvi_protocol_x509_pub_key.png differ diff --git a/doc/msc/rvi_protocol_double_connect1.msc b/doc/msc/rvi_protocol_double_connect1.msc new file mode 100644 index 0000000..eb22f83 --- /dev/null +++ b/doc/msc/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/msc/rvi_protocol_double_connect2.msc b/doc/msc/rvi_protocol_double_connect2.msc new file mode 100644 index 0000000..0240df5 --- /dev/null +++ b/doc/msc/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/msc/rvi_protocol_flow.msc b/doc/msc/rvi_protocol_flow.msc new file mode 100644 index 0000000..f4a84b3 --- /dev/null +++ b/doc/msc/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/msc/rvi_protocol_frag1.msc b/doc/msc/rvi_protocol_frag1.msc new file mode 100644 index 0000000..11d467f --- /dev/null +++ b/doc/msc/rvi_protocol_frag1.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_protocol_frag1.msc +# + +msc { + width="400"; + "Client", "Server"; + "Client" -> "Server" [ label = "{frg, [ID, Size, Offs1, Bin1]}" ]; + "Client" <- "Server" [ label = "{frg-get, [ID, Offs2, Bytes2]}" ]; + "Client" -> "Server" [ label = "{frg, [ID, Size, Offs2, Bin2]}" ]; + "Client" <- "Server" [ label = "{frg-get, [ID, Offs3, Bytes3]}" ]; + "Client" -> "Server" [ label = "{frg, [ID, Size, Offs3, Bin3]}" ]; + "Client" <- "Server" [ label = "{frg-end, [ID, ResultCode]}" ]; + "Client" abox "Server" [ label = "Message complete" ] ; +} 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 + +Overview + +## 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. -RVI Core protocol Stack +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. -X.509 - RVI Protocol integration +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). -RVI Core protocol Sequence Diagram +RVI Core protocol Sequence Diagram ## Authorize command The ```authorize``` command contains a list of RVI credentials, each specifying @@ -138,7 +138,7 @@ shown below. Connection 1 | Connection 2 :------:|:------: -RVI Core protocol Double Connect | RVI Core protocol Double Connect +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. @@ -181,7 +181,7 @@ fragmented. The protocol is as follows: -RVI Core fragmentation Sequence Diagram +RVI Core fragmentation Sequence Diagram ### Enabling fragmentation diff --git a/doc/rvi_protocol_double_connect1.msc b/doc/rvi_protocol_double_connect1.msc deleted file mode 100644 index eb22f83..0000000 --- a/doc/rvi_protocol_double_connect1.msc +++ /dev/null @@ -1,23 +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 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 deleted file mode 100644 index 21ad892..0000000 Binary files a/doc/rvi_protocol_double_connect1.png and /dev/null differ diff --git a/doc/rvi_protocol_double_connect2.msc b/doc/rvi_protocol_double_connect2.msc deleted file mode 100644 index 0240df5..0000000 --- a/doc/rvi_protocol_double_connect2.msc +++ /dev/null @@ -1,10 +0,0 @@ -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 deleted file mode 100644 index d14f92d..0000000 Binary files a/doc/rvi_protocol_double_connect2.png and /dev/null differ diff --git a/doc/rvi_protocol_flow.msc b/doc/rvi_protocol_flow.msc deleted file mode 100644 index f4a84b3..0000000 --- a/doc/rvi_protocol_flow.msc +++ /dev/null @@ -1,32 +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 = "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 deleted file mode 100644 index eb06363..0000000 Binary files a/doc/rvi_protocol_flow.png and /dev/null differ diff --git a/doc/rvi_protocol_frag1.msc b/doc/rvi_protocol_frag1.msc deleted file mode 100644 index 11d467f..0000000 --- a/doc/rvi_protocol_frag1.msc +++ /dev/null @@ -1,23 +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 rvi_protocol_frag1.msc -# - -msc { - width="400"; - "Client", "Server"; - "Client" -> "Server" [ label = "{frg, [ID, Size, Offs1, Bin1]}" ]; - "Client" <- "Server" [ label = "{frg-get, [ID, Offs2, Bytes2]}" ]; - "Client" -> "Server" [ label = "{frg, [ID, Size, Offs2, Bin2]}" ]; - "Client" <- "Server" [ label = "{frg-get, [ID, Offs3, Bytes3]}" ]; - "Client" -> "Server" [ label = "{frg, [ID, Size, Offs3, Bin3]}" ]; - "Client" <- "Server" [ label = "{frg-end, [ID, ResultCode]}" ]; - "Client" abox "Server" [ label = "Message complete" ] ; -} diff --git a/doc/rvi_protocol_frag1.png b/doc/rvi_protocol_frag1.png deleted file mode 100644 index aedb46e..0000000 Binary files a/doc/rvi_protocol_frag1.png and /dev/null differ diff --git a/doc/rvi_protocol_stack.png b/doc/rvi_protocol_stack.png deleted file mode 100644 index 043beaa..0000000 Binary files a/doc/rvi_protocol_stack.png and /dev/null differ diff --git a/doc/rvi_protocol_x509_credential.png b/doc/rvi_protocol_x509_credential.png deleted file mode 100644 index d63bb24..0000000 Binary files a/doc/rvi_protocol_x509_credential.png and /dev/null differ diff --git a/doc/rvi_protocol_x509_pub_key.png b/doc/rvi_protocol_x509_pub_key.png deleted file mode 100644 index f685ad7..0000000 Binary files a/doc/rvi_protocol_x509_pub_key.png and /dev/null differ -- cgit v1.2.1