idnits 2.17.1 draft-ietf-ppsp-base-tracker-protocol-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 31, 2015) is 3036 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5245 (Obsoleted by RFC 8445, RFC 8839) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5389 (Obsoleted by RFC 8489) ** Obsolete normative reference: RFC 5766 (Obsoleted by RFC 8656) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 7525 (Obsoleted by RFC 9325) Summary: 8 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 PPSP Rui S. Cruz 3 INTERNET-DRAFT Mario S. Nunes 4 Intended Status: Standards Track IST/INESC-ID/INOV 5 Expires: July 3, 2016 Yingjie Gu 6 Jinwei Xia 7 Rachel Huang 8 Huawei 9 Joao P. Taveira 10 IST/INOV 11 Deng Lingli 12 China Mobile 13 December 31, 2015 15 PPSP Tracker Protocol-Base Protocol (PPSP-TP/1.0) 16 draft-ietf-ppsp-base-tracker-protocol-12 18 Abstract 20 This document specifies the base Peer-to-Peer Streaming Protocol- 21 Tracker Protocol (PPSP-TP/1.0), an application-layer control 22 (signaling) protocol for the exchange of meta information between 23 trackers and peers. The specification outlines the architecture of 24 the protocol and its functionality, and describes message flows, 25 message processing instructions, message formats, formal syntax and 26 semantics. The PPSP Tracker Protocol enables cooperating peers to 27 form content streaming overlay networks to support near real-time 28 Structured Media content delivery (audio, video, associated timed 29 text and metadata), such as adaptive multi-rate, layered (scalable) 30 and multi-view (3D) videos, in live, time-shifted and on-demand 31 modes. 33 Status of this Memo 35 This Internet-Draft is submitted to IETF in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF), its areas, and its working groups. Note that 40 other groups may also distribute working documents as Internet- 41 Drafts. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 47 The list of current Internet-Drafts can be accessed at 48 http://www.ietf.org/1id-abstracts.html 50 The list of Internet-Draft Shadow Directories can be accessed at 51 http://www.ietf.org/shadow.html 53 Copyright and License Notice 55 Copyright (c) 2015 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (http://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5 72 1.2 Design Overview . . . . . . . . . . . . . . . . . . . . . . 7 73 1.2.1 Typical Use Cases . . . . . . . . . . . . . . . . . . . 8 74 1.2.2 Enrollment and Bootstrap . . . . . . . . . . . . . . . 9 75 2 Protocol Architecture and Functional View . . . . . . . . . . . 11 76 2.1 Messaging Model . . . . . . . . . . . . . . . . . . . . . . 12 77 2.2 Request/Response model . . . . . . . . . . . . . . . . . . 12 78 2.3 State Machines and Flows of the Protocol . . . . . . . . . 13 79 2.3.1 Normal Operation . . . . . . . . . . . . . . . . . . . 15 80 2.3.2 Error Conditions . . . . . . . . . . . . . . . . . . . 16 81 3 Protocol Specification . . . . . . . . . . . . . . . . . . . . 17 82 3.1 Presentation Language . . . . . . . . . . . . . . . . . . . 17 83 3.2 Resource Element Types . . . . . . . . . . . . . . . . . . 17 84 3.2.1 Version . . . . . . . . . . . . . . . . . . . . . . . . 17 85 3.2.2 Peer Number Element . . . . . . . . . . . . . . . . . . 17 86 3.2.3 Swarm Action Element . . . . . . . . . . . . . . . . . 18 87 3.2.4 Peer Information Elements . . . . . . . . . . . . . . . 19 88 3.2.5 Statistics and Status Information Element . . . . . . . 20 89 3.3 Requests and Responses . . . . . . . . . . . . . . . . . . 21 90 3.3.1 Request Types . . . . . . . . . . . . . . . . . . . . . 21 91 3.3.2 Response Types . . . . . . . . . . . . . . . . . . . . 22 92 3.3.3 Request Element . . . . . . . . . . . . . . . . . . . . 22 93 3.3.4 Response Element . . . . . . . . . . . . . . . . . . . 23 94 3.4 PPSP-TP Message Element . . . . . . . . . . . . . . . . . . 24 95 4 Protocol Specification: Encoding and Operation . . . . . . . . 24 96 4.1 Requests and Responses . . . . . . . . . . . . . . . . . . . 25 97 4.1.1 CONNECT Request . . . . . . . . . . . . . . . . . . . . 25 98 4.1.1.1 Example . . . . . . . . . . . . . . . . . . . . . . 27 99 4.1.2 FIND Request . . . . . . . . . . . . . . . . . . . . . 32 100 4.1.2.1 Example . . . . . . . . . . . . . . . . . . . . . . 33 101 4.1.3 STAT_REPORT Request . . . . . . . . . . . . . . . . . . 35 102 4.1.3.1 Example . . . . . . . . . . . . . . . . . . . . . . 36 103 4.2 Response element in response Messages . . . . . . . . . . . 37 104 4.3 Error and Recovery conditions . . . . . . . . . . . . . . . 37 105 4.4 Parsing of Unknown Fields in Message-body . . . . . . . . . 38 106 5 Operations and Manageability . . . . . . . . . . . . . . . . . 39 107 5.1 Operational Considerations . . . . . . . . . . . . . . . . 39 108 5.1.1 Installation and Initial Setup . . . . . . . . . . . . 39 109 5.1.2 Migration Path . . . . . . . . . . . . . . . . . . . . 40 110 5.1.3 Requirements on Other Protocols and Functional 111 Components . . . . . . . . . . . . . . . . . . . . . . 40 112 5.1.4 Impact on Network Operation . . . . . . . . . . . . . . 40 113 5.1.5 Verifying Correct Operation . . . . . . . . . . . . . . 40 114 5.2 Management Considerations . . . . . . . . . . . . . . . . . 40 115 5.2.1 Interoperability . . . . . . . . . . . . . . . . . . . 40 116 5.2.2 Management Information . . . . . . . . . . . . . . . . 41 117 5.2.3 Fault Management . . . . . . . . . . . . . . . . . . . 41 118 5.2.4 Configuration Management . . . . . . . . . . . . . . . 41 119 5.2.5 Accounting Management . . . . . . . . . . . . . . . . . 42 120 5.2.6 Performance Management . . . . . . . . . . . . . . . . 42 121 5.2.7 Security Management . . . . . . . . . . . . . . . . . . 42 122 6 Security Considerations . . . . . . . . . . . . . . . . . . . . 42 123 6.1 Authentication between Tracker and Peers . . . . . . . . . 42 124 6.2 Content Integrity protection against polluting 125 peers/trackers . . . . . . . . . . . . . . . . . . . . . . 43 126 6.3 Residual attacks and mitigation . . . . . . . . . . . . . . 43 127 6.4 Pro-incentive parameter trustfulness . . . . . . . . . . . 43 128 7 Guidelines for Extending PPSP-TP . . . . . . . . . . . . . . . 44 129 7.1 Forms of PPSP-TP Extension . . . . . . . . . . . . . . . . 45 130 7.2 Issues to Be Addressed in PPSP-TP Extensions . . . . . . . 46 131 8 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 47 132 8.1 MIME Type Registry . . . . . . . . . . . . . . . . . . . . . 47 133 8.2 PPSP Tracker Protocol Version Number Registry . . . . . . . 48 134 9 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 48 135 10 References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 136 10.1 Normative References . . . . . . . . . . . . . . . . . . . 49 137 10.2 Informative References . . . . . . . . . . . . . . . . . . 49 138 Appendix A. Revision History . . . . . . . . . . . . . . . . . . 51 139 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52 141 1 Introduction 143 The Peer-to-Peer Streaming Protocol (PPSP) is composed of two 144 protocols: the PPSP Tracker Protocol and the PPSP Peer Protocol. 145 [RFC6972] specifies that the Tracker Protocol should standardize the 146 messages between PPSP peers and PPSP trackers and also defines the 147 requirements. 149 The PPSP Tracker Protocol provides communication between trackers and 150 peers, by which peers send meta information to trackers, report 151 streaming status and obtain peer lists from trackers. 153 The PPSP architecture requires PPSP peers able to communicate with a 154 tracker in order to participate in a particular streaming content 155 swarm. This centralized tracker service is used by PPSP peers for 156 acquisition of peer lists. 158 The signaling and the media data transfer between PPSP peers is not 159 in the scope of this specification. 161 This document introduces a base PPSP Tracker Protocol which satisfies 162 the requirements from [RFC6972]. 164 1.1 Terminology 166 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 167 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 168 document are to be interpreted as described in [RFC2119]. 170 absolute time: Absolute time is expressed as ISO 8601 timestamps, 171 using zero UTC offset. Fractions of a second may be indicated. 172 Example for December 25, 2010 at 14h56 and 20.25 seconds: basic 173 format 20101225T145620.25Z or extended format 2010-12- 174 25T14:56:20.25Z. 176 chunk: An uniformly atomic subset of the resource that constitutes 177 the basic unit of data organized in P2P streaming for storage, 178 scheduling, advertisement and exchange among peers. 180 chunk ID: A unique resource identifier for a chunk. The identifier 181 type depends on the addressing scheme used, i.e., an integer, an 182 HTTP-URL and possibly a byte-range, and is described in the MPD. 184 LEECH: A LEECH refers to the peers in a swarm that download content 185 from other peers as well as contribute its downloaded content with 186 others. A LEECH should join the swarm with uncompleted media content. 188 MPD (Media Presentation Description): Formalized description for a 189 media presentation, i.e., describes the structure of the media, 190 namely, the Representations, the codecs used, the chunks, and the 191 corresponding addressing scheme. 193 peer: A participant in a P2P streaming system that not only receives 194 streaming content, but also caches and streams streaming content to 195 other participants. 197 peer ID: The identifier of a peer such that other peers, or the 198 Tracker, can refer to the peer by using its ID. The peer ID is 199 mandatory, can take the form of a universal unique identifier (UUID), 200 defined in [RFC4122], and can be bound to a network address of the 201 peer, i.e., an IP address, or a uniform resource identifier/locator 202 (URI/URL) that uniquely identifies the corresponding peer in the 203 network. The peer ID and any required security certificates are 204 obtained from an offline enrollment server. 206 peer list: A list of peers that are in the same swarm maintained by 207 the tracker. A peer can fetch the peer list of a swarm from the 208 tracker. 210 PPSP: The abbreviation of Peer-to-Peer Streaming Protocol. 212 PPSP-TP: The abbreviation of Peer-to-Peer Streaming Protocols - 213 Tracker Protocol. 215 SEEDER: A SEEDER refers to the peers in a swarm that only contribute 216 the content they have to others. A SEEDER should join the swarm with 217 the complete media content. 219 service portal: A logical entity typically used for client enrollment 220 and content information publishing, searching and retrieval. It is 221 usually located in a server of content provider. 223 swarm: A swarm refers to a group of peers that exchange data to 224 distribute chunks of the same content (e.g., video/audio program, 225 digital file, etc.) at a given time. 227 swarm ID: The identifier of a swarm containing a group of peers 228 sharing a common streaming content. The swarm ID may use a universal 229 unique identifier (UUID), e.g., a 64 or 128 bit datum to refer to the 230 content resource being shared among peers. 232 tracker: A tracker refers to a directory service that maintains a 233 list of peers participating in a specific audio/video channel or in 234 the distribution of a streaming file. It is a logical component that 235 can be deployed in a centralized or distributed way. 237 transaction ID: The identifier of a request from the peer to the 238 tracker. It is used to disambiguate responses that may arrive in a 239 different order of the corresponding requests. 241 1.2 Design Overview 243 The functional entities related to PPSP protocols are the Client 244 Media Player, the service portal, the tracker and the peers. The 245 complete description of Client Media Player and service portal is not 246 discussed here, as not in the scope of the specification. The 247 functional entities directly involved in the PPSP Tracker Protocol 248 are trackers and peers (which may support different capabilities). 250 The Client Media Player is a logical entity providing direct 251 interface to the end user at the client device, and includes the 252 functions to select, request, decode and render contents. The Client 253 Media Player may interface with the local peer application using 254 request and response standard formats for HTTP request and response 255 messages [RFC7230]. 257 The service portal is a logical entity typically used for client 258 enrollment and content information publishing, searching and 259 retrieval. 261 A peer corresponds to a logical entity (typically in a user device) 262 that actually participates in sharing a media content. Peers are 263 organized in (various) swarms corresponding each swarm to the group 264 of peers streaming a certain content at any given time. 266 A tracker is a logical entity that maintains the lists of peers 267 storing chunks for a specific Live media channel or on-demand media 268 streaming content, answers queries from peers and collects 269 information on the activity of peers. While a tracker may have an 270 underlying implementation consisting of more than one physical node, 271 logically the tracker can most simply be thought of as a single 272 element, and in this document it will be treated as a single logical 273 entity. Communications between these physical nodes to present them 274 as a single tracker to peers is not considered in PPSP-TP which is a 275 protocol between a tracker and a peer. 277 PPSP-TP is not used to exchange actual content data (either on demand 278 or live streaming) with peers, but information about which peers can 279 provide the content. And PPSP-TP is not designed for applications 280 where in-sync reception is needed. 282 1.2.1 Typical PPSP Session 284 When a peer wants to receive streaming of a selected content (LEECH 285 mode): 287 1. Peer connects to a tracker and joins a swarm. 288 2. Peer acquires a list of other peers in the swarm from the 289 tracker. 290 3. Peer exchanges its content availability with the 291 peers on the obtained peer list. 292 4. Peer identifies the peers with desired content. 294 5. Peer requests content from the identified peers. 296 When a peer wants to share streaming contents (SEEDER mode) with 297 other peers: 299 1. Peer connects to a tracker. 300 2. Peer sends information to the tracker about the swarms 301 it belongs to (joined swarms). 302 3. Peer waits other peers as LEECH to connect with it (see previous 303 step 3 - 5). 305 After having been disconnected due to some termination conditions or 306 user controls, a peer can resume previous activity by connecting and 307 re-joining the corresponding swarm(s). 309 1.2.2 An Example of PPSP Session 311 In order to be able to bootstrap in the P2P network, a peer must 312 first obtain a peer ID and any required security certificates or 313 authorization tokens from an enrollment service (end-user 314 registration). The peer ID MUST be unique (see the terminology of 315 peer ID in Section 1.1), however, the representation of the peer ID 316 is not considered in this document. 318 +--------+ +--------+ +--------+ +---------+ +--------+ 319 | Player | | Peer_1 | | Portal | | Tracker | | Peer_2 | 320 +--------+ +--------+ +--------+ +---------+ +--------+ 321 | | | | | 322 (a) |--Page request----------------->| | | 323 |<--------------Page with links--| | | 324 |--Select stream (MPD request)-->| | | 325 |<--------------------OK+MPD(x)--| | | 326 (b) |--Start/Resume->|--CONNECT(join x)------------>| | 327 |<-----------OK--|<----------------OK+Peerlist--| | 328 | | | | 329 |--Get(chunk)--->|<---------- (Peer protocol) ------------->| 330 |<--------chunk--|<---------------------------------chunks--| 331 : : : : : 332 | |--STAT_REPORT---------------->| | 333 | |<-------------------------OK--| | 334 : : : : : 335 | |--FIND----------------------->| | 336 | |<----------------OK+Peerlist--| | 337 : : : : : 338 |--Get(chunk)--->|<---------- (Peer protocol) ------------->| 339 |<--------chunk--|<---------------------------------chunks--| 340 : : : : : 341 Figure 1: A typical PPSP session for streaming a content. 343 To join an existing P2P streaming service and to participate in 344 content sharing, any peer must first locate a tracker. 346 As illustrated in Figure 1, a P2P streaming session may be initiated 347 starting at point (a), with the Client Media Player browsing for the 348 desired content in order to request it (to the local Peer_1 in the 349 figure), or resume a previously initiated stream, but starting at 350 point (b). For this example, the Peer_1 is in mode LEECH. 352 At point (a) in Figure 1, the Client Media Player accesses the Portal 353 and selects the content of interest. The Portal returns the Media 354 Presentation Description (MPD) file that includes information about 355 the address of one or more trackers (that can be grouped by tiers of 356 priority) which are controlling the swarm x for that media content 357 (e.g., content x). 359 With the information from the MPD the Client Media Player is able to 360 trigger the start of the streaming session, requesting to the local 361 Peer_1 the chunks of interest. 363 The PPSP streaming session is then started (or resumed) at Peer_1 by 364 sending a PPSP-TP CONNECT message to the tracker in order to join 365 swarm x. The tracker will then return the OK response message 366 containing a peer list, if the CONNECT message is successfully 367 accepted. From that point, every chunk request is addressed by Peer_1 368 to its neighbors (Peer_2 in Figure 1) using peer protocol, e.g., 369 [RFC7574], returning the received chunks to the Client Media Player. 371 Once connected, Peer_1 needs to periodically report its status and 372 statistics data to the tracker using a STAT_REPORT message. 374 If Peer_1 needs to refresh its neighborhood (for example, due to 375 churn) it will send a PPSP-TP FIND message (with the desired scope) 376 to the tracker. 378 Peers that are only SEEDERs (i.e., serving contents to other peers), 379 as are the typical cases of service provider P2P edge caches and/or 380 Media Servers, trigger their P2P streaming sessions for contents x, 381 y, z... (Figure 2), not from Media Player signals, but from some 382 "Start" activation signal received from the service provider 383 provisioning mechanism. In this particular case the peer starts or 384 resumes all its streaming sessions just by sending a PPSP-TP CONNECT 385 message to the tracker (Figure 2), in order to "join" all the 386 requested swarms. 388 Periodically, the peer also report its status and statistics data to 389 the tracker using a PPSP-TP STAT_REPORT message. 391 +---------+ +---------+ 392 | SEEDER | | Tracker | 393 +---------+ +---------+ 394 | | 395 Start->|--CONNECT (join x,y,z)-------->| 396 |<--------------------------OK--| 397 : : 398 | | 399 |--STAT_REPORT----------------->| 400 |<--------------------------Ok--| 401 : : 402 | | 403 |--STAT_REPORT----------------->| 404 |<--------------------------Ok--| 405 : : 407 Figure 2: A typical PPSP session for a streaming SEEDER. 409 The specification of the mechanisms used by the Client Media Player 410 (or provisioning process) and the peer to signal start/resume streams 411 or request media chunks, obtain a peer ID, security certificates or 412 tokens are not in the scope of this document. 414 2 Protocol Architecture and Functional View 416 PPSP-TP is designed with a layered approach i.e., a PPSP-TP 417 Request/Response layer, a Message layer and a Transport layer. The 418 PPSP-TP Request/Response layer deals with the interactions between 419 tracker and peers using request and response messages (see Figure 3). 421 +----------------------+ 422 | Application | 423 +----------------------+ 424 | Request/Response | PPSP-TP 425 |----------------------| 426 | (HTTP) Message | 427 +----------------------+ 428 | TRANSPORT | 429 +----------------------+ 431 Figure 3: Abstract layering of PPSP-TP. 433 The Message layer deals with the framing format, for encoding and 434 transmitting the data through the underlying transport protocol, as 435 well as the asynchronous nature of the interactions between tracker 436 and peers. 438 The Transport layer is responsible for the actual transmission of 439 requests and responses over network transports, including the 440 determination of the connection to use for a request or response 441 message when using TCP, or TLS [RFC5246] over it. 443 2.1 Messaging Model 445 The messaging model of PPSP-TP aligns with HTTP protocol and the 446 semantics of its messages, currently in version 1.1 [RFC7230], but 447 intended to support future versions of HTTP. 449 2.2 Request/Response model 451 PPSP-TP uses a REST-Like (Representational State Transfer) design 452 with the goal of leveraging current HTTP implementations and 453 infrastructure, as well as familiarity with existing REST-like 454 services in popular use. PPSP-TP messages use the UTF-8 character 455 set [RFC3629] and are either requests from peers to a tracker 456 service, or responses from a tracker service to peers. The request 457 and response semantics are carried as entities (header and body) in 458 messages which correspond to either HTTP request methods or HTTP 459 response codes, respectively. 461 PPSP-TP uses the HTTP POST method to send parameters in requests. 462 PPSP-TP messages use JavaScript Object Notation (JSON) [RFC7159] to 463 encode message bodies. 465 Peers send requests to tracker. Trackers send a single response for 466 each request though both requests and responses can be subject to 467 fragmentation of messages in transport. 469 The request messages of the base protocol are listed in Table 1: 471 +------------------------------+ 472 | PPSP-TP/1.0 Request Messages | 473 +------------------------------+ 474 | CONNECT | 475 | FIND | 476 | STAT_REPORT | 477 +------------------------------+ 479 Table 1: Request Messages 481 CONNECT: This request message is used when a peer registers in the 482 tracker (or if already registered) to notify it about the 483 participation in named swarm(s). The tracker records the peer ID, 484 connect-time (referenced to the absolute time), peer IP addresses 485 (and associated location information), link status and peer mode 486 for the named swarm(s). The tracker also changes the content 487 availability of the valid named swarm(s), i.e., changes the peers 488 lists of the corresponding swarm(s) for the requesting peer ID. On 489 receiving a CONNECT message, the tracker first checks the peer 490 mode type (SEEDER/LEECH) for the specified swarm(s) and then 491 decides the next steps (more details are referred in section 4.1) 493 FIND: This request message is used by peers to request to the 494 tracker, whenever needed, a list of peers active in the named 495 swarm. On receiving a FIND message, the tracker finds the peers, 496 listed in content status of the specified swarm that can satisfy 497 the requesting peer's requirements, returning the list to the 498 requesting peer. To create the peer list, the tracker may take 499 peer status, capabilities and peers priority into consideration. 500 Peer priority may be determined by network topology preference, 501 operator policy preference, etc. 503 STAT_REPORT: This request message is used to allow an active peer to 504 send status (and optionally statistic data) to the tracker to 505 signal continuing activity. This request message MUST be sent 506 periodically to the tracker while the peer is active in the 507 system. 509 2.3 State Machines and Flows of the Protocol 511 The state machine for the tracker is very simple, as shown in 512 Figure 4. Peer ID registrations represent a dynamic piece of state 513 maintained by the network. 515 -------------------------------------------- 516 / \ 517 | +------------+ +=========+ +======+ | 518 \-| TERMINATED |<---| STARTED |<---| INIT |<-/ 519 +------------+ +=========+ +======+ 520 (Transient) \- (start tracker) 521 Figure 4: Tracker State Machine 523 When there are no peers connected in the tracker, the state machine 524 is in the INIT state. 526 When the "first" peer connects for registration with its peer ID, the 527 state machine moves from INIT to STARTED. As long as there is at 528 least one active registration of a peer ID, the state machine remains 529 in the STARTED state. When the "last" peer ID is removed, the state 530 machine transitions to TERMINATED. From there, it immediately 531 transitions back to the INIT state. Because of that, the TERMINATED 532 state here is transient. 534 Once in STARTED state, each peer is instantiated (per peer ID) in the 535 tracker state machine with a dedicated transaction state machine 536 (Figure 5), which is deleted when the peer ID is removed. 538 -------------------------------------------- 539 / \ 540 | +------------+ +=========+ +======+ | 541 \-| TERMINATED |<---| STARTED |<---| INIT |<-/ 542 +------------+ +=========+ +======+ 543 (Transient) | (1) \- (start tracker) 544 V 545 +-----------+ +-------+ rcv CONNECT 546 (Transient) | TERMINATE | | START | --------------- (1) 547 +-----------+ +-------+ strt init timer 548 rcv FIND ^ | 549 rcv STAT_REPORT | | 550 on registration error | v 551 on action error | +------------+ 552 ---------------- (A) +<-----| PEER | (Transient) 553 stop init timer | | REGISTERED | 554 snd error | +------------+ 555 | | 556 on timeout (C) | | process swarm actions 557 ---------------- | | --------------------- (2) 558 stop track timer (C) | | snd OK (PeerList) 559 clean peer info (C) | / stop init timer 560 del registration (C) | / strt track timer 561 | / 562 | | 563 | | rcv FIND 564 STAT_REPORT ERR(B) \ | ---- --------------- (3) 565 FIND ERR(B) ---- \ | / \ snd OK (PeerList) 566 CONNECT ERR(B) / \ \ | | | rst track timer 567 rcv CONNECT | (4) | | | | | 568 ----------- | v | v v | rcv STAT_REPORT 569 snd OK \ +==============+ / --------------- (3) 570 rst track timer ----| TRACKING |---- snd OK response 571 snd error (B) +==============+ rst track timer 573 Figure 5: Per-Peer-ID Transaction State Machine and Flow Diagram 575 Unlike the tracker state machine, which exists even when no peer IDs 576 are registered, the "per-Peer-ID" transaction state machine is 577 instantiated only when the peer ID starts registration in the 578 tracker, and is deleted when the peer ID is de-registered/removed. 579 This allows for an implementation optimization whereby the tracker 580 can destroy the objects associated with the "per-Peer-ID" transaction 581 state machine once it enters the TERMINATE state (Figure 5). 583 When a new peer ID is added, the corresponding "per-Peer-ID" state 584 machine is instantiated, and it moves into the PEER REGISTERED state. 585 Because of that, the START state here is transient. 587 When the peer ID is no longer bound to a registration, the "per-Peer- 588 ID" state machine moves to the TERMINATE state, and the state machine 589 is destroyed. 591 During the lifetime of streaming activity of a peer, the instantiated 592 "per-Peer-ID" transaction state machine progresses from one state to 593 another in response to various events. The events that may 594 potentially advance the state include: 596 o Reception of CONNECT, FIND and STAT_REPORT messages, or 597 o Timeout events. 599 The state diagram in Figure 5 illustrates state changes, together 600 with the causing events and resulting actions. Specific error 601 conditions are not shown in the state diagram. 603 2.3.1 Normal Operation 605 On normal operation the process consists of the following steps: 607 1) When a peer wants to access the system, it needs to register with 608 a tracker by sending a CONNECT message asking for the swarm(s) it 609 wants to join. This request from a new peer ID triggers the 610 instantiation in the tracker of a "per-Peer-ID" State Machine. In 611 the START state of the new "per-Peer-ID" SM, the tracker registers 612 the peer ID and associated information (IP addresses), starts the 613 "init timer" and moves to PEER REGISTERED state. 615 2) In PEER REGISTERED state, if peer ID is valid, the tracker either 616 a) processes the requested action(s) for the valid swarm 617 information contained in the CONNECT request and in case of 618 success the tracker stops the "init timer", starts the "track 619 timer" and sends the response to the peer (the response may 620 contain the appropriate list of peers for the joining swarm(s), as 621 detailed in section 4.1, or b) moves the valid FIND request to 622 TRACKING state. 624 3) In TRACKING state, STAT_REPORT or FIND messages received from that 625 peer ID will reset the "track timer" and the tracker responds to 626 the respectively requests with a) a successful condition, b) a 627 successful condition containing the appropriate list of peers for 628 the named swarm (section 4.2). 630 4) While TRACKING, a CONNECT message received from that peer ID with 631 valid swarm actions information (section 4.1.1) resets the "track 632 timer" and the tracker responds to the request with a successful 633 condition. 635 2.3.2 Error Conditions 637 Peers are required not to generate protocol elements that are 638 invalid. However, several situations of a peer may lead to 639 abnormal conditions in the interaction with the tracker. The 640 situations may be related with peer malfunction or communications 641 errors. The tracker reacts to the abnormal situations depending on 642 its current state related to a peer ID, as follows: 644 A) At PEER REGISTERED state, when a CONNECT request only contains 645 invalid swarm actions (section 6.1.1), the tracker responds with 646 PPSP-TP error code specified in Section 4.3, deletes the 647 registration, transition to TERMINATE state for that peer ID and 648 the SM is destroyed. 650 At the PEER REGISTERED state, if the peer ID is considered invalid 651 (in the case of a CONNECT request or in the case of FIND or 652 STAT_REPORT requests received from an unregistered peer ID), the 653 tracker responds with either error codes authentication required 654 or Forbidden (described in section 4.3), transitions to TERMINATE 655 state for that peer ID and the SM is destroyed. 657 B) At the TRACKING state (while the "track timer" has not expired) 658 receiving a CONNECT message from that peer ID with invalid swarm 659 actions (section 5.1), or receiving a FIND/STAT_REPORT message 660 from that peer ID with invalid swarm ID is considered an error 661 condition. The tracker responds with corresponding error code 662 (described in section 4.3). 664 C) In TRACKING state, without receiving messages from the peer, on 665 timeout (track timer) the tracker cleans all the information 666 associated with the peer ID in all swarms it was joined, deletes 667 the registration, transitions to TERMINATE state for that peer ID 668 and the SM is destroyed. 670 NOTE: These situations may correspond to malfunctions at the peer or 671 to malicious conditions. As preventive measure, the tracker proceeds 672 to TERMINATE state for that peer ID. 674 3 Protocol Specification 676 3.1 Presentation Language 678 PPSP-TP uses a REST-Like design, encoding the requests and responses 679 using JSON [RFC7159]. For a generalization of the definition of 680 protocol elements and fields, their types and structures, this 681 document uses a C-style notation, similar to the presentation 682 language used to define TLS [RFC5246]. 684 A JSON object consists of name/value pairs with the grammar specified 685 in [RFC7159]. In this document, comments begin with "//", and the 686 "ppsp_tp_string_t" and "ppsp_tp_integer_t" types are used to indicate 687 the JSON string and number, respectively. Optional fields are 688 enclosed in "[ ]" brackets. An array is indicated by two numbers in 689 angle brackets, , where "min" indicates the minimal number 690 of values and "max" the maximum. An "*" is used to denote a no upper 691 bound value for "max". 693 3.2 Resource Element Types 695 This section details the format of PPSP-TP resource element types. 697 3.2.1 Version 699 For both requests and responses, the version of PPSP-TP being used 700 MUST be indicated by the attribute version, defined as follows: 702 ppsp_tp_integer_t ppsp_tp_version_t = 1 704 The defined value for ppsp_tp_version_t is listed in Table 2 706 +----------------------------------------------------------+ 707 | ppsp_tp_version_t | Description | 708 +----------------------------------------------------------+ 709 | 0 | Reserved | 710 | 1 | Protocol specified in this document | 711 | 2-255 | Unassigned | 712 +----------------------------------------------------------+ 714 Table 2: PPSP Tracker Protocol Version Numbers 716 3.2.2 Peer Number Element 718 The peer number element is a scope selector optionally present in 719 CONNECT and FIND requests. 721 This element contains the attribute peer_count to indicate the 722 maximum number of peers in the returned peer list. Peer_count should 723 be less than 30 in this specification. The other 4 attributes, i.e., 724 ability_nat, concurrent_links, online_time and upload_bandwidth may 725 be also contained in this element to inform the tracker the status of 726 the peer so that the tracker could return some eligible peers based 727 on the implementing rules set by the service providers: 729 o ability_nat is used to indicate the preferred NAT traversal 730 situation of the requesting peer. 732 o concurrent_links means the number of P2P links the peer currently 733 has. 735 o online_time represents online duration time of the peer. The unit 736 is second. 738 o upload_bandwidth is the maximum upload bandwidth capability of the 739 peer. The unit is kbps. 741 The definition of the scope selector element and attributes is 742 defined as follows: 744 Object { 745 ppsp_tp_integer_t peer_count; 746 [ppsp_tp_string_t ability_nat = "NO_NAT" 747 | "STUN" 748 | "TURN";] 749 [ppsp_tp_integer_t concurrent_links;] 750 [ppsp_tp_integer_t online_time;] 751 [ppsp_tp_integer_t upload_bandwidth;] 752 } ppsp_tp_peer_num_t; 754 3.2.3 Swarm Action Element 756 The swarm action element identifies the action(s) to be taken in the 757 named swarm(s) as well as the corresponding peer mode (if the peer is 758 LEECH or SEEDER in that swarm). 760 Object { 761 ppsp_tp_string_t swarm_id; //swarm ID 762 ppsp_tp_string_t action = "JOIN" 763 |"LEAVE"; // Action type of 764 // the CONNECT 765 // message 767 ppsp_tp_string_t peer_mode = "SEEDER" 768 | "LEECH"; // Mode of the peer 769 // participating 770 // in this swarm 771 } ppsp_tp_swarm_action_t; 773 3.2.4 Peer Information Elements 775 The peer information elements provides network identification 776 information of peers. A peer information consists of peer identifier 777 and the IP related addressing information. 779 Object { 780 ppsp_tp_string_t peer_id; 781 ppsp_tp_peer_addr_t peer_addr; 782 }ppsp_tp_peer_info_t; 784 The ppsp_tp_peer_addr_t element includes the IP address and port, 785 with a few optional attributes related with connection type and 786 network location (in terms of ASN) as well as, optionally, the 787 identifier of the Peer Protocol being used. 789 Object { 790 ppsp_tp_ip_address ip_address; 791 ppsp_tp_integer_t port; 792 ppsp_tp_integer_t priority; 793 ppsp_tp_string_t type = "HOST" 794 | "REFLEXIVE" 795 | "PROXY"; 796 [ppsp_tp_string_t connection = "wireless" 797 | "wired";] 798 [ppsp_tp_string_t asn;] 799 [ppsp_tp_string_t peer_protocol;] 800 } ppsp_tp_peer_addr_t; 802 The semantics of ppsp_tp_peer_addr_t attributes are listed in 803 Table 3: 805 +----------------------+----------------------------------+ 806 | Element or Attribute | Description | 807 +----------------------+----------------------------------+ 808 | ip_address | IP Address information | 809 | port | IP service port value | 810 | priority | The priority of this interface.It| 811 | | may be determined by network | 813 | | topology preference, operator | 814 | | policy preference, etc. How to | 815 | | create a priority is outside of | 816 | | the scope. The larger the value, | 817 | | the higher the priority. | 818 | type | Describes the address for NAT | 819 | | traversal, which can be HOST | 820 | | REFLEXIVE or PROXY | 821 | connection | Access type (wireless or wired.) | 822 | asn | Autonomous System Number | 823 | peer_protocol | PPSP Peer Protocol supported | 824 +----------------------+----------------------------------+ 826 Table 3: Semantics of ppsp_tp_peer_addr_t. 828 In this document, IP address is specified as ppsp_tp_addr_value. The 829 exact characters and format depend on address_type: 831 o The IPv4 address is encoded as specified by the IPv4address rule in 832 Section 3.2.2 of [RFC3986]. 834 o The IPv6 address is encoded as specified in section 4 of [RFC5952]. 836 Object { 837 ppsp_tp_string_t address_type; 838 ppsp_tp_addr_value address; 839 } ppsp_tp_ip_address; 841 The peer Information in responses is grouped in a 842 ppsp_tp_peer_group_t element: 844 Object { 845 ppsp_tp_peer_info_t peer_info<1..*>; 846 } ppsp_tp_peer_group_t; 848 3.2.5 Statistics and Status Information Element 850 The statistics element (stat) is used to describe several properties 851 relevant to the P2P network. These properties can be related to 852 stream statistics and peer status information. Each stat element 853 will correspond to a property type and several stat blocks can be 854 reported in a single STAT_REPORT message, corresponding to some or 855 all the swarms the peer is actively involved. This specification 856 only defines the property type "STREAM_STATS". 858 The definition of the statistic element and attributes is as follows: 860 Object { 861 ppsp_tp_string_t swarm_id; 862 ppsp_tp_integer_t uploaded_bytes; 863 ppsp_tp_integer_t downloaded_bytes; 864 ppsp_tp_integer_t available_bandwidth; 865 ppsp_tp_integer_t concurrent_links; 866 } stream_stats; 868 The semantics of stream_stats attributes are listed in Table 4: 870 +----------------------+----------------------------------+ 871 | Element or Attribute | Description | 872 +----------------------+----------------------------------+ 873 | swarm_id | Swarm ID | 874 | uploaded_bytes | Bytes sent to swarm | 875 | downloaded_bytes | Bytes received from swarm | 876 | available_bandwidth | available instantaneous upload | 877 | | bandwidth | 878 | concurrent_links | The number of concurrent links | 879 +----------------------+----------------------------------+ 881 Table 4: Semantics of stream_stats. 883 The Stat Information is grouped in the ppsp_tp_stat_group_t element: 885 Object { 886 ppsp_tp_string_t type = "STREAM_STATS"; // property type 887 stream_stats stat<1..*>; 888 } ppsp_tp_stat_group_t 890 Other properties may be defined, related for example with incentives 891 and reputation mechanisms like "peer online time", or connectivity 892 conditions like physical "link status", etc. 894 For that purpose, the Stat element may be extended to provide 895 additional specific information for new properties, elements or 896 attributes (guidelines in section 7). 898 3.3 Requests and Responses 900 This section defines the structure of PPSP-TP requests and responses. 902 3.3.1 Request Types 903 The request type includes CONNECT, FIND and STAT_REPORT, defined as 904 follows: 906 ppsp_tp_string_t ppsp_tp_request_type_t = "CONNECT" 907 | "FIND" 908 | "STAT_REPORT"; 910 3.3.2 Response Types 912 Response type corresponds to the response method type of the message, 913 defined as follows: 915 JSONValue ppsp_tp_response_type_t = 0x00 // SUCCESSFUL 916 | 0x01; // FAILED 918 3.3.3 Request Element 920 The request element MUST be present in requests and corresponds to 921 the request method type for the message. 923 The generic definition of a request element is the following: 925 Object { 926 [ppsp_tp_peer_num_t peer_num;] 927 [ppsp_tp_peer_addr_t peer_addr<1..*>;] 928 ppsp_tp_swarm_action_t swarm_action<1..*>; 929 } ppsp_tp_request_connect; 931 Object { 932 ppsp_tp_string_t swarm_id; 933 [ppsp_tp_peer_num_t peer_num;] 934 } ppsp_tp_request_find; 936 Object { 937 ppsp_tp_version_t version; 938 ppsp_tp_request_type_t request_type; 939 ppsp_tp_string_t transaction_id; 940 ppsp_tp_string_t peer_id; 941 JSONValue request_data = ppsp_tp_req_connect connect 942 | ppsp_tp_req_find find 943 | ppsp_tp_stat_group_t stat_report; 944 } ppsp_tp_request; 946 A request element consists the version of PPSP-TP, the request type, 947 a transaction ID and the requesting peer ID, as well as the 948 requesting body, i.e., request_data. The request_data MUST be 949 correctly set to the corresponding element based on the request type 950 (see Table 5). 952 +----------------------+----------------------+ 953 | request_type | request_data | 954 +----------------------+----------------------+ 955 | "CONNECT" | "connect" | 956 | "FIND" | "find" | 957 | "STAT_REPORT" | "stat_report" | 958 +----------------------+----------------------+ 960 Table 5: The relationship between request_type and request_data. 962 3.3.4 Response Element 964 The generic definition of a response element is the following: 966 Object { 967 ppsp_tp_version_t version; 968 ppsp_tp_response_type_t response_type; 969 ppsp_tp_integer_t error_code; 970 ppsp_tp_string_t transaction_id; 971 [ppsp_tp_peer_addr_t peer_addr;] 972 [ppsp_tp_swarm_action_result_t swarm_result<1..*>;] 973 } ppsp_tp_response; 975 A response element consists the version of PPSP-TP, the response 976 type, the error code, a transaction ID, and optionally the public 977 address of the requesting peer and one or multiple swarm action 978 result elements. Normally, swarm action result elements SHOULD be 979 present and error_code MUST be set to 0 when response_type is 0x00. 980 Swarm action result elements SHOULD NOT be set when error_code is 981 0x01. Detailed selection of error_code is introduced in Section 4.3; 983 Object { 984 ppsp_tp_string_t swarm_id; 985 ppsp_tp_response_type_t result; 986 [ppsp_tp_peer_group_t peer_group;] 987 }ppsp_tp_swarm_action_result_t; 989 A swarm action result element represents the result of an action 990 requested by the peer. It contains a swarm identifier which globally 991 indicates the swarm, the result for the peer of this action which it 992 could be CONNECT ("JOIN" or "LEAVE"), FIND or STAT_REQPORT, and 993 optionally one peer group element. The attribute result indicates the 994 operation result of the corresponding request. When the response 995 element is corresponding to the STAT_REPORT request, or the result 996 attribute is set to 0x01, the peer group element SHOULD NOT be set. 998 3.4 PPSP-TP Message Element 1000 PPSP-TP messages (requests or responses) are designed to have a 1001 similar structure with a root field named "PPSPTrackerProtocol" 1002 containing meta information and data pertaining to a request or a 1003 response. 1005 The base type of PPSP-TP message is defined as follows: 1007 Object { 1008 JSONValue PPSPTrackerProtocol = ppsp_tp_request Request 1009 | ppsp_tp_response Response; 1010 } ppsp_tp_message_root; 1012 4 Protocol Specification: Encoding and Operation 1014 PPSP-TP is a message-oriented request/response protocol. PPSP-TP 1015 messages use a text type encoding in JSON [RFC7159], which MUST be 1016 indicated in the Content-Type field in HTTP/1.1 [RFC7231], specifying 1017 the application/ppsp-tracker+json media type for all PPSP-TP request 1018 parameters and responses. 1020 Implementations MUST support the "https" URI scheme [RFC2818] and 1021 Transport Layer Security (TLS) [RFC5246]. 1023 For deployment scenarios where peer (Client) authentication is 1024 desired at the tracker, HTTP Digest Authentication [RFC7616] MUST be 1025 supported, with TLS Client Authentication as the preferred mechanism, 1026 if available. 1028 PPSP-TP uses the HTTP POST method to send parameters in requests to 1029 provide information resources that are the function of one or more of 1030 those input parameters. Input parameters are encoded in JSON in the 1031 HTTP entity body of the request. 1033 The section describes the operation of the three types of requests of 1034 PPSP-TP and provides some examples of usage. 1036 4.1 Requests and Responses 1038 4.1.1 CONNECT Request 1040 This method is used when a peer registers to the system and/or 1041 requests some swarm actions (join/leave). The peer MUST properly set 1042 the request type to CONNECT, generate and set the transaction_ids, 1043 set the peer_id and MUST include swarms the peer is interested in, 1044 followed by the corresponding action type and peer mode. 1046 o When a peer already possesses a content and agrees to share it to 1047 others, it should set the action type to the value JOIN, as well as 1048 set the peer mode to SEEDER during its start (or re-start) period. 1050 o When a peer makes a request to join a swarm to consume content, it 1051 should set the action type to the value JOIN, as well as set the 1052 peer mode to LEECH during its start (or re-start) period. 1054 In the above cases, the peer can provide optional information on the 1055 addresses of its network interface(s), for example, the priority, 1056 type, connection and ASN. 1058 When a peer plans to leave a previously joined swarm, it should set 1059 action type to LEAVE, regardless of the peer mode. 1061 When receiving a well-formed CONNECT request message, the tracker 1062 start by pre-processing the peer authentication information (provided 1063 as Authorization scheme and token in the HTTP message) to check 1064 whether it is valid and that it can connect to the service, then 1065 proceed to register the peer in the service and perform the swarm 1066 actions requested. In case of success a response message with a 1067 corresponding response value of SUCCESSFUL will be generated. 1069 The valid sets of number of swarms whose action type is combined with 1070 peer mode for the CONNECT request logic are enumerated in Table 6 1071 (referring to the tracker "per-Peer-ID" state machine in 1072 Section 2.3). 1074 +-----------+-----------+---------+----------+-----------+----------+ 1075 | Swarm | peer_mode | action | Initial | Final | Request | 1076 | Number | value | value | State | State | validity | 1077 +-----------+-----------+---------+----------+-----------+----------| 1078 | 1 | LEECH | JOIN | START | TRACKING | Valid | 1079 +-----------+-----------+---------+----------+-----------+----------+ 1080 | 1 | LEECH | LEAVE | START | TERMINATE | Invalid | 1081 +-----------+-----------+---------+----------+-----------+----------+ 1082 | 1 | LEECH | LEAVE | TRACKING | TERMINATE | Valid | 1083 +-----------+-----------+---------+----------+-----------+----------+ 1084 | 1 | LEECH | JOIN | START | TERMINATE | Invalid | 1085 | 1 | LEECH | LEAVE | | | | 1086 +-----------+-----------+---------+----------+-----------+----------+ 1087 | 1 | LEECH | JOIN | TRACKING | TRACKING | Valid | 1088 | 1 | LEECH | LEAVE | | | | 1089 +-----------+-----------+---------+----------+-----------+----------+ 1090 | N | SEEDER | JOIN | START | TRACKING | Valid | 1091 +-----------+-----------+---------+----------+-----------+----------+ 1092 | N | SEEDER | JOIN | TRACKING | TERMINATE | Invalid | 1093 +-----------+-----------+---------+----------+-----------+----------+ 1094 | N | SEEDER | LEAVE | TRACKING | TERMINATE | Valid | 1095 +-----------+-----------+---------+----------+-----------+----------+ 1097 Table 6: Validity of action combinations in CONNECT request. 1099 In the CONNECT request message, multiple swarm action elements 1100 ppsp_tp_swarm_action_t could be contained. Each of them contains the 1101 request action and the peer_mode of the peer. The peer_mode 1102 attribute MUST be set to the type of participation of the peer in the 1103 swarm (SEEDER or LEECH). 1105 The CONNECT message may contain multiple peer_addr elements with 1106 attributes ip_address, port, priority and type (if ICE [RFC5245] NAT 1107 traversal techniques are used), and optionally connection, asn and 1108 peer_protocol corresponding to each of the network interfaces the 1109 peer wants to advertise. 1111 The element peer_num indicates the maximum number of peers to be 1112 returned in a list from the tracker. The returned peer list can be 1113 optionally filtered by some indicated properties, such as ability_nat 1114 for NAT traversal, and concurrent_links, online_time and 1115 upload_bandwidth for the preferred capabilities. 1117 The element transaction_id MUST be present in requests to uniquely 1118 identify the transaction. Responses to completed transactions use the 1119 same transaction_id as the request they correspond to. 1121 The response may include peer_addr data of the requesting peer public 1122 IP address. Peers can use Session Traversal Utilities for NAT (STUN) 1123 [RFC5389] and Traversal Using Relays around NAT (TURN) [RFC5766] to 1124 gather their candidates, in which case peer_addr SHOULD NOT present 1125 in the response. If no STUN is used and the tracker is able to work 1126 as a "STUN-like" server which can inspect the public address of a 1127 peer, the tracker can return the address back with a " REFLEXIVE " 1128 attribute type. The swarm_result may also include peer_addr data 1129 corresponding to the peer IDs and public IP addresses of the selected 1130 active peers in the requested swarm. The tracker may also include 1131 the attribute asn with network location information of the transport 1132 address, corresponding to the Autonomous System Number of the access 1133 network provider of the referenced peer. 1135 In case the peer_mode is SEEDER, the tracker responds with a 1136 SUCCESSFUL response and enters the peer information into the 1137 corresponding swarm activity. In case the peer_mode is LEECH (or if 1138 a SEEDER includes a peer_num element in the request), the tracker 1139 will search and select an appropriate list of peers satisfying the 1140 conditions set by the requesting peer. The peer list returned MUST 1141 contain the peer IDs and the corresponding IP Addresses. To create 1142 the peer list, the tracker may take peer status and network location 1143 information into consideration, to express network topology 1144 preferences or Operators' policy preferences, with regard to the 1145 possibility of connecting with other IETF efforts such as ALTO 1146 [RFC7285]. 1148 IMPLEMENTATION NOTE: If no peer_num attributes are present in the 1149 request the tracker may return a random sample from the peer 1150 population. 1152 4.1.1.1 Example 1154 The following example of a CONNECT request corresponds to a peer that 1155 wants to start (or re-start) sharing its previously streamed contents 1156 (peer_mode is SEEDER). 1158 POST https://tracker.example.com/video_1 HTTP/1.1 1159 Host: tracker.example.com 1160 Content-Length: 494 1161 Content-Type: application/ppsp-tracker+json 1162 Accept: application/ppsp-tracker+json 1164 { 1165 "PPSPTrackerProtocol": { 1166 "version": 1, 1167 "request_type": "CONNECT", 1168 "transaction_id": "12345", 1169 "peer_id": "656164657220", 1170 "connect":{ 1171 "peer_addr": { 1172 "ip_address": { 1173 "address_type": "ipv4", 1174 "address": "192.0.2.2" 1175 }, 1176 "port": 80, 1177 "priority": 1, 1178 "type": "HOST", 1179 "connection": "wired", 1180 "asn": "45645" 1181 }, 1182 "swarm_action": [{ 1183 "swarm_id": "1111", 1184 "action": "JOIN", 1185 "peer_mode": "SEEDER" 1186 }, 1187 { 1188 "swarm_id": "2222", 1189 "action": "JOIN", 1190 "peer_mode": "SEEDER" 1191 }] 1192 } 1193 } 1194 } 1196 Another example of the message-body of a CONNECT request corresponds 1197 to a peer (peer_mode is LEECH, meaning that the peer is not in 1198 possession of the content) requesting join to a swarm, in order to 1199 start receiving the stream, and providing optional information on the 1200 addresses of its network interface(s): 1202 { 1203 "PPSPTrackerProtocol": { 1204 "version": 1, 1205 "request_type": "CONNECT", 1206 "transaction_id": "12345.0", 1207 "peer_id": "656164657221", 1208 "connect":{ 1209 "peer_num": { 1210 "peer_count": 5, 1211 "ability_nat": "STUN", 1212 "concurrent_links": "5", 1213 "online_time": "200", 1214 "upload_bandwidth": "600" 1215 }, 1216 "peer_addr": [{ 1217 "ip_address": { 1218 "address_type": "ipv4", 1219 "address": "192.0.2.2" 1220 }, 1221 "port": 80, 1222 "priority": 1, 1223 "type": "HOST", 1224 "connection": "wired", 1225 "asn": "3256546" 1226 }, 1227 { 1228 "ip_address":{ 1229 "address_type": "ipv6", 1230 "address": "2001:db8::2" 1231 }, 1232 "port": 80, 1233 "priority": 2, 1234 "type": "HOST", 1235 "connection": "wireless", 1236 "asn": "34563456", 1237 "peer_protocol": "PPSP-PP" 1238 }], 1239 "swarm_action": { 1240 "swarm_id": "1111", 1241 "action": "JOIN", 1242 "peer_mode": "LEECH" 1243 } 1244 } 1245 } 1246 } 1248 The next example of a CONNECT request corresponds to a peer "leaving" 1249 a previously joined swarm and requesting join to a new swarm. This is 1250 the typical example of a user watching a live channel but then 1251 deciding to switch to a different one: 1253 { 1254 "PPSPTrackerProtocol": { 1255 "version": 1, 1256 "request_type": "CONNECT", 1257 "transaction_id": "12345", 1258 "peer_id": "656164657221", 1259 "connect":{ 1260 "peer_num": { 1261 "peer_count": 5, 1262 "ability_nat": "STUN", 1263 "concurrent_links": "5", 1264 "online_time": "200", 1265 "upload_bandwidth": "600" 1266 }, 1267 "swarm_action": [{ 1268 "swarm_id": "1111", 1269 "action": "LEAVE", 1270 "peer_mode": "LEECH" 1271 }, 1272 { 1273 "swarm_id": "2222", 1274 "action": "JOIN", 1275 "peer_mode": "LEECH" 1276 }] 1277 } 1278 } 1279 } 1281 The next example illustrates the response for the previous example of 1282 CONNECT request where the peer requested two swarm actions and not 1283 more than 5 other peers, receiving from the tracker a peer list with 1284 only 2 two other peers in the swarm "2222": 1286 HTTP/1.1 200 OK 1287 Content-Length: 1342 1288 Content-Type: application/ppsp-tracker+json 1290 { 1291 "PPSPTrackerProtocol": { 1292 "version": 1, 1293 "response_type": 0, 1294 "error_code": 0, 1295 "transaction_id": "12345", 1296 "peer_addr": { 1297 "ip_address": { 1298 "address_type": "ipv4", 1299 "address": "198.51.100.1" 1300 }, 1301 "port": 80, 1302 "priority": 1, 1303 "asn": "64496" 1304 }, 1305 "swarm_result": { 1306 "swarm_id": "2222", 1307 "result": 0, 1308 "peer_group": { 1309 "peer_info": [{ 1310 "peer_id": "956264622298", 1311 "peer_addr": { 1312 "ip_address": { 1313 "address_type": "ipv4", 1314 "address": "198.51.100.22" 1315 }, 1316 "port": 80, 1317 "priority": 2, 1318 "type": "REFLEXIVE", 1319 "connection": "wired", 1320 "asn": "64496", 1321 "peer_protocol": "PPSP-PP" 1322 } 1323 }, 1324 { 1325 "peer_id": "3332001256741", 1326 "peer_addr": { 1327 "ip_address": { 1328 "address_type": "ipv4", 1329 "address": "198.51.100.201" 1330 }, 1331 "port": 80, 1332 "priority": 2, 1333 "type": "REFLEXIVE", 1335 "connection": "wired", 1336 "asn": "64496", 1337 "peer_protocol": "PPSP-PP" 1338 } 1339 }] 1340 } 1341 } 1342 } 1343 } 1345 4.1.2 FIND Request 1347 This method allows peers to request to the tracker, whenever needed, 1348 a new peer list for the swarm. 1350 The FIND request may include a peer_number element to indicate to the 1351 tracker the maximum number of peers to be returned in a list 1352 corresponding to the indicated conditions set by the requesting peer, 1353 being ability_nat for NAT traversal (considering that PPSP-ICE NAT 1354 traversal techniques may be used), and optionally concurrent_links, 1355 online_time and upload_bandwidth for the preferred capabilities. 1357 When receiving a well-formed FIND request the tracker processes the 1358 information to check if it is valid. In case of success a response 1359 message with a response value of SUCCESSFUL will be generated and the 1360 tracker will search out the list of peers for the swarm and select an 1361 appropriate peer list satisfying the conditions set by the requesting 1362 peer. The peer list returned MUST contain the peer IDs and the 1363 corresponding IP Addresses. 1365 The tracker may take the ability of peers and popularity of the 1366 requested content into consideration. For example, the tracker could 1367 select peers with higher ability than the current peers that provide 1368 the content if the content is relatively popular (see Section 5.1.1); 1369 and the tracker could also select peers with lower ability than the 1370 current peers that provide the content when the content is relatively 1371 uncommon. The tracker may take network location information into 1372 consideration as well, to express network topology preferences or 1373 operators' policy preferences. It can implement other IETF efforts 1374 like ALTO[RFC7285], which is out of the scope of this document. 1376 The response MUST include peer_group element which contains the peer 1377 IDs and the corresponding IP Addresses, may also include the 1378 attribute asn with network location information of the transport 1379 address, corresponding to the Autonomous System Number of the access 1380 network provider of the referenced peer. 1382 The response may also include peer_addr element that includes the 1383 requesting peer public IP address. If no STUN is used and the tracker 1384 is able to work as a "STUN-like" server which can inspect the public 1385 address of a peer, the tracker can return the address back with a " 1386 REFLEXIVE " attribute type. 1388 IMPLEMENTATION NOTE: If no peer_num attributes are present in the 1389 request the tracker may return a random sample from the peer 1390 population. 1392 4.1.2.1 Example 1394 An example of the message-body of a FIND request, where the peer 1395 requests to the tracker an list of not more than 5 peers in the swarm 1396 "1111" conforming to the characteristics expressed (concurrent links, 1397 online time, and upload bandwidth level) is the following: 1399 { 1400 "PPSPTrackerProtocol": { 1401 "version": 1, 1402 "request_type": "FIND", 1403 "transaction_id": "12345", 1404 "peer_id": "656164657221", 1405 "swarm_id": "1111", 1406 "peer_num": { 1407 "peer_count": 5, 1408 "ability_nat": "STUN", 1409 "concurrent_links": "5", 1410 "online_time": "200", 1411 "upload_bandwidth": "600" 1412 } 1413 } 1414 } 1416 An example of the message-body of a response for the above FIND 1417 request, including the requesting peer public IP address information, 1418 is the following: 1420 { 1421 "PPSPTrackerProtocol": { 1422 "version": 1, 1423 "response_type": 0, 1424 "error_code": 0, 1425 "transaction_id": "12345", 1426 "swarm_result": { 1427 "swarm_id": "1111", 1428 "result": 0, 1429 "peer_group": { 1430 "peer_info": [{ 1432 "peer_id": "656164657221", 1433 "peer_addr": { 1434 "ip_address": { 1435 "address_type": "ipv4", 1436 "address": "198.51.100.1" 1437 }, 1438 "port": 80, 1439 "priority": 1, 1440 "type": "REFLEXIVE", 1441 "connection": "wireless", 1442 "asn": "64496" 1443 } 1444 }, 1445 { 1446 "peer_id": "956264622298", 1447 "peer_addr": { 1448 "ip_address": { 1449 "address_type": "ipv4", 1450 "address": "198.51.100.22" 1451 }, 1452 "port": 80, 1453 "priority": 1, 1454 "type": "REFLEXIVE", 1455 "connection": "wireless", 1456 "asn": "64496" 1457 } 1458 }, 1459 { 1460 "peer_id": "3332001256741", 1461 "peer_addr": { 1462 "ip_address": { 1463 "address_type": "ipv4", 1464 "address": "198.51.100.201" 1465 }, 1466 "port": 80, 1467 "priority": 1, 1468 "type": "REFLEXIVE", 1470 "connection": "wireless", 1471 "asn": "64496" 1472 } 1473 }] 1474 } 1475 } 1476 } 1477 } 1479 4.1.3 STAT_REPORT Request 1481 This method allows peers to send status and statistic data to 1482 trackers. The method is initiated by the peer, periodically while 1483 active. 1485 The peer MUST set the request_type to "STAT_REPORT", set the peer_id 1486 with the identifier of the peer, and generate and set the 1487 transaction_id. 1489 The report may include multiple statistics elements describing 1490 several properties relevant to a specific swarm. These properties 1491 can be related with stream statistics and peer status information, 1492 including uploaded_bytes, downloaded_bytes, available_bandwidth, 1493 concurrent_links and etc. 1495 Other properties may be defined (guidelines in Section 7.1) related 1496 for example, with incentives and reputation mechanisms. In case no 1497 Statistics Group is included, the STAT_REPORT is used as a "keep- 1498 alive" message to prevent the tracker from de-registering the peer 1499 when "track timer" expires. 1501 If the request is valid the tracker processes the received 1502 information for future use, and generates a response message with a 1503 response value of SUCCESSFUL. 1505 The response MUST have the same transaction_id value as the request. 1507 4.1.3.1 Example 1509 An example of the message-body of a STAT_REPORT request is: 1511 { 1512 "PPSPTrackerProtocol": { 1513 "version": 1, 1514 "request_type": "STAT_REPORT", 1515 "transaction_id": "12345", 1516 "peer_id": "656164657221", 1517 "stat_report": { 1518 "type": "STREAM_STATS", 1519 "Stat": { 1520 "swarm_id": "1111", 1521 "uploaded_bytes": 512, 1522 "downloaded_bytes": 768, 1523 "available_bandwidth": 1024000, 1524 "concurrent_links": 5 1525 } 1526 } 1527 } 1528 } 1530 An example of the message-body of a response for the START_REPORT 1531 request is: 1533 { 1534 "PPSPTrackerProtocol": { 1535 "version": 1, 1536 "response_type": 0, 1537 "error_code": 0, 1538 "transaction_id": "12345", 1539 "swarm_result": { 1540 "swarm_id": "1111", 1541 "result": 0 1542 } 1544 } 1545 } 1547 4.2 Response Element in Response Messages 1549 Table 7 indicates the response type and corresponding semantics. 1551 +--------------------+---------------------+ 1552 | Response Type | Semantics | 1553 | | | 1554 +--------------------+---------------------+ 1555 | 0 | SUCCESSFUL | 1556 | 1 | FAILED | 1557 +--------------------+---------------------+ 1559 Table 7: Semantics for the Value of Response Type. 1561 SUCCESSFUL: indicates that the request has been processed properly 1562 and the desired operation has completed. The body of the response 1563 message includes the requested information and MUST include the same 1564 transaction_id of the corresponding request. 1566 CONNECT: returns information about the successful registration of 1567 the peer and/or of each swarm action requested. may additionally 1568 return the list of peers corresponding to the action attribute 1569 requested. 1571 FIND: returns the list of peers corresponding to the requested 1572 scope. 1574 STAT_REPORT: confirms the success of the requested operation. 1576 FAILED: indicates that the request has not been processed properly. 1577 And corresponding error_code SHOULD be set according to the 1578 conditions described in Section 4.3. 1580 4.3 Error and Recovery conditions 1582 If the peer receives an invalid response, the same request with 1583 identical content including the same transaction_id MUST be repeated. 1585 The transaction_id on a request can be reused if and only if all of 1586 the content is identical, including Date/Time information. Details 1587 of the retry process (including time intervals to pause, number of 1588 retries to attempt, and timeouts for retrying) are implementation 1589 dependent. 1591 The tracker MUST be prepared to receive a request with a repeated 1592 transaction_id. 1594 Error situations resulting from the Normal Operation or from abnormal 1595 conditions (Section 2.3.2) MUST be responded with response_type set 1596 to 0x01 and with the adequate error_code, as described here: 1598 o If the message is found to be incorrectly formed, the receiver MUST 1599 respond with a 01 (bad request) error_code with an empty message- 1600 body (no peer_addr and swarm_result attributes). 1602 o If the version number of the protocol is for a version the receiver 1603 does not supports, the receiver MUST respond with a 02 (Unsupported 1604 Version Number) error_code with an empty message-body (no peer_addr 1605 and swarm_result attributes). 1607 o In the PEER REGISTERED and TRACKING states of the tracker, certain 1608 requests are not allowed (Section 2.3.2). The tracker MUST respond 1609 with a 03 (Forbidden) error_code with an empty message-body (no 1610 peer_addr and swarm_result attributes). 1612 o If the tracker is unable to process a request message due to 1613 unexpected condition, it SHOULD respond with a 04 (Internal Server 1614 Error) error_code with an empty message-body (no peer_addr and 1615 swarm_result attributes). 1617 o If the tracker is unable to process a request message for being in 1618 an overloaded state, it SHOULD respond with a 05 (Service 1619 Unavailable) error_code with an empty message-body (no peer_addr 1620 and swarm_result attributes). 1622 o If authentication is required for the peer to make the request, the 1623 tracker SHOULD respond with a 06 (Authentication Required) 1624 error_code with an empty message-body (no peer_addr and 1625 swarm_result attributes). 1627 4.4 Parsing of Unknown Fields in Message-body 1629 This document only details object members used by this specification. 1630 Extensions may include additional members within JSON objects defined 1631 in this document. PPSP-TP implementations MUST ignore unknown 1632 members when processing PPSP-TP messages. 1634 5 Operations and Manageability 1636 This section provides the operational and managements aspects that 1637 are required to be considered in implementations of PPSP-TP. These 1638 aspects follow the recommendations expressed in [RFC5706]. 1640 5.1 Operational Considerations 1642 The PPSP-TP provides communication between trackers and peers and is 1643 conceived as a "client-server" mechanism, allowing the exchange of 1644 information about the participant peers sharing multimedia streaming 1645 contents. 1647 The "serving" component, i.e., the tracker, is a logical entity that 1648 can be envisioned as a centralized service (implemented in one or 1649 more physical nodes), or a fully distributed service. 1651 The "client" component can be implemented at each peer participating 1652 in the streaming of contents. 1654 5.1.1 Installation and Initial Setup 1656 Content providers wishing to use PPSP for content distribution should 1657 setup at least a PPSP tracker and a service portal (public web 1658 server) to publish links of the content descriptions, for access to 1659 their on-demand or live original contents sources. Content/Service 1660 providers should also create conditions to generate peer IDs and any 1661 required security certificates, as well as chunk IDs and swarm IDs 1662 for each streaming content. The configuration processes for the PPSP 1663 Tracking facility, the service portal and content sources are not 1664 standardized, enabling all the flexibility for implementers. 1666 The swarm IDs of available contents, as well as the addresses of the 1667 PPSP Tracking facility, can be distributed to end-users in various 1668 ways, but it is common practice to include both the swarm ID and the 1669 corresponding PPSP tracker addresses (as URLs) in the MPD of the 1670 content, which is obtainable (a link) from the service portal. 1672 The available contents could have different importance attribute 1673 values to indicate whether the content is popular or not. However, 1674 it is a totally implementation design and outside of this 1675 specification. For example, the importance attribute values of the 1676 contents could be set by content providers when distributing them or 1677 could be determined by the tracker based on the statistics of the 1678 requests from the peers that request the content. The tracker could 1679 set a upper threshold to decide that the content is popular enough 1680 when the importance attribute value is higher than the upper 1681 threshold. And the tracker could also set a lower threshold to 1682 decide that the content is uncommon enough when the importance 1683 attribute value is lower than the lower threshold. 1685 End-users browse and search for the desired contents in the service 1686 portal, selecting by clicking the links of the corresponding MPDs. 1687 This action typically requires security certificates or authorization 1688 tokens from an enrollment service (end user registration), and then 1689 launches the Client Media Player (with PPSP awareness) which will 1690 then, using PPSP-TP, contact the PPSP tracker to join the 1691 corresponding swarm and obtain the transport addresses of other PPSP 1692 peers in order to start streaming the content. 1694 5.1.2 Migration Path 1696 There is no previous standard protocol providing similar 1697 functionality as PPSP-TP. However, some popular proprietary 1698 protocols, e.g., BitTorrent, are used in existing systems. There is 1699 no way for PPSP-TP to migrate to proprietary protocols like 1700 BitTorrent tracker protocol. And because PPSP-TP is an application 1701 level protocol, there is no harm for PPSP-TP having no migration 1702 path. However, proprietary protocols migrating to standard protocols 1703 like PPSP-TP can solve the problems raised in [RFC6972]. It is also 1704 possible for systems to use PPSP-TP as the management protocol to 1705 work with exiting propriety peer protocols like BitTorrent peer 1706 protocol. 1708 5.1.3 Requirements on Other Protocols and Functional Components 1710 For security reasons, when using PPSP Peer protocol with PPSP-TP, the 1711 mechanisms described in Section 6.1 should be observed. 1713 5.1.4 Impact on Network Operation 1715 As the messaging model of PPSP-TP aligns with HTTP protocol and the 1716 semantics of its messages, the impact on Network Operation is similar 1717 to using HTTP. 1719 5.1.5 Verifying Correct Operation 1721 The correct operation of PPSP-TP can be verified both at the tracker 1722 and at the peer by logging the behavior of PPSP-TP. Additionally, 1723 the PPSP tracker collects the status of the peers including peer's 1724 activity, and such information can be used to monitor and obtain the 1725 global view of the operation. 1727 5.2 Management Considerations 1729 The management considerations for PPSP-TP are similar to other 1730 solutions using HTTP for large-scale content distribution. The PPSP 1731 tracker can be realized by geographically distributed tracker nodes 1732 or multiple server nodes in a data center. As these nodes are akin 1733 to WWW nodes, their configuration procedures, detection of faults, 1734 measurement of performance, usage accounting and security measures 1735 can be achieved by standard solutions and facilities. 1737 5.2.1 Interoperability 1739 Interoperability refers to allowing information sharing and 1740 operations between multiple devices and multiple management 1741 applications. For PPSP-TP, distinct types of devices host PPSP-TP 1742 trackers and peers. Therefore, support for multiple standard schema 1743 languages, management protocols and information models, suited to 1744 different purposes, was considered in the PPSP-TP design. 1745 Specifically, management functionality for PPSP-TP devices can be 1746 achieved with Simple Network Management Protocol (SNMP) [RFC3410], 1747 syslog [RFC5424] and NETCONF [RFC6241]. 1749 5.2.2 Management Information 1751 PPSP trackers may implement SNMP management interfaces, namely the 1752 Application Management MIB [RFC2564] without the need to instrument 1753 the tracker application itself. The channel, connections and 1754 transaction objects of the Application Management MIB can be used to 1755 report the basic behavior of the PPSP tracker service. 1757 The Application Performance Measurement MIB (APM-MIB) [RFC3729] and 1758 the Transport Performance Metrics MIB (TPM-MIB) [RFC4150] can be used 1759 with PPSP-TP, providing adequate metrics for the analysis of 1760 performance for transaction flows in the network, in direct 1761 relationship to the transport of PPSP-TP. 1763 The Host Resources MIB [RFC2790] can be used to supply information on 1764 the hardware, the operating system, and the installed and running 1765 software on a PPSP tracker host. 1767 The TCP-MIB [RFC4022] can additionally be considered for network 1768 monitoring. 1770 Logging is an important functionality for PPSP-TP tracker and peer, 1771 done via syslog [RFC5424]. 1773 5.2.3 Fault Management 1775 As PPSP tracker failures can be mainly attributed to host or network 1776 conditions, the facilities previously described for verifying the 1777 correct operation of PPSP-TP and the management of PPSP tracker 1778 servers, appear sufficient for PPSP-TP fault monitoring. 1780 5.2.4 Configuration Management 1782 PPSP tracker deployments, when realized by geographically distributed 1783 tracker nodes or multiple server nodes in a data center, may benefit 1784 from a standard way of replicating atomic configuration updates over 1785 a set of server nodes. This functionality can be provided via 1786 NETCONF [RFC6241]. 1788 5.2.5 Accounting Management 1790 PPSP-TP implementations, namely for content provider environments, 1791 can benefit from accounting standardization efforts as defined in 1792 [RFC2975], in terms of resource consumption data, for the purposes of 1793 capacity and trend analysis, cost allocation, auditing, and billing. 1795 5.2.6 Performance Management 1797 Being transaction-oriented, PPSP-TP performance, in terms of 1798 availability and responsiveness, can be measured with the facilities 1799 of the APM-MIB [RFC3729] and the TPM-MIB [RFC4150]. 1801 5.2.7 Security Management 1803 Standard SNMP notifications for PPSP tracker management [RFC5590] and 1804 syslog messages [RFC5424] can be used, to alert operators to the 1805 conditions identified in the security considerations (Section 6). 1807 The statistics collected about the operation of PPSP-TP can be used 1808 for detecting attacks, such as the receipt of malformed messages, 1809 messages out of order, or messages with invalid timestamps. However, 1810 collecting such endpoint properties may also raise some security 1811 issues. For example, the statistics collected by the tracker may be 1812 disclosed to an unauthorized third party which has some malicious 1813 intention. To address such risk, the provider of the tracker should 1814 evaluate how much information is revealed and the associated risks. 1815 And confidentiality mechanism must be provided by HTTP over TLS to 1816 guarantee the confidentiality of PPSP-TP. 1818 6 Security Considerations 1820 P2P streaming systems are subject to attacks by malicious or 1821 unfriendly peers/trackers that may eavesdrop on signaling, forge/deny 1822 information/knowledge about streaming content and/or its 1823 availability, impersonating a valid participant, or launch DoS 1824 attacks to a chosen victim. 1826 No security system can guarantee complete security in an open P2P 1827 streaming system where participants may be malicious or 1828 uncooperative. The goal of security considerations described here is 1829 to provide sufficient protection for maintaining some security 1830 properties during the tracker-peer communication even in the face of 1831 a large number of malicious peers and/or eventual distrustful 1832 trackers (under the distributed tracker deployment scenario). 1834 Since the protocol uses HTTP to transfer signaling, most of the 1835 security considerations described in [RFC7230] and [RFC7231] also 1836 apply. Due to the transactional nature of the communication between 1837 peers and tracker, the method for adding authentication and data 1838 security services can be the OAuth 2.0 Authorization [RFC6749] with 1839 bearer token, which provides the peer with the information required 1840 to successfully utilize an access token to make protected requests to 1841 the tracker. 1843 6.1 Authentication between Tracker and Peers 1845 To protect the PPSP-TP signaling from attackers pretending to be 1846 valid peers (or peers other than themselves) all messages received in 1847 the tracker SHOULD be received from authorized peers. For that 1848 purpose a peer SHOULD enroll in the system via a centralized 1849 enrollment server. The enrollment server is expected to provide a 1850 proper peer ID for the peer and information about the authentication 1851 mechanisms. The specification of the enrollment method and the 1852 provision of identifiers and authentication tokens is out of scope of 1853 this specification. 1855 Transport Layer Security (TLS) [RFC5246] MUST be used in the 1856 communication between peers and tracker to provide privacy and data 1857 integrity. Software engineers developing and service providers 1858 deploying the tracker should make themselves familiar with the Best 1859 Current Practices (BCP) on configuring HTTP over TLS [RFC7525]. 1861 OAuth 2.0 Authorization [RFC6749] SHOULD be also considered when 1862 digest authentication [RFC7616] and HTTPS client certificates are 1863 required. 1865 6.2 Content Integrity Protection Against Polluting Peers/Trackers 1867 Malicious peers may claim ownership of popular content to the tracker 1868 and try to serve polluted (i.e., decoy content or even virus/trojan 1869 infected contents) to other peers. Since trackers don't exchange 1870 content information among peers, they are difficult to detect if a 1871 peer is polluting the content or not. Usually, this kind of pollution 1872 can be detected by PPSPP [RFC7574] with requiring the use of Merkle 1873 Hash Tree scheme for protecting the integrity of the content. More 1874 details can be seen in Section 5 of [RFC7574]. 1876 Some attackers that disrupt P2P streaming on behalf of content 1877 providers may provide false or modified content or peer list 1878 information to achieve certain malicious goals. Peers connecting to 1879 those portals or trackers provided by the attackers may be redirected 1880 to some corrupted malicious content. However, there is no standard 1881 ways for peers to avoid this kind of situations completely. Peers can 1882 have mechanisms to detect undesirable content or results themselves. 1883 For example, if a peer finds the portal returns some undesired 1884 content information or the tracker returns some malicious peer lists, 1885 the peer may choose quitting the swarm, or switching to other P2P 1886 streaming services provided by other content providers. 1888 6.3 Residual attacks and mitigation 1890 To mitigate the impact of Sybil attackers, impersonating a large 1891 number of valid participants by repeatedly acquiring different peer 1892 identities, the enrollment server SHOULD carefully regulate the rate 1893 of peer/tracker admission. 1895 There is no guarantee that peers honestly report their status to the 1896 tracker, or serve authentic content to other peers as they claim to 1897 the tracker. It is expected that a global trust mechanism, where the 1898 credit of each peer is accumulated from evaluations for previous 1899 transactions, may be taken into account by other peers when selecting 1900 partners for future transactions, helping to mitigate the impact of 1901 such malicious behaviors. A globally trusted tracker may also take 1902 part of the trust mechanism by collecting evaluations, computing 1903 credit values and providing them to joining peers. 1905 6.4 Pro-incentive parameter trustfulness 1907 Property types for STAT_REPORT messages may consider additional pro- 1908 incentive parameters (guidelines for extension in Section 7), which 1909 can enable the tracker to improve the performance of the whole P2P 1910 streaming system. Trustworthiness of these pro-incentive parameters 1911 is critical to the effectiveness of the incentive mechanisms. 1912 Furthermore, both the amount of uploaded and downloaded data should 1913 be reported to the tracker to allow checking if there is any 1914 inconsistency between the upload and download report, and establish 1915 an appropriate credit/trust system. 1917 One such solution could be a reputation-incentive mechanism, based on 1918 the notions of reputation, social awareness and fairness. The 1919 mechanism would promote cooperation among participants (via each 1920 peer's reputation) based on the history of past transactions, such 1921 as, count of chunk requests (sent, received) in a swarm, contribution 1922 time of the peer, cumulative uploaded and downloaded content, JOIN 1923 and LEAVE timestamps, attainable rate, etc. 1925 Alternatively, exchange of cryptographic receipts signed by receiving 1926 peers can be used to attest to the upload contribution of a peer to 1927 the swarm, as suggested in [Contracts]. 1929 6.5 Privacy for Peers 1930 The PPSP-TP provides mechanisms in which the peers can send message 1931 containing IP addresses, ports and other information to the tracker. 1932 A tracker or a third party who is able to intercept such messages can 1933 store and process the obtained information in order to analyze peers' 1934 behaviors and communication patterns. Such analysis can lead to 1935 privacy risks. For example, an unauthorized party may snoop on the 1936 data transmission from the peer to a tracker in order to introduce 1937 some corrupted chunks. 1939 The PPSP peer protocol [RFC7574] has already introduced some 1940 mechanisms to protect the streamed content, see section 12.3 and 12.4 1941 of [RFC7574]. For PPSP-TP, peer implementations as well as tracker 1942 implementations MUST support the "https" URI scheme [RFC2818] and 1943 Transport Layer Security (TLS) [RFC5246]. In addition, a peer should 1944 be cognizant about potential tracker tracking through queries of 1945 peers, e.g., by using HTTP cookies. The PPSP-TP protocol specified in 1946 this document does not rely on HTTP cookies. Thus, peers may decide 1947 not to return cookies received from the tracker, in order to making 1948 some additional tracking more difficult. 1950 7 Guidelines for Extending PPSP-TP 1952 Extension mechanisms allow designers to add new features or to 1953 customize existing features of a protocol for different operating 1954 environments [RFC6709]. 1956 Extending a protocol implies either the addition of features without 1957 changing the protocol itself or the addition of new elements creating 1958 new versions of an existing schema and therefore new versions of the 1959 protocol. 1961 In PPSP-TP it means that an extension MUST NOT alter an existing 1962 protocol schema as the changes would result in a new version of an 1963 existing schema, not an extension of an existing schema, typically 1964 non-backwards-compatible. 1966 Additionally, a designer MUST remember that extensions themselves may 1967 also be extensible. 1969 Extensions MUST adhere to the principles described in this section in 1970 order to be considered valid. 1972 Extensions MUST be documented in standards-track RFCs if there are 1973 requirements for coordination, interoperability, and broad 1974 distribution. 1976 7.1 Forms of PPSP-TP Extension 1977 In PPSP-TP two extension mechanisms can be used: a Request-Response 1978 Extension or a Protocol-level Extension. 1980 o Request-Response Extension: Adding elements or attributes to an 1981 existing element mapping in the schema is the simplest form of 1982 extension. This form should be explored before any other. This 1983 task can be accomplished by extending an existing element mapping. 1985 For example, an element mapping for the Statistics Group can be 1986 extended to include additional elements needed to express status 1987 information about the activity of the peer, such as online time 1988 for the Stat element. 1990 o Protocol-level Extension: If there is no existing element mapping 1991 that can be extended to meet the requirements and the existing 1992 PPSP-TP request and response message structures are insufficient, 1993 then extending the protocol should be considered in order to 1994 define new operational requests and responses. 1996 For example, to enhance the level of control and the granularity 1997 of the operations, a new version of the protocol with new messages 1998 (JOIN, DISCONNECT), a retro-compatible change in semantics of an 1999 existing CONNECT request/response and an extension in STAT_REPORT 2000 could be considered. 2002 As illustrated in Figure 6, the peer would use an enhanced CONNECT 2003 request to perform the initial registration in the system. Then 2004 it would join a first swarm as SEEDER, later join a second swarm 2005 as LEECH, and then disconnect from the latter swarm but keeping as 2006 SEEDER for the first one. When deciding to leave the system, the 2007 peer disconnects gracefully from it: 2009 +--------+ +---------+ 2010 | Peer | | Tracker | 2011 +--------+ +---------+ 2012 | | 2013 |--CONNECT--------------------->| 2014 |<--------------------------OK--| 2015 |--JOIN(swarm_a;SEEDER)---------->| 2016 |<--------------------------OK--| 2017 : : 2018 |--STAT_REPORT(activity)------->| 2019 |<--------------------------Ok--| 2020 : : 2021 |--JOIN(swarm_b;LEECH)--------->| 2022 |<-----------------OK+PeerList--| 2023 : : 2024 |--STAT_REPORT(ChunkMap_b)----->| 2025 |<--------------------------Ok--| 2026 : : 2027 |--DISCONNECT(swarm_b)--------->| 2028 |<--------------------------Ok--| 2029 : : 2030 |--STAT_REPORT(activity)------->| 2031 |<--------------------------Ok--| 2032 : : 2033 |--DISCONNECT------------------>| 2034 |<---------------------Ok(BYE)--| 2036 Figure 6: Example of a session for a PPSP-TP extended version. 2038 7.2 Issues to Be Addressed in PPSP-TP Extensions 2040 There are several issues that all extensions should take into 2041 consideration. 2043 - Overview of the Extension: It is RECOMMENDED that extensions to 2044 PPSP-TP have a protocol overview section that discusses the basic 2045 operation of the extension. The most important processing rules 2046 for the elements in the message flows SHOULD also be mentioned. 2048 - Backward Compatibility: The new extension MUST be backward 2049 compatible with the base PPSP-TP specified in this document. 2051 - Syntactic Issues: Extensions that define new request/response 2052 methods SHOULD use all capitals for the method name, keeping with 2053 a long-standing convention in many protocols, such as HTTP. Method 2054 names are case sensitive in PPSP-TP. Method names SHOULD be 2055 shorter than 16 characters and SHOULD attempt to convey the 2056 general meaning of the request or response. 2058 - Semantic Issues: PPSP-TP extensions MUST clearly define the 2059 semantics of the extensions. Specifically, the extension MUST 2060 specify the behaviors expected from both the peer and the tracker 2061 in processing the extension, with the processing rules in temporal 2062 order of the common messaging scenario. 2064 Processing rules generally specify actions to be taken on receipt 2065 of messages and expiration of timers. 2067 The extension SHOULD specify procedures to be taken in exceptional 2068 conditions that are recoverable. Handling of unrecoverable errors 2069 does not require specification. 2071 - Security Issues: As security is an important component of any 2072 protocol, designers of PPSP-TP extensions need to carefully 2073 consider security requirements, e.g., authorization requirements 2074 and requirements for end-to-end integrity. 2076 - Examples of Usage: The specification of the extension SHOULD give 2077 examples of message flows and message formatting and include 2078 examples of messages containing new syntax. Examples of message 2079 flows should be given to cover common cases and at least one 2080 failure or unusual case. 2082 8 IANA Considerations 2084 8.1 MIME Type Registry 2086 This document registers application/ppsp-tracker+json media types. 2088 Type name: application 2090 Subtype name: ppsp-tracker+json 2092 Required parameters: n/a 2094 Optional parameters: n/a 2096 Encoding considerations: Encoding considerations are identical to 2097 those specified for the "application/json" media type. See 2098 [RFC7159]. 2100 Security considerations: See Section 6. 2102 Interoperability considerations: This document specifies format of 2103 conforming messages and the interpretation thereof. 2105 Published specification: This document. 2107 Applications that use this media type: PPSP trackers and peers 2108 either stand alone or embedded within other applications. 2110 Additional information: 2112 Magic number(s): n/a 2114 File extension(s): n/a. 2116 Macintosh file type code(s): n/a 2118 Fragment identifier considerations: n/a 2120 Person & email address to contact for further information: See 2121 Authors' Addresses section. 2123 Intended usage: COMMON 2125 Restrictions on usage: none 2127 Author: See Authors' Addresses section. 2129 Change controller: IESG (iesg@ietf.org) 2131 8.2 PPSP Tracker Protocol Version Number Registry 2133 Registry name is "PPSP Tracker Protocol Version Number Registry". 2134 Values are integers in the range 0-255, with initial assignments and 2135 reservations given in Table 2. New PPSP-TP version types are assigned 2136 after IETF Review [RFC5226] to ensure that proper documentation 2137 regarding the new version types and their usage has been provided. 2139 8.3 PPSP Tracker Protocol Request Type Registry 2141 Registry name is "PPSP Tracker Protocol Request Type Registry". 2142 Values are strings listed in Table 8. New PPSP-TP request types are 2143 assigned after IETF Review [RFC5226] to ensure that proper 2144 documentation regarding the new request types and their usage has 2145 been provided. 2147 +----------------------+-------------------------------------------+ 2148 | request_type | Description | 2149 +----------------------+-------------------------------------------+ 2150 | "CONNECT" | CONNECT message specified in this document| 2151 | "FIND" | FIND message specified in this document | 2152 | "STAT_REPORT" | STAT_REPORT message specified in this | 2153 | | document | 2154 +----------------------+-------------------------------------------+ 2155 Table 8: The PPSP Tracker Protocol Request Type Registry. 2157 8.4 PPSP Tracker Protocol Error Code Registry 2159 Registry name is "PPSP Tracker Protocol Error Code Registry". Values 2160 are strings listed in Table 9. New PPSP-TP error codes are assigned 2161 after IETF Review [RFC5226] to ensure that proper documentation 2162 regarding the new error codes and their usage has been provided. 2164 +---------------+-------------------------------------------+ 2165 | error_code | Description | 2166 +---------------+-------------------------------------------+ 2167 | 00 | no error | 2168 | 01 | bad request | 2169 | 02 | unsupported version number | 2170 | 03 | forbidden action | 2171 | 04 | internal server error | 2172 | 05 | service unavailable | 2173 | 06 | authentication required | 2174 +---------------+-------------------------------------------+ 2175 Table 9: The PPSP Tracker Protocol Error Code Registry. 2177 9 Acknowledgments 2179 The authors would like to thank many people for for their help and 2180 comments, particularly: Zhang Yunfei, Liao Hongluan, Roni Even, Dave 2181 Cottlehuber, Bhumip Khasnabish, Wu Yichuan, Peng Jin, Chi Jing, Zong 2182 Ning, Song Haibin, Chen Wei, Zhijia Chen, Christian Schmidt, Lars 2183 Eggert, David Harrington, Henning Schulzrinne, Kangheng Wu, Martin 2184 Stiemerling, Jianyin Zhang, Johan Pouwelse, Riccardo Petrocco and 2185 Arno Bakker. 2187 The views and conclusions contained herein are those of the authors 2188 and should not be interpreted as necessarily representing the 2189 official policies or endorsements, either expressed or implied, of 2190 the SARACEN project [SARACEN], the European Commission, Huawei or 2191 China Mobile. 2193 10 References 2195 10.1 Normative References 2197 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2198 Requirement Levels", BCP 14, RFC 2119, March 1997. 2200 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2202 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2203 10646", STD 63, RFC 3629, November 2003. 2205 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2206 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2207 3986, January 2005. 2209 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 2210 (ICE): A Protocol for Network Address Translator (NAT) 2211 Traversal for Offer/Answer Protocols", RFC 5245, April 2212 2010. 2214 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2215 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2217 [RFC5389] Rosenberg, J., Mahy R. and D., Wing, "Session Traversal 2218 Utilities for NAT (STUN)", RFC 5389, October 2008. 2220 [RFC5590] Harrington, D. and J., Schoenwaelder, "Transport Subsystem 2221 for the Simple Network Management Protocol (SNMP)", RFC 2222 5590, June 2009. 2224 [RFC5766] Mahy, R., Matthews, P. and J., Rosenberg, "Traversal Using 2225 Relays around NAT (TURN): Relay Extensions to Session 2226 Traversal Utilities for NAT (STUN)", RFC5766, April 2010. 2228 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 2229 Address Text Representation", RFC 5952, August 2010. 2231 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J. and A., 2232 Bierman, "Network Configuration Protocol (NETCONF)", RFC 2233 6241, June 2011. 2235 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 2236 6749, October 2012. 2238 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2239 Interchange Format", RFC 7159, March 2014. 2241 [RFC7230] Fielding, R., and J. Reschke, "Hypertext Transfer Protocol 2242 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2243 2014. 2245 [RFC7231] Fielding, R., and J. Reschke, "Hypertext Transfer Protocol 2246 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 2248 [RFC7285] Alimi, R., Penno, R., Yang, Y., Kiesel S., Previdi, S., 2249 Roome, W., Shalunov, S. and R. Woundy, "Application-Layer 2250 Traffic Optimization (ALTO) Protocol", RF 7285, September 2251 2014. 2253 [RFC7574] Bakker, A., Petrocco, R. and V., Grishchenko, "Peer-to- 2254 Peer Streaming Peer Protocol (PPSPP)", RFC 7574, July 2255 2015. 2257 [RFC7616] Shekh-Yusef, R., Ahrens, D., and S. Bremer, "HTTP Digest 2258 Access Authentication", RFC 7616, September 2015. 2260 10.2 Informative References 2262 [RFC2564] Kalbfleisch, C., Krupczak, C., Presuhn, R., and J. 2263 Saperia, "Application Management MIB", RFC 2564, May 1999. 2265 [RFC2790] Waldbusser, S. and P. Grillo, "Host Resources MIB", RFC 2266 2790, March 2000. 2268 [RFC2975] Aboba, B., Arkko, J., and D. Harrington, "Introduction to 2269 Accounting Management", RFC 2975, October 2000. 2271 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 2272 "Introduction and Applicability Statements for Internet- 2273 Standard Management Framework", RFC 3410, December 2002. 2275 [RFC3729] Waldbusser, S., "Application Performance Measurement MIB", 2276 RFC 3729, March 2004. 2278 [RFC4022] Raghunarayan, R., Ed., "Management Information Base for 2279 the Transmission Control Protocol (TCP)", RFC 4022, March 2280 2005. 2282 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2283 Unique IDentifier (UUID) URN Namespace", RFC 4122, July 2284 2005. 2286 [RFC4150] Dietz, R. and R. Cole, "Transport Performance Metrics 2287 MIB", RFC 4150, August 2005. 2289 [RFC5226] Narten, T. and H., Alvestrand, "Guidelines for Writing an 2290 IANA Considerations Section in RFCs", RFC 5226, May 2008. 2292 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009. 2294 [RFC5706] Harrington, D., "Guidelines for Considering Operations and 2295 Management of New Protocols and Protocol Extensions", RFC 2296 5706, November 2009. 2298 [RFC6709] Carpenter, B., Aboba, B. and S., Cheshire, "Design 2299 Considerations for Protocol Extensions", RFC 6709, 2300 September 2012. 2302 [RFC6972] Zhang, Y., and N., Zong, "Problem Statement and 2303 Requirement of the Peer-to-Peer Streaming Protocol 2304 (PPSP)", RFC 6972, July 2013. 2306 [RFC7525] Sheffer, Y., Holz, R., and P., Saint-Andre, 2307 "Recommendations for Secure Use of Transport Layer 2308 Security (TLS) and Datagram Transport Layer Security 2309 (DTLS)", RFC 7525, May 2015. 2311 [SARACEN] "SARACEN Project Website", http://www.saracen-p2p.eu/. 2313 [Contracts] Piatek, M., Venkataramani, A., Yang, R., Zhang, D. and A. 2314 Jaffe, "Contracts: Practical Contribution Incentives for 2315 P2P Live Streaming", in NSDI '10: USENIX Symposium on 2316 Networked Systems Design and Implementation, April 2010. 2318 Appendix A. Revision History 2320 -00 2013-02-14 Initial version. 2321 -01 2013-02-14 Minor revision. 2322 -02 2013-10-21 Minor revision. 2323 -03 2013-12-31 Major revision 2324 + Introduced a generalization of the protocol specification 2325 using a C-style notation. 2326 - removed all examples of protocol message encoding in XML 2327 -04 2014-07-01 Minor Revision 2328 - removed Appendix referencing the use of HTTP 2329 + refined the presentation language specification to include 2330 protocol elements definitions. 2331 -05 2014-07-04 Minor Revision 2332 -06 2014-10-27 Minor Revision 2333 -07 2014-12-12 Major Revision 2334 + introduced a text-based (JSON) protocol encoding with 2335 examples for all the messages 2336 + corrections in the specifications of protocol elements 2337 + section 5 specification of protocol elements semantics 2338 + introduced a IANA MIME Type registry 2339 -08 2015-01-08 Major Revision 2340 * merge sections 5 and 4 with section 3; renumbered all other 2341 + refined the protocol elements definitions for consistency 2342 with the JSON data structures 2344 + revised protocol messages encoding examples 2345 + additional IANA registry for protocol version 2346 * editorial corrections 2347 -09 (2015-3-27) Major Revision 2348 + Add concurrent_link in the stream_stats specification. 2349 + Remove "PROXY" value from "ability_nat" specification. 2350 + Dividing attributes by "," in the example 2351 * editorial corrections 2352 -10 (Current version) Major Revision 2353 + Update dates 2354 -11 (2015-12-12) Address the comments from IESG review 2356 Authors' Addresses 2358 Rui Santos Cruz 2359 IST/INESC-ID/INOV 2360 Phone: +351.939060939 2361 Email: rui.cruz@ieee.org 2363 Mario Serafim Nunes 2364 IST/INESC-ID/INOV 2365 Rua Alves Redol, n.9 2366 1000-029 LISBOA, Portugal 2367 Phone: +351.213100256 2368 Email: mario.nunes@inov.pt 2370 Rachel Huang (Editor) 2371 Huawei 2372 Email: rachel.huang@huawei.com 2374 Jinwei Xia 2375 Huawei 2376 Nanjing, Baixia District 210001, China 2377 Phone: +86-025-86622310 2378 Email: xiajinwei@huawei.com 2380 Joao P. Taveira 2381 IST/INOV 2382 Email: joao.silva@inov.pt 2384 Deng Lingli 2385 China Mobile 2386 Email: denglingli@chinamobile.com 2388 Gu Yingjie 2389 Email: guyingjie@gmail.com