Relayed Data Task (#141)

This adds a task that simply exists for the purpose of relaying arbitrary data from initiator to responder.

Author: dbrgn

Readme.md

@@ -6,8 +6,10 @@
 
 SaltyRTC is an **end-to-end encrypted signalling protocol**. It offers
 to freely choose from a range of signalling tasks, such as setting up a
-**WebRTC** or **ORTC** peer-to-peer connection. SaltyRTC is completely
-open to new and custom signalling tasks for everything feasible.
+**WebRTC** or **ORTC** peer-to-peer connection, or simply to exchange
+arbitrary data over the established transport in a secure manner.
+SaltyRTC is completely open to new and custom signalling tasks for
+everything feasible.
 
 In this repository, you can find...
 
@@ -17,6 +19,9 @@ In this repository, you can find...
   encryption techniques.
 * The [SaltyRTC ORTC Task Protocol](Task-ORTC.md) to set up a secure
   ORTC peer-to-peer connection.
+* The [SaltyRTC Relayed Data Task Protocol](Task-RelayedData.md) to set
+  up a secure channel for exchanging arbitrary data by using SaltyRTC's
+  end-to-end encryption techniques.
 * The [SaltyRTC Chunking Specification](Chunking.md) used by SaltyRTC's
   WebRTC task. However, the specification can also be used as a generic
   message chunking solution.

Task-ORTC.md

@@ -12,8 +12,8 @@ dedicated WebSocket connection over a SaltyRTC server.
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
-document are to be interpreted as described in [RFC 2119
-[RFC2119]](https://tools.ietf.org/html/rfc2119).
+document are to be interpreted as described in
+[RFC 2119](https://tools.ietf.org/html/rfc2119).
 
 # Terminology
 
@@ -158,7 +158,7 @@ channel:
    designate these for handover, the *label* field of each message SHALL
    be set to `handover`.
 2. The client creates a new `RTCDataChannel` instance from the negotiated
-   `RTCDataTransport` instance and the `RTCDataChannelParameters` object 
+   `RTCDataTransport` instance and the `RTCDataChannelParameters` object
    containing only the following values:
    * *ordered* SHALL be set to `true`,
    * *protocol* and *label* SHALL be set to the same subprotocol that has

Task-RelayedData.md

@@ -0,0 +1,104 @@
+# SaltyRTC Relayed Data Task
+
+This task uses the end-to-end encrypted WebSocket connection set up by
+the SaltyRTC protocol to send user defined messages.
+
+# Conventions
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in
+[RFC 2119](https://tools.ietf.org/html/rfc2119).
+
+# Terminology
+
+All terms from the [SaltyRTC protocol
+specification](./Protocol.md#terminology) are valid in this document.
+
+# Task Protocol Name
+
+The following protocol name SHALL be used for task negotiation:
+
+`v0.relayed-data.tasks.saltyrtc.org`
+
+# Task Data
+
+This task does not currently make use of the *data* field of the 'auth'
+messages described in the [SaltyRTC protocol
+specification](./Protocol.md#auth-message). The task data sent by the
+peers should be `Nil`.
+
+# Message Structure
+
+The same message structure as defined in the [SaltyRTC protocol
+specification](./Protocol.md#message-structure) SHALL be used.
+
+# Client-to-Client Messages
+
+Once the task has taken over, user data MAY be sent using 'data'
+messages.
+
+If one of the sides wants to terminate the connection, the 'close'
+Message SHALL be sent as described in the [SaltyRTC protocol
+specification](./Protocol.md#close-message).
+
+Other message types (including the
+['application' message](./Protocol.md#application-message))
+SHALL NOT be used in the Relayed Data task.
+
+## Message States (Beyond 'auth')
+
+          +--+
+          |  v
+        +-+----+    +-------+
+    -+->+ data +--->+ close |
+     |  +------+    +-------+
+     |                  ^
+     +------------------+
+
+## 'data' messages
+
+Once the task has taken over, the user application of a client MAY
+trigger sending this message.
+
+This message MAY contain any MessagePack value type. If the user does
+not wish to encode messages with MessagePack, they can be transmitted
+using MessagePack binary or string value types.
+
+A task who sends a 'data' message SHALL set the *p* field to whatever
+data the user application provided. The name is an abbreviation that
+stands for "payload" and has been chosen to reduce the message overhead.
+
+A receiving task SHALL validate that the *p* field is set. It MUST pass
+the payload inside that field to the user application.
+
+```
+{
+  "type": "data",
+  "p": ...
+}
+```
+
+# Sending a Message
+
+The task must provide a way for the user application to send 'data'
+messages. It MUST validate the messages as described in the section on
+['data' messages](#data-messages).
+
+The same procedure as described in the [SaltyRTC protocol
+specification](./Protocol.md#sending-a-signalling-message) SHALL be
+followed to send 'data' messages.
+
+# Receiving a Message
+
+Incoming task messages shall be processed as follows:
+
+* The client SHALL validate and decrypt the message according to the
+  [SaltyRTC protocol specification](./Protocol.md#receiving-a-signalling-message)
+* If the message type is 'close', the message MUST be handled as
+  described in the
+  [SaltyRTC protocol specification](./Protocol.md#close-message)
+* Otherwise, if the message type is 'data', the payload MUST be passed
+  to the user application.
+* For all other message types, the connection MUST be closed with a
+  close code of `3001` (*Protocol Error*)

Task-WebRTC.md

@@ -12,8 +12,8 @@ dedicated WebSocket connection over a SaltyRTC server.
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
-document are to be interpreted as described in [RFC 2119
-[RFC2119]](https://tools.ietf.org/html/rfc2119).
+document are to be interpreted as described in
+[RFC 2119](https://tools.ietf.org/html/rfc2119).
 
 # Terminology