idnits 2.17.1 draft-ietf-alto-protocol-25.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 1048 has weird spacing: '... meta meta ...' == Line 1327 has weird spacing: '...ilities capa...' == Line 1819 has weird spacing: '...ostMode cost...' == Line 2302 has weird spacing: '...ostType cost...' == Line 2304 has weird spacing: '...DFilter pids;...' == (2 more instances...) -- The document date (January 18, 2014) is 3750 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-08 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-25 -- 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 (~~), 9 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: July 22, 2014 Cisco Systems 6 Y. Yang, Ed. 7 Yale University 8 January 18, 2014 10 ALTO Protocol 11 draft-ietf-alto-protocol-25.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 July 22, 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 . . . . . . . . 11 93 4. ALTO Information Service Framework . . . . . . . . . . . . . . 11 94 4.1. ALTO Information Services . . . . . . . . . . . . . . . . 12 95 4.1.1. Map Service . . . . . . . . . . . . . . . . . . . . . 12 96 4.1.2. Map Filtering Service . . . . . . . . . . . . . . . . 13 97 4.1.3. Endpoint Property Service . . . . . . . . . . . . . . 13 98 4.1.4. Endpoint Cost Service . . . . . . . . . . . . . . . . 13 99 5. Network Map . . . . . . . . . . . . . . . . . . . . . . . . . 13 100 5.1. Provider-defined Identifier (PID) . . . . . . . . . . . . 13 101 5.2. Endpoint Addresses . . . . . . . . . . . . . . . . . . . . 14 102 5.3. Example Network Map . . . . . . . . . . . . . . . . . . . 14 103 6. Cost Map . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 104 6.1. Cost Types . . . . . . . . . . . . . . . . . . . . . . . . 16 105 6.1.1. Cost Metric . . . . . . . . . . . . . . . . . . . . . 16 106 6.1.2. Cost Mode . . . . . . . . . . . . . . . . . . . . . . 17 107 6.2. Cost Map Structure . . . . . . . . . . . . . . . . . . . . 18 108 6.3. Network Map and Cost Map Dependency . . . . . . . . . . . 18 109 6.4. Cost Map Update . . . . . . . . . . . . . . . . . . . . . 18 110 7. Endpoint Properties . . . . . . . . . . . . . . . . . . . . . 19 111 7.1. Endpoint Property Type . . . . . . . . . . . . . . . . . . 19 112 7.1.1. Endpoint Property Type: pid . . . . . . . . . . . . . 19 113 8. Protocol Specification: General Processing . . . . . . . . . . 19 114 8.1. Overall Design . . . . . . . . . . . . . . . . . . . . . . 19 115 8.2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . 20 116 8.3. Basic Operations . . . . . . . . . . . . . . . . . . . . . 20 117 8.3.1. Client Discovering Information Resources . . . . . . . 21 118 8.3.2. Client Requesting Information Resources . . . . . . . 21 119 8.3.3. Server Responding to IR Request . . . . . . . . . . . 22 120 8.3.4. Client Handling Server Response . . . . . . . . . . . 22 121 8.3.5. Authentication and Encryption . . . . . . . . . . . . 23 122 8.3.6. Information Refreshing . . . . . . . . . . . . . . . . 23 123 8.3.7. HTTP Cookies . . . . . . . . . . . . . . . . . . . . . 23 124 8.3.8. Parsing of Unknown Fields . . . . . . . . . . . . . . 23 125 8.4. Server Response Encoding . . . . . . . . . . . . . . . . . 24 126 8.4.1. Meta Information . . . . . . . . . . . . . . . . . . . 24 127 8.4.2. Data Information . . . . . . . . . . . . . . . . . . . 24 128 8.5. Protocol Errors . . . . . . . . . . . . . . . . . . . . . 24 129 8.5.1. Media Type . . . . . . . . . . . . . . . . . . . . . . 25 130 8.5.2. Response Format and Error Codes . . . . . . . . . . . 25 131 8.5.3. Overload Conditions and Server Unavailability . . . . 27 132 9. Protocol Specification: Information Resource Directory . . . . 27 133 9.1. Information Resource Attributes . . . . . . . . . . . . . 27 134 9.1.1. Resource ID . . . . . . . . . . . . . . . . . . . . . 28 135 9.1.2. Media Type . . . . . . . . . . . . . . . . . . . . . . 28 136 9.1.3. Capabilities . . . . . . . . . . . . . . . . . . . . . 28 137 9.1.4. Accepts Input Parameters . . . . . . . . . . . . . . . 28 138 9.1.5. Dependent Resources . . . . . . . . . . . . . . . . . 28 139 9.2. Information Resource Directory (IRD) . . . . . . . . . . . 28 140 9.2.1. Media Type . . . . . . . . . . . . . . . . . . . . . . 29 141 9.2.2. Encoding . . . . . . . . . . . . . . . . . . . . . . . 29 142 9.2.3. Example . . . . . . . . . . . . . . . . . . . . . . . 31 143 9.2.4. Delegation using IRD . . . . . . . . . . . . . . . . . 34 144 9.2.5. Considerations of Using IRD . . . . . . . . . . . . . 36 145 10. Protocol Specification: Basic Data Types . . . . . . . . . . . 36 146 10.1. PID Name . . . . . . . . . . . . . . . . . . . . . . . . . 36 147 10.2. Resource ID . . . . . . . . . . . . . . . . . . . . . . . 37 148 10.3. Version Tag . . . . . . . . . . . . . . . . . . . . . . . 37 149 10.4. Endpoints . . . . . . . . . . . . . . . . . . . . . . . . 37 150 10.4.1. Typed Endpoint Addresses . . . . . . . . . . . . . . . 38 151 10.4.2. Address Type . . . . . . . . . . . . . . . . . . . . . 38 152 10.4.3. Endpoint Address . . . . . . . . . . . . . . . . . . . 38 153 10.4.4. Endpoint Prefixes . . . . . . . . . . . . . . . . . . 38 154 10.4.5. Endpoint Address Group . . . . . . . . . . . . . . . . 39 155 10.5. Cost Mode . . . . . . . . . . . . . . . . . . . . . . . . 40 156 10.6. Cost Metric . . . . . . . . . . . . . . . . . . . . . . . 40 157 10.7. Cost Type . . . . . . . . . . . . . . . . . . . . . . . . 40 158 10.8. Endpoint Property . . . . . . . . . . . . . . . . . . . . 41 159 10.8.1. Resource Specific Endpoint Properties . . . . . . . . 41 160 10.8.2. Global Endpoint Properties . . . . . . . . . . . . . . 41 161 11. Protocol Specification: Service Information Resources . . . . 41 162 11.1. Meta Information . . . . . . . . . . . . . . . . . . . . . 42 163 11.2. Map Service . . . . . . . . . . . . . . . . . . . . . . . 42 164 11.2.1. Network Map . . . . . . . . . . . . . . . . . . . . . 42 165 11.2.2. Mapping IP Addresses to PIDs for 'ipv4'/'ipv6' 166 Network Maps . . . . . . . . . . . . . . . . . . . . . 45 167 11.2.3. Cost Map . . . . . . . . . . . . . . . . . . . . . . . 46 168 11.3. Map Filtering Service . . . . . . . . . . . . . . . . . . 49 169 11.3.1. Filtered Network Map . . . . . . . . . . . . . . . . . 49 170 11.3.2. Filtered Cost Map . . . . . . . . . . . . . . . . . . 51 171 11.4. Endpoint Property Service . . . . . . . . . . . . . . . . 55 172 11.4.1. Endpoint Property . . . . . . . . . . . . . . . . . . 56 173 11.5. Endpoint Cost Service . . . . . . . . . . . . . . . . . . 59 174 11.5.1. Endpoint Cost . . . . . . . . . . . . . . . . . . . . 59 175 12. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 62 176 12.1. ALTO Client Embedded in P2P Tracker . . . . . . . . . . . 63 177 12.2. ALTO Client Embedded in P2P Client: Numerical Costs . . . 64 178 12.3. ALTO Client Embedded in P2P Client: Ranking . . . . . . . 65 179 13. Discussions . . . . . . . . . . . . . . . . . . . . . . . . . 66 180 13.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 66 181 13.2. Hosts with Multiple Endpoint Addresses . . . . . . . . . . 67 182 13.3. Network Address Translation Considerations . . . . . . . . 67 183 13.4. Endpoint and Path Properties . . . . . . . . . . . . . . . 68 184 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 68 185 14.1. application/alto-* Media Types . . . . . . . . . . . . . . 68 186 14.2. ALTO Cost Metric Registry . . . . . . . . . . . . . . . . 70 187 14.3. ALTO Endpoint Property Type Registry . . . . . . . . . . . 71 188 14.4. ALTO Address Type Registry . . . . . . . . . . . . . . . . 71 189 14.5. ALTO Error Code Registry . . . . . . . . . . . . . . . . . 73 190 15. Security Considerations . . . . . . . . . . . . . . . . . . . 73 191 15.1. Authenticity and Integrity of ALTO Information . . . . . . 73 192 15.1.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 73 193 15.1.2. Protection Strategies . . . . . . . . . . . . . . . . 74 194 15.1.3. Limitations . . . . . . . . . . . . . . . . . . . . . 74 195 15.2. Potential Undesirable Guidance from Authenticated ALTO 196 Information . . . . . . . . . . . . . . . . . . . . . . . 74 197 15.2.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 75 198 15.2.2. Protection Strategies . . . . . . . . . . . . . . . . 75 199 15.3. Confidentiality of ALTO Information . . . . . . . . . . . 75 200 15.3.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 75 201 15.3.2. Protection Strategies . . . . . . . . . . . . . . . . 76 202 15.3.3. Limitations . . . . . . . . . . . . . . . . . . . . . 77 203 15.4. Privacy for ALTO Users . . . . . . . . . . . . . . . . . . 77 204 15.4.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 77 205 15.4.2. Protection Strategies . . . . . . . . . . . . . . . . 77 206 15.5. Availability of ALTO Service . . . . . . . . . . . . . . . 77 207 15.5.1. Risk Scenarios . . . . . . . . . . . . . . . . . . . . 77 208 15.5.2. Protection Strategies . . . . . . . . . . . . . . . . 78 209 16. Manageability Considerations . . . . . . . . . . . . . . . . . 78 210 16.1. Operations . . . . . . . . . . . . . . . . . . . . . . . . 78 211 16.1.1. Installation and Initial Setup . . . . . . . . . . . . 78 212 16.1.2. Migration Path . . . . . . . . . . . . . . . . . . . . 79 213 16.1.3. Dependencies on Other Protocols and Functional 214 Components . . . . . . . . . . . . . . . . . . . . . . 79 215 16.1.4. Impact and Observation on Network Operation . . . . . 79 216 16.2. Management . . . . . . . . . . . . . . . . . . . . . . . . 80 217 16.2.1. Management Interoperability . . . . . . . . . . . . . 80 218 16.2.2. Management Information . . . . . . . . . . . . . . . . 80 219 16.2.3. Fault Management . . . . . . . . . . . . . . . . . . . 80 220 16.2.4. Configuration Management . . . . . . . . . . . . . . . 80 221 16.2.5. Performance Management . . . . . . . . . . . . . . . . 81 222 16.2.6. Security Management . . . . . . . . . . . . . . . . . 81 223 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 82 224 17.1. Normative References . . . . . . . . . . . . . . . . . . . 82 225 17.2. Informative References . . . . . . . . . . . . . . . . . . 83 226 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 85 227 Appendix B. Design History and Merged Proposals . . . . . . . . . 86 228 Appendix C. Specifying the "value" Key for 229 E_INVALID_FIELD_VALUE . . . . . . . . . . . . . . . . 86 230 Appendix D. Authors . . . . . . . . . . . . . . . . . . . . . . . 87 231 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 88 233 1. Introduction 235 1.1. Problem Statement 237 This document defines the ALTO Protocol, which provides a solution 238 for the problem stated in [RFC5693]. Specifically, in today's 239 networks, network information such as network topologies, link 240 availability, routing policies, and path costs are hidden from the 241 application layer, and many applications benefited from such hiding 242 of network complexity. However, new applications, such as 243 application-layer overlays, can benefit from information about the 244 underlying network infrastructure. In particular, these modern 245 network applications can be adaptive, and hence become more network- 246 efficient (e.g., reduce network resource consumption) and achieve 247 better application performance (e.g., accelerated download rate), by 248 leveraging network-provided information. 250 At a high level, the ALTO Protocol specified in this document is a 251 unidirectional interface that allows a network to publish its network 252 information such as network locations, costs between them at 253 configurable granularities, and endhost properties to network 254 applications. The information published by the ALTO Protocol should 255 benefit both the network and the applications (i.e., the consumers of 256 the information). Either the operator of the network or a third- 257 party (e.g., an information aggregator) can retrieve or derive 258 related information of the network and publish it using the ALTO 259 Protocol. When a network provides information through the ALTO 260 Protocol, we say that the network provides the ALTO Service. 262 To better understand the goal of the ALTO Protocol, we provide a 263 short, non-normative overview of the benefits of ALTO to both 264 networks and applications: 266 o A network that provides an ALTO Service can achieve better 267 utilization of its networking infrastructure. For example, by 268 using ALTO as a tool to interact with applications, a network is 269 able to provide network information to applications so that the 270 applications can better manage traffic on more expensive or 271 difficult-to-provision links such as long distance, transit or 272 backup links. During the interaction, the network can choose to 273 protect its sensitive and confidential network state information, 274 by abstracting real metric values into non-real numerical scores 275 or ordinal ranking. 277 o An application that uses an ALTO Service can benefit from better 278 knowledge of the network to avoid network bottlenecks. For 279 example, an overlay application can use information provided by 280 the ALTO Service to avoid selecting peers connected via high-delay 281 links (e.g., some intercontinental links). Using ALTO to 282 initialize each node with promising ("better-than-random") peers, 283 an adaptive peer-to-peer overlay may achieve faster, better 284 convergence. 286 1.2. Design Overview 288 The ALTO Protocol specified in this document meets the ALTO 289 requirements specified in [RFC5693], and unifies multiple protocols 290 previously designed with similar intentions. See Appendix A for a 291 list of people and Appendix B for a list of proposals that have made 292 significant contributions to this effort. 294 The ALTO Protocol uses a REST-ful design [Fielding-Thesis], and 295 encodes its requests and responses using JSON [RFC4627]. These 296 designs are chosen because of their flexibility and extensibility. 297 In addition, these designs make it possible for ALTO to be deployed 298 at scale by leveraging existing HTTP [RFC2616] implementations, 299 infrastructures and deployment experience. 301 2. Terminology 303 We use the following terms defined in [RFC5693]: Application, Overlay 304 Network, Peer, Resource, Resource Identifier, Resource Provider, 305 Resource Consumer, Resource Directory, Transport Address, Host 306 Location Attribute, ALTO Service, ALTO Server, ALTO Client, ALTO 307 Query, ALTO Reply, ALTO Transaction, Local Traffic, Peering Traffic, 308 Transit Traffic. 310 We also use the following additional terms: Endpoint Address, Network 311 Location, ALTO Information, ALTO Information Base, 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 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, overlay ID, and phone number. An Endpoint Address can be 326 network-attachment based (e.g., IP address) or network-attachment 327 agnostic (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 We use the term ALTO Information Base to refer to the internal 346 representation of ALTO Information maintained by an ALTO Server. 347 Note that the structure of this internal representation is not 348 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 We now define the ALTO architecture and the ALTO Protocol's place in 358 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. Hence, 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, we say that it provides a 379 "single-node" abstract topology. Extensions to this document may 380 provide topology details in "my-Internet view". 382 To better understand the ALTO Service and the role of the ALTO 383 Protocol, we show in Figure 1 the overall ALTO system architecture. 384 In this architecture, an ALTO Server prepares ALTO Information; an 385 ALTO Client uses ALTO Service Discovery to identify an appropriate 386 ALTO Server; and the ALTO Client requests available ALTO Information 387 from the ALTO Server using the ALTO Protocol. 389 The ALTO Information provided by the ALTO Server can be updated 390 dynamically based on network conditions, or can be seen as a policy 391 which is updated at a larger time-scale. 393 +-------------------------------------------------------------------+ 394 | Network Region | 395 | | 396 | +-----------+ | 397 | | Routing | | 398 | +--------------+ | Protocols | | 399 | | Provisioning | +-----------+ | 400 | | Policy | | | 401 | +--------------+\ | | 402 | \ | | 403 | \ | | 404 | +-----------+ \+---------+ +--------+ | 405 | |Dynamic | | ALTO | ALTO Protocol | ALTO | | 406 | |Network |.......| Server | ==================== | Client | | 407 | |Information| +---------+ +--------+ | 408 | +-----------+ / / | 409 | / ALTO SD Query/Response / | 410 | / / | 411 | +----------+ +----------------+ | 412 | | External | | ALTO Service | | 413 | | Interface| | Discovery (SD) | | 414 | +----------+ +----------------+ | 415 | | | 416 +-------------------------------------------------------------------+ 417 | 418 +------------------+ 419 | Third Parties | 420 | | 421 | Content Providers| 422 +------------------+ 424 Figure 1: Basic ALTO Architecture. 426 Figure 1 illustrates that the ALTO Information provided by an ALTO 427 Server may be influenced (at the service provider's discretion) by 428 other systems. In particular, the ALTO Server can aggregate 429 information from multiple systems to provide an abstract and unified 430 view that can be more useful to applications. Examples of other 431 systems include (but are not limited to) static network configuration 432 databases, dynamic network information, routing protocols, 433 provisioning policies, and interfaces to outside parties. These 434 components are shown in the figure for completeness but are outside 435 the scope of this specification. Recall that while the ALTO Protocol 436 may convey dynamic network information, it is not intended to replace 437 near-real-time congestion control protocols. 439 It may also be possible for an ALTO Server to exchange network 440 information with other ALTO Servers (either within the same 441 administrative domain or another administrative domain with the 442 consent of both parties) in order to adjust exported ALTO 443 Information. Such a protocol is also outside the scope of this 444 specification. 446 3.2. ALTO Information Reuse and Redistribution 448 ALTO Information may be useful to a large number of applications and 449 users. At the same time, distributing ALTO Information must be 450 efficient and not become a bottleneck. 452 The design of the ALTO Protocol allows integration with the existing 453 HTTP caching infrastructure to redistribute ALTO Information. If 454 caching or redistribution is used, the response message to an ALTO 455 Client may be returned from a third-party. 457 Application-dependent mechanisms, such as P2P DHTs or P2P file- 458 sharing, may be used to cache and redistribute ALTO Information. 459 This document does not define particular mechanisms for such 460 redistribution. 462 Additional protocol mechanisms (e.g., expiration times and digital 463 signatures for returned ALTO information) are left for future 464 investigation. 466 4. ALTO Information Service Framework 468 The ALTO Protocol conveys network information through services, where 469 each service defines a set of related functionalities. An ALTO 470 Client can request each service individually. All of the services 471 defined in ALTO are said to form the ALTO service framework and are 472 provided through a common transport protocol, messaging structure and 473 encoding, and transaction model. Functionalities offered in 474 different services can overlap. 476 The goals of the services defined in this document are to convey (1) 477 Network Locations, which denote the locations of Endpoints at a 478 network, (2) provider-defined costs for paths between pairs of 479 Network Locations, and (3) network related properties of endhosts. 480 The aforementioned goals are achieved by defining the Map Service, 481 which provides the core ALTO information to clients, and three 482 additional services: the Map Filtering Service, Endpoint Property 483 Service, and Endpoint Cost Service. Additional services can be 484 defined in companion documents. Below we give an overview of the 485 services. Details of the services will be presented in the following 486 sections. 488 .-----------------------------------------. 489 | ALTO Information Services | 490 | .-----------. .----------. .----------. | 491 | | Map | | Endpoint | | Endpoint | | 492 | | Filtering | | Property | | Cost | | 493 | | Service | | Service | | Service | | 494 | `-----------' `----------' `----------' | 495 | .-------------------------------------. | 496 | | Map Service | | 497 | | .-------------. .--------------. | | 498 | | | Network Map | | Cost Map | | | 499 | | `-------------' `--------------' | | 500 | `-------------------------------------' | 501 `-----------------------------------------' 503 Figure 2: ALTO Service Framework. 505 4.1. ALTO Information Services 507 4.1.1. Map Service 509 The Map Service provides batch information to ALTO Clients in the 510 form of Network Map and Cost Map. A Network Map (See Section 5) 511 provides a full set of Network Location groupings defined by the ALTO 512 Server and the Endpoints contained within each grouping. A Cost Map 513 (see Section 6) provides costs between a defined groupings. 515 These two maps can be thought of (and implemented as) as simple files 516 with appropriate encoding provided by the ALTO Server. 518 4.1.2. Map Filtering Service 520 Resource constrained ALTO Clients may benefit from filtering of query 521 results at the ALTO Server. This avoids that an ALTO Client first 522 spends network bandwidth and CPU cycles to collect results and then 523 performs client-side filtering. The Map Filtering Service allows 524 ALTO Clients to query an ALTO Server on Network Map and Cost Map 525 based on additional parameters. 527 4.1.3. Endpoint Property Service 529 This service allows ALTO Clients to look up properties for individual 530 Endpoints. An example property of an Endpoint is its Network 531 Location (i.e., its grouping defined by the ALTO Server). Another 532 example property is its connectivity type such as ADSL (Asymmetric 533 Digital Subscriber Line), Cable, or FTTH (Fiber To The Home). 535 4.1.4. Endpoint Cost Service 537 Some ALTO Clients may also benefit from querying for costs and 538 rankings based on Endpoints. The Endpoint Cost Service allows an 539 ALTO Server to return either numerical costs or ordinal costs 540 (rankings) directly amongst Endpoints. 542 5. Network Map 544 An ALTO Network Map defines a grouping of network endpoints. In this 545 document, we use Network Map to refer to the syntax and semantics of 546 how an ALTO Server distributes the grouping. This document does not 547 discuss the internal representation of this data structure within the 548 ALTO Server. 550 The definition of Network Map is based on the observation that in 551 reality, many endpoints are close by to one another in terms of 552 network connectivity. By treating a group of close-by endpoints 553 together as a single entity, an ALTO Server indicates aggregation of 554 these endpoints due to their proximity. This aggregation can also 555 lead to greater scalability without losing critical information when 556 conveying other network information (e.g., when defining Cost Map). 558 5.1. Provider-defined Identifier (PID) 560 One issue is that proximity varies depending on the granularity of 561 the ALTO information configured by the provider. In one deployment, 562 endpoints on the same subnet may be considered close; while in 563 another deployment, endpoints connected to the same Point of Presence 564 (PoP) may be considered close. 566 ALTO introduces provider-defined Network Location identifiers called 567 Provider-defined Identifiers (PIDs) to provide an indirect and 568 network-agnostic way to specify an aggregation of network endpoints 569 that may be treated similarly, based on network topology, type, or 570 other properties. Specifically, a PID is a US-ASCII string of type 571 PIDName (see Section 10.1) and its associated set of Endpoint 572 Addresses. As we discussed above, there can be many different ways 573 of grouping the endpoints and assigning PIDs. For example, a PID may 574 denote a subnet, a set of subnets, a metropolitan area, a PoP, an 575 autonomous system, or a set of autonomous systems. Interpreting the 576 PIDs defined in a Network Map using the "single-node" abstraction, 577 one can consider that each PID represents an abstract port (PoP) that 578 connects a set of endpoints. 580 A key use case of PIDs is to specify network preferences (costs) 581 between PIDs instead of individual endpoints. This allows cost 582 information to be more compactly represented and updated at a faster 583 time scale than the network aggregations themselves. For example, an 584 ISP may prefer that endpoints associated with the same PoP (Point-of- 585 Presence) in a P2P application communicate locally instead of 586 communicating with endpoints in other PoPs. The ISP may aggregate 587 endhosts within a PoP into a single PID in the Network Map. The cost 588 may be encoded to indicate that Network Locations within the same PID 589 are preferred; for example, cost(PID_i, PID_i) == c and cost(PID_i, 590 PID_j) > c for i != j. Section 6 provides further details on using 591 PIDs to represent costs in an ALTO Cost Map. 593 5.2. Endpoint Addresses 595 The endpoints aggregated into a PID are denoted by endpoint 596 addresses. There are many types of addresses, such as IP addresses, 597 MAC addresses, or overlay IDs. This document specifies in Section 598 10.4 how to specify IPv4/IPv6 addresses or prefixes. Extension 599 documents may define further address types; Section 14.4 of this 600 document provides an IANA registry for endpoint address types. 602 5.3. Example Network Map 604 We use the Network Map shown in Figure 3 in most examples of this 605 document. 607 .------------------------------------------------------------. 608 | An ALTO Network Map | 609 | | 610 | .-----------------------------------. .----------------. | 611 | | NetLoc: PID-1 | | NetLoc: PID-3 | | 612 | | .------------------------------. | | | | 613 | | | 192.0.2.0/24 | | | .-----------. | | 614 | | | .--------------------------. | | | | 0.0.0.0/0 | | | 615 | | | | Endpoint: 192.0.2.34 | | | | `-----------` | | 616 | | | `--------------------------` | | | | | 617 | | `------------------------------` | | | | 618 | | .------------------------------. | | | | 619 | | | 198.51.100.0/25 | | | | | 620 | | | .--------------------------. | | | | | 621 | | | | Endpoint: 198.51.100.100 | | | | | | 622 | | | `--------------------------` | | | | | 623 | | `------------------------------` | | | | 624 | `-----------------------------------` | | | 625 | | | | 626 | .-----------------------------------. | | | 627 | | NetLoc: PID-2 | | | | 628 | | .------------------------------. | | | | 629 | | | 198.51.100.128/25 | | | | | 630 | | `------------------------------` | | | | 631 | `-----------------------------------` `----------------` | 632 `------------------------------------------------------------` 634 Figure 3: Example Network Map. 636 6. Cost Map 638 An ALTO Server indicates preferences amongst network locations in the 639 form of Path Costs. Path Costs are generic costs and can be 640 internally computed by a network provider according to its own 641 policy. 643 For a given Network Map, an ALTO Cost Map defines Path Costs pairwise 644 amongst sets of source and destination Network Locations defined by 645 PIDs defined in the Network Map. Each Path Cost is the end-to-end 646 cost when a unit of traffic goes from the source to the destination. 648 Since cost is directional from the source to the destination, an 649 application, when using ALTO Information, may independently determine 650 how the Resource Consumer and Resource Provider are designated as the 651 source or destination in an ALTO query, and hence how to utilize the 652 Path Cost provided by ALTO Information. For example, if the cost is 653 expected to be correlated with throughput, a typical application 654 concerned with bulk data retrieval may use the Resource Provider as 655 the source, and Resource Consumer as the destination. 657 One advantage of separating ALTO information into a Network Map and a 658 Cost Map is that the two components can be updated at different time 659 scales. For example, Network Maps may be stable for a longer time 660 while Cost Maps may be updated to reflect dynamic network conditions. 662 As used in this document, a Cost Map refers to the syntax and 663 semantics of the information distributed by the ALTO Server. This 664 document does not discuss the internal representation of this data 665 structure within the ALTO Server. 667 6.1. Cost Types 669 Path Costs have attributes: 671 o Metric: identifies what the costs represent; 673 o Mode: identifies how the costs should be interpreted. 675 The combination of a metric and a mode defines a Cost Type. Certain 676 queries for Cost Maps allow the ALTO Client to indicate the desired 677 Cost Type. For a given ALTO Server, the combination of Cost Type and 678 Network Map defines a key. In other words, an ALTO Server MUST NOT 679 define two Cost Maps with the same Cost Type, Network Map pair. 681 6.1.1. Cost Metric 683 The Metric attribute indicates what the cost represents. For 684 example, an ALTO Server could define costs representing air-miles, 685 hop-counts, or generic routing costs. 687 Cost metrics are indicated in protocol messages as strings. 689 6.1.1.1. Cost Metric: routingcost 691 An ALTO Server MUST offer the 'routingcost' Cost Metric. 693 This Cost Metric conveys a generic measure for the cost of routing 694 traffic from a source to a destination. A lower value indicates a 695 higher preference for traffic to be sent from a source to a 696 destination. 698 Note that an ISP may internally compute routing cost using any method 699 that it chooses (e.g., air-miles or hop-count) as long as it conforms 700 to these semantics. 702 6.1.2. Cost Mode 704 The Mode attribute indicates how costs should be interpreted. 705 Specifically, the Mode attribute indicates whether returned costs 706 should be interpreted as numerical values or ordinal rankings. 708 It is important to communicate such information to ALTO Clients, as 709 certain operations may not be valid on certain costs returned by an 710 ALTO Server. For example, it is possible for an ALTO Server to 711 return a set of IP addresses with costs indicating a ranking of the 712 IP addresses. Arithmetic operations that would make sense for 713 numerical values, do not make sense for ordinal rankings. ALTO 714 Clients may handle such costs differently. 716 Cost Modes are indicated in protocol messages as strings. 718 An ALTO Server MUST support at least one of 'numerical' and 'ordinal' 719 modes. An ALTO Client SHOULD be cognizant of operations when a 720 desired Cost Mode is not supported. For example, an ALTO Client 721 desiring numerical costs may adjust its behaviors if only the ordinal 722 Cost Mode is available. Alternatively, an ALTO Client desiring 723 ordinal costs may construct ordinal costs from retrieved numerical 724 values, if only the numerical Cost Mode is available. 726 6.1.2.1. Cost Mode: numerical 728 This Cost Mode is indicated by the string 'numerical'. This mode 729 indicates that it is safe to perform numerical operations (e.g. 730 normalization or computing ratios for weighted load-balancing) on the 731 returned costs. The values are floating-point numbers. 733 6.1.2.2. Cost Mode: ordinal 735 This Cost Mode is indicated by the string 'ordinal'. This mode 736 indicates that the costs values in a Cost Map are a ranking (relative 737 to all other values in a Cost Map), with a lower value indicating a 738 higher preference. The values are non-negative integers. Ordinal 739 cost values in a Cost Map need not be unique nor contiguous. In 740 particular, it is possible that two entries in a map have an 741 identical rank (ordinal cost value). This document does not specify 742 any behavior by an ALTO Client in this case; an ALTO Client may 743 decide to break ties by random selection, other application 744 knowledge, or some other means. 746 It is important to note that the values in the Cost Map provided with 747 the ordinal Cost Mode are not necessarily the actual costs known to 748 the ALTO Server. 750 6.2. Cost Map Structure 752 A request for a Cost Map either explicitly or implicitly includes a 753 list of Source Network Locations and a list of Destination Network 754 Locations. (Recall that a Network Location can be an endpoint 755 address or a PID.) 757 Specifically, assume that a request specifies a list of multiple 758 Source Network Locations, say [Src_1, Src_2, ..., Src_m], and a list 759 of multiple Destination Network Locations, say [Dst_1, Dst_2, ..., 760 Dst_n]. 762 The ALTO Server will return the Path Cost for each of the m*n 763 communicating pairs (i.e., Src_1 -> Dst_1, ..., Src_1 -> Dst_n, ..., 764 Src_m -> Dst_1, ..., Src_m -> Dst_n). If the ALTO Server does not 765 define a Path Cost for a particular pair, it may be omitted. We 766 refer to this structure as a Cost Map. 768 If the Cost Mode is 'ordinal', the Path Cost of each communicating 769 pair is relative to the m*n entries. 771 6.3. Network Map and Cost Map Dependency 773 A Cost Map gives Path Costs between the PIDs defined in a Network 774 Map. An ALTO Server may modify a Network Map at any time, say by 775 adding or deleting PIDs, or even redefining them. Hence to 776 effectively use an instance of a Cost Map, an ALTO Client must know 777 which version of the Network Map defined the PIDs in that Cost Map. 778 Version Tags allow ALTO Clients to correlate Cost Map instances with 779 the corresponding versions of the Network Map. 781 A Version Tag is a tuple of (1) an ID for the resource (e.g., a 782 Network Map), and (2) a tag (an opaque string) associated with the 783 version of that resource. A Network Map distributed by an ALTO 784 Server includes its Version Tag. A Cost Map referring to PIDs also 785 includes Version Tag for the Network Map on which it is based. 787 Two Network Maps are the same if they have the same Version Tag. 788 Whenever the content of the Network Map maintained by an ALTO Server 789 changes, tag MUST also be changed. Possibilities of setting the tag 790 component include the last-modified timestamp for the Network Map, or 791 a hash of its contents, where the collision probability is considered 792 zero in practical deployment scenarios. 794 6.4. Cost Map Update 796 An ALTO Server can update a Cost Map at any time. Hence, the same 797 Cost Map retrieved from the same ALTO Server but from different 798 requests can be inconsistent. 800 7. Endpoint Properties 802 An endpoint property defines a network-aware property of an endpoint. 804 7.1. Endpoint Property Type 806 For each endpoint and an endpoint property type, there can be a value 807 for the property. The type of an Endpoint property is indicated in 808 protocol messages as a string. The value depends on the specific 809 property. For example, for a property such as whether an endpoint is 810 metered, the value is a true or false value. 812 7.1.1. Endpoint Property Type: pid 814 An ALTO Server MUST define the 'pid' Endpoint Property Type for each 815 Network Map that it provides. 817 8. Protocol Specification: General Processing 819 This section first specifies general client and server processing. 820 The details of specific services will be covered in the following 821 sections. 823 8.1. Overall Design 825 The ALTO Protocol uses a REST-ful design. There are two primary 826 components to this design: 828 o Information Resources: An ALTO Server provides a set of network 829 information resources. Each information resource has a media type 830 [RFC2046]. An ALTO Client may construct an HTTP request for a 831 particular information resource (including any parameters, if 832 necessary), and the ALTO Server returns the requested information 833 resource in an HTTP response. 835 o Information Resource Directory (IRD): An ALTO Server provides to 836 ALTO Clients a list of available information resources and the URI 837 at which each is provided. This document refers to this list as 838 the Information Resource Directory. ALTO Clients consult the 839 directory to determine the services provided by an ALTO Server. 841 8.2. Notation 843 This document uses 'JSONString', 'JSONNumber', 'JSONBool' to indicate 844 the JSON string, number, and boolean types, respectively. The type 845 'JSONValue' indicates a JSON value, as specified in Section 2.1 of 846 [RFC4627]. 848 We use an adaptation of the C-style struct notation to define the 849 fields (names/values) of JSON objects. An optional field is enclosed 850 by [ ], and an array is indicated by two numbers in angle brackets, 851 , where m indicates the minimal number of values, and n is the 852 maximum. When we write * for n, it means no upper bound. In the 853 definitions, the JSON names of the fields are case sensitive. 855 For example, the definition below defines a new type Type4, with 856 three field members (or fields for short) named "name1", "name2", and 857 "name3" respectively. The field named "name3" is optional, and the 858 field named "name2" is an array of at least one value. 859 object { Type1 name1; Type2 name2<1..*>; [Type3 name3;] 860 } Type4; 862 We also define dictionary maps (or maps for short) from strings to 863 JSON values. For example, the definition below defines a Type3 864 object as a map. Type1 must be defined as string, and Type2 can be 865 defined as any type. 866 object-map { Type1 -> Type2; } Type3; 868 We use subtyping to denote that one type is derived from another 869 type. The example below denotes that TypeDerived is derived from 870 TypeBase. TypeDerived includes all fields defined in TypeBase. If 871 TypeBase does not have a field named "name1", TypeDerived will have a 872 new field named "name1". If TypeBase already has a field named 873 "name1" but with a different type, TypeDerived will have a field 874 named "name1" with the type defined in TypeDerived (i.e., Type1 in 875 the example). 876 object { Type1 name1; } TypeDerived : TypeBase; 878 Note that despite the notation, no standard, machine-readable 879 interface definition or schema is provided in this document. 880 Extension documents may document these as necessary. 882 8.3. Basic Operations 884 The ALTO Protocol employs standard HTTP [RFC2616]. It is used for 885 discovering available Information Resources at an ALTO Server and 886 retrieving Information Resources. ALTO Clients and ALTO Servers use 887 HTTP requests and responses carrying ALTO-specific content with 888 encoding as specified in this document, and MUST be compliant with 890 [RFC2616]. 892 Instead of specifying the generic application/json Media Type for all 893 ALTO request parameters (if any) and responses, ALTO Clients and 894 Servers use multiple, specific JSON-based Media Types (e.g., 895 application/alto-networkmap+json, application/alto-costmap+json) to 896 indicate content types; see Table 2 for a list of Media Types defined 897 in this document. This allows easy extensibility while maintaining 898 clear semantics and versioning. For example, a new version of a 899 component of the ALTO Protocol (e.g., a new version of the Network 900 Map) can be defined by simply introducing a new Media Type (e.g., 901 application/alto-networkmap-v2+json). 903 8.3.1. Client Discovering Information Resources 905 To discover available Information Resources, an ALTO Client requests 906 Information Resource Directories. Informally, an Information 907 Resource Directory enumerates URIs at which an ALTO Server offers 908 Information Resources. 910 Specifically, using the ALTO Discovery protocol, an ALTO Client 911 obtains a URI through which it can request an Information Resource 912 Directory (IRD). We refer to this IRD as the Root IRD of the ALTO 913 Client. Each entry in an IRD indicates a URI at which an ALTO Server 914 accepts requests, and returns either an Information Resource or an 915 Information Resource Directory that references additional Information 916 Resources. Beginning with its Root IRD and following links to IRDs 917 recursively, an ALTO Client can discover all Information Resources 918 available to it. We refer to this set of Information Resources as 919 the Information Resource Closure of the ALTO Client. By inspecting 920 its Information Resource Closure, an ALTO Client can determine 921 whether an ALTO Server supports the desired Information Resource, and 922 if it is supported, the URI at which it is available. 924 See Section 9.2 for a detailed specification on IRDs. 926 8.3.2. Client Requesting Information Resources 928 Where possible, the ALTO Protocol uses the HTTP GET method to request 929 resources. However, some ALTO services provide Information Resources 930 that are the function of one or more input parameters. Input 931 parameters are encoded in the HTTP request's entity body, and the 932 ALTO Client MUST use the HTTP POST method to send the parameters. 934 When requesting an ALTO Information Resource that requires input 935 parameters specified in a HTTP POST request, an ALTO Client MUST set 936 the Content-Type HTTP header to the media type corresponding to the 937 format of the supplied input parameters. 939 8.3.3. Server Responding to IR Request 941 Upon receiving a request for an Information Resource that the ALTO 942 Server can provide, the ALTO Server MUST return the requested 943 Information Resource. In other cases, to be more informative 944 ([I-D.ietf-httpbis-p2-semantics]), the ALTO Server MAY provide the 945 ALTO Client with an Information Resource Directory indicating how to 946 reach the desired information resource, or return an ALTO error 947 object; see Section 8.5 for more details on ALTO error handling. 949 It is possible for an ALTO Server to leverage caching HTTP 950 intermediaries to respond to both GET and POST requests by including 951 explicit freshness information (see Section 14 of [RFC2616]). 952 Caching of POST requests is not widely implemented by HTTP 953 intermediaries, however an alternative approach is for an ALTO 954 Server, in response to POST requests, to return an HTTP 303 status 955 code ("See Other") indicating to the ALTO Client that the resulting 956 Information Resource is available via a GET request to an alternate 957 URL. HTTP intermediaries that do not support caching of POST 958 requests could then cache the response to the GET request from the 959 ALTO Client following the alternate URL in the 303 response if the 960 response to the subsequent GET request contains explicit freshness 961 information. 963 The ALTO Server MUST indicate the type of its response using a media 964 type (i.e., the Content-Type HTTP header of the response). 966 8.3.4. Client Handling Server Response 968 8.3.4.1. Using Information Resources 970 This specification does not indicate any required actions taken by 971 ALTO Clients upon successfully receiving an Information Resource from 972 an ALTO Server. Although ALTO Clients are suggested to interpret the 973 received ALTO Information and adapt application behavior, ALTO 974 Clients are not required to do so. 976 8.3.4.2. Handling Server Response and IRD 978 After receiving an Information Resource Directory, the Client can 979 consult it to determine if any of the offered URIs contain the 980 desired Information Resource. However, an ALTO Client MUST NOT 981 assume that the media type returned by the ALTO Server for a request 982 to a URI is the media type advertised in the IRD or specified in its 983 request (i.e., the client must still check the Content-Type header). 984 The expectation is that the media type returned should normally be 985 the media type advertised and requested, but in some cases it may 986 legitimately not be so. 988 In particular, it is possible for an ALTO Client to receive an 989 Information Resource Directory from an ALTO Server as a response to 990 its request for a specific Information Resource. In this case, the 991 ALTO Client may ignore the response or still parse the response. To 992 indicate that an ALTO Client will always check if a response is an 993 Information Resource Directory, the ALTO Client can indicate in the 994 "Accept" header of a HTTP request that it can accept Information 995 Resource Directory; see Section 9.2 for the media type. 997 8.3.4.3. Handling Error Conditions 999 If an ALTO Client does not successfully receive a desired Information 1000 Resource from a particular ALTO Server (i.e., server response 1001 indicates error or there is no response), the Client can either 1002 choose another server (if one is available) or fall back to a default 1003 behavior (e.g., perform peer selection without the use of ALTO 1004 information, when used in a peer-to-peer system). 1006 8.3.5. Authentication and Encryption 1008 When server and/or client authentication, encryption, and/or 1009 integrity protection are required, an ALTO Server MUST support SSL/ 1010 TLS [RFC5246] as a mechanism. For cases such as a public ALTO 1011 service or deployment scenarios where there is an implicit trust 1012 relationship between the client and the server and the network 1013 infrastructure connecting them is secure, SSL/TLS may not be 1014 necessary. See [RFC6125] for considerations regarding verification 1015 of server identity. 1017 8.3.6. Information Refreshing 1019 An ALTO Client MAY determine the frequency at which ALTO Information 1020 is refreshed based on information made available via HTTP. 1022 8.3.7. HTTP Cookies 1024 If cookies are included in an HTTP request received by an ALTO 1025 Server, they MUST be ignored. 1027 8.3.8. Parsing of Unknown Fields 1029 This document only details object fields used by this specification. 1030 Extensions may include additional fields within JSON objects defined 1031 in this document. ALTO implementations MUST ignore unknown fields 1032 when processing ALTO messages. 1034 8.4. Server Response Encoding 1036 Though each type of ALTO Server response (i.e., an Information 1037 Resource Directory, an individual Information Resource, or an error 1038 message) has its distinct syntax and hence its unique Media Type, 1039 they are designed to have a similar structure: a meta field providing 1040 meta definitions, and another field containing the data, if needed. 1042 Specifically, we define the base type of each ALTO Server response as 1043 ResponseEntityBase: 1044 object { ResponseMeta meta; } ResponseEntityBase; 1046 with field: 1048 meta meta information pertaining to the response. 1050 8.4.1. Meta Information 1052 Meta information is encoded as a map object for flexibility. 1053 Specifically, ResponseMeta is defined as: 1054 object-map { JSONString -> JSONValue } ResponseMeta; 1056 8.4.2. Data Information 1058 The data component of the response encodes the response-specific 1059 data. In this document, we derive five types from ResponseEntityBase 1060 to add different types of data component: InforResourceDirectory 1061 (Section 9.2.2), InfoResourceNetworkMap (Section 11.2.1.6), 1062 InfoResourceCostMap (Section 11.2.3.6), 1063 InfoResourceEndpointProperties (Section 11.4.1.6), and 1064 InfoResourceEndpointCostMap (Section 11.5.1.6). 1066 8.5. Protocol Errors 1068 If there is an error processing a request, an ALTO Server SHOULD 1069 return additional ALTO-layer information, if it is available, in the 1070 form of an ALTO Error Resource encoded in the HTTP response' entity 1071 body. If no ALTO-layer information is available, an ALTO Server may 1072 omit an ALTO Error resource from the response. 1074 With or without additional ALTO-layer error information, an ALTO 1075 Server MUST set an appropriate HTTP status code. It is important to 1076 note that the HTTP Status Code and ALTO Error Resource have distinct 1077 roles. An ALTO Error Resource provides detailed information about 1078 why a particular request for an ALTO Resource was not successful. 1079 The HTTP status code indicates to HTTP processing elements (e.g., 1080 intermediaries and clients) how the response should be treated. 1082 8.5.1. Media Type 1084 The media type for an ALTO Error Response is "application/ 1085 alto-error+json". 1087 8.5.2. Response Format and Error Codes 1089 An ALTO Error Response MUST include the "code" key in the "meta" 1090 field of the response. The value of "code" MUST be an ALTO Error 1091 Code, encoded in US ASCII, defined in Table 1. Note that the ALTO 1092 Error Codes defined in Table 1 are limited to support the error 1093 conditions needed for purposes of this document. Additional status 1094 codes may be defined in companion or extension documents. 1096 +-----------------------+-------------------------------------------+ 1097 | ALTO Error Code | Description | 1098 +-----------------------+-------------------------------------------+ 1099 | E_SYNTAX | Parsing error in request (including | 1100 | | identifiers) | 1101 | E_MISSING_FIELD | A required JSON field is missing | 1102 | E_INVALID_FIELD_TYPE | The type of the value of a JSON field is | 1103 | | invalid | 1104 | E_INVALID_FIELD_VALUE | The value of a JSON field is invalid | 1105 +-----------------------+-------------------------------------------+ 1107 Table 1: Defined ALTO Error Codes. 1109 After an ALTO Server receives a request, it needs to verify the 1110 syntactic and semantic validity of the request. The following 1111 paragraphs in this section are intended to illustrate the usage of 1112 the error codes defined above during the verification. An individual 1113 implementation may define its message processing in a different 1114 order. 1116 In the first step after an ALTO Server receives a request, it checks 1117 the syntax of the request body (i.e., whether the JSON structure can 1118 be parsed), and indicates a syntax error using the error code 1119 E_SYNTAX. For an E_SYNTAX error, the ALTO Server MAY provide an 1120 optional key "syntax-error" in the "meta" field of the error 1121 response. The objective of providing "syntax-error" is to provide 1122 technical debugging information to developers, not end users. Hence, 1123 it should be a human-readable, free-form text describing the syntax 1124 error. If possible, the text should include position information 1125 such as line number and offset within line about the syntax error. 1126 If nothing else, "syntax-error" could have just the position. If a 1127 syntax error occurs in a production environment, the ALTO Client 1128 could inform the end user that there was an error communicating with 1129 the ALTO Server, and suggest that the user submit the error 1130 information, which includes "syntax-error", to the developers. 1132 A request without syntax errors may still be invalid. An error case 1133 is that the request misses a required field. The server indicates 1134 such an error using the error code E_MISSING_FIELD. This document 1135 defines required fields for Network Map Filtering (Section 11.3.1.3), 1136 Cost Map Filtering (Section 11.3.2.3), Endpoint Properties 1137 (Section 11.4.1.3), and Endpoint Cost (Section 11.5.1.3). For an 1138 E_MISSING_FIELD error, the server may include an optional "field" key 1139 in the "meta" field of the error response, to indicate the missing 1140 field. "field" should be a JSONString indicating the full path of the 1141 missing field. For example, assume that a Filtered CostMap request 1142 (see Section 11.3.2.3) misses the "cost-metric" field in the request. 1143 The error response from the ALTO Server may specify the "field" key 1144 as "cost-type/cost-mode". 1146 A request with the correct fields might use a wrong type for the 1147 value of a field. For example, the value of a field could be a 1148 JSONString when a JSONNumber is expected. The server indicates such 1149 an error using the error code E_INVALID_FIELD_TYPE. The server may 1150 include an optional "field" key in the "meta" field of the response, 1151 to indicate the field that contains the wrong type. 1153 A request with the correct fields and types of values for the fields 1154 may specify a wrong value for a field. For example, a cost map 1155 filtering request may specify a wrong value of CostMode in the "cost- 1156 type" field (Section 11.3.2.3). The server indicates such an error 1157 with the error code E_INVALID_FIELD_VALUE. For an 1158 E_INVALID_FIELD_VALUE error, the server may include an optional 1159 "field" key in the "meta" field of the response, to indicate the 1160 field that contains the wrong value. The server may also include an 1161 optional "value" key in the "meta" field of the response to indicate 1162 the wrong value that triggered the error. 1164 A request with the correct fields and types of values for the fields 1165 may specify a wrong value for a field. For example, a filtered cost 1166 map request may specify a wrong value for CostMode in the "cost-type" 1167 field (Section 11.3.2.3). The server indicates such an error with 1168 the error code E_INVALID_FIELD_VALUE. For an E_INVALID_FIELD_VALUE 1169 error, the server may include an optional "field" key in the "meta" 1170 field of the response, to indicate the field that contains the wrong 1171 value. The server may also include an optional "value" key in the 1172 "meta" field of the response to indicate the wrong value that 1173 triggered the error. If the "value" key is specified, the "field" 1174 key MUST be specified. The "value" key MUST have a JSONString value. 1175 If the invalid value is not a string, the ALTO Server MUST convert it 1176 to a string. See Appendix C for the rules to specify the "value" 1177 key. 1179 If multiple errors are present in a single request (e.g., a request 1180 uses a JSONString when a JSONNumber is expected and a required field 1181 is missing), then the ALTO Server MUST return exactly one of the 1182 detected errors. However, the reported error is implementation 1183 defined, since specifying a particular order for message processing 1184 encroaches needlessly on implementation techniques. 1186 8.5.3. Overload Conditions and Server Unavailability 1188 If an ALTO Server detects that it cannot handle a request from an 1189 ALTO Client due to excessive load, technical problems, or system 1190 maintenance, it SHOULD do one of the following: 1192 o Return an HTTP 503 ("Service Unavailable") status code to the ALTO 1193 Client. As indicated by [RFC2616], a the Retry-After HTTP header 1194 may be used to indicate when the ALTO Client should retry the 1195 request. 1197 o Return an HTTP 307 ("Temporary Redirect") status code indicating 1198 an alternate ALTO Server that may be able to satisfy the request. 1199 Using Temporary Redirect may generate infinite redirection loops. 1200 Although [RFC2616] Section 10.3 requires that an HTTP client 1201 SHOULD detect infinite redirection loops, it is more desirable 1202 that multiple ALTO Servers are configured to not form redirection 1203 loops. 1205 The ALTO Server MAY also terminate the connection with the ALTO 1206 Client. 1208 The particular policy applied by an ALTO Server to determine that it 1209 cannot service a request is outside of the scope of this document. 1211 9. Protocol Specification: Information Resource Directory 1213 As we discussed, an ALTO Client starts by retrieving an Information 1214 Resource Directory, which specifies the attributes of individual 1215 Information Resources that an ALTO Server provides. 1217 9.1. Information Resource Attributes 1219 In this document, each Information Resource has five attributes 1220 associated with it, including its assigned ID, its response format, 1221 its capabilities, its accepted input parameters, and other resources 1222 that it may depend on. The function of an Information Resource 1223 Directory is to publishes these attributes. 1225 9.1.1. Resource ID 1227 Each Information Resource that an ALTO Client can request MUST be 1228 assigned an ID that is unique amongst all Information Resources in 1229 the Information Resource Closure of the client. The ID SHOULD remain 1230 stable even when the data provided by that resource changes. For 1231 example, even though the number of PIDs in a Network Map may be 1232 adjusted, its Resource ID should remain the same. Similarly, if the 1233 entries in a Cost Map are updated, its Resource ID should remain the 1234 same. IDs SHOULD NOT be re-used for different resources over time. 1236 9.1.2. Media Type 1238 ALTO uses Media Type [RFC2046] to uniquely indicate the data format 1239 used to encode the content to be transmitted between an ALTO Server 1240 and an ALTO Client in the HTTP entity body. 1242 9.1.3. Capabilities 1244 The Capabilities attribute of an Information Resource indicates 1245 specific capabilities that the server can provide. For example, if 1246 an ALTO Server allows an ALTO Client to specify cost constraints when 1247 the Client requests a Cost Map Information Resource, then the Server 1248 advertises the cost-constraints capability of the Cost Map 1249 Information Resource. 1251 9.1.4. Accepts Input Parameters 1253 An ALTO Server may allow an ALTO Client to supply input parameters 1254 when requesting certain Information Resources. The associated 1255 accepts attribute of an Information Resource is a Media Type, which 1256 indicates how the Client specifies the input parameters as contained 1257 in the entity body of the HTTP POST request. 1259 9.1.5. Dependent Resources 1261 The information provided in an Information Resource may use 1262 information provided in some other resources (e.g., a Cost Map uses 1263 the PIDs defined in a Network Map). The uses attribute conveys such 1264 information. 1266 9.2. Information Resource Directory (IRD) 1268 An ALTO Server uses Information Resource Directory to publish 1269 available Information Resources and their aforementioned attributes. 1270 Since resource selection happens after consumption of the Information 1271 Resource Directory, the format of the Information Resource Directory 1272 is designed to be simple with the intention of future ALTO Protocol 1273 versions maintaining backwards compatibility. Future extensions or 1274 versions of the ALTO Protocol SHOULD be accomplished by extending 1275 existing media types or adding new media types, but retaining the 1276 same format for the Information Resource Directory. 1278 An ALTO Server MUST make an Information Resource Directory available 1279 via the HTTP GET method to a URI discoverable by an ALTO Client. 1280 Discovery of this URI is out of scope of this document, but could be 1281 accomplished by manual configuration or by returning the URI of an 1282 Information Resource Directory from the ALTO Discovery Protocol 1283 [I-D.ietf-alto-server-discovery]. For recommendations on how the URI 1284 may look like, see [I-D.ietf-alto-server-discovery]. 1286 9.2.1. Media Type 1288 The media type to indicate an information directory is "application/ 1289 alto-directory+json". 1291 9.2.2. Encoding 1293 An Information Resource Directory response may include in "meta" the 1294 "cost-types" key, whose value is of type IRDMetaCostTypes defined 1295 below, where CostType is defined in Section 10.7: 1297 object-map { 1298 JSONString -> CostType; 1299 } IRDMetaCostTypes; 1301 The function of "cost-types" is to assign names to a set of CostTypes 1302 that can be used in one or more "resources" entries in the IRD to 1303 simplify specification. The names defined in "cost-types" in an IRD 1304 are local to the IRD. 1306 For a Root IRD, "meta" MUST include the "default-alto-network-map" 1307 key, which specifies the Resource ID of a Network Map. When there are 1308 multiple Network Maps defined in an IRD (e.g., with different levels 1309 of granularity), the "default-alto-network-map" key provides a 1310 guideline to simple clients that use only one Network Map. 1312 The data component of an Information Resource Directory response is 1313 named "resources", which is a JSON object of type IRDResourceEntries: 1315 object { 1316 IRDResourceEntries resources; 1317 } InfoResourceDirectory : ResponseEntityBase; 1319 object-map { 1320 ResourceID -> IRDResourceEntry; 1321 } IRDResourceEntries; 1323 object { 1324 JSONString uri; 1325 JSONString media-type; 1326 [JSONString accepts;] 1327 [Capabilities capabilities;] 1328 [ResourceID uses<0..*>;] 1329 } IRDResourceEntry; 1331 object { 1332 ... 1333 } Capabilities; 1335 An IRDResourceEntries object is a dictionary map keyed by 1336 ResourceIDs, where ResourceID is defined in Section 10.2. The value 1337 of each entry specifies: 1339 uri A URI at which the ALTO Server provides one or more Information 1340 Resources, or an Information Resource Directory indicating 1341 additional Information Resources. URIs can be relative to the URI 1342 of the IRD and MUST be resolved according to Section 5 of 1343 [RFC3986]. 1345 media-type The media type of Information Resource (see 1346 Section 9.1.2) available via GET or POST requests to the 1347 corresponding URI or "application/alto-directory+json", which 1348 indicates that the response for a request to the URI will be an 1349 Information Resource Directory for URIs discoverable via the URI. 1351 accepts The media type of input parameters (see Section 9.1.4) 1352 accepted by POST requests to the corresponding URI. If this field 1353 is not present, it MUST be assumed to be empty. 1355 capabilities A JSON Object enumerating capabilities of an ALTO 1356 Server in providing the Information Resource at the corresponding 1357 URI and Information Resources discoverable via the URI. If this 1358 field is not present, it MUST be assumed to be an empty object. 1360 If a capability for one of the offered Information Resources is 1361 not explicitly listed here, an ALTO Client may either issue an 1362 OPTIONS HTTP request to the corresponding URI to determine if the 1363 capability is supported, or assume its default value documented in 1364 this specification or an extension document describing the 1365 capability. 1367 uses A list of Resource IDs, defined in the same IRD, that define 1368 the resources on which this resource directly depends. An ALTO 1369 Server SHOULD include in this list any resources that the ALTO 1370 Client would need to retrieve in order to interpret the contents 1371 of this resource. For example, a Cost Map resource should include 1372 in this list the Network Map on which it depends. ALTO Clients 1373 may wish to consult this list in order to pre-fetch necessary 1374 resources. 1376 If an entry has an empty list for "accepts", then the corresponding 1377 URI MUST support GET requests. If an entry has a non-empty 1378 "accepts", then the corresponding URI MUST support POST requests. If 1379 an ALTO Server wishes to support both GET and POST on a single URI, 1380 it MUST specify two entries in the Information Resource Directory. 1382 9.2.3. Example 1384 The following is an example Information Resource Directory returned 1385 by an ALTO Server to an ALTO Client. Assume it is the Root IRD of 1386 the Client. 1388 GET /directory HTTP/1.1 1389 Host: alto.example.com 1390 Accept: application/alto-directory+json,application/alto-error+json 1392 HTTP/1.1 200 OK 1393 Content-Length: TBA 1394 Content-Type: application/alto-directory+json 1396 { 1397 "meta" : { 1398 "cost-types": { 1399 "num-routing": { 1400 "cost-mode" : "numerical", 1401 "cost-metric": "routingcost", 1402 "description": "My default" 1403 }, 1404 "num-hop": { 1405 "cost-mode" : "numerical", 1406 "cost-metric": "hopcount" 1407 }, 1408 "ord-routing": { 1409 "cost-mode" : "ordinal", 1410 "cost-metric": "routingcost" 1411 }, 1412 "ord-hop": { 1413 "cost-mode" : "ordinal", 1414 "cost-metric": "hopcount" 1415 } 1416 }, 1417 "default-alto-network-map" : "my-default-network-map" 1418 }, 1419 "resources" : { 1420 "my-default-network-map" : { 1421 "uri" : "http://alto.example.com/networkmap", 1422 "media-type" : "application/alto-networkmap+json" 1423 }, 1424 "numerical-routing-cost-map" : { 1425 "uri" : "http://alto.example.com/costmap/num/routingcost", 1426 "media-type" : "application/alto-costmap+json", 1427 "capabilities" : { 1428 "cost-type-names" : [ "num-routing" ] 1429 }, 1430 "uses": [ "my-default-network-map" ] 1431 }, 1432 "numerical-hopcount-cost-map" : { 1433 "uri" : "http://alto.example.com/costmap/num/hopcount", 1434 "media-type" : "application/alto-costmap+json", 1435 "capabilities" : { 1436 "cost-type-names" : [ "num-hop" ] 1437 }, 1438 "uses": [ "my-default-network-map" ] 1439 }, 1440 "custom-maps-resources" : { 1441 "uri" : "http://custom.alto.example.com/maps", 1442 "media-type" : "application/alto-directory+json" 1443 }, 1444 "endpoint-property" : { 1445 "uri" : "http://alto.example.com/endpointprop/lookup", 1446 "media-type" : "application/alto-endpointprop+json", 1447 "accepts" : "application/alto-endpointpropparams+json", 1448 "capabilities" : { 1449 "prop-types" : [ "my-default-network-map.pid", 1450 "priv:ietf-example-prop" ] 1451 }, 1453 }, 1454 "endpoint-cost" : { 1455 "uri" : "http://alto.example.com/endpointcost/lookup", 1456 "media-type" : "application/alto-endpointcost+json", 1457 "accepts" : "application/alto-endpointcostparams+json", 1458 "capabilities" : { 1459 "cost-constraints" : true, 1460 "cost-type-names" : [ "num-routing", "num-hop", 1461 "ord-routing", "ord-hop"] 1462 } 1463 } 1464 } 1465 } 1467 Specifically, the "cost-types" key of "meta" of the example IRD 1468 defines names for four cost types in this IRD. For example, "num- 1469 routing" in the example is the name that refers to a Cost Type with 1470 Cost Mode being "numerical" and Cost Metric being "routingcost". 1471 This name is used in the second entry of "resources", which defines a 1472 Cost Map. In particular, the "cost-type-names" of its "capabilities" 1473 specifies that this resource supports a Cost Type named as "num- 1474 routing". The ALTO Client looks up the name "num-routing" in "cost- 1475 types" of the IRD to obtain the Cost Type named as "num-routing". 1476 The last entry of "resources" uses all four names defined in "cost- 1477 types". 1479 Another key defined in "meta" of the example IRD is "default-alto- 1480 network-map", which has value "my-default-network-map", which is the 1481 Resource ID of a Network Map that will be defined in "resources". 1483 The "resources" field of the example IRD defines six Information 1484 Resources. For example, the second entry, which is assigned a 1485 Resource ID "numerical-routing-cost-map", provides a Cost Map, as 1486 indicated by the media-type "application/alto-costmap+json". The 1487 Cost Map is based on the Network Map defined with Resource ID "my- 1488 default-network-map". As another example, the last entry, which is 1489 assigned Resource ID "endpoint-cost", provides the Endpoint Cost 1490 Service, which is indicated by the media-type "application/ 1491 alto-endpointcost+json". An ALTO Client should use uri 1492 "http://alto.example.com/endpointcost/lookup" to access the service. 1493 The ALTO Client should format its request body to be the 1494 "application/alto-endpointcostparams+json" media type, as specified 1495 by the "accepts" attribute of the Information Resource. The "cost- 1496 type-names" field of the "capabilities" attribute of the Information 1497 Resource includes four defined cost types specified in the "cost- 1498 types" key of "meta" of the IRD. Hence, one can verify that the 1499 Endpoint Cost Information Resource supports both Cost Metrics 1500 'routingcost' and 'hopcount', each available for both 'numerical' and 1501 'ordinal'. When requesting the Information Resource, an ALTO Client 1502 can specify cost constraints, as indicated by the "cost-constraints" 1503 field of the "capabilities" attribute. 1505 9.2.4. Delegation using IRD 1507 ALTO Information Resource Directory provides flexibility to provide 1508 ALTO Service (e.g., delegation to another domain). Consider the 1509 preceding example. Assume that the ALTO Server running at 1510 alto.example.com wants to delegate some Information Resources to a 1511 separate subdomain: "custom.alto.example.com". In particular, assume 1512 that the maps available via this subdomain are filtered Network Maps, 1513 filtered Cost Maps, and some pre-generated maps for the "hopcount" 1514 and "routingcost" Cost Metrics in the "ordinal" Cost Mode. The 1515 fourth entry of "resources" in the preceding example IRD implements 1516 the delegation. The entry has a media-type of "application/ 1517 alto-directory+json", and an ALTO Client can discover the Information 1518 Resources available at "custom.alto.example.com" if its request to 1519 "http://custom.alto.example.com/maps" is successful: 1521 GET /maps HTTP/1.1 1522 Host: custom.alto.example.com 1523 Accept: application/alto-directory+json,application/alto-error+json 1525 HTTP/1.1 200 OK 1526 Content-Length: TBA 1527 Content-Type: application/alto-directory+json 1529 { 1530 "meta" : { 1531 "cost-types": { 1532 "num-routing": { 1533 "cost-mode" : "numerical", 1534 "cost-metric": "routingcost", 1535 "description": "My default" 1536 }, 1537 "num-hop": { 1538 "cost-mode" : "numerical", 1539 "cost-metric": "hopcount" 1540 }, 1541 "ord-routing": { 1542 "cost-mode" : "ordinal", 1543 "cost-metric": "routingcost" 1545 }, 1546 "ord-hop": { 1547 "cost-mode" : "ordinal", 1548 "cost-metric": "hopcount" 1549 } 1550 } 1551 }, 1552 "resources" : { 1553 "filtered-network-map" : { 1554 "uri" : "http://custom.alto.example.com/networkmap/filtered", 1555 "media-type" : "application/alto-networkmap+json", 1556 "accepts" : "application/alto-networkmapfilter+json", 1557 "uses": [ "my-default-network-map" ] 1558 }, 1559 "filtered-cost-map" : { 1560 "uri" : "http://custom.alto.example.com/costmap/filtered", 1561 "media-type" : "application/alto-costmap+json", 1562 "accepts" : "application/alto-costmapfilter+json", 1563 "capabilities" : { 1564 "cost-constraints" : true, 1565 "cost-type-names" : [ "num-routing", "num-hop", 1566 "ord-routing", "ord-hop" ] 1567 }, 1568 "uses": [ "my-default-network-map" ] 1569 }, 1570 "ordinal-routing-cost-map" : { 1571 "uri" : "http://custom.alto.example.com/ord/routingcost", 1572 "media-type" : "application/alto-costmap+json", 1573 "capabilities" : { 1574 "cost-type-names" : [ "ord-routing" ] 1575 }, 1576 "uses": [ "my-default-network-map" ] 1577 }, 1578 "ordinal-hopcount-cost-map" : { 1579 "uri" : "http://custom.alto.example.com/ord/hopcount", 1580 "media-type" : "application/alto-costmap+json", 1581 "capabilities" : { 1582 "cost-type-names" : [ "ord-hop" ], 1583 }, 1584 "uses": [ "my-default-network-map" ] 1585 } 1586 } 1587 } 1589 Note that the subdomain does not define Network Map, and uses the 1590 Network Map with Resource ID "my-default-network-map" defined in the 1591 Root IRD. 1593 9.2.5. Considerations of Using IRD 1595 9.2.5.1. ALTO Client 1597 This document specifies no requirements or constraints on ALTO 1598 Clients with regards to how they process an Information Resource 1599 Directory to identify the URI corresponding to a desired Information 1600 Resource. However, some advice is provided for implementors. 1602 It is possible that multiple entries in the directory match a desired 1603 Information Resource. For instance, in the example in Section 9.2.3, 1604 a full Cost Map with "numerical" Cost Mode and "routingcost" Cost 1605 Metric could be retrieved via a GET request to 1606 "http://alto.example.com/costmap/num/routingcost", or via a POST 1607 request to "http://custom.alto.example.com/costmap/filtered". 1609 In general, it is preferred for ALTO Clients to use GET requests 1610 where appropriate, since it is more likely for responses to be 1611 cachable. However, an ALTO Client may need to use POST, for example, 1612 to get ALTO costs or properties that are for a restricted set of PIDs 1613 or Endpoints, or to update cached information previously acquired via 1614 GET requests." 1616 9.2.5.2. ALTO Server 1618 This document indicates that an ALTO Server may or may not provide 1619 the Information Resources specified in the Map Filtering Service. If 1620 these resources are not provided, it is indicated to an ALTO Client 1621 by the absence of a Network Map or Cost Map with any media types 1622 listed under "accepts". 1624 10. Protocol Specification: Basic Data Types 1626 This section details the format of basic data types. 1628 10.1. PID Name 1630 A PID Name is encoded as a US-ASCII string. The string MUST be no 1631 more than 64 characters, and MUST NOT contain characters other than 1632 alphanumeric characters (code points 0x30-0x39, 0x41-0x5A, and 0x61- 1633 0x7A), the hyphen ('-', code point 0x2D), the colon (':', code point 1634 0x3A), the at ('@', code point 0x40), the underline ('_', code point 1635 0x5F), or the '.' separator (code point 0x2E). The '.' separator is 1636 reserved for future use and MUST NOT be used unless specifically 1637 indicated in this document, or an extension document. 1639 The type 'PIDName' is used in this document to indicate a string of 1640 this format. 1642 10.2. Resource ID 1644 A Resource ID uniquely identifies an particular resource (e.g., a 1645 Network Map) within an ALTO Server (see Section 9.2). 1647 A Resource ID is encoded as a US-ASCII string with the same format as 1648 that of PIDName. 1650 The type 'ResourceID' is used in this document to indicate a string 1651 of this format. 1653 10.3. Version Tag 1655 A Version Tag is defined as: 1657 object { 1658 ResourceID resource-id; 1659 JSONString tag; 1660 } VersionTag; 1662 The 'resource-id' attribute is the Resource ID of a resource (e.g., a 1663 Network Map) defined in the Information Resource Directory, and 'tag' 1664 is a case-sensitive US-ASCII string. The 'tag' string MUST be no 1665 more than 64 characters, and MUST NOT contain any ASCII character 1666 below 0x21 or above 0x7E. 1668 Two values of the VersionTag are equal if and only if both the the 1669 'resource-id' attributes are byte-for-byte equal and the 'tag' 1670 attributes are byte-for-byte equal. 1672 10.4. Endpoints 1674 This section defines formats used to encode addresses for Endpoints. 1675 In a case that multiple textual representations encode the same 1676 Endpoint address or prefix (within the guidelines outlined in this 1677 document), the ALTO Protocol does not require ALTO Clients or ALTO 1678 Servers to use a particular textual representation, nor does it 1679 require that ALTO Servers reply to requests using the same textual 1680 representation used by requesting ALTO Clients. ALTO Clients must be 1681 cognizant of this. 1683 10.4.1. Typed Endpoint Addresses 1685 When an Endpoint Address is used, an ALTO implementation must be able 1686 to determine its type. For this purpose, the ALTO Protocol allows 1687 endpoint addresses to also explicitly indicate their types. We refer 1688 to such addresses as Typed Endpoint Addresses. 1690 Typed Endpoint Addresses are encoded as US-ASCII strings of the 1691 format 'AddressType:EndpointAddr' (with the ':' character as a 1692 separator). The type 'TypedEndpointAddr' is used to indicate a 1693 string of this format. 1695 10.4.2. Address Type 1697 The AddressType component of TypedEndPointAddr is defined as an US- 1698 ASCII string consisting of only alphanumeric characters (code points 1699 0x30-0x39, 0x41-0x5A, and 0x61-0x7A). The type 'AddressType' is used 1700 in this document to indicate a string of this format. 1702 This document defines two values for AddressType: 'ipv4' to refer to 1703 IPv4 addresses, and 'ipv6' to refer to IPv6 addresses. All 1704 AddressType identifiers appearing in an HTTP request or response with 1705 an 'application/alto-*' media type MUST be registered in the ALTO 1706 Address Type registry (see Section 14.4). 1708 10.4.3. Endpoint Address 1710 The EndpointAddr component of TypedEndPointAddr is also encoded as an 1711 US-ASCII string. The exact characters and format depend on 1712 AddressType. This document defines EndpointAddr when AddressType is 1713 'ipv4' or 'ipv6'. 1715 10.4.3.1. IPv4 1717 IPv4 Endpoint Addresses are encoded as specified by the 'IPv4address' 1718 rule in Section 3.2.2 of [RFC3986]. 1720 10.4.3.2. IPv6 1722 IPv6 Endpoint Addresses are encoded as specified in Section 4 of 1723 [RFC5952]. 1725 10.4.4. Endpoint Prefixes 1727 For efficiency, it is useful to denote a set of Endpoint Addresses 1728 using a special notation (if one exists). This specification makes 1729 use of the prefix notations for both IPv4 and IPv6 for this purpose. 1731 Endpoint Prefixes are encoded as US-ASCII strings. The exact 1732 characters and format depend on the type of endpoint address. 1734 The type 'EndpointPrefix' is used in this document to indicate a 1735 string of this format. 1737 10.4.4.1. IPv4 1739 IPv4 Endpoint Prefixes are encoded as specified in Section 3.1 of 1740 [RFC4632]. 1742 10.4.4.2. IPv6 1744 IPv6 Endpoint Prefixes are encoded as specified in Section 7 of 1745 [RFC5952]. 1747 10.4.5. Endpoint Address Group 1749 The ALTO Protocol includes messages that specify potentially large 1750 sets of endpoint addresses. Endpoint Address Groups provide a more 1751 efficient way to encode such sets, even when the set contains 1752 endpoint addresses of different types. 1754 An Endpoint Address Group is defined as: 1756 object-map { 1757 AddressType -> EndpointPrefix<0..*>; 1758 } EndpointAddrGroup; 1760 In particular, an Endpoint Address Group is a JSON object 1761 representing a map, where each key is the string corresponding to an 1762 address type, and the corresponding value is an array listing 1763 prefixes of addresses of that type. 1765 The following is an example with both IPv4 and IPv6 endpoint 1766 addresses: 1768 { 1769 "ipv4": [ 1770 "192.0.2.0/24", 1771 "198.51.100.0/25" 1772 ], 1773 "ipv6": [ 1774 "2001:db8:0:1::/64", 1775 "2001:db8:0:2::/64" 1777 ] 1778 } 1780 10.5. Cost Mode 1782 A Cost Mode is encoded as a US-ASCII string. The string MUST either 1783 have the value 'numerical' or 'ordinal'. 1785 The type 'CostMode' is used in this document to indicate a string of 1786 this format. 1788 10.6. Cost Metric 1790 A Cost Metric is encoded as a US-ASCII string. The string MUST be no 1791 more than 32 characters, and MUST NOT contain characters other than 1792 alphanumeric characters (code points 0x30-0x39, 0x41-0x5A, and 0x61- 1793 0x7A), the hyphen ('-', code point 0x2D), the colon (':', code point 1794 0x3A), the underline ('_', code point 0x5F), or the '.' separator 1795 (0x2E). The '.' separator is reserved for future use and MUST NOT be 1796 used unless specifically indicated by a companion or extension 1797 document. 1799 Identifiers prefixed with 'priv:' are reserved for Private Use 1800 [RFC5226]. Identifiers prefixed with 'exp:' are reserved for 1801 Experimental use. For an identifier with the 'priv:' or 'exp:' 1802 prefix, an additional string (e.g., company identifier or random 1803 string) MUST follow to reduce potential collisions. For example, a 1804 short string after 'exp:' to indicate the starting time of a specific 1805 experiment is recommended. All other identifiers that appear in an 1806 HTTP request or response with an 'application/alto-*' media type and 1807 indicate Cost Metrics MUST be registered in the ALTO Cost Metrics 1808 registry Section 14.2. 1810 The type 'CostMetric' is used in this document to indicate a string 1811 of this format. 1813 10.7. Cost Type 1815 The combination of a CostMetric and a CostMode defines a CostType: 1817 object { 1818 CostMetric cost-metric; 1819 CostMode cost-mode; 1820 [JSONString description;] 1821 } CostType; 1822 'description', if present, MUST contain a US-ASCII string with a 1823 human-readable description of the cost-metric and cost-mode. An ALTO 1824 Client MAY present this string to a developer, as part of a discovery 1825 process. But the field is not intended to be interpreted by an ALTO 1826 Client. 1828 10.8. Endpoint Property 1830 We distinguish two types of Endpoint Properties: Resource Specific 1831 Endpoint Properties and Global Endpoint Properties. The type 1832 'EndpointPropertyType' is used in this document to indicate a US- 1833 ASCII string denoting either a Resource Specific Endpoint Property or 1834 a Global Endpoint Property. 1836 10.8.1. Resource Specific Endpoint Properties 1838 We define only one Resource Specific Endpoint Property in this 1839 document: pid. It has the following format: a Resource ID, followed 1840 by the '.' separator (0x2E), followed by "pid". An example is "my- 1841 default-networkmap.pid". 1843 10.8.2. Global Endpoint Properties 1845 An Global Endpoint Property is encoded as a US-ASCII string. The 1846 string MUST be no more than 32 characters, and MUST NOT contain 1847 characters other than alphanumeric characters (code points 0x30-0x39, 1848 0x41-0x5A, and 0x61-0x7A), the hyphen ('-', code point 0x2D), the 1849 colon (':', code point 0x3A), or the underline ('_', code point 1850 0x5F). Note that the '.' separator is not allowed so that there is 1851 no ambiguity on whether an endpoint property is global or resource 1852 specific. 1854 Identifiers prefixed with 'priv:' are reserved for Private Use 1855 [RFC5226]. Identifiers prefixed with 'exp:' are reserved for 1856 Experimental use. For an identifier with the 'priv:' or 'exp:' 1857 prefix, an additional string (e.g., company identifier or random 1858 string) MUST follow to reduce potential collisions. For example, a 1859 short string after 'exp:' to indicate the starting time of a specific 1860 experiment is recommended. All other identifiers for Endpoint 1861 Properties appearing in an HTTP request or response with an 1862 'application/alto-*' media type MUST be registered in the ALTO 1863 Endpoint Property registry Section 14.3. 1865 11. Protocol Specification: Service Information Resources 1867 This section documents the individual Information Resources defined 1868 to provide the services defined in this document. 1870 11.1. Meta Information 1872 For the "meta" field of the response to an individual Information 1873 Resource, we define two generic keys: "vtag", which is the Version 1874 Tag (see Section 10.3) of the current Information Resource; and 1875 "dependent-vtags", which is an array of Version Tags, to indicate the 1876 Version Tags of the resources that this resource depends on. 1878 11.2. Map Service 1880 The Map Service provides batch information to ALTO Clients in the 1881 form of two types of maps: a Network Map and Cost Map. 1883 11.2.1. Network Map 1885 A Network Map Information Resource defines a set of PIDs, and for 1886 each PID, lists the network locations (endpoints) within the PID. An 1887 ALTO Server MUST provide at least one Network Map. 1889 11.2.1.1. Media Type 1891 The media type of Network Map is "application/alto-networkmap+json". 1893 11.2.1.2. HTTP Method 1895 A Network Map resource is requested using the HTTP GET method. 1897 11.2.1.3. Accept Input Parameters 1899 None. 1901 11.2.1.4. Capabilities 1903 None. 1905 11.2.1.5. Uses 1907 None. 1909 11.2.1.6. Response 1911 The "meta" field of a Network Map response MUST include "vtag", which 1912 is the Version Tag of the retrieved Network Map. 1914 The data component of a Network Map response is named "network-map", 1915 which is a JSON object of type NetworkMapData: 1917 object { 1918 NetworkMapData network-map; 1919 } InfoResourceNetworkMap : ResponseEntityBase; 1921 object-map { 1922 PIDName -> EndpointAddrGroup; 1923 } NetworkMapData; 1925 Specifically, a NetworkMapData object is a dictionary map keyed by 1926 PIDs, and each value representing the associated set of endpoint 1927 addresses of a PID. 1929 The returned Network Map MUST include all PIDs known to the ALTO 1930 Server. 1932 11.2.1.7. Example 1934 GET /networkmap HTTP/1.1 1935 Host: alto.example.com 1936 Accept: application/alto-networkmap+json,application/alto-error+json 1937 HTTP/1.1 200 OK 1938 Content-Length: TBA 1939 Content-Type: application/alto-networkmap+json 1941 { 1942 "meta" : { 1943 "vtag": { 1944 "resource-id": "my-default-network-map", 1945 "tag": "1266506139" 1946 } 1947 }, 1948 "network-map" : { 1949 "PID1" : { 1950 "ipv4" : [ 1951 "192.0.2.0/24", 1952 "198.51.100.0/25" 1953 ] 1954 }, 1955 "PID2" : { 1956 "ipv4" : [ 1957 "198.51.100.128/25" 1958 ] 1959 }, 1960 "PID3" : { 1961 "ipv4" : [ 1962 "0.0.0.0/0" 1963 ], 1964 "ipv6" : [ 1965 "::/0" 1966 ] 1967 } 1968 } 1969 } 1971 When parsing a Network Map, an ALTO Client MUST ignore any 1972 EndpointAddressGroup whose address type it does not recognize. If as 1973 a result a PID does not have any address types known to the client, 1974 the client still MUST recognize that PID name as valid, even though 1975 the PID then contains no endpoints. 1977 Note that the encoding of a Network Map response was chosen for 1978 readability and compactness. If lookup efficiency at runtime is 1979 crucial, then the returned Network Map can be transformed into data 1980 structures offering more efficient lookup. For example, one may 1981 store the Network Map as a trie-based data structure, which may allow 1982 efficient longest-prefix matching of IP addresses. 1984 11.2.2. Mapping IP Addresses to PIDs for 'ipv4'/'ipv6' Network Maps 1986 A key usage of a Network Map is to map Endpoint Addresses to PIDs. 1987 For Network Maps containing the 'ipv4' and 'ipv6' address types 1988 defined in this document, when either an ALTO Client or an ALTO 1989 Server needs to compute the mapping from IP addresses to PIDs, the 1990 longest-prefix matching algorithm [RFC1812] MUST be used. 1992 To ensure that the longest-prefix matching algorithm yields one and 1993 only one PID, Network Maps containing the 'ipv4/'ipv6' address types 1994 MUST satisfy the following two requirements. 1996 First, such a Network Map MUST define a PID for each possible address 1997 in the IP address space for all of the address types contained in the 1998 map. We refer to this as the completeness property of such a Network 1999 Map. A RECOMMENDED way to satisfy this property is to define a PID 2000 with the shortest enclosing prefix of the addresses provided in the 2001 map. For a map with full IPv4 reachability, this would mean 2002 including the 0.0.0.0/0 prefix in a PID; for full IPv6 reachability, 2003 this would be the ::/0 prefix. 2005 Second, such a Network Map MUST NOT define two or more PIDs that 2006 contain an identical IP prefix, in order to ensure that the longest- 2007 prefix matching algorithm maps each IP addresses into exactly one 2008 PID. We refer to this as the non-overlapping property of such a 2009 Network Map. Specifically, to map an IP address to its PID in a non- 2010 overlapping Network Map, one considers the set S which consists of 2011 all prefixes defined in the Network Map, applies the longest-prefix 2012 mapping algorithm to S to identify the longest prefix containing the 2013 IP address, and assigns that the IP address belongs to the PID 2014 containing the identified longest prefix. 2016 The following example shows a complete and non-overlapping Network 2017 Map: 2019 "network-map" : { 2020 "PID0" : { "ipv6" : [ "::/0" ] }, 2021 "PID1" : { "ipv4" : [ "0.0.0.0/0" ] }, 2022 "PID2" : { "ipv4" : [ "192.0.2.0/24", "198.51.100.0/24" ] }, 2023 "PID3" : { "ipv4" : [ "192.0.2.0/25", "192.0.2.128/25" ] } 2024 } 2026 The IP address 192.0.2.1 should be mapped to PID3. 2028 If, however, the two adjacent prefixes in PID3 were combined as a 2029 single prefix, then PID3 was changed to 2031 "PID3" : { "ipv4" : [ "192.0.2.0/24" ] } 2033 The new map is no longer non-overlapping, and 192.0.2.1 could no 2034 longer be mapped unambiguously to a PID by means of longest-prefix 2035 matching. 2037 Extension documents may define techniques to allow a single IP 2038 address being mapped to multiple PIDs, when a need is identified. 2040 11.2.3. Cost Map 2042 A Cost Map resource lists the Path Cost for each pair of source/ 2043 destination PID defined by the ALTO Server for a given Cost Metric 2044 and Cost Mode. This resource MUST be provided for at least the 2045 'routingcost' Cost Metric. 2047 11.2.3.1. Media Type 2049 The media type of Cost Map is "application/alto-costmap+json". 2051 11.2.3.2. HTTP Method 2053 A Cost Map resource is requested using the HTTP GET method. 2055 11.2.3.3. Accept Input Parameters 2057 None. 2059 11.2.3.4. Capabilities 2061 The capabilities of an ALTO Server URI providing an unfiltered cost 2062 map is a JSON Object of type CostMapCapabilities: 2064 object { 2065 JSONString cost-type-names<1..1>; 2066 } CostMapCapabilities; 2068 with field: 2070 cost-type-names Note that the array MUST include a single CostType 2071 name defined by key "cost-types" in "meta" of the IRD. This is 2072 because an unfiltered Cost Map (accept == "") is requested via an 2073 HTTP GET that accepts no input parameters. As a contrast, for 2074 filtered cost maps (see Section 11.3.2), the array can have 2075 multiple elements. 2077 11.2.3.5. Uses 2079 The Resource ID of the Network Map based on which the Cost Map will 2080 be defined. Recall (Section 6) that the combination of a Network Map 2081 and a CostType defines a key. In other words, an ALTO Server MUST 2082 NOT define two Cost Maps with the same Cost Type, Network Map pair. 2084 11.2.3.6. Response 2086 The "meta" field of a Cost Map response MUST include the "dependent- 2087 vtags" key, whose value is a single-element array to indicate the 2088 Version Tag of the Network Map used, where the Network Map is 2089 specified in "uses" of the IRD. The "meta" MUST also include "cost- 2090 type", to indicate the Cost Type (Section 10.7) of the Cost Map. 2092 The data component of a Cost Map response is named "cost-map", which 2093 is a JSON object of type CostMapData: 2095 object { 2096 CostMapData cost-map; 2097 } InfoResourceCostMap : ResponseEntityBase; 2099 object-map { 2100 PIDName -> DstCosts; 2101 } CostMapData; 2103 object-map { 2104 PIDName -> JSONValue; 2105 } DstCosts; 2107 Specifically, a CostMapData object is a dictionary map object, with 2108 each key being the PIDName string identifying the corresponding 2109 Source PID, and value being a type of DstCosts, which denotes the 2110 associated costs from the Source PID to a set of destination PIDs ( 2111 Section 6.2). An implementation of the protocol in this document 2112 SHOULD assume that the cost is a JSONNumber and fail to parse if it 2113 is not, unless the implementation is using an extension to this 2114 document that indicates when and how costs of other data types are 2115 signaled. 2117 The returned Cost Map MUST include the Path Cost for each (Source 2118 PID, Destination PID) pair for which a Path Cost is defined. An ALTO 2119 Server MAY omit entries for which a Path Cost is not defined (e.g., 2120 both the Source and Destination PIDs contain addresses outside of the 2121 Network Provider's administrative domain). 2123 Similar to Network Map, the encoding of Cost Map was chosen for 2124 readability and compactness. If lookup efficiency at runtime is 2125 crucial, then the returned Cost Map can be transformed into data 2126 structures offering more efficient lookup. For example, one may 2127 store a Cost Map as a matrix. 2129 11.2.3.7. Example 2131 GET /costmap/num/routingcost HTTP/1.1 2132 Host: alto.example.com 2133 Accept: application/alto-costmap+json,application/alto-error+json 2135 HTTP/1.1 200 OK 2136 Content-Length: TBA 2137 Content-Type: application/alto-costmap+json 2139 { 2140 "meta" : { 2141 "dependent-vtags" : [ 2142 {"resource-id": "my-default-network-map", 2143 "tag": "1266506139" 2144 } 2145 ], 2146 "cost-type" : {"cost-mode" : "numerical", 2147 "cost-metric": "routingcost" 2148 } 2149 }, 2150 "cost-map" : { 2151 "PID1": { "PID1": 1, "PID2": 5, "PID3": 10 }, 2152 "PID2": { "PID1": 5, "PID2": 1, "PID3": 15 }, 2153 "PID3": { "PID1": 20, "PID2": 15 } 2154 } 2155 } 2157 Similar to the Network Map case, we considered array-based encoding 2158 for "map", but chose the current encoding for clarity. 2160 11.3. Map Filtering Service 2162 The Map Filtering Service allows ALTO Clients to specify filtering 2163 criteria to return a subset of the full maps available in the Map 2164 Service. 2166 11.3.1. Filtered Network Map 2168 A Filtered Network Map is a Network Map Information Resource 2169 (Section 11.2.1) for which an ALTO Client may supply a list of PIDs 2170 to be included. A Filtered Network Map MAY be provided by an ALTO 2171 Server. 2173 11.3.1.1. Media Type 2175 Since a Filtered Network Map is still a Network Map, it uses the 2176 media type defined for Network Map at Section 11.2.1.1. 2178 11.3.1.2. HTTP Method 2180 A Filtered Network Map is requested using the HTTP POST method. 2182 11.3.1.3. Accept Input Parameters 2184 An ALTO Client supplies filtering parameters by specifying media type 2185 "application/alto-networkmapfilter+json" with HTTP POST body 2186 containing a JSON Object of type ReqFilteredNetworkMap, where: 2188 object { 2189 PIDName pids<0..*>; 2190 [AddressType address-types<0..*>;] 2191 } ReqFilteredNetworkMap; 2193 with fields: 2195 pids Specifies list of PIDs to be included in the returned Filtered 2196 Network Map. If the list of PIDs is empty, the ALTO Server MUST 2197 interpret the list as if it contained a list of all currently- 2198 defined PIDs. The ALTO Server MUST interpret entries appearing 2199 multiple times as if they appeared only once. 2201 address-types Specifies list of address types to be included in the 2202 returned Filtered Network Map. If the "address-types" field is not 2203 specified, or the list of address types is empty, the ALTO Server 2204 MUST interpret the list as if it contained a list of all address 2205 types known to the ALTO Server. The ALTO Server MUST interpret 2206 entries appearing multiple times as if they appeared only once. 2208 11.3.1.4. Capabilities 2210 None. 2212 11.3.1.5. Uses 2214 The Resource ID of the Network Map based on which the filtering is 2215 performed. 2217 11.3.1.6. Response 2219 The format is the same as unfiltered Network Map. See 2220 Section 11.2.1.6 for the format. 2222 The ALTO Server MUST only include PIDs in the response that were 2223 specified (implicitly or explicitly) in the request. If the input 2224 parameters contain a PID name that is not currently defined by the 2225 ALTO Server, the ALTO Server MUST behave as if the PID did not appear 2226 in the input parameters. Similarly, the ALTO Server MUST only 2227 enumerate addresses within each PID that have types which were 2228 specified (implicitly or explicitly) in the request. If the input 2229 parameters contain an address type that is not currently known to the 2230 ALTO Server, the ALTO Server MUST behave as if the address type did 2231 not appear in the input parameters. 2233 The Version Tag included in the "vtag" of the response MUST 2234 correspond to the full (unfiltered) Network Map Information Resource 2235 from which the filtered information is provided. This ensures that a 2236 single, canonical Version Tag is used independent of any filtering 2237 that is requested by an ALTO Client. 2239 11.3.1.7. Example 2241 POST /networkmap/filtered HTTP/1.1 2242 Host: custom.alto.example.com 2243 Content-Length: TBA 2244 Content-Type: application/alto-networkmapfilter+json 2245 Accept: application/alto-networkmap+json,application/alto-error+json 2247 { 2248 "pids": [ "PID1", "PID2" ] 2249 } 2251 HTTP/1.1 200 OK 2252 Content-Length: TBA 2253 Content-Type: application/alto-networkmap+json 2255 { 2256 "meta" : { 2257 "vtag" : { 2258 "resource-id": "my-default-network-map", 2259 "tag": "1266506139" 2260 } 2261 }, 2262 "network-map" : { 2263 "PID1" : { 2264 "ipv4" : [ 2265 "192.0.2.0/24", 2266 "198.51.100.0/24" 2267 ] 2268 }, 2269 "PID2" : { 2270 "ipv4": [ 2271 "198.51.100.128/24" 2272 ] 2273 } 2274 } 2275 } 2277 11.3.2. Filtered Cost Map 2279 A Filtered Cost Map is a Cost Map Information Resource 2280 (Section 11.2.3) for which an ALTO Client may supply additional 2281 parameters limiting the scope of the resulting Cost Map. A Filtered 2282 Cost Map MAY be provided by an ALTO Server. 2284 11.3.2.1. Media Type 2286 Since a Filtered Cost Map is still a Cost Map, it uses the media type 2287 defined for Cost Map at Section 11.2.3.1. 2289 11.3.2.2. HTTP Method 2291 A Filtered Cost Map is requested using the HTTP POST method. 2293 11.3.2.3. Accept Input Parameters 2295 The input parameters for a Filtered Map are supplied in the entity 2296 body of the POST request. This document specifies the input 2297 parameters with a data format indicated by the media type 2298 "application/alto-costmapfilter+json", which is a JSON Object of type 2299 ReqFilteredCostMap, where: 2301 object { 2302 CostType cost-type; 2303 [JSONString constraints<0..*>;] 2304 [PIDFilter pids;] 2305 } ReqFilteredCostMap; 2307 object { 2308 PIDName srcs<0..*>; 2309 PIDName dsts<0..*>; 2310 } PIDFilter; 2312 with fields: 2314 cost-type The CostType (Section 10.7) for the returned costs. The 2315 cost-metric and cost-mode fields MUST match one of the supported 2316 Cost Types indicated in this resource's capabilities 2317 (Section 11.3.2.4). The ALTO Client SHOULD omit the description 2318 field, and if present, the ALTO Server MUST ignore the description 2319 field. 2321 constraints Defines a list of additional constraints on which 2322 elements of the Cost Map are returned. This parameter MUST NOT be 2323 specified if this resource's capabilities ( Section 11.3.2.4) 2324 indicate that constraint support is not available. A constraint 2325 contains two entities separated by whitespace: (1) an operator, 2326 'gt' for greater than, 'lt' for less than, 'ge' for greater than 2327 or equal to, 'le' for less than or equal to, or 'eq' for equal to; 2328 (2) a target cost value. The cost value is a number that MUST be 2329 defined in the same units as the Cost Metric indicated by the 2330 cost-metric parameter. ALTO Servers SHOULD use at least IEEE 754 2331 double-precision floating point [IEEE.754.2008] to store the cost 2332 value, and SHOULD perform internal computations using double- 2333 precision floating-point arithmetic. If multiple 'constraint' 2334 parameters are specified, they are interpreted as being related to 2335 each other with a logical AND. 2337 pids A list of Source PIDs and a list of Destination PIDs for which 2338 Path Costs are to be returned. If a list is empty, the ALTO 2339 Server MUST interpret it as the full set of currently-defined 2340 PIDs. The ALTO Server MUST interpret entries appearing in a list 2341 multiple times as if they appeared only once. If the "pids" field 2342 is not present, both lists MUST be interpreted by the ALTO Server 2343 as containing the full set of currently-defined PIDs. 2345 11.3.2.4. Capabilities 2347 The URI providing this resource supports all capabilities documented 2348 in Section 11.2.3.4 (with identical semantics), plus additional 2349 capabilities. In particular, the capabilities are defined by a JSON 2350 object of type FilteredCostMapCapabilities: 2352 object { 2353 JSONString cost-type-names<1..*>; 2354 JSONBool cost-constraints; 2355 } FilteredCostMapCapabilities; 2357 with fields: 2359 cost-type-names See Section 11.2.3.4 and note that the array can 2360 have 1 to many cost types. 2362 cost-constraints If true, then the ALTO Server allows cost 2363 constraints to be included in requests to the corresponding URI. 2364 If not present, this field MUST be interpreted as if it specified 2365 false. ALTO Clients should be aware that constraints may not have 2366 the intended effect for cost maps with the 'ordinal' Cost Mode 2367 since ordinal costs are not restricted to being sequential 2368 integers. 2370 11.3.2.5. Uses 2372 The Resource ID of the Network Map based on which the Cost Map will 2373 be filtered. 2375 11.3.2.6. Response 2377 The format is the same as an unfiltered Cost Map. See 2378 Section 11.2.3.6 for the format. 2380 The "dependent-vtags" key in the "meta" field is an array consisting 2381 of a single element, which is the Version Tag of the Network Map used 2382 in filtering. ALTO Clients should verify that the Version Tag 2383 included in the response is consistent with the Version Tag of the 2384 Network Map used to generate the request (if applicable). If it is 2385 not, the ALTO Client may wish to request an updated Network Map, 2386 identify changes, and consider requesting a new Filtered Cost Map. 2388 The returned Cost Map MUST contain only source/destination pairs that 2389 have been indicated (implicitly or explicitly) in the input 2390 parameters. If the input parameters contain a PID name that is not 2391 currently defined by the ALTO Server, the ALTO Server MUST behave as 2392 if the PID did not appear in the input parameters. 2394 If any constraints are specified, Source/Destination pairs for which 2395 the Path Costs do not meet the constraints MUST NOT be included in 2396 the returned Cost Map. If no constraints were specified, then all 2397 Path Costs are assumed to meet the constraints. 2399 11.3.2.7. Example 2401 POST /costmap/filtered HTTP/1.1 2402 Host: custom.alto.example.com 2403 Content-Type: application/alto-costmapfilter+json 2404 Accept: application/alto-costmap+json,application/alto-error+json 2406 { 2407 "cost-type" : {"cost-mode": "numerical", 2408 "cost-metric": "routingcost" 2409 }, 2410 "pids" : { 2411 "srcs" : [ "PID1" ], 2412 "dsts" : [ "PID1", "PID2", "PID3" ] 2413 } 2414 } 2416 HTTP/1.1 200 OK 2417 Content-Length: TBA 2418 Content-Type: application/alto-costmap+json 2420 { 2421 "meta" : { 2422 "dependent-vtags" : [ 2423 {"resource-id": "my-default-network-map", 2424 "tag": "1266506139" 2425 } 2426 ], 2427 "cost-type": {"cost-mode" : "numerical", 2428 "cost-metric" : "routingcost" 2429 } 2430 }, 2431 "cost-map" : { 2432 "PID1": { "PID1": 0, "PID2": 1, "PID3": 2 } 2433 } 2434 } 2436 11.4. Endpoint Property Service 2438 The Endpoint Property Service provides information about Endpoint 2439 properties to ALTO Clients. 2441 11.4.1. Endpoint Property 2443 An Endpoint Property resource provides information about properties 2444 for individual endpoints. It MAY be provided by an ALTO Server. 2446 11.4.1.1. Media Type 2448 The media type of Endpoint Property is "application/ 2449 alto-endpointprop+json". 2451 11.4.1.2. HTTP Method 2453 The Endpoint Property resource is requested using the HTTP POST 2454 method. 2456 11.4.1.3. Accept Input Parameters 2458 An ALTO Client supplies the endpoint properties to be queried through 2459 a media type "application/alto-endpointpropparams+json", and 2460 specifies in the HTTP POST entity body a JSON Object of type 2461 ReqEndpointProp: 2463 object { 2464 EndpointPropertyType properties<1..*>; 2465 TypedEndpointAddr endpoints<1..*>; 2466 } ReqEndpointProp; 2468 with fields: 2470 properties List of endpoint properties to be returned for each 2471 endpoint. Each specified property MUST be included in the list of 2472 supported properties indicated by this resource's capabilities 2473 (Section 11.4.1.4). The ALTO Server MUST interpret entries 2474 appearing multiple times as if they appeared only once. 2476 endpoints List of endpoint addresses for which the specified 2477 properties are to be returned. The ALTO Server MUST interpret 2478 entries appearing multiple times as if they appeared only once. 2480 11.4.1.4. Capabilities 2482 This resource may be defined across multiple types of endpoint 2483 properties. The capabilities of an ALTO Server URI providing 2484 Endpoint Properties are defined by a JSON Object of type 2485 EndpointPropertyCapabilities: 2487 object { 2488 EndpointPropertyType prop-types<1..*>; 2489 } EndpointPropertyCapabilities; 2491 with field: 2493 prop-types The Endpoint Properties (see Section 10.8) supported by 2494 the corresponding URI. 2496 In particular, the Information Resource Closure MUST provide the look 2497 up of pid for every Network Map defined. 2499 11.4.1.5. Uses 2501 None. 2503 11.4.1.6. Response 2505 The "dependent-vtags" key in the "meta" field of the response MUST be 2506 an array that includes the Version Tags of all Network Maps whose 2507 'pid' is queried. 2509 The data component of an Endpoint Properties response is named 2510 "endpoint-properties", which is a JSON object of type 2511 EndpointPropertyMapData, where: 2513 object { 2514 EndpointPropertyMapData endpoint-properties; 2515 } InfoResourceEndpointProperties : ResponseEntityBase; 2517 object-map { 2518 TypedEndpointAddr -> EndpointProps; 2519 } EndpointPropertyMapData; 2521 object { 2522 EndpointPropertyType -> JSONValue; 2523 } EndpointProps; 2525 Specifically, an EndpointPropertyMapData object has one member for 2526 each endpoint indicated in the input parameters (with the name being 2527 the endpoint encoded as a TypedEndpointAddr). The requested 2528 properties for each endpoint are encoded in a corresponding 2529 EndpointProps object, which encodes one name/value pair for each 2530 requested property, where the property names are encoded as strings 2531 of type EndpointPropertyType. An implementation of the protocol in 2532 this document SHOULD assume that the property value is a JSONString 2533 and fail to parse if it is not, unless the implementation is using an 2534 extension to this document that indicates when and how property 2535 values of other data types are signaled. 2537 The ALTO Server returns the value for each of the requested endpoint 2538 properties for each of the endpoints listed in the input parameters. 2540 If the ALTO Server does not define a requested property's value for a 2541 particular endpoint, then it MUST omit that property from the 2542 response for only that endpoint. 2544 11.4.1.7. Example 2546 POST /endpointprop/lookup HTTP/1.1 2547 Host: alto.example.com 2548 Content-Length: TBA 2549 Content-Type: application/alto-endpointpropparams+json 2550 Accept: application/alto-endpointprop+json,application/alto-error+json 2552 { 2553 "properties" : [ "my-default-networkmap.pid", 2554 "priv:ietf-example-prop" ], 2555 "endpoints" : [ "ipv4:192.0.2.34", 2556 "ipv4:203.0.113.129" ] 2557 } 2559 HTTP/1.1 200 OK 2560 Content-Length: TBA 2561 Content-Type: application/alto-endpointprop+json 2563 { 2564 "meta" : { 2565 "dependent-vtags" : [ 2566 {"resource-id": "my-default-network-map", 2567 "tag": "1266506139" 2568 } 2569 ] 2570 }, 2571 "endpoint-properties": { 2572 "ipv4:192.0.2.34" : { "my-default-network-map.pid": "PID1", 2573 "priv:ietf-example-prop": "1" }, 2574 "ipv4:203.0.113.129" : { "my-default-network-map.pid": "PID3" } 2575 } 2576 } 2578 11.5. Endpoint Cost Service 2580 The Endpoint Cost Service provides information about costs between 2581 individual endpoints. 2583 In particular, this service allows lists of Endpoint prefixes (and 2584 addresses, as a special case) to be ranked (ordered) by an ALTO 2585 Server. 2587 11.5.1. Endpoint Cost 2589 An Endpoint Cost resource provides information about costs between 2590 individual endpoints. It MAY be provided by an ALTO Server. 2592 It is important to note that although this resource allows an ALTO 2593 Server to reveal costs between individual endpoints, an ALTO Server 2594 is not required to do so. A simple alternative would be to compute 2595 the cost between two endpoints as the cost between the PIDs 2596 corresponding to the endpoints. See Section 15.3 for additional 2597 details. 2599 11.5.1.1. Media Type 2601 The media type of Endpoint Cost is "application/ 2602 alto-endpointcost+json". 2604 11.5.1.2. HTTP Method 2606 The Endpoint Cost resource is requested using the HTTP POST method. 2608 11.5.1.3. Accept Input Parameters 2610 An ALTO Client supplies the endpoint cost parameters through a media 2611 type "application/alto-endpointcostparams+json", with an HTTP POST 2612 entity body of a JSON Object of type ReqEndpointCostMap: 2614 object { 2615 CostType cost-type; 2616 [JSONString constraints<0..*>;] 2617 EndpointFilter endpoints; 2618 } ReqEndpointCostMap; 2620 object { 2621 [TypedEndpointAddr srcs<0..*>;] 2622 [TypedEndpointAddr dsts<0..*>;] 2623 } EndpointFilter; 2624 with fields: 2626 cost-type The Cost Type (Section 10.7) to use for returned costs. 2627 The cost-metric and cost-mode fields MUST match one of the 2628 supported Cost Types indicated in this resource's capabilities ( 2629 Section 11.5.1.4). The ALTO Client SHOULD omit the description 2630 field, and if present, the ALTO Server MUST ignore the description 2631 field. 2633 constraints Defined equivalently to the "constraints" input 2634 parameter of a Filtered Cost Map (see Section 11.3.2). 2636 endpoints A list of Source Endpoints and Destination Endpoints for 2637 which Path Costs are to be returned. If the list of Source or 2638 Destination Endpoints is empty (or not included), the ALTO Server 2639 MUST interpret it as if it contained the Endpoint Address 2640 corresponding to the client IP address from the incoming 2641 connection (see Section 13.3 for discussion and considerations 2642 regarding this mode). The Source and Destination Endpoint lists 2643 MUST NOT be both empty. The ALTO Server MUST interpret entries 2644 appearing multiple times in a list as if they appeared only once. 2646 11.5.1.4. Capabilities 2648 In this document, we define EndpointCostCapabilities the same as 2649 FilteredCostMapCapabilities. See Section 11.3.2.4. 2651 11.5.1.5. Uses 2653 It is important to note that although this resource allows an ALTO 2654 Server to reveal costs between individual endpoints, an ALTO Server 2655 is not required to do so. A simple implementation of an ECS resource 2656 may compute the cost between two endpoints as the cost between the 2657 PIDs corresponding to the endpoints, using one of the exposed network 2658 and cost maps defined by the server. However, to preserve 2659 flexibility, the ECS resource MAY omit declaring in the "uses" 2660 attribute the network map and/or cost map on which it depends. 2662 11.5.1.6. Response 2664 The "meta" field of an Endpoint Cost response MUST include the "cost- 2665 type" key, to indicate the Cost Type used. 2667 The data component of an Endpoint Cost response is named "endpoint- 2668 cost-map", which is a JSON object of type EndpointCostMapData: 2670 object { 2671 EndpointCostMapData endpoint-cost-map; 2672 } InfoResourceEndpointCostMap : ResponseEntityBase; 2674 object-map { 2675 TypedEndpointAddr -> EndpointDstCosts; 2676 } EndpointCostMapData; 2678 object-map { 2679 TypedEndpointAddr -> JSONValue; 2680 } EndpointDstCosts; 2682 Specifically, an EndpointCostMapData object is a dictionary map with 2683 each key representing a TypedEndpointAddr string identifying the 2684 Source Endpoint specified in the input parameters. For each Source 2685 Endpoint, a EndpointDstCosts dictionary map object denotes the 2686 associated cost to each Destination Endpoint specified in input 2687 parameters. An implementation of the protocol in this document 2688 SHOULD assume that the cost value is a JSONNumber and fail to parse 2689 if it is not, unless the implementation is using an extension to this 2690 document that indicates when and how costs of other data types are 2691 signaled. If the ALTO Server does not define a cost value from a 2692 Source Endpoint to a particular Destination Endpoint, it MAY be 2693 omitted from the response. 2695 11.5.1.7. Example 2697 POST /endpointcost/lookup HTTP/1.1 2698 Host: alto.example.com 2699 Content-Length: TBA 2700 Content-Type: application/alto-endpointcostparams+json 2701 Accept: application/alto-endpointcost+json,application/alto-error+json 2703 { 2704 "cost-type": {"cost-mode" : "ordinal", 2705 "cost-metric" : "routingcost"}, 2706 "endpoints" : { 2707 "srcs": [ "ipv4:192.0.2.2" ], 2708 "dsts": [ 2709 "ipv4:192.0.2.89", 2710 "ipv4:198.51.100.34", 2711 "ipv4:203.0.113.45" 2712 ] 2713 } 2714 } 2716 HTTP/1.1 200 OK 2717 Content-Length: TBA 2718 Content-Type: application/alto-endpointcost+json 2720 { 2721 "meta" : { 2722 "cost-type": {"cost-mode" : "ordinal", 2723 "cost-metric" : "routingcost" 2724 } 2725 }, 2726 "endpoint-cost-map" : { 2727 "ipv4:192.0.2.2": { 2728 "ipv4:192.0.2.89" : 1, 2729 "ipv4:198.51.100.34" : 2, 2730 "ipv4:203.0.113.45" : 3 2731 } 2732 } 2733 } 2735 12. Use Cases 2737 The sections below depict typical use cases. While these use cases 2738 focus on peer-to-peer applications, ALTO can be applied to other 2739 environments such as CDNs [I-D.jenkins-alto-cdn-use-cases]. 2741 12.1. ALTO Client Embedded in P2P Tracker 2743 Many currently-deployed P2P systems use a Tracker to manage swarms 2744 and perform peer selection. Such a P2P Tracker can already use a 2745 variety of information to perform peer selection to meet application- 2746 specific goals. By acting as an ALTO Client, the P2P Tracker can use 2747 ALTO information as an additional information source to enable more 2748 network-efficient traffic patterns and improve application 2749 performance. 2751 A particular requirement of many P2P trackers is that they must 2752 handle a large number of P2P clients. A P2P tracker can obtain and 2753 locally store ALTO information (the Network Map and Cost Map) from 2754 the ISPs containing the P2P clients, and benefit from the same 2755 aggregation of network locations done by ALTO Servers. 2757 .---------. (1) Get Network Map .---------------. 2758 | | <----------------------> | | 2759 | ALTO | | P2P Tracker | 2760 | Server | (2) Get Cost Map | (ALTO Client) | 2761 | | <----------------------> | | 2762 `---------' `---------------' 2763 ^ | 2764 (3) Get Peers | | (4) Selected Peer 2765 | v List 2766 .---------. .-----------. 2767 | Peer 1 | <-------------- | P2P | 2768 `---------' | Client | 2769 . (5) Connect to `-----------' 2770 . Selected Peers / 2771 .---------. / 2772 | Peer 50 | <------------------ 2773 `---------' 2775 Figure 4: ALTO Client Embedded in P2P Tracker 2777 Figure 4 shows an example use case where a P2P tracker is an ALTO 2778 Client and applies ALTO information when selecting peers for its P2P 2779 clients. The example proceeds as follows: 2781 1. The P2P Tracker requests from the ALTO Server using the Network 2782 Map query the Network Map covering all PIDs. The Network Map 2783 includes the IP prefixes contained in each PID, allowing the P2P 2784 tracker to locally map P2P clients into PIDs. 2786 2. The P2P Tracker requests from the ALTO Server the Cost Map 2787 amongst all PIDs identified in the preceding step. 2789 3. A P2P Client joins the swarm, and requests a peer list from the 2790 P2P Tracker. 2792 4. The P2P Tracker returns a peer list to the P2P client. The 2793 returned peer list is computed based on the Network Map and Cost 2794 Map returned by the ALTO Server, and possibly other information 2795 sources. Note that it is possible that a tracker may use only 2796 the Network Map to implement hierarchical peer selection by 2797 preferring peers within the same PID and ISP. 2799 5. The P2P Client connects to the selected peers. 2801 Note that the P2P tracker may provide peer lists to P2P clients 2802 distributed across multiple ISPs. In such a case, the P2P tracker 2803 may communicate with multiple ALTO Servers. 2805 12.2. ALTO Client Embedded in P2P Client: Numerical Costs 2807 P2P clients may also utilize ALTO information themselves when 2808 selecting from available peers. It is important to note that not all 2809 P2P systems use a P2P tracker for peer discovery and selection. 2810 Furthermore, even when a P2P tracker is used, the P2P clients may 2811 rely on other sources, such as peer exchange and DHTs, to discover 2812 peers. 2814 When an P2P Client uses ALTO information, it typically queries only 2815 the ALTO Server servicing its own ISP. The my-Internet view provided 2816 by its ISP's ALTO Server can include preferences to all potential 2817 peers. 2819 .---------. (1) Get Network Map .---------------. 2820 | | <----------------------> | | 2821 | ALTO | | P2P Client | 2822 | Server | (2) Get Cost Map | (ALTO Client) | 2823 | | <----------------------> | | .---------. 2824 `---------' `---------------' <- | P2P | 2825 .---------. / | ^ ^ | Tracker | 2826 | Peer 1 | <-------------- | | \ `---------' 2827 `---------' | (3) Gather Peers 2828 . (4) Select Peers | | \ 2829 . and Connect / .--------. .--------. 2830 .---------. / | P2P | | DHT | 2831 | Peer 50 | <---------------- | Client | `--------' 2832 `---------' | (PEX) | 2833 `--------' 2835 Figure 5: ALTO Client Embedded in P2P Client 2837 Figure 5 shows an example use case where a P2P Client locally applies 2838 ALTO information to select peers. The use case proceeds as follows: 2840 1. The P2P Client requests the Network Map covering all PIDs from 2841 the ALTO Server servicing its own ISP. 2843 2. The P2P Client requests the Cost Map amongst all PIDs from the 2844 ALTO Server. The Cost Map by default specifies numerical costs. 2846 3. The P2P Client discovers peers from sources such as Peer Exchange 2847 (PEX) from other P2P Clients, Distributed Hash Tables (DHT), and 2848 P2P Trackers. 2850 4. The P2P Client uses ALTO information as part of the algorithm for 2851 selecting new peers, and connects to the selected peers. 2853 12.3. ALTO Client Embedded in P2P Client: Ranking 2855 It is also possible for a P2P Client to offload the selection and 2856 ranking process to an ALTO Server. In this use case, the ALTO Client 2857 gathers a list of known peers in the swarm, and asks the ALTO Server 2858 to rank them. 2860 As in the use case using numerical costs, the P2P Client typically 2861 only queries the ALTO Server servicing its own ISP. 2863 .---------. .---------------. 2864 | | | | 2865 | ALTO | (2) Get Endpoint Ranking | P2P Client | 2866 | Server | <----------------------> | (ALTO Client) | 2867 | | | | .---------. 2868 `---------' `---------------' <- | P2P | 2869 .---------. / | ^ ^ | Tracker | 2870 | Peer 1 | <-------------- | | \ `---------' 2871 `---------' | (1) Gather Peers 2872 . (3) Connect to | | \ 2873 . Selected Peers / .--------. .--------. 2874 .---------. / | P2P | | DHT | 2875 | Peer 50 | <---------------- | Client | `--------' 2876 `---------' | (PEX) | 2877 `--------' 2879 Figure 6: ALTO Client Embedded in P2P Client: Ranking 2881 Figure 6 shows an example of this scenario. The use case proceeds as 2882 follows: 2884 1. The P2P Client discovers peers from sources such as Peer Exchange 2885 (PEX) from other P2P Clients, Distributed Hash Tables (DHT), and 2886 P2P Trackers. 2888 2. The P2P Client queries the ALTO Server's Ranking Service, 2889 including discovered peers as the set of Destination Endpoints, 2890 and indicates the 'ordinal' Cost Mode. The response indicates 2891 the ranking of the candidate peers. 2893 3. The P2P Client connects to the peers in the order specified in 2894 the ranking. 2896 13. Discussions 2898 13.1. Discovery 2900 The discovery mechanism by which an ALTO Client locates an 2901 appropriate ALTO Server is out of scope for this document. This 2902 document assumes that an ALTO Client can discover an appropriate ALTO 2903 Server. Once it has done so, the ALTO Client may use the Information 2904 Resource Directory (see Section 9.2) to locate an Information 2905 Resource with the desired ALTO Information. 2907 13.2. Hosts with Multiple Endpoint Addresses 2909 In practical deployments, a particular host can be reachable using 2910 multiple addresses (e.g., a wireless IPv4 connection, a wireline IPv4 2911 connection, and a wireline IPv6 connection). In general, the 2912 particular network path followed when sending packets to the host 2913 will depend on the address that is used. Network providers may 2914 prefer one path over another. An additional consideration may be how 2915 to handle private address spaces (e.g., behind carrier-grade NATs). 2917 To support such behavior, this document allows multiple endpoint 2918 addresses and address types. With this support, the ALTO Protocol 2919 allows an ALTO Service Provider the flexibility to indicate 2920 preferences for paths from an endpoint address of one type to an 2921 endpoint address of a different type. 2923 13.3. Network Address Translation Considerations 2925 At this day and age of NAT v4<->v4, v4<->v6 [RFC6144], and possibly 2926 v6<->v6 [RFC6296], a protocol should strive to be NAT friendly and 2927 minimize carrying IP addresses in the payload, or provide a mode of 2928 operation where the source IP address provide the information 2929 necessary to the server. 2931 The protocol specified in this document provides a mode of operation 2932 where the source network location is computed by the ALTO Server 2933 (i.e., the the Endpoint Cost Service) from the source IP address 2934 found in the ALTO Client query packets. This is similar to how some 2935 P2P Trackers (e.g., BitTorrent Trackers - see "Tracker HTTP/HTTPS 2936 Protocol" in [BitTorrent]) operate. 2938 There may be cases where an ALTO Client needs to determine its own IP 2939 address, such as when specifying a source Endpoint Address in the 2940 Endpoint Cost Service. It is possible that an ALTO Client has 2941 multiple network interface addresses, and that some or all of them 2942 may require NAT for connectivity to the public Internet. 2944 If a public IP address is required for a network interface, the ALTO 2945 Client SHOULD use the Session Traversal Utilities for NAT (STUN) 2946 [RFC5389]. If using this method, the host MUST use the "Binding 2947 Request" message and the resulting "XOR-MAPPED-ADDRESS" parameter 2948 that is returned in the response. Using STUN requires cooperation 2949 from a publicly accessible STUN server. Thus, the ALTO Client also 2950 requires configuration information that identifies the STUN server, 2951 or a domain name that can be used for STUN server discovery. To be 2952 selected for this purpose, the STUN server needs to provide the 2953 public reflexive transport address of the host. 2955 ALTO Clients should be cognizant that the network path between 2956 Endpoints can depend on multiple factors, e.g., source address, and 2957 destination address used for communication. An ALTO Server provides 2958 information based on Endpoint Addresses (more generally, Network 2959 Locations), but the mechanisms used for determining existence of 2960 connectivity or usage of NAT between Endpoints are out of scope of 2961 this document. 2963 13.4. Endpoint and Path Properties 2965 An ALTO Server could make available many properties about Endpoints 2966 beyond their network location or grouping. For example, connection 2967 type, geographical location, and others may be useful to 2968 applications. This specification focuses on network location and 2969 grouping, but the protocol may be extended to handle other Endpoint 2970 properties. 2972 14. IANA Considerations 2974 This document defines registries for application/alto-* Media Types, 2975 ALTO Cost Metric, ALTO Endpoint Property Types, ALTO Address Types, 2976 and ALTO Error Codes. Initial values for the registries and the 2977 process of future assignments are given below. 2979 14.1. application/alto-* Media Types 2981 This document requests the registration of multiple media types, 2982 listed in Table 2. 2984 +-------------+------------------------------+----------------+ 2985 | Type | Subtype | Specification | 2986 +-------------+------------------------------+----------------+ 2987 | application | alto-directory+json | Section 9.2 | 2988 | application | alto-networkmap+json | Section 11.2.1 | 2989 | application | alto-networkmapfilter+json | Section 11.3.1 | 2990 | application | alto-costmap+json | Section 11.2.3 | 2991 | application | alto-costmapfilter+json | Section 11.3.2 | 2992 | application | alto-endpointprop+json | Section 11.4.1 | 2993 | application | alto-endpointpropparams+json | Section 11.4.1 | 2994 | application | alto-endpointcost+json | Section 11.5.1 | 2995 | application | alto-endpointcostparams+json | Section 11.5.1 | 2996 | application | alto-error+json | Section 8.5 | 2997 +-------------+------------------------------+----------------+ 2999 Table 2: ALTO Protocol Media Types. 3001 Type name: application 3003 Subtype name: This documents requests the registration of multiple 3004 subtypes, as listed in Table 2. 3006 Required parameters: n/a 3008 Optional parameters: n/a 3010 Encoding considerations: Encoding considerations are identical to 3011 those specified for the 'application/json' media type. See 3012 [RFC4627]. 3014 Security considerations: Security considerations relating to the 3015 generation and consumption of ALTO Protocol messages are discussed 3016 in Section 15. 3018 Interoperability considerations: This document specifies format of 3019 conforming messages and the interpretation thereof. 3021 Published specification: This document is the specification for 3022 these media types; see Table 2 for the section documenting each 3023 media type. 3025 Applications that use this media type: ALTO Servers and ALTO Clients 3026 either standalone or embedded within other applications. 3028 Additional information: 3030 Magic number(s): n/a 3032 File extension(s): This document uses the mime type to refer to 3033 protocol messages and thus does not require a file extension. 3035 Macintosh file type code(s): n/a 3037 Person & email address to contact for further information: See 3038 "Authors' Addresses" section. 3040 Intended usage: COMMON 3042 Restrictions on usage: n/a 3044 Author: See "Authors' Addresses" section. 3046 Change controller: Internet Engineering Task Force 3047 (mailto:iesg@ietf.org). 3049 14.2. ALTO Cost Metric Registry 3051 This document requests the creation of an ALTO Cost Metric registry, 3052 listed in Table 3, to be maintained by IANA. 3054 +-------------+---------------------+ 3055 | Identifier | Intended Semantics | 3056 +-------------+---------------------+ 3057 | routingcost | See Section 6.1.1.1 | 3058 | priv: | Private use | 3059 | exp: | Experimental use | 3060 +-------------+---------------------+ 3062 Table 3: ALTO Cost Metrics. 3064 This registry serves two purposes. First, it ensures uniqueness of 3065 identifiers referring to ALTO Cost Metrics. Second, it provides 3066 references to particular semantics of allocated Cost Metrics to be 3067 applied by both ALTO Servers and applications utilizing ALTO Clients. 3069 New ALTO Cost Metrics are assigned after IETF Review [RFC5226] to 3070 ensure that proper documentation regarding ALTO Cost Metric semantics 3071 and security considerations has been provided. The RFCs documenting 3072 the new metrics should be detailed enough to provide guidance to both 3073 ALTO Service Providers and applications utilizing ALTO Clients as to 3074 how values of the registered ALTO Cost Metric should be interpreted. 3075 Updates and deletions of ALTO Cost Metrics follow the same procedure. 3077 Registered ALTO Cost Metric identifiers MUST conform to the 3078 syntactical requirements specified in Section 10.6. Identifiers are 3079 to be recorded and displayed as ASCII strings. 3081 Identifiers prefixed with 'priv:' are reserved for Private Use. 3082 Identifiers prefixed with 'exp:' are reserved for Experimental use. 3084 Requests to add a new value to the registry MUST include the 3085 following information: 3087 o Identifier: The name of the desired ALTO Cost Metric. 3089 o Intended Semantics: ALTO Costs carry with them semantics to guide 3090 their usage by ALTO Clients. For example, if a value refers to a 3091 measurement, the measurement units must be documented. For proper 3092 implementation of the ordinal Cost Mode (e.g., by a third-party 3093 service), it should be documented whether higher or lower values 3094 of the cost are more preferred. 3096 o Security Considerations: ALTO Costs expose information to ALTO 3097 Clients. As such, proper usage of a particular Cost Metric may 3098 require certain information to be exposed by an ALTO Service 3099 Provider. Since network information is frequently regarded as 3100 proprietary or confidential, ALTO Service Providers should be made 3101 aware of the security ramifications related to usage of a Cost 3102 Metric. 3104 This specification requests registration of the identifier 3105 'routingcost'. Semantics for the this Cost Metric are documented in 3106 Section 6.1.1.1, and security considerations are documented in 3107 Section 15.3. 3109 14.3. ALTO Endpoint Property Type Registry 3111 This document requests the creation of an ALTO Endpoint Property 3112 Types registry, listed in Table 4, to be maintained by IANA. 3114 +------------+--------------------+ 3115 | Identifier | Intended Semantics | 3116 +------------+--------------------+ 3117 | pid | See Section 7.1.1 | 3118 | priv: | Private use | 3119 | exp: | Experimental use | 3120 +------------+--------------------+ 3122 Table 4: ALTO Endpoint Property Types. 3124 The maintenance of this registry is similar to that of the preceding 3125 ALTO Cost Metrics. 3127 14.4. ALTO Address Type Registry 3129 This document requests the creation of an ALTO Address Type registry, 3130 listed in Table 5, to be maintained by IANA. 3132 +------------+-----------------+-----------------+------------------+ 3133 | Identifier | Address | Prefix Encoding | Mapping to/from | 3134 | | Encoding | | IPv4/v6 | 3135 +------------+-----------------+-----------------+------------------+ 3136 | ipv4 | See | See | Direct mapping | 3137 | | Section 10.4.3 | Section 10.4.4 | to IPv4 | 3138 | ipv6 | See | See | Direct mapping | 3139 | | Section 10.4.3 | Section 10.4.4 | to IPv6 | 3140 +------------+-----------------+-----------------+------------------+ 3141 Table 5: ALTO Address Types. 3143 This registry serves two purposes. First, it ensures uniqueness of 3144 identifiers referring to ALTO Address Types. Second, it states the 3145 requirements for allocated Address Type identifiers. 3147 New ALTO Address Types are assigned after IETF Review [RFC5226] to 3148 ensure that proper documentation regarding the new ALTO Address Types 3149 and their security considerations has been provided. RFCs defining 3150 new Address Types should indicate how an address of a registered type 3151 is encoded as an EndpointAddr and, if possible, a compact method 3152 (e.g., IPv4 and IPv6 prefixes) for encoding a set of addresses as an 3153 EndpointPrefix. Updates and deletions of ALTO Address Types follow 3154 the same procedure. 3156 Registered ALTO Address Type identifiers MUST conform to the 3157 syntactical requirements specified in Section 10.4.2. Identifiers 3158 are to be recorded and displayed as ASCII strings. 3160 Requests to add a new value to the registry MUST include the 3161 following information: 3163 o Identifier: The name of the desired ALTO Address Type. 3165 o Endpoint Address Encoding: The procedure for encoding an address 3166 of the registered type as an EndpointAddr (see Section 10.4.3). 3168 o Endpoint Prefix Encoding: The procedure for encoding a set of 3169 addresses of the registered type as an EndpointPrefix (see 3170 Section 10.4.4). If no such compact encoding is available, the 3171 same encoding used for a singular address may be used. In such a 3172 case, it must be documented that sets of addresses of this type 3173 always have exactly one element. 3175 o Mapping to/from IPv4/IPv6 Addresses: If possible, a mechanism to 3176 map addresses of the registered type to and from IPv4 or IPv6 3177 addresses should be specified. 3179 o Security Considerations: In some usage scenarios, Endpoint 3180 Addresses carried in ALTO Protocol messages may reveal information 3181 about an ALTO Client or an ALTO Service Provider. Applications 3182 and ALTO Service Providers using addresses of the registered type 3183 should be made aware of how (or if) the addressing scheme relates 3184 to private information and network proximity. 3186 This specification requests registration of the identifiers 'ipv4' 3187 and 'ipv6', as shown in Table 5. 3189 14.5. ALTO Error Code Registry 3191 This document requests the creation of an ALTO Error Code registry, 3192 to be maintained by IANA. Initial values are listed in Table 1, and 3193 recommended usage of the Error Codes is specified in Section 8.5.2. 3195 Although the Error Codes defined in Table 1 are already quite 3196 complete, future extensions may define new Error Codes. The ALTO 3197 Error Code registry ensures the uniqueness of Error Codes when new 3198 Error Codes are added. 3200 New ALTO Error Codes are assigned after IETF Review [RFC5226] to 3201 ensure that proper documentation regarding the new ALTO Error Codes 3202 and their usage has been provided. 3204 A request to add a new ALTO Error Code to the registry MUST include 3205 the following information: 3207 o Error Code: An US ASCII String starting with E_ to indicate the 3208 error. 3210 o Intended Usage: ALTO Error Codes carry with them semantics to 3211 guide their usage by ALTO Servers and Clients. In particular, if 3212 a new Error Code indicates conditions that overlap with those of 3213 an existing ALTO Error Code, recommended usage of the new Error 3214 Code should be specified. 3216 15. Security Considerations 3218 Some environments and use cases of ALTO require consideration of 3219 security attacks on ALTO Servers and Clients. In order to support 3220 those environments interoperably, the ALTO requirements document 3221 [RFC6708] outlines minimum-to-implement authentication and other 3222 security requirements. Below we consider the threats and protection 3223 strategies. 3225 15.1. Authenticity and Integrity of ALTO Information 3227 15.1.1. Risk Scenarios 3229 An attacker may want to provide false or modified ALTO Information 3230 Resources or Information Resource Directory to ALTO Clients to 3231 achieve certain malicious goals. As an example, an attacker may 3232 provide false endpoint properties. For example, suppose that a 3233 network supports an endpoint property named "hasQuota" which reports 3234 if the endpoint has usage quota. An attacker may want to generate a 3235 false reply to lead to unexpected charges to the endpoint. An attack 3236 may also want to provide false Cost Map. For example, by faking a 3237 Cost Map that highly prefers a small address range or a single 3238 address, the attacker may be able to turn a distributed application 3239 into a Distributed Denial of Service (DDoS) tool. 3241 Depending on the network scenario, an attacker can attack 3242 authenticity and integrity of ALTO Information Resources using 3243 various techniques, including, but not limited to, sending forged 3244 DHCP replies in an Ethernet, DNS poisoning, and installing a 3245 transparent HTTP proxy that does some modifications. 3247 15.1.2. Protection Strategies 3249 ALTO protects the authenticity and integrity of ALTO Information 3250 (both Information Directory and individual Information Resources) by 3251 leveraging the authenticity and integrity mechanisms in TLS. In 3252 particular, the ALTO Protocol requires that HTTP over TLS [RFC2818] 3253 MUST be supported, when protecting the authenticity and integrity of 3254 ALTO Information is required. The rules in [RFC2818] for a client to 3255 verify server identity using server certificates MUST be supported. 3256 ALTO Providers who request server certificates and certification 3257 authorities who issue ALTO-specific certificates SHOULD consider the 3258 recommendations and guidelines defined in [RFC6125] 3260 Software engineers developing and service providers deploying ALTO 3261 should make themselves familiar with up-to-date Best Current 3262 Practices on configuring HTTP over TLS. 3264 15.1.3. Limitations 3266 The protection of HTTP over TLS for ALTO depends on that the domain 3267 name in the URI for the Information Resources is not comprised. This 3268 will depend on the protection implemented by service discovery. 3270 A deployment scenario may require redistribution of ALTO information 3271 to improve scalability. When authenticity and integrity of ALTO 3272 information are still required, then ALTO Clients obtaining ALTO 3273 information through redistribution must be able to validate the 3274 received ALTO information. Support for this validation is not 3275 provided in this document, but may be provided by extension 3276 documents. 3278 15.2. Potential Undesirable Guidance from Authenticated ALTO 3279 Information 3281 15.2.1. Risk Scenarios 3283 The ALTO Service makes it possible for an ALTO Provider to influence 3284 the behavior of network applications. An ALTO Provider may be 3285 hostile to some applications and hence try to use ALTO Information 3286 Resources to achieve certain goals [RFC5693]: "redirecting 3287 applications to corrupted mediators providing malicious content, or 3288 applying policies in computing Cost Map based on criteria other than 3289 network efficiency." See [I-D.ietf-alto-deployments] for additional 3290 discussions on faked ALTO Guidance. 3292 A related scenario is that an ALTO Server could unintentionally give 3293 "bad" guidance. For example, if many ALTO Clients follow the Cost 3294 Map or Endpoint Cost guidance without doing additional sanity checks 3295 or adaptation, more preferable hosts and/or links could get 3296 overloaded while less preferable ones remain idle; see AR-14 of 3297 [RFC6708] for related application considerations. 3299 15.2.2. Protection Strategies 3301 To protect applications from undesirable ALTO Information Resources, 3302 it is important to note that there is no protocol mechanism to 3303 require conforming behaviors on how applications use ALTO Information 3304 Resources. An application using ALTO may consider including a 3305 mechanism to detect misleading or undesirable results from using ALTO 3306 Information Resources. For example, if throughput measurements do 3307 not show "better-than-random" results when using the Cost Map to 3308 select resource providers, the application may want to disable ALTO 3309 usage or switch to an external ALTO Server provided by an 3310 "independent organization" (see AR-20 and AR-21 in [RFC6708]). If 3311 the first ALTO Server is provided by the access network service 3312 provider and the access network service provider tries to redirect 3313 access to the external ALTO Server back to the provider's ALTO Server 3314 or try to tamper with the responses, the preceding authentication and 3315 integrity protection can detect such a behavior. 3317 15.3. Confidentiality of ALTO Information 3319 15.3.1. Risk Scenarios 3321 Although in many cases ALTO Information Resources may be regarded as 3322 non-confidential information, there are deployment cases where ALTO 3323 Information Resources can be sensitive information that can pose 3324 risks if exposed to unauthorized parties. We discuss the risks and 3325 protection strategies for such deployment scenarios. 3327 For example, an attacker may infer details regarding the topology, 3328 status, and operational policies of a network through the Network and 3329 Cost Maps. As a result, a sophisticated attacker may be able to 3330 infer more fine-graind topology information than an ISP hosting an 3331 ALTO Server intends to disclose. The attacker can leverage the 3332 information to mount effective attacks such as focusing on high-cost 3333 links. 3335 Revealing some endpoint properties may also reveal additional 3336 information than the Provider intended. For example, when adding the 3337 line bitrate as one endpoint property, such information may be 3338 potentially linked to the income of the habitants at the network 3339 location of an endpoint. 3341 In [RFC6708] Section 5.2.1, three types of risks associated with the 3342 confidentiality of ALTO Information Resources are identified: risk 3343 type (1) Excess disclosure of the ALTO service provider's data to an 3344 authorized ALTO Client; risk type (2) Disclosure of the ALTO service 3345 provider's data (e.g., network topology information) to an 3346 unauthorized third party; and risk type (3) Excess retrieval of the 3347 ALTO service provider's data by collaborating ALTO Clients. 3348 [I-D.ietf-alto-deployments] also discusses information leakage from 3349 ALTO. 3351 15.3.2. Protection Strategies 3353 To address risk types (1) and (3), the Provider of an ALTO Server 3354 must be cognizant that the network topology and provisioning 3355 information provided through ALTO may lead to attacks. ALTO does not 3356 require any particular level of details of information disclosure, 3357 and hence the Provider should evaluate how much information is 3358 revealed and the associated risks. 3360 To address risk type (2), the ALTO Protocol need confidentiality. 3361 Since ALTO requires that HTTP over TLS MUST be supported, the 3362 confidentiality mechanism is provided by HTTP over TLS. 3364 For deployment scenarios where client authentication is desired to 3365 address risk type (2), ALTO requires that HTTP Digestion 3366 Authentication MUST be supported to achieve ALTO Client 3367 Authentication to limit the number of parties with whom ALTO 3368 information is directly shared. Depending on the use-case and 3369 scenario, an ALTO Server may apply other access control techniques to 3370 restrict access to its services. Access control can also help to 3371 prevent Denial-of-Service attacks by arbitrary hosts from the 3372 Internet. See [I-D.ietf-alto-deployments] for a more detailed 3373 discussion on this issue. 3375 15.3.3. Limitations 3377 ALTO Information Providers should be cognizant that encryption only 3378 protects ALTO information until it is decrypted by the intended ALTO 3379 Client. Digital Rights Management (DRM) techniques and legal 3380 agreements protecting ALTO information are outside of the scope of 3381 this document. 3383 15.4. Privacy for ALTO Users 3385 15.4.1. Risk Scenarios 3387 The ALTO Protocol provides mechanisms in which the ALTO Client 3388 serving a user can send messages containing Network Location 3389 Identifiers (IP addresses or fine-grained PIDs) to the ALTO Server. 3390 This is particularly true for the Endpoint Property, Endpoint Cost, 3391 and fine-grained Filtered Map services. The ALTO Server or a third- 3392 party who is able to intercept such messages can store and process 3393 obtained information in order to analyze user behaviors and 3394 communication patterns. The analysis may correlate information 3395 collected from multiple clients to deduce additional application/ 3396 content information. Such analysis can lead to privacy risks. For a 3397 more comprehensive classification of related risk scenarios, see 3398 cases 4, 5, and 6 in [RFC6708], Section 5.2. 3400 15.4.2. Protection Strategies 3402 To protect user privacy, an ALTO Client should be cognizant about 3403 potential ALTO Server tracking through client queries. An ALTO 3404 Client may consider the possibility of relying only on Network Map 3405 for PIDs and Cost Map amongst PIDs to avoid passing IP addresses of 3406 other endpoints (e.g., peers) to the ALTO Server. When specific IP 3407 addresses are needed (e.g., when using the Endpoint Cost Service), an 3408 ALTO Client may consider obfuscation techniques such as specifying a 3409 broader address range (i.e., a shorter prefix length) or by zeroing 3410 out or randomizing the last few bits of IP addresses. Note that 3411 obfuscation may yield less accurate results. 3413 15.5. Availability of ALTO Service 3415 15.5.1. Risk Scenarios 3417 An attacker may want to disable ALTO Service as a way to disable 3418 network guidance to large scale applications.In particular, queries 3419 which can be generated with low effort but result in expensive 3420 workloads at the ALTO Server could be exploited for Denial-of-Service 3421 attacks. For instance, a simple ALTO query with n Source Network 3422 Locations and m Destination Network Locations can be generated fairly 3423 easily but results in the computation of n*m Path Costs between pairs 3424 by the ALTO Server (see Section 5.2). 3426 15.5.2. Protection Strategies 3428 ALTO Provider should be cognizant of the workload at the ALTO Server 3429 generated by certain ALTO Queries, such as certain queries to the Map 3430 Service, the Map Filtering Service and the Endpoint Cost (Ranking) 3431 Service. One way to limit Denial-of-Service attacks is to employ 3432 access control to the ALTO Server. The ALTO Server can also indicate 3433 overload and reject repeated requests that can cause availability 3434 problems. More advanced protection schemes such as computational 3435 puzzles [I-D.jennings-sip-hashcash] may be considered in an extension 3436 document. 3438 An ALTO Provider should also leverage the fact that the Map Service 3439 allows ALTO Servers to pre-generate maps that can be distributed to 3440 many ALTO Clients. 3442 16. Manageability Considerations 3444 This section details operations and management considerations based 3445 on existing deployments and discussions during protocol development. 3446 It also indicates where extension documents are expected to provide 3447 appropriate functionality discussed in [RFC5706] as additional 3448 deployment experience becomes available. 3450 16.1. Operations 3452 16.1.1. Installation and Initial Setup 3454 The ALTO Protocol is based on HTTP. Thus, configuring an ALTO Server 3455 may require configuring the underlying HTTP server implementation to 3456 define appropriate security policies, caching policies, performance 3457 settings, etc. 3459 Additionally, an ALTO Service Provider will need to configure the 3460 ALTO information to be provided by the ALTO Server. The granularity 3461 of the topological map and the cost map is left to the specific 3462 policies of the ALTO Service Provider. However, a reasonable default 3463 may include two PIDs, one to hold the endpoints in the provider's 3464 network and the second PID to represent full IPv4 and IPv6 3465 reachability (see Section 11.2.2), with the cost between each source/ 3466 destination PID set to 1. Another operational issue that the ALTO 3467 Service Provider needs to consider is that the filtering service can 3468 degenerate into a full map service when the filtering input is empty. 3469 Although this choice as the degeneration behavior provides 3470 continuity, the computational and network load of serving full maps 3471 to a large number of ALTO Clients should be considered. 3473 Implementers employing an ALTO Client should attempt to automatically 3474 discover an appropriate ALTO Server. Manual configuration of the 3475 ALTO Server location may be used where automatic discovery is not 3476 appropriate. Methods for automatic discovery and manual 3477 configuration are discussed in [I-D.ietf-alto-server-discovery]. 3479 Specifications for underlying protocols (e.g., TCP, HTTP, SSL/TLS) 3480 should be consulted for their available settings and proposed default 3481 configurations. 3483 16.1.2. Migration Path 3485 This document does not detail a migration path for ALTO Servers since 3486 there is no previous standard protocol providing the similar 3487 functionality. 3489 There are existing applications making use of network information 3490 discovered from other entities such as whois, geo-location databases, 3491 or round-trip time measurements, etc. Such applications should 3492 consider using ALTO as an additional source of information; ALTO need 3493 not be the sole source of network information. 3495 16.1.3. Dependencies on Other Protocols and Functional Components 3497 The ALTO Protocol assumes that HTTP client and server implementations 3498 exist. It also assumes that JSON encoder and decoder implementations 3499 exist. 3501 An ALTO Server assumes that it can gather sufficient information to 3502 populate Network and Cost maps. "Sufficient information" is 3503 dependent on the information being exposed, but likely includes 3504 information gathered from protocols such as IGP and EGP Routing 3505 Information Bases (see Figure 1). Specific mechanisms have been 3506 proposed (e.g., [I-D.medved-alto-svr-apis]) and are expected to be 3507 provided in extension documents. 3509 16.1.4. Impact and Observation on Network Operation 3511 ALTO presents a new opportunity for managing network traffic by 3512 providing additional information to clients. The potential impact to 3513 network operation is large. 3515 Deployment of an ALTO Server may shift network traffic patterns. 3516 Thus, an ALTO Service Provider should consider impacts on (or 3517 integration with) traffic engineering and the deployment of a 3518 monitoring service to observe the effects of ALTO operations. Note 3519 that ALTO-specific monitoring and metrics are discussed in 3520 [I-D.ietf-alto-deployments]. In particular, an ALTO Service Provider 3521 may observe that ALTO Clients are not bound to ALTO Server guidance 3522 as ALTO is only one source of information. 3524 An ALTO Service Provider should ensure that appropriate information 3525 is being exposed. Privacy implications for ISPs are discussed in 3526 Section 15.3. Both ALTO Service Providers and those using ALTO 3527 Clients should be aware of the impact of incorrect or faked guidance 3528 (see [I-D.ietf-alto-deployments]). 3530 16.2. Management 3532 16.2.1. Management Interoperability 3534 A common management API would be desirable given that ALTO Servers 3535 may typically be configured with dynamic data from various sources, 3536 and ALTO Servers are intended to scale horizontally for fault- 3537 tolerance and reliability. A specific API or protocol is outside the 3538 scope of this document, but may be provided by an extension document. 3540 Logging is an important functionality for ALTO Servers and, depending 3541 on the deployment, ALTO Clients. Logging should be done via syslog 3542 [RFC5424]. 3544 16.2.2. Management Information 3546 A Management Information Model (see Section 3.2 of [RFC5706] is not 3547 provided by this document, but should be included or referenced by 3548 any extension documenting an ALTO-related management API or protocol. 3550 16.2.3. Fault Management 3552 Monitoring ALTO Servers and Clients is described in 3553 [I-D.ietf-alto-deployments]. 3555 16.2.4. Configuration Management 3557 Standardized approaches and protocols to configuration management for 3558 ALTO are outside the scope of this document, but this document does 3559 outline high-level principles suggested for future standardization 3560 efforts. 3562 An ALTO Server requires at least the following logical inputs: 3564 o Data sources from which ALTO Information is derived. This can 3565 either be raw network information (e.g., from routing elements) or 3566 pre-processed ALTO-level information in the form of a Network Map, 3567 Cost Map, etc. 3569 o Algorithms for computing the ALTO information returned to clients. 3570 These could either return information from a database, or 3571 information customized for each client. 3573 o Security policies mapping potential clients to the information 3574 that they have privilege to access. 3576 Multiple ALTO Servers can be deployed for scalability. A centralized 3577 configuration database may be used to ensure they are providing the 3578 desired ALTO information with appropriate security controls. The 3579 ALTO information (e.g., Network Maps and Cost Maps) being served by 3580 each ALTO Server, as well as security policies (HTTP authentication, 3581 SSL/TLS client and server authentication, SSL/TLS encryption 3582 parameters) intended to serve the same information should be 3583 monitored for consistency. 3585 16.2.5. Performance Management 3587 An exhaustive list of desirable performance information from a ALTO 3588 Servers and ALTO Clients are outside of the scope of this document. 3589 The following is a list of suggested ALTO-specific to be monitored 3590 based on the existing deployment and protocol development experience: 3592 o Requests and responses for each service listed in a Information 3593 Directory (total counts and size in bytes). 3595 o CPU and memory utilization 3597 o ALTO map updates 3599 o Number of PIDs 3601 o ALTO map sizes (in-memory size, encoded size, number of entries) 3603 16.2.6. Security Management 3605 Section 15 documents ALTO-specific security considerations. 3606 Operators should configure security policies with those in mind. 3607 Readers should refer to HTTP [RFC2616] and SSL/TLS [RFC5246] and 3608 related documents for mechanisms available for configuring security 3609 policies. Other appropriate security mechanisms (e.g., physical 3610 security, firewalls, etc) should also be considered. 3612 17. References 3613 17.1. Normative References 3615 [RFC1812] Baker, F., "Requirements for IP Version 4 Routers", 3616 RFC 1812, June 1995. 3618 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3619 Extensions (MIME) Part Two: Media Types", RFC 2046, 3620 November 1996. 3622 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3623 Requirement Levels", BCP 14, RFC 2119, March 1997. 3625 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3626 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3627 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3629 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3630 Resource Identifier (URI): Generic Syntax", STD 66, 3631 RFC 3986, January 2005. 3633 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 3634 (CIDR): The Internet Address Assignment and Aggregation 3635 Plan", BCP 122, RFC 4632, August 2006. 3637 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3638 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3639 May 2008. 3641 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3642 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3644 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 3645 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 3646 October 2008. 3648 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009. 3650 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3651 Address Text Representation", RFC 5952, August 2010. 3653 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3654 Verification of Domain-Based Application Service Identity 3655 within Internet Public Key Infrastructure Using X.509 3656 (PKIX) Certificates in the Context of Transport Layer 3657 Security (TLS)", RFC 6125, March 2011. 3659 17.2. Informative References 3661 [BitTorrent] 3662 "Bittorrent Protocol Specification v1.0", 3663 . 3665 [Fielding-Thesis] 3666 Fielding, R., "Architectural Styles and the Design of 3667 Network-based Software Architectures", University of 3668 California, Irvine, Dissertation 2000, 2000. 3670 [I-D.akonjang-alto-proxidor] 3671 Akonjang, O., Feldmann, A., Previdi, S., Davie, B., and D. 3672 Saucez, "The PROXIDOR Service", 3673 draft-akonjang-alto-proxidor-00 (work in progress), 3674 March 2009. 3676 [I-D.ietf-alto-deployments] 3677 Stiemerling, M., Kiesel, S., Previdi, S., and M. Scharf, 3678 "ALTO Deployment Considerations", 3679 draft-ietf-alto-deployments-08 (work in progress), 3680 October 2013. 3682 [I-D.ietf-alto-server-discovery] 3683 Kiesel, S., Stiemerling, M., Schwan, N., Scharf, M., and 3684 S. Yongchao, "ALTO Server Discovery", 3685 draft-ietf-alto-server-discovery-10 (work in progress), 3686 September 2013. 3688 [I-D.ietf-httpbis-p2-semantics] 3689 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3690 (HTTP/1.1): Semantics and Content", 3691 draft-ietf-httpbis-p2-semantics-25 (work in progress), 3692 November 2013. 3694 [I-D.jenkins-alto-cdn-use-cases] 3695 Niven-Jenkins, B., Watson, G., Bitar, N., Medved, J., and 3696 S. Previdi, "Use Cases for ALTO within CDNs", 3697 draft-jenkins-alto-cdn-use-cases-03 (work in progress), 3698 June 2012. 3700 [I-D.jennings-sip-hashcash] 3701 Jennings, C., "Computational Puzzles for SPAM Reduction in 3702 SIP", draft-jennings-sip-hashcash-06 (work in progress), 3703 July 2007. 3705 [I-D.medved-alto-svr-apis] 3706 Medved, J., Ward, D., Peterson, J., Woundy, R., and D. 3708 McDysan, "ALTO Network-Server and Server-Server APIs", 3709 draft-medved-alto-svr-apis-00 (work in progress), 3710 March 2011. 3712 [I-D.p4p-framework] 3713 Alimi, R., Pasko, D., Popkin, L., Wang, Y., and Y. Yang, 3714 "P4P: Provider Portal for P2P Applications", 3715 draft-p4p-framework-00 (work in progress), November 2008. 3717 [I-D.saumitra-alto-multi-ps] 3718 Das, S., Narayanan, V., and L. Dondeti, "ALTO: A Multi 3719 Dimensional Peer Selection Problem", 3720 draft-saumitra-alto-multi-ps-00 (work in progress), 3721 October 2008. 3723 [I-D.saumitra-alto-queryresponse] 3724 Das, S. and V. Narayanan, "A Client to Service Query 3725 Response Protocol for ALTO", 3726 draft-saumitra-alto-queryresponse-00 (work in progress), 3727 March 2009. 3729 [I-D.shalunov-alto-infoexport] 3730 Shalunov, S., Penno, R., and R. Woundy, "ALTO Information 3731 Export Service", draft-shalunov-alto-infoexport-00 (work 3732 in progress), October 2008. 3734 [I-D.wang-alto-p4p-specification] 3735 Wang, Y., Alimi, R., Pasko, D., Popkin, L., and Y. Yang, 3736 "P4P Protocol Specification", 3737 draft-wang-alto-p4p-specification-00 (work in progress), 3738 March 2009. 3740 [IEEE.754.2008] 3741 Institute of Electrical and Electronics Engineers, 3742 "Standard for Binary Floating-Point Arithmetic", IEEE 3743 Standard 754, August 2008. 3745 [P4P-SIGCOMM08] 3746 Xie, H., Yang, Y., Krishnamurthy, A., Liu, Y., and A. 3747 Silberschatz, "P4P: Provider Portal for (P2P) 3748 Applications", SIGCOMM 2008, August 2008. 3750 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3752 [RFC4627] Crockford, D., "The application/json Media Type for 3753 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 3755 [RFC5693] Seedorf, J. and E. Burger, "Application-Layer Traffic 3756 Optimization (ALTO) Problem Statement", RFC 5693, 3757 October 2009. 3759 [RFC5706] Harrington, D., "Guidelines for Considering Operations and 3760 Management of New Protocols and Protocol Extensions", 3761 RFC 5706, November 2009. 3763 [RFC6144] Baker, F., Li, X., Bao, C., and K. Yin, "Framework for 3764 IPv4/IPv6 Translation", RFC 6144, April 2011. 3766 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 3767 Translation", RFC 6296, June 2011. 3769 [RFC6708] Kiesel, S., Previdi, S., Stiemerling, M., Woundy, R., and 3770 Y. Yang, "Application-Layer Traffic Optimization (ALTO) 3771 Requirements", RFC 6708, September 2012. 3773 Appendix A. Acknowledgments 3775 Thank you to Sebastian Kiesel (University of Stuttgart) and Jan 3776 Seedorf (NEC) for substantial contributions to the Security 3777 Considerations section. Ben Niven-Jenkins (Velocix), Michael Scharf 3778 and Sabine Randriamasy (Alcatel-Lucent) gave substantial feedback and 3779 suggestions on the protocol design. We are particularly grateful to 3780 the substantial contributions of Wendy Roome (Alcatel-Lucent). 3782 We would like to thank the following people whose input and 3783 involvement was indispensable in achieving this merged proposal: 3785 Obi Akonjang (DT Labs/TU Berlin), 3787 Saumitra M. Das (Qualcomm Inc.), 3789 Syon Ding (China Telecom), 3791 Doug Pasko (Verizon), 3793 Laird Popkin (Pando Networks), 3795 Satish Raghunath (Juniper Networks), 3797 Albert Tian (Ericsson/Redback), 3799 Yu-Shun Wang (Microsoft), 3801 David Zhang (PPLive), 3802 Yunfei Zhang (China Mobile). 3804 We would also like to thank the following additional people who were 3805 involved in the projects that contributed to this merged document: 3806 Alex Gerber (ATT), Chris Griffiths (Comcast), Ramit Hora (Pando 3807 Networks), Arvind Krishnamurthy (University of Washington), Marty 3808 Lafferty (DCIA), Erran Li (Bell Labs), Jin Li (Microsoft), Y. Grace 3809 Liu (IBM Watson), Jason Livingood (Comcast), Michael Merritt (ATT), 3810 Ingmar Poese (DT Labs/TU Berlin), James Royalty (Pando Networks), 3811 Damien Saucez (UCL) Thomas Scholl (ATT), Emilio Sepulveda 3812 (Telefonica), Avi Silberschatz (Yale University), Hassan Sipra (Bell 3813 Canada), Georgios Smaragdakis (DT Labs/TU Berlin), Haibin Song 3814 (Huawei), Oliver Spatscheck (ATT), See-Mong Tang (Microsoft), Jia 3815 Wang (ATT), Hao Wang (Yale University), Ye Wang (Yale University), 3816 Haiyong Xie (Yale University). 3818 Appendix B. Design History and Merged Proposals 3820 The ALTO Protocol specified in this document consists of 3821 contributions from 3823 o P4P [I-D.p4p-framework], [P4P-SIGCOMM08], 3824 [I-D.wang-alto-p4p-specification]; 3826 o ALTO Info-Export [I-D.shalunov-alto-infoexport]; 3828 o Query/Response [I-D.saumitra-alto-queryresponse], 3829 [I-D.saumitra-alto-multi-ps]; and 3831 o Proxidor [I-D.akonjang-alto-proxidor]. 3833 Appendix C. Specifying the "value" Key for E_INVALID_FIELD_VALUE 3835 In Section 8.5.2, an ALTO Server may specify an optional "value" key 3836 to indicate the invalid value that triggerred an 3837 E_INVALID_FIELD_VALUE error. The "value" key must specify a 3838 JSONString, but the invalid value may not be a simple JSONString. 3839 Below are the rule to specify the "value" key: 3841 o If the invalid value is a string, "value" is that string; 3843 o If the invalid value is a number, "value" must be the invalid 3844 number as a string; 3846 o If the invalid value is a subfield, the server must set the 3847 "field" key to the full path of the field name and "value" to the 3848 invalid subfield value, converting it to a string if needed. For 3849 example, if the "cost-mode" subfield of the "cost-type" field is 3850 an invalid mode "foo", the server should set "value" to "foo", and 3851 "field" to "cost-mode/cost-type"; 3853 o If an element of a JSON array has an invalid value, the server 3854 sets "value" to the value of the invalid element, as a string, and 3855 "field" to the name of the array. An array element of the wrong 3856 type (e.g., a number in what is supposed to be an array of 3857 strings) is an invalid value error, not an invalid type error. 3858 The server sets "value" to the string version of the incorrect 3859 element, and "field" to the name of the array. 3861 Appendix D. Authors 3863 [[CmtAuthors: RFC Editor: Please move information in this section to 3864 the Authors' Addresses section at publication time.]] 3866 Sebastian Kiesel 3867 University of Stuttgart Computing Center 3868 Networks and Communication Systems Department 3869 Allmandring 30 3870 70550 Stuttgart 3871 Germany 3873 Email: ietf-alto@skiesel.de 3875 Stefano Previdi 3876 Cisco 3878 Email: sprevidi@cisco.com 3880 Wendy Roome 3881 Alcatel Lucent 3883 Email: w.roome@alcatel-lucent.com 3885 Stanislav Shalunov 3886 BitTorrent 3888 Email: shalunov@bittorrent.com 3889 Richard Woundy 3890 Comcast 3892 Richard_Woundy@cable.comcast.com 3894 Authors' Addresses 3896 Richard Alimi (editor) 3897 Google 3898 1600 Amphitheatre Parkway 3899 Mountain View CA 3900 USA 3902 Email: ralimi@google.com 3904 Reinaldo Penno (editor) 3905 Cisco Systems 3906 170 West Tasman Dr 3907 San Jose CA 3908 USA 3910 Email: repenno@cisco.com 3912 Y. Richard Yang (editor) 3913 Yale University 3914 51 Prospect St 3915 New Haven CT 3916 USA 3918 Email: yry@cs.yale.edu