idnits 2.17.1 draft-ietf-alto-protocol-11.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 : ---------------------------------------------------------------------------- -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 932 has weird spacing: '...etaData meta...' == Line 938 has weird spacing: '... meta meta-...' == Line 940 has weird spacing: '... data the d...' == Line 1255 has weird spacing: '...NString uri;...' == Line 1256 has weird spacing: '...NString medi...' == (9 more instances...) -- The document date (March 11, 2012) is 4426 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) == Missing Reference: 'ATTP' is mentioned on line 218, but not defined == Missing Reference: 'OPTIONAL' is mentioned on line 2093, but not defined == Missing Reference: 'InfoResourceDataType' is mentioned on line 933, but not defined == Missing Reference: 'TODO' is mentioned on line 2190, but not defined == Missing Reference: 'PIDName' is mentioned on line 1607, but not defined == Missing Reference: 'EndpointProperty' is mentioned on line 1993, but not defined == Missing Reference: 'TypedEndpointAddr' is mentioned on line 2130, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE.754.2008' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5389 (Obsoleted by RFC 8489) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) == Outdated reference: A later version (-16) exists of draft-ietf-alto-reqs-08 == Outdated reference: A later version (-10) exists of draft-ietf-alto-server-discovery-03 Summary: 5 errors (**), 0 flaws (~~), 16 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ALTO WG R. Alimi, Ed. 3 Internet-Draft Google 4 Intended status: Standards Track R. Penno, Ed. 5 Expires: September 12, 2012 Juniper Networks 6 Y. Yang, Ed. 7 Yale University 8 March 11, 2012 10 ALTO Protocol 11 draft-ietf-alto-protocol-11.txt 13 Abstract 15 Networking applications today already have access to a great amount 16 of Inter-Provider network topology information. For example, views 17 of the Internet routing table are easily available at looking glass 18 servers and entirely practical to be downloaded by clients. What is 19 missing is knowledge of the underlying network topology from the ISP 20 or Content Provider (henceforth referred as Provider) point of view. 21 In other words, what a Provider prefers in terms of traffic 22 optimization -- and a way to distribute it. 24 The ALTO Service provides network information (e.g., basic network 25 location structure, preferences of network paths) with the goal of 26 modifying network resource consumption patterns while maintaining or 27 improving application performance. The basic information of ALTO is 28 based on abstract maps of a network. These maps provide simplified, 29 yet enough information of a network for applications to effectively 30 utilize. Additional services are built on top the maps. 32 This document describes a protocol implementing the ALTO Service. 33 Although the ALTO service would primarily be provided by the network 34 (i.e., the ISP), content providers and third parties could also 35 operate this service. Applications that could use this service are 36 those that have a choice in connection endpoints. Examples of such 37 applications are peer-to-peer (P2P) and content delivery networks. 39 Requirements Language 41 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 42 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 43 document are to be interpreted as described in RFC 2119 [RFC2119]. 45 Status of this Memo 47 This Internet-Draft is submitted in full conformance with the 48 provisions of BCP 78 and BCP 79. 50 Internet-Drafts are working documents of the Internet Engineering 51 Task Force (IETF). Note that other groups may also distribute 52 working documents as Internet-Drafts. The list of current Internet- 53 Drafts is at http://datatracker.ietf.org/drafts/current/. 55 Internet-Drafts are draft documents valid for a maximum of six months 56 and may be updated, replaced, or obsoleted by other documents at any 57 time. It is inappropriate to use Internet-Drafts as reference 58 material or to cite them other than as "work in progress." 60 This Internet-Draft will expire on September 12, 2012. 62 Copyright Notice 64 Copyright (c) 2012 IETF Trust and the persons identified as the 65 document authors. All rights reserved. 67 This document is subject to BCP 78 and the IETF Trust's Legal 68 Provisions Relating to IETF Documents 69 (http://trustee.ietf.org/license-info) in effect on the date of 70 publication of this document. Please review these documents 71 carefully, as they describe your rights and restrictions with respect 72 to this document. Code Components extracted from this document must 73 include Simplified BSD License text as described in Section 4.e of 74 the Trust Legal Provisions and are provided without warranty as 75 described in the Simplified BSD License. 77 Table of Contents 79 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 80 1.1. Background and Problem Statement . . . . . . . . . . . . . 6 81 1.2. Design History and Merged Proposals . . . . . . . . . . . 6 82 1.3. Solution Benefits . . . . . . . . . . . . . . . . . . . . 7 83 1.3.1. Service Providers . . . . . . . . . . . . . . . . . . 7 84 1.3.2. Applications . . . . . . . . . . . . . . . . . . . . . 7 85 2. Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 7 86 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 87 2.1.1. Endpoint Address . . . . . . . . . . . . . . . . . . . 8 88 2.1.2. ASN . . . . . . . . . . . . . . . . . . . . . . . . . 8 89 2.1.3. Network Location . . . . . . . . . . . . . . . . . . . 8 90 2.1.4. ALTO Information . . . . . . . . . . . . . . . . . . . 8 91 2.1.5. ALTO Information Base . . . . . . . . . . . . . . . . 8 92 2.2. ALTO Service and Protocol Scope . . . . . . . . . . . . . 8 93 3. Protocol Structure . . . . . . . . . . . . . . . . . . . . . . 10 94 3.1. ALTO Information Services . . . . . . . . . . . . . . . . 11 95 3.1.1. Map Service . . . . . . . . . . . . . . . . . . . . . 11 96 3.1.2. Map Filtering Service . . . . . . . . . . . . . . . . 12 97 3.1.3. Endpoint Property Service . . . . . . . . . . . . . . 12 98 3.1.4. Endpoint Cost Service . . . . . . . . . . . . . . . . 12 99 4. Network Map . . . . . . . . . . . . . . . . . . . . . . . . . 12 100 4.1. PID . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 101 4.2. Endpoint Addresses . . . . . . . . . . . . . . . . . . . . 13 102 4.2.1. IP Addresses . . . . . . . . . . . . . . . . . . . . . 13 103 4.3. Example Network Map . . . . . . . . . . . . . . . . . . . 14 104 5. Cost Map . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 105 5.1. Cost Attributes . . . . . . . . . . . . . . . . . . . . . 15 106 5.1.1. Cost Type . . . . . . . . . . . . . . . . . . . . . . 15 107 5.1.2. Cost Mode . . . . . . . . . . . . . . . . . . . . . . 15 108 5.2. Cost Map Structure . . . . . . . . . . . . . . . . . . . . 16 109 5.3. Network Map and Cost Map Dependency . . . . . . . . . . . 17 110 6. Protocol Design Overview . . . . . . . . . . . . . . . . . . . 17 111 6.1. Benefits . . . . . . . . . . . . . . . . . . . . . . . . . 17 112 6.1.1. Existing Infrastructure . . . . . . . . . . . . . . . 18 113 6.1.2. ALTO Information Reuse and Redistribution . . . . . . 18 114 6.2. Protocol Design . . . . . . . . . . . . . . . . . . . . . 18 115 7. Protocol Specification . . . . . . . . . . . . . . . . . . . . 19 116 7.1. Notation . . . . . . . . . . . . . . . . . . . . . . . . . 19 117 7.2. Basic Operation . . . . . . . . . . . . . . . . . . . . . 19 118 7.2.1. Discovering Information Resources . . . . . . . . . . 19 119 7.2.2. Requesting Information Resources . . . . . . . . . . . 20 120 7.2.3. Response . . . . . . . . . . . . . . . . . . . . . . . 20 121 7.2.4. Client Behavior . . . . . . . . . . . . . . . . . . . 20 122 7.2.5. Authentication and Encryption . . . . . . . . . . . . 21 123 7.2.6. HTTP Cookies . . . . . . . . . . . . . . . . . . . . . 21 124 7.2.7. Parsing . . . . . . . . . . . . . . . . . . . . . . . 21 126 7.3. Information Resource . . . . . . . . . . . . . . . . . . . 21 127 7.3.1. Capabilities . . . . . . . . . . . . . . . . . . . . . 21 128 7.3.2. Input Parameters Media Type . . . . . . . . . . . . . 22 129 7.3.3. Media Type . . . . . . . . . . . . . . . . . . . . . . 22 130 7.3.4. Encoding . . . . . . . . . . . . . . . . . . . . . . . 22 131 7.4. ALTO Errors . . . . . . . . . . . . . . . . . . . . . . . 23 132 7.4.1. Media Type . . . . . . . . . . . . . . . . . . . . . . 23 133 7.4.2. Resource Format . . . . . . . . . . . . . . . . . . . 24 134 7.4.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 24 135 7.5. ALTO Types . . . . . . . . . . . . . . . . . . . . . . . . 25 136 7.5.1. PID Name . . . . . . . . . . . . . . . . . . . . . . . 25 137 7.5.2. Version Tag . . . . . . . . . . . . . . . . . . . . . 25 138 7.5.3. Endpoints . . . . . . . . . . . . . . . . . . . . . . 26 139 7.5.4. Cost Mode . . . . . . . . . . . . . . . . . . . . . . 28 140 7.5.5. Cost Type . . . . . . . . . . . . . . . . . . . . . . 28 141 7.5.6. Endpoint Property . . . . . . . . . . . . . . . . . . 28 142 7.6. Information Resource Directory . . . . . . . . . . . . . . 29 143 7.6.1. Media Type . . . . . . . . . . . . . . . . . . . . . . 29 144 7.6.2. Encoding . . . . . . . . . . . . . . . . . . . . . . . 29 145 7.6.3. Example . . . . . . . . . . . . . . . . . . . . . . . 30 146 7.6.4. Usage Considerations . . . . . . . . . . . . . . . . . 33 147 7.7. Information Resources . . . . . . . . . . . . . . . . . . 34 148 7.7.1. Map Service . . . . . . . . . . . . . . . . . . . . . 34 149 7.7.2. Map Filtering Service . . . . . . . . . . . . . . . . 39 150 7.7.3. Endpoint Property Service . . . . . . . . . . . . . . 45 151 7.7.4. Endpoint Cost Service . . . . . . . . . . . . . . . . 48 152 8. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 52 153 8.1. ALTO Client Embedded in P2P Tracker . . . . . . . . . . . 52 154 8.2. ALTO Client Embedded in P2P Client: Numerical Costs . . . 53 155 8.3. ALTO Client Embedded in P2P Client: Ranking . . . . . . . 54 156 9. Discussions . . . . . . . . . . . . . . . . . . . . . . . . . 55 157 9.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 55 158 9.2. Hosts with Multiple Endpoint Addresses . . . . . . . . . . 56 159 9.3. Network Address Translation Considerations . . . . . . . . 56 160 9.4. Mapping IPs to ASNs . . . . . . . . . . . . . . . . . . . 57 161 9.5. Endpoint and Path Properties . . . . . . . . . . . . . . . 57 162 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 163 10.1. application/alto-* Media Types . . . . . . . . . . . . . . 57 164 10.2. ALTO Cost Type Registry . . . . . . . . . . . . . . . . . 59 165 10.3. ALTO Endpoint Property Registry . . . . . . . . . . . . . 60 166 11. Security Considerations . . . . . . . . . . . . . . . . . . . 61 167 11.1. Privacy Considerations for ISPs . . . . . . . . . . . . . 61 168 11.2. ALTO Clients . . . . . . . . . . . . . . . . . . . . . . . 62 169 11.3. Authentication, Integrity Protection, and Encryption . . . 62 170 11.4. ALTO Information Redistribution . . . . . . . . . . . . . 63 171 11.5. Denial of Service . . . . . . . . . . . . . . . . . . . . 63 172 11.6. ALTO Server Access Control . . . . . . . . . . . . . . . . 63 173 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 64 174 12.1. Normative References . . . . . . . . . . . . . . . . . . . 64 175 12.2. Informative References . . . . . . . . . . . . . . . . . . 65 176 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 66 177 Appendix B. Authors . . . . . . . . . . . . . . . . . . . . . . . 67 178 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 68 180 1. Introduction 182 1.1. Background and Problem Statement 184 Today, network information available to applications is mostly from 185 the view of endhosts. There is no clear mechanism to convey 186 information about the network (e.g., preferences) to applications. 187 On the other hand, modern network applications can be adaptive, with 188 the potential to become more network-efficient (e.g., reduce network 189 resource consumption) and achieve better application performance 190 (e.g., accelerated download rate), by leveraging better network- 191 provided information. 193 The ALTO Service intends to provide a simple mechanism to convey 194 network information to applications. Its objective is to provide 195 basic, abstract but useful network information to applications. The 196 mechanism should include abstractions to achieve concise, flexible 197 network information expression. 199 The goal of this document is to specify a simple and unified protocol 200 that meets the ALTO requirements [I-D.ietf-alto-reqs] while providing 201 a migration path for Internet Service Providers (ISP), Content 202 Providers, and clients that have deployed protocols with similar 203 intentions (see below). This document is a work in progress and will 204 be updated with further developments. 206 1.2. Design History and Merged Proposals 208 The protocol specified here consists of contributions from 210 o P4P [I-D.p4p-framework], [P4P-SIGCOMM08], 211 [I-D.wang-alto-p4p-specification]; 213 o ALTO Info-Export [I-D.shalunov-alto-infoexport]; 215 o Query/Response [I-D.saumitra-alto-queryresponse], 216 [I-D.saumitra-alto-multi-ps]; 218 o ATTP [ATTP]; 220 o Proxidor [I-D.akonjang-alto-proxidor]. 222 See Appendix A for a list of people that have contributed 223 significantly to this effort and the projects and proposals listed 224 above. 226 1.3. Solution Benefits 228 The ALTO Service offers many benefits to both end-users (consumers of 229 the service) and Internet Service Providers (providers of the 230 service). 232 1.3.1. Service Providers 234 The ALTO Service enables ISPs to influence the peer selection process 235 in distributed applications in order to increase locality of traffic, 236 improve user-experience, amongst others. It also helps ISPs to 237 efficiently manage traffic that traverses more expensive links such 238 as transit and backup links, thus allowing a better provisioning of 239 the networking infrastructure. 241 1.3.2. Applications 243 Applications that use the ALTO Service can benefit in multiple ways. 244 For example, they may no longer need to infer topology information, 245 and some applications can reduce reliance on measuring path 246 performance metrics themselves. They can take advantage of the ISP's 247 knowledge to avoid bottlenecks and boost performance. 249 An example type of application is a Peer-to-Peer overlay where peer 250 selection can be improved by including ALTO information in the 251 selection process. 253 2. Architecture 255 Two key design objectives of the ALTO Protocol are simplicity and 256 extensibility. At the same time, it introduces additional techniques 257 to address potential scalability and privacy issues. This section 258 first introduces the terminology, and then defines the ALTO 259 architecture and the ALTO Protocol's place in the overall 260 architecture. 262 2.1. Terminology 264 We use the following terms defined in [RFC5693]: Application, Overlay 265 Network, Peer, Resource, Resource Identifier, Resource Provider, 266 Resource Consumer, Resource Directory, Transport Address, Host 267 Location Attribute, ALTO Service, ALTO Server, ALTO Client, ALTO 268 Query, ALTO Reply, ALTO Transaction, Local Traffic, Peering Traffic, 269 Transit Traffic. 271 We also use the following additional terms: Endpoint Address, 272 Autonomous System Number (ASN), and Network Location. 274 2.1.1. Endpoint Address 276 An endpoint address represents the communication address of an 277 endpoint. An endpoint address can be network-attachment based (IP 278 address) or network-attachment agnostic. Common forms of endpoint 279 addresses include IP address, MAC address, overlay ID, and phone 280 number. 282 Each Endpoint Address has an associated Address Type, which indicates 283 both its syntax and semantics. 285 2.1.2. ASN 287 An Autonomous System Number. 289 2.1.3. Network Location 291 Network Location is a generic term denoting a single endpoint or 292 group of endpoints. 294 2.1.4. ALTO Information 296 ALTO Information is a generic term referring to the network 297 information sent by an ALTO Server. 299 2.1.5. ALTO Information Base 301 Internal representation of the ALTO Information maintained by the 302 ALTO Server. Note that the structure of this internal representation 303 is not defined by this document. 305 2.2. ALTO Service and Protocol Scope 307 An ALTO Server conveys the network information from the perspective 308 of a network region; the ALTO Server presents its "my-Internet View" 309 of the network region. In particular, an ALTO Server defines network 310 Endpoints (and aggregations thereof) and generic costs amongst them, 311 both from the network region's own perspective. A network region in 312 this context can be an Autonomous System, an ISP, or perhaps a 313 smaller region or set of ISPs; the details depend on the deployment 314 scenario and discovery mechanism. 316 To better understand the ALTO Service and the role of the ALTO 317 Protocol, we show in Figure 1 the overall system architecture. In 318 this architecture, an ALTO Server prepares ALTO Information; an ALTO 319 Client uses ALTO Service Discovery to identify an appropriate ALTO 320 Server; and the ALTO Client requests available ALTO Information from 321 the ALTO Server using the ALTO Protocol. 323 The ALTO Information provided by the ALTO Server can be updated 324 dynamically based on network conditions, or can be seen as a policy 325 which is updated at a larger time-scale. 327 More specifically, the ALTO Information provided by an ALTO Server 328 may be influenced (at the operator's discretion) by other systems. 329 The ALTO Server aggregates information from multiple systems to 330 provide an abstract, unified, useful network view to applications. 331 Examples of other systems include (but are not limited to) static 332 network configuration databases, dynamic network information, routing 333 protocols, provisioning policies, and interfaces to outside parties. 334 These components are shown in the figure for completeness but outside 335 the scope of this specification. 337 Note that it may also be possible for ALTO Servers to exchange 338 network information with other ALTO Servers (either within the same 339 administrative domain or another administrative domain with the 340 consent of both parties) in order to adjust exported ALTO 341 Information. Such a protocol is also outside the scope of this 342 specification. 344 +-------------------------------------------------------------------+ 345 | ISP | 346 | | 347 | +-----------+ | 348 | | Routing | | 349 | +--------------+ | Protocols | | 350 | | Provisioning | +-----------+ | 351 | | Policy | | | 352 | +--------------+\ | | 353 | \ | | 354 | \ | | 355 | +-----------+ \+---------+ +--------+ | 356 | |Dynamic | | ALTO | ALTO Protocol | ALTO | | 357 | |Network |.......| Server | -------------------- | Client | | 358 | |Information| +---------+ +--------+ | 359 | +-----------+ / / | 360 | / ALTO SD Query/Response / | 361 | / / | 362 | +----------+ +--------------+ | 363 | | External | | ALTO Service | | 364 | | Interface| | Discovery | | 365 | +----------+ +--------------+ | 366 | | | 367 +-------------------------------------------------------------------+ 368 | 369 +------------------+ 370 | Third Parties | 371 | | 372 | Content Providers| 373 +------------------+ 375 Figure 1: Basic ALTO Architecture. 377 3. Protocol Structure 379 The ALTO Protocol uses a simple extensible framework to convey 380 network information. In the general framework, the ALTO protocol 381 will convey properties on both Network Locations and the paths 382 between Network Locations. 384 In this document, we focus on a particular Endpoint property to 385 denote the location of an endpoint, and provider-defined costs for 386 paths between pairs of Network Locations. 388 The ALTO Protocol is built on a common transport protocol, messaging 389 structure and encoding, and transaction model. The protocol is 390 subdivided into services of related functionality. ALTO-Core 391 provides the Map Service, which provides the core ALTO informtion to 392 clients. Other ALTO Information services can provide additional 393 functionality. There are three such services defined in this 394 document: the Map Filtering Service, Endpoint Property Service, and 395 Endpoint Cost Service. Additional services may be defined in 396 companion documents. Note that functionality offered in different 397 services are not totally non-overlapping (e.g., the Map Service and 398 Map Filtering Service). 400 .-----------------------------------------. 401 | ALTO Information Services | 402 | .-----------. .----------. .----------. | 403 | | Map | | Endpoint | | Endpoint | | 404 | | Filtering | | Property | | Cost | | 405 | | Service | | Service | | Service | | 406 | `-----------' `----------' `----------' | 407 | .-------------------------------------. | 408 | | Map Service | | 409 | | .-------------. .--------------. | | 410 | | | Network Map | | Cost Map | | | 411 | | `-------------' `--------------' | | 412 | `-------------------------------------' | 413 `-----------------------------------------' 415 Figure 2: ALTO Protocol Structure 417 3.1. ALTO Information Services 419 Multiple, distinct services are defined to allow ALTO Clients to 420 query ALTO Information from an ALTO Server. The ALTO Server 421 internally maintains an ALTO Information Base that encodes the 422 network provider's preferences. The ALTO Information Base encodes 423 the Network Locations defined by the ALTO Server (and their 424 corresponding properties), as well as the provider-defined costs 425 between pairs of Network Locations. 427 3.1.1. Map Service 429 The Map Service provides batch information to ALTO Clients in the 430 form of Network Map and Cost Map. The Network Map (See Section 4) 431 provides the full set of Network Location groupings defined by the 432 ALTO Server and the endpoints contained with each grouping. The Cost 433 Map (see Section 5) provides costs between the defined groupings. 435 These two maps can be thought of (and implemented as) as simple files 436 with appropriate encoding provided by the ALTO Server. 438 3.1.2. Map Filtering Service 440 Resource constrained ALTO Clients may benefit from query results 441 being filtered at the ALTO Server. This avoids an ALTO Client 442 spending network bandwidth or CPU collecting results and performing 443 client-side filtering. The Map Filtering Service allows ALTO Clients 444 to query for the ALTO Server Network Map and Cost Map based on 445 additional parameters. 447 3.1.3. Endpoint Property Service 449 This service allows ALTO Clients to look up properties for individual 450 endpoints. An example endpoint property is its Network Location (its 451 grouping defined by the ALTO Server) or connectivity type (e.g., 452 ADSL, Cable, or FTTH). 454 3.1.4. Endpoint Cost Service 456 Some ALTO Clients may also benefit from querying for costs and 457 rankings based on endpoints. The Endpoint Cost Service allows an 458 ALTO Server to return either numerical costs or ordinal costs 459 (rankings) directly amongst Endpoints. 461 4. Network Map 463 In reality, many endpoints are very close to one another in terms of 464 network connectivity, for example, endpoints on the same site of an 465 enterprise. By treating a group of endpoints together as a single 466 entity in ALTO, we can achieve much greater scalability without 467 losing critical information. 469 The Network Location endpoint property allows an ALTO Server to group 470 endpoints together to indicate their proximity. The resulting set of 471 groupings is called the ALTO Network Map. 473 The definition of proximity varies depending on the granularity of 474 the ALTO information configured by the provider. In one deployment, 475 endpoints on the same subnet may be considered close; while in 476 another deployment, endpoints connected to the same PoP may be 477 considered close. 479 As used in this document, the Network Map refers to the syntax and 480 semantics of the information distributed by the ALTO Server. This 481 document does not discuss the internal representation of this data 482 structure within the ALTO Server. 484 4.1. PID 486 Each group of Endpoints is identified by a provider-defined Network 487 Location identifier called a PID. There can be many different ways 488 of grouping the endpoints and assigning PIDs. 490 A PID is an identifier that provides an indirect and network-agnostic 491 way to specify an aggregation of network endpoints that may be 492 treated similarly, based on network topology, type, or other 493 properties. For example, a PID may be defined by the ALTO service 494 provider to denote a subnet, a set of subnets, a metropolitan area, a 495 PoP, an autonomous system, or a set of autonomous systems. 496 Aggregation of endpoints into PIDs can indicate proximity and can 497 improve scalability. In particular, network preferences (costs) may 498 be specified between PIDs, allowing cost information to be more 499 compactly represented and updated at a faster time scale than the 500 network aggregations themselves. 502 Using PIDs, the Network Map may also be used to communicate simple 503 preferences with only minimal information from the Cost Map. For 504 example, an ISP may prefer that endpoints associated with the same 505 PoP (Point-of-Presence) in a P2P application communicate locally 506 instead of communicating with endpoints in other PoPs. The ISP may 507 aggregate endhosts within a PoP into a single PID in the Network Map. 508 The Cost Map may be encoded to indicate that peering within the same 509 PID is preferred; for example, cost(PID_i, PID_i) == c* and 510 cost(PID_i, PID_j) > c* for i != j. Section 5 provides further 511 details about Cost Map structure. 513 4.2. Endpoint Addresses 515 Communicating endpoints may have many types of addresses, such as IP 516 addresses, MAC addresses, or overlay IDs. The current specification 517 only considers IP addresses. 519 4.2.1. IP Addresses 521 The endpoints aggregated into a PID are denoted by a list of IP 522 prefixes. When either an ALTO Client or ALTO Server needs to 523 determine which PID in a Network Map contains a particular IP 524 address, longest-prefix matching MUST be used. 526 A Network Map MUST define a PID for each possible address in the IP 527 address space for all of the address types contained in the map. A 528 RECOMMENDED way to satisfy this property is to define a PID that 529 contains the 0.0.0.0/0 prefix for IPv4 or ::/0 (for IPv6). 531 Each endpoint MUST map into exactly one PID. Since longest-prefix 532 matching is used to map an endpoint to a PID, this can be 533 accomplished by ensuring that no two PIDs contain an identical IP 534 prefix. 536 4.3. Example Network Map 538 Figure 3 illustrates an example Network Map. PIDs are used to 539 identify network-agnostic aggregations. 541 .-----------------------------------------------------------. 542 | ALTO Network Map | 543 | | 544 | .-----------------------------------. .---------------. | 545 | | NetLoc: PID-1 | | NetLoc: PID-2 | | 546 | | .------------------------------. | | ... | | 547 | | | 192.0.2.0/24 | | `---------------` | 548 | | | .--------------------------. | | | 549 | | | | Endpoint: 192.0.2.34 | | | .---------------. | 550 | | | `--------------------------` | | | NetLoc: PID-3 | | 551 | | `------------------------------` | | ... | | 552 | | .------------------------------. | `---------------` | 553 | | | 198.51.100.0/25 | | | 554 | | | .--------------------------. | | .---------------. | 555 | | | | Endpoint: 198.51.100.100 | | | | NetLoc: PID-4 | | 556 | | | `--------------------------` | | | ... | | 557 | | `------------------------------` | `---------------` | 558 | `-----------------------------------` | 559 | | 560 `-----------------------------------------------------------` 562 Figure 3: Example Network Map 564 5. Cost Map 566 An ALTO Server indicates preferences amongst network locations in the 567 form of Path Costs. Path Costs are generic costs and can be 568 internally computed by a network provider according to its own needs. 570 An ALTO Cost Map defines Path Costs pairwise amongst sets of source 571 and destination Network Locations. Each Path Cost is the end-to-end 572 cost from the source to the destination. 574 One advantage of separating ALTO information into a Network Map and a 575 Cost Map is that the two components can be updated at different time 576 scales. For example, Network Maps may be stable for a longer time 577 while Cost Maps may be updated to reflect dynamic network conditions. 579 As used in this document, the Cost Map refers to the syntax and 580 semantics of the information distributed by the ALTO Server. This 581 document does not discuss the internal representation of this data 582 structure within the ALTO Server. 584 5.1. Cost Attributes 586 Path Costs have attributes: 588 o Type: identifies what the costs represent; 590 o Mode: identifies how the costs should be interpreted. 592 Certain queries for Cost Maps allow the ALTO Client to indicate the 593 desired Type and Mode. 595 5.1.1. Cost Type 597 The Type attribute indicates what the cost represents. For example, 598 an ALTO Server could define costs representing air-miles, hop-counts, 599 or generic routing costs. 601 Cost types are indicated in protocol messages as strings. 603 5.1.1.1. Cost Type: routingcost 605 An ALTO Server MUST define the 'routingcost' Cost Type. 607 This Cost Type conveys a generic measure for the cost of routing 608 traffic from a source to a destination. Lower values indicate a 609 higher preference for traffic to be sent from a source to a 610 destination. 612 Note that an ISP may internally compute routing cost using any method 613 it chooses (e.g., air-miles or hop-count) as long as it conforms to 614 these semantics. 616 5.1.2. Cost Mode 618 The Mode attribute indicates how costs should be interpreted. 619 Specifically, the Mode attribute indicates whether returned costs 620 should be interpreted as numerical values or ordinal rankings. 622 It is important to communicate such information to ALTO Clients, as 623 certain operations may not be valid on certain costs returned by an 624 ALTO Server. For example, it is possible for an ALTO Server to 625 return a set of IP addresses with costs indicating a ranking of the 626 IP addresses. Arithmetic operations that would make sense for 627 numerical values, do not make sense for ordinal rankings. ALTO 628 Clients may handle such costs differently. 630 Cost Modes are indicated in protocol messages as strings. 632 An ALTO Server MUST support at least one of 'numerical' and 'ordinal' 633 costs. ALTO Clients SHOULD be cognizant of operations when a desired 634 cost mode is not supported. For example, an ALTO Client desiring 635 numerical costs may adjust behavior if only the ordinal Cost Mode is 636 available. Alternatively, an ALTO Client desiring ordinal costs may 637 construct ordinal costs given numerical values if only the numerical 638 Cost Mode is available. 640 5.1.2.1. Cost Mode: numerical 642 This Cost Mode is indicated by the string 'numerical'. This mode 643 indicates that it is safe to perform numerical operations (e.g. 644 normalization) on the returned costs. 646 5.1.2.2. Cost Mode: ordinal 648 This Cost Mode is indicated by the string 'ordinal'. This mode 649 indicates that the costs values to a set of Destination Network 650 Locations from a particular Source Network Location are a ranking, 651 with lower values indicating a higher preference. The values are 652 non-negative integers. Ordinal cost values from a particular Source 653 Network Location to a set of Destination Network Locations need not 654 be unique nor contiguous. In particular, from the perspective of a 655 particular Source Network Location, two Destination Network Locations 656 may have an identical rank (ordinal cost value). This document does 657 not specify any behavior by an ALTO Client in this case; an ALTO 658 Client may decide to break ties by random selection, other 659 application knowledge, or some other means. 661 It is important to note that the values in the Cost Map provided with 662 the ordinal Cost Mode are not necessarily the actual cost known to 663 the ALTO Server. 665 5.2. Cost Map Structure 667 A query for a Cost Map either explicitly or implicitly includes a 668 list of Source Network Locations and a list of Destination Network 669 Locations. (Recall that a Network Location can be an endpoint 670 address or a PID.) 672 Specifically, assume that a query has a list of multiple Source 673 Network Locations, say [Src_1, Src_2, ..., Src_m], and a list of 674 multiple Destination Network Locations, say [Dst_1, Dst_2, ..., 675 Dst_n]. 677 The ALTO Server will return the Path Cost for each communicating pair 678 (i.e., Src_1 -> Dst_1, ..., Src_1 -> Dst_n, ..., Src_m -> Dst_1, ..., 679 Src_m -> Dst_n). If the ALTO Server does not define a Path Cost for 680 a particular pair, it may be omitted. We refer to this structure as 681 a Cost Map. 683 If the Cost Mode is 'ordinal', the Path Cost of each communicating 684 pair is relative to the m*n entries. 686 5.3. Network Map and Cost Map Dependency 688 If a Cost Map contains PIDs in the list of Source Network Locations 689 or the list of Destination Network Locations, the Path Costs are 690 generated based on a particular Network Map (which defines the PIDs). 691 Version Tags are introduced to ensure that ALTO Clients are able to 692 use consistent information even though the information is provided in 693 two maps. 695 A Version Tag is an opaque string associated with a Network Map 696 maintained by the ALTO Server. When the Network Map changes, the 697 Version Tag MUST also be changed. (Thus, the Version Tag is defined 698 similarly to HTTP's Entity Tags; see Section 3.11 of [RFC2616].) 699 Possibilities for generating a Version Tag include the last-modified 700 timestamp for the Network Map, or a hash of its contents. 702 A Network Map distributed by the ALTO Server includes its Version 703 Tag. A Cost Map referring to PIDs also includes the Version Tag of 704 the Network Map on which it is based. 706 6. Protocol Design Overview 708 The ALTO Protocol design uses a REST-ful design with the goal of 709 leveraging current HTTP [RFC2616] implementations and infrastructure. 710 The REST-ful design supports flexible deployment strategies and 711 provides extensibility. ALTO requests and responses are encoded with 712 JSON [RFC4627]. 714 6.1. Benefits 716 Benefits enabled by these design choices include easier understanding 717 and debugging, mature libraries, tools, infrastructure, and caching 718 and redistribution of ALTO information for increased scalability. 720 6.1.1. Existing Infrastructure 722 HTTP is a natural choice for integration with existing applications 723 and infrastructure. In particular, the ALTO Protocol design 724 leverages: 726 o the huge installed base of infrastructure, including HTTP caches, 728 o mature software implementations, 730 o the fact that many P2P clients already have an embedded HTTP 731 client, and 733 o authentication and encryption mechanisms in HTTP and SSL/TLS. 735 6.1.2. ALTO Information Reuse and Redistribution 737 ALTO information may be useful to a large number of applications and 738 users. For example, an identical Network Map may be used by all ALTO 739 Clients querying a particular ALTO Server. At the same time, 740 distributing ALTO information must be efficient and not become a 741 bottleneck. 743 Beyond integration with existing HTTP caching infrastructure, ALTO 744 information may also be cached or redistributed using application- 745 dependent mechanisms, such as P2P DHTs or P2P file-sharing. This 746 document does not define particular mechanisms for such 747 redistribution. See [I-D.gu-alto-redistribution] for further 748 discussion. 750 Note that if caching or redistribution is used, the response message 751 may be returned from another (possibly third-party) entity. 753 6.2. Protocol Design 755 The ALTO Protocol uses a REST-ful design. There are two primary 756 components to this design: 758 o Information Resources: Each service provides network information 759 as a set of resources, which are distinguished by their media 760 types [RFC2046]. An ALTO Client may construct an HTTP request for 761 a particular resource (including any parameters, if necessary), 762 and an ALTO Server returns the requested resource in an HTTP 763 response. 765 o Information Resource Directory: An ALTO Server provides to ALTO 766 Clients a list of available resources and the URI at which each is 767 provided. This document refers to this list as the Information 768 Resource Directory. This directory is the single entry point to 769 an ALTO Service. ALTO Clients consult the directory to determine 770 the services provided by an ALTO Server. 772 7. Protocol Specification 774 This section first specifies general client and server processing, 775 followed by a detailed specification for each ALTO Information 776 Resource. 778 7.1. Notation 780 This document uses an adaptation of the C-style struct notation to 781 define the required and optional members of JSON objects. Unless 782 explicitly noted, each member of a struct is REQUIRED. 784 The types 'JSONString', 'JSONNumber', 'JSONBool' indicate the JSON 785 string, number, and boolean types, respectively. 'JSONValue' 786 indicates a JSON value, as specified in Section 2.1 of [RFC4627]. 788 Note that no standard, machine-readable interface definition or 789 schema is provided. Extension documents may document these as 790 necessary. 792 7.2. Basic Operation 794 The ALTO Protocol employs standard HTTP [RFC2616]. It is used for 795 discovering available Information Resources at an ALTO Server and 796 retrieving Information Resources. ALTO Clients and ALTO Servers use 797 HTTP requests and responses carrying ALTO-specific content with 798 encoding as specified in this document, and MUST be compliant with 799 [RFC2616]. 801 7.2.1. Discovering Information Resources 803 To discover available resources, an ALTO Client may request the 804 Information Resource Directory, which an ALTO Server provides at the 805 URI found by the ALTO Discovery protocol. 807 Informally, an Information Resource Directory enumerates URIs at 808 which an ALTO Server offers Information Resources. Each entry in the 809 directory indicates a URI at which an ALTO Server accepts requests, 810 and returns either the requested Information Resource or an 811 Information Resource Directory that references additional Information 812 Resources. See Section 7.6 for a detailed specification. 814 7.2.2. Requesting Information Resources 816 Through the retrieved Information Resource Directories, an ALTO 817 Client can determine whether an ALTO Server supports the desired 818 Information Resource, and if it is supported, the URI at which it is 819 available. 821 Where possible, the ALTO Protocol uses the HTTP GET method to request 822 resources. However, some ALTO services provide Information Resources 823 that are the function of one or more input parameters. Input 824 parameters are encoded in the HTTP request's entity body, and the 825 request uses the HTTP POST method. 827 Note that it is possible for an ALTO Server to employ caching for the 828 response to a POST request. This can be accomplished by returning an 829 HTTP 303 status code ("See Other") indicating to the ALTO Client that 830 the resulting Cost Map is available via a GET request to an alternate 831 URL (which may be cached). 833 When requesting an ALTO Information Resource that requires input 834 parameters specified in a HTTP POST request, an ALTO Client MUST set 835 the Content-Type HTTP header to the media type corresponding to the 836 format of the supplied input parameters. 838 7.2.3. Response 840 Upon receiving a request, an ALTO server either returns the requested 841 resource, provides the ALTO Client an Information Resource Directory 842 indicating how to reach the desired resource, or returns an error. 844 The type of response MUST be indicated by the media type attached to 845 the response (the Content-Type HTTP header). If an ALTO Client 846 receives an Information Resource Directory, it can consult the 847 received directory to determine if any of the offered URIs contain 848 the desired Information Resource. 850 The generic encoding for an Information Resource is specified in 851 Section 7.3. 853 Errors are indicated via either ALTO-level error codes, or via HTTP 854 status codes; see Section 7.4. 856 7.2.4. Client Behavior 858 7.2.4.1. Using Information Resources 860 This specification does not indicate any required actions taken by 861 ALTO Clients upon successfully receiving an Information Resource from 862 an ALTO Server. Although ALTO Clients are suggested to interpret the 863 received ALTO Information and adapt application behavior, ALTO 864 Clients are not required to do so. 866 7.2.4.2. Error Conditions 868 If an ALTO Client does not successfully receive a desired Information 869 Resource from a particular ALTO Server, it can either choose another 870 server (if one is available) or fall back to a default behavior 871 (e.g., perform peer selection without the use of ALTO information). 872 An ALTO Client may also retry the request at a later time. 874 7.2.5. Authentication and Encryption 876 An ALTO Server MAY support SSL/TLS to implement server and/or client 877 authentication, as well as encryption. See [RFC6125] for 878 considerations regarding verification of server identity. 880 7.2.6. HTTP Cookies 882 If cookies are included in an HTTP request received by an ALTO 883 Server, they MUST be ignored. 885 7.2.7. Parsing 887 This document only details object members used by this specification. 888 Extensions may include additional members within JSON objects defined 889 in this document. ALTO implementations MUST ignore such unknown 890 fields when processing ALTO messages. 892 7.3. Information Resource 894 An Information Resource is an HTTP entity body received by an ALTO 895 Server that encodes the ALTO Information desired by an ALTO Client. 897 This document specifies multiple Information Resources that can be 898 provided by an ALTO Server. Each Information Resource has certain 899 attributes associated with it, indicating its data format, the input 900 parameters it supports, and format of the input parameters. 902 7.3.1. Capabilities 904 An ALTO Server may advertise to an ALTO Client that it supports 905 certain capabilities in requests for an Information Resource. For 906 example, if an ALTO Server allows requests for a Cost Map to include 907 constraints, it may advertise that it supports this capability. 909 7.3.2. Input Parameters Media Type 911 An ALTO Server may allow an ALTO Client to supply input parameters 912 when requesting certain Information Resources. The format of the 913 input parameters (i.e., as contained in the entity body of the HTTP 914 POST request) is indicated by the media type [RFC2046]. 916 7.3.3. Media Type 918 The media type [RFC2046] uniquely indicates the data format of the 919 Information Resource as returned by an ALTO Server in the HTTP entity 920 body. 922 7.3.4. Encoding 924 Though each Information Resource may have a distinct syntax, they are 925 designed to have a common structure containing generic ALTO-layer 926 metadata about the resource, as well as data itself. 928 An Information Resource has a single top-level JSON object of type 929 InfoResourceEntity: 931 object { 932 InfoResourceMetaData meta; [OPTIONAL] 933 [InfoResourceDataType] data; 934 } InfoResourceEntity; 936 with members: 938 meta meta-information pertaining to the Information Resource 940 data the data contained in the Information Resource 942 7.3.4.1. Meta Information 944 Meta information is encoded as a JSON object. This document does not 945 specify any members, but it is defined here as a standard container 946 for extensibility. Specifically, InfoResourceMetaData is defined as: 948 object { 949 } InfoResourceMetaData; 951 7.3.4.2. ALTO Information 953 The "data" member of the InfoResourceEntity encodes the resource- 954 specific data; the structure of this member is detailed later in this 955 section for each particular Information Resource. 957 7.3.4.3. Example 959 The following is an example of the encoding for an Information 960 Resource: 962 HTTP/1.1 200 OK 963 Content-Length: [TODO] 964 Content-Type: application/alto-costmap+json 966 { 967 "meta" : {}, 968 "data" : { 969 ... 970 } 971 } 973 7.4. ALTO Errors 975 If there is an error processing a request, an ALTO Server SHOULD 976 return additional ALTO-layer information, if it is available, in the 977 form of an ALTO Error Resource encoded in the HTTP response's entity 978 body. 980 If no ALTO-layer information is available, an ALTO Server may omit an 981 ALTO Error resource from the response. An appropriate HTTP status 982 code MUST be set. 984 It is important to note that the HTTP Status Code and ALTO Error Code 985 have distinct roles. An ALTO Error Code provides detailed 986 information about the why a particular request for an ALTO Resource 987 was not successful. The HTTP status code indicates to HTTP 988 processing elements (e.g., intermediaries and clients) how the 989 response should be treated. 991 7.4.1. Media Type 993 The media type for an Error Resource is "application/ 994 alto-error+json". 996 7.4.2. Resource Format 998 An Error Resource has the format: 1000 object { 1001 JSONString code; 1002 JSONString reason; [OPTIONAL] 1003 } ErrorResourceEntity; 1005 where: 1007 code An ALTO Error Code defined in Table 1 1009 reason A (free-form) human-readable explanation of the particular 1010 error 1012 7.4.3. Error Codes 1014 This document defines ALTO Error Codes to support the error 1015 conditions needed for purposes of this document. Additional status 1016 codes may be defined in companion or extension documents. 1018 The HTTP status codes corresponding to each ALTO Error Code are 1019 defined to provide correct behavior with HTTP intermediaries and 1020 clients. When an ALTO Server returns a particular ALTO Error Code, 1021 it MUST indicate one of the corresponding HTTP status codes in 1022 Table 1in the HTTP response. 1024 If multiple errors are present in a single request (e.g., a request 1025 uses a JSONString when a JSONInteger is expected and a required field 1026 is missing), then the ALTO Server MUST return exactly one of the 1027 detected errors. However, the reported error is implementation 1028 defined, since specifying a particular order for message processing 1029 encroaches needlessly on implementation technique. 1031 +-------------------------+-------------+---------------------------+ 1032 | ALTO Error Code | HTTP Status | Description | 1033 | | Code(s) | | 1034 +-------------------------+-------------+---------------------------+ 1035 | E_SYNTAX | 400 | Parsing error in request | 1036 | | | (including identifiers) | 1037 | | | | 1038 | E_JSON_FIELD_MISSING | 400 | Required field missing | 1039 | | | | 1040 | E_JSON_VALUE_TYPE | 400 | JSON Value of unexpected | 1041 | | | type | 1042 | | | | 1043 | E_INVALID_COST_MODE | 400 | Invalid cost mode | 1044 | | | | 1045 | E_INVALID_COST_TYPE | 400 | Invalid cost type | 1046 | | | | 1047 | E_INVALID_PROPERTY_TYPE | 400 | Invalid property type | 1048 +-------------------------+-------------+---------------------------+ 1050 Table 1: Defined ALTO Error Codes 1052 7.5. ALTO Types 1054 This section details the format for particular data values used in 1055 the ALTO Protocol. 1057 7.5.1. PID Name 1059 A PID Name is encoded as a US-ASCII string. The string MUST be no 1060 more than 64 characters, and MUST NOT contain any ASCII character 1061 below 0x21 or above 0x7E or the '.' separator. The '.' separator is 1062 reserved for future use and MUST NOT be used unless specifically 1063 indicated by a companion or extension document. 1065 The type 'PIDName' is used in this document to indicate a string of 1066 this format. 1068 7.5.2. Version Tag 1070 A Version Tag is encoded as a US-ASCII string. The string MUST be no 1071 more than 64 characters, and MUST NOT contain any ASCII character 1072 below 0x21 or above 0x7E. 1074 The type 'VersionTag' is used in this document to indicate a string 1075 of this type. 1077 7.5.3. Endpoints 1079 This section defines formats used to encode addresses for Endpoints. 1080 In a case that multiple textual representations encode the same 1081 Endpoint address or prefix (within the guidelines outlined in this 1082 document), the ALTO Protocol does not require ALTO Clients or ALTO 1083 Servers to use a particular textual representation, nor does it 1084 require that ALTO Servers reply to requests using the same textual 1085 representation used by requesting ALTO Clients. ALTO Clients must be 1086 cognizant of this. 1088 7.5.3.1. Address Type 1090 Address Types are encoded as US-ASCII strings consisting of only 1091 alphanumeric characters. This document defines the address type 1092 "ipv4" to refer to IPv4 addresses, and "ipv6" to refer to IPv6 1093 addresses. Extension documents may define additional Address Types. 1095 The type 'AddressType' is used in this document to indicate a string 1096 of this format. 1098 7.5.3.2. Endpoint Address 1100 Endpoint Addresses are encoded as US-ASCII strings. The exact 1101 characters and format depend on the type of endpoint address. 1103 The type 'EndpointAddr' is used in this document to indicate a string 1104 of this format. 1106 7.5.3.2.1. IPv4 1108 IPv4 Endpoint Addresses are encoded as specified by the 'IPv4address' 1109 rule in Section 3.2.2 of [RFC3986]. 1111 7.5.3.2.2. IPv6 1113 IPv6 Endpoint Addresses are encoded as specified in Section 4 of 1114 [RFC5952]. 1116 7.5.3.2.3. Typed Endpoint Addresses 1118 When an Endpoint Address is used, an ALTO implementation must be able 1119 to determine its type. For this purpose, the ALTO Protocol allows 1120 endpoint addresses to also explicitly indicate their type. 1122 Typed Endpoint Addresses are encoded as US-ASCII strings of the 1123 format 'AddressType:EndpointAddr' (with the ':' character as a 1124 separator). The type 'TypedEndpointAddr' is used to indicate a 1125 string of this format. 1127 7.5.3.3. Endpoint Prefixes 1129 For efficiency, it is useful to denote a set of Endpoint Addresses 1130 using a special notation (if one exists). This specification makes 1131 use of the prefix notations for both IPv4 and IPv6 for this purpose. 1133 Endpoint Prefixes are encoded as US-ASCII strings. The exact 1134 characters and format depend on the type of endpoint address. 1136 The type 'EndpointPrefix' is used in this document to indicate a 1137 string of this format. 1139 7.5.3.3.1. IPv4 1141 IPv4 Endpoint Prefixes are encoded as specified in Section 3.1 of 1142 [RFC4632]. 1144 7.5.3.3.2. IPv6 1146 IPv6 Endpoint Prefixes are encoded as specified in Section 7 of 1147 [RFC5952]. 1149 7.5.3.4. Endpoint Address Group 1151 The ALTO Protocol includes messages that specify potentially large 1152 sets of endpoint addresses. Endpoint Address Groups provide a more 1153 efficient way to encode such sets, even when the set contains 1154 endpoint addresses of different types. 1156 An Endpoint Address Group is defined as: 1158 object { 1159 EndpointPrefix [AddressType]<0..*>; 1160 ... 1161 } EndpointAddrGroup; 1163 In particular, an Endpoint Address Group is a JSON object with the 1164 name of each member being the string corresponding to the address 1165 type, and the member's corresponding value being a list of prefixes 1166 of addresses of that type. 1168 The following is an example with both IPv4 and IPv6 endpoint 1169 addresses: 1171 { 1172 "ipv4": [ 1173 "192.0.2.0/24", 1174 "198.51.100.0/25" 1175 ], 1176 "ipv6": [ 1177 "2001:db8:0:1::/64", 1178 "2001:db8:0:2::/64" 1179 ] 1180 } 1182 7.5.4. Cost Mode 1184 A Cost Mode is encoded as a US-ASCII string. The string MUST either 1185 have the value 'numerical' or 'ordinal'. 1187 The type 'CostMode' is used in this document to indicate a string of 1188 this format. 1190 7.5.5. Cost Type 1192 A Cost Type is encoded as a US-ASCII string. The string MUST be no 1193 more than 32 characters, and MUST NOT contain characters other than 1194 alphanumeric characters, the hyphen ('-'), or the ':' separator. 1196 Identifiers prefixed with 'priv:' are reserved for Private Use 1197 [RFC5226]. Identifiers prefixed with 'exp:' are reserved for 1198 Experimental use. All other identifiers appearing in an HTTP request 1199 or response with an 'application/alto-*' media type MUST be 1200 registered in the ALTO Cost Types registry Section 10.2. 1202 The type 'CostType' is used in this document to indicate a string of 1203 this format. 1205 7.5.6. Endpoint Property 1207 An Endpoint Property is encoded as a US-ASCII string. The string 1208 MUST be no more than 32 characters, and MUST NOT contain characters 1209 other than alphanumeric characters, the hyphen ('-'), or the ':' 1210 separator. 1212 Identifiers prefixed with 'priv:' are reserved for Private Use 1213 [RFC5226]. Identifiers prefixed with 'exp:' are reserved for 1214 Experimental use. All other identifiers appearing in an HTTP request 1215 or response with an 'application/alto-*' media type MUST be 1216 registered in the ALTO Endpoint Property registry Section 10.3. 1218 The type 'EndpointProperty' is used in this document to indicate a 1219 string of this format. 1221 7.6. Information Resource Directory 1223 An Information Resource Directory indicates to ALTO Clients which 1224 Information Resources are made available by an ALTO Server. 1226 Since resource selection happens after consumption of the Information 1227 Resource Directory, the format of the Information Resource Directory 1228 is designed to be simple with the intention of future ALTO Protocol 1229 versions maintaining backwards compatibility. Future extensions or 1230 versions of the ALTO Protocol SHOULD be accomplished by extending 1231 existing media types or adding new media types, but retaining the 1232 same format for the Information Resource Directory. 1234 An ALTO Server MUST make an Information Resource Directory available 1235 via the HTTP GET method to a URI discoverable by an ALTO Client. 1236 Discovery of this URI is out of scope of this document, but could be 1237 accomplished by manual configuration or by returning the URI of an 1238 Information Resource Directory from the ALTO Discovery Protocol 1239 [I-D.ietf-alto-server-discovery]. 1241 7.6.1. Media Type 1243 The media type is "application/alto-directory+json". 1245 7.6.2. Encoding 1247 An Information Resource Directory is a JSON object of type 1248 InfoResourceDirectory: 1250 object { 1251 ... 1252 } Capabilities; 1254 object { 1255 JSONString uri; 1256 JSONString media-types<1..*>; 1257 JSONString accepts<0..*>; [OPTIONAL] 1258 Capabilities capabilities; [OPTIONAL] 1259 } ResourceEntry; 1261 object { 1262 ResourceEntry resources<0..*>; 1263 } InfoResourceDirectory; 1264 where the "resources" array indicates a list of Information Resources 1265 provided by an ALTO Server. Note that the list of available 1266 resources is enclosed in a JSON object for extensibility; future 1267 protocol versions may specify additional members in the 1268 InfoResourceDirectory object. 1270 Any URI endpoint indicated in an Information Resource Directory MAY 1271 provide a response to an OPTIONS request that is in the format of an 1272 Information Resource Directory. This provides ALTO Clients a means 1273 to discover resources and capabilities offered by that URI endpoint. 1274 ALTO Servers that reply with an HTTP 300 status code ("Multiple 1275 Choices") SHOULD use the Information Resource Directory format in the 1276 reply. 1278 Each entry in the directory specifies: 1280 uri A URI at which the ALTO Server provides one or more Information 1281 Resources, or an Information Resource Directory indicating 1282 additional Information Resources. 1284 media-types The list of all media types of Information Resources 1285 (see Section 7.3.3) available via GET or POST requests to the 1286 corresponding URI or URIs discoverable via the URI. 1288 accepts The list of all media types of input parameters (see 1289 Section 7.3.2) accepted by POST requests to the corresponding URI 1290 or URIs discoverable via the URI. If this member is not present, 1291 it MUST be assumed to be an empty array. 1293 capabilities A JSON Object enumerating capabilities of an ALTO 1294 Server in providing the Information Resource at the corresponding 1295 URI and Information Resources discoverable via the URI. If this 1296 member is not present, it MUST be assumed to be an empty array. 1297 If a capability for one of the offered Information Resources is 1298 not explicitly listed here, an ALTO Client may either issue an 1299 OPTIONS HTTP request to the corresponding URI to determine if the 1300 capability is supported, or assume its default value. 1302 If an entry has an empty list for "accepts", then the corresponding 1303 URI MUST support GET requests. If an entry has a non-empty list for 1304 "accepts", then the corresponding URI MUST support POST requests. If 1305 an ALTO Server wishes to support both GET and POST on a single URI, 1306 it MUST specify two entries in the Information Resource Directory. 1308 7.6.3. Example 1310 The following is an example Information Resource Directory returned 1311 by an ALTO Server. In this example, the ALTO Server provides 1312 additional Network and Cost Maps via a separate subdomain, 1313 "custom.alto.example.com". The maps available via this subdomain are 1314 Filtered Network and Cost Maps as well as pre-generated maps for the 1315 "hopcount" and "routingcost" Cost Types in the "ordinal" Cost Mode. 1317 An ALTO Client can discover the maps available by 1318 "custom.alto.example.com" by successfully performing an OPTIONS 1319 request to "http://custom.alto.example.com/maps". 1321 GET /directory HTTP/1.1 1322 Host: alto.example.com 1323 Accept: application/alto-directory+json,application/alto-error+json 1325 HTTP/1.1 200 OK 1326 Content-Length: [TODO] 1327 Content-Type: application/alto-directory+json 1329 { 1330 "resources" : [ 1331 { 1332 "uri" : "http://alto.example.com/serverinfo", 1333 "media-types" : [ "application/alto-serverinfo+json" ] 1334 }, { 1335 "uri" : "http://alto.example.com/networkmap", 1336 "media-types" : [ "application/alto-networkmap+json" ] 1337 }, { 1338 "uri" : "http://alto.example.com/costmap/num/routingcost", 1339 "media-types" : [ "application/alto-costmap+json" ], 1340 "capabilities" : { 1341 "cost-modes" : [ "numerical" ], 1342 "cost-types" : [ "routingcost" ] 1343 } 1344 }, { 1345 "uri" : "http://alto.example.com/costmap/num/hopcount", 1346 "media-types" : [ "application/alto-costmap+json" ], 1347 "capabilities" : { 1348 "cost-modes" : [ "numerical" ], 1349 "cost-types" : [ "hopcount" ] 1350 } 1351 }, { 1352 "uri" : "http://custom.alto.example.com/maps", 1353 "media-types" : [ 1354 "application/alto-networkmap+json", 1355 "application/alto-costmap+json" 1357 ], 1358 "accepts" : [ 1359 "application/alto-networkmapfilter+json", 1360 "application/alto-costmapfilter+json" 1361 ] 1362 }, { 1363 "uri" : "http://alto.example.com/endpointprop/lookup", 1364 "media-types" : [ "application/alto-endpointprop+json" ], 1365 "accepts" : [ "application/alto-endpointpropparams+json" ], 1366 "capabilities" : { 1367 "prop-types" : [ "pid" ] 1368 } 1369 }, { 1370 "uri" : "http://alto.example.com/endpointcost/lookup", 1371 "media-types" : [ "application/alto-endpointcost+json" ], 1372 "accepts" : [ "application/alto-endpointcostparams+json" ], 1373 "capabilities" : { 1374 "cost-constraints" : true, 1375 "cost-modes" : [ "ordinal", "numerical" ], 1376 "cost-types" : [ "routingcost", "hopcount" ] 1377 } 1378 } 1379 ] 1380 } 1382 OPTIONS /maps HTTP/1.1 1383 Host: custom.alto.example.com 1384 Accept: application/alto-directory+json,application/alto-error+json 1385 HTTP/1.1 200 OK 1386 Content-Length: [TODO] 1387 Content-Type: application/alto-directory+json 1389 { 1390 "resources" : [ 1391 { 1392 "uri" : "http://custom.alto.example.com/networkmap/filtered", 1393 "media-types" : [ "application/alto-networkmap+json" ], 1394 "accepts" : [ "application/alto-networkmapfilter+json" ] 1395 }, { 1396 "uri" : "http://custom.alto.example.com/costmap/filtered", 1397 "media-types" : [ "application/alto-costmap+json" ], 1398 "accepts" : [ "application/alto-costmapfilter+json" ], 1399 "capabilities" : { 1400 "cost-constraints" : true, 1401 "cost-modes" : [ "ordinal", "numerical" ], 1402 "cost-types" : [ "routingcost", "hopcount" ] 1403 } 1404 }, { 1405 "uri" : "http://custom.alto.example.com/ord/routingcost", 1406 "media-types" : [ "application/alto-costmap+json" ], 1407 "capabilities" : { 1408 "cost-modes" : [ "ordinal" ], 1409 "cost-types" : [ "routingcost" ] 1410 } 1411 }, { 1412 "uri" : "http://custom.alto.example.com/ord/hopcount", 1413 "media-types" : [ "application/alto-costmap+json" ], 1414 "capabilities" : { 1415 "cost-modes" : [ "ordinal" ], 1416 "cost-types" : [ "hopcount" ] 1417 } 1418 } 1419 ] 1420 } 1422 7.6.4. Usage Considerations 1424 7.6.4.1. ALTO Client 1426 This document specifies no requirements or constraints on ALTO 1427 Clients with regards to how they process an Information Resource 1428 Directory to identify the URI corresponding to a desired Information 1429 Resource. However, some advice is provided for implementors. 1431 It is possible that multiple entries in the directory match a desired 1432 Information Resource. For instance, in the example in Section 7.6.3, 1433 a full Cost Map with "numerical" Cost Mode and "routingcost" Cost 1434 Type could be retrieved via a GET request to 1435 "http://alto.example.com/costmap/num/routingcost", or via a POST 1436 request to "http://custom.alto.example.com/costmap/filtered". 1438 In general, it is preferred for ALTO Clients to use GET requests 1439 where appropriate, since it is more likely for responses to be 1440 cacheable. 1442 7.6.4.2. ALTO Server 1444 This document indicates that an ALTO Server may or may not provide 1445 the Information Resources specified in the Map Filtering Service. If 1446 these resources are not provided, it is indicated to an ALTO Client 1447 by the absence of a Network Map or Cost Map with any media types 1448 listed under "accepts". 1450 7.7. Information Resources 1452 This section documents the individual Information Resources defined 1453 in the ALTO Protocol. 1455 7.7.1. Map Service 1457 The Map Service provides batch information to ALTO Clients in the 1458 form of two types of maps: a Network Map and Cost Map. 1460 7.7.1.1. Network Map 1462 The Network Map Information Resource lists for each PID, the network 1463 locations (endpoints) within the PID. It MUST be provided by an ALTO 1464 Server. 1466 7.7.1.1.1. Media Type 1468 The media type is "application/alto-networkmap+json". 1470 7.7.1.1.2. HTTP Method 1472 This resource is requested using the HTTP GET method. 1474 7.7.1.1.3. Input Parameters 1476 None. 1478 7.7.1.1.4. Capabilities 1480 None. 1482 7.7.1.1.5. Response 1484 The returned InfoResourceEntity object "data" member of type 1485 InfoResourceNetworkMap: 1487 object { 1488 EndpointAddrGroup [pidname]<0..*>; 1489 ... 1490 } NetworkMapData; 1492 object { 1493 VersionTag map-vtag; 1494 NetworkMapData map; 1495 } InfoResourceNetworkMap; 1497 with members: 1499 map-vtag The Version Tag (Section 5.3) of the Network Map. 1501 map The Network Map data itself. 1503 NetworkMapData is a JSON object with each member representing a 1504 single PID and its associated set of endpoint addresses. A member's 1505 name is a string of type PIDName. 1507 The returned Network Map MUST include all PIDs known to the ALTO 1508 Server. 1510 7.7.1.1.6. Example 1512 GET /networkmap HTTP/1.1 1513 Host: alto.example.com 1514 Accept: application/alto-networkmap+json,application/alto-error+json 1515 HTTP/1.1 200 OK 1516 Content-Length: [TODO] 1517 Content-Type: application/alto-networkmap+json 1519 { 1520 "meta" : {}, 1521 "data" : { 1522 "map-vtag" : "1266506139", 1523 "map" : { 1524 "PID1" : { 1525 "ipv4" : [ 1526 "192.0.2.0/24", 1527 "198.51.100.0/25" 1528 ] 1529 }, 1530 "PID2" : { 1531 "ipv4" : [ 1532 "198.51.100.128/25" 1533 ] 1534 }, 1535 "PID3" : { 1536 "ipv4" : [ 1537 "0.0.0.0/0" 1538 ], 1539 "ipv6" : [ 1540 "::/0" 1541 ] 1542 } 1543 } 1544 } 1545 } 1547 7.7.1.2. Cost Map 1549 The Cost Map resource lists the Path Cost for each pair of source/ 1550 destination PID defined by the ALTO Server for a given Cost Type and 1551 Cost Mode. This resource MUST be provided for at least the 1552 'routingcost' Cost Type and 'numerical' Cost Mode. 1554 Note that since this resource, an unfiltered Cost Map requested by an 1555 HTTP GET, does not indicate the desired Cost Mode or Cost Type as 1556 input parameters, an ALTO Server MUST indicate in an Information 1557 Resource Directory a unfiltered Cost Map Information Resource by 1558 specifying the capabilities (Section 7.7.1.2.4) with "cost-types" and 1559 "cost-modes" members each having a single element. This technique 1560 will allow an ALTO Client to determine a URI for an unfiltered Cost 1561 Map of the desired Cost Mode and Cost Type. 1563 7.7.1.2.1. Media Type 1565 The media type is "application/alto-costmap+json". 1567 7.7.1.2.2. HTTP Method 1569 This resource is requested using the HTTP GET method. 1571 7.7.1.2.3. Input Parameters 1573 None. 1575 7.7.1.2.4. Capabilities 1577 This resource may be defined for across multiple Cost Types and Cost 1578 Modes. The capabilities of an ALTO Server URI providing this 1579 resource are defined by a JSON Object of type CostMapCapability: 1581 object { 1582 CostMode cost-modes<0..*>; 1583 CostType cost-types<0..*>; 1584 } CostMapCapability; 1586 with members: 1588 cost-modes The Cost Modes ( Section 5.1.2) supported by the 1589 corresponding URI. If not present, this member MUST be 1590 interpreted as an empty array. 1592 cost-types The Cost Types ( Section 5.1.1) supported by the 1593 corresponding URI. If not present, this member MUST be 1594 interpreted as an empty array. 1596 An ALTO Server MUST support all of the Cost Types listed here for 1597 each of the listed Cost Modes. Note that an ALTO Server may provide 1598 multiple Cost Map Information Resources, each with different 1599 capabilities. 1601 7.7.1.2.5. Response 1603 The returned InfoResourceEntity object has "data" member of type 1604 InfoResourceCostMap: 1606 object DstCosts { 1607 JSONValue [PIDName]; 1608 ... 1609 }; 1611 object { 1612 DstCosts [PIDName]<0..*>; 1613 ... 1614 } CostMapData; 1616 object { 1617 CostMode cost-mode; 1618 CostType cost-type; 1619 VersionTag map-vtag; 1620 CostMapData map; 1621 } InfoResourceCostMap; 1623 with members: 1625 cost-mode Cost Mode (Section 5.1.2) used in the Cost Map. 1627 cost-type Cost Type (Section 5.1.1) used in the Cost Map. 1629 map-vtag The Version Tag (Section 5.3) of the Network Map used to 1630 generate the Cost Map. 1632 map The Cost Map data itself. 1634 CostMapData is a JSON object with each member representing a single 1635 Source PID; the name for a member is the PIDName string identifying 1636 the corresponding Source PID. For each Source PID, a DstCosts object 1637 denotes the associated cost to a set of destination PIDs ( 1638 Section 5.2); the name for each member in the object is the PIDName 1639 string identifying the corresponding Destination PID. An 1640 implementation of the protocol in this document SHOULD assume that 1641 the cost is a JSONNumber and fail to parse if it is not, unless the 1642 implementation is using an extensions to this document that indicates 1643 when and how costs of other data types are signaled. 1645 The returned Cost Map MUST include the Path Cost for each (Source 1646 PID, Destination PID) pair for which a Path Cost is defined. An ALTO 1647 Server MAY omit entries for which a Path Cost is not defined (e.g., 1648 both the Source and Destination PIDs contain addresses outside of the 1649 Network Provider's administrative domain). 1651 7.7.1.2.6. Example 1653 GET /costmap/num/routingcost HTTP/1.1 1654 Host: alto.example.com 1655 Accept: application/alto-costmap+json,application/alto-error+json 1657 HTTP/1.1 200 OK 1658 Content-Length: [TODO] 1659 Content-Type: application/alto-costmap+json 1661 { 1662 "meta" : {}, 1663 "data" : { 1664 "cost-mode" : "numerical", 1665 "cost-type" : "routingcost", 1666 "map-vtag" : "1266506139", 1667 "map" : { 1668 "PID1": { "PID1": 1, "PID2": 5, "PID3": 10 }, 1669 "PID2": { "PID1": 5, "PID2": 1, "PID3": 15 }, 1670 "PID3": { "PID1": 20, "PID2": 15 } 1671 } 1672 } 1673 } 1675 7.7.2. Map Filtering Service 1677 The Map Filtering Service allows ALTO Clients to specify filtering 1678 criteria to return a subset of the full maps available in the Map 1679 Service. 1681 7.7.2.1. Filtered Network Map 1683 A Filtered Network Map is a Network Map Information Resource 1684 (Section 7.7.1.1) for which an ALTO Client may supply a list of PIDs 1685 to be included. A Filtered Network Map MAY be provided by an ALTO 1686 Server. 1688 7.7.2.1.1. Media Type 1690 See Section 7.7.1.1.1. 1692 7.7.2.1.2. HTTP Method 1694 This resource is requested using the HTTP POST method. 1696 7.7.2.1.3. Input Parameters 1698 Input parameters are supplied in the entity body of the POST request. 1699 This document specifies the input parameters with a data format 1700 indicated by the media type "application/alto-networkmapfilter+json", 1701 which is a JSON Object of type ReqFilteredNetworkMap, where: 1703 object { 1704 PIDName pids<0..*>; 1705 AddressType address-types<0..*>; 1706 } ReqFilteredNetworkMap; 1708 with members: 1710 pids Specifies list of PIDs to be included in the returned Filtered 1711 Network Map. If the list of PIDs is empty, the ALTO Server MUST 1712 interpret the list as if it contained a list of all currently- 1713 defined PIDs. The ALTO Server MUST interpret entries appearing 1714 multiple times as if they appeared only once. 1716 address-types Specifies list of address types to be included in the 1717 returned Filtered Network Map. If the list of address types is 1718 empty, the ALTO Server MUST interpret the list as if it contained 1719 a list of all address types known to the ALTO Server. The ALTO 1720 Server MUST interpret entries appearing multiple times as if they 1721 appeared only once. 1723 7.7.2.1.4. Capabilities 1725 None. 1727 7.7.2.1.5. Response 1729 See Section 7.7.1.1.5 for the format. 1731 The ALTO Server MUST only include PIDs in the response that were 1732 specified (implicitly or explicitly) in the request. If the input 1733 parameters contain a PID name that is not currently defined by the 1734 ALTO Server, the ALTO Server MUST behave as if the PID did not appear 1735 in the input parameters. Similarly, the ALTO Server MUST only 1736 enumerate addresses within each PID that have types which were 1737 specified (implicitly or explicitly) in the request. If the input 1738 parameters contain an address type that is not currently known to the 1739 ALTO Server, the ALTO Server MUST behave as if the address type did 1740 not appear in the input parameters. 1742 7.7.2.1.6. Example 1744 POST /networkmap/filtered HTTP/1.1 1745 Host: custom.alto.example.com 1746 Content-Length: [TODO] 1747 Content-Type: application/alto-networkmapfilter+json 1748 Accept: application/alto-networkmap+json,application/alto-error+json 1750 { 1751 "pids": [ "PID1", "PID2" ] 1752 } 1754 HTTP/1.1 200 OK 1755 Content-Length: [TODO] 1756 Content-Type: application/alto-networkmap+json 1758 { 1759 "meta" : {}, 1760 "data" : { 1761 "map-vtag" : "1266506139", 1762 "map" : { 1763 "PID1" : { 1764 "ipv4" : [ 1765 "192.0.2.0/24", 1766 "198.51.100.0/24" 1767 ] 1768 }, 1769 "PID2" : { 1770 "ipv4": [ 1771 "198.51.100.128/24" 1772 ] 1773 } 1774 } 1775 } 1776 } 1778 7.7.2.2. Filtered Cost Map 1780 A Filtered Cost Map is a Cost Map Information Resource 1781 (Section 7.7.1.2) for which an ALTO Client may supply additional 1782 parameters limiting the scope of the resulting Cost Map. A Filtered 1783 Cost Map MAY be provided by an ALTO Server. 1785 7.7.2.2.1. Media Type 1787 See Section 7.7.1.2.1. 1789 7.7.2.2.2. HTTP Method 1791 This resource is requested using the HTTP POST method. 1793 7.7.2.2.3. Input Parameters 1795 Input parameters are supplied in the entity body of the POST request. 1796 This document specifies the input parameters with a data format 1797 indicated by the media type "application/alto-costmapfilter+json", 1798 which is a JSON Object of type ReqFilteredCostMap, where: 1800 object { 1801 PIDName srcs<0..*>; 1802 PIDName dsts<0..*>; 1803 } PIDFilter; 1805 object { 1806 CostMode cost-mode; 1807 CostType cost-type; 1808 JSONString constraints<0..*>; [OPTIONAL] 1809 PIDFilter pids; [OPTIONAL] 1810 } ReqFilteredCostMap; 1812 with members: 1814 cost-type The Cost Type ( Section 5.1.1) for the returned costs. 1815 This MUST be one of the supported Cost Types indicated in this 1816 resource's capabilities ( Section 7.7.2.2.4). 1818 cost-mode The Cost Mode ( Section 5.1.2) for the returned costs. 1819 This MUST be one of the supported Cost Modes indicated in this 1820 resource's capabilities ( Section 7.7.2.2.4). 1822 constraints Defines a list of additional constraints on which 1823 elements of the Cost Map are returned. This parameter MUST NOT be 1824 specified if this resource's capabilities ( Section 7.7.2.2.4) 1825 indicate that constraint support is not available. A constraint 1826 contains two entities separated by whitespace: (1) an operator, 1827 'gt' for greater than, 'lt' for less than, 'ge' for greater than 1828 or equal to, 'le' for less than or equal to, or 'eq' for equal to 1829 (2) a target numerical cost. The numerical cost is a number that 1830 MUST be defined in the same units as the Cost Type indicated by 1831 the cost-type parameter. ALTO Servers SHOULD use at least IEEE 1832 754 double-precision floating point [IEEE.754.2008] to store the 1833 numerical cost, and SHOULD perform internal computations using 1834 double-precision floating-point arithmetic. If multiple 1835 'constraint' parameters are specified, they are interpreted as 1836 being related to each other with a logical AND. 1838 pids A list of Source PIDs and a list of Destination PIDs for which 1839 Path Costs are to be returned. If a list is empty, the ALTO 1840 Server MUST interpret it as the full set of currently-defined 1841 PIDs. The ALTO Server MUST interpret entries appearing in a list 1842 multiple times as if they appeared only once. If the "pids" 1843 member is not present, both lists MUST be interpreted by the ALTO 1844 Server as containing the full set of currently-defined PIDs. 1846 7.7.2.2.4. Capabilities 1848 The URI providing this resource supports all capabilities documented 1849 in Section 7.7.1.2.4 (with identical semantics), plus additional 1850 capabilities. In particular, the capabilities are defined by a JSON 1851 object of type FilteredCostMapCapability: 1853 object { 1854 CostMode cost-modes<0..*>; 1855 CostType cost-types<0..*>; 1856 JSONBool cost-constraints; 1857 } FilteredCostMapCapability; 1859 with members: 1861 cost-modes See Section 7.7.1.2.4. 1863 cost-types See Section 7.7.1.2.4. 1865 cost-constraints If true, then the ALTO Server allows cost 1866 constraints to be included in requests to the corresponding URI. 1867 If not present, this member MUST be interpreted as if it specified 1868 false. ALTO Clients should be aware that constraints may not have 1869 the intended effect for cost maps with the 'ordinal' Cost Mode 1870 since ordinal costs are not restricted to being sequential 1871 integers. 1873 7.7.2.2.5. Response 1875 See Section 7.7.1.2.5 for the format. 1877 The returned Cost Map MUST NOT contain any source/destination pair 1878 that was not indicated (implicitly or explicitly) in the input 1879 parameters. If the input parameters contain a PID name that is not 1880 currently defined by the ALTO Server, the ALTO Server MUST behave as 1881 if the PID did not appear in the input parameters. 1883 If any constraints are specified, Source/Destination pairs for which 1884 the Path Costs do not meet the constraints MUST NOT be included in 1885 the returned Cost Map. If no constraints were specified, then all 1886 Path Costs are assumed to meet the constraints. 1888 Note that ALTO Clients should verify that the Version Tag included in 1889 the response is consistent with the Version Tag of the Network Map 1890 used to generate the request (if applicable). If it is not, the ALTO 1891 Client may wish to request an updated Network Map, identify changes, 1892 and consider requesting a new Filtered Cost Map. 1894 7.7.2.2.6. Example 1896 POST /costmap/filtered HTTP/1.1 1897 Host: custom.alto.example.com 1898 Content-Type: application/alto-costmapfilter+json 1899 Accept: application/alto-costmap+json,application/alto-error+json 1901 { 1902 "cost-mode" : "numerical", 1903 "cost-type" : "routingcost", 1904 "pids" : { 1905 "srcs" : [ "PID1" ], 1906 "dsts" : [ "PID1", "PID2", "PID3" ] 1907 } 1908 } 1910 HTTP/1.1 200 OK 1911 Content-Length: [TODO] 1912 Content-Type: application/alto-costmap+json 1914 { 1915 "meta" : {}, 1916 "data" : { 1917 "cost-mode" : "numerical", 1918 "cost-type" : "routingcost", 1919 "map-vtag" : "1266506139", 1920 "map" : { 1921 "PID1": { "PID1": 0, "PID2": 1, "PID3": 2 } 1922 } 1923 } 1924 } 1926 7.7.3. Endpoint Property Service 1928 The Endpoint Property Service provides information about Endpoint 1929 properties to ALTO Clients. 1931 7.7.3.1. Endpoint Property 1933 The Endpoint Property resource provides information about properties 1934 for individual endpoints. It MAY be provided by an ALTO Server. If 1935 an ALTO Server provides the Endpoint Property resource, it MUST 1936 provide and define at least the 'pid' property for each Endpoint. 1938 7.7.3.1.1. Media Type 1940 The media type is "application/alto-endpointprop+json". 1942 7.7.3.1.2. HTTP Method 1944 This resource is requested using the HTTP POST method. 1946 7.7.3.1.3. Input Parameters 1948 Input parameters are supplied in the entity body of the POST request. 1949 This document specifies the data format of input parameteres with the 1950 media type "application/alto-endpointpropparams+json", which is a 1951 JSON Object of type ReqEndpointProp: 1953 object { 1954 EndpointProperty properties<1..*>; 1955 TypedEndpointAddr endpoints<1..*>; 1956 } ReqEndpointProp; 1958 with members: 1960 properties List of endpoint properties to returned for each 1961 endpoint. Each specified property MUST be included in the list of 1962 supported properties indicated by this resource's capabilities ( 1963 Section 7.7.3.1.4). The ALTO Server MUST interpret entries 1964 appearing multiple times as if they appeared only once. 1966 endpoints List of endpoint addresses for which the specified 1967 properties are to be returned. The ALTO Server MUST interpret 1968 entries appearing multiple times as if they appeared only once. 1970 7.7.3.1.4. Capabilities 1972 This resource may be defined across multiple types of endpoint 1973 properties. The capabilities of an ALTO Server URI providing 1974 Endpoint Properties are defined by a JSON Object of type 1975 EndpointPropertyCapability: 1977 object { 1978 EndpointProperty prop-types<0..*>; 1979 } EndpointPropertyCapability; 1981 with members: 1983 prop-types The Endpoint Property Types ( Section 3.1.3) supported by 1984 the corresponding URI. If not present, this member MUST be 1985 interpreted as an empty array. 1987 7.7.3.1.5. Response 1989 The returned InfoResourceEntity object has "data" member of type 1990 InfoResourceEndpointProperty, where: 1992 object { 1993 JSONString [EndpointProperty]; 1994 ... 1995 } EndpointProps; 1997 object { 1998 VersionTag map-vtag; [OPTIONAL] 1999 EndpointProps [TypedEndpointAddr]<0..*>; 2000 ... 2001 } InfoResourceEndpointProperty; 2003 InfoResourceEndpointProperty has one member for each endpoint 2004 indicated in the input parameters (with the name being the endpoint 2005 encoded as a TypedEndpointAddr). The requested properties for each 2006 endpoint are encoded in a corresponding EndpointProps object, which 2007 encodes one name/value pair for each requested property, where the 2008 property names are encoded as strings of type EndpointProperty and 2009 the property values encoded as JSON Strings. 2011 The ALTO Server returns the value for each of the requested endpoint 2012 properties for each of the endpoints listed in the input parameters. 2014 If the ALTO Server does not define a requested property for a 2015 particular endpoint, then it MUST omit it from the response for only 2016 that endpoint. 2018 The ALTO Server MAY include the Version Tag (Section 5.3) of the 2019 Network Map used to generate the response (if desired and applicable) 2020 as the 'map-vtag' member in the response. If the 'pid' property is 2021 returned for any endpoints in the response, the 'map-vtag' member is 2022 REQUIRED instead of OPTIONAL. 2024 7.7.3.1.6. Example 2026 POST /endpointprop/lookup HTTP/1.1 2027 Host: alto.example.com 2028 Content-Length: [TODO] 2029 Content-Type: application/alto-endpointpropparams+json 2030 Accept: application/alto-endpointprop+json,application/alto-error+json 2032 { 2033 "properties" : [ "pid" ], 2034 "endpoints" : [ "ipv4:192.0.2.34", "ipv4:203.0.113.129" ] 2035 } 2037 HTTP/1.1 200 OK 2038 Content-Length: [TODO] 2039 Content-Type: application/alto-endpointprop+json 2041 { 2042 "meta" : {}, 2043 "data": { 2044 "ipv4:192.0.2.34" : { "pid": "PID1" }, 2045 "ipv4:203.0.113.129" : { "pid": "PID3" } 2046 } 2047 } 2049 7.7.4. Endpoint Cost Service 2051 The Endpoint Cost Service provides information about costs between 2052 individual endpoints. 2054 In particular, this service allows lists of Endpoint prefixes (and 2055 addresses, as a special case) to be ranked (ordered) by an ALTO 2056 Server. 2058 7.7.4.1. Endpoint Cost 2060 The Endpoint Cost resource provides information about costs between 2061 individual endpoints. It MAY be provided by an ALTO Server. 2063 It is important to note that although this resource allows an ALTO 2064 Server to reveal costs between individual endpoints, an ALTO Server 2065 is not required to do so. A simple alternative would be to compute 2066 the cost between two endpoints as the cost between the PIDs 2067 corresponding to the endpoints. See Section 11.1 for additional 2068 details. 2070 7.7.4.1.1. Media Type 2072 The media type is "application/alto-endpointcost+json". 2074 7.7.4.1.2. HTTP Method 2076 This resource is requested using the HTTP POST method. 2078 7.7.4.1.3. Input Parameters 2080 Input parameters are supplied in the entity body of the POST request. 2081 This document specifies input parameters with a data format indicated 2082 by media type "application/alto-endpointcostparams+json", which is a 2083 JSON Object of type ReqEndpointCostMap: 2085 object { 2086 TypedEndpointAddr srcs<0..*>; [OPTIONAL] 2087 TypedEndpointAddr dsts<1..*>; 2088 } EndpointFilter; 2090 object { 2091 CostMode cost-mode; 2092 CostType cost-type; 2093 JSONString constraints; [OPTIONAL] 2094 EndpointFilter endpoints; 2095 } ReqEndpointCostMap; 2097 with members: 2099 cost-mode The Cost Mode ( Section 5.1.2) to use for returned costs. 2100 This MUST be one of the Cost Modes indicated in this resource's 2101 capabilities ( Section 7.7.4.1.4). 2103 cost-type The Cost Type ( Section 5.1.1) to use for returned costs. 2104 This MUST be one of the Cost Types indicated in this resource's 2105 capabilities ( Section 7.7.4.1.4). 2107 constraints Defined equivalently to the "constraints" input 2108 parameter of a Filtered Cost Map (see Section 7.7.2.2). 2110 endpoints A list of Source Endpoints and Destination Endpoints for 2111 which Path Costs are to be returned. If the list of Source 2112 Endpoints is empty (or not included), the ALTO Server MUST 2113 interpret it as if it contained the Endpoint Address corresponding 2114 to the client IP address from the incoming connection (see 2115 Section 9.3 for discussion and considerations regarding this 2116 mode). The list of destination Endpoints MUST NOT be empty. The 2117 ALTO Server MUST interpret entries appearing multiple times in a 2118 list as if they appeared only once. 2120 7.7.4.1.4. Capabilities 2122 See Section 7.7.2.2.4. 2124 7.7.4.1.5. Response 2126 The returned InfoResourceEntity object has "data" member equal to 2127 InfoResourceEndpointCostMap, where: 2129 object EndpointDstCosts { 2130 JSONValue [TypedEndpointAddr]; 2131 ... 2132 }; 2134 object { 2135 EndpointDstCosts [TypedEndpointAddr]<0..*>; 2136 ... 2137 } EndpointCostMapData; 2139 object { 2140 CostMode cost-mode; 2141 CostType cost-type; 2142 EndpointCostMapData map; 2143 } InfoResourceEndpointCostMap; 2145 InfoResourceEndpointCostMap has members: 2147 cost-mode The Cost Mode used in the returned Cost Map. 2149 cost-type The Cost Type used in the returned Cost Map. 2151 map The Endpoint Cost Map data itself. 2153 EndpointCostMapData is a JSON object with each member representing a 2154 single Source Endpoint specified in the input parameters; the name 2155 for a member is the TypedEndpointAddr string identifying the 2156 corresponding Source Endpoint. For each Source Endpoint, a 2157 EndpointDstCosts object denotes the associated cost to each 2158 Destination Endpoint specified in the input parameters; the name for 2159 each member in the object is the TypedEndpointAddr string identifying 2160 the corresponding Destination Endpoint. An implementation of the 2161 protocol in this document SHOULD assume that the cost is a JSONNumber 2162 and fail to parse if it is not, unless the implementation is using an 2163 extensions to this document that indicates when and how costs of 2164 other data types are signaled. If the ALTO Server does not define a 2165 cost from a Source Endpoint to a particular Destination Endpoint, it 2166 MAY be omitted from the response. 2168 7.7.4.1.6. Example 2170 POST /endpointcost/lookup HTTP/1.1 2171 Host: alto.example.com 2172 Content-Length: [TODO] 2173 Content-Type: application/alto-endpointcostparams+json 2174 Accept: application/alto-endpointcost+json,application/alto-error+json 2176 { 2177 "cost-mode" : "ordinal", 2178 "cost-type" : "routingcost", 2179 "endpoints" : { 2180 "srcs": [ "ipv4:192.0.2.2" ], 2181 "dsts": [ 2182 "ipv4:192.0.2.89", 2183 "ipv4:198.51.100.34", 2184 "ipv4:203.0.113.45" 2185 ] 2186 } 2187 } 2189 HTTP/1.1 200 OK 2190 Content-Length: [TODO] 2191 Content-Type: application/alto-endpointcost+json 2193 { 2194 "meta" : {}, 2195 "data" : { 2196 "cost-mode" : "ordinal", 2197 "cost-type" : "routingcost", 2198 "map" : { 2199 "ipv4:192.0.2.2": { 2200 "ipv4:192.0.2.89" : 1, 2201 "ipv4:198.51.100.34" : 2, 2202 "ipv4:203.0.113.45" : 3 2203 } 2204 } 2205 } 2206 } 2208 8. Use Cases 2210 The sections below depict typical use cases. 2212 8.1. ALTO Client Embedded in P2P Tracker 2214 Many P2P currently-deployed P2P systems use a Tracker to manage 2215 swarms and perform peer selection. P2P trackers may currently use a 2216 variety of information to perform peer selection to meet application- 2217 specific goals. By acting as an ALTO Client, an P2P tracker can use 2218 ALTO information as an additional information source to enable more 2219 network-efficient traffic patterns and improve application 2220 performance. 2222 A particular requirement of many P2P trackers is that they must 2223 handle a large number of P2P clients. A P2P tracker can obtain and 2224 locally store ALTO information (the Network Map and Cost Map) from 2225 the ISPs containing the P2P clients, and benefit from the same 2226 aggregation of network locations done by ALTO Servers. 2228 .---------. (1) Get Network Map .---------------. 2229 | | <----------------------> | | 2230 | ALTO | | P2P Tracker | 2231 | Server | (2) Get Cost Map | (ALTO Client) | 2232 | | <----------------------> | | 2233 `---------' `---------------' 2234 ^ | 2235 (3) Get Peers | | (4) Selected Peer 2236 | v List 2237 .---------. .-----------. 2238 | Peer 1 | <-------------- | P2P | 2239 `---------' | Client | 2240 . (5) Connect to `-----------' 2241 . Selected Peers / 2242 .---------. / 2243 | Peer 50 | <------------------ 2244 `---------' 2246 Figure 4: ALTO Client Embedded in P2P Tracker 2248 Figure 4 shows an example use case where a P2P tracker is an ALTO 2249 Client and applies ALTO information when selecting peers for its P2P 2250 clients. The example proceeds as follows: 2252 1. The P2P Tracker requests the Network Map covering all PIDs from 2253 the ALTO Server using the Network Map query. The Network Map 2254 includes the IP prefixes contained in each PID, allowing the P2P 2255 tracker to locally map P2P clients into a PIDs. 2257 2. The P2P Tracker requests the Cost Map amongst all PIDs from the 2258 ALTO Server. 2260 3. A P2P Client joins the swarm, and requests a peer list from the 2261 P2P Tracker. 2263 4. The P2P Tracker returns a peer list to the P2P client. The 2264 returned peer list is computed based on the Network Map and Cost 2265 Map returned by the ALTO Server, and possibly other information 2266 sources. Note that it is possible that a tracker may use only 2267 the Network Map to implement hierarchical peer selection by 2268 preferring peers within the same PID and ISP. 2270 5. The P2P Client connects to the selected peers. 2272 Note that the P2P tracker may provide peer lists to P2P clients 2273 distributed across multiple ISPs. In such a case, the P2P tracker 2274 may communicate with multiple ALTO Servers. 2276 8.2. ALTO Client Embedded in P2P Client: Numerical Costs 2278 P2P clients may also utilize ALTO information themselves when 2279 selecting from available peers. It is important to note that not all 2280 P2P systems use a P2P tracker for peer discovery and selection. 2281 Furthermore, even when a P2P tracker is used, the P2P clients may 2282 rely on other sources, such as peer exchange and DHTs, to discover 2283 peers. 2285 When an P2P Client uses ALTO information, it typically queries only 2286 the ALTO Server servicing its own ISP. The my-Internet view provided 2287 by its ISP's ALTO Server can include preferences to all potential 2288 peers. 2290 .---------. (1) Get Network Map .---------------. 2291 | | <----------------------> | | 2292 | ALTO | | P2P Client | 2293 | Server | (2) Get Cost Map | (ALTO Client) | 2294 | | <----------------------> | | .---------. 2295 `---------' `---------------' <- | P2P | 2296 .---------. / | ^ ^ | Tracker | 2297 | Peer 1 | <-------------- | | \ `---------' 2298 `---------' | (3) Gather Peers 2299 . (4) Select Peers | | \ 2300 . and Connect / .--------. .--------. 2301 .---------. / | P2P | | DHT | 2302 | Peer 50 | <---------------- | Client | `--------' 2303 `---------' | (PEX) | 2304 `--------' 2306 Figure 5: ALTO Client Embedded in P2P Client 2308 Figure 5 shows an example use case where a P2P Client locally applies 2309 ALTO information to select peers. The use case proceeds as follows: 2311 1. The P2P Client requests the Network Map covering all PIDs from 2312 the ALTO Server servicing its own ISP. 2314 2. The P2P Client requests the Cost Map amongst all PIDs from the 2315 ALTO Server. The Cost Map by default specifies numerical costs. 2317 3. The P2P Client discovers peers from sources such as Peer Exchange 2318 (PEX) from other P2P Clients, Distributed Hash Tables (DHT), and 2319 P2P Trackers. 2321 4. The P2P Client uses ALTO information as part of the algorithm for 2322 selecting new peers, and connects to the selected peers. 2324 8.3. ALTO Client Embedded in P2P Client: Ranking 2326 It is also possible for a P2P Client to offload the selection and 2327 ranking process to an ALTO Server. In this use case, the ALTO Client 2328 gathers a list of known peers in the swarm, and asks the ALTO Server 2329 to rank them. 2331 As in the use case using numerical costs, the P2P Client typically 2332 only queries the ALTO Server servicing its own ISP. 2334 .---------. .---------------. 2335 | | | | 2336 | ALTO | (2) Get Endpoint Ranking | P2P Client | 2337 | Server | <----------------------> | (ALTO Client) | 2338 | | | | .---------. 2339 `---------' `---------------' <- | P2P | 2340 .---------. / | ^ ^ | Tracker | 2341 | Peer 1 | <-------------- | | \ `---------' 2342 `---------' | (1) Gather Peers 2343 . (3) Connect to | | \ 2344 . Selected Peers / .--------. .--------. 2345 .---------. / | P2P | | DHT | 2346 | Peer 50 | <---------------- | Client | `--------' 2347 `---------' | (PEX) | 2348 `--------' 2350 Figure 6: ALTO Client Embedded in P2P Client: Ranking 2352 Figure 6 shows an example of this scenario. The use case proceeds as 2353 follows: 2355 1. The P2P Client discovers peers from sources such as Peer Exchange 2356 (PEX) from other P2P Clients, Distributed Hash Tables (DHT), and 2357 P2P Trackers. 2359 2. The P2P Client queries the ALTO Server's Ranking Service, 2360 including discovered peers as the set of Destination Endpoints, 2361 and indicates the 'ordinal' Cost Mode. The response indicates 2362 the ranking of the candidate peers. 2364 3. The P2P Client connects to the peers in the order specified in 2365 the ranking. 2367 9. Discussions 2369 9.1. Discovery 2371 The discovery mechanism by which an ALTO Client locates an 2372 appropriate ALTO Server is out of scope for this document. This 2373 document assumes that an ALTO Client can discover an appropriate ALTO 2374 Server. Once it has done so, the ALTO Client may use the Information 2375 Resource Directory (see Section 7.6) to locate an Information 2376 Resource with the desired ALTO Information. 2378 9.2. Hosts with Multiple Endpoint Addresses 2380 In practical deployments, especially during the transition from IPv4 2381 to IPv6, a particular host may be reachable using multiple addresses. 2382 Furthermore, the particular network path followed when sending 2383 packets to the host may differ based on the address that is used. 2384 Network providers may prefer one path over another (e.g., one path my 2385 have a NAT64 middlebox). An additional consideration may be how to 2386 handle private address spaces (e.g., behind carrier-grade NATs). 2388 To support such behavior, this document allows multiple types of 2389 endpoint addresses. In supporting multiple address types, the ALTO 2390 Protocol also allows ALTO Service Provider the flexibility to 2391 indicate preferences for paths from an endpoint address of one type 2392 to an endpoint address of a different type. Note that in general, 2393 the path through the network may differ dependent on the types of 2394 addresses that are used. 2396 Note that there are limitations as to what information ALTO can 2397 provide in this regard. In particular, a particular ALTO Service 2398 provider may not be able to determine if connectivity with a 2399 particular endhost will succeed over IPv4 or IPv6, as this may depend 2400 upon information unknown to the ISP such as particular application 2401 implementations. 2403 9.3. Network Address Translation Considerations 2405 At this day and age of NAT v4<->v4, v4<->v6 [RFC6144], and possibly 2406 v6<->v6[I-D.mrw-nat66], a protocol should strive to be NAT friendly 2407 and minimize carrying IP addresses in the payload, or provide a mode 2408 of operation where the source IP address provide the information 2409 necessary to the server. 2411 The protocol specified in this document provides a mode of operation 2412 where the source network location is computed by the ALTO Server 2413 (i.e., the the Endpoint Cost Service) from the source IP address 2414 found in the ALTO Client query packets. This is similar to how some 2415 P2P Trackers (e.g., BitTorrent Trackers - see "Tracker HTTP/HTTPS 2416 Protocol" in [BitTorrent]) operate. 2418 The ALTO client SHOULD use the Session Traversal Utilities for NAT 2419 (STUN) [RFC5389] to determine a public IP address to use as a source 2420 Endpoint address. If using this method, the host MUST use the 2421 "Binding Request" message and the resulting "XOR-MAPPED-ADDRESS" 2422 parameter that is returned in the response. Using STUN requires 2423 cooperation from a publicly accessible STUN server. Thus, the ALTO 2424 client also requires configuration information that identifies the 2425 STUN server, or a domain name that can be used for STUN server 2426 discovery. To be selected for this purpose, the STUN server needs to 2427 provide the public reflexive transport address of the host. 2429 9.4. Mapping IPs to ASNs 2431 It may be desired for the ALTO Protocol to provide ALTO information 2432 including ASNs. Thus, ALTO Clients may need to identify the ASN for 2433 a Resource Provider to determine the cost to that Resource Provider. 2435 Applications can already map IPs to ASNs using information from a BGP 2436 Looking Glass. To do so, they must download a file of about 1.5MB 2437 when compressed (as of October 2008, with all information not needed 2438 for IP to ASN mapping removed) and periodically (perhaps monthly) 2439 refresh it. 2441 Alternatively, the Network Map query in the Map Filtering Service 2442 defined in this document could be extended to map ASNs into a set of 2443 IP prefixes. The mappings provided by the ISP would be both smaller 2444 and more authoritative. 2446 For simplicity of implementation, it's highly desirable that clients 2447 only have to implement exactly one mechanism of mapping IPs to ASNs. 2449 9.5. Endpoint and Path Properties 2451 An ALTO Server could make available many properties about Endpoints 2452 beyond their network location or grouping. For example, connection 2453 type, geographical location, and others may be useful to 2454 applications. This specification focuses on network location and 2455 grouping, but the protocol may be extended to handle other Endpoint 2456 properties. 2458 10. IANA Considerations 2460 10.1. application/alto-* Media Types 2462 This document requests the registration of multiple media types, 2463 listed in Table 2. 2465 +-------------+------------------------------+-----------------+ 2466 | Type | Subtype | Specification | 2467 +-------------+------------------------------+-----------------+ 2468 | application | alto-directory+json | Section 7.6 | 2469 | application | alto-networkmap+json | Section 7.7.1.1 | 2470 | application | alto-networkmapfilter+json | Section 7.7.2.1 | 2471 | application | alto-costmap+json | Section 7.7.1.2 | 2472 | application | alto-costmapfilter+json | Section 7.7.2.2 | 2473 | application | alto-endpointprop+json | Section 7.7.3.1 | 2474 | application | alto-endpointpropparams+json | Section 7.7.3.1 | 2475 | application | alto-endpointcost+json | Section 7.7.4.1 | 2476 | application | alto-endpointcostparams+json | Section 7.7.4.1 | 2477 | application | alto-error+json | Section 7.4 | 2478 +-------------+------------------------------+-----------------+ 2480 Table 2: ALTO Protocol Media Types 2482 Type name: application 2484 Subtype name: This documents requests the registration of multiple 2485 subtypes, as listed in Table 2. 2487 Required parameters: n/a 2489 Optional parameters: n/a 2491 Encoding considerations: Encoding considerations are identical to 2492 those specified for the 'application/json' media type. See 2493 [RFC4627]. 2495 Security considerations: Security considerations relating to the 2496 generation and consumption of ALTO protocol messages are discussed 2497 in Section 11. 2499 Interoperability considerations: This document specifies format of 2500 conforming messages and the interpretation thereof. 2502 Published specification: This document is the specification for 2503 these media types; see Table 2for the section documenting each 2504 media type. 2506 Applications that use this media type: ALTO Servers and ALTO Clients 2507 either standalone or embedded within other applications. 2509 Additional information: 2511 Magic number(s): n/a 2513 File extension(s): This document uses the mime type to refer to 2514 protocol messages and thus does not require a file extension. 2516 Macintosh file type code(s): n/a 2518 Person & email address to contact for further information: See 2519 "Authors' Addresses" section. 2521 Intended usage: COMMON 2523 Restrictions on usage: n/a 2525 Author: See "Authors' Addresses" section. 2527 Change controller: See "Authors' Addresses" section. 2529 10.2. ALTO Cost Type Registry 2531 This document requests the creation of an ALTO Cost Type registry to 2532 be maintained by IANA. 2534 This registry serves two purposes. First, it ensures uniqueness of 2535 identifiers referring to ALTO Cost Types. Second, it provides 2536 references to particular semantics of allocated Cost Types to be 2537 applied by both ALTO Servers and applications utilizing ALTO Clients. 2539 New ALTO Cost Types are assigned after Expert Review [RFC5226]. The 2540 Expert Reviewer will generally consult the ALTO Working Group or its 2541 successor. Expert Review is used to ensure that proper documentation 2542 regarding ALTO Cost Type semantics and security considerations has 2543 been provided. The provided documentation should be detailed enough 2544 to provide guidance to both ALTO Service Providers and applications 2545 utilizing ALTO Clients as to how values of the registered ALTO Cost 2546 Type should be interpreted. Updates and deletions of ALTO Cost Types 2547 follow the same procedure. 2549 Registered ALTO Cost Type identifiers MUST conform to the syntatical 2550 requirements specified in Section 7.5.5. Identifiers are to be 2551 recorded and displayed as ASCII strings. 2553 Identifiers prefixed with 'priv:' are reserved for Private Use. 2554 Identifiers prefixed with 'exp:' are reserved for Experimental use. 2556 Requests to add a new value to the registry MUST include the 2557 following information: 2559 o Identifier: The name of the desired ALTO Cost Type. 2561 o Intended Semantics: ALTO Costs carry with them semantics to guide 2562 their usage by ALTO Clients. For example, if a value refers to a 2563 measurement, the measurement units must be documented. For proper 2564 implementation of the ordinal Cost Mode (e.g., by a third-party 2565 service), it should be documented whether higher or lower values 2566 of the cost are more preferred. 2568 o Security Considerations: ALTO Costs expose information to ALTO 2569 Clients. As such, proper usage of a particular Cost Type may 2570 require certain information to be exposed by an ALTO Service 2571 Provider. Since network information is frequently regarded as 2572 proprietary or confidential, ALTO Service Providers should be made 2573 aware of the security ramifications related to usage of a Cost 2574 Type. 2576 This specification requests registration of the identifier 2577 'routingcost'. Semantics for the this Cost Type are documented in 2578 Section 5.1.1.1, and security considerations are documented in 2579 Section 11.1. 2581 10.3. ALTO Endpoint Property Registry 2583 This document requests the creation of an ALTO Endpoint Property 2584 registry to be maintained by IANA. 2586 This registry serves two purposes. First, it ensures uniqueness of 2587 identifiers referring to ALTO Endpoint Properties. Second, it 2588 provides references to particular semantics of allocated Endpoint 2589 Properties to be applied by both ALTO Servers and applications 2590 utilizing ALTO Clients. 2592 New ALTO Endpoint Properties are assigned after Expert Review 2593 [RFC5226]. The Expert Reviewer will generally consult the ALTO 2594 Working Group or its successor. Expert Review is used to ensure that 2595 proper documentation regarding ALTO Endpoint Property semantics and 2596 security considerations has been provided. The provided 2597 documentation should be detailed enough to provide guidance to both 2598 ALTO Service Providers and applications utilizing ALTO Clients as to 2599 how values of the registered ALTO Endpoint Properties should be 2600 interpreted. Updates and deletions of ALTO Endpoint Properties 2601 follow the same procedure. 2603 Registered ALTO Endpoint Property identifiers MUST conform to the 2604 syntatical requirements specified in Section 7.5.6. Identifiers are 2605 to be recorded and displayed as ASCII strings. 2607 Identifiers prefixed with 'priv:' are reserved for Private Use. 2608 Identifiers prefixed with 'exp:' are reserved for Experimental use. 2610 Requests to add a new value to the registry MUST include the 2611 following information: 2613 o Identifier: The name of the desired ALTO Endpoint Property. 2615 o Intended Semantics: ALTO Endpoint Properties carry with them 2616 semantics to guide their usage by ALTO Clients. For example, if a 2617 value refers to a measurement, the measurement units must be 2618 documented. For proper implementation of the ordinal Cost Mode 2619 (e.g., by a third-party service), it should be documented whether 2620 higher or lower values of the cost are more preferred. 2622 o Security Considerations: ALTO Endpoint Properties expose 2623 information to ALTO Clients. As such, proper usage of a 2624 particular Endpoint Properties may require certain information to 2625 be exposed by an ALTO Service Provider. Since network information 2626 is frequently regarded as proprietary or confidential, ALTO 2627 Service Providers should be made aware of the security 2628 ramifications related to usage of an Endpoint Property. 2630 This specification requests registration of the identifier 'pid'. 2631 Semantics for the this Endpoint Property are documented in 2632 Section 4.1, and security considerations are documented in 2633 Section 11.1. 2635 11. Security Considerations 2637 11.1. Privacy Considerations for ISPs 2639 ISPs must be cognizant of the network topology and provisioning 2640 information provided through ALTO Interfaces. ISPs should evaluate 2641 how much information is revealed and the associated risks. On the 2642 one hand, providing overly fine-grained information may make it 2643 easier for attackers to infer network topology. In particular, 2644 attackers may try to infer details regarding ISPs' operational 2645 policies or inter-ISP business relationships by intentionally posting 2646 a multitude of selective queries to an ALTO server and analyzing the 2647 responses. Such sophisticated attacks may reveal more information 2648 than an ISP hosting an ALTO server intends to disclose. On the other 2649 hand, revealing overly coarse-grained information may not provide 2650 benefits to network efficiency or performance improvements to ALTO 2651 Clients. 2653 11.2. ALTO Clients 2655 Applications using the information must be cognizant of the 2656 possibility that the information is malformed or incorrect. Even if 2657 an ALTO Server has been properly authenticated by the ALTO Client, 2658 the information provided may be malicious because the ALTO Server and 2659 its credentials have been compromised (e.g., through malware). Other 2660 considerations (e.g., relating to application performance) can be 2661 found in Section 6 of [RFC5693]. 2663 ALTO Clients should also be cognizant of revealing Network Location 2664 Identifiers (IP addresses or fine-grained PIDs) to the ALTO Server, 2665 as doing so may allow the ALTO Server to infer communication 2666 patterns. One possibility is for the ALTO Client to only rely on 2667 Network Map for PIDs and Cost Map amongst PIDs to avoid passing IP 2668 addresses of their peers to the ALTO Server. 2670 In addition, ALTO clients should be cautious not to unintentionally 2671 or indirectly disclose the resource identifier (of which they try to 2672 improve the retrieval through ALTO-guidance), e.g., the name/ 2673 identifier of a certain video stream in P2P live streaming, to the 2674 ALTO server. Note that the ALTO Protocol specified in this document 2675 does not explicitly reveal any resource identifier to the ALTO 2676 Server. However, for instance, depending on the popularity or other 2677 specifics (such as language) of the resource, an ALTO server could 2678 potentially deduce information about the desired resource from 2679 information such as the Network Locations the client sends as part of 2680 its request to the server. 2682 11.3. Authentication, Integrity Protection, and Encryption 2684 SSL/TLS can provide encryption of transmitted messages as well as 2685 authentication of the ALTO Client and Server. HTTP Basic or Digest 2686 authentication can provide authentication of the client (combined 2687 with SSL/TLS, it can additionally provide encryption and 2688 authentication of the server). 2690 An ALTO Server may optionally use authentication (and potentially 2691 encryption) to protect ALTO information it provides. This can be 2692 achieved by digitally signing a hash of the ALTO information itself 2693 and attaching the signature to the ALTO information. There may be 2694 special use cases where encryption of ALTO information is desirable. 2695 In many cases, however, information sent out by an ALTO Server may be 2696 regarded as non-confidential information. 2698 ISPs should be cognizant that encryption only protects ALTO 2699 information until it is decrypted by the intended ALTO Client. 2700 Digital Rights Management (DRM) techniques and legal agreements 2701 protecting ALTO information are outside of the scope of this 2702 document. 2704 11.4. ALTO Information Redistribution 2706 It is possible for applications to redistribute ALTO information to 2707 improve scalability. Even with such a distribution scheme, ALTO 2708 Clients obtaining ALTO information must be able to validate the 2709 received ALTO information to ensure that it was generated by an 2710 appropriate ALTO Server. Support for this validation is not provided 2711 in this document, but may be provided by extension documents. 2713 11.5. Denial of Service 2715 ISPs should be cognizant of the workload at the ALTO Server generated 2716 by certain ALTO Queries, such as certain queries to the Map Filtering 2717 Service and Ranking Service. In particular, queries which can be 2718 generated with low effort but result in expensive workloads at the 2719 ALTO Server could be exploited for Denial-of-Service attacks. For 2720 instance, a simple ALTO query with n Source Network Locations and m 2721 Destination Network Locations can be generated fairly easily but 2722 results in the computation of n*m Path Costs between pairs by the 2723 ALTO Server (see Section 5.2). One way to limit Denial-of-Service 2724 attacks is to employ access control to the ALTO server. Another 2725 possible mechanism for an ALTO Server to protect itself against a 2726 multitude of computationally expensive bogus requests is to demand 2727 that each ALTO Client to solve a computational puzzle first before 2728 allocating resources for answering a request (see, e.g., 2729 [I-D.jennings-sip-hashcash]). The current specification does not use 2730 such computational puzzles, and discussion regarding tradeoffs of 2731 such an approach would be needed before including such a technique in 2732 the ALTO Protocol. 2734 ISPs should also leverage the fact that the the Map Service allows 2735 ALTO Servers to pre-generate maps that can be useful to many ALTO 2736 Clients. 2738 11.6. ALTO Server Access Control 2740 In order to limit access to an ALTO server (e.g., for an ISP to only 2741 allow its users to access its ALTO server, or to prevent Denial-of- 2742 Service attacks by arbitrary hosts from the Internet), an ALTO server 2743 may employ access control policies. Depending on the use-case and 2744 scenario, an ALTO server may restrict access to its services more 2745 strictly or rather openly (see [I-D.stiemerling-alto-deployments] for 2746 a more detailed discussion on this issue). 2748 12. References 2750 12.1. Normative References 2752 [IEEE.754.2008] 2753 Institute of Electrical and Electronics Engineers, 2754 "Standard for Binary Floating-Point Arithmetic", IEEE 2755 Standard 754, August 2008. 2757 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2758 Extensions (MIME) Part Two: Media Types", RFC 2046, 2759 November 1996. 2761 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2762 Requirement Levels", BCP 14, RFC 2119, March 1997. 2764 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2765 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2766 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2768 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2769 Resource Identifier (URI): Generic Syntax", STD 66, 2770 RFC 3986, January 2005. 2772 [RFC4627] Crockford, D., "The application/json Media Type for 2773 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2775 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2776 (CIDR): The Internet Address Assignment and Aggregation 2777 Plan", BCP 122, RFC 4632, August 2006. 2779 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2780 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2781 May 2008. 2783 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 2784 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 2785 October 2008. 2787 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 2788 Address Text Representation", RFC 5952, August 2010. 2790 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2791 Verification of Domain-Based Application Service Identity 2792 within Internet Public Key Infrastructure Using X.509 2793 (PKIX) Certificates in the Context of Transport Layer 2794 Security (TLS)", RFC 6125, March 2011. 2796 12.2. Informative References 2798 [BitTorrent] 2799 "Bittorrent Protocol Specification v1.0", 2800 . 2802 [I-D.akonjang-alto-proxidor] 2803 Akonjang, O., Feldmann, A., Previdi, S., Davie, B., and D. 2804 Saucez, "The PROXIDOR Service", 2805 draft-akonjang-alto-proxidor-00 (work in progress), 2806 March 2009. 2808 [I-D.gu-alto-redistribution] 2809 Yingjie, G., Alimi, R., and R. Even, "ALTO Information 2810 Redistribution", draft-gu-alto-redistribution-03 (work in 2811 progress), July 2010. 2813 [I-D.ietf-alto-reqs] 2814 Previdi, S., Stiemerling, M., Woundy, R., and Y. Yang, 2815 "Application-Layer Traffic Optimization (ALTO) 2816 Requirements", draft-ietf-alto-reqs-08 (work in progress), 2817 March 2011. 2819 [I-D.ietf-alto-server-discovery] 2820 Kiesel, S., Stiemerling, M., Schwan, N., Scharf, M., and 2821 S. Yongchao, "ALTO Server Discovery", 2822 draft-ietf-alto-server-discovery-03 (work in progress), 2823 March 2012. 2825 [I-D.jennings-sip-hashcash] 2826 Jennings, C., "Computational Puzzles for SPAM Reduction in 2827 SIP", draft-jennings-sip-hashcash-06 (work in progress), 2828 July 2007. 2830 [I-D.mrw-nat66] 2831 Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 2832 Translation", draft-mrw-nat66-16 (work in progress), 2833 April 2011. 2835 [I-D.p4p-framework] 2836 Alimi, R., Pasko, D., Popkin, L., Wang, Y., and Y. Yang, 2837 "P4P: Provider Portal for P2P Applications", 2838 draft-p4p-framework-00 (work in progress), November 2008. 2840 [I-D.saumitra-alto-multi-ps] 2841 Das, S., Narayanan, V., and L. Dondeti, "ALTO: A Multi 2842 Dimensional Peer Selection Problem", 2843 draft-saumitra-alto-multi-ps-00 (work in progress), 2844 October 2008. 2846 [I-D.saumitra-alto-queryresponse] 2847 Das, S. and V. Narayanan, "A Client to Service Query 2848 Response Protocol for ALTO", 2849 draft-saumitra-alto-queryresponse-00 (work in progress), 2850 March 2009. 2852 [I-D.shalunov-alto-infoexport] 2853 Shalunov, S., Penno, R., and R. Woundy, "ALTO Information 2854 Export Service", draft-shalunov-alto-infoexport-00 (work 2855 in progress), October 2008. 2857 [I-D.stiemerling-alto-deployments] 2858 Stiemerling, M. and S. Kiesel, "ALTO Deployment 2859 Considerations", draft-stiemerling-alto-deployments-06 2860 (work in progress), January 2011. 2862 [I-D.wang-alto-p4p-specification] 2863 Wang, Y., Alimi, R., Pasko, D., Popkin, L., and Y. Yang, 2864 "P4P Protocol Specification", 2865 draft-wang-alto-p4p-specification-00 (work in progress), 2866 March 2009. 2868 [P4P-SIGCOMM08] 2869 Xie, H., Yang, Y., Krishnamurthy, A., Liu, Y., and A. 2870 Silberschatz, "P4P: Provider Portal for (P2P) 2871 Applications", SIGCOMM 2008, August 2008. 2873 [RFC5693] Seedorf, J. and E. Burger, "Application-Layer Traffic 2874 Optimization (ALTO) Problem Statement", RFC 5693, 2875 October 2009. 2877 [RFC6144] Baker, F., Li, X., Bao, C., and K. Yin, "Framework for 2878 IPv4/IPv6 Translation", RFC 6144, April 2011. 2880 Appendix A. Acknowledgments 2882 Thank you to Jan Seedorf for contributions to the Security 2883 Considerations section. 2885 We would like to thank the following people whose input and 2886 involvement was indispensable in achieving this merged proposal: 2888 Obi Akonjang (DT Labs/TU Berlin), 2889 Saumitra M. Das (Qualcomm Inc.), 2891 Syon Ding (China Telecom), 2893 Doug Pasko (Verizon), 2895 Laird Popkin (Pando Networks), 2897 Satish Raghunath (Juniper Networks), 2899 Albert Tian (Ericsson/Redback), 2901 Yu-Shun Wang (Microsoft), 2903 David Zhang (PPLive), 2905 Yunfei Zhang (China Mobile). 2907 We would also like to thank the following additional people who were 2908 involved in the projects that contributed to this merged document: 2909 Alex Gerber (AT&T), Chris Griffiths (Comcast), Ramit Hora (Pando 2910 Networks), Arvind Krishnamurthy (University of Washington), Marty 2911 Lafferty (DCIA), Erran Li (Bell Labs), Jin Li (Microsoft), Y. Grace 2912 Liu (IBM Watson), Jason Livingood (Comcast), Michael Merritt (AT&T), 2913 Ingmar Poese (DT Labs/TU Berlin), James Royalty (Pando Networks), 2914 Damien Saucez (UCL) Thomas Scholl (AT&T), Emilio Sepulveda 2915 (Telefonica), Avi Silberschatz (Yale University), Hassan Sipra (Bell 2916 Canada), Georgios Smaragdakis (DT Labs/TU Berlin), Haibin Song 2917 (Huawei), Oliver Spatscheck (AT&T), See-Mong Tang (Microsoft), Jia 2918 Wang (AT&T), Hao Wang (Yale University), Ye Wang (Yale University), 2919 Haiyong Xie (Yale University). 2921 Appendix B. Authors 2923 [[CmtAuthors: RFC Editor: Please move information in this section to 2924 the Authors' Addresses section at publication time.]] 2926 Stefano Previdi 2927 Cisco 2929 Email: sprevidi@cisco.com 2931 Stanislav Shalunov 2932 BitTorrent 2934 Email: shalunov@bittorrent.com 2935 Richard Woundy 2936 Comcast 2938 Richard_Woundy@cable.comcast.com 2940 Authors' Addresses 2942 Richard Alimi (editor) 2943 Google 2944 1600 Amphitheatre Parkway 2945 Mountain View CA 2946 USA 2948 Email: ralimi@google.com 2950 Reinaldo Penno (editor) 2951 Juniper Networks 2952 1194 N Mathilda Avenue 2953 Sunnyvale CA 2954 USA 2956 Email: rpenno@juniper.net 2958 Y. Richard Yang (editor) 2959 Yale University 2960 51 Prospect St 2961 New Haven CT 2962 USA 2964 Email: yry@cs.yale.edu