idnits 2.17.1 draft-ietf-alto-protocol-27.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 1047 has weird spacing: '... meta meta ...' == Line 1344 has weird spacing: '...ilities capa...' == Line 1831 has weird spacing: '...ostMode cost...' == Line 2314 has weird spacing: '...ostType cost...' == Line 2316 has weird spacing: '...DFilter pids;...' == (2 more instances...) -- The document date (March 5, 2014) is 3697 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** 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-deployments-09 -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 5 errors (**), 0 flaws (~~), 8 warnings (==), 4 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 6, 2014 Cisco Systems 6 Y. Yang, Ed. 7 Yale University 8 March 5, 2014 10 ALTO Protocol 11 draft-ietf-alto-protocol-27.txt 13 Abstract 15 Applications using the Internet already have access to some topology 16 information of Internet Service Provider (ISP) networks. For 17 example, views to Internet routing tables at looking glass servers 18 are available and can be practically downloaded to many network 19 application clients. What is missing is knowledge of the underlying 20 network topologies from the point of view of ISPs. In other words, 21 what an ISP prefers in terms of traffic optimization -- and a way to 22 distribute it. 24 The Application-Layer Traffic Optimization (ALTO) Service provides 25 network information (e.g., basic network location structure and 26 preferences of network paths) with the goal of modifying network 27 resource consumption patterns while maintaining or improving 28 application performance. The basic information of ALTO is based on 29 abstract maps of a network. These maps provide a simplified view, 30 yet enough information about a network for applications to 31 effectively utilize them. Additional services are built on top of 32 the maps. 34 This document describes a protocol implementing the ALTO Service. 35 Although the ALTO Service would primarily be provided by ISPs, other 36 entities such as content service providers could also operate an ALTO 37 Service. Applications that could use this service are those that 38 have a choice to which end points to connect. Examples of such 39 applications are peer-to-peer (P2P) and content delivery networks. 41 Requirements Language 43 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 44 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 45 document are to be interpreted as described in RFC 2119 [RFC2119]. 47 Status of this Memo 48 This Internet-Draft is submitted in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF). Note that other groups may also distribute 53 working documents as Internet-Drafts. The list of current Internet- 54 Drafts is at http://datatracker.ietf.org/drafts/current/. 56 Internet-Drafts are draft documents valid for a maximum of six months 57 and may be updated, replaced, or obsoleted by other documents at any 58 time. It is inappropriate to use Internet-Drafts as reference 59 material or to cite them other than as "work in progress." 61 This Internet-Draft will expire on September 6, 2014. 63 Copyright Notice 65 Copyright (c) 2014 IETF Trust and the persons identified as the 66 document authors. All rights reserved. 68 This document is subject to BCP 78 and the IETF Trust's Legal 69 Provisions Relating to IETF Documents 70 (http://trustee.ietf.org/license-info) in effect on the date of 71 publication of this document. Please review these documents 72 carefully, as they describe your rights and restrictions with respect 73 to this document. Code Components extracted from this document must 74 include Simplified BSD License text as described in Section 4.e of 75 the Trust Legal Provisions and are provided without warranty as 76 described in the Simplified BSD License. 78 Table of Contents 80 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 7 81 1.1. Problem Statement . . . . . . . . . . . . . . . . . . . . 7 82 1.2. Design Overview . . . . . . . . . . . . . . . . . . . . . 8 83 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 84 2.1. Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . 8 85 2.2. Endpoint Address . . . . . . . . . . . . . . . . . . . . . 8 86 2.3. Network Location . . . . . . . . . . . . . . . . . . . . . 9 87 2.4. ALTO Information . . . . . . . . . . . . . . . . . . . . . 9 88 2.5. ALTO Information Base . . . . . . . . . . . . . . . . . . 9 89 2.6. ALTO Service . . . . . . . . . . . . . . . . . . . . . . . 9 90 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 9 91 3.1. ALTO Service and Protocol Scope . . . . . . . . . . . . . 9 92 3.2. ALTO Information Reuse and Redistribution . . . . . . . . 12 93 4. ALTO Information Service Framework . . . . . . . . . . . . . . 12 94 4.1. ALTO Information Services . . . . . . . . . . . . . . . . 13 95 4.1.1. Map Service . . . . . . . . . . . . . . . . . . . . . 13 96 4.1.2. Map Filtering Service . . . . . . . . . . . . . . . . 13 97 4.1.3. Endpoint Property Service . . . . . . . . . . . . . . 13 98 4.1.4. Endpoint Cost Service . . . . . . . . . . . . . . . . 14 99 5. Network Map . . . . . . . . . . . . . . . . . . . . . . . . . 14 100 5.1. Provider-defined Identifier (PID) . . . . . . . . . . . . 14 101 5.2. Endpoint Addresses . . . . . . . . . . . . . . . . . . . . 15 102 5.3. Example Network Map . . . . . . . . . . . . . . . . . . . 15 103 6. Cost Map . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 104 6.1. Cost Types . . . . . . . . . . . . . . . . . . . . . . . . 17 105 6.1.1. Cost Metric . . . . . . . . . . . . . . . . . . . . . 17 106 6.1.2. Cost Mode . . . . . . . . . . . . . . . . . . . . . . 18 107 6.2. Cost Map Structure . . . . . . . . . . . . . . . . . . . . 18 108 6.3. Network Map and Cost Map Dependency . . . . . . . . . . . 19 109 6.4. Cost Map Update . . . . . . . . . . . . . . . . . . . . . 19 110 7. Endpoint Properties . . . . . . . . . . . . . . . . . . . . . 20 111 7.1. Endpoint Property Type . . . . . . . . . . . . . . . . . . 20 112 7.1.1. Endpoint Property Type: pid . . . . . . . . . . . . . 20 113 8. Protocol Specification: General Processing . . . . . . . . . . 20 114 8.1. Overall Design . . . . . . . . . . . . . . . . . . . . . . 20 115 8.2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . 21 116 8.3. Basic Operations . . . . . . . . . . . . . . . . . . . . . 21 117 8.3.1. Client Discovering Information Resources . . . . . . . 22 118 8.3.2. Client Requesting Information Resources . . . . . . . 22 119 8.3.3. Server Responding to IR Request . . . . . . . . . . . 23 120 8.3.4. Client Handling Server Response . . . . . . . . . . . 23 121 8.3.5. Authentication and Encryption . . . . . . . . . . . . 24 122 8.3.6. Information Refreshing . . . . . . . . . . . . . . . . 24 123 8.3.7. Parsing of Unknown Fields . . . . . . . . . . . . . . 24 124 8.4. Server Response Encoding . . . . . . . . . . . . . . . . . 25 125 8.4.1. Meta Information . . . . . . . . . . . . . . . . . . . 25 126 8.4.2. Data Information . . . . . . . . . . . . . . . . . . . 25 127 8.5. Protocol Errors . . . . . . . . . . . . . . . . . . . . . 25 128 8.5.1. Media Type . . . . . . . . . . . . . . . . . . . . . . 26 129 8.5.2. Response Format and Error Codes . . . . . . . . . . . 26 130 8.5.3. Overload Conditions and Server Unavailability . . . . 28 131 9. Protocol Specification: Information Resource Directory . . . . 29 132 9.1. Information Resource Attributes . . . . . . . . . . . . . 29 133 9.1.1. Resource ID . . . . . . . . . . . . . . . . . . . . . 29 134 9.1.2. Media Type . . . . . . . . . . . . . . . . . . . . . . 29 135 9.1.3. Capabilities . . . . . . . . . . . . . . . . . . . . . 29 136 9.1.4. Accepts Input Parameters . . . . . . . . . . . . . . . 29 137 9.1.5. Dependent Resources . . . . . . . . . . . . . . . . . 30 138 9.2. Information Resource Directory (IRD) . . . . . . . . . . . 30 139 9.2.1. Media Type . . . . . . . . . . . . . . . . . . . . . . 30 140 9.2.2. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30 141 9.2.3. Example . . . . . . . . . . . . . . . . . . . . . . . 32 142 9.2.4. Delegation using IRD . . . . . . . . . . . . . . . . . 35 143 9.2.5. Considerations of Using IRD . . . . . . . . . . . . . 37 144 10. Protocol Specification: Basic Data Types . . . . . . . . . . . 37 145 10.1. PID Name . . . . . . . . . . . . . . . . . . . . . . . . . 38 146 10.2. Resource ID . . . . . . . . . . . . . . . . . . . . . . . 38 147 10.3. Version Tag . . . . . . . . . . . . . . . . . . . . . . . 38 148 10.4. Endpoints . . . . . . . . . . . . . . . . . . . . . . . . 39 149 10.4.1. Typed Endpoint Addresses . . . . . . . . . . . . . . . 39 150 10.4.2. Address Type . . . . . . . . . . . . . . . . . . . . . 39 151 10.4.3. Endpoint Address . . . . . . . . . . . . . . . . . . . 39 152 10.4.4. Endpoint Prefixes . . . . . . . . . . . . . . . . . . 40 153 10.4.5. Endpoint Address Group . . . . . . . . . . . . . . . . 40 154 10.5. Cost Mode . . . . . . . . . . . . . . . . . . . . . . . . 41 155 10.6. Cost Metric . . . . . . . . . . . . . . . . . . . . . . . 41 156 10.7. Cost Type . . . . . . . . . . . . . . . . . . . . . . . . 42 157 10.8. Endpoint Property . . . . . . . . . . . . . . . . . . . . 42 158 10.8.1. Resource Specific Endpoint Properties . . . . . . . . 42 159 10.8.2. Global Endpoint Properties . . . . . . . . . . . . . . 42 160 11. Protocol Specification: Service Information Resources . . . . 43 161 11.1. Meta Information . . . . . . . . . . . . . . . . . . . . . 43 162 11.2. Map Service . . . . . . . . . . . . . . . . . . . . . . . 43 163 11.2.1. Network Map . . . . . . . . . . . . . . . . . . . . . 43 164 11.2.2. Mapping IP Addresses to PIDs for 'ipv4'/'ipv6' 165 Network Maps . . . . . . . . . . . . . . . . . . . . . 46 166 11.2.3. Cost Map . . . . . . . . . . . . . . . . . . . . . . . 47 167 11.3. Map Filtering Service . . . . . . . . . . . . . . . . . . 50 168 11.3.1. Filtered Network Map . . . . . . . . . . . . . . . . . 50 169 11.3.2. Filtered Cost Map . . . . . . . . . . . . . . . . . . 52 170 11.4. Endpoint Property Service . . . . . . . . . . . . . . . . 56 171 11.4.1. Endpoint Property . . . . . . . . . . . . . . . . . . 57 172 11.5. Endpoint Cost Service . . . . . . . . . . . . . . . . . . 60 173 11.5.1. Endpoint Cost . . . . . . . . . . . . . . . . . . . . 60 175 12. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 63 176 12.1. ALTO Client Embedded in P2P Tracker . . . . . . . . . . . 64 177 12.2. ALTO Client Embedded in P2P Client: Numerical Costs . . . 65 178 12.3. ALTO Client Embedded in P2P Client: Ranking . . . . . . . 66 179 13. Discussions . . . . . . . . . . . . . . . . . . . . . . . . . 67 180 13.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 67 181 13.2. Hosts with Multiple Endpoint Addresses . . . . . . . . . . 68 182 13.3. Network Address Translation Considerations . . . . . . . . 68 183 13.4. Endpoint and Path Properties . . . . . . . . . . . . . . . 69 184 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 185 14.1. application/alto-* Media Types . . . . . . . . . . . . . . 69 186 14.2. ALTO Cost Metric Registry . . . . . . . . . . . . . . . . 71 187 14.3. ALTO Endpoint Property Type Registry . . . . . . . . . . . 72 188 14.4. ALTO Address Type Registry . . . . . . . . . . . . . . . . 74 189 14.5. ALTO Error Code Registry . . . . . . . . . . . . . . . . . 75 190 15. Security Considerations . . . . . . . . . . . . . . . . . . . 75 191 15.1. Authenticity and Integrity of ALTO Information . . . . . . 76 192 15.1.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 76 193 15.1.2. Protection Strategies . . . . . . . . . . . . . . . . 76 194 15.1.3. Limitations . . . . . . . . . . . . . . . . . . . . . 76 195 15.2. Potential Undesirable Guidance from Authenticated ALTO 196 Information . . . . . . . . . . . . . . . . . . . . . . . 77 197 15.2.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 77 198 15.2.2. Protection Strategies . . . . . . . . . . . . . . . . 77 199 15.3. Confidentiality of ALTO Information . . . . . . . . . . . 78 200 15.3.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 78 201 15.3.2. Protection Strategies . . . . . . . . . . . . . . . . 78 202 15.3.3. Limitations . . . . . . . . . . . . . . . . . . . . . 79 203 15.4. Privacy for ALTO Users . . . . . . . . . . . . . . . . . . 79 204 15.4.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 79 205 15.4.2. Protection Strategies . . . . . . . . . . . . . . . . 79 206 15.5. Availability of ALTO Service . . . . . . . . . . . . . . . 80 207 15.5.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 80 208 15.5.2. Protection Strategies . . . . . . . . . . . . . . . . 80 209 16. Manageability Considerations . . . . . . . . . . . . . . . . . 80 210 16.1. Operations . . . . . . . . . . . . . . . . . . . . . . . . 81 211 16.1.1. Installation and Initial Setup . . . . . . . . . . . . 81 212 16.1.2. Migration Path . . . . . . . . . . . . . . . . . . . . 81 213 16.1.3. Dependencies on Other Protocols and Functional 214 Components . . . . . . . . . . . . . . . . . . . . . . 82 215 16.1.4. Impact and Observation on Network Operation . . . . . 82 216 16.2. Management . . . . . . . . . . . . . . . . . . . . . . . . 83 217 16.2.1. Management Interoperability . . . . . . . . . . . . . 83 218 16.2.2. Management Information . . . . . . . . . . . . . . . . 83 219 16.2.3. Fault Management . . . . . . . . . . . . . . . . . . . 83 220 16.2.4. Configuration Management . . . . . . . . . . . . . . . 83 221 16.2.5. Performance Management . . . . . . . . . . . . . . . . 84 222 16.2.6. Security Management . . . . . . . . . . . . . . . . . 84 224 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 84 225 17.1. Normative References . . . . . . . . . . . . . . . . . . . 84 226 17.2. Informative References . . . . . . . . . . . . . . . . . . 85 227 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 88 228 Appendix B. Design History and Merged Proposals . . . . . . . . . 89 229 Appendix C. Authors . . . . . . . . . . . . . . . . . . . . . . . 89 230 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 90 232 1. Introduction 234 1.1. Problem Statement 236 This document defines the ALTO Protocol, which provides a solution 237 for the problem stated in [RFC5693]. Specifically, in today's 238 networks, network information such as network topologies, link 239 availability, routing policies, and path costs are hidden from the 240 application layer, and many applications benefited from such hiding 241 of network complexity. However, new applications, such as 242 application-layer overlays, can benefit from information about the 243 underlying network infrastructure. In particular, these new network 244 applications can be adaptive, and hence become more network-efficient 245 (e.g., reduce network resource consumption) and achieve better 246 application performance (e.g., accelerated download rate), by 247 leveraging network-provided information. 249 At a high level, the ALTO Protocol specified in this document is an 250 information publishing interface that allows a network to publish its 251 network information such as network locations, costs between them at 252 configurable granularities, and endhost properties to network 253 applications. The information published by the ALTO Protocol should 254 benefit both the network and the applications (i.e., the consumers of 255 the information). Either the operator of the network or a third- 256 party (e.g., an information aggregator) can retrieve or derive 257 related information of the network and publish it using the ALTO 258 Protocol. When a network provides information through the ALTO 259 Protocol, the network is said to provide the ALTO Service. 261 To allow better understanding of the goal of the ALTO Protocol, this 262 document provides a short, non-normative overview of the benefits of 263 ALTO to both networks and applications: 265 o A network that provides an ALTO Service can achieve better 266 utilization of its networking infrastructure. For example, by 267 using ALTO as a tool to interact with applications, a network is 268 able to provide network information to applications so that the 269 applications can better manage traffic on more expensive or 270 difficult-to-provision links such as long distance, transit or 271 backup links. During the interaction, the network can choose to 272 protect its sensitive and confidential network state information, 273 by abstracting real metric values into non-real numerical scores 274 or ordinal ranking. 276 o An application that uses an ALTO Service can benefit from better 277 knowledge of the network to avoid network bottlenecks. For 278 example, an overlay application can use information provided by 279 the ALTO Service to avoid selecting peers connected via high-delay 280 links (e.g., some intercontinental links). Using ALTO to 281 initialize each node with promising ("better-than-random") peers, 282 an adaptive peer-to-peer overlay may achieve faster, better 283 convergence. 285 1.2. Design Overview 287 The ALTO Protocol specified in this document meets the ALTO 288 requirements specified in [RFC5693], and unifies multiple protocols 289 previously designed with similar intentions. See Appendix A for a 290 list of people and Appendix B for a list of proposals that have made 291 significant contributions to this effort. 293 The ALTO Protocol uses a REST-ful design [Fielding-Thesis], and 294 encodes its requests and responses using JSON [RFC4627]. These 295 designs are chosen because of their flexibility and extensibility. 296 In addition, these designs make it possible for ALTO to be deployed 297 at scale by leveraging existing HTTP [RFC2616] implementations, 298 infrastructures and deployment experience. 300 2. Terminology 302 This document uses the following terms defined in [RFC5693]: 303 Application, Overlay Network, Peer, Resource, Resource Identifier, 304 Resource Provider, Resource Consumer, Resource Directory, Transport 305 Address, Host Location Attribute, ALTO Service, ALTO Server, ALTO 306 Client, ALTO Query, ALTO Reply, ALTO Transaction, Local Traffic, 307 Peering Traffic, Transit Traffic. 309 This document also uses the following additional terms: Endpoint 310 Address, Network Location, ALTO Information, ALTO Information Base, 311 and ALTO Service. 313 2.1. Endpoint 315 An Endpoint is an application or host that is capable of 316 communicating (sending and/or receiving messages) on a network. 318 An Endpoint is typically either a Resource Provider or a Resource 319 Consumer. 321 2.2. Endpoint Address 323 An Endpoint Address represents the communication address of an 324 endpoint. Common forms of Endpoint Addresses include IP address, MAC 325 address and overlay ID. An Endpoint Address can be network- 326 attachment based (e.g., IP address) or network-attachment agnostic 327 (e.g., MAC address). 329 Each Endpoint Address has an associated Address Type, which indicates 330 both its syntax and semantics. 332 2.3. Network Location 334 Network Location is a generic term denoting a single Endpoint or a 335 group of Endpoints. For instance, it can be a single IPv4 or IPv6 336 address, an IPv4 or IPv6 prefix, or a set of prefixes. 338 2.4. ALTO Information 340 ALTO Information is a generic term referring to the network 341 information sent by an ALTO Server. 343 2.5. ALTO Information Base 345 This document uses the term ALTO Information Base to refer to the 346 internal representation of ALTO Information maintained by an ALTO 347 Server. Note that the structure of this internal representation is 348 not defined by this document. 350 2.6. ALTO Service 352 A network that provides ALTO Information through the ALTO Protocol is 353 said to provide the ALTO Service. 355 3. Architecture 357 This section defines the ALTO architecture and the ALTO Protocol's 358 place in the overall architecture. 360 3.1. ALTO Service and Protocol Scope 362 Each network region in the global Internet can provide its ALTO 363 Service, which conveys network information from the perspective of 364 that network region. A network region in this context can be an 365 Autonomous System (AS), an ISP, a region smaller than an AS or ISP, 366 or a set of ISPs. The specific network region that an ALTO Service 367 represents will depend on the ALTO deployment scenario and ALTO 368 service discovery mechanism. 370 The ALTO Service specified in this document defines network Endpoints 371 (and aggregations thereof) and generic costs amongst them from the 372 region's perspective. The network Endpoints may include all 373 Endpoints in the global Internet. We say that the network 374 information provided by the ALTO Service of a network region 375 represents the "my-Internet view" of the network region. 377 The "my-Internet view" defined in this document does not specify the 378 internal topology of a network, and hence, it is said to provide a 379 "single-node" abstract topology. Extensions to this document may 380 provide topology details in "my-Internet view". 382 Figure 1 provides an overall picture of ALTO's system architecture, 383 so that one can better understand the ALTO Service and the role of 384 the ALTO Protocol. In this architecture, an ALTO Server prepares 385 ALTO Information; an ALTO Client uses ALTO Service Discovery to 386 identify an appropriate ALTO Server; and the ALTO Client requests 387 available ALTO Information from the ALTO Server using the ALTO 388 Protocol. 390 The ALTO Information provided by the ALTO Server can be updated 391 dynamically based on network conditions, or can be seen as a policy 392 which is updated at a larger time-scale. 394 +-------------------------------------------------------------------+ 395 | Network Region | 396 | | 397 | +-----------+ | 398 | | Routing | | 399 | +--------------+ | Protocols | | 400 | | Provisioning | +-----------+ | 401 | | Policy | | | 402 | +--------------+\ | | 403 | \ | | 404 | \ | | 405 | +-----------+ \+---------+ +--------+ | 406 | |Dynamic | | ALTO | ALTO Protocol | ALTO | | 407 | |Network |.......| Server | ==================== | Client | | 408 | |Information| +---------+ +--------+ | 409 | +-----------+ / / | 410 | / ALTO SD Query/Response / | 411 | / / | 412 | +----------+ +----------------+ | 413 | | External | | ALTO Service | | 414 | | Interface| | Discovery (SD) | | 415 | +----------+ +----------------+ | 416 | | | 417 +-------------------------------------------------------------------+ 418 | 419 +------------------+ 420 | Third Parties | 421 | | 422 | Content Providers| 423 +------------------+ 425 Figure 1: Basic ALTO Architecture. 427 Figure 1 illustrates that the ALTO Information provided by an ALTO 428 Server may be influenced (at the service provider's discretion) by 429 other systems. In particular, the ALTO Server can aggregate 430 information from multiple systems to provide an abstract and unified 431 view that can be more useful to applications. Examples of other 432 systems include (but are not limited to) static network configuration 433 databases, dynamic network information, routing protocols, 434 provisioning policies, and interfaces to outside parties. These 435 components are shown in the figure for completeness but are outside 436 the scope of this specification. Recall that while the ALTO Protocol 437 may convey dynamic network information, it is not intended to replace 438 near-real-time congestion control protocols. 440 It may also be possible for an ALTO Server to exchange network 441 information with other ALTO Servers (either within the same 442 administrative domain or another administrative domain with the 443 consent of both parties) in order to adjust exported ALTO 444 Information. Such a protocol is also outside the scope of this 445 specification. 447 3.2. ALTO Information Reuse and Redistribution 449 ALTO Information may be useful to a large number of applications and 450 users. At the same time, distributing ALTO Information must be 451 efficient and not become a bottleneck. 453 The design of the ALTO Protocol allows integration with the existing 454 HTTP caching infrastructure to redistribute ALTO Information. If 455 caching or redistribution is used, the response message to an ALTO 456 Client may be returned from a third-party. 458 Application-dependent mechanisms, such as P2P DHTs or P2P file- 459 sharing, may be used to cache and redistribute ALTO Information. 460 This document does not define particular mechanisms for such 461 redistribution. 463 Additional protocol mechanisms (e.g., expiration times and digital 464 signatures for returned ALTO information) are left for future 465 investigation. 467 4. ALTO Information Service Framework 469 The ALTO Protocol conveys network information through services, where 470 each service defines a set of related functionalities. An ALTO 471 Client can request each service individually. All of the services 472 defined in ALTO are said to form the ALTO service framework and are 473 provided through a common transport protocol, messaging structure and 474 encoding, and transaction model. Functionalities offered in 475 different services can overlap. 477 The goals of the services defined in this document are to convey (1) 478 Network Locations, which denote the locations of Endpoints at a 479 network, (2) provider-defined costs for paths between pairs of 480 Network Locations, and (3) network related properties of endhosts. 481 The aforementioned goals are achieved by defining the Map Service, 482 which provides the core ALTO information to clients, and three 483 additional services: the Map Filtering Service, Endpoint Property 484 Service, and Endpoint Cost Service. Additional services can be 485 defined in companion documents. Figure 2 gives an overview of the 486 services. Details of the services are presented in subsequent 487 sections. 489 .-----------------------------------------. 490 | ALTO Information Services | 491 | .-----------. .----------. .----------. | 492 | | Map | | Endpoint | | Endpoint | | 493 | | Filtering | | Property | | Cost | | 494 | | Service | | Service | | Service | | 495 | `-----------' `----------' `----------' | 496 | .-------------------------------------. | 497 | | Map Service | | 498 | | .-------------. .--------------. | | 499 | | | Network Map | | Cost Map | | | 500 | | `-------------' `--------------' | | 501 | `-------------------------------------' | 502 `-----------------------------------------' 504 Figure 2: ALTO Service Framework. 506 4.1. ALTO Information Services 508 4.1.1. Map Service 510 The Map Service provides batch information to ALTO Clients in the 511 form of Network Map and Cost Map. A Network Map (See Section 5) 512 provides a full set of Network Location groupings defined by the ALTO 513 Server and the Endpoints contained within each grouping. A Cost Map 514 (see Section 6) provides costs between a defined grouping. 516 These two maps can be thought of (and implemented as) as simple files 517 with appropriate encoding provided by the ALTO Server. 519 4.1.2. Map Filtering Service 521 Resource constrained ALTO Clients may benefit from filtering of query 522 results at the ALTO Server. This avoids that an ALTO Client first 523 spends network bandwidth and CPU cycles to collect results and then 524 performs client-side filtering. The Map Filtering Service allows 525 ALTO Clients to query an ALTO Server on Network Map and Cost Map 526 based on additional parameters. 528 4.1.3. Endpoint Property Service 530 This service allows ALTO Clients to look up properties for individual 531 Endpoints. An example property of an Endpoint is its Network 532 Location (i.e., its grouping defined by the ALTO Server). Another 533 example property is its connectivity type such as ADSL (Asymmetric 534 Digital Subscriber Line), Cable, or FTTH (Fiber To The Home). 536 4.1.4. Endpoint Cost Service 538 Some ALTO Clients may also benefit from querying for costs and 539 rankings based on Endpoints. The Endpoint Cost Service allows an 540 ALTO Server to return either numerical costs or ordinal costs 541 (rankings) directly amongst Endpoints. 543 5. Network Map 545 An ALTO Network Map defines a grouping of network endpoints. This 546 document uses Network Map to refer to the syntax and semantics of how 547 an ALTO Server distributes the grouping. This document does not 548 discuss the internal representation of this data structure within the 549 ALTO Server. 551 The definition of Network Map is based on the observation that in 552 reality, many endpoints are close by to one another in terms of 553 network connectivity. By treating a group of close-by endpoints 554 together as a single entity, an ALTO Server indicates aggregation of 555 these endpoints due to their proximity. This aggregation can also 556 lead to greater scalability without losing critical information when 557 conveying other network information (e.g., when defining Cost Map). 559 5.1. Provider-defined Identifier (PID) 561 One issue is that proximity varies depending on the granularity of 562 the ALTO information configured by the provider. In one deployment, 563 endpoints on the same subnet may be considered close; while in 564 another deployment, endpoints connected to the same Point of Presence 565 (PoP) may be considered close. 567 ALTO introduces provider-defined Network Location identifiers called 568 Provider-defined Identifiers (PIDs) to provide an indirect and 569 network-agnostic way to specify an aggregation of network endpoints 570 that may be treated similarly, based on network topology, type, or 571 other properties. Specifically, a PID is a string of type PIDName 572 (see Section 10.1) and its associated set of Endpoint Addresses. As 573 discussed above, there can be many different ways of grouping the 574 endpoints and assigning PIDs. For example, a PID may denote a 575 subnet, a set of subnets, a metropolitan area, a PoP, an autonomous 576 system, or a set of autonomous systems. Interpreting the PIDs 577 defined in a Network Map using the "single-node" abstraction, one can 578 consider that each PID represents an abstract port (PoP) that 579 connects a set of endpoints. 581 A key use case of PIDs is to specify network preferences (costs) 582 between PIDs instead of individual endpoints. This allows cost 583 information to be more compactly represented and updated at a faster 584 time scale than the network aggregations themselves. For example, an 585 ISP may prefer that endpoints associated with the same PoP (Point-of- 586 Presence) in a P2P application communicate locally instead of 587 communicating with endpoints in other PoPs. The ISP may aggregate 588 endhosts within a PoP into a single PID in the Network Map. The cost 589 may be encoded to indicate that Network Locations within the same PID 590 are preferred; for example, cost(PID_i, PID_i) == c and cost(PID_i, 591 PID_j) > c for i != j. Section 6 provides further details on using 592 PIDs to represent costs in an ALTO Cost Map. 594 5.2. Endpoint Addresses 596 The endpoints aggregated into a PID are denoted by endpoint 597 addresses. There are many types of addresses, such as IP addresses, 598 MAC addresses, or overlay IDs. This document specifies in Section 599 10.4 how to specify IPv4/IPv6 addresses or prefixes. Extension 600 documents may define further address types; Section 14.4 of this 601 document provides an IANA registry for endpoint address types. 603 5.3. Example Network Map 605 This document uses the Network Map shown in Figure 3 in most 606 examples. 608 .------------------------------------------------------------. 609 | An ALTO Network Map | 610 | | 611 | .-----------------------------------. .----------------. | 612 | | NetLoc: PID-1 | | NetLoc: PID-3 | | 613 | | .------------------------------. | | | | 614 | | | 192.0.2.0/24 | | | .-----------. | | 615 | | | .--------------------------. | | | | 0.0.0.0/0 | | | 616 | | | | Endpoint: 192.0.2.34 | | | | `-----------` | | 617 | | | `--------------------------` | | | | | 618 | | `------------------------------` | | | | 619 | | .------------------------------. | | | | 620 | | | 198.51.100.0/25 | | | | | 621 | | | .--------------------------. | | | | | 622 | | | | Endpoint: 198.51.100.100 | | | | | | 623 | | | `--------------------------` | | | | | 624 | | `------------------------------` | | | | 625 | `-----------------------------------` | | | 626 | | | | 627 | .-----------------------------------. | | | 628 | | NetLoc: PID-2 | | | | 629 | | .------------------------------. | | | | 630 | | | 198.51.100.128/25 | | | | | 631 | | `------------------------------` | | | | 632 | `-----------------------------------` `----------------` | 633 `------------------------------------------------------------` 635 Figure 3: Example Network Map. 637 6. Cost Map 639 An ALTO Server indicates preferences amongst network locations in the 640 form of Path Costs. Path Costs are generic costs and can be 641 internally computed by a network provider according to its own 642 policy. 644 For a given Network Map, an ALTO Cost Map defines Path Costs pairwise 645 amongst sets of source and destination Network Locations defined by 646 PIDs defined in the Network Map. Each Path Cost is the end-to-end 647 cost when a unit of traffic goes from the source to the destination. 649 Since cost is directional from the source to the destination, an 650 application, when using ALTO Information, may independently determine 651 how the Resource Consumer and Resource Provider are designated as the 652 source or destination in an ALTO query, and hence how to utilize the 653 Path Cost provided by ALTO Information. For example, if the cost is 654 expected to be correlated with throughput, a typical application 655 concerned with bulk data retrieval may use the Resource Provider as 656 the source, and Resource Consumer as the destination. 658 One advantage of separating ALTO information into a Network Map and a 659 Cost Map is that the two components can be updated at different time 660 scales. For example, Network Maps may be stable for a longer time 661 while Cost Maps may be updated to reflect dynamic network conditions. 663 As used in this document, a Cost Map refers to the syntax and 664 semantics of the information distributed by the ALTO Server. This 665 document does not discuss the internal representation of this data 666 structure within the ALTO Server. 668 6.1. Cost Types 670 Path Costs have attributes: 672 o Metric: identifies what the costs represent; 674 o Mode: identifies how the costs should be interpreted. 676 The combination of a metric and a mode defines a Cost Type. Certain 677 queries for Cost Maps allow the ALTO Client to indicate the desired 678 Cost Type. For a given ALTO Server, the combination of Cost Type and 679 Network Map defines a key. In other words, an ALTO Server MUST NOT 680 define two Cost Maps with the same Cost Type, Network Map pair. 682 6.1.1. Cost Metric 684 The Metric attribute indicates what the cost represents. For 685 example, an ALTO Server could define costs representing air-miles, 686 hop-counts, or generic routing costs. 688 Cost metrics are indicated in protocol messages as strings. 690 6.1.1.1. Cost Metric: routingcost 692 An ALTO Server MUST offer the 'routingcost' Cost Metric. 694 This Cost Metric conveys a generic measure for the cost of routing 695 traffic from a source to a destination. A lower value indicates a 696 higher preference for traffic to be sent from a source to a 697 destination. 699 Note that an ISP may internally compute routing cost using any method 700 that it chooses (e.g., air-miles or hop-count) as long as it conforms 701 to these semantics. 703 6.1.2. Cost Mode 705 The Mode attribute indicates how costs should be interpreted. 706 Specifically, the Mode attribute indicates whether returned costs 707 should be interpreted as numerical values or ordinal rankings. 709 It is important to communicate such information to ALTO Clients, as 710 certain operations may not be valid on certain costs returned by an 711 ALTO Server. For example, it is possible for an ALTO Server to 712 return a set of IP addresses with costs indicating a ranking of the 713 IP addresses. Arithmetic operations that would make sense for 714 numerical values, do not make sense for ordinal rankings. ALTO 715 Clients may handle such costs differently. 717 Cost Modes are indicated in protocol messages as strings. 719 An ALTO Server MUST support at least one of 'numerical' and 'ordinal' 720 modes. An ALTO Client needs to be cognizant of operations when its 721 desired Cost Mode is not supported. Specifically, an ALTO Client 722 desiring numerical costs MAY adjust its behaviors if only the ordinal 723 Cost Mode is available. Alternatively, an ALTO Client desiring 724 ordinal costs MAY construct ordinal costs from retrieved numerical 725 values, if only the numerical Cost Mode is available. 727 6.1.2.1. Cost Mode: numerical 729 This Cost Mode is indicated by the string 'numerical'. This mode 730 indicates that it is safe to perform numerical operations (e.g. 731 normalization or computing ratios for weighted load-balancing) on the 732 returned costs. The values are floating-point numbers. 734 6.1.2.2. Cost Mode: ordinal 736 This Cost Mode is indicated by the string 'ordinal'. This mode 737 indicates that the costs values in a Cost Map represent a ranking 738 (relative to all other values in a Cost Map), not actual costs. The 739 values are non-negative integers, with a lower value indicating a 740 higher preference. Ordinal cost values in a Cost Map need not be 741 unique nor contiguous. In particular, it is possible that two 742 entries in a map have an identical rank (ordinal cost value). This 743 document does not specify any behavior by an ALTO Client in this 744 case; an ALTO Client may decide to break ties by random selection, 745 other application knowledge, or some other means. 747 6.2. Cost Map Structure 749 A request for a Cost Map either explicitly or implicitly includes a 750 list of Source Network Locations and a list of Destination Network 751 Locations. (Recall that a Network Location can be an endpoint 752 address or a PID.) 754 Specifically, assume that a request specifies a list of multiple 755 Source Network Locations, say [Src_1, Src_2, ..., Src_m], and a list 756 of multiple Destination Network Locations, say [Dst_1, Dst_2, ..., 757 Dst_n]. 759 The ALTO Server will return the Path Cost for each of the m*n 760 communicating pairs (i.e., Src_1 -> Dst_1, ..., Src_1 -> Dst_n, ..., 761 Src_m -> Dst_1, ..., Src_m -> Dst_n). If the ALTO Server does not 762 define a Path Cost for a particular pair, it may be omitted. This 763 document refers to this structure as a Cost Map. 765 If the Cost Mode is 'ordinal', the Path Cost of each communicating 766 pair is relative to the m*n entries. 768 6.3. Network Map and Cost Map Dependency 770 A Cost Map gives Path Costs between the PIDs defined in a Network 771 Map. An ALTO Server may modify a Network Map at any time, say by 772 adding or deleting PIDs, or even redefining them. Hence to 773 effectively use an instance of a Cost Map, an ALTO Client must know 774 which version of the Network Map defined the PIDs in that Cost Map. 775 Version Tags allow ALTO Clients to correlate Cost Map instances with 776 the corresponding versions of the Network Map. 778 A Version Tag is a tuple of (1) an ID for the resource (e.g., a 779 Network Map), and (2) a tag (an opaque string) associated with the 780 version of that resource. A Network Map distributed by an ALTO 781 Server includes its Version Tag. A Cost Map referring to PIDs also 782 includes Version Tag for the Network Map on which it is based. 784 Two Network Maps are the same if they have the same Version Tag. 785 Whenever the content of the Network Map maintained by an ALTO Server 786 changes, tag MUST also be changed. Possibilities of setting the tag 787 component include the last-modified timestamp for the Network Map, or 788 a hash of its contents, where the collision probability is considered 789 zero in practical deployment scenarios. 791 6.4. Cost Map Update 793 An ALTO Server can update a Cost Map at any time. Hence, the same 794 Cost Map retrieved from the same ALTO Server but from different 795 requests can be inconsistent. 797 7. Endpoint Properties 799 An endpoint property defines a network-aware property of an endpoint. 801 7.1. Endpoint Property Type 803 For each endpoint and an endpoint property type, there can be a value 804 for the property. The type of an Endpoint property is indicated in 805 protocol messages as a string. The value depends on the specific 806 property. For example, for a property such as whether an endpoint is 807 metered, the value is a true or false value. 809 7.1.1. Endpoint Property Type: pid 811 An ALTO Server MUST define the 'pid' Endpoint Property Type for each 812 Network Map that it provides. Specifically, each Network Map defines 813 multiple PIDs. For an 'ipv4'/'ipv6' Network Map, given an endpoint's 814 IP address, the ALTO Server uses the algorithm specified in 815 Section 11.2.2 to lookup the PID of the endpoint. This PID is the 816 'pid' property of the endpoint for the Network Map. See 817 Section 11.4.1.7 for an example. 819 8. Protocol Specification: General Processing 821 This section first specifies general client and server processing. 822 The details of specific services will be covered in the following 823 sections. 825 8.1. Overall Design 827 The ALTO Protocol uses a REST-ful design. There are two primary 828 components to this design: 830 o Information Resources: An ALTO Server provides a set of network 831 information resources. Each information resource has a media type 832 [RFC2046]. An ALTO Client may construct an HTTP request for a 833 particular information resource (including any parameters, if 834 necessary), and the ALTO Server returns the requested information 835 resource in an HTTP response. 837 o Information Resource Directory (IRD): An ALTO Server provides to 838 ALTO Clients a list of available information resources and the URI 839 at which each is provided. This document refers to this list as 840 the Information Resource Directory. ALTO Clients consult the 841 directory to determine the services provided by an ALTO Server. 843 8.2. Notation 845 This document uses 'JSONString', 'JSONNumber', 'JSONBool' to indicate 846 the JSON string, number, and boolean types, respectively. The type 847 'JSONValue' indicates a JSON value, as specified in Section 2.1 of 848 [RFC4627]. 850 This document uses an adaptation of the C-style struct notation to 851 define the fields (names/values) of JSON objects. An optional field 852 is enclosed by [ ], and an array is indicated by two numbers in angle 853 brackets, , where m indicates the minimal number of values, and 854 n is the maximum. When this document writes * for n, it means no 855 upper bound. In the definitions, the JSON names of the fields are 856 case sensitive. 858 For example, the definition below defines a new type Type4, with 859 three field members (or fields for short) named "name1", "name2", and 860 "name3" respectively. The field named "name3" is optional, and the 861 field named "name2" is an array of at least one value. 862 object { Type1 name1; Type2 name2<1..*>; [Type3 name3;] 863 } Type4; 865 This document also defines dictionary maps (or maps for short) from 866 strings to JSON values. For example, the definition below defines a 867 Type3 object as a map. Type1 must be defined as string, and Type2 868 can be defined as any type. 869 object-map { Type1 -> Type2; } Type3; 871 This document uses subtyping to denote that one type is derived from 872 another type. The example below denotes that TypeDerived is derived 873 from TypeBase. TypeDerived includes all fields defined in TypeBase. 874 If TypeBase does not have a field named "name1", TypeDerived will 875 have a new field named "name1". If TypeBase already has a field 876 named "name1" but with a different type, TypeDerived will have a 877 field named "name1" with the type defined in TypeDerived (i.e., Type1 878 in the example). 879 object { Type1 name1; } TypeDerived : TypeBase; 881 Note that despite the notation, no standard, machine-readable 882 interface definition or schema is provided in this document. 883 Extension documents may document these as necessary. 885 8.3. Basic Operations 887 The ALTO Protocol employs standard HTTP [RFC2616]. It is used for 888 discovering available Information Resources at an ALTO Server and 889 retrieving Information Resources. ALTO Clients and ALTO Servers use 890 HTTP requests and responses carrying ALTO-specific content with 891 encoding as specified in this document, and MUST be compliant with 892 [RFC2616]. 894 Instead of specifying the generic application/json Media Type for all 895 ALTO request parameters (if any) and responses, ALTO Clients and 896 Servers use multiple, specific JSON-based Media Types (e.g., 897 application/alto-networkmap+json, application/alto-costmap+json) to 898 indicate content types; see Table 2 for a list of Media Types defined 899 in this document. This allows easy extensibility while maintaining 900 clear semantics and versioning. For example, a new version of a 901 component of the ALTO Protocol (e.g., a new version of the Network 902 Map) can be defined by simply introducing a new Media Type (e.g., 903 application/alto-networkmap-v2+json). 905 8.3.1. Client Discovering Information Resources 907 To discover available Information Resources, an ALTO Client requests 908 Information Resource Directories. Informally, an Information 909 Resource Directory enumerates URIs at which an ALTO Server offers 910 Information Resources. 912 Specifically, using the ALTO Discovery protocol, an ALTO Client 913 obtains a URI through which it can request an Information Resource 914 Directory (IRD). This document refers to this IRD as the Root IRD of 915 the ALTO Client. Each entry in an IRD indicates a URI at which an 916 ALTO Server accepts requests, and returns either an Information 917 Resource or an Information Resource Directory that references 918 additional Information Resources. Beginning with its Root IRD and 919 following links to IRDs recursively, an ALTO Client can discover all 920 Information Resources available to it. This set of Information 921 Resources is referred to as the Information Resource Closure of the 922 ALTO Client. By inspecting its Information Resource Closure, an ALTO 923 Client can determine whether an ALTO Server supports the desired 924 Information Resource, and if it is supported, the URI at which it is 925 available. 927 See Section 9.2 for a detailed specification on IRDs. 929 8.3.2. Client Requesting Information Resources 931 Where possible, the ALTO Protocol uses the HTTP GET method to request 932 resources. However, some ALTO services provide Information Resources 933 that are the function of one or more input parameters. Input 934 parameters are encoded in the HTTP request's entity body, and the 935 ALTO Client MUST use the HTTP POST method to send the parameters. 937 When requesting an ALTO Information Resource that requires input 938 parameters specified in a HTTP POST request, an ALTO Client MUST set 939 the Content-Type HTTP header to the media type corresponding to the 940 format of the supplied input parameters. 942 8.3.3. Server Responding to IR Request 944 Upon receiving a request for an Information Resource that the ALTO 945 Server can provide, the ALTO Server normally returns the requested 946 Information Resource. In other cases, to be more informative 947 ([I-D.ietf-httpbis-p2-semantics]), the ALTO Server either provides 948 the ALTO Client with an Information Resource Directory indicating how 949 to reach the desired information resource, or returns an ALTO error 950 object; see Section 8.5 for more details on ALTO error handling. 952 It is possible for an ALTO Server to leverage caching HTTP 953 intermediaries to respond to both GET and POST requests by including 954 explicit freshness information (see Section 14 of [RFC2616]). 955 Caching of POST requests is not widely implemented by HTTP 956 intermediaries, however an alternative approach is for an ALTO 957 Server, in response to POST requests, to return an HTTP 303 status 958 code ("See Other") indicating to the ALTO Client that the resulting 959 Information Resource is available via a GET request to an alternate 960 URL. HTTP intermediaries that do not support caching of POST 961 requests could then cache the response to the GET request from the 962 ALTO Client following the alternate URL in the 303 response if the 963 response to the subsequent GET request contains explicit freshness 964 information. 966 The ALTO Server MUST indicate the type of its response using a media 967 type (i.e., the Content-Type HTTP header of the response). 969 8.3.4. Client Handling Server Response 971 8.3.4.1. Using Information Resources 973 This specification does not indicate any required actions taken by 974 ALTO Clients upon successfully receiving an Information Resource from 975 an ALTO Server. Although ALTO Clients are suggested to interpret the 976 received ALTO Information and adapt application behavior, ALTO 977 Clients are not required to do so. 979 8.3.4.2. Handling Server Response and IRD 981 After receiving an Information Resource Directory, the Client can 982 consult it to determine if any of the offered URIs contain the 983 desired Information Resource. However, an ALTO Client MUST NOT 984 assume that the media type returned by the ALTO Server for a request 985 to a URI is the media type advertised in the IRD or specified in its 986 request (i.e., the client must still check the Content-Type header). 988 The expectation is that the media type returned should normally be 989 the media type advertised and requested, but in some cases it may 990 legitimately not be so. 992 In particular, it is possible for an ALTO Client to receive an 993 Information Resource Directory from an ALTO Server as a response to 994 its request for a specific Information Resource. In this case, the 995 ALTO Client may ignore the response or still parse the response. To 996 indicate that an ALTO Client will always check if a response is an 997 Information Resource Directory, the ALTO Client can indicate in the 998 "Accept" header of a HTTP request that it can accept Information 999 Resource Directory; see Section 9.2 for the media type. 1001 8.3.4.3. Handling Error Conditions 1003 If an ALTO Client does not successfully receive a desired Information 1004 Resource from a particular ALTO Server (i.e., server response 1005 indicates error or there is no response), the Client can either 1006 choose another server (if one is available) or fall back to a default 1007 behavior (e.g., perform peer selection without the use of ALTO 1008 information, when used in a peer-to-peer system). 1010 8.3.5. Authentication and Encryption 1012 ALTO server implementations as well as ALTO client implementations 1013 MUST support the "https" URI scheme [RFC2818] and TLS [RFC5246]. See 1014 Section 15.1.2 for security considerations and Section 16 for 1015 manageability considerations regarding the usage of HTTPS/TLS. 1017 For deployment scenarios where client authentication is desired, HTTP 1018 Digest Authentication MUST be supported. TLS Client Authentication 1019 is the preferred mechanism if it is available. 1021 8.3.6. Information Refreshing 1023 An ALTO Client can determine the frequency at which ALTO Information 1024 is refreshed based on information made available via HTTP. 1026 8.3.7. Parsing of Unknown Fields 1028 This document only details object fields used by this specification. 1029 Extensions may include additional fields within JSON objects defined 1030 in this document. ALTO implementations MUST ignore unknown fields 1031 when processing ALTO messages. 1033 8.4. Server Response Encoding 1035 Though each type of ALTO Server response (i.e., an Information 1036 Resource Directory, an individual Information Resource, or an error 1037 message) has its distinct syntax and hence its unique Media Type, 1038 they are designed to have a similar structure: a meta field providing 1039 meta definitions, and another field containing the data, if needed. 1041 Specifically, this document defines the base type of each ALTO Server 1042 response as ResponseEntityBase: 1043 object { ResponseMeta meta; } ResponseEntityBase; 1045 with field: 1047 meta meta information pertaining to the response. 1049 8.4.1. Meta Information 1051 Meta information is encoded as a map object for flexibility. 1052 Specifically, ResponseMeta is defined as: 1053 object-map { JSONString -> JSONValue } ResponseMeta; 1055 8.4.2. Data Information 1057 The data component of the response encodes the response-specific 1058 data. This document derives five types from ResponseEntityBase to 1059 add different types of data component: InfoResourceDirectory 1060 (Section 9.2.2), InfoResourceNetworkMap (Section 11.2.1.6), 1061 InfoResourceCostMap (Section 11.2.3.6), 1062 InfoResourceEndpointProperties (Section 11.4.1.6), and 1063 InfoResourceEndpointCostMap (Section 11.5.1.6). 1065 8.5. Protocol Errors 1067 If there is an error processing a request, an ALTO Server SHOULD 1068 return additional ALTO-layer information, if it is available, in the 1069 form of an ALTO Error Resource encoded in the HTTP response' entity 1070 body. If no ALTO-layer information is available, an ALTO Server may 1071 omit an ALTO Error resource from the response. 1073 With or without additional ALTO-layer error information, an ALTO 1074 Server MUST set an appropriate HTTP status code. It is important to 1075 note that the HTTP Status Code and ALTO Error Resource have distinct 1076 roles. An ALTO Error Resource provides detailed information about 1077 why a particular request for an ALTO Resource was not successful. 1078 The HTTP status code indicates to HTTP processing elements (e.g., 1079 intermediaries and clients) how the response should be treated. 1081 8.5.1. Media Type 1083 The media type for an ALTO Error Response is "application/ 1084 alto-error+json". 1086 8.5.2. Response Format and Error Codes 1088 An ALTO Error Response MUST include the "code" key in the "meta" 1089 field of the response. The value of "code" MUST be an ALTO Error 1090 Code, encoded in string, defined in Table 1. Note that the ALTO 1091 Error Codes defined in Table 1 are limited to support the error 1092 conditions needed for purposes of this document. Additional status 1093 codes may be defined in companion or extension documents. 1095 +-----------------------+-------------------------------------------+ 1096 | ALTO Error Code | Description | 1097 +-----------------------+-------------------------------------------+ 1098 | E_SYNTAX | Parsing error in request (including | 1099 | | identifiers) | 1100 | E_MISSING_FIELD | A required JSON field is missing | 1101 | E_INVALID_FIELD_TYPE | The type of the value of a JSON field is | 1102 | | invalid | 1103 | E_INVALID_FIELD_VALUE | The value of a JSON field is invalid | 1104 +-----------------------+-------------------------------------------+ 1106 Table 1: Defined ALTO Error Codes. 1108 After an ALTO Server receives a request, it needs to verify the 1109 syntactic and semantic validity of the request. The following 1110 paragraphs in this section are intended to illustrate the usage of 1111 the error codes defined above during the verification. An individual 1112 implementation may define its message processing in a different 1113 order. 1115 In the first step after an ALTO Server receives a request, it checks 1116 the syntax of the request body (i.e., whether the JSON structure can 1117 be parsed), and indicates a syntax error using the error code 1118 E_SYNTAX. For an E_SYNTAX error, the ALTO Server MAY provide an 1119 optional key "syntax-error" in the "meta" field of the error 1120 response. The objective of providing "syntax-error" is to provide 1121 technical debugging information to developers, not end users. Hence, 1122 it should be a human-readable, free-form text describing the syntax 1123 error. If possible, the text should include position information 1124 such as line number and offset within line about the syntax error. 1125 If nothing else, "syntax-error" could have just the position. If a 1126 syntax error occurs in a production environment, the ALTO Client 1127 could inform the end user that there was an error communicating with 1128 the ALTO Server, and suggest that the user submit the error 1129 information, which includes "syntax-error", to the developers. 1131 A request without syntax errors may still be invalid. An error case 1132 is that the request misses a required field. The server indicates 1133 such an error using the error code E_MISSING_FIELD. This document 1134 defines required fields for Network Map Filtering (Section 11.3.1.3), 1135 Cost Map Filtering (Section 11.3.2.3), Endpoint Properties 1136 (Section 11.4.1.3), and Endpoint Cost (Section 11.5.1.3). For an 1137 E_MISSING_FIELD error, the server may include an optional "field" key 1138 in the "meta" field of the error response, to indicate the missing 1139 field. "field" should be a JSONString indicating the full path of the 1140 missing field. For example, assume that a Filtered CostMap request 1141 (see Section 11.3.2.3) misses the "cost-metric" field in the request. 1142 The error response from the ALTO Server may specify the "field" key 1143 as "cost-type/cost-mode". 1145 A request with the correct fields might use a wrong type for the 1146 value of a field. For example, the value of a field could be a 1147 JSONString when a JSONNumber is expected. The server indicates such 1148 an error using the error code E_INVALID_FIELD_TYPE. The server may 1149 include an optional "field" key in the "meta" field of the response, 1150 to indicate the field that contains the wrong type. 1152 A request with the correct fields and types of values for the fields 1153 may specify a wrong value for a field. For example, a cost map 1154 filtering request may specify a wrong value of CostMode in the "cost- 1155 type" field (Section 11.3.2.3). The server indicates such an error 1156 with the error code E_INVALID_FIELD_VALUE. For an 1157 E_INVALID_FIELD_VALUE error, the server may include an optional 1158 "field" key in the "meta" field of the response, to indicate the 1159 field that contains the wrong value. The server may also include an 1160 optional "value" key in the "meta" field of the response to indicate 1161 the wrong value that triggered the error. 1163 A request with the correct fields and types of values for the fields 1164 may specify a wrong value for a field. For example, a filtered cost 1165 map request may specify a wrong value for CostMode in the "cost-type" 1166 field (Section 11.3.2.3). The server indicates such an error with 1167 the error code E_INVALID_FIELD_VALUE. For an E_INVALID_FIELD_VALUE 1168 error, the server may include an optional "field" key in the "meta" 1169 field of the response, to indicate the field that contains the wrong 1170 value. The server may also include an optional "value" key in the 1171 "meta" field of the response to indicate the wrong value that 1172 triggered the error. If the "value" key is specified, the "field" 1173 key MUST be specified. The "value" key MUST have a JSONString value. 1174 If the invalid value is not a string, the ALTO Server MUST convert it 1175 to a string. Below are the rules to specify the "value" key: 1177 o If the invalid value is a string, "value" is that string; 1179 o If the invalid value is a number, "value" must be the invalid 1180 number as a string; 1182 o If the invalid value is a subfield, the server must set the 1183 "field" key to the full path of the field name and "value" to the 1184 invalid subfield value, converting it to a string if needed. For 1185 example, if the "cost-mode" subfield of the "cost-type" field is 1186 an invalid mode "foo", the server should set "value" to "foo", and 1187 "field" to "cost-mode/cost-type"; 1189 o If an element of a JSON array has an invalid value, the server 1190 sets "value" to the value of the invalid element, as a string, and 1191 "field" to the name of the array. An array element of the wrong 1192 type (e.g., a number in what is supposed to be an array of 1193 strings) is an invalid value error, not an invalid type error. 1194 The server sets "value" to the string version of the incorrect 1195 element, and "field" to the name of the array. 1197 If multiple errors are present in a single request (e.g., a request 1198 uses a JSONString when a JSONNumber is expected and a required field 1199 is missing), then the ALTO Server MUST return exactly one of the 1200 detected errors. However, the reported error is implementation 1201 defined, since specifying a particular order for message processing 1202 encroaches needlessly on implementation techniques. 1204 8.5.3. Overload Conditions and Server Unavailability 1206 If an ALTO Server detects that it cannot handle a request from an 1207 ALTO Client due to excessive load, technical problems, or system 1208 maintenance, it SHOULD do one of the following: 1210 o Return an HTTP 503 ("Service Unavailable") status code to the ALTO 1211 Client. As indicated by [RFC2616], the Retry-After HTTP header 1212 may be used to indicate when the ALTO Client should retry the 1213 request. 1215 o Return an HTTP 307 ("Temporary Redirect") status code indicating 1216 an alternate ALTO Server that may be able to satisfy the request. 1217 Using Temporary Redirect may generate infinite redirection loops. 1218 Although [RFC2616] Section 10.3 requires that an HTTP client 1219 SHOULD detect infinite redirection loops, it is more desirable 1220 that multiple ALTO Servers are configured to not form redirection 1221 loops. 1223 The ALTO Server MAY also terminate the connection with the ALTO 1224 Client. 1226 The particular policy applied by an ALTO Server to determine that it 1227 cannot service a request is outside of the scope of this document. 1229 9. Protocol Specification: Information Resource Directory 1231 As already discussed, an ALTO Client starts by retrieving an 1232 Information Resource Directory, which specifies the attributes of 1233 individual Information Resources that an ALTO Server provides. 1235 9.1. Information Resource Attributes 1237 In this document, each Information Resource has five attributes 1238 associated with it, including its assigned ID, its response format, 1239 its capabilities, its accepted input parameters, and other resources 1240 that it may depend on. The function of an Information Resource 1241 Directory is to publishes these attributes. 1243 9.1.1. Resource ID 1245 Each Information Resource that an ALTO Client can request MUST be 1246 assigned an ID that is unique amongst all Information Resources in 1247 the Information Resource Closure of the client. The ID SHOULD remain 1248 stable even when the data provided by that resource changes. For 1249 example, even though the number of PIDs in a Network Map may be 1250 adjusted, its Resource ID should remain the same. Similarly, if the 1251 entries in a Cost Map are updated, its Resource ID should remain the 1252 same. IDs SHOULD NOT be re-used for different resources over time. 1254 9.1.2. Media Type 1256 ALTO uses Media Type [RFC2046] to uniquely indicate the data format 1257 used to encode the content to be transmitted between an ALTO Server 1258 and an ALTO Client in the HTTP entity body. 1260 9.1.3. Capabilities 1262 The Capabilities attribute of an Information Resource indicates 1263 specific capabilities that the server can provide. For example, if 1264 an ALTO Server allows an ALTO Client to specify cost constraints when 1265 the Client requests a Cost Map Information Resource, then the Server 1266 advertises the cost-constraints capability of the Cost Map 1267 Information Resource. 1269 9.1.4. Accepts Input Parameters 1271 An ALTO Server may allow an ALTO Client to supply input parameters 1272 when requesting certain Information Resources. The associated 1273 accepts attribute of an Information Resource is a Media Type, which 1274 indicates how the Client specifies the input parameters as contained 1275 in the entity body of the HTTP POST request. 1277 9.1.5. Dependent Resources 1279 The information provided in an Information Resource may use 1280 information provided in some other resources (e.g., a Cost Map uses 1281 the PIDs defined in a Network Map). The uses attribute conveys such 1282 information. 1284 9.2. Information Resource Directory (IRD) 1286 An ALTO Server uses Information Resource Directory to publish 1287 available Information Resources and their aforementioned attributes. 1288 Since resource selection happens after consumption of the Information 1289 Resource Directory, the format of the Information Resource Directory 1290 is designed to be simple with the intention of future ALTO Protocol 1291 versions maintaining backwards compatibility. Future extensions or 1292 versions of the ALTO Protocol SHOULD be accomplished by extending 1293 existing media types or adding new media types, but retaining the 1294 same format for the Information Resource Directory. 1296 An ALTO Server MUST make an Information Resource Directory available 1297 via the HTTP GET method to a URI discoverable by an ALTO Client. 1298 Discovery of this URI is out of scope of this document, but could be 1299 accomplished by manual configuration or by returning the URI of an 1300 Information Resource Directory from the ALTO Discovery Protocol 1301 [I-D.ietf-alto-server-discovery]. For recommendations on how the URI 1302 may look like, see [I-D.ietf-alto-server-discovery]. 1304 9.2.1. Media Type 1306 The media type to indicate an information directory is "application/ 1307 alto-directory+json". 1309 9.2.2. Encoding 1311 An Information Resource Directory response may include in "meta" the 1312 "cost-types" key, whose value is of type IRDMetaCostTypes defined 1313 below, where CostType is defined in Section 10.7: 1315 object-map { 1316 JSONString -> CostType; 1317 } IRDMetaCostTypes; 1318 The function of "cost-types" is to assign names to a set of CostTypes 1319 that can be used in one or more "resources" entries in the IRD to 1320 simplify specification. The names defined in "cost-types" in an IRD 1321 are local to the IRD. 1323 For a Root IRD, "meta" MUST include the "default-alto-network-map" 1324 key, which specifies the Resource ID of a Network Map. When there are 1325 multiple Network Maps defined in an IRD (e.g., with different levels 1326 of granularity), the "default-alto-network-map" key provides a 1327 guideline to simple clients that use only one Network Map. 1329 The data component of an Information Resource Directory response is 1330 named "resources", which is a JSON object of type IRDResourceEntries: 1332 object { 1333 IRDResourceEntries resources; 1334 } InfoResourceDirectory : ResponseEntityBase; 1336 object-map { 1337 ResourceID -> IRDResourceEntry; 1338 } IRDResourceEntries; 1340 object { 1341 JSONString uri; 1342 JSONString media-type; 1343 [JSONString accepts;] 1344 [Capabilities capabilities;] 1345 [ResourceID uses<0..*>;] 1346 } IRDResourceEntry; 1348 object { 1349 ... 1350 } Capabilities; 1352 An IRDResourceEntries object is a dictionary map keyed by 1353 ResourceIDs, where ResourceID is defined in Section 10.2. The value 1354 of each entry specifies: 1356 uri A URI at which the ALTO Server provides one or more Information 1357 Resources, or an Information Resource Directory indicating 1358 additional Information Resources. URIs can be relative to the URI 1359 of the IRD and MUST be resolved according to Section 5 of 1360 [RFC3986]. 1362 media-type The media type of Information Resource (see 1363 Section 9.1.2) available via GET or POST requests to the 1364 corresponding URI or "application/alto-directory+json", which 1365 indicates that the response for a request to the URI will be an 1366 Information Resource Directory for URIs discoverable via the URI. 1368 accepts The media type of input parameters (see Section 9.1.4) 1369 accepted by POST requests to the corresponding URI. If this field 1370 is not present, it MUST be assumed to be empty. 1372 capabilities A JSON Object enumerating capabilities of an ALTO 1373 Server in providing the Information Resource at the corresponding 1374 URI and Information Resources discoverable via the URI. If this 1375 field is not present, it MUST be assumed to be an empty object. 1376 If a capability for one of the offered Information Resources is 1377 not explicitly listed here, an ALTO Client may either issue an 1378 OPTIONS HTTP request to the corresponding URI to determine if the 1379 capability is supported, or assume its default value documented in 1380 this specification or an extension document describing the 1381 capability. 1383 uses A list of Resource IDs, defined in the same IRD, that define 1384 the resources on which this resource directly depends. An ALTO 1385 Server SHOULD include in this list any resources that the ALTO 1386 Client would need to retrieve in order to interpret the contents 1387 of this resource. For example, a Cost Map resource should include 1388 in this list the Network Map on which it depends. ALTO Clients 1389 may wish to consult this list in order to pre-fetch necessary 1390 resources. 1392 If an entry has an empty list for "accepts", then the corresponding 1393 URI MUST support GET requests. If an entry has a non-empty 1394 "accepts", then the corresponding URI MUST support POST requests. If 1395 an ALTO Server wishes to support both GET and POST on a single URI, 1396 it MUST specify two entries in the Information Resource Directory. 1398 9.2.3. Example 1400 The following is an example Information Resource Directory returned 1401 by an ALTO Server to an ALTO Client. Assume it is the Root IRD of 1402 the Client. 1404 GET /directory HTTP/1.1 1405 Host: alto.example.com 1406 Accept: application/alto-directory+json,application/alto-error+json 1407 HTTP/1.1 200 OK 1408 Content-Length: 2333 1409 Content-Type: application/alto-directory+json 1411 { 1412 "meta" : { 1413 "cost-types": { 1414 "num-routing": { 1415 "cost-mode" : "numerical", 1416 "cost-metric": "routingcost", 1417 "description": "My default" 1418 }, 1419 "num-hop": { 1420 "cost-mode" : "numerical", 1421 "cost-metric": "hopcount" 1422 }, 1423 "ord-routing": { 1424 "cost-mode" : "ordinal", 1425 "cost-metric": "routingcost" 1426 }, 1427 "ord-hop": { 1428 "cost-mode" : "ordinal", 1429 "cost-metric": "hopcount" 1430 } 1431 }, 1432 "default-alto-network-map" : "my-default-network-map" 1433 }, 1434 "resources" : { 1435 "my-default-network-map" : { 1436 "uri" : "http://alto.example.com/networkmap", 1437 "media-type" : "application/alto-networkmap+json" 1438 }, 1439 "numerical-routing-cost-map" : { 1440 "uri" : "http://alto.example.com/costmap/num/routingcost", 1441 "media-type" : "application/alto-costmap+json", 1442 "capabilities" : { 1443 "cost-type-names" : [ "num-routing" ] 1444 }, 1445 "uses": [ "my-default-network-map" ] 1446 }, 1447 "numerical-hopcount-cost-map" : { 1448 "uri" : "http://alto.example.com/costmap/num/hopcount", 1449 "media-type" : "application/alto-costmap+json", 1450 "capabilities" : { 1451 "cost-type-names" : [ "num-hop" ] 1452 }, 1453 "uses": [ "my-default-network-map" ] 1454 }, 1455 "custom-maps-resources" : { 1456 "uri" : "http://custom.alto.example.com/maps", 1457 "media-type" : "application/alto-directory+json" 1458 }, 1459 "endpoint-property" : { 1460 "uri" : "http://alto.example.com/endpointprop/lookup", 1461 "media-type" : "application/alto-endpointprop+json", 1462 "accepts" : "application/alto-endpointpropparams+json", 1463 "capabilities" : { 1464 "prop-types" : [ "my-default-network-map.pid", 1465 "priv:ietf-example-prop" ] 1466 }, 1467 }, 1468 "endpoint-cost" : { 1469 "uri" : "http://alto.example.com/endpointcost/lookup", 1470 "media-type" : "application/alto-endpointcost+json", 1471 "accepts" : "application/alto-endpointcostparams+json", 1472 "capabilities" : { 1473 "cost-constraints" : true, 1474 "cost-type-names" : [ "num-routing", "num-hop", 1475 "ord-routing", "ord-hop"] 1476 } 1477 } 1478 } 1479 } 1481 Specifically, the "cost-types" key of "meta" of the example IRD 1482 defines names for four cost types in this IRD. For example, "num- 1483 routing" in the example is the name that refers to a Cost Type with 1484 Cost Mode being "numerical" and Cost Metric being "routingcost". 1485 This name is used in the second entry of "resources", which defines a 1486 Cost Map. In particular, the "cost-type-names" of its "capabilities" 1487 specifies that this resource supports a Cost Type named as "num- 1488 routing". The ALTO Client looks up the name "num-routing" in "cost- 1489 types" of the IRD to obtain the Cost Type named as "num-routing". 1490 The last entry of "resources" uses all four names defined in "cost- 1491 types". 1493 Another key defined in "meta" of the example IRD is "default-alto- 1494 network-map", which has value "my-default-network-map", which is the 1495 Resource ID of a Network Map that will be defined in "resources". 1497 The "resources" field of the example IRD defines six Information 1498 Resources. For example, the second entry, which is assigned a 1499 Resource ID "numerical-routing-cost-map", provides a Cost Map, as 1500 indicated by the media-type "application/alto-costmap+json". The 1501 Cost Map is based on the Network Map defined with Resource ID "my- 1502 default-network-map". As another example, the last entry, which is 1503 assigned Resource ID "endpoint-cost", provides the Endpoint Cost 1504 Service, which is indicated by the media-type "application/ 1505 alto-endpointcost+json". An ALTO Client should use uri 1506 "http://alto.example.com/endpointcost/lookup" to access the service. 1507 The ALTO Client should format its request body to be the 1508 "application/alto-endpointcostparams+json" media type, as specified 1509 by the "accepts" attribute of the Information Resource. The "cost- 1510 type-names" field of the "capabilities" attribute of the Information 1511 Resource includes four defined cost types specified in the "cost- 1512 types" key of "meta" of the IRD. Hence, one can verify that the 1513 Endpoint Cost Information Resource supports both Cost Metrics 1514 'routingcost' and 'hopcount', each available for both 'numerical' and 1515 'ordinal'. When requesting the Information Resource, an ALTO Client 1516 can specify cost constraints, as indicated by the "cost-constraints" 1517 field of the "capabilities" attribute. 1519 9.2.4. Delegation using IRD 1521 ALTO Information Resource Directory provides flexibility to provide 1522 ALTO Service (e.g., delegation to another domain). Consider the 1523 preceding example. Assume that the ALTO Server running at 1524 alto.example.com wants to delegate some Information Resources to a 1525 separate subdomain: "custom.alto.example.com". In particular, assume 1526 that the maps available via this subdomain are filtered Network Maps, 1527 filtered Cost Maps, and some pre-generated maps for the "hopcount" 1528 and "routingcost" Cost Metrics in the "ordinal" Cost Mode. The 1529 fourth entry of "resources" in the preceding example IRD implements 1530 the delegation. The entry has a media-type of "application/ 1531 alto-directory+json", and an ALTO Client can discover the Information 1532 Resources available at "custom.alto.example.com" if its request to 1533 "http://custom.alto.example.com/maps" is successful: 1535 GET /maps HTTP/1.1 1536 Host: custom.alto.example.com 1537 Accept: application/alto-directory+json,application/alto-error+json 1539 HTTP/1.1 200 OK 1540 Content-Length: 1900 1541 Content-Type: application/alto-directory+json 1543 { 1544 "meta" : { 1545 "cost-types": { 1546 "num-routing": { 1547 "cost-mode" : "numerical", 1548 "cost-metric": "routingcost", 1549 "description": "My default" 1550 }, 1551 "num-hop": { 1552 "cost-mode" : "numerical", 1553 "cost-metric": "hopcount" 1554 }, 1555 "ord-routing": { 1556 "cost-mode" : "ordinal", 1557 "cost-metric": "routingcost" 1558 }, 1559 "ord-hop": { 1560 "cost-mode" : "ordinal", 1561 "cost-metric": "hopcount" 1562 } 1563 } 1564 }, 1565 "resources" : { 1566 "filtered-network-map" : { 1567 "uri" : "http://custom.alto.example.com/networkmap/filtered", 1568 "media-type" : "application/alto-networkmap+json", 1569 "accepts" : "application/alto-networkmapfilter+json", 1570 "uses": [ "my-default-network-map" ] 1571 }, 1572 "filtered-cost-map" : { 1573 "uri" : "http://custom.alto.example.com/costmap/filtered", 1574 "media-type" : "application/alto-costmap+json", 1575 "accepts" : "application/alto-costmapfilter+json", 1576 "capabilities" : { 1577 "cost-constraints" : true, 1578 "cost-type-names" : [ "num-routing", "num-hop", 1579 "ord-routing", "ord-hop" ] 1580 }, 1581 "uses": [ "my-default-network-map" ] 1582 }, 1583 "ordinal-routing-cost-map" : { 1584 "uri" : "http://custom.alto.example.com/ord/routingcost", 1585 "media-type" : "application/alto-costmap+json", 1586 "capabilities" : { 1587 "cost-type-names" : [ "ord-routing" ] 1588 }, 1589 "uses": [ "my-default-network-map" ] 1590 }, 1591 "ordinal-hopcount-cost-map" : { 1592 "uri" : "http://custom.alto.example.com/ord/hopcount", 1593 "media-type" : "application/alto-costmap+json", 1594 "capabilities" : { 1595 "cost-type-names" : [ "ord-hop" ], 1596 }, 1597 "uses": [ "my-default-network-map" ] 1598 } 1599 } 1600 } 1602 Note that the subdomain does not define Network Map, and uses the 1603 Network Map with Resource ID "my-default-network-map" defined in the 1604 Root IRD. 1606 9.2.5. Considerations of Using IRD 1608 9.2.5.1. ALTO Client 1610 This document specifies no requirements or constraints on ALTO 1611 Clients with regards to how they process an Information Resource 1612 Directory to identify the URI corresponding to a desired Information 1613 Resource. However, some advice is provided for implementors. 1615 It is possible that multiple entries in the directory match a desired 1616 Information Resource. For instance, in the example in Section 9.2.3, 1617 a full Cost Map with "numerical" Cost Mode and "routingcost" Cost 1618 Metric could be retrieved via a GET request to 1619 "http://alto.example.com/costmap/num/routingcost", or via a POST 1620 request to "http://custom.alto.example.com/costmap/filtered". 1622 In general, it is preferred for ALTO Clients to use GET requests 1623 where appropriate, since it is more likely for responses to be 1624 cachable. However, an ALTO Client may need to use POST, for example, 1625 to get ALTO costs or properties that are for a restricted set of PIDs 1626 or Endpoints, or to update cached information previously acquired via 1627 GET requests." 1629 9.2.5.2. ALTO Server 1631 This document indicates that an ALTO Server may or may not provide 1632 the Information Resources specified in the Map Filtering Service. If 1633 these resources are not provided, it is indicated to an ALTO Client 1634 by the absence of a Network Map or Cost Map with any media types 1635 listed under "accepts". 1637 10. Protocol Specification: Basic Data Types 1639 This section details the format of basic data types. 1641 10.1. PID Name 1643 A PID Name is encoded as a JSON string. The string MUST be no more 1644 than 64 characters, and MUST NOT contain characters other than US- 1645 ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and 1646 U+0061-U+007A), the hyphen ('-', U+002D), the colon (':', U+003A), 1647 the at ('@', code point U+0040), the low line ('_', U+005F), or the 1648 '.' separator (U+002E). The '.' separator is reserved for future use 1649 and MUST NOT be used unless specifically indicated in this document, 1650 or an extension document. 1652 The type 'PIDName' is used in this document to indicate a string of 1653 this format. 1655 10.2. Resource ID 1657 A Resource ID uniquely identifies an particular resource (e.g., a 1658 Network Map) within an ALTO Server (see Section 9.2). 1660 A Resource ID is encoded as a JSON string with the same format as 1661 that of PIDName. 1663 The type 'ResourceID' is used in this document to indicate a string 1664 of this format. 1666 10.3. Version Tag 1668 A Version Tag is defined as: 1670 object { 1671 ResourceID resource-id; 1672 JSONString tag; 1673 } VersionTag; 1675 As described in Section 6.3, the 'resource-id' attribute is the 1676 Resource ID of a resource (e.g., a Network Map) defined in the 1677 Information Resource Directory, and 'tag' is an identifier string. 1679 Two values of the VersionTag are equal if and only if both the 1680 'resource-id' attributes are byte-for-byte equal and the 'tag' 1681 attributes are byte-for-byte equal. 1683 A 'tag' string MUST be no more than 64 characters, and MUST NOT 1684 contain any character below U+0021 or above U+007E. It is RECOMMENDED 1685 that the tag have a low collision probability with other tags. One 1686 suggested mechanism is to compute it using a hash of the data 1687 contents of the resource. 1689 10.4. Endpoints 1691 This section defines formats used to encode addresses for Endpoints. 1692 In a case that multiple textual representations encode the same 1693 Endpoint address or prefix (within the guidelines outlined in this 1694 document), the ALTO Protocol does not require ALTO Clients or ALTO 1695 Servers to use a particular textual representation, nor does it 1696 require that ALTO Servers reply to requests using the same textual 1697 representation used by requesting ALTO Clients. ALTO Clients must be 1698 cognizant of this. 1700 10.4.1. Typed Endpoint Addresses 1702 When an Endpoint Address is used, an ALTO implementation must be able 1703 to determine its type. For this purpose, the ALTO Protocol allows 1704 endpoint addresses to also explicitly indicate their types. This 1705 document refers to such addresses as Typed Endpoint Addresses. 1707 Typed Endpoint Addresses are encoded as strings of the format 1708 'AddressType:EndpointAddr', with the ':' character as a separator. 1709 The type 'TypedEndpointAddr' is used to indicate a string of this 1710 format. 1712 10.4.2. Address Type 1714 The AddressType component of TypedEndPointAddr is defined as a string 1715 consisting of only US-ASCII alphanumeric characters (U+0030-U+0039, 1716 U+0041-U+005A, and U+0061-U+007A). The type 'AddressType' is used in 1717 this document to indicate a string of this format. 1719 This document defines two values for AddressType: 'ipv4' to refer to 1720 IPv4 addresses, and 'ipv6' to refer to IPv6 addresses. All 1721 AddressType identifiers appearing in an HTTP request or response with 1722 an 'application/alto-*' media type MUST be registered in the ALTO 1723 Address Type registry (see Section 14.4). 1725 10.4.3. Endpoint Address 1727 The EndpointAddr component of TypedEndPointAddr is also encoded as a 1728 string. The exact characters and format depend on AddressType. This 1729 document defines EndpointAddr when AddressType is 'ipv4' or 'ipv6'. 1731 10.4.3.1. IPv4 1733 IPv4 Endpoint Addresses are encoded as specified by the 'IPv4address' 1734 rule in Section 3.2.2 of [RFC3986]. 1736 10.4.3.2. IPv6 1738 IPv6 Endpoint Addresses are encoded as specified in Section 4 of 1739 [RFC5952]. 1741 10.4.4. Endpoint Prefixes 1743 For efficiency, it is useful to denote a set of Endpoint Addresses 1744 using a special notation (if one exists). This specification makes 1745 use of the prefix notations for both IPv4 and IPv6 for this purpose. 1747 Endpoint Prefixes are encoded as strings. The exact characters and 1748 format depend on the type of endpoint address. 1750 The type 'EndpointPrefix' is used in this document to indicate a 1751 string of this format. 1753 10.4.4.1. IPv4 1755 IPv4 Endpoint Prefixes are encoded as specified in Section 3.1 of 1756 [RFC4632]. 1758 10.4.4.2. IPv6 1760 IPv6 Endpoint Prefixes are encoded as specified in Section 7 of 1761 [RFC5952]. 1763 10.4.5. Endpoint Address Group 1765 The ALTO Protocol includes messages that specify potentially large 1766 sets of endpoint addresses. Endpoint Address Groups provide a more 1767 efficient way to encode such sets, even when the set contains 1768 endpoint addresses of different types. 1770 An Endpoint Address Group is defined as: 1772 object-map { 1773 AddressType -> EndpointPrefix<0..*>; 1774 } EndpointAddrGroup; 1776 In particular, an Endpoint Address Group is a JSON object 1777 representing a map, where each key is the string corresponding to an 1778 address type, and the corresponding value is an array listing 1779 prefixes of addresses of that type. 1781 The following is an example with both IPv4 and IPv6 endpoint 1782 addresses: 1784 { 1785 "ipv4": [ 1786 "192.0.2.0/24", 1787 "198.51.100.0/25" 1788 ], 1789 "ipv6": [ 1790 "2001:db8:0:1::/64", 1791 "2001:db8:0:2::/64" 1792 ] 1793 } 1795 10.5. Cost Mode 1797 A Cost Mode is encoded as a string. The string MUST either have the 1798 value 'numerical' or 'ordinal'. 1800 The type 'CostMode' is used in this document to indicate a string of 1801 this format. 1803 10.6. Cost Metric 1805 A Cost Metric is encoded as a string. The string MUST be no more 1806 than 32 characters, and MUST NOT contain characters other than US- 1807 ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and 1808 U+0061-U+007A), the hyphen ('-', U+002D), the colon (':', U+003A), 1809 the low line ('_', U+005F), or the '.' separator (U+002E). The '.' 1810 separator is reserved for future use and MUST NOT be used unless 1811 specifically indicated by a companion or extension document. 1813 Identifiers prefixed with 'priv:' are reserved for Private Use 1814 [RFC5226] without a need to register with IANA. All other 1815 identifiers that appear in an HTTP request or response with an 1816 'application/alto-*' media type and indicate Cost Metrics MUST be 1817 registered in the ALTO Cost Metrics registry Section 14.2. For an 1818 identifier with the 'priv:' prefix, an additional string (e.g., 1819 company identifier or random string) MUST follow (i.e., 'priv:' only 1820 is not a valid identifier) to reduce potential collisions. 1822 The type 'CostMetric' is used in this document to indicate a string 1823 of this format. 1825 10.7. Cost Type 1827 The combination of a CostMetric and a CostMode defines a CostType: 1829 object { 1830 CostMetric cost-metric; 1831 CostMode cost-mode; 1832 [JSONString description;] 1833 } CostType; 1835 'description', if present, MUST contain a string with a human- 1836 readable description of the cost-metric and cost-mode. An ALTO 1837 Client MAY present this string to a developer, as part of a discovery 1838 process. But the field is not intended to be interpreted by an ALTO 1839 Client. 1841 10.8. Endpoint Property 1843 This document will distinguish two types of Endpoint Properties: 1844 Resource Specific Endpoint Properties and Global Endpoint Properties. 1845 The type 'EndpointPropertyType' is used in this document to indicate 1846 a string denoting either a Resource Specific Endpoint Property or a 1847 Global Endpoint Property. 1849 10.8.1. Resource Specific Endpoint Properties 1851 This document defines only one Resource Specific Endpoint Property in 1852 this document: pid. It has the following format: a Resource ID, 1853 followed by the '.' separator (U+002E), followed by "pid". An 1854 example is "my-default-networkmap.pid". 1856 10.8.2. Global Endpoint Properties 1858 An Global Endpoint Property is encoded as a string. The string MUST 1859 be no more than 32 characters, and MUST NOT contain characters other 1860 than US-ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, 1861 and U+0061-U+007A), the hyphen ('-', U+002D), the colon (':', 1862 U+003A), or the low line ('_', U+005F). Note that the '.' separator 1863 is not allowed so that there is no ambiguity on whether an endpoint 1864 property is global or resource specific. 1866 Identifiers prefixed with 'priv:' are reserved for Private Use 1867 [RFC5226] without a need to register with IANA. All other 1868 identifiers for Endpoint Properties appearing in an HTTP request or 1869 response with an 'application/alto-*' media type MUST be registered 1870 in the ALTO Endpoint Property registry Section 14.3. For an Endpoint 1871 Property identifier with the 'priv:' prefix, an additional string 1872 (e.g., company identifier or random string) MUST follow (i.e., 1873 'priv:' only is not a valid Endpoint Property identifier) to reduce 1874 potential collisions. 1876 11. Protocol Specification: Service Information Resources 1878 This section documents the individual Information Resources defined 1879 to provide the services defined in this document. 1881 11.1. Meta Information 1883 For the "meta" field of the response to an individual Information 1884 Resource, this document defines two generic keys: "vtag", which is 1885 the Version Tag (see Section 10.3) of the current Information 1886 Resource; and "dependent-vtags", which is an array of Version Tags, 1887 to indicate the Version Tags of the resources that this resource 1888 depends on. 1890 11.2. Map Service 1892 The Map Service provides batch information to ALTO Clients in the 1893 form of two types of maps: a Network Map and Cost Map. 1895 11.2.1. Network Map 1897 A Network Map Information Resource defines a set of PIDs, and for 1898 each PID, lists the network locations (endpoints) within the PID. An 1899 ALTO Server MUST provide at least one Network Map. 1901 11.2.1.1. Media Type 1903 The media type of Network Map is "application/alto-networkmap+json". 1905 11.2.1.2. HTTP Method 1907 A Network Map resource is requested using the HTTP GET method. 1909 11.2.1.3. Accept Input Parameters 1911 None. 1913 11.2.1.4. Capabilities 1915 None. 1917 11.2.1.5. Uses 1919 None. 1921 11.2.1.6. Response 1923 The "meta" field of a Network Map response MUST include "vtag", which 1924 is the Version Tag of the retrieved Network Map. 1926 The data component of a Network Map response is named "network-map", 1927 which is a JSON object of type NetworkMapData: 1929 object { 1930 NetworkMapData network-map; 1931 } InfoResourceNetworkMap : ResponseEntityBase; 1933 object-map { 1934 PIDName -> EndpointAddrGroup; 1935 } NetworkMapData; 1937 Specifically, a NetworkMapData object is a dictionary map keyed by 1938 PIDs, and each value representing the associated set of endpoint 1939 addresses of a PID. 1941 The returned Network Map MUST include all PIDs known to the ALTO 1942 Server. 1944 11.2.1.7. Example 1946 GET /networkmap HTTP/1.1 1947 Host: alto.example.com 1948 Accept: application/alto-networkmap+json,application/alto-error+json 1949 HTTP/1.1 200 OK 1950 Content-Length: 449 1951 Content-Type: application/alto-networkmap+json 1953 { 1954 "meta" : { 1955 "vtag": { 1956 "resource-id": "my-default-network-map", 1957 "tag": "da65eca2eb7a10ce8b059740b0b2e3f8eb1d4785" 1958 } 1959 }, 1960 "network-map" : { 1961 "PID1" : { 1962 "ipv4" : [ 1963 "192.0.2.0/24", 1964 "198.51.100.0/25" 1965 ] 1966 }, 1967 "PID2" : { 1968 "ipv4" : [ 1969 "198.51.100.128/25" 1970 ] 1971 }, 1972 "PID3" : { 1973 "ipv4" : [ 1974 "0.0.0.0/0" 1975 ], 1976 "ipv6" : [ 1977 "::/0" 1978 ] 1979 } 1980 } 1981 } 1983 When parsing a Network Map, an ALTO Client MUST ignore any 1984 EndpointAddressGroup whose address type it does not recognize. If as 1985 a result a PID does not have any address types known to the client, 1986 the client still MUST recognize that PID name as valid, even though 1987 the PID then contains no endpoints. 1989 Note that the encoding of a Network Map response was chosen for 1990 readability and compactness. If lookup efficiency at runtime is 1991 crucial, then the returned Network Map can be transformed into data 1992 structures offering more efficient lookup. For example, one may 1993 store the Network Map as a trie-based data structure, which may allow 1994 efficient longest-prefix matching of IP addresses. 1996 11.2.2. Mapping IP Addresses to PIDs for 'ipv4'/'ipv6' Network Maps 1998 A key usage of a Network Map is to map Endpoint Addresses to PIDs. 1999 For Network Maps containing the 'ipv4' and 'ipv6' address types 2000 defined in this document, when either an ALTO Client or an ALTO 2001 Server needs to compute the mapping from IP addresses to PIDs, the 2002 longest-prefix matching algorithm [RFC1812] MUST be used. 2004 To ensure that the longest-prefix matching algorithm yields one and 2005 only one PID, Network Maps containing the 'ipv4/'ipv6' address types 2006 MUST satisfy the following two requirements. 2008 First, such a Network Map MUST define a PID for each possible address 2009 in the IP address space for all of the address types contained in the 2010 map. This is defined as the completeness property of a Network Map. 2011 A RECOMMENDED way to satisfy this property is to define a PID with 2012 the shortest enclosing prefix of the addresses provided in the map. 2013 For a map with full IPv4 reachability, this would mean including the 2014 0.0.0.0/0 prefix in a PID; for full IPv6 reachability, this would be 2015 the ::/0 prefix. 2017 Second, such a Network Map MUST NOT define two or more PIDs that 2018 contain an identical IP prefix, in order to ensure that the longest- 2019 prefix matching algorithm maps each IP addresses into exactly one 2020 PID. This is defined as the non-overlapping property of a Network 2021 Map. Specifically, to map an IP address to its PID in a non- 2022 overlapping Network Map, one considers the set S which consists of 2023 all prefixes defined in the Network Map, applies the longest-prefix 2024 mapping algorithm to S to identify the longest prefix containing the 2025 IP address, and assigns that the IP address belongs to the PID 2026 containing the identified longest prefix. 2028 The following example shows a complete and non-overlapping Network 2029 Map: 2031 "network-map" : { 2032 "PID0" : { "ipv6" : [ "::/0" ] }, 2033 "PID1" : { "ipv4" : [ "0.0.0.0/0" ] }, 2034 "PID2" : { "ipv4" : [ "192.0.2.0/24", "198.51.100.0/24" ] }, 2035 "PID3" : { "ipv4" : [ "192.0.2.0/25", "192.0.2.128/25" ] } 2036 } 2038 The IP address 192.0.2.1 should be mapped to PID3. 2040 If, however, the two adjacent prefixes in PID3 were combined as a 2041 single prefix, then PID3 was changed to 2043 "PID3" : { "ipv4" : [ "192.0.2.0/24" ] } 2045 The new map is no longer non-overlapping, and 192.0.2.1 could no 2046 longer be mapped unambiguously to a PID by means of longest-prefix 2047 matching. 2049 Extension documents may define techniques to allow a single IP 2050 address being mapped to multiple PIDs, when a need is identified. 2052 11.2.3. Cost Map 2054 A Cost Map resource lists the Path Cost for each pair of source/ 2055 destination PID defined by the ALTO Server for a given Cost Metric 2056 and Cost Mode. This resource MUST be provided for at least the 2057 'routingcost' Cost Metric. 2059 11.2.3.1. Media Type 2061 The media type of Cost Map is "application/alto-costmap+json". 2063 11.2.3.2. HTTP Method 2065 A Cost Map resource is requested using the HTTP GET method. 2067 11.2.3.3. Accept Input Parameters 2069 None. 2071 11.2.3.4. Capabilities 2073 The capabilities of an ALTO Server URI providing an unfiltered cost 2074 map is a JSON Object of type CostMapCapabilities: 2076 object { 2077 JSONString cost-type-names<1..1>; 2078 } CostMapCapabilities; 2080 with field: 2082 cost-type-names Note that the array MUST include a single CostType 2083 name defined by key "cost-types" in "meta" of the IRD. This is 2084 because an unfiltered Cost Map (accept == "") is requested via an 2085 HTTP GET that accepts no input parameters. As a contrast, for 2086 filtered cost maps (see Section 11.3.2), the array can have 2087 multiple elements. 2089 11.2.3.5. Uses 2091 The Resource ID of the Network Map based on which the Cost Map will 2092 be defined. Recall (Section 6) that the combination of a Network Map 2093 and a CostType defines a key. In other words, an ALTO Server MUST 2094 NOT define two Cost Maps with the same Cost Type, Network Map pair. 2096 11.2.3.6. Response 2098 The "meta" field of a Cost Map response MUST include the "dependent- 2099 vtags" key, whose value is a single-element array to indicate the 2100 Version Tag of the Network Map used, where the Network Map is 2101 specified in "uses" of the IRD. The "meta" MUST also include "cost- 2102 type", to indicate the Cost Type (Section 10.7) of the Cost Map. 2104 The data component of a Cost Map response is named "cost-map", which 2105 is a JSON object of type CostMapData: 2107 object { 2108 CostMapData cost-map; 2109 } InfoResourceCostMap : ResponseEntityBase; 2111 object-map { 2112 PIDName -> DstCosts; 2113 } CostMapData; 2115 object-map { 2116 PIDName -> JSONValue; 2117 } DstCosts; 2119 Specifically, a CostMapData object is a dictionary map object, with 2120 each key being the PIDName string identifying the corresponding 2121 Source PID, and value being a type of DstCosts, which denotes the 2122 associated costs from the Source PID to a set of destination PIDs ( 2123 Section 6.2). An implementation of the protocol in this document 2124 SHOULD assume that the cost is a JSONNumber and fail to parse if it 2125 is not, unless the implementation is using an extension to this 2126 document that indicates when and how costs of other data types are 2127 signaled. 2129 The returned Cost Map MUST include the Path Cost for each (Source 2130 PID, Destination PID) pair for which a Path Cost is defined. An ALTO 2131 Server MAY omit entries for which a Path Cost is not defined (e.g., 2132 both the Source and Destination PIDs contain addresses outside of the 2133 Network Provider's administrative domain). 2135 Similar to Network Map, the encoding of Cost Map was chosen for 2136 readability and compactness. If lookup efficiency at runtime is 2137 crucial, then the returned Cost Map can be transformed into data 2138 structures offering more efficient lookup. For example, one may 2139 store a Cost Map as a matrix. 2141 11.2.3.7. Example 2143 GET /costmap/num/routingcost HTTP/1.1 2144 Host: alto.example.com 2145 Accept: application/alto-costmap+json,application/alto-error+json 2147 HTTP/1.1 200 OK 2148 Content-Length: 435 2149 Content-Type: application/alto-costmap+json 2151 { 2152 "meta" : { 2153 "dependent-vtags" : [ 2154 {"resource-id": "my-default-network-map", 2155 "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e" 2156 } 2157 ], 2158 "cost-type" : {"cost-mode" : "numerical", 2159 "cost-metric": "routingcost" 2160 } 2161 }, 2162 "cost-map" : { 2163 "PID1": { "PID1": 1, "PID2": 5, "PID3": 10 }, 2164 "PID2": { "PID1": 5, "PID2": 1, "PID3": 15 }, 2165 "PID3": { "PID1": 20, "PID2": 15 } 2166 } 2167 } 2169 Similar to the Network Map case, array-based encoding for "map" was 2170 considered, but the current encoding was chosen for clarity. 2172 11.3. Map Filtering Service 2174 The Map Filtering Service allows ALTO Clients to specify filtering 2175 criteria to return a subset of the full maps available in the Map 2176 Service. 2178 11.3.1. Filtered Network Map 2180 A Filtered Network Map is a Network Map Information Resource 2181 (Section 11.2.1) for which an ALTO Client may supply a list of PIDs 2182 to be included. A Filtered Network Map MAY be provided by an ALTO 2183 Server. 2185 11.3.1.1. Media Type 2187 Since a Filtered Network Map is still a Network Map, it uses the 2188 media type defined for Network Map at Section 11.2.1.1. 2190 11.3.1.2. HTTP Method 2192 A Filtered Network Map is requested using the HTTP POST method. 2194 11.3.1.3. Accept Input Parameters 2196 An ALTO Client supplies filtering parameters by specifying media type 2197 "application/alto-networkmapfilter+json" with HTTP POST body 2198 containing a JSON Object of type ReqFilteredNetworkMap, where: 2200 object { 2201 PIDName pids<0..*>; 2202 [AddressType address-types<0..*>;] 2203 } ReqFilteredNetworkMap; 2205 with fields: 2207 pids Specifies list of PIDs to be included in the returned Filtered 2208 Network Map. If the list of PIDs is empty, the ALTO Server MUST 2209 interpret the list as if it contained a list of all currently- 2210 defined PIDs. The ALTO Server MUST interpret entries appearing 2211 multiple times as if they appeared only once. 2213 address-types Specifies list of address types to be included in the 2214 returned Filtered Network Map. If the "address-types" field is not 2215 specified, or the list of address types is empty, the ALTO Server 2216 MUST interpret the list as if it contained a list of all address 2217 types known to the ALTO Server. The ALTO Server MUST interpret 2218 entries appearing multiple times as if they appeared only once. 2220 11.3.1.4. Capabilities 2222 None. 2224 11.3.1.5. Uses 2226 The Resource ID of the Network Map based on which the filtering is 2227 performed. 2229 11.3.1.6. Response 2231 The format is the same as unfiltered Network Map. See 2232 Section 11.2.1.6 for the format. 2234 The ALTO Server MUST only include PIDs in the response that were 2235 specified (implicitly or explicitly) in the request. If the input 2236 parameters contain a PID name that is not currently defined by the 2237 ALTO Server, the ALTO Server MUST behave as if the PID did not appear 2238 in the input parameters. Similarly, the ALTO Server MUST only 2239 enumerate addresses within each PID that have types which were 2240 specified (implicitly or explicitly) in the request. If the input 2241 parameters contain an address type that is not currently known to the 2242 ALTO Server, the ALTO Server MUST behave as if the address type did 2243 not appear in the input parameters. 2245 The Version Tag included in the "vtag" of the response MUST 2246 correspond to the full (unfiltered) Network Map Information Resource 2247 from which the filtered information is provided. This ensures that a 2248 single, canonical Version Tag is used independent of any filtering 2249 that is requested by an ALTO Client. 2251 11.3.1.7. Example 2253 POST /networkmap/filtered HTTP/1.1 2254 Host: custom.alto.example.com 2255 Content-Length: 33 2256 Content-Type: application/alto-networkmapfilter+json 2257 Accept: application/alto-networkmap+json,application/alto-error+json 2259 { 2260 "pids": [ "PID1", "PID2" ] 2261 } 2263 HTTP/1.1 200 OK 2264 Content-Length: 342 2265 Content-Type: application/alto-networkmap+json 2267 { 2268 "meta" : { 2269 "vtag" : { 2270 "resource-id": "my-default-network-map", 2271 "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d" 2272 } 2273 }, 2274 "network-map" : { 2275 "PID1" : { 2276 "ipv4" : [ 2277 "192.0.2.0/24", 2278 "198.51.100.0/24" 2279 ] 2280 }, 2281 "PID2" : { 2282 "ipv4": [ 2283 "198.51.100.128/24" 2284 ] 2285 } 2286 } 2287 } 2289 11.3.2. Filtered Cost Map 2291 A Filtered Cost Map is a Cost Map Information Resource 2292 (Section 11.2.3) for which an ALTO Client may supply additional 2293 parameters limiting the scope of the resulting Cost Map. A Filtered 2294 Cost Map MAY be provided by an ALTO Server. 2296 11.3.2.1. Media Type 2298 Since a Filtered Cost Map is still a Cost Map, it uses the media type 2299 defined for Cost Map at Section 11.2.3.1. 2301 11.3.2.2. HTTP Method 2303 A Filtered Cost Map is requested using the HTTP POST method. 2305 11.3.2.3. Accept Input Parameters 2307 The input parameters for a Filtered Map are supplied in the entity 2308 body of the POST request. This document specifies the input 2309 parameters with a data format indicated by the media type 2310 "application/alto-costmapfilter+json", which is a JSON Object of type 2311 ReqFilteredCostMap, where: 2313 object { 2314 CostType cost-type; 2315 [JSONString constraints<0..*>;] 2316 [PIDFilter pids;] 2317 } ReqFilteredCostMap; 2319 object { 2320 PIDName srcs<0..*>; 2321 PIDName dsts<0..*>; 2322 } PIDFilter; 2324 with fields: 2326 cost-type The CostType (Section 10.7) for the returned costs. The 2327 cost-metric and cost-mode fields MUST match one of the supported 2328 Cost Types indicated in this resource's capabilities 2329 (Section 11.3.2.4). The ALTO Client SHOULD omit the description 2330 field, and if present, the ALTO Server MUST ignore the description 2331 field. 2333 constraints Defines a list of additional constraints on which 2334 elements of the Cost Map are returned. This parameter MUST NOT be 2335 specified if this resource's capabilities ( Section 11.3.2.4) 2336 indicate that constraint support is not available. A constraint 2337 contains two entities separated by whitespace: (1) an operator, 2338 'gt' for greater than, 'lt' for less than, 'ge' for greater than 2339 or equal to, 'le' for less than or equal to, or 'eq' for equal to; 2340 (2) a target cost value. The cost value is a number that MUST be 2341 defined in the same units as the Cost Metric indicated by the 2342 cost-metric parameter. ALTO Servers SHOULD use at least IEEE 754 2343 double-precision floating point [IEEE.754.2008] to store the cost 2344 value, and SHOULD perform internal computations using double- 2345 precision floating-point arithmetic. If multiple 'constraint' 2346 parameters are specified, they are interpreted as being related to 2347 each other with a logical AND. 2349 pids A list of Source PIDs and a list of Destination PIDs for which 2350 Path Costs are to be returned. If a list is empty, the ALTO 2351 Server MUST interpret it as the full set of currently-defined 2352 PIDs. The ALTO Server MUST interpret entries appearing in a list 2353 multiple times as if they appeared only once. If the "pids" field 2354 is not present, both lists MUST be interpreted by the ALTO Server 2355 as containing the full set of currently-defined PIDs. 2357 11.3.2.4. Capabilities 2359 The URI providing this resource supports all capabilities documented 2360 in Section 11.2.3.4 (with identical semantics), plus additional 2361 capabilities. In particular, the capabilities are defined by a JSON 2362 object of type FilteredCostMapCapabilities: 2364 object { 2365 JSONString cost-type-names<1..*>; 2366 JSONBool cost-constraints; 2367 } FilteredCostMapCapabilities; 2369 with fields: 2371 cost-type-names See Section 11.2.3.4 and note that the array can 2372 have 1 to many cost types. 2374 cost-constraints If true, then the ALTO Server allows cost 2375 constraints to be included in requests to the corresponding URI. 2376 If not present, this field MUST be interpreted as if it specified 2377 false. ALTO Clients should be aware that constraints may not have 2378 the intended effect for cost maps with the 'ordinal' Cost Mode 2379 since ordinal costs are not restricted to being sequential 2380 integers. 2382 11.3.2.5. Uses 2384 The Resource ID of the Network Map based on which the Cost Map will 2385 be filtered. 2387 11.3.2.6. Response 2389 The format is the same as an unfiltered Cost Map. See 2390 Section 11.2.3.6 for the format. 2392 The "dependent-vtags" key in the "meta" field is an array consisting 2393 of a single element, which is the Version Tag of the Network Map used 2394 in filtering. ALTO Clients should verify that the Version Tag 2395 included in the response is equal to the Version Tag of the Network 2396 Map used to generate the request (if applicable). If it is not, the 2397 ALTO Client may wish to request an updated Network Map, identify 2398 changes, and consider requesting a new Filtered Cost Map. 2400 The returned Cost Map MUST contain only source/destination pairs that 2401 have been indicated (implicitly or explicitly) in the input 2402 parameters. If the input parameters contain a PID name that is not 2403 currently defined by the ALTO Server, the ALTO Server MUST behave as 2404 if the PID did not appear in the input parameters. 2406 If any constraints are specified, Source/Destination pairs for which 2407 the Path Costs do not meet the constraints MUST NOT be included in 2408 the returned Cost Map. If no constraints were specified, then all 2409 Path Costs are assumed to meet the constraints. 2411 11.3.2.7. Example 2413 POST /costmap/filtered HTTP/1.1 2414 Host: custom.alto.example.com 2415 Content-Type: application/alto-costmapfilter+json 2416 Content-Length: 181 2417 Accept: application/alto-costmap+json,application/alto-error+json 2419 { 2420 "cost-type" : {"cost-mode": "numerical", 2421 "cost-metric": "routingcost" 2422 }, 2423 "pids" : { 2424 "srcs" : [ "PID1" ], 2425 "dsts" : [ "PID1", "PID2", "PID3" ] 2426 } 2427 } 2429 HTTP/1.1 200 OK 2430 Content-Length: 341 2431 Content-Type: application/alto-costmap+json 2433 { 2434 "meta" : { 2435 "dependent-vtags" : [ 2436 {"resource-id": "my-default-network-map", 2437 "tag": "75ed013b3cb58f896e839582504f622838ce670f" 2438 } 2439 ], 2440 "cost-type": {"cost-mode" : "numerical", 2441 "cost-metric" : "routingcost" 2442 } 2443 }, 2444 "cost-map" : { 2445 "PID1": { "PID1": 0, "PID2": 1, "PID3": 2 } 2446 } 2447 } 2449 11.4. Endpoint Property Service 2451 The Endpoint Property Service provides information about Endpoint 2452 properties to ALTO Clients. 2454 11.4.1. Endpoint Property 2456 An Endpoint Property resource provides information about properties 2457 for individual endpoints. It MAY be provided by an ALTO Server. 2459 11.4.1.1. Media Type 2461 The media type of Endpoint Property is "application/ 2462 alto-endpointprop+json". 2464 11.4.1.2. HTTP Method 2466 The Endpoint Property resource is requested using the HTTP POST 2467 method. 2469 11.4.1.3. Accept Input Parameters 2471 An ALTO Client supplies the endpoint properties to be queried through 2472 a media type "application/alto-endpointpropparams+json", and 2473 specifies in the HTTP POST entity body a JSON Object of type 2474 ReqEndpointProp: 2476 object { 2477 EndpointPropertyType properties<1..*>; 2478 TypedEndpointAddr endpoints<1..*>; 2479 } ReqEndpointProp; 2481 with fields: 2483 properties List of endpoint properties to be returned for each 2484 endpoint. Each specified property MUST be included in the list of 2485 supported properties indicated by this resource's capabilities 2486 (Section 11.4.1.4). The ALTO Server MUST interpret entries 2487 appearing multiple times as if they appeared only once. 2489 endpoints List of endpoint addresses for which the specified 2490 properties are to be returned. The ALTO Server MUST interpret 2491 entries appearing multiple times as if they appeared only once. 2493 11.4.1.4. Capabilities 2495 This resource may be defined across multiple types of endpoint 2496 properties. The capabilities of an ALTO Server URI providing 2497 Endpoint Properties are defined by a JSON Object of type 2498 EndpointPropertyCapabilities: 2500 object { 2501 EndpointPropertyType prop-types<1..*>; 2502 } EndpointPropertyCapabilities; 2504 with field: 2506 prop-types The Endpoint Properties (see Section 10.8) supported by 2507 the corresponding URI. 2509 In particular, the Information Resource Closure MUST provide the look 2510 up of pid for every Network Map defined. 2512 11.4.1.5. Uses 2514 None. 2516 11.4.1.6. Response 2518 The "dependent-vtags" key in the "meta" field of the response MUST be 2519 an array that includes the Version Tags of all Network Maps whose 2520 'pid' is queried. 2522 The data component of an Endpoint Properties response is named 2523 "endpoint-properties", which is a JSON object of type 2524 EndpointPropertyMapData, where: 2526 object { 2527 EndpointPropertyMapData endpoint-properties; 2528 } InfoResourceEndpointProperties : ResponseEntityBase; 2530 object-map { 2531 TypedEndpointAddr -> EndpointProps; 2532 } EndpointPropertyMapData; 2534 object { 2535 EndpointPropertyType -> JSONValue; 2536 } EndpointProps; 2538 Specifically, an EndpointPropertyMapData object has one member for 2539 each endpoint indicated in the input parameters (with the name being 2540 the endpoint encoded as a TypedEndpointAddr). The requested 2541 properties for each endpoint are encoded in a corresponding 2542 EndpointProps object, which encodes one name/value pair for each 2543 requested property, where the property names are encoded as strings 2544 of type EndpointPropertyType. An implementation of the protocol in 2545 this document SHOULD assume that the property value is a JSONString 2546 and fail to parse if it is not, unless the implementation is using an 2547 extension to this document that indicates when and how property 2548 values of other data types are signaled. 2550 The ALTO Server returns the value for each of the requested endpoint 2551 properties for each of the endpoints listed in the input parameters. 2553 If the ALTO Server does not define a requested property's value for a 2554 particular endpoint, then it MUST omit that property from the 2555 response for only that endpoint. 2557 11.4.1.7. Example 2559 POST /endpointprop/lookup HTTP/1.1 2560 Host: alto.example.com 2561 Content-Length: 181 2562 Content-Type: application/alto-endpointpropparams+json 2563 Accept: application/alto-endpointprop+json,application/alto-error+json 2565 { 2566 "properties" : [ "my-default-networkmap.pid", 2567 "priv:ietf-example-prop" ], 2568 "endpoints" : [ "ipv4:192.0.2.34", 2569 "ipv4:203.0.113.129" ] 2570 } 2572 HTTP/1.1 200 OK 2573 Content-Length: 396 2574 Content-Type: application/alto-endpointprop+json 2576 { 2577 "meta" : { 2578 "dependent-vtags" : [ 2579 {"resource-id": "my-default-network-map", 2580 "tag": "7915dc0290c2705481c491a2b4ffbec482b3cf62" 2581 } 2582 ] 2583 }, 2584 "endpoint-properties": { 2585 "ipv4:192.0.2.34" : { "my-default-network-map.pid": "PID1", 2586 "priv:ietf-example-prop": "1" }, 2587 "ipv4:203.0.113.129" : { "my-default-network-map.pid": "PID3" } 2588 } 2589 } 2591 11.5. Endpoint Cost Service 2593 The Endpoint Cost Service provides information about costs between 2594 individual endpoints. 2596 In particular, this service allows lists of Endpoint prefixes (and 2597 addresses, as a special case) to be ranked (ordered) by an ALTO 2598 Server. 2600 11.5.1. Endpoint Cost 2602 An Endpoint Cost resource provides information about costs between 2603 individual endpoints. It MAY be provided by an ALTO Server. 2605 How an ALTO Server provides the Endpoint Cost resource is 2606 implementation dependent. An ALTO Server may use either fine-grained 2607 costs among individual endpoints or coarse-grained costs based on the 2608 costs between the PIDs corresponding to the endpoints. See 2609 Section 15.3 for additional details. 2611 11.5.1.1. Media Type 2613 The media type of Endpoint Cost is "application/ 2614 alto-endpointcost+json". 2616 11.5.1.2. HTTP Method 2618 The Endpoint Cost resource is requested using the HTTP POST method. 2620 11.5.1.3. Accept Input Parameters 2622 An ALTO Client supplies the endpoint cost parameters through a media 2623 type "application/alto-endpointcostparams+json", with an HTTP POST 2624 entity body of a JSON Object of type ReqEndpointCostMap: 2626 object { 2627 CostType cost-type; 2628 [JSONString constraints<0..*>;] 2629 EndpointFilter endpoints; 2630 } ReqEndpointCostMap; 2632 object { 2633 [TypedEndpointAddr srcs<0..*>;] 2634 [TypedEndpointAddr dsts<0..*>;] 2635 } EndpointFilter; 2636 with fields: 2638 cost-type The Cost Type (Section 10.7) to use for returned costs. 2639 The cost-metric and cost-mode fields MUST match one of the 2640 supported Cost Types indicated in this resource's capabilities ( 2641 Section 11.5.1.4). The ALTO Client SHOULD omit the description 2642 field, and if present, the ALTO Server MUST ignore the description 2643 field. 2645 constraints Defined equivalently to the "constraints" input 2646 parameter of a Filtered Cost Map (see Section 11.3.2). 2648 endpoints A list of Source Endpoints and Destination Endpoints for 2649 which Path Costs are to be returned. If the list of Source or 2650 Destination Endpoints is empty (or not included), the ALTO Server 2651 MUST interpret it as if it contained the Endpoint Address 2652 corresponding to the client IP address from the incoming 2653 connection (see Section 13.3 for discussion and considerations 2654 regarding this mode). The Source and Destination Endpoint lists 2655 MUST NOT be both empty. The ALTO Server MUST interpret entries 2656 appearing multiple times in a list as if they appeared only once. 2658 11.5.1.4. Capabilities 2660 This document defines EndpointCostCapabilities as the same as 2661 FilteredCostMapCapabilities. See Section 11.3.2.4. 2663 11.5.1.5. Uses 2665 It is important to note that although this resource allows an ALTO 2666 Server to reveal costs between individual endpoints, an ALTO Server 2667 is not required to do so. A simple implementation of an ECS resource 2668 may compute the cost between two endpoints as the cost between the 2669 PIDs corresponding to the endpoints, using one of the exposed network 2670 and cost maps defined by the server. ECS MUST NOT use a Network or 2671 Cost Map. Hence, the ECS cost is the cost from the source to 2672 destination endpoint. A future extension may allow ECS to state that 2673 it "uses" a Network Map. The extension then will need to define the 2674 semantics. 2676 11.5.1.6. Response 2678 The "meta" field of an Endpoint Cost response MUST include the "cost- 2679 type" key, to indicate the Cost Type used. 2681 The data component of an Endpoint Cost response is named "endpoint- 2682 cost-map", which is a JSON object of type EndpointCostMapData: 2684 object { 2685 EndpointCostMapData endpoint-cost-map; 2686 } InfoResourceEndpointCostMap : ResponseEntityBase; 2688 object-map { 2689 TypedEndpointAddr -> EndpointDstCosts; 2690 } EndpointCostMapData; 2692 object-map { 2693 TypedEndpointAddr -> JSONValue; 2694 } EndpointDstCosts; 2696 Specifically, an EndpointCostMapData object is a dictionary map with 2697 each key representing a TypedEndpointAddr string identifying the 2698 Source Endpoint specified in the input parameters. For each Source 2699 Endpoint, a EndpointDstCosts dictionary map object denotes the 2700 associated cost to each Destination Endpoint specified in input 2701 parameters. An implementation of the protocol in this document 2702 SHOULD assume that the cost value is a JSONNumber and fail to parse 2703 if it is not, unless the implementation is using an extension to this 2704 document that indicates when and how costs of other data types are 2705 signaled. If the ALTO Server does not define a cost value from a 2706 Source Endpoint to a particular Destination Endpoint, it MAY be 2707 omitted from the response. 2709 11.5.1.7. Example 2711 POST /endpointcost/lookup HTTP/1.1 2712 Host: alto.example.com 2713 Content-Length: 248 2714 Content-Type: application/alto-endpointcostparams+json 2715 Accept: application/alto-endpointcost+json,application/alto-error+json 2717 { 2718 "cost-type": {"cost-mode" : "ordinal", 2719 "cost-metric" : "routingcost"}, 2720 "endpoints" : { 2721 "srcs": [ "ipv4:192.0.2.2" ], 2722 "dsts": [ 2723 "ipv4:192.0.2.89", 2724 "ipv4:198.51.100.34", 2725 "ipv4:203.0.113.45" 2726 ] 2727 } 2728 } 2730 HTTP/1.1 200 OK 2731 Content-Length: 274 2732 Content-Type: application/alto-endpointcost+json 2734 { 2735 "meta" : { 2736 "cost-type": {"cost-mode" : "ordinal", 2737 "cost-metric" : "routingcost" 2738 } 2739 }, 2740 "endpoint-cost-map" : { 2741 "ipv4:192.0.2.2": { 2742 "ipv4:192.0.2.89" : 1, 2743 "ipv4:198.51.100.34" : 2, 2744 "ipv4:203.0.113.45" : 3 2745 } 2746 } 2747 } 2749 12. Use Cases 2751 The sections below depict typical use cases. While these use cases 2752 focus on peer-to-peer applications, ALTO can be applied to other 2753 environments such as CDNs [I-D.jenkins-alto-cdn-use-cases]. 2755 12.1. ALTO Client Embedded in P2P Tracker 2757 Many currently-deployed P2P systems use a Tracker to manage swarms 2758 and perform peer selection. Such a P2P Tracker can already use a 2759 variety of information to perform peer selection to meet application- 2760 specific goals. By acting as an ALTO Client, the P2P Tracker can use 2761 ALTO information as an additional information source to enable more 2762 network-efficient traffic patterns and improve application 2763 performance. 2765 A particular requirement of many P2P trackers is that they must 2766 handle a large number of P2P clients. A P2P tracker can obtain and 2767 locally store ALTO information (the Network Map and Cost Map) from 2768 the ISPs containing the P2P clients, and benefit from the same 2769 aggregation of network locations done by ALTO Servers. 2771 .---------. (1) Get Network Map .---------------. 2772 | | <----------------------> | | 2773 | ALTO | | P2P Tracker | 2774 | Server | (2) Get Cost Map | (ALTO Client) | 2775 | | <----------------------> | | 2776 `---------' `---------------' 2777 ^ | 2778 (3) Get Peers | | (4) Selected Peer 2779 | v List 2780 .---------. .-----------. 2781 | Peer 1 | <-------------- | P2P | 2782 `---------' | Client | 2783 . (5) Connect to `-----------' 2784 . Selected Peers / 2785 .---------. / 2786 | Peer 50 | <------------------ 2787 `---------' 2789 Figure 4: ALTO Client Embedded in P2P Tracker 2791 Figure 4 shows an example use case where a P2P tracker is an ALTO 2792 Client and applies ALTO information when selecting peers for its P2P 2793 clients. The example proceeds as follows: 2795 1. The P2P Tracker requests from the ALTO Server using the Network 2796 Map query the Network Map covering all PIDs. The Network Map 2797 includes the IP prefixes contained in each PID, allowing the P2P 2798 tracker to locally map P2P clients into PIDs. 2800 2. The P2P Tracker requests from the ALTO Server the Cost Map 2801 amongst all PIDs identified in the preceding step. 2803 3. A P2P Client joins the swarm, and requests a peer list from the 2804 P2P Tracker. 2806 4. The P2P Tracker returns a peer list to the P2P client. The 2807 returned peer list is computed based on the Network Map and Cost 2808 Map returned by the ALTO Server, and possibly other information 2809 sources. Note that it is possible that a tracker may use only 2810 the Network Map to implement hierarchical peer selection by 2811 preferring peers within the same PID and ISP. 2813 5. The P2P Client connects to the selected peers. 2815 Note that the P2P tracker may provide peer lists to P2P clients 2816 distributed across multiple ISPs. In such a case, the P2P tracker 2817 may communicate with multiple ALTO Servers. 2819 12.2. ALTO Client Embedded in P2P Client: Numerical Costs 2821 P2P clients may also utilize ALTO information themselves when 2822 selecting from available peers. It is important to note that not all 2823 P2P systems use a P2P tracker for peer discovery and selection. 2824 Furthermore, even when a P2P tracker is used, the P2P clients may 2825 rely on other sources, such as peer exchange and DHTs, to discover 2826 peers. 2828 When an P2P Client uses ALTO information, it typically queries only 2829 the ALTO Server servicing its own ISP. The my-Internet view provided 2830 by its ISP's ALTO Server can include preferences to all potential 2831 peers. 2833 .---------. (1) Get Network Map .---------------. 2834 | | <----------------------> | | 2835 | ALTO | | P2P Client | 2836 | Server | (2) Get Cost Map | (ALTO Client) | 2837 | | <----------------------> | | .---------. 2838 `---------' `---------------' <- | P2P | 2839 .---------. / | ^ ^ | Tracker | 2840 | Peer 1 | <-------------- | | \ `---------' 2841 `---------' | (3) Gather Peers 2842 . (4) Select Peers | | \ 2843 . and Connect / .--------. .--------. 2844 .---------. / | P2P | | DHT | 2845 | Peer 50 | <---------------- | Client | `--------' 2846 `---------' | (PEX) | 2847 `--------' 2849 Figure 5: ALTO Client Embedded in P2P Client 2851 Figure 5 shows an example use case where a P2P Client locally applies 2852 ALTO information to select peers. The use case proceeds as follows: 2854 1. The P2P Client requests the Network Map covering all PIDs from 2855 the ALTO Server servicing its own ISP. 2857 2. The P2P Client requests the Cost Map amongst all PIDs from the 2858 ALTO Server. The Cost Map by default specifies numerical costs. 2860 3. The P2P Client discovers peers from sources such as Peer Exchange 2861 (PEX) from other P2P Clients, Distributed Hash Tables (DHT), and 2862 P2P Trackers. 2864 4. The P2P Client uses ALTO information as part of the algorithm for 2865 selecting new peers, and connects to the selected peers. 2867 12.3. ALTO Client Embedded in P2P Client: Ranking 2869 It is also possible for a P2P Client to offload the selection and 2870 ranking process to an ALTO Server. In this use case, the ALTO Client 2871 embedded in the P2P Client gathers a list of known peers in the 2872 swarm, and asks the ALTO Server to rank them. This document limits 2873 the use case to when the P2P Client and the ALTO Server are deployed 2874 by the same entity, and hence the P2P Client uses the ranking 2875 provided by the ALTO Server directly. 2877 As in the use case using numerical costs, the P2P Client typically 2878 only queries the ALTO Server servicing its own ISP. 2880 .---------. .---------------. 2881 | | | | 2882 | ALTO | (2) Get Endpoint Ranking | P2P Client | 2883 | Server | <----------------------> | (ALTO Client) | 2884 | | | | .---------. 2885 `---------' `---------------' <- | P2P | 2886 .---------. / | ^ ^ | Tracker | 2887 | Peer 1 | <-------------- | | \ `---------' 2888 `---------' | (1) Gather Peers 2889 . (3) Connect to | | \ 2890 . Selected Peers / .--------. .--------. 2891 .---------. / | P2P | | DHT | 2892 | Peer 50 | <---------------- | Client | `--------' 2893 `---------' | (PEX) | 2894 `--------' 2896 Figure 6: ALTO Client Embedded in P2P Client: Ranking 2898 Figure 6 shows an example of this scenario. The use case proceeds as 2899 follows: 2901 1. The P2P Client discovers peers from sources such as Peer Exchange 2902 (PEX) from other P2P Clients, Distributed Hash Tables (DHT), and 2903 P2P Trackers. 2905 2. The P2P Client queries the ALTO Server's Ranking Service, 2906 including discovered peers as the set of Destination Endpoints, 2907 and indicates the 'ordinal' Cost Mode. The response indicates 2908 the ranking of the candidate peers. 2910 3. The P2P Client connects to the peers in the order specified in 2911 the ranking. 2913 13. Discussions 2915 13.1. Discovery 2917 The discovery mechanism by which an ALTO Client locates an 2918 appropriate ALTO Server is out of scope for this document. This 2919 document assumes that an ALTO Client can discover an appropriate ALTO 2920 Server. Once it has done so, the ALTO Client may use the Information 2921 Resource Directory (see Section 9.2) to locate an Information 2922 Resource with the desired ALTO Information. 2924 13.2. Hosts with Multiple Endpoint Addresses 2926 In practical deployments, a particular host can be reachable using 2927 multiple addresses (e.g., a wireless IPv4 connection, a wireline IPv4 2928 connection, and a wireline IPv6 connection). In general, the 2929 particular network path followed when sending packets to the host 2930 will depend on the address that is used. Network providers may 2931 prefer one path over another. An additional consideration may be how 2932 to handle private address spaces (e.g., behind carrier-grade NATs). 2934 To support such behavior, this document allows multiple endpoint 2935 addresses and address types. With this support, the ALTO Protocol 2936 allows an ALTO Service Provider the flexibility to indicate 2937 preferences for paths from an endpoint address of one type to an 2938 endpoint address of a different type. 2940 13.3. Network Address Translation Considerations 2942 At this day and age of NAT v4<->v4, v4<->v6 [RFC6144], and possibly 2943 v6<->v6 [RFC6296], a protocol should strive to be NAT friendly and 2944 minimize carrying IP addresses in the payload, or provide a mode of 2945 operation where the source IP address provide the information 2946 necessary to the server. 2948 The protocol specified in this document provides a mode of operation 2949 where the source network location is computed by the ALTO Server 2950 (i.e., the the Endpoint Cost Service) from the source IP address 2951 found in the ALTO Client query packets. This is similar to how some 2952 P2P Trackers (e.g., BitTorrent Trackers - see "Tracker HTTP/HTTPS 2953 Protocol" in [BitTorrent]) operate. 2955 There may be cases where an ALTO Client needs to determine its own IP 2956 address, such as when specifying a source Endpoint Address in the 2957 Endpoint Cost Service. It is possible that an ALTO Client has 2958 multiple network interface addresses, and that some or all of them 2959 may require NAT for connectivity to the public Internet. 2961 If a public IP address is required for a network interface, the ALTO 2962 Client SHOULD use the Session Traversal Utilities for NAT (STUN) 2963 [RFC5389]. If using this method, the host MUST use the "Binding 2964 Request" message and the resulting "XOR-MAPPED-ADDRESS" parameter 2965 that is returned in the response. Using STUN requires cooperation 2966 from a publicly accessible STUN server. Thus, the ALTO Client also 2967 requires configuration information that identifies the STUN server, 2968 or a domain name that can be used for STUN server discovery. To be 2969 selected for this purpose, the STUN server needs to provide the 2970 public reflexive transport address of the host. 2972 ALTO Clients should be cognizant that the network path between 2973 Endpoints can depend on multiple factors, e.g., source address, and 2974 destination address used for communication. An ALTO Server provides 2975 information based on Endpoint Addresses (more generally, Network 2976 Locations), but the mechanisms used for determining existence of 2977 connectivity or usage of NAT between Endpoints are out of scope of 2978 this document. 2980 13.4. Endpoint and Path Properties 2982 An ALTO Server could make available many properties about Endpoints 2983 beyond their network location or grouping. For example, connection 2984 type, geographical location, and others may be useful to 2985 applications. This specification focuses on network location and 2986 grouping, but the protocol may be extended to handle other Endpoint 2987 properties. 2989 14. IANA Considerations 2991 This document defines registries for application/alto-* Media Types, 2992 ALTO Cost Metric, ALTO Endpoint Property Types, ALTO Address Types, 2993 and ALTO Error Codes. Initial values for the registries and the 2994 process of future assignments are given below. 2996 14.1. application/alto-* Media Types 2998 This document requests the registration of multiple media types, 2999 listed in Table 2. 3001 +-------------+------------------------------+----------------+ 3002 | Type | Subtype | Specification | 3003 +-------------+------------------------------+----------------+ 3004 | application | alto-directory+json | Section 9.2 | 3005 | application | alto-networkmap+json | Section 11.2.1 | 3006 | application | alto-networkmapfilter+json | Section 11.3.1 | 3007 | application | alto-costmap+json | Section 11.2.3 | 3008 | application | alto-costmapfilter+json | Section 11.3.2 | 3009 | application | alto-endpointprop+json | Section 11.4.1 | 3010 | application | alto-endpointpropparams+json | Section 11.4.1 | 3011 | application | alto-endpointcost+json | Section 11.5.1 | 3012 | application | alto-endpointcostparams+json | Section 11.5.1 | 3013 | application | alto-error+json | Section 8.5 | 3014 +-------------+------------------------------+----------------+ 3016 Table 2: ALTO Protocol Media Types. 3018 Type name: application 3020 Subtype name: This documents requests the registration of multiple 3021 subtypes, as listed in Table 2. 3023 Required parameters: n/a 3025 Optional parameters: n/a 3027 Encoding considerations: Encoding considerations are identical to 3028 those specified for the 'application/json' media type. See 3029 [RFC4627]. 3031 Security considerations: Security considerations relating to the 3032 generation and consumption of ALTO Protocol messages are discussed 3033 in Section 15. 3035 Interoperability considerations: This document specifies format of 3036 conforming messages and the interpretation thereof. 3038 Published specification: This document is the specification for 3039 these media types; see Table 2 for the section documenting each 3040 media type. 3042 Applications that use this media type: ALTO Servers and ALTO Clients 3043 either standalone or embedded within other applications. 3045 Additional information: 3047 Magic number(s): n/a 3049 File extension(s): This document uses the mime type to refer to 3050 protocol messages and thus does not require a file extension. 3052 Macintosh file type code(s): n/a 3054 Person & email address to contact for further information: See 3055 "Authors' Addresses" section. 3057 Intended usage: COMMON 3059 Restrictions on usage: n/a 3061 Author: See "Authors' Addresses" section. 3063 Change controller: Internet Engineering Task Force 3064 (mailto:iesg@ietf.org). 3066 14.2. ALTO Cost Metric Registry 3068 This document requests the creation of an ALTO Cost Metric registry, 3069 listed in Table 3, to be maintained by IANA. 3071 +-------------+---------------------+ 3072 | Identifier | Intended Semantics | 3073 +-------------+---------------------+ 3074 | routingcost | See Section 6.1.1.1 | 3075 | priv: | Private use | 3076 +-------------+---------------------+ 3078 Table 3: ALTO Cost Metrics. 3080 This registry serves two purposes. First, it ensures uniqueness of 3081 identifiers referring to ALTO Cost Metrics. Second, it provides 3082 references to particular semantics of allocated Cost Metrics to be 3083 applied by both ALTO Servers and applications utilizing ALTO Clients. 3085 New ALTO Cost Metrics are assigned after IETF Review [RFC5226] to 3086 ensure that proper documentation regarding ALTO Cost Metric semantics 3087 and security considerations has been provided. The RFCs documenting 3088 the new metrics should be detailed enough to provide guidance to both 3089 ALTO Service Providers and applications utilizing ALTO Clients as to 3090 how values of the registered ALTO Cost Metric should be interpreted. 3091 Updates and deletions of ALTO Cost Metrics follow the same procedure. 3093 Registered ALTO Cost Metric identifiers MUST conform to the 3094 syntactical requirements specified in Section 10.6. Identifiers are 3095 to be recorded and displayed as strings. 3097 As specified in Section 10.6, identifiers prefixed with 'priv:' are 3098 reserved for Private Use. 3100 Requests to add a new value to the registry MUST include the 3101 following information: 3103 o Identifier: The name of the desired ALTO Cost Metric. 3105 o Intended Semantics: ALTO Costs carry with them semantics to guide 3106 their usage by ALTO Clients. For example, if a value refers to a 3107 measurement, the measurement units must be documented. For proper 3108 implementation of the ordinal Cost Mode (e.g., by a third-party 3109 service), it should be documented whether higher or lower values 3110 of the cost are more preferred. 3112 o Security Considerations: ALTO Costs expose information to ALTO 3113 Clients. As such, proper usage of a particular Cost Metric may 3114 require certain information to be exposed by an ALTO Service 3115 Provider. Since network information is frequently regarded as 3116 proprietary or confidential, ALTO Service Providers should be made 3117 aware of the security ramifications related to usage of a Cost 3118 Metric. 3120 This specification requests registration of the identifier 3121 'routingcost'. Semantics for the this Cost Metric are documented in 3122 Section 6.1.1.1, and security considerations are documented in 3123 Section 15.3. 3125 14.3. ALTO Endpoint Property Type Registry 3127 This document requests the creation of an ALTO Endpoint Property 3128 Types registry, listed in Table 4, to be maintained by IANA. 3130 +------------+--------------------+ 3131 | Identifier | Intended Semantics | 3132 +------------+--------------------+ 3133 | pid | See Section 7.1.1 | 3134 | priv: | Private use | 3135 +------------+--------------------+ 3137 Table 4: ALTO Endpoint Property Types. 3139 The maintenance of this registry is similar to that of the preceding 3140 ALTO Cost Metrics. That is, the registry will be maintained by IANA, 3141 subject to the description in Section 10.8.2. 3143 New Endpoint Property Types are assigned after IETF Review [RFC5226] 3144 to ensure that proper documentation regarding ALTO Endpoint Property 3145 Type semantics and security considerations has been provided. 3146 Updates and deletions of ALTO Endpoint Property Type follow the same 3147 procedure. 3149 Registered ALTO Endpoint Property Type identifiers MUST conform to 3150 the syntactical requirements specified in Section 10.8.1. 3151 Identifiers are to be recorded and displayed as strings. 3153 As specified in Section 10.8.1, identifiers prefixed with 'priv:' are 3154 reserved for Private Use. 3156 Requests to add a new value to the registry MUST include the 3157 following information: 3159 o Identifier: The name of the desired ALTO Endpoint Property Type. 3161 o Intended Semantics: ALTO Endpoint Properties carry with them 3162 semantics to guide their usage by ALTO Clients. Hence, a document 3163 defining a new type should provide guidance to both ALTO Service 3164 Providers and applications utilizing ALTO Clients as to how values 3165 of the registered ALTO Endpoint Property should be interpreted. 3166 For example, if a value refers to a measurement, the measurement 3167 units must be documented. 3169 o Security Considerations: ALTO Endpoint Properties expose 3170 information to ALTO Clients. ALTO Service Providers should be 3171 made aware of the security ramifications related to the exposure 3172 of an Endpoint Property. 3174 In particular, the request should discuss the sensitivity of the 3175 information, and why such sensitive information is required for ALTO- 3176 based operations. It may recommend that ISP provide mechanisms for 3177 users to grant or deny consent to such information sharing. 3178 Limitation to a trust domain being a type of consent bounding. 3180 A request defining new Endpoint Properties should focus on exposing 3181 attributes of endpoints that are related to the goals of ALTO -- 3182 optimization of application-layer traffic -- as opposed to more 3183 general properties of endpoints. Maintaining this focus on 3184 technical, network-layer data will also help extension developers 3185 avoid the privacy concerns associated with publishing information 3186 about endpoints. For example: 3188 o An extension to indicate the capacity of a server would likely be 3189 appropriate, since server capacities can be used by a client to 3190 choose between multiple equivalent servers. In addition, these 3191 properties are unlikely to be viewed as private information. 3193 o An extension to indicate the geolocation of endpoints might be 3194 appropriate. In some cases, a certain level of geolocation (e.g., 3195 to the country level) can be useful for selecting content sources. 3196 More precise geolocation, however, is not relevant to content 3197 delivery, and is typically considered private. 3199 o An extension indicating demographic attributes of the owner of an 3200 endpoint (e.g., age, sex, income) would not be appropriate, 3201 because these attributes are not related to delivery optimization, 3202 and because they are clearly private data. 3204 This specification requests registration of the identifier 'pid'. 3205 Semantics for this property is documented in Section 7.1.1, and 3206 security considerations are documented in Section 15.4. 3208 14.4. ALTO Address Type Registry 3210 This document requests the creation of an ALTO Address Type registry, 3211 listed in Table 5, to be maintained by IANA. 3213 +------------+-----------------+-----------------+------------------+ 3214 | Identifier | Address | Prefix Encoding | Mapping to/from | 3215 | | Encoding | | IPv4/v6 | 3216 +------------+-----------------+-----------------+------------------+ 3217 | ipv4 | See | See | Direct mapping | 3218 | | Section 10.4.3 | Section 10.4.4 | to IPv4 | 3219 | ipv6 | See | See | Direct mapping | 3220 | | Section 10.4.3 | Section 10.4.4 | to IPv6 | 3221 +------------+-----------------+-----------------+------------------+ 3223 Table 5: ALTO Address Types. 3225 This registry serves two purposes. First, it ensures uniqueness of 3226 identifiers referring to ALTO Address Types. Second, it states the 3227 requirements for allocated Address Type identifiers. 3229 New ALTO Address Types are assigned after IETF Review [RFC5226] to 3230 ensure that proper documentation regarding the new ALTO Address Types 3231 and their security considerations has been provided. RFCs defining 3232 new Address Types should indicate how an address of a registered type 3233 is encoded as an EndpointAddr and, if possible, a compact method 3234 (e.g., IPv4 and IPv6 prefixes) for encoding a set of addresses as an 3235 EndpointPrefix. Updates and deletions of ALTO Address Types follow 3236 the same procedure. 3238 Registered ALTO Address Type identifiers MUST conform to the 3239 syntactical requirements specified in Section 10.4.2. Identifiers 3240 are to be recorded and displayed as strings. 3242 Requests to add a new value to the registry MUST include the 3243 following information: 3245 o Identifier: The name of the desired ALTO Address Type. 3247 o Endpoint Address Encoding: The procedure for encoding an address 3248 of the registered type as an EndpointAddr (see Section 10.4.3). 3250 o Endpoint Prefix Encoding: The procedure for encoding a set of 3251 addresses of the registered type as an EndpointPrefix (see 3252 Section 10.4.4). If no such compact encoding is available, the 3253 same encoding used for a singular address may be used. In such a 3254 case, it must be documented that sets of addresses of this type 3255 always have exactly one element. 3257 o Mapping to/from IPv4/IPv6 Addresses: If possible, a mechanism to 3258 map addresses of the registered type to and from IPv4 or IPv6 3259 addresses should be specified. 3261 o Security Considerations: In some usage scenarios, Endpoint 3262 Addresses carried in ALTO Protocol messages may reveal information 3263 about an ALTO Client or an ALTO Service Provider. Applications 3264 and ALTO Service Providers using addresses of the registered type 3265 should be made aware of how (or if) the addressing scheme relates 3266 to private information and network proximity. 3268 This specification requests registration of the identifiers 'ipv4' 3269 and 'ipv6', as shown in Table 5. 3271 14.5. ALTO Error Code Registry 3273 This document requests the creation of an ALTO Error Code registry, 3274 to be maintained by IANA. Initial values are listed in Table 1, and 3275 recommended usage of the Error Codes is specified in Section 8.5.2. 3277 Although the Error Codes defined in Table 1 are already quite 3278 complete, future extensions may define new Error Codes. The ALTO 3279 Error Code registry ensures the uniqueness of Error Codes when new 3280 Error Codes are added. 3282 New ALTO Error Codes are assigned after IETF Review [RFC5226] to 3283 ensure that proper documentation regarding the new ALTO Error Codes 3284 and their usage has been provided. 3286 A request to add a new ALTO Error Code to the registry MUST include 3287 the following information: 3289 o Error Code: A string starting with E_ to indicate the error. 3291 o Intended Usage: ALTO Error Codes carry with them semantics to 3292 guide their usage by ALTO Servers and Clients. In particular, if 3293 a new Error Code indicates conditions that overlap with those of 3294 an existing ALTO Error Code, recommended usage of the new Error 3295 Code should be specified. 3297 15. Security Considerations 3299 Some environments and use cases of ALTO require consideration of 3300 security attacks on ALTO Servers and Clients. In order to support 3301 those environments interoperably, the ALTO requirements document 3302 [RFC6708] outlines minimum-to-implement authentication and other 3303 security requirements. This document considers the following threats 3304 and protection strategies. 3306 15.1. Authenticity and Integrity of ALTO Information 3308 15.1.1. Risk Scenarios 3310 An attacker may want to provide false or modified ALTO Information 3311 Resources or Information Resource Directory to ALTO Clients to 3312 achieve certain malicious goals. As an example, an attacker may 3313 provide false endpoint properties. For example, suppose that a 3314 network supports an endpoint property named "hasQuota" which reports 3315 whether an endpoint has usage quota. An attacker may want to 3316 generate a false reply to lead to unexpected charges to the endpoint. 3317 An attack may also want to provide false Cost Map. For example, by 3318 faking a Cost Map that highly prefers a small address range or a 3319 single address, the attacker may be able to turn a distributed 3320 application into a Distributed Denial of Service (DDoS) tool. 3322 Depending on the network scenario, an attacker can attack 3323 authenticity and integrity of ALTO Information Resources using 3324 various techniques, including, but not limited to, sending forged 3325 DHCP replies in an Ethernet, DNS poisoning, and installing a 3326 transparent HTTP proxy that does some modifications. 3328 15.1.2. Protection Strategies 3330 ALTO protects the authenticity and integrity of ALTO Information 3331 (both Information Directory and individual Information Resources) by 3332 leveraging the authenticity and integrity mechanisms in TLS (see 3333 Section 8.3.5). 3335 ALTO Providers who request server certificates and certification 3336 authorities who issue ALTO-specific certificates SHOULD consider the 3337 recommendations and guidelines defined in [RFC6125]. 3339 Software engineers developing and service providers deploying ALTO 3340 should make themselves familiar with possibly updated standards 3341 documents as well as up-to-date Best Current Practices on configuring 3342 HTTP over TLS. 3344 15.1.3. Limitations 3346 The protection of HTTP over TLS for ALTO depends on that the domain 3347 name in the URI for the Information Resources is not comprised. This 3348 will depend on the protection implemented by service discovery. 3350 A deployment scenario may require redistribution of ALTO information 3351 to improve scalability. When authenticity and integrity of ALTO 3352 information are still required, then ALTO Clients obtaining ALTO 3353 information through redistribution must be able to validate the 3354 received ALTO information. Support for this validation is not 3355 provided in this document, but may be provided by extension 3356 documents. 3358 15.2. Potential Undesirable Guidance from Authenticated ALTO 3359 Information 3361 15.2.1. Risk Scenarios 3363 The ALTO Service makes it possible for an ALTO Provider to influence 3364 the behavior of network applications. An ALTO Provider may be 3365 hostile to some applications and hence try to use ALTO Information 3366 Resources to achieve certain goals [RFC5693]: "redirecting 3367 applications to corrupted mediators providing malicious content, or 3368 applying policies in computing Cost Map based on criteria other than 3369 network efficiency." See [I-D.ietf-alto-deployments] for additional 3370 discussions on faked ALTO Guidance. 3372 A related scenario is that an ALTO Server could unintentionally give 3373 "bad" guidance. For example, if many ALTO Clients follow the Cost 3374 Map or Endpoint Cost guidance without doing additional sanity checks 3375 or adaptation, more preferable hosts and/or links could get 3376 overloaded while less preferable ones remain idle; see AR-14 of 3377 [RFC6708] for related application considerations. 3379 15.2.2. Protection Strategies 3381 To protect applications from undesirable ALTO Information Resources, 3382 it is important to note that there is no protocol mechanism to 3383 require conforming behaviors on how applications use ALTO Information 3384 Resources. An application using ALTO may consider including a 3385 mechanism to detect misleading or undesirable results from using ALTO 3386 Information Resources. For example, if throughput measurements do 3387 not show "better-than-random" results when using the Cost Map to 3388 select resource providers, the application may want to disable ALTO 3389 usage or switch to an external ALTO Server provided by an 3390 "independent organization" (see AR-20 and AR-21 in [RFC6708]). If 3391 the first ALTO Server is provided by the access network service 3392 provider and the access network service provider tries to redirect 3393 access to the external ALTO Server back to the provider's ALTO Server 3394 or try to tamper with the responses, the preceding authentication and 3395 integrity protection can detect such a behavior. 3397 15.3. Confidentiality of ALTO Information 3399 15.3.1. Risk Scenarios 3401 Although in many cases ALTO Information Resources may be regarded as 3402 non-confidential information, there are deployment cases where ALTO 3403 Information Resources can be sensitive information that can pose 3404 risks if exposed to unauthorized parties. This document discusses 3405 the risks and protection strategies for such deployment scenarios. 3407 For example, an attacker may infer details regarding the topology, 3408 status, and operational policies of a network through the Network and 3409 Cost Maps. As a result, a sophisticated attacker may be able to 3410 infer more fine-grained topology information than an ISP hosting an 3411 ALTO Server intends to disclose. The attacker can leverage the 3412 information to mount effective attacks such as focusing on high-cost 3413 links. 3415 Revealing some endpoint properties may also reveal additional 3416 information than the Provider intended. For example, when adding the 3417 line bitrate as one endpoint property, such information may be 3418 potentially linked to the income of the habitants at the network 3419 location of an endpoint. 3421 In [RFC6708] Section 5.2.1, three types of risks associated with the 3422 confidentiality of ALTO Information Resources are identified: risk 3423 type (1) Excess disclosure of the ALTO service provider's data to an 3424 authorized ALTO Client; risk type (2) Disclosure of the ALTO service 3425 provider's data (e.g., network topology information or endpoint 3426 addresses) to an unauthorized third party; and risk type (3) Excess 3427 retrieval of the ALTO service provider's data by collaborating ALTO 3428 Clients. [I-D.ietf-alto-deployments] also discusses information 3429 leakage from ALTO. 3431 15.3.2. Protection Strategies 3433 To address risk types (1) and (3), the Provider of an ALTO Server 3434 must be cognizant that the network topology and provisioning 3435 information provided through ALTO may lead to attacks. ALTO does not 3436 require any particular level of details of information disclosure, 3437 and hence the Provider should evaluate how much information is 3438 revealed and the associated risks. 3440 To address risk type (2), the ALTO Protocol needs confidentiality. 3441 Since ALTO requires that HTTP over TLS must be supported, the 3442 confidentiality mechanism is provided by HTTP over TLS. 3444 For deployment scenarios where client authentication is desired to 3445 address risk type (2), ALTO requires that HTTP Digestion 3446 Authentication is supported to achieve ALTO Client Authentication to 3447 limit the number of parties with whom ALTO information is directly 3448 shared. TLS Client Authentication may also be supported. Depending 3449 on the use-case and scenario, an ALTO Server may apply other access 3450 control techniques to restrict access to its services. Access 3451 control can also help to prevent Denial-of-Service attacks by 3452 arbitrary hosts from the Internet. See [I-D.ietf-alto-deployments] 3453 for a more detailed discussion on this issue. 3455 See Section 14.3 on guidelines when registering Endpoint Properties 3456 to protect endpoint privacy. 3458 15.3.3. Limitations 3460 ALTO Information Providers should be cognizant that encryption only 3461 protects ALTO information until it is decrypted by the intended ALTO 3462 Client. Digital Rights Management (DRM) techniques and legal 3463 agreements protecting ALTO information are outside of the scope of 3464 this document. 3466 15.4. Privacy for ALTO Users 3468 15.4.1. Risk Scenarios 3470 The ALTO Protocol provides mechanisms in which the ALTO Client 3471 serving a user can send messages containing Network Location 3472 Identifiers (IP addresses or fine-grained PIDs) to the ALTO Server. 3473 This is particularly true for the Endpoint Property, Endpoint Cost, 3474 and fine-grained Filtered Map services. The ALTO Server or a third- 3475 party who is able to intercept such messages can store and process 3476 obtained information in order to analyze user behaviors and 3477 communication patterns. The analysis may correlate information 3478 collected from multiple clients to deduce additional application/ 3479 content information. Such analysis can lead to privacy risks. For a 3480 more comprehensive classification of related risk scenarios, see 3481 cases 4, 5, and 6 in [RFC6708], Section 5.2. 3483 15.4.2. Protection Strategies 3485 To protect user privacy, an ALTO Client should be cognizant about 3486 potential ALTO Server tracking through client queries, e.g., by using 3487 HTTP cookies. The ALTO Protocol as defined by this document does not 3488 rely on HTTP cookies. ALTO Clients MAY decide to not return cookies 3489 received from the server, in order to make tracking more difficult. 3490 However, this might break protocol extensions that are beyond the 3491 scope of this document. 3493 An ALTO Client may consider the possibility of relying only on 3494 Network Map for PIDs and Cost Map amongst PIDs to avoid passing IP 3495 addresses of other endpoints (e.g., peers) to the ALTO Server. When 3496 specific IP addresses are needed (e.g., when using the Endpoint Cost 3497 Service), an ALTO Client SHOULD minimize the amount of information 3498 sent in IP addresses. For example, the ALTO Client may consider 3499 obfuscation techniques such as specifying a broader address range 3500 (i.e., a shorter prefix length) or by zeroing out or randomizing the 3501 last few bits of IP addresses. Note that obfuscation may yield less 3502 accurate results. 3504 15.5. Availability of ALTO Service 3506 15.5.1. Risk Scenarios 3508 An attacker may want to disable ALTO Service as a way to disable 3509 network guidance to large scale applications.In particular, queries 3510 which can be generated with low effort but result in expensive 3511 workloads at the ALTO Server could be exploited for Denial-of-Service 3512 attacks. For instance, a simple ALTO query with n Source Network 3513 Locations and m Destination Network Locations can be generated fairly 3514 easily but results in the computation of n*m Path Costs between pairs 3515 by the ALTO Server (see Section 5.2). 3517 15.5.2. Protection Strategies 3519 ALTO Provider should be cognizant of the workload at the ALTO Server 3520 generated by certain ALTO Queries, such as certain queries to the Map 3521 Service, the Map Filtering Service and the Endpoint Cost (Ranking) 3522 Service. One way to limit Denial-of-Service attacks is to employ 3523 access control to the ALTO Server. The ALTO Server can also indicate 3524 overload and reject repeated requests that can cause availability 3525 problems. More advanced protection schemes such as computational 3526 puzzles [I-D.jennings-sip-hashcash] may be considered in an extension 3527 document. 3529 An ALTO Provider should also leverage the fact that the Map Service 3530 allows ALTO Servers to pre-generate maps that can be distributed to 3531 many ALTO Clients. 3533 16. Manageability Considerations 3535 This section details operations and management considerations based 3536 on existing deployments and discussions during protocol development. 3537 It also indicates where extension documents are expected to provide 3538 appropriate functionality discussed in [RFC5706] as additional 3539 deployment experience becomes available. 3541 16.1. Operations 3543 16.1.1. Installation and Initial Setup 3545 The ALTO Protocol is based on HTTP. Thus, configuring an ALTO Server 3546 may require configuring the underlying HTTP server implementation to 3547 define appropriate security policies, caching policies, performance 3548 settings, etc. 3550 Additionally, an ALTO Service Provider will need to configure the 3551 ALTO information to be provided by the ALTO Server. The granularity 3552 of the topological map and the cost map is left to the specific 3553 policies of the ALTO Service Provider. However, a reasonable default 3554 may include two PIDs, one to hold the endpoints in the provider's 3555 network and the second PID to represent full IPv4 and IPv6 3556 reachability (see Section 11.2.2), with the cost between each source/ 3557 destination PID set to 1. Another operational issue that the ALTO 3558 Service Provider needs to consider is that the filtering service can 3559 degenerate into a full map service when the filtering input is empty. 3560 Although this choice as the degeneration behavior provides 3561 continuity, the computational and network load of serving full maps 3562 to a large number of ALTO Clients should be considered. 3564 Implementers employing an ALTO Client should attempt to automatically 3565 discover an appropriate ALTO Server. Manual configuration of the 3566 ALTO Server location may be used where automatic discovery is not 3567 appropriate. Methods for automatic discovery and manual 3568 configuration are discussed in [I-D.ietf-alto-server-discovery]. 3570 Specifications for underlying protocols (e.g., TCP, HTTP, TLS) should 3571 be consulted for their available settings and proposed default 3572 configurations. 3574 16.1.2. Migration Path 3576 This document does not detail a migration path for ALTO Servers since 3577 there is no previous standard protocol providing the similar 3578 functionality. 3580 There are existing applications making use of network information 3581 discovered from other entities such as whois, geo-location databases, 3582 or round-trip time measurements, etc. Such applications should 3583 consider using ALTO as an additional source of information; ALTO need 3584 not be the sole source of network information. 3586 16.1.3. Dependencies on Other Protocols and Functional Components 3588 The ALTO Protocol assumes that HTTP client and server implementations 3589 exist. It also assumes that JSON encoder and decoder implementations 3590 exist. 3592 An ALTO Server assumes that it can gather sufficient information to 3593 populate Network and Cost maps. "Sufficient information" is 3594 dependent on the information being exposed, but likely includes 3595 information gathered from protocols such as IGP and EGP Routing 3596 Information Bases (see Figure 1). Specific mechanisms have been 3597 proposed (e.g., [I-D.medved-alto-svr-apis]) and are expected to be 3598 provided in extension documents. 3600 16.1.4. Impact and Observation on Network Operation 3602 ALTO presents a new opportunity for managing network traffic by 3603 providing additional information to clients. In particular, the 3604 deployment of an ALTO Server may shift network traffic patterns, and 3605 the potential impact to network operation can be large. An ALTO 3606 Service Provider should ensure that appropriate information is being 3607 exposed. Privacy implications for ISPs are discussed in 3608 Section 15.3. 3610 An ALTO Service Provider should consider how to measure impacts on 3611 (or integration with) traffic engineering, in addition to monitoring 3612 correctness and responsiveness of ALTO Servers. The measurement of 3613 impacts can be challenging because ALTO-enabled applications may not 3614 provide related information back to the ALTO Service Provider. 3615 Furthermore, the measurement of an ALTO Service Provider may show 3616 that ALTO Clients are not bound to ALTO Server guidance as ALTO is 3617 only one source of information. 3619 While it can be challenging to measure the impact of ALTO guidance, 3620 there exist some possible techniques. In certain trusted deployment 3621 environments, it may be possible to collect information directly from 3622 ALTO clients. It may also be possible to vary or selectively disable 3623 ALTO guidance for a portion of ALTO clients either by time, 3624 geographical region, or some other criteria to compare the network 3625 traffic characteristics with and without ALTO. 3627 Both ALTO Service Providers and those using ALTO Clients should be 3628 aware of the impact of incorrect or faked guidance (see 3629 [I-D.ietf-alto-deployments]). 3631 16.2. Management 3633 16.2.1. Management Interoperability 3635 A common management API would be desirable given that ALTO Servers 3636 may typically be configured with dynamic data from various sources, 3637 and ALTO Servers are intended to scale horizontally for fault- 3638 tolerance and reliability. A specific API or protocol is outside the 3639 scope of this document, but may be provided by an extension document. 3641 Logging is an important functionality for ALTO Servers and, depending 3642 on the deployment, ALTO Clients. Logging should be done via syslog 3643 [RFC5424]. 3645 16.2.2. Management Information 3647 A Management Information Model (see Section 3.2 of [RFC5706]) is not 3648 provided by this document, but should be included or referenced by 3649 any extension documenting an ALTO-related management API or protocol. 3651 16.2.3. Fault Management 3653 An ALTO Service Provider should monitor whether any ALTO Servers have 3654 failed. See Section 16.2.5 for related metrics which may indicate 3655 server failures. 3657 16.2.4. Configuration Management 3659 Standardized approaches and protocols to configuration management for 3660 ALTO are outside the scope of this document, but this document does 3661 outline high-level principles suggested for future standardization 3662 efforts. 3664 An ALTO Server requires at least the following logical inputs: 3666 o Data sources from which ALTO Information is derived. This can 3667 either be raw network information (e.g., from routing elements) or 3668 pre-processed ALTO-level information in the form of a Network Map, 3669 Cost Map, etc. 3671 o Algorithms for computing the ALTO information returned to clients. 3672 These could either return information from a database, or 3673 information customized for each client. 3675 o Security policies mapping potential clients to the information 3676 that they have privilege to access. 3678 Multiple ALTO Servers can be deployed for scalability. A centralized 3679 configuration database may be used to ensure they are providing the 3680 desired ALTO information with appropriate security controls. The 3681 ALTO information (e.g., Network Maps and Cost Maps) being served by 3682 each ALTO Server, as well as security policies (HTTP authentication, 3683 TLS client and server authentication, TLS encryption parameters) 3684 intended to serve the same information should be monitored for 3685 consistency. 3687 16.2.5. Performance Management 3689 An exhaustive list of desirable performance information from ALTO 3690 Servers and ALTO Clients are outside of the scope of this document. 3691 The following is a list of suggested ALTO-specific metrics to be 3692 monitored based on the existing deployment and protocol development 3693 experience: 3695 o Requests and responses for each service listed in a Information 3696 Directory (total counts and size in bytes). 3698 o CPU and memory utilization 3700 o ALTO map updates 3702 o Number of PIDs 3704 o ALTO map sizes (in-memory size, encoded size, number of entries) 3706 16.2.6. Security Management 3708 Section 15 documents ALTO-specific security considerations. 3709 Operators should configure security policies with those in mind. 3710 Readers should refer to HTTP [RFC2616] and TLS [RFC5246] and related 3711 documents for mechanisms available for configuring security policies. 3712 Other appropriate security mechanisms (e.g., physical security, 3713 firewalls, etc) should also be considered. 3715 17. References 3717 17.1. Normative References 3719 [RFC1812] Baker, F., "Requirements for IP Version 4 Routers", 3720 RFC 1812, June 1995. 3722 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3723 Extensions (MIME) Part Two: Media Types", RFC 2046, 3724 November 1996. 3726 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3727 Requirement Levels", BCP 14, RFC 2119, March 1997. 3729 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3730 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3731 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3733 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3734 Resource Identifier (URI): Generic Syntax", STD 66, 3735 RFC 3986, January 2005. 3737 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 3738 (CIDR): The Internet Address Assignment and Aggregation 3739 Plan", BCP 122, RFC 4632, August 2006. 3741 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3742 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3743 May 2008. 3745 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3746 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3748 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 3749 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 3750 October 2008. 3752 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009. 3754 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3755 Address Text Representation", RFC 5952, August 2010. 3757 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3758 Verification of Domain-Based Application Service Identity 3759 within Internet Public Key Infrastructure Using X.509 3760 (PKIX) Certificates in the Context of Transport Layer 3761 Security (TLS)", RFC 6125, March 2011. 3763 17.2. Informative References 3765 [BitTorrent] 3766 "Bittorrent Protocol Specification v1.0", 3767 . 3769 [Fielding-Thesis] 3770 Fielding, R., "Architectural Styles and the Design of 3771 Network-based Software Architectures", University of 3772 California, Irvine, Dissertation 2000, 2000. 3774 [I-D.akonjang-alto-proxidor] 3775 Akonjang, O., Feldmann, A., Previdi, S., Davie, B., and D. 3776 Saucez, "The PROXIDOR Service", 3777 draft-akonjang-alto-proxidor-00 (work in progress), 3778 March 2009. 3780 [I-D.ietf-alto-deployments] 3781 Stiemerling, M., Kiesel, S., Previdi, S., and M. Scharf, 3782 "ALTO Deployment Considerations", 3783 draft-ietf-alto-deployments-09 (work in progress), 3784 February 2014. 3786 [I-D.ietf-alto-server-discovery] 3787 Kiesel, S., Stiemerling, M., Schwan, N., Scharf, M., and 3788 S. Yongchao, "ALTO Server Discovery", 3789 draft-ietf-alto-server-discovery-10 (work in progress), 3790 September 2013. 3792 [I-D.ietf-httpbis-p2-semantics] 3793 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3794 (HTTP/1.1): Semantics and Content", 3795 draft-ietf-httpbis-p2-semantics-26 (work in progress), 3796 February 2014. 3798 [I-D.jenkins-alto-cdn-use-cases] 3799 Niven-Jenkins, B., Watson, G., Bitar, N., Medved, J., and 3800 S. Previdi, "Use Cases for ALTO within CDNs", 3801 draft-jenkins-alto-cdn-use-cases-03 (work in progress), 3802 June 2012. 3804 [I-D.jennings-sip-hashcash] 3805 Jennings, C., "Computational Puzzles for SPAM Reduction in 3806 SIP", draft-jennings-sip-hashcash-06 (work in progress), 3807 July 2007. 3809 [I-D.medved-alto-svr-apis] 3810 Medved, J., Ward, D., Peterson, J., Woundy, R., and D. 3811 McDysan, "ALTO Network-Server and Server-Server APIs", 3812 draft-medved-alto-svr-apis-00 (work in progress), 3813 March 2011. 3815 [I-D.p4p-framework] 3816 Alimi, R., Pasko, D., Popkin, L., Wang, Y., and Y. Yang, 3817 "P4P: Provider Portal for P2P Applications", 3818 draft-p4p-framework-00 (work in progress), November 2008. 3820 [I-D.saumitra-alto-multi-ps] 3821 Das, S., Narayanan, V., and L. Dondeti, "ALTO: A Multi 3822 Dimensional Peer Selection Problem", 3823 draft-saumitra-alto-multi-ps-00 (work in progress), 3824 October 2008. 3826 [I-D.saumitra-alto-queryresponse] 3827 Das, S. and V. Narayanan, "A Client to Service Query 3828 Response Protocol for ALTO", 3829 draft-saumitra-alto-queryresponse-00 (work in progress), 3830 March 2009. 3832 [I-D.shalunov-alto-infoexport] 3833 Shalunov, S., Penno, R., and R. Woundy, "ALTO Information 3834 Export Service", draft-shalunov-alto-infoexport-00 (work 3835 in progress), October 2008. 3837 [I-D.wang-alto-p4p-specification] 3838 Wang, Y., Alimi, R., Pasko, D., Popkin, L., and Y. Yang, 3839 "P4P Protocol Specification", 3840 draft-wang-alto-p4p-specification-00 (work in progress), 3841 March 2009. 3843 [IEEE.754.2008] 3844 Institute of Electrical and Electronics Engineers, 3845 "Standard for Binary Floating-Point Arithmetic", IEEE 3846 Standard 754, August 2008. 3848 [P4P-SIGCOMM08] 3849 Xie, H., Yang, Y., Krishnamurthy, A., Liu, Y., and A. 3850 Silberschatz, "P4P: Provider Portal for (P2P) 3851 Applications", SIGCOMM 2008, August 2008. 3853 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3855 [RFC4627] Crockford, D., "The application/json Media Type for 3856 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 3858 [RFC5693] Seedorf, J. and E. Burger, "Application-Layer Traffic 3859 Optimization (ALTO) Problem Statement", RFC 5693, 3860 October 2009. 3862 [RFC5706] Harrington, D., "Guidelines for Considering Operations and 3863 Management of New Protocols and Protocol Extensions", 3864 RFC 5706, November 2009. 3866 [RFC6144] Baker, F., Li, X., Bao, C., and K. Yin, "Framework for 3867 IPv4/IPv6 Translation", RFC 6144, April 2011. 3869 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 3870 Translation", RFC 6296, June 2011. 3872 [RFC6708] Kiesel, S., Previdi, S., Stiemerling, M., Woundy, R., and 3873 Y. Yang, "Application-Layer Traffic Optimization (ALTO) 3874 Requirements", RFC 6708, September 2012. 3876 Appendix A. Acknowledgments 3878 Thank you to Sebastian Kiesel (University of Stuttgart) and Jan 3879 Seedorf (NEC) for substantial contributions to the Security 3880 Considerations section. Ben Niven-Jenkins (Velocix), Michael Scharf 3881 and Sabine Randriamasy (Alcatel-Lucent) gave substantial feedback and 3882 suggestions on the protocol design. We are particularly grateful to 3883 the substantial contributions of Wendy Roome (Alcatel-Lucent). 3885 We would like to thank the following people whose input and 3886 involvement was indispensable in achieving this merged proposal: 3888 Obi Akonjang (DT Labs/TU Berlin), 3890 Saumitra M. Das (Qualcomm Inc.), 3892 Syon Ding (China Telecom), 3894 Doug Pasko (Verizon), 3896 Laird Popkin (Pando Networks), 3898 Satish Raghunath (Juniper Networks), 3900 Albert Tian (Ericsson/Redback), 3902 Yu-Shun Wang (Microsoft), 3904 David Zhang (PPLive), 3906 Yunfei Zhang (China Mobile). 3908 We would also like to thank the following additional people who were 3909 involved in the projects that contributed to this merged document: 3910 Alex Gerber (ATT), Chris Griffiths (Comcast), Ramit Hora (Pando 3911 Networks), Arvind Krishnamurthy (University of Washington), Marty 3912 Lafferty (DCIA), Erran Li (Bell Labs), Jin Li (Microsoft), Y. Grace 3913 Liu (IBM Watson), Jason Livingood (Comcast), Michael Merritt (ATT), 3914 Ingmar Poese (DT Labs/TU Berlin), James Royalty (Pando Networks), 3915 Damien Saucez (UCL) Thomas Scholl (ATT), Emilio Sepulveda 3916 (Telefonica), Avi Silberschatz (Yale University), Hassan Sipra (Bell 3917 Canada), Georgios Smaragdakis (DT Labs/TU Berlin), Haibin Song 3918 (Huawei), Oliver Spatscheck (ATT), See-Mong Tang (Microsoft), Jia 3919 Wang (ATT), Hao Wang (Yale University), Ye Wang (Yale University), 3920 Haiyong Xie (Yale University). 3922 Appendix B. Design History and Merged Proposals 3924 The ALTO Protocol specified in this document consists of 3925 contributions from 3927 o P4P [I-D.p4p-framework], [P4P-SIGCOMM08], 3928 [I-D.wang-alto-p4p-specification]; 3930 o ALTO Info-Export [I-D.shalunov-alto-infoexport]; 3932 o Query/Response [I-D.saumitra-alto-queryresponse], 3933 [I-D.saumitra-alto-multi-ps]; and 3935 o Proxidor [I-D.akonjang-alto-proxidor]. 3937 Appendix C. Authors 3939 [[CmtAuthors: RFC Editor: Please move information in this section to 3940 the Authors' Addresses section at publication time.]] 3942 Sebastian Kiesel 3943 University of Stuttgart Computing Center 3944 Networks and Communication Systems Department 3945 Allmandring 30 3946 70550 Stuttgart 3947 Germany 3949 Email: ietf-alto@skiesel.de 3951 Stefano Previdi 3952 Cisco 3954 Email: sprevidi@cisco.com 3956 Wendy Roome 3957 Alcatel Lucent 3959 Email: w.roome@alcatel-lucent.com 3960 Stanislav Shalunov 3961 BitTorrent 3963 Email: shalunov@bittorrent.com 3965 Richard Woundy 3966 Comcast 3968 Richard_Woundy@cable.comcast.com 3970 Authors' Addresses 3972 Richard Alimi (editor) 3973 Google 3974 1600 Amphitheatre Parkway 3975 Mountain View CA 3976 USA 3978 Email: ralimi@google.com 3980 Reinaldo Penno (editor) 3981 Cisco Systems 3982 170 West Tasman Dr 3983 San Jose CA 3984 USA 3986 Email: repenno@cisco.com 3988 Y. Richard Yang (editor) 3989 Yale University 3990 51 Prospect St 3991 New Haven CT 3992 USA 3994 Email: yry@cs.yale.edu