text: saltyrtc-meta/Task-WebRTC.md at master · saltyrtc/saltyrtc-meta · GitHub
  saltyrtc-meta/Task-WebRTC.md
  447 lines (361 sloc) 18 KB
  SaltyRTC WebRTC Task
  This task uses the end-to-end encryption techniques of SaltyRTC to set up a secure WebRTC peer-to-peer connection. It also adds another security layer for data channels that are available to users. The signalling channel will persist and should be handed over to a dedicated data channel once the peer-to-peer connection has been set up. Therefore, further signalling communication between the peers may not require a dedicated WebSocket connection over a SaltyRTC server.
  All terms from the SaltyRTC protocol specification are valid in this document. Furthermore, this document will reference API parts of the WebRTC specification.
  The SaltyRTC chunking specification makes it possible to split a message into chunks and reassemble the message on the receiver's side while allowing any combination of ordered/unordered and reliable/unreliable transport channel underneath.
  This protocol adds another security layer for WebRTC data channels as we want our protocol to sustain broken (D)TLS environments. A data channel that uses this security layer will be called Secure Data Channel. Note that the user MAY or MAY NOT choose to use secure data channels for its purpose. However, the handed over signalling channel MUST use a secure data channel.
  v1.webrtc.tasks.saltyrtc.org
  The exclude field MUST contain an Array of WebRTC data channel ids (non-negative integers less than 65535) that SHALL not be used for the signalling channel. This Array MUST be available to be set from user applications that use pre-negotiated data channel ids.
  The handover field SHALL be set to true unless the user application explicitly requested to turn off the handover feature in which case it SHALL be set to false.
  A client who receives the task's data from the remote peer MUST do the following checks:
  The exclude field MUST contain an Array of WebRTC data channel IDs (non-negative integers less than 65535) that SHALL not be used for the signalling channel. The client SHALL store this list for usage during handover.
  The handover field MUST be either true or false. If both client's values are true, the negotiated value is true. In any other case, the negotiated value is false and a handover requested by the user application SHALL be rejected (see the Signalling Channel Handover section for details).
  This protocol adds another security layer to WebRTC's data channels which the handed over signalling channel SHALL use. It MUST be possible for the user application to utilise this security layer for further data channels. The secure data channel MUST use NaCl for encryption/decryption of messages.
  Outgoing messages MUST be processed and encrypted by following the Sending a Secure Data Channel Message section.
  Incoming messages MUST be processed and decrypted by following the Receiving a Secure Data Channel Message section.
  As described in the Sending a Secure Data Channel Message and the Receiving a Secure Data Channel Message section, each new secure data channel instance is being treated as a distinct remote peer from the nonce's perspective and independent of the underlying data channel id. To prevent nonce reuse, it is absolutely vital that each secure data channel instance has its own cookie, sequence number and overflow number, each for incoming and outgoing messages. Both clients SHALL use cryptographically secure random numbers for generating the cookie and the sequence number.
  If the negotiated handover parameter is true, the user application SHOULD initiate the handover process:
  The client creates a new data channel on the RTCPeerConnection instance with the RTCDataChannelInit object containing only the following values:
  protocol SHALL be set to the same subprotocol that has been negotiated with the server,
  The newly created RTCDataChannel instance SHALL be secured by following the Secure Data Channel section.
  If the RTCDataChannel does not change its state to open, the client SHALL continue using the WebSocket-based signalling channel.
  For all messages that are being exchanged over secure data channels (such as the handed over signalling channel), the nonce/header MUST be slightly changed:
  The cookie field remains the same as in the SaltyRTC protocol specification. Each new secure data channel SHALL have a new cryptographically secure random cookie, one for incoming messages and one for outgoing messages.
  Overflow Number and Sequence Number SHALL remain the same as in the SaltyRTC protocol specification. Each new secure data channel instance SHALL have its own overflow number and sequence number, each for outgoing and incoming messages.
  Sending a Secure Data Channel Message
  The same procedure as described in the SaltyRTC protocol specification SHALL be followed. However, for all messages that are being exchanged over secure data channels, the following changes MUST be applied:
  For the handed over signalling channel, the encrypted message MUST be fragmented into chunks using SaltyRTC chunking in unreliable/unordered mode (for legacy reasons) after encryption. The chunk size MUST be less or equal to the maxMessageSize value of the RTCPeerConnection's RTCSctpTransport.
  Receiving a Secure Data Channel Message
  For the handed over signalling channel, the encrypted message MUST be reassembled into a complete signalling message using SaltyRTC chunking in unreliable/unordered mode (for legacy reasons) before decryption.
  Source and destination addresses are not present in the secure data channel's nonce/header.
  Overflow number and sequence number SHALL NOT be validated to ensure unordered and unreliable secure data channels can function properly. However, a client SHOULD check that two consecutive incoming messages of the same data channel do not have the exact same overflow and sequence number.
  The following messages are new messages that will be exchanged between two clients (initiator and responder) over the signalling channel. Note that the signalling channel may be handed over to a data channel any time which is RECOMMENDED to be supported by the implementation. Furthermore, the handed over signalling channel MUST support all existing client-to-client message types.
  +----------+    +------------------------------+
  |          v    |                              |
  +----+----------+----+-----+                        v
  |      offer / answer      |    +----------+    +---+---+
  --->+ candidates / application +--->+ handover +--->+ close |
  +--------------------------+    +-----+----+    +---+---+
  +--------------------+-----+       |
  |      offer / answer      +-------+
  | candidates / application |
  |             offer             |
  |             answer            |
  |      candidates (n times)     |
  |      candidates (m times)     |
  'offer' Message
  At any time, the initiator MAY send an 'offer' message to the responder.
  The initiator MUST set the offer field to the Map of its WebRTC RTCPeerConnection's local description the user application has generated with calling createOffer on the RTCPeerConnection instance. The offer field SHALL be a Map and MUST contain:
  The type field containing a valid RTCSdpType in string representation.
  The sdp field containing a blob of SDP data in string representation. If the type field is rollback, the field MAY be omitted.
  The responder SHALL validate that the offer field is a Map containing the above mentioned fields and value types. It SHALL continue by requesting the user application to set the value of that field as the WebRTC RTCPeerConnection's remote description and creating an answer.
  'answer' Message
  Once the user application of the responder has set the remote description on its WebRTC RTCPeerConnection instance and generated an answer by calling createAnswer on the instance, the user application SHALL request sending an 'answer' message. The answer field SHALL be a Map and MUST contain:
  The initiator SHALL validate that the answer field is a Map containing the above mentioned fields and value types. It SHALL continue by requesting the user application to set the value of that field as the WebRTC RTCPeerConnection's remote description.
  'candidates' Message
  A client who sends an ICE candidate SHALL set the candidates field to an Array. Elements of this array SHALL either be Nil or a Map containing the following fields:
  The candidate field SHALL contain an SDP candidate-attribute or an empty string as defined in the WebRTC specification in string representation.
  The sdpMid field SHALL contain the media stream identification as defined in the WebRTC specification in string representation or Nil.
  The sdpMLineIndex field SHALL contain the index of the media description the candidate is associated with as described in the WebRTC specification. It's value SHALL be either an unsigned integer (16 bits) or Nil.
  The usernameFragment field SHALL contain the ICE user fragment as defined in the WebRTC specification in string representation or Nil.
  (Note: The naming is inconsistent with the rest of the protocol, since it uses camelCase keys instead of under_scores. The reason for this is ease of use in browser implementations: When using camelCase each candidates entry can be passed directly to the JavaScript WebRTC implementation.)
  The receiving client SHALL validate that the candidates field is an Array containing one or more Maps. These Maps SHALL contain the above mentioned fields value types. It SHALL continue by requesting the user application to add the value of each item in the Array as a remote candidate to its WebRTC RTCPeerConnection instance.
  "candidate": "...",
  "sdpMid": "data",
  "usernameFragment": "abcdefgh"
  "sdpMLineIndex": null, // Nil
  "usernameFragment": null // Nil
  null // Nil
  Both clients SHALL send this message once the secure data channel dedicated for the signalling is open. However, the message MUST be sent over the WebSocket-based signalling channel.
  A client who sends a 'handover' message SHALL NOT include any additional fields. After sending this message, the client MUST send further signalling messages over the new data channel based signalling channel only.
  Validate that the negotiated handover parameter is true and otherwise treat this incident as a protocol error,
  The message itself and the client's behaviour is described in the SaltyRTC protocol specification. Once the signalling channel has been handed over to a secure data channel, sent and received 'close' messages SHALL trigger closing the underlying data channel used for signalling. The user application MAY continue using the RTCPeerConnection instance and its data channels. However, secure data channels MAY or MAY NOT be available once the signalling's data channel has been closed, depending on the flexibility of the client's implementation.