idnits 2.17.1 draft-ietf-alto-unified-props-new-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC7285]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 3 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1120 has weird spacing: '...rtyName prop...' == Line 1299 has weird spacing: '...country stat...' == Line 1360 has weird spacing: '...axresbw per...' == Line 2222 has weird spacing: '...esource doma...' -- The document date (March 9, 2020) is 1506 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'TBD' is mentioned on line 1756, but not defined ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Downref: Normative reference to an Informational RFC: RFC 7921 == Outdated reference: A later version (-25) exists of draft-ietf-alto-path-vector-09 Summary: 4 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ALTO WG W. Roome 3 Internet-Draft S. Randriamasy 4 Intended status: Standards Track Nokia Bell Labs 5 Expires: September 10, 2020 Y. Yang 6 Yale University 7 J. Zhang 8 Tongji University 9 K. Gao 10 Sichuan University 11 March 9, 2020 13 Unified Properties for the ALTO Protocol 14 draft-ietf-alto-unified-props-new-11 16 Abstract 18 This document extends the Application-Layer Traffic Optimization 19 (ALTO) Protocol [RFC7285] by generalizing the concept of "endpoint 20 properties" to generic types of entities, and by presenting those 21 properties as maps, similar to the network and cost maps in 22 [RFC7285]. 24 Requirements Language 26 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 27 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 28 document are to be interpreted as described in RFC 2119 [RFC2119]. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on September 10, 2020. 47 Copyright Notice 49 Copyright (c) 2020 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 65 2. Basic Features of the Unified Property Extension . . . . . . 6 66 2.1. Entity . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 2.2. Entity Domain . . . . . . . . . . . . . . . . . . . . . . 7 68 2.3. Entity Property . . . . . . . . . . . . . . . . . . . . . 7 69 2.4. New information resource and media type: ALTO Property 70 Map . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 3. Advanced Features of the Unified Property Extension . . . . . 8 72 3.1. Entity Identifier and Entity Domain . . . . . . . . . . . 8 73 3.2. Resource-Specific Entity Domain Name . . . . . . . . . . 8 74 3.3. Resource-Specific Entity Property . . . . . . . . . . . . 9 75 3.4. Entity Hierarchy and Property Inheritance . . . . . . . . 10 76 3.5. Applicable Entity Domains and Properties in the Property 77 Map Capabilities . . . . . . . . . . . . . . . . . . . . 11 78 3.6. Connection between Resource-Specific Entity Domain/Entity 79 Property Mapping and Information Resources . . . . . . . 11 80 4. Protocol Specification: Basic Data Type . . . . . . . . . . . 12 81 4.1. Entity Domain . . . . . . . . . . . . . . . . . . . . . . 12 82 4.1.1. Entity Domain Type . . . . . . . . . . . . . . . . . 12 83 4.1.2. Entity Domain Name . . . . . . . . . . . . . . . . . 12 84 4.1.3. Entity Identifier . . . . . . . . . . . . . . . . . . 13 85 4.1.4. Hierarchy and Inheritance . . . . . . . . . . . . . . 14 86 4.2. Entity Property . . . . . . . . . . . . . . . . . . . . . 14 87 4.2.1. Entity Property Type . . . . . . . . . . . . . . . . 14 88 4.2.2. Entity Property Name . . . . . . . . . . . . . . . . 15 89 5. Entity Domain Types . . . . . . . . . . . . . . . . . . . . . 15 90 5.1. Internet Address Domain Types . . . . . . . . . . . . . . 16 91 5.1.1. IPv4 Domain . . . . . . . . . . . . . . . . . . . . . 16 92 5.1.2. IPv6 Domain . . . . . . . . . . . . . . . . . . . . . 16 93 5.1.3. Hierarchy and Inheritance of Internet Address Domains 17 94 5.2. PID Domain . . . . . . . . . . . . . . . . . . . . . . . 18 95 5.2.1. Entity Domain Type . . . . . . . . . . . . . . . . . 18 96 5.2.2. Domain-Specific Entity Identifiers . . . . . . . . . 18 97 5.2.3. Hierarchy and Inheritance . . . . . . . . . . . . . . 18 98 5.2.4. Relationship To Internet Addresses Domains . . . . . 18 99 5.3. Internet Address Properties vs. PID Properties . . . . . 19 100 6. Entity Domains and Property Mappings in Information Resources 19 101 6.1. Information Resource Export . . . . . . . . . . . . . . . 19 102 6.1.1. Resource-Specific Entity Domain Export . . . . . . . 19 103 6.1.2. Entity Property Mapping Export . . . . . . . . . . . 20 104 6.2. Network Map Resource . . . . . . . . . . . . . . . . . . 20 105 6.2.1. Resource-Specific Entity Domain . . . . . . . . . . . 20 106 6.2.2. Entity Property Mapping . . . . . . . . . . . . . . . 20 107 6.3. Endpoint Property Resource . . . . . . . . . . . . . . . 21 108 6.3.1. Resource-Specific Entity Domain . . . . . . . . . . . 21 109 6.3.2. Entity Property Mapping . . . . . . . . . . . . . . . 21 110 6.4. Property Map Resource . . . . . . . . . . . . . . . . . . 21 111 7. Property Map . . . . . . . . . . . . . . . . . . . . . . . . 21 112 7.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 22 113 7.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 22 114 7.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 22 115 7.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . 22 116 7.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 22 117 7.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 22 118 8. Filtered Property Map . . . . . . . . . . . . . . . . . . . . 24 119 8.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 24 120 8.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 24 121 8.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 24 122 8.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . 25 123 8.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 25 124 8.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 25 125 9. Impact on Legacy ALTO Servers and ALTO Clients . . . . . . . 27 126 9.1. Impact on Endpoint Property Service . . . . . . . . . . . 27 127 9.2. Impact on Resource-Specific Properties . . . . . . . . . 27 128 9.3. Impact on Other Properties . . . . . . . . . . . . . . . 27 129 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 27 130 10.1. Network Map . . . . . . . . . . . . . . . . . . . . . . 27 131 10.2. Property Definitions . . . . . . . . . . . . . . . . . . 28 132 10.3. Properties for Abstract Network Elements . . . . . . . . 29 133 10.4. Information Resource Directory (IRD) . . . . . . . . . . 29 134 10.5. Property Map Example . . . . . . . . . . . . . . . . . . 32 135 10.6. Filtered Property Map Example #1 . . . . . . . . . . . . 33 136 10.7. Filtered Property Map Example #2 . . . . . . . . . . . . 34 137 10.8. Filtered Property Map Example #3 . . . . . . . . . . . . 35 138 10.9. Filtered Property Map Example #4 . . . . . . . . . . . . 37 139 10.10. Property Map in Path Vector Example #1 . . . . . . . . . 37 140 11. Security Considerations . . . . . . . . . . . . . . . . . . . 39 141 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 142 12.1. application/alto-* Media Types . . . . . . . . . . . . . 40 143 12.2. ALTO Entity Domain Type Registry . . . . . . . . . . . . 41 144 12.2.1. Consistency Procedure between ALTO Address Type 145 Registry and ALTO Entity Domain Type Registry . . . 42 146 12.2.2. ALTO Entity Domain Type Registration Process . . . . 43 147 12.3. ALTO Entity Property Type Registry . . . . . . . . . . . 44 148 12.4. ALTO Resource-Specific Entity Domain Registries . . . . 45 149 12.4.1. Network Map . . . . . . . . . . . . . . . . . . . . 45 150 12.4.2. Endpoint Property . . . . . . . . . . . . . . . . . 45 151 12.5. ALTO Resource Entity Property Mapping Registries . . . . 46 152 12.5.1. Network Map . . . . . . . . . . . . . . . . . . . . 46 153 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46 154 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 46 155 14.1. Normative References . . . . . . . . . . . . . . . . . . 46 156 14.2. Informative References . . . . . . . . . . . . . . . . . 48 157 Appendix A. Scope of Property Map . . . . . . . . . . . . . . . 48 158 A.1. Example Property Map . . . . . . . . . . . . . . . . . . 49 159 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 161 1. Introduction 163 The ALTO protocol [RFC7285] introduces the concept of "properties" 164 attached to "endpoint addresses", and defines the Endpoint Property 165 Service (EPS) to allow ALTO clients to retrieve those properties. 166 While useful, the EPS, as defined in [RFC7285], has at least three 167 limitations. 169 First, the EPS allows properties to be associated with only endpoints 170 which are identified by individual communication addresses like IPv4 171 and IPv6 addresses. It is reasonable to think that collections of 172 endpoints, as defined by CIDRs [RFC4632] or PIDs, may also have 173 properties. Furthermore, recent ALTO use cases show that properties 174 of network flows [RFC7011] and routing elements [RFC7921] are also 175 very useful. Since the EPS cannot be extended to those generic 176 entities, new services, with new request and response messages, would 177 have to be defined for them. 179 Second, the EPS only allows endpoints identified by global 180 communication addresses. However, an endpoint address may be a local 181 IP address or an anycast IP address which is also not globally 182 unique. Additionally, a generic entity such as a PID may have an 183 identifier that is not globally unique. For example, a PID 184 identifier may be used in multiple network maps, where in each 185 network map, this PID identifier points to a different set of 186 addresses. 188 Third, the EPS is only defined as a POST-mode service. Clients must 189 request the properties for an explicit set of endpoint addresses. By 190 contrast, [RFC7285] defines a GET-mode cost map resource which 191 returns all available costs, so a client can get a full set of costs 192 once, and then process cost lookups without querying the ALTO server. 193 [RFC7285] does not define a similar service for endpoint properties. 194 At first, a map of endpoint properties might seem impractical, 195 because it could require enumerating the property value for every 196 possible endpoint. However, in practice, it is highly unlikely that 197 properties will be defined for every endpoint address. It is much 198 more likely that properties may be defined for only a subset of 199 endpoint addresses, and the specification of properties uses an 200 aggregation representation to allow enumeration. This is 201 particularly true if blocks of endpoint addresses with a common 202 prefix (e.g., a CIDR) have the same value for a property. Entities 203 in other domains may very well allow aggregated representation and 204 hence be enumerable as well. 206 To address the three limitations, this document specifies a protocol 207 extension for defining and retrieving ALTO properties: 209 o The first limitation is addressed by introducing a generic concept 210 called ALTO Entity, which generalizes an endpoint and may 211 represent a PID, a network element, a cell in a cellular network, 212 an abstracted network element as defined in [REF path-vector], or 213 other physical or logical objects used by ALTO. Each entity is 214 included in a collection called an ALTO Entity Domain. Since each 215 ALTO Entity Domain includes only one type of entities, each Entity 216 Domain can be classified by the type of entities in it. 218 o The second limitation is addressed by using resource-specific 219 entity domains. A resource-specific entity domain contains 220 entities that are defined and identified with respect to a given 221 ALTO information resource, which provides scoping. For example, 222 an entity domain containing PIDs is identified with respect to the 223 network map in which these PIDs are defined. Likewise an entity 224 domain containing local IP addresses may be defined with respect 225 to a local network map. 227 o The third limitation is addressed by defining two new types of 228 ALTO information resources: Property Map, detailed in Section 7 229 and Filtered Property Map, detailed in Section 8. The former is a 230 GET-mode resource that returns the property values for all 231 entities in one or more entity domains, and is analogous to a 232 network map or a cost map in [RFC7285]. The latter is a POST-mode 233 resource that returns the values for a set of properties and 234 entities requested by the client, and is analogous to a filtered 235 network map or a filtered cost map. 237 The protocol extension defined in this document is extensible. New 238 entity domain types can be defined without revising the specification 239 defined in this document. Similarly, new cost metrics and new 240 endpoint properties can be defined in other documents without 241 revising the protocol specification defined in [RFC7285]. 243 This document subsumes the Endpoint Property Service defined in 244 [RFC7285], although that service may be retained for legacy clients 245 (see Section 9). 247 2. Basic Features of the Unified Property Extension 249 The purpose of this extension is to convey properties on objects that 250 extend ALTO Endpoints and are called ALTO Entities, entities for 251 short. This section introduces the basic features involved in ALTO 252 Property Maps. 254 2.1. Entity 256 The concept of an ALTO Entity generalizes the concept of an ALTO 257 Endpoint defined in Section 2.1 of [RFC7285]. An entity is an object 258 that can be an endpoint that is defined by its network address, but 259 can also be an object that has a defined mapping to a set of one or 260 more network addresses or an object that is not even related to any 261 network address. Thus, where as all endpoints are entities, not all 262 entities are endpoints. 264 Examples of entities are: 266 o an ALTO endpoint, defined in [RFC7285], that represents an 267 application or a host identified by a communication address (e.g., 268 an IPv4 or IPv6 address) in a network. 270 o a PID, defined in [RFC7285], that has a provider defined human- 271 readable abstract identifier specified by an ALTO network map, 272 which maps a PID to a set of ipv4 and ipv6 addresses; 274 o an autonomous system (AS), that has an AS number (ASN) as its 275 identifier and maps to a set of ipv4 and ipv6 addresses; 277 o a country, identified by its country code defined by ISO 3166, to 278 which applications such as CDN providers associate properties and 279 capabilities; 281 o a TCP/IP network flow, that is identified by a TCP/IP 5-Tuple 282 specifying its source and destination addresses and port numbers 283 and the utilized protocol; 285 o a routing element, that is specified in [RFC7921] and is 286 associated with routing capabilities information; 288 o an abstract network element, that represents an abstraction of a 289 network part such as a routable network node, one or more link, a 290 network domain or their aggregation. 292 2.2. Entity Domain 294 An entity domain defines a set of entities of the same type. This 295 type, also called entity domain type, defines the semantics of a type 296 of entity. Entity domain types could be defined in different 297 documents. For example: the present document defines entity domain 298 types "ipv4", "ipv6" and "pid" in sections Section 5.1 and 299 Section 5.2; the entity domain type "ane", that defines Abstract 300 Network Elements (ANEs), is introduced in 301 [I-D.ietf-alto-path-vector]. 303 An entity domain also has a name. The name and type of an entity 304 domain can be the same. This is the case for the abovementionned 305 types "ipv4", "ipv6" and "pid". The name of an entity domain may 306 however be different from its type, in particular when the identifier 307 of its entities cannot be recognized outside this domain. For 308 example: an entity "mypid10" of domain type "pid" is only recognized 309 with respect to a given network map resource and may be undefined in 310 other network maps, or may even map to a different set of addresses. 311 This document addresses this case in Section 3.2 and related. 313 2.3. Entity Property 315 An entity property defines a property of an entity. It is similar to 316 the endpoint property defined by Section 7.1 of [RFC7285]. It can 317 convey either network-aware or network-agnostic information. 319 For example: 321 o an entity in the "ipv4" domain may have a property whose value is 322 an Autonomous System (AS) number indicating the AS that owns this 323 IPv4 address, 325 o an entity in the "pid" domain may have a property that indicates 326 the central geographical location of endpoints it includes. 328 It should be noted that some objects may be both entities and 329 properties. For example, a PID may be both a property of an "ipv4" 330 entity and an entity on which a Client may query properties such as 331 geographical location. 333 2.4. New information resource and media type: ALTO Property Map 335 This document introduces a new ALTO information resource named 336 Property Map. An ALTO property map provides a set of properties on a 337 set of entities. These entities may be of different types. For 338 example, an ALTO property map may define the ASN property for both 339 "ipv4" and "ipv6" type of entities. 341 The present extension also introduces a new media type. 343 This document uses the same definition of the information resource as 344 defined by [RFC7285]. Each information resource usually has a JSON 345 format representation following a specific schema defined by its 346 media type. In the present case, an ALTO property map resource is 347 represented by a JSON object of type InfoResourcePropertyMap and 348 defined by the media type "application/alto-propmap+json". 350 A Property Map can be queried as a GET-mode resource, thus conveying 351 values of all properties on all entities indicated in its 352 capabilities. It can also be queried as a POST-mode resource, thus 353 conveying a selection of properties on a selection of entities. 355 3. Advanced Features of the Unified Property Extension 357 3.1. Entity Identifier and Entity Domain 359 In [RFC7285], an endpoint has an identifier explicitly associated 360 with the "ipv4" or "ipv6" address domain. Examples are 361 "ipv4:192.0.2.14" and "ipv6:2001:db8::12". In this extension, an 362 entity domain characterizes the type semantics and identifier format 363 of its entities. And the identifier of an entity is explicitly 364 associated with its entity domain. For instance: an entity that is 365 an endpoint with an IPv4 address will have an identifier associated 366 with the "ipv4" domain, like "ipv4:192.0.2.14"; an entity which is a 367 PID will have an identifier associated with a "pid" domain, like 368 "pid:mypid10". 370 In this document, an entity must be owned by exactly one entity 371 domain. And an entity identifier must point to exactly one entity. 372 Even if two entities in two different entity domains refer to the 373 same physical or logical object, they are treated as different 374 entities. For example, an IPv4 and IPv6 address. 376 3.2. Resource-Specific Entity Domain Name 378 Some entities are defined and identified in a unique and global way. 379 This is the case for instance for entities that are endpoints 380 identified by a routable IPv4 or IPv6 address. The entity domain for 381 such entities can be globally defined and named "ipv4" or "ipv6". 382 Those entity domains are also called resource-agnostic entity domains 383 in this document, as they are not associated to any specific ALTO 384 information resources. 386 Some other entities and entity types are only defined relatively to a 387 given information resource. This is the case for entities of domain 388 "pid", that can only be understood with respect to the network map 389 where they are defined. For example, a PID named "mypid10" may be 390 defined to represent a set S1 of IP addresses in an information 391 resource of type Network Map and named "netmap1". Another Network 392 Map "netmap2" may use the same name "mypid10" and define it to 393 represent another set S2 of IP addresses. The identifier 394 "pid:mypid10" may thus point to different objects because the 395 information on the originating information resource is lost. The 396 reason is that "pid" denotes an entity domain type rather than an 397 unambiguous identifier. 399 To solve this ambiguity, the present extension introduces the concept 400 of resources-specific entity domain. This concept applies to domains 401 where entities are defined relatively to a given information 402 resource. It can also apply to domains of entities that are defined 403 locally, such as local networks of objects identified with a local 404 IPv4 address. 406 In such cases, an entity domain name is explicitly associated with an 407 identifier of the information resource where these entities are 408 defined. Using a resource-specific entity domain name, an ALTO 409 Property Map may unambiguously indicate entity domains of the same 410 type, on which entity properties may be queried. Example resource- 411 specific entity domain names may look like: "netmap1.pid" or 412 "netmap2.pid". This allows to identify two distinct PID entities 413 such as "netmap1.pid:mypid10" or "netmap2.pid:mypid10". Resource- 414 specific entity domain name will be specified in Section 4.1.2. 416 3.3. Resource-Specific Entity Property 418 An entity may have properties of same type, whose values are 419 associated to different information resources. For instance, entity 420 "192.0.2.34" defined in the "ipv4" domain may have two "pid" 421 properties defined in two different network maps "netmap1" and 422 "netmap2". These properties will likely have different values in 423 "netmap1" and "netmap2". To distinguish between them, this document 424 uses the same approach proposed as in Section 10.8.1 of [RFC7285], 425 which is called "Resource-Specific Entity Property". When a property 426 value depends on a given information resource, the identifier of the 427 property must be explicitly associated with the information resource 428 that defines it. 430 For example, the property "pid" queried on entity "ipv4:192.0.2.34" 431 and defined in both "netmap1" and "netmap2", may be named 432 "netmap1.pid" and "netmap2.pid". This allows a Client to get a 433 property of the same type but defined in different information 434 resources in a single query. Specifications are provided in 435 Section 4.2. 437 3.4. Entity Hierarchy and Property Inheritance 439 Enumerating all individual entities is inefficient for both the 440 Client and the Server. 442 o For the Client, even if it only wants to request properties for a 443 "/24" ipv4 subnet, using the individual ipv4 entity, it has to 444 enumerate all 256 entities. 446 o For the Server, in some cases, most of the entities may have the 447 same properties. Simply enumerating all of them may introduce a 448 lot of reduncency in the payload. For example, all the individual 449 ipv4 entities in a "/24" ipv4 subnet is usually owned by the same 450 AS. When a Client requests the ASN property for this ipv4 subnet, 451 using the individual ipv4 address, the Server has to repeat the 452 same ASN property for 256 times in the worst case. 454 To reduce the size of the property map request and response payloads, 455 this document introduces, when appicable, an approach called 456 "Property Inheritance". This approach consists of two parts: Entity 457 Hierarchy and Property Inheritance. 459 o Entity Hierarchy: This approach allows an entity domain to support 460 using a single identifier to identify a set of indivudial 461 entities. For example, a CIDR can be used to identify a set of 462 ipv4 or ipv6 entities. Such an identifier is called a 463 hierarchical entity identifier, as the set identified by it can be 464 hierarachical. For example, the CIDR "ipv4:192.0.1.0/24" covers 465 all the individual ipv4 entities identified the CIDR 466 "ipv4:192.0.1.0/26". 468 o Property Inheritance: This approach allows a property map to 469 define a property for a hierarchical entity identifier. An 470 undefined property of an entity may inherit the value of the 471 property defined for a hierarchical entity identifier. For 472 example, a property map only defines the ASN property for a 473 hierarchical ipv4 entity identifier "ipv4:192.0.1.0/24". When 474 receiving this property map, a Client could infer that the ipv4 475 entity "ipv4:192.0.1.1" inherits the same ASN property even if it 476 does not appear in the property map. 478 The detailed specification will be specified in Section 4.1.4. 480 3.5. Applicable Entity Domains and Properties in the Property Map 481 Capabilities 483 A property is not necessarily applicable to any domain, or an ALTO 484 Server may just not support it for all applicable domains. For 485 instance, a property reflecting link bandwidth is likely not defined 486 on entities of a domain of type "country-code". Therefore an ALTO 487 server supporting Property Maps specifies the properties that can be 488 queried on the different domains defined in this server. 490 In Section 6 and related, this document explains how the IRD 491 capabilities of a Property Map unambiguously expose what type of 492 properties on what entity domains a Client can query. For short, a 493 field called "mapping" enumerates the entity domains supported by the 494 Property Map; For each entity domain, a list of applicable properties 495 is provided. An example can be found in Section 10.4. Using 496 resource-agnostic or resource-specific entity domains and properties 497 allows to formulate compact and unambiguous entity property queries 498 relating to one or more information resources, in particular: 500 o avoid a Client to query a property on entity domains on which P is 501 not defined, 503 o query for en entity E property values defined in different 504 information resources, 506 o query a property P on entities E defined in different information 507 resources. 509 Specifications will be provided in Section 7.4. 511 3.6. Connection between Resource-Specific Entity Domain/Entity Property 512 Mapping and Information Resources 514 Although the IRD capabilities of a Property Map can expose the 515 supported mappings in this property map, it may still not be clear to 516 a Client what a resource-specific entity domain is, and what an 517 applicable resource-specific entity property means, as those concepts 518 are not defined in other ALTO information resources. For example, a 519 Client should understand that: 521 o a local IPv4 entity domain "netmap1.ipv4" includes the IPv4 522 addresses appearing in the "ipv4" field of the endpoint address 523 group of each PID in the network map "netmap1"; 525 o a "netmap1.pid" property of an IPv4 entity "ipv4:192.0.1.1" 526 indicates the PID defined by the network map "netmap1" and 527 including the IPv4 address "ipv4:192.0.1.1" in its endpoint 528 address group. 530 To help the client understanding these connections, this document 531 requests two new IANA registries for each information resource to 532 define the connection to each supported resource-specific entity 533 domain and entity property mapping respectively. Such a connection 534 is called "Information Resource Export", to explain what is an 535 resource-specific entity domain or an entity property mapping 536 exported by an information resource. Examples of "Information 537 Resource Exports" of existing ALTO information resources are provided 538 in Section 6. Specifications are provided in Section 6.1. The 539 details of these new IANA registries are provided in Section 12.4 and 540 Section 12.5. 542 4. Protocol Specification: Basic Data Type 544 4.1. Entity Domain 546 4.1.1. Entity Domain Type 548 An entity domain has a type, which is defined by a string that MUST 549 be no more than 64 characters, and MUST NOT contain characters other 550 than US-ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, 551 and U+0061-U+007A), hyphen ("-", U+002D), and low line ("_", U+005F). 552 For example, the strings "ipv4", "ipv6", and "pid" are valid entity 553 domain types. 555 The type EntityDomainType is used in this document to denote a JSON 556 string confirming to the preceding requirement. 558 An entity domain type defines the semantics of a type of entity 559 domains. Each entity domain type MUST be registered with the IANA. 560 The format of the entity identifiers (see Section 4.1.3) in that type 561 of entity domains, as well as any hierarchical or inheritance rules 562 (see Section 4.1.4) for those entities, MUST be specified at the same 563 time. 565 4.1.2. Entity Domain Name 567 Each entity domain is identified by an entity domain name, a string 568 of the following format: 570 EntityDomainName ::= [ [ ResourceID ] '.' ] EntityDomainType 571 This document distinguishes three types of entity domains: resource- 572 specific entity domains, self-defined entity domains, and resource- 573 agnostic entity domains. Their entity domain names are derived as 574 follows. 576 Each ALTO information resource MAY define a resource-specific entity 577 domain (which could be empty) in a given entity domain type. A 578 resource-specific entity domain is identified by an entity domain 579 name derived as follows. It MUST start with a resource ID using the 580 ResourceID type defined in [RFC7285], followed by the "." separator 581 (U+002E), followed by an EntityDomainType typed string. For example, 582 if an ALTO server provides two network maps "netmap-1" and "netmap- 583 2", they can define two different "pid" domains identified by 584 "netmap-1.pid" and "netmap-2.pid" respectively. To be simplified, in 585 the scope of a specific information resource, the resource-specific 586 entity domain defined by itself can be identified by the "." 587 EntityDomainTyep without the ResourceID. 589 When the associated information resource of a resource-specific 590 entity domain is the current information resource itself, this 591 resource-specific entity domain is a self-defined entity domain, and 592 its ResourceID SHOULD be ignored from its entity domain name. 594 Given a set of ALTO information resources, there MAY be a resource- 595 agnostic entity domain in a given entity domain type amongst them. A 596 resource-agnostic entity domain is simply identified by its entity 597 domain type. For example, given two network maps "net-map-1" and 598 "net-map-2", "ipv4" and "ipv6" identify two resource-agnostic 599 Internet address entity domains (see Section 5.1) between them. 601 Note that the "." separator is not allowed in EntityDomainType and 602 hence there is no ambiguity on whether an entity domain name refers 603 to a resource-agnostic entity domain or a resource-specific entity 604 domain. 606 4.1.3. Entity Identifier 608 Entities in an entity domain are identified by entity identifiers 609 (EntityID) of the following format: 611 EntityID ::= EntityDomainName ':' DomainTypeSpecificEntityID 613 Examples from the Internet address entity domains include individual 614 IP addresses such as "net1.ipv4:192.0.2.14" and 615 "net1.ipv6:2001:db8::12", as well as address blocks such as 616 "net1.ipv4:192.0.2.0/26" and "net1.ipv6:2001:db8::1/48". 618 The format of the second part of an entity identifier depends on the 619 entity domain type, and MUST be specified when registering a new 620 entity domain type. Identifiers MAY be hierarchical, and properties 621 MAY be inherited based on that hierarchy. Again, the rules defining 622 any hierarchy or inheritance MUST be defined when the entity domain 623 type is registered. 625 The type EntityID is used in this document to denote a JSON string 626 representing an entity identifier in this format. 628 Note that two entity identifiers with different textual 629 representations may refer to the same entity, for a given entity 630 domain. For example, the strings "net1.ipv6:2001:db8::1" and 631 "net1.ipv6:2001:db8:0:0:0:0:0:1" refer to the same entity in the 632 "ipv6" entity domain. 634 4.1.4. Hierarchy and Inheritance 636 To make the representation efficient, some types of entity domains 637 MAY allow the ALTO client/server to use a hierarchical format entity 638 identifier to represent a block of individual entities. e.g., In an 639 IPv4 domain "net1.ipv4", a cidr "net1.ipv4:192.0.2.0/26" represents 640 64 individual IPv4 entities. In this case, the corresponding 641 property inheritance rule MUST be defined for the entity domain type. 642 The hierarchy and inheritance rule MUST have no ambiguity. 644 4.2. Entity Property 646 Each entity property has a type to indicate the encoding and the 647 semantics of the value of this entity property, and has a name to be 648 identified. One entity MAY have multiple properties in the same 649 type. 651 4.2.1. Entity Property Type 653 The type EntityPropertyType is used in this document to indicate a 654 string denoting an entity property type. The string MUST be no more 655 than 32 characters, and it MUST NOT contain characters other than US- 656 ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and 657 U+0061-U+007A), the hyphen ("-", U+002D), the colon (":", U+003A), or 658 the low line ('_', U+005F). 660 Each entity property type MUST be registered with the IANA. The 661 intended semantics of the entity property type MUST be specified at 662 the same time. 664 To distinguish with the endpoint property type, the entity property 665 type has the following features. 667 o Some entity property types may be applicable to entities in only 668 particular types of entity domains, not all. For example, the 669 "pid" property is not applicable to entities in a "pid" typed 670 entity domain, but is applicable to entities in the "ipv4" or 671 "ipv6" domains. 673 o The intended semantics of the value of an entity property may also 674 depend on the entity domain type of this entity. For example, 675 suppose that the "geo-location" property is defined as the 676 coordinates of a point, encoded as (say) "latitude longitude 677 [altitude]." When applied to an entity that represents a specific 678 host computer, identified by an address in the "ipv4" or "ipv6" 679 entity domain, the property defines the host's location. However, 680 when applied to an entity in a "pid" domain, the property would 681 indicate the location of the center of all hosts in this "pid" 682 entity. 684 4.2.2. Entity Property Name 686 Each entity property is identified by an entity property name, which 687 is a string of the following format: 689 EntityPropertyName ::= [ ResourceID ] '.' EntityPropertyType 691 Similar to the endpoint property type defined in Section 10.8 of 692 [RFC7285], each entity property may be defined by either the property 693 map itself (self-defined) or some other specific information resource 694 (resource-specific). 696 The entity property name of a resource-specific entity property 697 starts with a string of the type ResourceID defined in [RFC7285], 698 followed by the "." separator (U+002E) and a EntityDomainType typed 699 string. For example, the "pid" properties of an "ipv4" entity 700 defined by two different maps "net-map-1" and "net-map-2" are 701 identified by "net-map-1.pid" and "net-map-2.pid" respectively. 703 When the associated information resource of the entity property is 704 the current information resource itself, the ResourceID in the 705 property name SHOULD be ignored. For example, the ".asn" property of 706 an "ipv4" entity indicates the AS number of the AS which this IPv4 707 address is owned by. 709 5. Entity Domain Types 711 This document requires the definition of each entity domain type MUST 712 include (1) the entity domain type name and (2) domain-specific 713 entity identifiers, and MAY include (3) hierarchy and inheritance 714 semantics optionally. This document defines three initial entity 715 domain types as follows. 717 5.1. Internet Address Domain Types 719 The document defines two entity domain types (IPv4 and IPv6) for 720 Internet addresses. Both types are resource-agnostic entity domain 721 types and hence define corresponding resource-agnostic entity domains 722 as well. Since the two domains use the same hierarchy and 723 inheritance semantics, we define the semantics together, instead of 724 repeating for each. 726 5.1.1. IPv4 Domain 728 5.1.1.1. Entity Domain Type 730 ipv4 732 5.1.1.2. Domain-Specific Entity Identifiers 734 Individual addresses are strings as specified by the IPv4Addresses 735 rule of Section 3.2.2 of [RFC3986]; Hierarchical addresses are 736 prefix-match strings as specified in Section 3.1 of [RFC4632]. To 737 define properties, an individual Internet address and the 738 corresponding full-length prefix are considered aliases for the same 739 entity. Thus "ipv4:192.0.2.0" and "ipv4:192.0.2.0/32" are 740 equivalent. 742 5.1.2. IPv6 Domain 744 5.1.2.1. Entity Domain Type 746 ipv6 748 5.1.2.2. Domain-Specific Entity Identifiers 750 Individual addresses are strings as specified by Section 4 of 751 [RFC5952]; Hierarchical addresses are prefix-match strings as 752 specified in Section 7 of [RFC5952]. To define properties, an 753 individual Internet address and the corresponding 128-bit prefix are 754 considered aliases for the same entity. That is, "ipv6:2001:db8::1" 755 and "ipv6:2001:db8::1/128" are equivalent, and have the same set of 756 properties. 758 5.1.3. Hierarchy and Inheritance of Internet Address Domains 760 Both Internet address domains allow property values to be inherited. 761 Specifically, if a property P is not defined for a specific Internet 762 address I, but P is defined for a a hierarchical Internet address C 763 which prefix-matches I, then the address I inherits the value of P 764 defined for the hierarchical address C. If more than one such 765 hierarchical addresses define a value for P, I inherits the value of 766 P in the hierarchical address with the longest prefix. Note that 767 this longest prefix rule ensures no multiple inheritances, and hence 768 no ambiguity. 770 Hierarchical addresses can also inherit properties: if a property P 771 is not defined for the hierarchical address C, but is defined for 772 another hierarchical address C' which covers all IP addresses in C, 773 and C' has a shorter prefix length than C, then C MAY inherits the 774 property from C'. If there are multiple such hierarchical addresses 775 like C', C MUST inherit from the hierarchical address having the 776 longest prefix length. 778 As an example, suppose that a server defines a property P for the 779 following entities: 781 ipv4:192.0.2.0/26: P=v1 782 ipv4:192.0.2.0/28: P=v2 783 ipv4:192.0.2.0/30: P=v3 784 ipv4:192.0.2.0: P=v4 786 Figure 1: Defined Property Values. 788 Then the following entities have the indicated values: 790 ipv4:192.0.2.0: P=v4 791 ipv4:192.0.2.1: P=v3 792 ipv4:192.0.2.16: P=v1 793 ipv4:192.0.2.32: P=v1 794 ipv4:192.0.2.64: (not defined) 795 ipv4:192.0.2.0/32: P=v4 796 ipv4:192.0.2.0/31: P=v3 797 ipv4:192.0.2.0/29: P=v2 798 ipv4:192.0.2.0/27: P=v1 799 ipv4:192.0.2.0/25: (not defined) 801 Figure 2: Inherited Property Values. 803 An ALTO server MAY explicitly indicate a property as not having a 804 value for a particular entity. That is, a server MAY say that 805 property P of entity X is "defined to have no value", instead of 806 "undefined". To indicate "no value", a server MAY perform different 807 behaviours: 809 o If that entity would inherit a value for that property, then the 810 ALTO server MUST return a "null" value for that property. In this 811 case, the ALTO client MUST recognize a "null" value as "no value" 812 and "do not apply the inheritance rules for this property." 814 o If the entity would not inherit a value, then the ALTO server MAY 815 return "null" or just omit the property. In this case, the ALTO 816 client cannot infer the value for this property of this entity 817 from the Inheritance rules. So the client MUST interpret that 818 this property has no value. 820 If the ALTO server does not define any properties for an entity, then 821 the server MAY omit that entity from the response. 823 5.2. PID Domain 825 The PID domain associates property values with the PIDs in a network 826 map. Accordingly, this entity domain always depends on a network 827 map. 829 5.2.1. Entity Domain Type 831 pid 833 5.2.2. Domain-Specific Entity Identifiers 835 The entity identifiers are the PID names of the associated network 836 map. 838 5.2.3. Hierarchy and Inheritance 840 There is no hierarchy or inheritance for properties associated with 841 PIDs. 843 5.2.4. Relationship To Internet Addresses Domains 845 The PID domain and the Internet address domains are completely 846 independent; the properties associated with a PID have no relation to 847 the properties associated with the prefixes or endpoint addresses in 848 that PID. An ALTO server MAY choose to assign some or all properties 849 of a PID to the prefixes in that PID. 851 For example, suppose "PID1" consists of the prefix 852 "ipv4:192.0.2.0/24", and has the property "P" with value "v1". The 853 Internet address entities "ipv4:192.0.2.0" and "ipv4:192.0.2.0/24" in 854 the IPv4 domain MAY have a value for the property "P", and if they 855 do, it is not necessarily "v1". 857 5.3. Internet Address Properties vs. PID Properties 859 Because the Internet address and PID domains are completely separate, 860 the question may arise as to which entity domain is the best for a 861 property. In general, the Internet address domains are RECOMMENDED 862 for properties that are closely related to the Internet address, or 863 are associated with, and inherited through, hierarchical addresses. 865 The PID domain is RECOMMENDED for properties that arise from the 866 definition of the PID, rather than from the Internet address prefixes 867 in that PID. 869 For example, because Internet addresses are allocated to service 870 providers by blocks of prefixes, an "ISP" property would be best 871 associated with the Internet address domain. On the other hand, a 872 property that explains why a PID was formed, or how it relates to a 873 provider's network, would best be associated with the PID domain. 875 6. Entity Domains and Property Mappings in Information Resources 877 6.1. Information Resource Export 879 Each information resource MUST export a set of entity domains and 880 entity property mappings (which can be empty). 882 6.1.1. Resource-Specific Entity Domain Export 884 Each type of information resource MAY export different types of 885 entity domains. For example, a network map resource MUST export a 886 "pid" domain, an "ipv4" domain and an "ipv6" domain (which may be 887 empty); if a facilitated endpoint type "ecgi" and its corresponding 888 entity domain type defined for cellular network addresses are 889 supported in a future ALTO extension, a network map supporting the 890 "ecgi" endpoint type MUST also export an "ecgi" domain. 892 When a new ALTO information resource type is registered, if this type 893 of information resource MAY export an existing type of entity domain, 894 the corresponding document MUST define how to export such type of 895 entity domain from such type of information resource. 897 When a new entity domain type is registered, if an existing type of 898 information resource MAY export an entity domain in this entity 899 domain type, the corresponding document MUST define how to export 900 such type of entity domain from such type of information resource. 902 6.1.2. Entity Property Mapping Export 904 For each entity domain which MAY be exported by an information 905 resource, this information resource MAY also export mappings from 906 this entity domain to some entity property. For example, a network 907 map resource MUST map an "ipv4" entity to its "pid" property; if a 908 facilitated ALTO CDNI FCI information resource including 909 "capabilities with footprint restrictions" [RFC8008] supporting ALTO 910 PIDs as a new footprint type, this information ressource MUST map a 911 "pid" entity to its corresponding "cdni-fci-capabilities" property. 913 When a new ALTO information resource type is registered, if this type 914 of information resource MAY export an entity domain in an existing 915 entity domain type, and map entities in this entity domain to an 916 existing type of entity property, the corresponding document MUST 917 define how to export such type of an entity property. 919 When a new ALTO entity domain type or a new entity property type is 920 defined, if an existing type of resource MAY export an entity domain 921 in this entity domain type, and map entities in this entity domain to 922 this type of entity property, the corresponding document MUST define 923 how to export such type of an entity property. 925 6.2. Network Map Resource 927 The ALTO network map resource defined by the media type "application/ 928 alto-networkmap+json" exports the following types of entity domains 929 and entity property mappings. 931 6.2.1. Resource-Specific Entity Domain 933 An ALTO network map resource defines a "pid" domain, an "ipv4" domain 934 and an "ipv6" domain by follows: 936 o The defined "pid" domain includes all PIDs in keys of the 937 "network-map" object. 939 o The defined "ipv4" domain includes all IPv4 addresses appearing in 940 the "ipv4" field of the endpoint address group of each PID. 942 o The defined "ipv6" domain includes all IPv6 addresses appearing in 943 the "ipv6" field of the endpoint address group of each PID. 945 6.2.2. Entity Property Mapping 947 For each of the preceding entity domains, an ALTO network map 948 resource provides the properties mapping as follows: 950 ipv4 -> pid: An "networkmap" typed resource can map an "ipv4" entity 951 to a "pid" property whose value is a PID defined by this 952 "networkmap" resource and including the IPv4 address of this 953 entity. 955 ipv6 -> pid: An "networkmap" typed resource can map an "ipv6" entity 956 to a "pid" property whose value is a PID defined by this 957 "networkmap" resource and including the IPv6 address of this 958 entity. 960 6.3. Endpoint Property Resource 962 The ALTO endpoint property resource defined by the media type 963 "application/alto-endpointprop+json" exports the following types of 964 entity domains and entity property mappings. 966 6.3.1. Resource-Specific Entity Domain 968 An ALTO endpoint property resource defined an "ipv4" domain and an 969 "ipv6" domain by follows: 971 o The defined "ipv4" domain includes all IPv4 addresses appearing in 972 keys of the "endpoint-properties" object. 974 o The defined "ipv6" domain includes all IPv6 addresses appearing in 975 keys of the "endpoint-properties" object. 977 6.3.2. Entity Property Mapping 979 For each of the preceding entity domains, an ALTO endpoint property 980 resource exports the properties mapping from it to each supported 981 global endpoint property. The property value is the corresponding 982 global endpoint property value in the "endpiont-properties" object. 984 6.4. Property Map Resource 986 To avoid the nested reference and its potential complexity, this 987 document does not specify the export rule of resource-specific entity 988 domain and entity property mapping for the ALTO property map resource 989 defined by the media type "application/alto-propmap+json" (see 990 Section 7.1). 992 7. Property Map 994 A property map returns the properties defined for all entities in one 995 or more domains, e.g., the "location" property of entities in "pid" 996 domain, and the "ASN" property of entities in "ipv4" and "ipv6" 997 domains. 999 Section 10.5 gives an example of a property map request and its 1000 response. 1002 7.1. Media Type 1004 The media type of a property map is "application/alto-propmap+json". 1006 7.2. HTTP Method 1008 The property map is requested using the HTTP GET method. 1010 7.3. Accept Input Parameters 1012 None. 1014 7.4. Capabilities 1016 The capabilities are defined by an object of type 1017 PropertyMapCapabilities: 1019 object { 1020 EntityPropertyMapping mappings; 1021 } PropertyMapCapabilities; 1023 object-map { 1024 EntityDomainName -> EntityPropertyName<1..*>; 1025 } EntityPropertyMapping 1027 with fields: 1029 mappings: A JSON object whose keys are names of entity domains and 1030 values are the supported entity properties of the corresponding 1031 entity domains. 1033 7.5. Uses 1035 The "uses" field of a property map resource in an IRD entry specifies 1036 dependent resources of this property map. It is an array of the 1037 resource ID(s) of the resource(s). 1039 7.6. Response 1041 If the entity domains in this property map depend on other resources, 1042 the "dependent-vtags" field in the "meta" field of the response MUST 1043 be an array that includes the version tags of those resources, and 1044 the order MUST be consistent with the "uses" field of this property 1045 map resource. The data component of a property map response is named 1046 "property-map", which is a JSON object of type PropertyMapData, 1047 where: 1049 object { 1050 PropertyMapData property-map; 1051 } InfoResourceProperties : ResponseEntityBase; 1053 object-map { 1054 EntityID -> EntityProps; 1055 } PropertyMapData; 1057 object { 1058 EntityPropertyName -> JSONValue; 1059 } EntityProps; 1061 The ResponseEntityBase type is defined in Section 8.4 of [RFC7285]. 1063 Specifically, a PropertyMapData object has one member for each entity 1064 in the property map. The entity's properties are encoded in the 1065 corresponding EntityProps object. EntityProps encodes one name/value 1066 pair for each property, where the property names are encoded as 1067 strings of type PropertyName. A protocol implementation SHOULD 1068 assume that the property value is either a JSONString or a JSON 1069 "null" value, and fail to parse if it is not, unless the 1070 implementation is using an extension to this document that indicates 1071 when and how property values of other data types are signaled. 1073 For each entity in the property map: 1075 o If the entity is in a resource-specific entity domain, the ALTO 1076 server SHOULD only return self-defined properties and resource- 1077 specific properties which depend on the same resource as the 1078 entity does. The ALTO client SHOULD ignore the resource-specific 1079 property in this entity if their mapping is not registered in the 1080 ALTO Resource Entity Property Transfer Registry of the type of the 1081 corresponding resource. 1083 o If the entity is in a shared entity domain, the ALTO server SHOULD 1084 return self-defined properties and all resource-specific 1085 properties defined for all resource-specific entities which have 1086 the same domain-specific entity identifier as this entity does. 1088 For efficiency, the ALTO server SHOULD omit property values that are 1089 inherited rather than explicitly defined; if a client needs inherited 1090 values, the client SHOULD use the entity domain's inheritance rules 1091 to deduce those values. 1093 8. Filtered Property Map 1095 A filtered property map returns the values of a set of properties for 1096 a set of entities selected by the client. 1098 Section 10.6, Section 10.7, Section 10.8 and Section 10.9 give 1099 examples of filtered property map requests and responses. 1101 8.1. Media Type 1103 The media type of a property map resource is "application/alto- 1104 propmap+json". 1106 8.2. HTTP Method 1108 The filtered property map is requested using the HTTP POST method. 1110 8.3. Accept Input Parameters 1112 The input parameters for a filtered property map request are supplied 1113 in the entity body of the POST request. This document specifies the 1114 input parameters with a data format indicated by the media type 1115 "application/alto-propmapparams+json", which is a JSON object of type 1116 ReqFilteredPropertyMap: 1118 object { 1119 EntityID entities<1..*>; 1120 EntityPropertyName properties<1..*>; 1121 } ReqFilteredPropertyMap; 1123 with fields: 1125 entities: List of entity identifiers for which the specified 1126 properties are to be returned. The ALTO server MUST interpret 1127 entries appearing multiple times as if they appeared only once. 1128 The domain of each entity MUST be included in the list of entity 1129 domains in this resource's "capabilities" field (see Section 8.4). 1131 properties: List of properties to be returned for each entity. Each 1132 specified property MUST be included in the list of properties in 1133 this resource's "capabilities" field (see Section 8.4). The ALTO 1134 server MUST interpret entries appearing multiple times as if they 1135 appeared only once. 1137 Note that the "entities" and "properties" fields MUST have at 1138 least one entry each. 1140 8.4. Capabilities 1142 The capabilities are defined by an object of type 1143 PropertyMapCapabilities, as defined in Section 7.4. 1145 8.5. Uses 1147 Same to the "uses" field of the Property Map resource (see 1148 Section 7.5). 1150 8.6. Response 1152 The response MUST indicate an error, using ALTO protocol error 1153 handling, as defined in Section 8.5 of [RFC7285], if the request is 1154 invalid. 1156 Specifically, a filtered property map request can be invalid as 1157 follows: 1159 o An entity identifier in "entities" in the request is invalid if: 1161 * The domain of this entity is not defined in the "entity- 1162 domains" capability of this resource in the IRD; 1164 * The entity identifier is an invalid identifier in the entity 1165 domain. 1167 A valid entity identifier is never an error, even if this filtered 1168 property map resource does not define any properties for it. 1170 If an entity identifier in "entities" in the request is invalid, 1171 the ALTO server MUST return an "E_INVALID_FIELD_VALUE" error 1172 defined in Section 8.5.2 of [RFC7285], and the "value" field of 1173 the error message SHOULD indicate this entity identifier. 1175 o A property name in "properties" in the request is invalid if this 1176 property name is not defined in the "properties" capability of 1177 this resource in the IRD. 1179 It is not an error that a filtered property map resource does not 1180 define a requested property's value for a particular entity. In 1181 this case, the ALTO server MUST omit that property from the 1182 response for that endpoint. 1184 If a property name in "properties" in the request is invalid, the 1185 ALTO server MUST return an "E_INVALID_FIELD_VALUE" error defined 1186 in Section 8.5.2 of [RFC7285]. The "value" field of the error 1187 message SHOULD indicate the property name. 1189 The response to a valid request is the same as for the Property Map 1190 (see Section 7.6), except that: 1192 o If the requested entities include entities in the shared entity 1193 domain, the "dependent-vtags" field in its "meta" field MUST 1194 include version tags of all dependent resources appearing in the 1195 "uses" field. 1197 o If the requested entities only include entities in resource- 1198 specific entity domains, the "dependent-vtags" field in its "meta" 1199 field MUST include version tags of resources which requested 1200 resource-specific entity domains and requested resource-specific 1201 properties are dependent on. 1203 o The response only includes the entities and properties requested 1204 by the client. If an entity in the request is identified by a 1205 hierarchical identifier (e.g., a "ipv4" or "ipv6" prefix), the 1206 response MUST cover properties for all identifiers in this 1207 hierarchical identifier. 1209 It is important that the filtered property map response MUST include 1210 all inherited property values for the requested entities and all the 1211 entities which are able to inherit property values from them. To 1212 achieve this goal, the ALTO server MAY follow three rules: 1214 o If a property for a requested entity is inherited from another 1215 entity not included in the request, the response SHOULD include 1216 this property for the requested entity. For example, A full 1217 property map may skip a property P for an entity A (e.g., 1218 ipv4:192.0.2.0/31) if P can be derived using inheritance from 1219 another entity B (e.g., ipv4:192.0.2.0/30). A filtered property 1220 map request may include only A but not B. In such a case, the 1221 property P SHOULD be included in the response for A. 1223 o If there are entities covered by a requested entity but having 1224 different values for the requested properties, the response SHOULD 1225 include all those entities and the different property values for 1226 them. For example, considering a request for property P of entity 1227 A (e.g., ipv4:192.0.2.0/31), if P has value v1 for 1228 A1=ipv4:192.0.2.0/32 and v2 for A2=ipv4:192.0.2.1/32, then, the 1229 response SHOULD include A1 and A2. 1231 o If an entity in the response is already covered by some other 1232 entities in the same response, it SHOULD be removed from the 1233 response for compactness. For example, in the previous example, 1234 the entity A=ipv4:192.0.2.0/31 SHOULD be removed because A1 and A2 1235 cover all the addresses in A. 1237 An ALTO client should be aware that the entities in the response MAY 1238 be different from the entities in its request. 1240 9. Impact on Legacy ALTO Servers and ALTO Clients 1242 9.1. Impact on Endpoint Property Service 1244 Since the property map and the filtered property map defined in this 1245 document provide the functionality of the Endpoint Property Service 1246 (EPS) defined in Section 11.4 of [RFC7285], it is RECOMMENDED that 1247 the EPS be deprecated in favor of Property Map and Filtered Property 1248 Map. However, ALTO servers MAY provide an EPS for the benefit of 1249 legacy clients. 1251 9.2. Impact on Resource-Specific Properties 1253 Section 10.8 of [RFC7285] defines two categories of endpoint 1254 properties: "resource-specific" and "global". Resource-specific 1255 property names are prefixed with the ID of the resource they depend 1256 upon, while global property names have no such prefix. The property 1257 map and the filtered property map defined in this document defines 1258 the similar categories for entity properties. The difference is that 1259 there is no "global" entity properties but the "self-defined" entity 1260 properties as the special case of the "resource-specific" entity 1261 properties instead. 1263 9.3. Impact on Other Properties 1265 In general, there should be little or no impact on other previously 1266 defined properties. The only consideration is that properties can 1267 now be defined on hierarchical entity identifiers, rather than just 1268 individual entity identifiers, which might change the semantics of a 1269 property. 1271 10. Examples 1273 10.1. Network Map 1275 The examples in this section use a very simple default network map: 1277 defaultpid: ipv4:0.0.0.0/0 ipv6:::0/0 1278 pid1: ipv4:192.0.2.0/25 1279 pid2: ipv4:192.0.2.0/27 1280 pid3: ipv4:192.0.3.0/28 1281 pid4: ipv4:192.0.3.16/28 1283 Figure 3: Example Default Network Map 1285 And another simple alternative network map: 1287 defaultpid: ipv4:0.0.0.0/0 ipv6:::0/0 1288 pid1: ipv4:192.0.2.0/27 1289 pid2: ipv4:192.0.3.0/27 1291 Figure 4: Example Alternative Network Map 1293 10.2. Property Definitions 1295 Beyond "pid", the examples in this section use four additional 1296 properties for Internet address domains, "ISP", "ASN", "country" and 1297 "state", with the following values: 1299 ISP ASN country state 1300 ipv4:192.0.2.0/23: BitsRus - us - 1301 ipv4:192.0.2.0/28: - 12345 - NJ 1302 ipv4:192.0.2.16/28: - 12345 - CT 1303 ipv4:192.0.2.1: - - - PA 1304 ipv4:192.0.3.0/28: - 12346 - TX 1305 ipv4:192.0.3.16/28: - 12346 - MN 1307 Figure 5: Example Property Values for Internet Address Domains 1309 And the examples in this section use the property "region" for the 1310 PID domain of the default network map with the following values: 1312 region 1313 pid:defaultpid: - 1314 pid:pid1: us-west 1315 pid:pid2: us-east 1316 pid:pid3: us-south 1317 pid:pid4: us-north 1319 Figure 6: Example Property Values for Default Network Map's PID 1320 Domain 1322 Note that "-" means the value of the property for the entity is 1323 "undefined". So the entity would inherit a value for this property 1324 by the inheritance rule if possible. For example, the value of the 1325 "ISP" property for "ipv4:192.0.2.1" is "BitsRus" because of 1326 "ipv4:192.0.2.0/24". But the "region" property for "pid:defaultpid" 1327 has no value because no entity from which it can inherit. 1329 Similar to the PID domain of the default network map, the examples in 1330 this section use the property "ASN" for the PID domain of the 1331 alternative network map with the following values: 1333 ASN 1334 pid:defaultpid: - 1335 pid:pid1: 12345 1336 pid:pid2: 12346 1338 Figure 7: Example Property Values for Alternative Network Map's PID 1339 Domain 1341 10.3. Properties for Abstract Network Elements 1343 Additionally, the examples in this section consider a facilitated 1344 entity domain: "ane" (Abstract Network Element). Abstract network 1345 elements allow ALTO clients to discover information beyond the end- 1346 to-end routing costs. Examples of abstract network elements include: 1348 Forwarding elements: Forwarding elements include optical wires, 1349 physical layer links, IP tunnels, etc. Forwarding elements share 1350 the common property "maxresbw". 1352 Value-added services: Value-added services include HTTP caches, 5G 1353 UPF nodes, mobile edge computing, etc. Value-added services share 1354 the common property "persistent-entities", which contains 1355 information that points to the entry point of the service. 1356 Different value-added services may have specific properties, e.g., 1357 an abstract network element of a mobile edge may provide a list of 1358 flavors to the client. 1360 maxresbw persistent-entities mec-flavors 1361 ane:L001 100 Mbps 1362 ane:L002 100 Mbps 1363 ane:CACHE1 http-proxy:192.0.2.1 1364 ane:MEC01 mec:192.0.2.1 {gpu:2G, ssd:128G} 1365 ane:MEC02 mec:192.0.2.2 {gpu:1G, ssd:128G} 1367 The "ane" entities are usually not used alone, but associated with 1368 other ALTO resources, e.g., cost maps. It means that the ALTO server 1369 may not define a property map resource to provide properties of "ane" 1370 entities. The property map payload for "ane" entities may be 1371 provided in the response of other ALTO resources in some way. 1373 10.4. Information Resource Directory (IRD) 1375 The following IRD defines the relevant resources of the ALTO server. 1376 It provides two property maps, one for the "ISP" and "ASN" 1377 properties, and another for the "country" and "state" properties. 1378 The server could have provided a single property map for all four 1379 properties, but did not, presumably because the organization that 1380 runs the ALTO server believes any given client is not interested in 1381 all four properties. 1383 The server provides two filtered property maps. The first returns 1384 all four properties, and the second just returns the "pid" property 1385 for the default network map. 1387 The filtered property maps for the "ISP", "ASN", "country" and 1388 "state" properties do not depend on the default network map (it does 1389 not have a "uses" capability), because the definitions of those 1390 properties do not depend on the default network map. The Filtered 1391 Property Map for the "pid" property does have a "uses" capability for 1392 the default network map, because that defines the values of the "pid" 1393 property. 1395 Note that for legacy clients, the ALTO server provides an Endpoint 1396 Property Service for the "pid" property for the default network map. 1398 The server also provides a facilitated ALTO resource which accepts 1399 the filtered cost map request but returns a multipart message 1400 including a cost map and an associated property map for "ane" 1401 entities. 1403 "meta" : { 1404 ... 1405 "default-alto-network-map" : "default-network-map" 1406 }, 1407 "resources" : { 1408 "default-network-map" : { 1409 "uri" : "http://alto.example.com/networkmap/default", 1410 "media-type" : "application/alto-networkmap+json" 1411 }, 1412 "alt-network-map" : { 1413 "uri" : "http://alto.example.com/networkmap/alt", 1414 "media-type" : "application/alto-networkmap+json" 1415 }, 1416 .... property map resources .... 1417 "ia-property-map" : { 1418 "uri" : "http://alto.example.com/propmap/full/inet-ia", 1419 "media-type" : "application/alto-propmap+json", 1420 "uses": [ "default-network-map", "alt-network-map" ], 1421 "capabilities" : { 1422 "mappings": { 1423 "ipv4": [ ".ISP", ".ASN" ], 1424 "ipv6": [ ".ISP", ".ASN" ] 1425 } 1426 } 1427 }, 1428 "iacs-property-map" : { 1429 "uri" : "http://alto.example.com/propmap/full/inet-iacs", 1430 "media-type" : "application/alto-propmap+json", 1431 "accepts": "application/alto-propmapparams+json", 1432 "uses": [ "default-network-map", "alt-network-map" ], 1433 "capabilities" : { 1434 "mappings": { 1435 "ipv4": [ ".ISP", ".ASN", ".country", ".state" ], 1436 "ipv6": [ ".ISP", ".ASN", ".country", ".state" ] 1437 } 1438 } 1439 }, 1440 "region-property-map": { 1441 "uri": "http://alto.exmaple.com/propmap/region", 1442 "media-type": "application/alto-propmap+json", 1443 "accepts": "application/alto-propmapparams+json", 1444 "uses" : [ "default-network-map", "alt-network-map" ], 1445 "capabilities": { 1446 "mappings": { 1447 "default-network-map.pid": [ ".region" ], 1448 "alt-network-map.pid": [ ".ASN" ], 1449 } 1450 } 1451 }, 1452 "ip-pid-property-map" : { 1453 "uri" : "http://alto.example.com/propmap/lookup/pid", 1454 "media-type" : "application/alto-propmap+json", 1455 "accepts" : "application/alto-propmapparams+json", 1456 "uses" : [ "default-network-map", "alt-network-map" ], 1457 "capabilities" : { 1458 "mappings": { 1459 "ipv4": [ "default-network-map.pid", 1460 "alt-network-map.pid" ], 1461 "ipv6": [ "default-network-map.pid", 1462 "alt-network-map.pid" ] 1463 } 1464 } 1465 }, 1466 "legacy-endpoint-property" : { 1467 "uri" : "http://alto.example.com/legacy/eps-pid", 1468 "media-type" : "application/alto-endpointprop+json", 1469 "accepts" : "application/alto-endpointpropparams+json", 1470 "capabilities" : { 1471 "properties" : [ "default-network-map.pid", 1472 "alt-network-map.pid" ] 1473 } 1474 }, 1475 "path-vector-map": { 1476 "uri": "http://alto.example.com/costmap/pv", 1477 "media-type": 1478 "multipart/related;type=applicatoin/alto-costmap+json", 1479 "accepts": "applicatoin/alto-costmapfilter+json", 1480 "capabilities": { 1481 "cost-type-names": ["path-vector"], 1482 "ane-properties": ["maxresbw", "persistent-entities", 1483 "mec-flavors"] 1484 }, 1485 "uses": [ "default-network-map" ] 1486 } 1487 } 1489 Figure 8: Example IRD 1491 10.5. Property Map Example 1493 The following example uses the properties and IRD defined above to 1494 retrieve a Property Map for entities with the "ISP" and "ASN" 1495 properties. 1497 Note that, to be compact, the response does not include the entity 1498 "ipv4:192.0.2.0", because values of all those properties for this 1499 entity are inherited from other entities. 1501 Also note that the entities "ipv4:192.0.2.0/28" and 1502 "ipv4:192.0.2.16/28" are merged into "ipv4:192.0.2.0/27", because 1503 they have the same value of the "ASN" property. The same rule 1504 applies to the entities "ipv4:192.0.3.0/28" and "ipv4:192.0.3.0/28". 1505 Both of "ipv4:192.0.2.0/27" and "ipv4:192.0.3.0/27" omit the value 1506 for the "ISP" property, because it is inherited from 1507 "ipv4:192.0.2.0/23". 1509 GET /propmap/full/inet-ia HTTP/1.1 1510 Host: alto.example.com 1511 Accept: application/alto-propmap+json,application/alto-error+json 1512 HTTP/1.1 200 OK 1513 Content-Length: ### 1514 Content-Type: application/alto-propmap+json 1516 { 1517 "meta": { 1518 "dependent-vtags": [ 1519 {"resource-id": "default-network-map", 1520 "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"}, 1521 {"resource-id": "alt-network-map", 1522 "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"} 1523 ] 1524 }, 1525 "property-map": { 1526 "ipv4:192.0.2.0/23": {".ISP": "BitsRus"}, 1527 "ipv4:192.0.2.0/27": {".ASN": "12345"}, 1528 "ipv4:192.0.3.0/27": {".ASN": "12346"} 1529 } 1530 } 1532 10.6. Filtered Property Map Example #1 1534 The following example uses the filtered property map resource to 1535 request the "ISP", "ASN" and "state" properties for several IPv4 1536 addresses. 1538 Note that the value of "state" for "ipv4:192.0.2.0" is the only 1539 explicitly defined property; the other values are all derived by the 1540 inheritance rules for Internet address entities. 1542 POST /propmap/lookup/inet-iacs HTTP/1.1 1543 Host: alto.example.com 1544 Accept: application/alto-propmap+json,application/alto-error+json 1545 Content-Length: ### 1546 Content-Type: application/alto-propmapparams+json 1548 { 1549 "entities" : [ "ipv4:192.0.2.0", 1550 "ipv4:192.0.2.1", 1551 "ipv4:192.0.2.17" ], 1552 "properties" : [ ".ISP", ".ASN", ".state" ] 1553 } 1554 HTTP/1.1 200 OK 1555 Content-Length: ### 1556 Content-Type: application/alto-propmap+json 1558 { 1559 "meta": { 1560 "dependent-vtags": [ 1561 {"resource-id": "default-network-map", 1562 "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"}, 1563 {"resource-id": "alt-network-map", 1564 "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"} 1565 ] 1566 }, 1567 "property-map": { 1568 "ipv4:192.0.2.0": 1569 {".ISP": "BitsRus", ".ASN": "12345", ".state": "PA"}, 1570 "ipv4:192.0.2.1": 1571 {".ISP": "BitsRus", ".ASN": "12345", ".state": "NJ"}, 1572 "ipv4:192.0.2.17": 1573 {".ISP": "BitsRus", ".ASN": "12345", ".state": "CT"} 1574 } 1575 } 1577 10.7. Filtered Property Map Example #2 1579 The following example uses the filtered property map resource to 1580 request the "ASN", "country" and "state" properties for several IPv4 1581 prefixes. 1583 Note that the property values for both entities "ipv4:192.0.2.0/26" 1584 and "ipv4:192.0.3.0/26" are not explicitly defined. They are 1585 inherited from the entity "ipv4:192.0.2.0/23". 1587 Also note that some entities like "ipv4:192.0.2.0/28" and 1588 "ipv4:192.0.2.16/28" in the response are not listed in the request 1589 explicitly. The response includes them because they are refinements 1590 of the requested entities and have different values for the requested 1591 properties. 1593 The entity "ipv4:192.0.4.0/26" is not included in the response, 1594 because there are neither entities which it is inherited from, nor 1595 entities inherited from it. 1597 POST /propmap/lookup/inet-iacs HTTP/1.1 1598 Host: alto.example.com 1599 Accept: application/alto-propmap+json,application/alto-error+json 1600 Content-Length: ### 1601 Content-Type: application/alto-propmapparams+json 1603 { 1604 "entities" : [ "ipv4:192.0.2.0/26", 1605 "ipv4:192.0.3.0/26", 1606 "ipv4:192.0.4.0/26" ], 1607 "properties" : [ ".ASN", ".country", ".state" ] 1608 } 1610 HTTP/1.1 200 OK 1611 Content-Length: ### 1612 Content-Type: application/alto-propmap+json 1614 { 1615 "meta": { 1616 "dependent-vtags": [ 1617 {"resource-id": "default-network-map", 1618 "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"}, 1619 {"resource-id": "alt-network-map", 1620 "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"} 1621 ] 1622 }, 1623 "property-map": { 1624 "ipv4:192.0.2.0/26": {".country": "us"}, 1625 "ipv4:192.0.2.0/28": {".ASN": "12345", 1626 ".state": "NJ"}, 1627 "ipv4:192.0.2.16/28": {".ASN": "12345", 1628 ".state": "CT"}, 1629 "ipv4:192.0.2.0": {".state": "PA"}, 1630 "ipv4:192.0.3.0/26": {".country": "us"}, 1631 "ipv4:192.0.3.0/28": {".ASN": "12345", 1632 ".state": "TX"}, 1633 "ipv4:192.0.3.16/28": {".ASN": "12345", 1634 ".state": "MN"} 1635 } 1636 } 1638 10.8. Filtered Property Map Example #3 1640 The following example uses the filtered property map resource to 1641 request the "default-network-map.pid" property and the "alt-network- 1642 map.pid" property for a set of IPv4 addresses and prefixes. 1644 Note that the entity "ipv4:192.0.3.0/27" is decomposed into two 1645 entities "ipv4:192.0.3.0/28" and "ipv4:192.0.3.16/28", as they have 1646 different "default-network-map.pid" property values. 1648 POST /propmap/lookup/pid HTTP/1.1 1649 Host: alto.example.com 1650 Accept: application/alto-propmap+json,application/alto-error+json 1651 Content-Length: ### 1652 Content-Type: application/alto-propmapparams+json 1654 { 1655 "entities" : [ 1656 "ipv4:192.0.2.128", 1657 "ipv4:192.0.2.0/27", 1658 "ipv4:192.0.3.0/27" ], 1659 "properties" : [ "default-network-map.pid", 1660 "alt-network-map.pid ] 1661 } 1663 HTTP/1.1 200 OK 1664 Content-Length: ### 1665 Content-Type: application/alto-propmap+json 1667 { 1668 "meta": { 1669 "dependent-vtags": [ 1670 {"resource-id": "default-network-map", 1671 "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"}, 1672 {"resource-id": "alt-network-map", 1673 "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"} 1674 ] 1675 }, 1676 "property-map": { 1677 "ipv4:192.0.2.128": {"default-network-map.pid": "defaultpid", 1678 "alt-network-map.pid": "defaultpid"}, 1679 "ipv4:192.0.2.0/27": {"default-network-map.pid": "pid2", 1680 "alt-network-map.pid": "pid1"}, 1681 "ipv4:192.0.3.0/28": {"default-network-map.pid": "pid3", 1682 "alt-network-map.pid": "pid2"}, 1683 "ipv4:192.0.3.16/28": {"default-network-map.pid": "pid4", 1684 "alt-network-map.pid": "pid2"} 1685 } 1686 } 1688 10.9. Filtered Property Map Example #4 1690 The following example uses the filtered property map resource to 1691 request the "region" property for several PIDs defined in "default- 1692 network-map". The value of the "region" property for each PID is not 1693 defined by "default-network-map", but the reason why the PID is 1694 defined by the network operator. 1696 POST /propmap/lookup/region HTTP/1.1 1697 Host: alto.example.com 1698 Accept: application/alto-propmap+json,application/alto-error+json 1699 Content-Length: ### 1700 Content-Type: application/alto-propmapparams+json 1702 { 1703 "entities" : ["default-network-map.pid:pid1", 1704 "default-network-map.pid:pid2"], 1705 "properties" : [ ".region" ] 1706 } 1708 HTTP/1.1 200 OK 1709 Content-Length: ### 1710 Content-Type: application/alto-propmap+json 1712 { 1713 "meta" : { 1714 "dependent-vtags" : [ 1715 {"resource-id": "default-network-map", 1716 "tag": "7915dc0290c2705481c491a2b4ffbec482b3cf62"} 1717 ] 1718 }, 1719 "property-map": { 1720 "default-network-map.pid:pid1": { 1721 ".region": "us-west" 1722 }, 1723 "default-network-map.pid:pid2": { 1724 ".region": "us-east" 1725 } 1726 } 1727 } 1729 10.10. Property Map in Path Vector Example #1 1731 The following example requests the "maxresbw", "persistent-entities" 1732 and "mec-flavors" properties for abstract network elements between 1733 "pid1" and "pid3" in "default-network-map". 1735 POST /costmap/pv HTTP/1.1 1736 Host: alto.example.com 1737 Accept: multipart/related;type=application/alto-costmap+json, 1738 application/alto-error+json 1739 Content-Length: [TBD] 1740 Content-Type: application/alto-costmapfilter+json 1742 { 1743 "cost-type": { 1744 "cost-mode": "array", 1745 "cost-metric": "ane-path" 1746 }, 1747 "pids": { 1748 "srcs": [ "pid1" ], 1749 "dsts": [ "pid3" ] 1750 }, 1751 "ane-properties": ["maxresbw", "persistent-entities", "mec-flavors"] 1753 } 1755 HTTP/1.1 200 OK 1756 Content-Length: [TBD] 1757 Content-Type: multipart/related; boundary=example-1; 1758 type=application/alto-costmap+json 1760 --example-1 1761 Content-Id: costmap 1762 Content-Type: application/alto-costmap+json 1764 { 1765 "meta": { 1766 "vtag": { 1767 "resource-id": "cost-map-pv.costmap", 1768 "tag": "d827f484cb66ce6df6b5077cb8562b0a" 1769 }, 1770 "dependent-vtags": [ 1771 { 1772 "resource-id": "my-default-networkmap", 1773 "tag": "75ed013b3cb58f896e839582504f6228" 1774 } 1775 ], 1776 "cost-type": { 1777 "cost-mode": "array", 1778 "cost-metric": "ane-path" 1779 } 1780 }, 1781 "cost-map": { 1782 "pid1": { 1783 "pid3": [ "ane:L001", "ane:L002", "ane:MEC01", "ane:MEC02" ], 1784 } 1785 } 1786 } 1787 --example-1 1788 Content-Id: propmap 1789 Content-Type: application/alto-propmap+json 1791 { 1792 "meta": { 1793 "dependent-vtags": [ 1794 { 1795 "resource-id": "cost-map-pv.costmap", 1796 "tag": "d827f484cb66ce6df6b5077cb8562b0a" 1797 } 1798 ] 1799 }, 1800 "property-map": { 1801 "ane:L001": { "maxresbw": 100000000 }, 1802 "ane:L002": { "maxresbw": 100000000 }, 1803 "ane:MEC01": { "persistent-entities": "mec:192.0.2.1", 1804 "mec-flavors": [ {"gpu": "2G", "ssd": "128G"}]}, 1805 "ane:MEC02": { "persistent-entities": "mec:192.0.2.2", 1806 "mec-flavors": [ {"gpu": "1G", "ssd": "128G"}]} 1807 } 1808 } 1810 11. Security Considerations 1812 Both Property Map and Filtered Property Map defined in this document 1813 fit into the architecture of the ALTO base protocol, and hence the 1814 Security Considerations (Section 15 of [RFC7285]) of the base 1815 protocol fully apply: authenticity and integrity of ALTO information 1816 (i.e., authenticity and integrity of Property Maps), potential 1817 undesirable guidance from authenticated ALTO information (e.g., 1818 potentially imprecise or even wrong value of a property such as geo- 1819 location), confidentiality of ALTO information (e.g., exposure of a 1820 potentially sensitive entity property such as geo-location), privacy 1821 for ALTO users, and availability of ALTO services should all be 1822 considered. 1824 A particular fundamental security consideration when an ALTO server 1825 provides a Property Map is to define precisely the policies on who 1826 can access what properties for which entities. Security mechanisms 1827 such as authentication and confidentiality mechanisms then should be 1828 applied to enforce the policy. For example, a policy can be that a 1829 property P can be accessed only by its owner (e.g., the customer who 1830 is allocated a given IP address). Then, the ALTO server will need to 1831 deploy corresponding mechanisms to realize the policy. The policy 1832 may allow non-owners to access a coarse-grained value of the property 1833 P. In such a case, the ALTO server may provide a different URI to 1834 provide the information. 1836 12. IANA Considerations 1838 This document defines additional application/alto-* media types, and 1839 extends the ALTO endpoint property registry. 1841 12.1. application/alto-* Media Types 1843 This document registers two additional ALTO media types, listed in 1844 Table 1. 1846 +----------------+-------------------------+------------------------+ 1847 | Type | Subtype | Specification | 1848 +----------------+-------------------------+------------------------+ 1849 | application | alto- | Section 7.1 | 1850 | | propmap+json | | 1851 | application | alto- | Section 8.3 | 1852 | | propmapparams+json | | 1853 +----------------+-------------------------+------------------------+ 1855 Table 1: Additional ALTO Media Types. 1857 Type name: application 1859 Subtype name: This document registers multiple subtypes, as listed 1860 in Table 1. 1862 Required parameters: n/a 1864 Optional parameters: n/a 1866 Encoding considerations: Encoding considerations are identical to 1867 those specified for the "application/json" media type. See 1868 [RFC7159]. 1870 Security considerations: Security considerations related to the 1871 generation and consumption of ALTO Protocol messages are discussed 1872 in Section 15 of [RFC7285]. 1874 Interoperability considerations: This document specifies formats of 1875 conforming messages and the interpretation thereof. 1877 Published specification: This document is the specification for 1878 these media types; see Table 1 for the section documenting each 1879 media type. 1881 Applications that use this media type: ALTO servers and ALTO clients 1882 either stand alone or are embedded within other applications. 1884 Additional information: 1886 Magic number(s): n/a 1888 File extension(s): This document uses the mime type to refer to 1889 protocol messages and thus does not require a file extension. 1891 Macintosh file type code(s): n/a 1893 Person & email address to contact for further information: 1894 See Authors' Addresses section. 1896 Intended usage: COMMON 1898 Restrictions on usage: n/a 1900 Author: See Authors' Addresses section. 1902 Change controller: Internet Engineering Task Force 1903 (mailto:iesg@ietf.org). 1905 12.2. ALTO Entity Domain Type Registry 1907 This document requests IANA to create and maintain the "ALTO Entity 1908 Domain Type Registry", listed in Table 2. 1910 +---------------+-------------------------+-------------------------+ 1911 | Identifier | Entity | Hierarchy & Inheritance | 1912 | | Identifier Encoding | | 1913 +---------------+-------------------------+-------------------------+ 1914 | ipv4 | See | See | 1915 | | Section 5.1.1 | Section 5.1.3 | 1916 | ipv6 | See | See | 1917 | | Section 5.1.2 | Section 5.1.3 | 1918 | pid | See | None | 1919 | | Section 5.2 | | 1920 +---------------+-------------------------+-------------------------+ 1922 Table 2: ALTO Entity Domains. 1924 This registry serves two purposes. First, it ensures uniqueness of 1925 identifiers referring to ALTO entity domains. Second, it states the 1926 requirements for allocated entity domains. 1928 12.2.1. Consistency Procedure between ALTO Address Type Registry and 1929 ALTO Entity Domain Type Registry 1931 One potential issue of introducing the "ALTO Entity Domain Type 1932 Registry" is its relationship with the "ALTO Address Types Registry" 1933 already defined in Section 14.4 of [RFC7285]. In particular, the 1934 entity identifier of a type of an entity domain registered in the 1935 "ALTO Entity Domain Type Registry" MAY match an address type defined 1936 in "ALTO Address Type Registry". It is necessary to precisely define 1937 and guarantee the consistency between "ALTO Address Type Registry" 1938 and "ALTO Entity Domain Registry". 1940 We define that the ALTO Entity Domain Type Registry is consistent 1941 with ALTO Address Type Registry if two conditions are satisfied: 1943 o When an address type is already or able to be registered in the 1944 ALTO Address Type Registry [RFC7285], the same identifier MUST be 1945 used when a corresponding entity domain type is registered in the 1946 ALTO Entity Domain Type Registry. 1948 o If an ALTO entity domain type has the same identifier as an ALTO 1949 address type, their addresses encoding MUST be compatible. 1951 To achieve this consistency, the following items MUST be checked 1952 before registering a new ALTO entity domain type in a future 1953 document: 1955 o Whether the ALTO Address Type Registry contains an address type 1956 that can be used as an entity identifier for the candidate domain 1957 identifier. This has been done for the identifiers "ipv4" and 1958 "ipv6" in Table 2. 1960 o Whether the candidate entity identifier of the type of the entity 1961 domain is able to be an endpoint address, as defined in Sections 1962 2.1 and 2.2 of [RFC7285]. 1964 When a new ALTO entity domain type is registered, the consistency 1965 with the ALTO Address Type Registry MUST be ensured by the following 1966 procedure: 1968 o Test: Do corresponding entity identifiers match a known "network" 1969 address type? 1971 * If yes (e.g., cell, MAC or socket addresses): 1973 + Test: Is such an address type present in the ALTO Address 1974 Type Registry? 1976 - If yes: Set the new ALTO entity domain type identifier to 1977 be the found ALTO address type identifier. 1979 - If no: Define a new ALTO entity domain type identifier 1980 and use it to register a new address type in the ALTO 1981 Address Type Registry following Section 14.4 of 1982 [RFC7285]. 1984 + Use the new ALTO entity domain type identifier to register a 1985 new ALTO entity domain type in the ALTO Entity Domain Type 1986 Registry following Section 12.2.2 of this document. 1988 * If no (e.g., pid name, ane name or country code): Proceed with 1989 the ALTO Entity Domain Type registration as described in 1990 Section 12.2.2. 1992 12.2.2. ALTO Entity Domain Type Registration Process 1994 New ALTO entity domain types are assigned after IETF Review [RFC5226] 1995 to ensure that proper documentation regarding the new ALTO entity 1996 domain types and their security considerations has been provided. 1997 RFCs defining new entity domain types SHOULD indicate how an entity 1998 in a registered type of domain is encoded as an EntityID, and, if 1999 applicable, the rules defining the entity hierarchy and property 2000 inheritance. Updates and deletions of ALTO entity domains follow the 2001 same procedure. 2003 Registered ALTO entity domain type identifiers MUST conform to the 2004 syntactical requirements specified in Section 4.1.2. Identifiers are 2005 to be recorded and displayed as strings. 2007 Requests to the IANA to add a new value to the registry MUST include 2008 the following information: 2010 o Identifier: The name of the desired ALTO entity domain type. 2012 o Entity Identifier Encoding: The procedure for encoding the 2013 identifier of an entity of the registered type as an EntityID (see 2014 Section 4.1.3). If corresponding entity identifiers of an entity 2015 domain match a known "network" address type, the Entity Identifier 2016 Encoding of this domain identifier MUST include both Address 2017 Encoding and Prefix Encoding of the same identifier registered in 2018 the ALTO Address Type Registry [RFC7285]. For the purpose of 2019 defining properties, an individual entity identifier and the 2020 corresponding full-length prefix MUST be considered aliases for 2021 the same entity. 2023 o Hierarchy: If the entities form a hierarchy, the procedure for 2024 determining that hierarchy. 2026 o Inheritance: If entities can inherit property values from other 2027 entities, the procedure for determining that inheritance. 2029 o Mapping to ALTO Address Type: A boolean value to indicate if the 2030 entity domain type can be mapped to the ALTO address type with the 2031 same identifier. 2033 o Security Considerations: In some usage scenarios, entity 2034 identifiers carried in ALTO Protocol messages may reveal 2035 information about an ALTO client or an ALTO service provider. 2036 Applications and ALTO service providers using addresses of the 2037 registered type should be made aware of how (or if) the addressing 2038 scheme relates to private information and network proximity. 2040 This specification requests registration of the identifiers "ipv4", 2041 "ipv6" and "pid", as shown in Table 2. 2043 12.3. ALTO Entity Property Type Registry 2045 This document requests IANA to create and maintain the "ALTO Entity 2046 Property Type Registry", listed in Table 3. 2048 To distinguish with the "ALTO Endpoint Property Type Registry", each 2049 entry in this registry is an ALTO entity property type defined in 2050 Section 4.2.1. Thus, registered ALTO entity property type identifier 2051 MUST conform to the syntactical requirements specified in that 2052 section. 2054 The initial registered ALTO entity property types are listed in 2055 Table 3. 2057 +---------------------------+---------------------------------------+ 2058 | Identifier | Intended Semantics | 2059 +---------------------------+---------------------------------------+ 2060 | pid | See Section 7.1.1 of | 2061 | | [RFC7285] | 2062 +---------------------------+---------------------------------------+ 2064 Table 3: ALTO Entity Property Types. 2066 Requests to the IANA to add a new value to the registry MUST include 2067 the following information: 2069 o Identifier: The unique id for the desired ALTO entity property 2070 type. The format MUST be as defined in Section 4.2.1 of this 2071 document. It includes the information of the applied ALTO entity 2072 domain and the property name. 2074 o Intended Semantics: ALTO entity properties carry with them 2075 semantics to guide their usage by ALTO clients. Hence, a document 2076 defining a new type SHOULD provide guidance to both ALTO service 2077 providers and applications utilizing ALTO clients as to how values 2078 of the registered ALTO entity property should be interpreted. 2080 This document requests registration of the identifier "pid", as shown 2081 in Table 3. 2083 12.4. ALTO Resource-Specific Entity Domain Registries 2085 12.4.1. Network Map 2087 Media-type: application/alto-networkmap+json 2089 +---------------------------------+---------------------------------+ 2090 | Entity Domain | Intended | 2091 | Type | Semantics | 2092 +---------------------------------+---------------------------------+ 2093 | ipv4 | See | 2094 | | Section 6.2.1 | 2095 | ipv6 | See | 2096 | | Section 6.2.1 | 2097 | pid | See | 2098 | | Section 6.2.1 | 2099 +---------------------------------+---------------------------------+ 2101 Table 4: ALTO Network Map Resource-Specific Entity Domain. 2103 12.4.2. Endpoint Property 2105 Media-type: application/alto-endpointprop+json 2106 +---------------------------------+---------------------------------+ 2107 | Entity Domain | Intended | 2108 | Type | Semantics | 2109 +---------------------------------+---------------------------------+ 2110 | ipv4 | See | 2111 | | Section 6.3.1 | 2112 | ipv6 | See | 2113 | | Section 6.3.1 | 2114 +---------------------------------+---------------------------------+ 2116 Table 5: ALTO Endpoint Property Resource-Specific Entity Domain. 2118 12.5. ALTO Resource Entity Property Mapping Registries 2120 12.5.1. Network Map 2122 Media-type: application/alto-networkmap+json 2124 +----------------+-----------------+-------------+------------------+ 2125 | Mapping | Entity Domain | Property | Intended | 2126 | Descriptor | Type | Type | Semantics | 2127 +----------------+-----------------+-------------+------------------+ 2128 | ipv4 -> pid | ipv4 | pid | See | 2129 | | | | Section 6.2.2 | 2130 | ipv6 -> pid | ipv6 | pid | See | 2131 | | | | Section 6.2.2 | 2132 +----------------+-----------------+-------------+------------------+ 2134 Table 6: ALTO Network Map Entity Property Mapping. 2136 13. Acknowledgments 2138 The authors would like to thank discussions with Kai Gao, Qiao Xiang, 2139 Shawn Lin, Xin Wang, Danny Perez, and Vijay Gurbani. The authors 2140 thank Dawn Chen (Tongji University), and Shenshen Chen (Tongji/Yale 2141 University) for their contributions to earlier drafts. 2143 14. References 2145 14.1. Normative References 2147 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2148 Requirement Levels", BCP 14, RFC 2119, 2149 DOI 10.17487/RFC2119, March 1997, 2150 . 2152 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2153 Resource Identifier (URI): Generic Syntax", STD 66, 2154 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2155 . 2157 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2158 (CIDR): The Internet Address Assignment and Aggregation 2159 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2160 2006, . 2162 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2163 IANA Considerations Section in RFCs", RFC 5226, 2164 DOI 10.17487/RFC5226, May 2008, 2165 . 2167 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 2168 Address Text Representation", RFC 5952, 2169 DOI 10.17487/RFC5952, August 2010, 2170 . 2172 [RFC7011] Claise, B., Ed., Trammell, B., Ed., and P. Aitken, 2173 "Specification of the IP Flow Information Export (IPFIX) 2174 Protocol for the Exchange of Flow Information", STD 77, 2175 RFC 7011, DOI 10.17487/RFC7011, September 2013, 2176 . 2178 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2179 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2180 2014, . 2182 [RFC7285] Alimi, R., Ed., Penno, R., Ed., Yang, Y., Ed., Kiesel, S., 2183 Previdi, S., Roome, W., Shalunov, S., and R. Woundy, 2184 "Application-Layer Traffic Optimization (ALTO) Protocol", 2185 RFC 7285, DOI 10.17487/RFC7285, September 2014, 2186 . 2188 [RFC7921] Atlas, A., Halpern, J., Hares, S., Ward, D., and T. 2189 Nadeau, "An Architecture for the Interface to the Routing 2190 System", RFC 7921, DOI 10.17487/RFC7921, June 2016, 2191 . 2193 [RFC8008] Seedorf, J., Peterson, J., Previdi, S., van Brandenburg, 2194 R., and K. Ma, "Content Delivery Network Interconnection 2195 (CDNI) Request Routing: Footprint and Capabilities 2196 Semantics", RFC 8008, DOI 10.17487/RFC8008, December 2016, 2197 . 2199 14.2. Informative References 2201 [I-D.ietf-alto-path-vector] 2202 Gao, K., Lee, Y., Randriamasy, S., Yang, Y., and J. Zhang, 2203 "ALTO Extension: Path Vector", draft-ietf-alto-path- 2204 vector-09 (work in progress), November 2019, 2205 . 2208 Appendix A. Scope of Property Map 2210 Using entity domains to organize entities, an ALTO property map 2211 resource can be regarded as given sets of properties for given entity 2212 domains. If we ignore the resource-agnostic entity domains, we can 2213 regard an ALTO property map resource as a set of (ri, di) => (ro, po) 2214 mappings, where (ri, di) means a resource-specific entity domain of 2215 type di defined by the information resource ri, and (ro, po) means a 2216 resource-specific entity property po defined by the information 2217 resource ro. 2219 For each (ri, di) => (ro, po) mapping, the scope of an ALTO property 2220 map resource must be one of the cases in the following diagram: 2222 domain.resource domain.resource 2223 (ri) = r (ri) = this 2224 +-----------------|-----------------+ 2225 prop.resource | Export | Non-exist | 2226 (ro) = r | | | 2227 +-----------------|-----------------+ 2228 prop.resource | Extend | Define | 2229 (ro) = this | | | 2230 +-----------------|-----------------+ 2232 where "this" represents the resulting property map resource, and "r" 2233 represents an existing ALTO information resource other the resulting 2234 property map resource. 2236 o ri = ro = r ("export" mode): the property map resource just 2237 transforms the property mapping di => po defined by r into the 2238 unified representation format and exports it. For example: r = 2239 "netmap1", di = "ipv4", po = "pid". The property map resource 2240 exports the "ipv4 => pid" mapping defined by "netmap1". 2242 o ri = r, ro = this ("extend" mode): the property map extends 2243 properties of entities in the entity domain (r, di) and defines a 2244 new property po on them. For example: the property map resource 2245 ("this") defines a "geolocation" property on domain "netmap1.pid". 2247 o ri = ro = this ("define" mode): the property map defines a new 2248 intrinsic entity domain and defines property po for each entity in 2249 this domain. For example: the property map resource ("this") 2250 defines a new entity domain "asn" and defines a property 2251 "ipprefixes" on this domain. 2253 o ri = this, ro = r: in the scope of a property map resource, it 2254 does not make sense that another existing ALTO information 2255 resource defines a property for this property map resource. 2257 A.1. Example Property Map 2259 The following figure shows an example property map called Property 2260 Map 1, which depends on two network maps and provides three sets of 2261 mappings by 2263 o exporting a mapping from ipv4 entities to PIDs defined by two 2264 different network maps, 2266 o extending geo-location properties to ipv4 entities defined by 2267 Network Map 1, 2269 o and defining a new mapping from ASNs to traffic load properties. 2271 (Define) 2272 +----------+ +-------------+ 2273 ->| Property |<---------------------------+--------| asn | load | 2274 / | Map 1 | | |-------------| 2275 / +----------+ | | 1234 | 95% | 2276 | ^ | | 5678 | 70% | 2277 | | \ +-------------+ 2278 | | (Export) \ (Extend) 2279 | +---------+ +------------------------+ \ +--------------+ 2280 | | Network |----| ipv4 | pid | -----| geo-location | 2281 | | Map 1 | |------------------------| +--------------+ 2282 | +---------+ | 192.168.0.0/24 | pid1 | - - -> | New York | 2283 | | 192.168.1.0/24 | pid2 | - - -> | Shanghai | 2284 | +------------------------+ +--------------+ 2285 | (Export) 2286 \ +---------+ +------------------------+ 2287 ---| Network |----| ipv4 | pid | 2288 | Map 2 | |------------------------| 2289 +---------+ | 192.168.0.0/24 | Paris | 2290 | ... | ... | 2291 +------------------------+ 2293 More detailed examples are shown in Section 10. 2295 Authors' Addresses 2297 Wendy Roome 2298 Nokia Bell Labs (Retired) 2299 124 Burlington Rd 2300 Murray Hill, NJ 07974 2301 USA 2303 Phone: +1-908-464-6975 2304 Email: wendy@wdroome.com 2306 Sabine Randriamasy 2307 Nokia Bell Labs 2308 Route de Villejust 2309 NOZAY 91460 2310 FRANCE 2312 Email: Sabine.Randriamasy@nokia-bell-labs.com 2314 Y. Richard Yang 2315 Yale University 2316 51 Prospect Street 2317 New Haven, CT 06511 2318 USA 2320 Phone: +1-203-432-6400 2321 Email: yry@cs.yale.edu 2323 Jingxuan Jensen Zhang 2324 Tongji University 2325 4800 Caoan Road 2326 Shanghai 201804 2327 China 2329 Email: jingxuan.n.zhang@gmail.com 2331 Kai Gao 2332 Sichuan University 2333 Chengdu 610000 2334 China 2336 Email: kaigao@scu.edu.cn