idnits 2.17.1 draft-ietf-alto-unified-props-new-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1414 has weird spacing: '...rtyName prop...' == Line 1623 has weird spacing: '...country stat...' -- The document date (16 April 2021) is 1105 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO3166-1' ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-22) exists of draft-ietf-alto-cdni-request-routing-alto-16 == Outdated reference: A later version (-25) exists of draft-ietf-alto-path-vector-13 Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). 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: 18 October 2021 Y. Yang 6 Yale University 7 J. Zhang 8 Tongji University 9 K. Gao 10 Sichuan University 11 16 April 2021 13 ALTO Extension: Entity Property Maps 14 draft-ietf-alto-unified-props-new-17 16 Abstract 18 This document extends the base Application-Layer Traffic Optimization 19 (ALTO) Protocol by generalizing the concept of "endpoint properties" 20 as applied to endpoints as defined by IP addresses to endpoints 21 defined by a wider set of objects. Further, these properties are 22 presented as maps, similar to the network and cost maps in the base 23 ALTO protocol. The protocol is extended in two major directions. 24 First, from endpoints restricted to IP addresses to entities covering 25 a wider and extensible set of objects; second, from properties on 26 specific endpoints to entire entity property maps. These extensions 27 introduce additional features allowing entities and property values 28 to be specific to a given information resource. This is made 29 possible by a generic and flexible design of entity and property 30 types. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on 18 October 2021. 49 Copyright Notice 51 Copyright (c) 2021 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Simplified BSD License text 60 as described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 66 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 67 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 6 68 3. Basic Features of the Entity Property Map Extension . . . . . 7 69 3.1. Entity . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 3.2. Entity Domain . . . . . . . . . . . . . . . . . . . . . . 8 71 3.2.1. Entity Domain Type . . . . . . . . . . . . . . . . . 8 72 3.2.2. Entity Domain Name . . . . . . . . . . . . . . . . . 9 73 3.3. Entity Property Type . . . . . . . . . . . . . . . . . . 9 74 3.4. New information resource and media type: ALTO Property 75 Map . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 76 4. Advanced Features of the Entity Property Map Extension . . . 11 77 4.1. Entity Identifier and Entity Domain Name . . . . . . . . 11 78 4.2. Resource-Specific Entity Domain Name . . . . . . . . . . 11 79 4.3. Resource-Specific Entity Property Value . . . . . . . . . 12 80 4.4. Entity Hierarchy and Property Inheritance . . . . . . . . 13 81 4.4.1. Entity Hierarchy . . . . . . . . . . . . . . . . . . 14 82 4.4.2. Property Inheritance . . . . . . . . . . . . . . . . 14 83 4.4.3. Property Value Unicity . . . . . . . . . . . . . . . 14 84 4.5. Supported Properties on Entity Domains in Property Map 85 Capabilities . . . . . . . . . . . . . . . . . . . . . . 15 86 4.6. Defining Information Resource for Resource-Specific Entity 87 Domains . . . . . . . . . . . . . . . . . . . . . . . . . 16 88 4.6.1. Defining Information Resource and its Media Type . . 17 89 4.6.2. Examples of Defining Information Resources and Their 90 Media Types . . . . . . . . . . . . . . . . . . . . . 18 91 4.7. Defining Information Resource for Resource-Specific 92 Property Values . . . . . . . . . . . . . . . . . . . . . 18 93 5. Protocol Specification: Basic Data Types . . . . . . . . . . 19 94 5.1. Entity Domain . . . . . . . . . . . . . . . . . . . . . . 19 95 5.1.1. Entity Domain Type . . . . . . . . . . . . . . . . . 19 96 5.1.2. Entity Domain Name . . . . . . . . . . . . . . . . . 20 97 5.1.3. Entity Identifier . . . . . . . . . . . . . . . . . . 22 98 5.1.4. Hierarchy and Inheritance . . . . . . . . . . . . . . 22 99 5.2. Entity Property . . . . . . . . . . . . . . . . . . . . . 23 100 5.2.1. Entity Property Type . . . . . . . . . . . . . . . . 23 101 5.2.2. Entity Property Name . . . . . . . . . . . . . . . . 24 102 5.2.3. Format for Entity Property Value . . . . . . . . . . 24 103 6. Entity Domain Types Defined in this Document . . . . . . . . 24 104 6.1. Internet Address Domain Types . . . . . . . . . . . . . . 25 105 6.1.1. Entity Domain Type: IPv4 . . . . . . . . . . . . . . 25 106 6.1.2. Entity Domain Type: IPv6 . . . . . . . . . . . . . . 25 107 6.1.3. Hierarchy and Inheritance of Internet Address 108 Domains . . . . . . . . . . . . . . . . . . . . . . . 26 109 6.1.4. Defining Information Resource Media Type for domain 110 types IPv4 and IPv6 . . . . . . . . . . . . . . . . . 27 111 6.2. Entity Domain Type: PID . . . . . . . . . . . . . . . . . 27 112 6.2.1. Entity Domain Type Identifier . . . . . . . . . . . . 27 113 6.2.2. Domain-Specific Entity Identifiers . . . . . . . . . 27 114 6.2.3. Hierarchy and Inheritance . . . . . . . . . . . . . . 28 115 6.2.4. Defining Information Resource Media Type for Domain 116 Type PID . . . . . . . . . . . . . . . . . . . . . . 28 117 6.2.5. Relationship To Internet Addresses Domains . . . . . 28 118 6.3. Internet Address Properties vs. PID Properties . . . . . 28 119 7. Property Map . . . . . . . . . . . . . . . . . . . . . . . . 29 120 7.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 29 121 7.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 29 122 7.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 29 123 7.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . 29 124 7.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 29 125 7.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 30 126 8. Filtered Property Map . . . . . . . . . . . . . . . . . . . . 31 127 8.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 31 128 8.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 31 129 8.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 31 130 8.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . 32 131 8.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 32 132 8.6. Filtered Property Map Response . . . . . . . . . . . . . 32 133 8.7. Entity property type defined in this document . . . . . . 34 134 8.7.1. Entity Property Type: pid . . . . . . . . . . . . . . 34 135 9. Impact on Legacy ALTO Servers and ALTO Clients . . . . . . . 34 136 9.1. Impact on Endpoint Property Service . . . . . . . . . . . 35 137 9.2. Impact on Resource-Specific Properties . . . . . . . . . 35 138 9.3. Impact on Other Properties . . . . . . . . . . . . . . . 35 139 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 35 140 10.1. Network Map . . . . . . . . . . . . . . . . . . . . . . 35 141 10.2. Property Definitions . . . . . . . . . . . . . . . . . . 36 142 10.3. Information Resource Directory (IRD) . . . . . . . . . . 37 143 10.4. Full Property Map Example . . . . . . . . . . . . . . . 39 144 10.5. Filtered Property Map Example #1 . . . . . . . . . . . . 40 145 10.6. Filtered Property Map Example #2 . . . . . . . . . . . . 41 146 10.7. Filtered Property Map Example #3 . . . . . . . . . . . . 43 147 10.8. Filtered Property Map Example #4 . . . . . . . . . . . . 44 148 10.9. Filtered Property Map for ANEs Example #5 . . . . . . . 45 149 11. Security Considerations . . . . . . . . . . . . . . . . . . . 46 150 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 151 12.1. application/alto-* Media Types . . . . . . . . . . . . . 48 152 12.2. ALTO Entity Domain Type Registry . . . . . . . . . . . . 50 153 12.2.1. Consistency Procedure between ALTO Address Type 154 Registry and ALTO Entity Domain Type Registry . . . . 51 155 12.2.2. ALTO Entity Domain Type Registration Process . . . . 52 156 12.3. ALTO Entity Property Type Registry . . . . . . . . . . . 54 157 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55 158 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 159 14.1. Normative References . . . . . . . . . . . . . . . . . . 55 160 14.2. Informative References . . . . . . . . . . . . . . . . . 56 161 Appendix A. Features introduced with the Entity Property Maps 162 extension . . . . . . . . . . . . . . . . . . . . . . . . 57 163 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58 165 1. Introduction 167 The ALTO protocol [RFC7285] introduces the concept of "properties" 168 attached to "endpoint addresses", and defines the Endpoint Property 169 Service (EPS) to allow ALTO clients to retrieve those properties. 170 While useful, the EPS, as defined in [RFC7285], has at least three 171 limitations. 173 First, the EPS allows properties to be associated with only endpoints 174 that are identified by individual communication addresses like IPv4 175 and IPv6 addresses. It is reasonable to think that collections of 176 endpoints, as defined by CIDRs [RFC4632] or PIDs, may also have 177 properties. Furthermore, recent ALTO use cases show that properties 178 of entities such as network flows [RFC7011] and routing elements 179 [RFC7921] are also useful. Such cases are documented in 180 [I-D.gao-alto-fcs]. The current EPS however is restricted to 181 individual endpoints and cannot be applied to those entities. 183 Second, the EPS only allows endpoints identified by global 184 communication addresses. However, an endpoint address may be a local 185 IP address or an anycast IP address that may not be globally unique. 186 Additionally, an entity such as a PID may have an identifier that is 187 not globally unique. That is, a same PID identifier may be used in 188 multiple network maps, while in each network map, this PID identifier 189 points to a different set of addresses. For example, PID "mypid10" 190 may be defined in "netmap1" and "netmap2" while in each network map, 191 "mypid10" covers a different set of addresses. 193 Third, the EPS is only defined as a POST-mode service. Clients must 194 request the properties for an explicit set of endpoint addresses. By 195 contrast, [RFC7285] defines a GET-mode cost map resource which 196 returns all available costs, so a client can get a full set of costs 197 once, and then process cost lookups without querying the ALTO server. 198 [RFC7285] does not define a similar service for endpoint properties. 199 At first, a map of endpoint properties might seem impractical, 200 because it could require enumerating the property value for every 201 possible endpoint. However, in practice, it is highly unlikely that 202 properties will be defined for every endpoint address. It is much 203 more likely that properties may be defined for only a subset of 204 endpoint addresses, and the specification of properties uses an 205 aggregation representation to allow enumeration. This is 206 particularly true if blocks of endpoint addresses with a common 207 prefix (e.g., a CIDR) have the same value for a property. Entities 208 in other domains may very well allow aggregated representation and 209 hence be enumerable as well. 211 To address the three limitations, this document specifies a protocol 212 extension for defining and retrieving ALTO properties: 214 * The first limitation is addressed by introducing a generic concept 215 called ALTO Entity, which generalizes an endpoint and may 216 represent a PID, a network element, a cell in a cellular network, 217 an abstracted network element as defined in 218 [I-D.ietf-alto-path-vector], or other physical or logical objects 219 involved in a network topology. Each entity is included in a 220 collection called an ALTO Entity Domain. Since each ALTO Entity 221 Domain includes only one type of entities, each Entity Domain can 222 be classified by the type of entities in it. 224 * The second limitation is addressed by using resource-specific 225 entity domains. A resource-specific entity domain contains 226 entities that are defined and identified with respect to a given 227 ALTO information resource, which provides scoping. For example, 228 an entity domain containing PIDs is identified with respect to the 229 network map in which these PIDs are defined. Likewise, an entity 230 domain containing local IP addresses may be defined with respect 231 to a local network map. 233 * The third limitation is addressed by defining two new types of 234 ALTO information resources: Property Map, detailed in Section 7 235 and Filtered Property Map, detailed in Section 8. The former is a 236 GET-mode resource that returns the property values for all 237 entities in one or more entity domains, and is analogous to a 238 network map or a cost map in [RFC7285]. The latter is a POST-mode 239 resource that returns the values for sets of properties and 240 entities requested by the client, and is analogous to a filtered 241 network map or a filtered cost map. 243 The protocol extension defined in this document is augmentable. New 244 entity domain types can be defined without revising the specification 245 defined in this document. Similarly, new cost metrics and new 246 endpoint properties can be defined in other documents without 247 revising the protocol specification defined in [RFC7285]. 249 1.1. Terminology 251 This document uses the following terms and abbreviations, that will 252 be further defined in the document. While this document introduces 253 the feature "entity property map", it will use both the term 254 "property map" and "entity property map" to refer to this feature. 256 * Transaction: A request/response exchange between an ALTO client 257 and an ALTO server. 259 * Client: When used with a capital "C", this term refers to an ALTO 260 client. Note that expressions "ALTO client" and "ALTO Client" are 261 equivalent. 263 * Server: When used with a capital "S", this term refers to an ALTO 264 server. Note that expressions "ALTO server" and "ALTO Server" are 265 equivalent. 267 * EPM: An abbreviation for entity property map. 269 * FPM: An abbreviation for filtered property map. 271 * EPS: An abbreviation for Endpoint Property Service. 273 2. Requirements Language 275 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 276 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 277 "OPTIONAL" in this document are to be interpreted as described in BCP 278 14 [RFC2119] [RFC8174] when, and only when, they appear in all 279 capitals, as shown here. When the words appear in lower case, they 280 are to be interpreted with their natural language meanings. 282 3. Basic Features of the Entity Property Map Extension 284 This section gives a high-level overview of the basic features 285 involved in ALTO Entity Property Maps. It assumes the reader is 286 familiar with the ALTO protocol [RFC7285]. The purpose of this 287 extension is to allow conveying properties on objects that extend 288 ALTO Endpoints and are called ALTO Entities, or entities for short. 290 The features introduced in this section can be used as standalone. 291 However, in some cases, these features may depend on particular 292 information resources and need to be defined with respect to them. 293 To this end, Section 4 introduces additional features that extend the 294 ones presented in the present section. 296 The Entity Property Maps extension described in this document 297 introduces a number of features that are summarized in Appendix A, 298 where Table 4 lists the features and references the sections in this 299 document that give a high-level and normative description thereof. 301 3.1. Entity 303 The concept of an ALTO Entity generalizes the concept of an ALTO 304 Endpoint defined in Section 2.1 of [RFC7285]. An entity is an object 305 that can be an endpoint that is defined by its network address, but 306 can also be an object that has a defined mapping to a set of one or 307 more network addresses or an object that is not even related to any 308 network address. Thus, whereas all endpoints are entities, not all 309 entities are endpoints. 311 Examples of entities are: 313 * an ALTO endpoint, defined in [RFC7285], that represents an 314 application or a host identified by a communication address (e.g., 315 an IPv4 or IPv6 address) in a network, 317 * a PID, defined in [RFC7285], that has a provider defined human- 318 readable identifier specified by an ALTO network map, which maps a 319 PID to a set of IPv4 and IPv6 addresses, 321 * an autonomous system (AS), that has an AS number (ASN) as its 322 identifier and maps to a set of IPv4 and IPv6 addresses, 324 * a country with a code as specified in [ISO3166-1], to which 325 applications such as CDN providers associate properties and 326 capabilities, 328 * a TCP/IP network flow, that is identified by a TCP/IP 5-Tuple 329 specifying its source and destination addresses and port numbers 330 and the utilized protocol, 332 * a routing element, that is specified in [RFC7921] and is 333 associated with routing capabilities information, 335 * an abstract network element, that represents an abstraction of a 336 network part such as a router, one or more links, a network domain 337 or their aggregation. 339 3.2. Entity Domain 341 An entity domain defines a set of entities of the same semantic type. 342 An entity domain is characterized by its type and identified by its 343 name. 345 In this document, an entity is owned by exactly one entity domain 346 name. An entity identifier points to exactly one entity. If two 347 entities in two different entity domains refer to the same physical 348 or logical object, they are treated as different entities. For 349 example, if an end host has both an IPv4 and an IPv6 address, these 350 two addresses will be treated as two entities, defined respectively 351 in the "ipv4" and "ipv6" entity domains. 353 3.2.1. Entity Domain Type 355 The type of an entity domain type defines the semantics of a type of 356 entity. Entity domain types can be defined in different documents. 357 For example: the present document defines entity domain types "ipv4", 358 "ipv6" and "pid" in sections Section 6.1 and Section 6.2. The entity 359 domain type "ane", that defines Abstract Network Elements (ANEs), is 360 introduced in [I-D.ietf-alto-path-vector]. The entity domain type 361 that defines country codes is introduced in 362 [I-D.ietf-alto-cdni-request-routing-alto]. An entity domain type 363 MUST be registered at the IANA, as specified in section 364 Section 12.2.2 and similarly to an ALTO address type. 366 3.2.2. Entity Domain Name 368 The name of an entity domain is defined in the scope of an ALTO 369 server. An entity domain name can sometimes be identical to the name 370 of its relevant entity domain type. This is the case when the 371 entities of a domain have an identifier that points to the same 372 object throughout all the information resources of the Server that 373 provide entity properties for this domain. For example, a domain of 374 type "ipv4" containing entities identified by a public IPv4 address 375 can be named "ipv4" because its entities are uniquely identified by 376 all the Server resources. 378 In some cases the name of an entity domain needs to be different from 379 simply its entity domain type. Indeed, for some domain types, 380 entities are defined relative to a given information resource. This 381 is the case for entities of domain type "pid". A PID is defined 382 relative to a network map. For example: an entity "mypid10" of 383 domain type "pid" may be defined in a given network map and be 384 undefined in other network maps. Or "mypid10" may even be defined in 385 two different network maps and map, in each of these network maps, to 386 a different set of endpoint addresses. In this case, naming an 387 entity domain only by its type "pid" does not guarantee that its set 388 of entities is owned by exactly one entity domain. 390 Section 4.2 and Section 5.1.2 of this document describe how a domain 391 is uniquely identified, across the ALTO Server, by a name that 392 associates the domain type and the related information resource. 394 3.3. Entity Property Type 396 An entity property defines a property of an entity. This is similar 397 to the endpoint property defined in Section 7.1 of [RFC7285]. An 398 entity property can convey either network-aware or network-agnostic 399 information. Similarly to an entity domain, an entity property is 400 characterized by its type and identified by its name. An entity 401 property type MUST be registered at the IANA, as specified in section 402 Section 12.3. 404 Below are some examples with real and fictitious entity domain and 405 property names: 407 * an entity in the "ipv4" domain type may have a property whose 408 value is an Autonomous System (AS) number indicating the AS that 409 owns this IPv4 address and another property named "countrycode" 410 indicating a country code mapping to this address, 412 * an entity identified by its country code in the entity domain type 413 "countrycode", defined in 414 [I-D.ietf-alto-cdni-request-routing-alto] may have a property 415 indicating what delivery protocol is used by a CDN, 417 * an entity in the "netmap1.pid" domain may have a property that 418 indicates the central geographical location of the endpoints it 419 includes. 421 It should be noted that some identifiers may be used for both an 422 entity domain type and a property type. For example: 424 * the identifier "countrycode" may point to both the entity domain 425 type "countrycode" and the fictitious property type "countrycode". 427 * the identifier "pid" may point to both the entity domain type 428 "pid" and the property type "pid". 430 Likewise, a same identifier may point to both a domain name and a 431 property name. For example: the identifier "netmap10.pid" may point 432 to either the domain defined by the PIDs of network map "netmap10" or 433 to a property that returns, for an entity defined by its IPv4 434 address, the PID of netmap10 that contains this entity. Such cases 435 will be further explained in Section 4. 437 3.4. New information resource and media type: ALTO Property Map 439 This document introduces a new ALTO information resource named 440 Property Map. An ALTO property map provides a set of properties on 441 one or more sets of entities. A property may apply to different 442 entity domain types and names. For example, an ALTO property map may 443 define the "ASN" property for both "ipv4" and "ipv6" entity domains. 445 The present extension also introduces a new media type. 447 This document uses the same definition of an information resource as 448 Section 9.1 of [RFC7285]. ALTO uses media types to uniquely indicate 449 the data format used to encode the content to be transmitted between 450 an ALTO server and an ALTO client in the HTTP entity body. In the 451 present case, an ALTO property map resource is defined by the media 452 type "application/alto-propmap+json". 454 A Property Map can be queried as a GET-mode resource, thus conveying 455 all properties on all entities indicated in its capabilities. It can 456 also be queried as a POST-mode resource, thus conveying a selection 457 of properties on a selection of entities. 459 4. Advanced Features of the Entity Property Map Extension 461 This section gives a high-level overview of the advanced features 462 involved in ALTO Entity Property Maps. Most of these features are 463 defined to extend the ones defined in Section 3. 465 4.1. Entity Identifier and Entity Domain Name 467 In [RFC7285], an endpoint has an identifier that is explicitly 468 associated with the "ipv4" or "ipv6" address domain. Examples are 469 "ipv4:192.0.2.14" and "ipv6:2001:db8::12". 471 In this document, an entity must be owned by exactly one entity 472 domain name and an entity identifier must point to exactly one 473 entity. To ensure this, an entity identifier is explicitly attached 474 to the name of its entity domain and an entity domain type 475 characterizes the semantics and identifier format of its entities. 477 The encoding format of an entity identifier is further specified in 478 Section 5.1.3 of this document. 480 For instance: 482 * if an entity is an endpoint with example routable IPv4 address 483 "192.0.2.14", its identifier is associated with domain name "ipv4" 484 and is "ipv4:192.0.2.14", 486 * if an entity is a PID named "mypid10" in network map resource 487 "netmap2", its identifier is associated with domain name 488 "netmap2.pid" and is "netmap2.pid:mypid10". 490 4.2. Resource-Specific Entity Domain Name 492 Some entities are defined and identified uniquely and globally. This 493 is the case for instance when entities are endpoints that are 494 identified by a routable IPv4 or IPv6 address. The entity domain for 495 such entities can be globally defined and named "ipv4" or "ipv6". 496 Those entity domains are called resource-agnostic entity domains in 497 this document, as they are not associated with any specific ALTO 498 information resources. 500 Some other entities and entity types are only defined relatively to a 501 given information resource. This is the case for entities of domain 502 type "pid", that can only be understood with respect to the network 503 map where they are defined. For example, a PID named "mypid10" may 504 be defined to represent a set S1 of IP addresses in a network map 505 resource named "netmap1". Another network map "netmap2" may use the 506 same name "mypid10" and define it to represent another set S2 of IP 507 addresses. The identifier "pid:mypid10" may thus point to different 508 objects because the information on the originating information 509 resource is lost. 511 To solve this ambiguity, the present extension introduces the concept 512 of resources-specific entity domain. This concept applies to domain 513 types where entities are defined relatively to a given information 514 resource. It can also apply to entity domains that are defined 515 locally, such as local networks of objects identified with a local 516 IPv4 address. 518 In such cases, an entity domain type is explicitly associated with an 519 identifier of the information resource where these entities are 520 defined. Such an information resource is referred to as the 521 "specific information resource". Using a resource-aware entity 522 domain name, an ALTO property map can unambiguously identify distinct 523 entity domains of the same type, on which entity properties may be 524 queried. Examples of resource-specific entity domain names may look 525 like: "netmap1.pid" or "netmap2.pid". Thus, a name association such 526 as "netmap1.pid:mypid10" and "netmap2.pid:mypid10" allows to 527 distinguish the two abovementioned PIDs that are both named "mypid10" 528 but in two different resources, "netmap1" and "netmap2". 530 An information resource is defined in the scope of an ALTO Server and 531 so is an entity domain name. The format of a resource-specific 532 entity domain name is further specified in Section 5.1.2. 534 4.3. Resource-Specific Entity Property Value 536 Like entity domains, some types of properties are defined relatively 537 to an information resource. That is, an entity may have a property 538 of a given type, whose values are associated to different information 539 resources. 541 For example, suppose entity "192.0.2.34" defined in the "ipv4" domain 542 has a property of type "pid", whose value is the PID to which address 543 "192.0.2.34" is attached in a network map. The mapping of network 544 addresses to PIDs is specific to a network map and probably different 545 from one network map resource to another one. Thus, if a property 546 "pid" is defined for entity "192.0.2.34" in two different network 547 maps "netmap1" and "netmap2", the value for this property will likely 548 be a different value in "netmap1" and "netmap2". 550 To support information resource dependent property values, this 551 document uses the same approach as in Section 10.8.1 of [RFC7285] 552 entitled "Resource-Specific Endpoint Properties". When a property 553 value depends on a given information resource, the name of this 554 property MUST be explicitly associated with the information resource 555 that defines it. 557 For example, the property "pid" queried on entity "ipv4:192.0.2.34" 558 and defined in both "netmap1" and "netmap2", can be named 559 "netmap1.pid" and "netmap2.pid". This allows a Client to get a 560 property of the same type but defined in different information 561 resources with a single query. Specifications on the property name 562 format are provided in Section 5.2. 564 4.4. Entity Hierarchy and Property Inheritance 566 For some domain types, entities can be grouped in a set and be 567 defined by the identifier of this set. This is the case for domain 568 types "ipv4" and "ipv6", where individual Internet addresses can be 569 grouped in blocks. When a same property value applies to a whole 570 set, a Server can define a property for the identifier of this set 571 instead of enumerating all the entities and their properties. This 572 allows a substantial reduction of transmission payload both for the 573 Server and the Client. For example, all the entities included in the 574 set defined by the address block "ipv6:2001:db8::1/64" share the same 575 properties and values defined for this block. 577 Additionally, entity sets sometimes are related by inclusion, 578 hierarchy or other relations. This allows defining inheritance rules 579 for entity properties that propagate properties among related entity 580 sets. The Server and the Client can use these inheritance rules for 581 further payload savings. Entity hierarchy and property inheritance 582 rules are specified in the documents that define the applicable 583 domain types. The present document defines these rules for the 584 "ipv4" and "ipv6" domain types. 586 This document introduces, for applicable domain types, "Entity 587 Property Inheritance rules", with the following concepts: Entity 588 Hierarchy, Property Inheritance and Property Value Unicity. A 589 detailed specification of entity hierarchy and property inheritance 590 rules is provided in Section 5.1.4. 592 4.4.1. Entity Hierarchy 594 An entity domain may allow using a single identifier to identify a 595 set of individual entities. For example, a CIDR block can be used to 596 identify a set of IPv4 or IPv6 entities. A CIDR block is called a 597 hierarchical entity identifier, as it can reflect inclusion relations 598 among entity sets. That is, in an entity hierarchy, "supersets" are 599 defined at upper levels and include "subsets" defined at lower 600 levels." For example, the CIDR "ipv4:192.0.1.0/24" includes all the 601 individual IPv4 entities identified by the CIDR "ipv4:192.0.1.0/26". 603 4.4.2. Property Inheritance 605 A property may be defined for a hierarchical entity identifier, while 606 it may be undefined for individual entities covered by this 607 identifier. In this case, these individual entities inherit the 608 property value defined for the identifier that covers them. For 609 example, suppose a property map defines a property P for which it 610 assigns value V1 only for the hierarchical entity identifier 611 "ipv4:192.0.1.0/24" but not for individual entities in this block. 612 Suppose also that inheritance rules are specified for CIDR blocks in 613 the "ipv4" domain type. When receiving this property map, a Client 614 can infer that entity "ipv4:192.0.1.1" inherits the property value V1 615 of block "ipv4:192.0.1.0/24" because the address "ipv4:192.0.1.1" is 616 included in the CIDR block "ipv4:192.0.1.0/24". 618 Property value inheritance rules also apply among entity sets. A 619 property map may define values for an entity set belonging to a 620 hierarchy but not for "subsets" that are covered by this set 621 identifier. In this case, inheritance rules must specify how 622 entities in "subsets" inherit property values from their "superset". 623 For instance, if a property P is defined only for the entity set 624 identified by address block "ipv4:192.0.1.0/24", the entity set 625 identified by "ipv4:192.0.1.0/30" and thus included in the former 626 set, may inherit the property P value from set "ipv4:192.0.1.0/24". 628 4.4.3. Property Value Unicity 630 The inheritance rules must ensure that an entity belonging to a 631 hierarchical set of entities inherits no more than one property 632 value, for the sake of consistency. Indeed, a property map may 633 define a property on a hierarchy of entity sets that inherit property 634 values from one or more supersets (located at upper levels). On the 635 other hand, a property value, defined on a subset (located at a lower 636 level) may be different from the value defined on a superset. In 637 such a case, subsets may potentially end up with different property 638 values. This may be the case for address blocs with increasing 639 prefix length, on which a property value gets increasingly accurate 640 and thus may differ. For example, a fictitious property such as 641 "geo-location" or "average transfer volume" may be defined at a 642 progressively finer grain for lower level subsets of entities, 643 defined with progressively longer CIDR prefixes. It seems more 644 interesting to have property values of progressively higher accuracy. 645 A unicity rule, applied to the entity domain type must specify an 646 arbitration rule among the different property values for an entity. 647 An example illustrating the need for such rules is provided in 648 Section 6.1.3. 650 4.5. Supported Properties on Entity Domains in Property Map 651 Capabilities 653 A property type is not necessarily applicable to any domain type, or 654 an ALTO Server may choose not to provide a property on all applicable 655 domains. For instance, a property type reflecting link bandwidth is 656 likely not defined on entities of a domain of type "country-code". 657 Therefore an ALTO server providing Property Maps needs to specify the 658 properties that can be queried on the different entity domains it 659 supports. 661 This document explains how the Information Resources Directory (IRD) 662 capabilities of a Property Map resource unambiguously expose what 663 properties a Client can query on a given entity domain. 665 * a field named "mappings" lists the names of the entity domains 666 supported by the Property Map, 668 * for each listed entity domain, a list of the names of the 669 applicable properties is provided. 671 An example is provided in Section 10.3. The "mappings" field 672 associates entity domains and properties that can be resource- 673 agnostic or resource-specific. This allows a Client to formulate 674 compact and unambiguous entity property queries, possibly relating to 675 one or more information resources. In particular: 677 * it avoids a Client to query a property on entity domains on which 678 it is not defined, 680 * it allows a Client to query, for an entity E, values for a 681 property P that are defined in several information resources, 683 * it allows a Client to query a property P on entities that are 684 defined in several information resources. 686 Further specifications are provided in Section 7.4. 688 4.6. Defining Information Resource for Resource-Specific Entity Domains 690 A Client willing to query properties on entities belonging to a 691 domain needs to know how to retrieve these entities. To this end, 692 the Client can look up the "mappings" field exposed in IRD 693 capabilities of a property map, see Section 4.5. This field, in its 694 keys, exposes all the entity domains supported by the property map. 695 The syntax of the entity domain identifier specified in Section 5.1.2 696 allows the client to infer whether the entity domain is resource- 697 specific or not. The Client can extract, if applicable, the 698 identifier of the specific resource, query the resource and retrieve 699 the entities. For example: 701 * an entity domain named "netmap1.ipv4" includes the IPv4 addresses 702 that appear in the "ipv4" field of the endpoint address group of 703 each PID in the network map "netmap1", and that cannot be 704 recognized outside "netmap1" because, for instance, these are 705 local non-routable addresses, 707 * an entity domain named "netmap1.pid" includes the PIDs listed in 708 network map "netmap1". 710 * an entity domain named "ipv4" is resource-agnostic and covers all 711 the routable IPv4 addresses. 713 Besides, it is also necessary to inform a Client about which 714 associations of specific resources and entity domain types are 715 allowed, because it is not possible to prevent a Server from exposing 716 inappropriate associations. An informed Client will just ignore 717 inappropriate associations exposed by a Server and avoid error-prone 718 transactions with the Server. 720 For example, the association "costmap3.pid" is not allowed for the 721 following reason: although a cost map exposes PID identifiers, it 722 does not define the set of addresses included in this PID. Neither 723 does a cost map list all the PIDs on which properties can be queried, 724 because a cost map only exposes PID pairs on which a queried cost 725 type is defined. Therefore, the resource "costmap3" does not enable 726 a Client to extract information on the existing PID entities or on 727 the addresses they contain. 729 Instead, the cost map uses a network map, where all the PIDs used in 730 a cost map are defined together with the addresses contained by the 731 PIDs. This network map is qualified in this document as the Defining 732 Information Resource for the entity domain of type "pid" and this 733 concept is explained in Section 4.6.1. 735 4.6.1. Defining Information Resource and its Media Type 737 For the reasons explained in the previous section, this document 738 introduces the concept of "Defining Information Resource and its 739 Media Type". 741 A defining information resource for an entity domain D is the 742 information resource where entities of D are defined. That is, all 743 the information on the entities of D can be retrieved in this 744 resource. This concept applies to resource-specific entity domains. 745 This is useful for entity domain types that are by essence domain- 746 specific, such as "pid" and "ane" domain types. It is also useful 747 for resource-specific entity domains constructed from resource- 748 agnostic domain types, such as network map specific domains of local 749 IPv4 addresses. 751 The defining information resource of a resource-specific entity 752 domain D is unique and has the following specificities: 754 * it has an entry in the IRD, 756 * it defines the entities of D, 758 * it does not use another information resource that defines these 759 entities, 761 * it defines and exposes entity identifiers that are all persistent. 763 * its media type is unique and equal to the one that is specified 764 for the defining information resource of an entity domain type. 766 A fundamental attribute of a defining information resource is its 767 media type. There is a unique association between an entity domain 768 type and the media type of its defining information resource. When 769 an entity domain type allows associations with defining information 770 resources, the media type of the potential defining information 771 resource MUST be specified: 773 * in the document that defines this entity domain type, 775 * in the IANA ALTO Entity Domain Type Registry and related 776 information. 778 When the Client wants to use a resource-specific entity domain, it 779 needs to be cognizant of the media-type of its defining information 780 resource. If the Server exposes a resource-specific entity domain 781 with a non-compliant media type for the defining resource, the Client 782 MUST ignore the entities from that entity domain to avoid errors. 784 4.6.2. Examples of Defining Information Resources and Their Media Types 786 Here are examples of defining information resource types and their 787 media types associated to different entity domain types. 789 * For entity domain type "pid": the media type of the specific 790 resource is "application/alto-networkmap+json", because PIDs are 791 defined in network map resources. 793 * For entity domain types "ipv4" and "ipv6": the media type of the 794 specific resource is "application/alto-networkmap+json", because 795 IPv4 and IPv6 addresses covered by the Server are defined in 796 network map resources. 798 * For entities of domain type "ane": [I-D.ietf-alto-path-vector] 799 defines entities named "ANE", where ANE stands for Abstracted 800 Network Element, and the entity domain type "ane". An ANE may 801 have a persistent identifier, say, "entity-4", that is provided by 802 the Server as a value of the "persistent-entity-id" property of 803 this ANE. Further properties may then be queried on an ANE by 804 using its persistent entity ID. These properties are available 805 from a persistent property map, that defines properties on a 806 specific "ane" domain. Together with the persistent identifier, 807 the Server also provides the property map resource identifier 808 where the "ane" domain containing "entity-4" is defined. The 809 definition of the "ane" entity domain containing "entity-4" is 810 thus specific to the property map. Therefore, for entities of 811 domain type "ane" that have a persitent identifier, the media type 812 of the specific information resource is "application/alto- 813 propmap+json". 815 * Last, the entity domain types "asn" and "countrycode" defined in 816 [I-D.ietf-alto-cdni-request-routing-alto] do not have a defining 817 information resource. Indeed, the entity identifiers in these two 818 entity domain types are already standardized in documents that the 819 Client can use. 821 4.7. Defining Information Resource for Resource-Specific Property 822 Values 824 As explained in Section 4.3, a property type may take values that are 825 resource-specific. This is the case for property type "pid", whose 826 values are by essence defined relatively to a specific network map. 827 That is, the PID value returned for an IPv4 address is specific to 828 the network map defining this PID and may differ from one network map 829 to another one. 831 Another example is provided in 832 [I-D.ietf-alto-cdni-request-routing-alto] that defines property type 833 "cdni-capabilities". The value of this property is specific to a 834 CDNI Advertisement resource, that provides a list of CDNI 835 capabilities. The property is provided for entity domain types 836 "ipv4", "ipv6", "asn" and "countrycode". A CDNI Advertisement 837 resource does however not define PID values for IPv4 addresses while 838 a network map does not define CDNI capabilities for IPv4 addresses. 840 Similarly to resource-specific entity domains, the Client needs to be 841 cognizant of appropriate associations of information resource and 842 property types. Therefore, when specifying and registering a 843 property type whose values are resource-specific, the media type of 844 its defining information resource needs to be specified. For 845 example: 847 * The media type of the defining information resource for property 848 type "pid" is "application/alto-networkmap+json". 850 * The media type of the defining information resource for property 851 type "cdni-capabilities" defined in 852 [I-D.ietf-alto-cdni-request-routing-alto] is "application/alto- 853 cdni+json". 855 5. Protocol Specification: Basic Data Types 857 5.1. Entity Domain 859 5.1.1. Entity Domain Type 861 An entity domain has a type, which is uniquely identified by a string 862 that MUST be no more than 64 characters, and MUST NOT contain 863 characters other than US-ASCII alphanumeric characters 864 (U+0030-U+0039, U+0041-U+005A, and U+0061-U+007A), the hyphen ('-', 865 U+002D), or the low line ('_', U+005F). 867 For example, the strings "ipv4", "ipv6", and "pid" are valid entity 868 domain types. "ipv4.anycast" and "pid.local" are invalid. 870 The type EntityDomainType is used in this document to denote a JSON 871 string meeting the preceding requirements. 873 An entity domain type defines the semantics of a type of entity, 874 independently of any specifying resource. Each entity domain type 875 MUST be registered with the IANA, following the procedure specified 876 in Section 12.2.2 of this document. The format of the entity 877 identifiers (see Section 5.1.3) in that type of entity domain, as 878 well as any hierarchical or inheritance rules (see Section 5.1.4) for 879 those entities, MUST be specified at the same time. 881 5.1.2. Entity Domain Name 883 As said in Section 3.2 when introducing entity domains, an entity 884 domain is characterized by its type and identified by its name. 886 This document distinguishes three categories of entity domains: 887 resource-specific entity domains, resource-agnostic entity domains 888 and self-defined entity domains. Their entity domain names are 889 constructed as specified in the following sub-sections. 891 Each entity domain is identified by a unique entity domain name which 892 is a string of the following format: 894 EntityDomainName ::= [ [ ResourceID ] '.' ] EntityDomainType 896 Where the presence and construction of component: 898 "[ [ ResourceID ] '.' ]" 900 depends on the category of entity domain. 902 Note that the '.' separator is not allowed in EntityDomainType and 903 hence there is no ambiguity on whether an entity domain name refers 904 to a resource-agnostic entity domain or a resource-specific entity 905 domain. 907 Note also that Section 10.1 of [RFC7285] specifies the format of the 908 PID Name which is the format of the resource ID including the 909 following specification: "the '.' separator is reserved for future 910 use and MUST NOT be used unless specifically indicated in this 911 document, or an extension document". The present extension keeps the 912 format specification of [RFC7285], hence the '.' separator MUST NOT 913 be used in an information resource ID. 915 5.1.2.1. Resource-specific Entity Domain 917 A resource-specific entity domain is identified by an entity domain 918 name constructed as follows. It MUST start with a resource ID using 919 the ResourceID type defined in Section 10.2 of [RFC7285], followed by 920 the '.' separator (U+002E), followed by a string of the type 921 EntityDomainType specified in Section 5.1.1. 923 For example, if an ALTO server provides two network maps "netmap-1" 924 and "netmap-2", these network maps can define two resource-specific 925 domains of type "pid", respectively identified by "netmap-1.pid" and 926 "netmap-2.pid". 928 5.1.2.2. Resource-agnostic Entity Domain 930 A resource-agnostic entity domain contains entities that are 931 identified independently of any information resource. Hence, the 932 identifier of a resource-agnostic entity domain is simply the 933 identifier of its entity domain type. For example, "ipv4" and "ipv6" 934 identify the two resource-agnostic Internet address entity domains 935 defined in Section 6.1. 937 5.1.2.3. Self-defined Entity Domain 939 A property map can define properties on entities that are specific to 940 a unique information resource, which is the property map itself. 941 This may be the case when an ALTO Server provides properties on a set 942 of entities that are defined only in this property map, are not 943 relevant to another one and do not depend on another specific 944 resource. 946 For example: a specialised property map may define a domain of type 947 "ane", defined in [I-D.ietf-alto-path-vector], that contains a set of 948 ANEs representing data centers, that each have a persistent 949 identifier and are relevant only to this property map. 951 In this case, the entity domain is qualified as "self-defined". The 952 identifier of a self-defined entity domain can be of the format: 954 EntityDomainName ::= '.' EntityDomainType 956 where '.' indicates that the entity domain only exists within the 957 property map resource using it. 959 A self-defined entity domain can be viewed as a particular case of 960 resource-specific entity domain, where the specific resource is the 961 current resource that uses this entity domain. In that case, for the 962 sake of simplification, the component "ResourceID" SHOULD be omitted 963 in its entity domain name. 965 5.1.3. Entity Identifier 967 Entities in an entity domain are identified by entity identifiers 968 (EntityID) of the following format: 970 EntityID ::= EntityDomainName ':' DomainTypeSpecificEntityID 972 Examples from the Internet address entity domains include individual 973 IP addresses such as "net1.ipv4:192.0.2.14" and 974 "net1.ipv6:2001:db8::12", as well as address blocks such as 975 "net1.ipv4:192.0.2.0/26" and "net1.ipv6:2001:db8::1/48". 977 The format of the second part of an entity identifier depends on the 978 entity domain type, and MUST be specified when defining a new entity 979 domain type and registering it with the IANA. Identifiers MAY be 980 hierarchical, and properties MAY be inherited based on that 981 hierarchy. The rules defining any hierarchy or inheritance MUST be 982 defined when the entity domain type is registered. 984 The type EntityID is used in this document to denote a JSON string 985 representing an entity identifier in this format. 987 Note that two entity identifiers with different valid textual 988 representations may refer to the same entity, for a given entity 989 domain. For example, the strings "net1.ipv6:2001:db8::1" and 990 "net1.ipv6:2001:db8:0:0:0:0:0:1" refer to the same entity in the 991 "ipv6" entity domain. Such equivalences should be established by the 992 object represented by DomainTypeSpecificEntityID, for example, 993 [RFC5952] establishes equivalence for IPv6 addresses, while [RFC4632] 994 does so for IPv4 addresses. 996 5.1.4. Hierarchy and Inheritance 998 To simplify the representation, some types of entity domains allow 999 the ALTO Client and Server to use a hierarchical entity identifier 1000 format to represent a block of individual entities. For instance, in 1001 an IPv4 domain "net1.ipv4", a CIDR "net1.ipv4:192.0.2.0/26" covers 64 1002 individual IPv4 entities. In this case, the corresponding property 1003 inheritance rule MUST be defined for the entity domain type. The 1004 hierarchy and inheritance rule MUST have no ambiguity. 1006 5.2. Entity Property 1008 Each entity property has a type to indicate the encoding and the 1009 semantics of the value of this entity property, and has a name to 1010 identify it. 1012 5.2.1. Entity Property Type 1014 The type EntityPropertyType is used in this document to indicate a 1015 string denoting an entity property type. The string MUST be no more 1016 than 32 characters, and it MUST NOT contain characters other than US- 1017 ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and 1018 U+0061-U+007A), the hyphen ('-', U+002D), the colon (':', U+003A), or 1019 the low line ('_', U+005F). Note that the '.' separator is not 1020 allowed because it is reserved to separate an entity property type 1021 and an information resource identifier when an entity property is 1022 resource-specific. 1024 Each entity property type MUST be registered with the IANA, following 1025 the procedure specified in Section 12.3 of this document. The 1026 intended semantics of the entity property type MUST be specified at 1027 the same time. 1029 Identifiers prefixed with "priv:" are reserved for Private Use 1030 [RFC8126] without a need to register with IANA. All other 1031 identifiers for entity property types appearing in an HTTP request or 1032 response with an "application/alto-*" media type MUST be registered 1033 in the "ALTO Entity Property Type Registry", defined in Section 12.3. 1034 For an entity property identifier with the "priv:" prefix, an 1035 additional string (e.g., company identifier or random string) MUST 1036 follow the prefix to reduce potential collisions, that is, the string 1037 "priv:" alone is not a valid endpoint property identifier. 1039 To distinguish from the endpoint property type, the entity property 1040 type has the following characteristics: 1042 * Some entity property types are applicable to entities in 1043 particular entity domain types only. For example, the property 1044 type "pid" is applicable to entities in the entity domain types 1045 "ipv4" or "ipv6" while is not applicable to entities in an entity 1046 domain of type "pid". 1048 * The intended semantics of the value of an entity property may also 1049 depend on the entity domain type. For example, suppose that a 1050 property named "geo-location" is defined as the coordinates of a 1051 point, encoded as: "latitude longitude [altitude]." When applied 1052 to an entity that represents a specific host computer, identified 1053 by an address in an entity domain of type "ipv4" or "ipv6", the 1054 "geo-location" property would define the host's location. 1055 However, when applied to an entity in a "pid" domain type, the 1056 property would indicate the location of the center of all hosts in 1057 this "pid" entity. 1059 5.2.2. Entity Property Name 1061 Each entity property is identified by an entity property name, which 1062 is a string of the following format: 1064 EntityPropertyName ::= [ ResourceID ] '.' EntityPropertyType 1066 Similar to the endpoint property type defined in Section 10.8 of 1067 [RFC7285], each entity property may be defined by either the property 1068 map itself (self-defined) or some other specific information resource 1069 (resource-specific). 1071 The entity property name of a resource-specific entity property 1072 starts with a string of the type ResourceID defined in [RFC7285], 1073 followed by the '.' separator (U+002E) and a EntityDomainType typed 1074 string. For example, the "pid" properties of an "ipv4" entity 1075 defined by two different maps "net-map-1" and "net-map-2" are 1076 identified by "net-map-1.pid" and "net-map-2.pid" respectively. 1078 The specific information resource of an entity property may be the 1079 current information resource itself, that is, the property map 1080 defining the property. In that case, the ResourceID in the property 1081 name SHOULD be ignored. For example, the property name ".asn" 1082 applied to an entity identitifed by its IPv4 address, indicates the 1083 AS number of the AS that "owns" the entity, where the returned AS 1084 number is defined by the property map itself. 1086 5.2.3. Format for Entity Property Value 1088 [RFC7285] in Section 11.4.1.6, specifies that an implementation of 1089 the Endpoint Property Service specified in [RFC7285] SHOULD assume 1090 that the property value is a JSONString and fail to parse if it is 1091 not. This document extends the format of a property value by 1092 allowing it to be a JSONValue instead of just a JSONString. 1094 6. Entity Domain Types Defined in this Document 1096 This document requires the definition of each entity domain type MUST 1097 include (1) the entity domain type name and (2) domain-specific 1098 entity identifiers, and MAY include (3) hierarchy and inheritance 1099 semantics optionally. This document defines three initial entity 1100 domain types as follows. 1102 6.1. Internet Address Domain Types 1104 The document defines two entity domain types (IPv4 and IPv6) for 1105 Internet addresses. Both types are resource-agnostic entity domain 1106 types and hence define corresponding resource-agnostic entity domains 1107 as well. Since the two domains use the same hierarchy and 1108 inheritance semantics, we define the semantics together, instead of 1109 repeating for each. 1111 6.1.1. Entity Domain Type: IPv4 1113 6.1.1.1. Entity Domain Type Identifier 1115 ipv4 1117 6.1.1.2. Domain-Specific Entity Identifiers 1119 Individual addresses are strings as specified by the IPv4Addresses 1120 rule of Section 3.2.2 of [RFC3986]; Hierarchical addresses are 1121 prefix-match strings as specified in Section 3.1 of [RFC4632]. To 1122 define properties, an individual Internet address and the 1123 corresponding full-length prefix are considered aliases for the same 1124 entity. An individual Internet address and the corresponding full- 1125 length prefix are considered aliases for the same entity on which to 1126 define properties. Thus, "ipv4:192.0.2.0" and "ipv4:192.0.2.0/32" 1127 are equivalent. 1129 6.1.2. Entity Domain Type: IPv6 1131 6.1.2.1. Entity Domain Type Identifier 1133 ipv6 1135 6.1.2.2. Domain-Specific Entity Identifiers 1137 Individual addresses are strings as specified by Section 4 of 1138 [RFC5952]; Hierarchical addresses are prefix-match strings as 1139 specified in Section 7 of [RFC5952]. To define properties, an 1140 individual Internet address and the corresponding 128-bit prefix are 1141 considered aliases for the same entity. That is, "ipv6:2001:db8::1" 1142 and "ipv6:2001:db8::1/128" are equivalent, and have the same set of 1143 properties. 1145 6.1.3. Hierarchy and Inheritance of Internet Address Domains 1147 Both Internet address domains allow property values to be inherited. 1148 Specifically, if a property P is not defined for a specific Internet 1149 address I, but P is defined for a hierarchical Internet address C 1150 which prefix-matches I, then the address I inherits the value of P 1151 defined for the hierarchical address C. If more than one such 1152 hierarchical addresses define a value for P, I inherits the value of 1153 P in the hierarchical address with the longest prefix. Note that 1154 this longest prefix rule ensures no multiple value inheritances, and 1155 hence no ambiguity. 1157 Hierarchical addresses can also inherit properties: if a property P 1158 is not defined for the hierarchical address C, but is defined for 1159 another hierarchical address C' which covers all IP addresses in C, 1160 and C' has a shorter prefix length than C, then C MAY inherit the 1161 property from C'. If there are multiple such hierarchical addresses 1162 like C', C MUST inherit from the hierarchical address having the 1163 longest prefix length. 1165 As an example, suppose that a server defines a property P for the 1166 following entities: 1168 ipv4:192.0.2.0/26: P=v1 1169 ipv4:192.0.2.0/28: P=v2 1170 ipv4:192.0.2.0/30: P=v3 1171 ipv4:192.0.2.0: P=v4 1173 Figure 1: Defined Property Values. 1175 Then the following entities have the indicated values: 1177 ipv4:192.0.2.0: P=v4 1178 ipv4:192.0.2.1: P=v3 1179 ipv4:192.0.2.16: P=v1 1180 ipv4:192.0.2.32: P=v1 1181 ipv4:192.0.2.64: (not defined) 1182 ipv4:192.0.2.0/32: P=v4 1183 ipv4:192.0.2.0/31: P=v3 1184 ipv4:192.0.2.0/29: P=v2 1185 ipv4:192.0.2.0/27: P=v1 1186 ipv4:192.0.2.0/25: (not defined) 1188 Figure 2: Inherited Property Values. 1190 An ALTO server MAY explicitly indicate a property as not having a 1191 value for a particular entity. That is, a server MAY say that 1192 property P of entity X is "defined to have no value", instead of 1193 "undefined". To indicate "no value", a server MAY perform different 1194 behaviours: 1196 * If that entity would inherit a value for that property, then the 1197 ALTO server MUST return a "null" value for that property. In this 1198 case, the ALTO client MUST recognize a "null" value as "no value" 1199 and "do not apply the inheritance rules for this property." 1201 * If the entity would not inherit a value, then the ALTO server MAY 1202 return "null" or just omit the property. In this case, the ALTO 1203 client cannot infer the value for this property of this entity 1204 from the Inheritance rules. So the client MUST interpret that 1205 this property has no value. 1207 If the ALTO server does not define any properties for an entity, then 1208 the server MAY omit that entity from the response. 1210 6.1.4. Defining Information Resource Media Type for domain types IPv4 1211 and IPv6 1213 Entity domain types "ipv4" and "ipv6" both allow to define resource 1214 specific entity domains. When resource specific domains are defined 1215 with entities of domain type "ipv4" or "ipv6", the defining 1216 information resource for an entity domain of type "ipv4" or "ipv6" 1217 MUST be a Network Map. The media type of a defining information 1218 resource is therefore: 1220 application/alto-networkmap+json 1222 6.2. Entity Domain Type: PID 1224 The PID domain associates property values with the PIDs in a network 1225 map. Accordingly, this entity domain always depends on a network 1226 map. 1228 6.2.1. Entity Domain Type Identifier 1230 pid 1232 6.2.2. Domain-Specific Entity Identifiers 1234 The entity identifiers are the PID names of the associated network 1235 map. 1237 6.2.3. Hierarchy and Inheritance 1239 There is no hierarchy or inheritance for properties associated with 1240 PIDs. 1242 6.2.4. Defining Information Resource Media Type for Domain Type PID 1244 The entity domain type "pid" allows to define resource specific 1245 entity domains. When resource specific domains are defined with 1246 entities of domain type "pid", the defining information resource for 1247 entity domain type "pid" MUST be a Network Map. The media type of a 1248 defining information resource is therefore: 1250 application/alto-networkmap+json 1252 6.2.5. Relationship To Internet Addresses Domains 1254 The PID domain and the Internet address domains are completely 1255 independent; the properties associated with a PID have no relation to 1256 the properties associated with the prefixes or endpoint addresses in 1257 that PID. An ALTO server MAY choose to assign all the properties of 1258 a PID to the prefixes in that PID or only some of these properties. 1260 For example, suppose "PID1" consists of the prefix 1261 "ipv4:192.0.2.0/24", and has the property "P" with value "v1". The 1262 Internet address entities "ipv4:192.0.2.0" and "ipv4:192.0.2.0/24" in 1263 the IPv4 domain MAY have a value for the property "P", and if they 1264 do, it is not necessarily "v1". 1266 6.3. Internet Address Properties vs. PID Properties 1268 Because the Internet address and PID domains relate to completely 1269 distinct domain types, the question may arise as to which entity 1270 domain type is the best for a property. In general, the Internet 1271 address domain types are RECOMMENDED for properties that are closely 1272 related to the Internet address, or are associated with, and 1273 inherited through, hierarchical addresses. 1275 The PID domain type is RECOMMENDED for properties that arise from the 1276 definition of the PID, rather than from the Internet address prefixes 1277 in that PID. 1279 For example, because Internet addresses are allocated to service 1280 providers by blocks of prefixes, an "ISP" property would be best 1281 associated with Internet address domain types. On the other hand, a 1282 property that explains why a PID was formed, or how it relates to a 1283 provider's network, would best be associated with the PID domain 1284 type. 1286 7. Property Map 1288 A property map returns the properties defined for all entities in one 1289 or more domains, e.g., the "location" property of entities in "pid" 1290 domain, and the "ASN" property of entities in "ipv4" and "ipv6" 1291 domains. 1293 Section 10.4 gives an example of a property map request and its 1294 response. 1296 7.1. Media Type 1298 The media type of a property map is "application/alto-propmap+json". 1300 7.2. HTTP Method 1302 The property map is requested using the HTTP GET method. 1304 7.3. Accept Input Parameters 1306 None. 1308 7.4. Capabilities 1310 The capabilities are defined by an object of type 1311 PropertyMapCapabilities: 1313 object { 1314 EntityPropertyMapping mappings; 1315 } PropertyMapCapabilities; 1317 object-map { 1318 EntityDomainName -> EntityPropertyName<1..*>; 1319 } EntityPropertyMapping 1321 with fields: 1323 mappings: A JSON object whose keys are names of entity domains and 1324 values are the supported entity properties of the corresponding 1325 entity domains. 1327 7.5. Uses 1329 The "uses" field of a property map resource in an IRD entry specifies 1330 dependent resources of this property map. It is an array of the 1331 resource ID(s) of the resource(s). 1333 7.6. Response 1335 If the entity domains in this property map depend on other resources, 1336 the "dependent-vtags" field in the "meta" field of the response MUST 1337 be an array that includes the version tags of those resources, and 1338 the order MUST be consistent with the "uses" field of this property 1339 map resource. The data component of a property map response is named 1340 "property-map", which is a JSON object of type PropertyMapData, 1341 where: 1343 object { 1344 PropertyMapData property-map; 1345 } InfoResourceProperties : ResponseEntityBase; 1347 object-map { 1348 EntityID -> EntityProps; 1349 } PropertyMapData; 1351 object { 1352 EntityPropertyName -> JSONValue; 1353 } EntityProps; 1355 The ResponseEntityBase type is defined in Section 8.4 of [RFC7285]. 1357 Specifically, a PropertyMapData object has one member for each entity 1358 in the property map. The entity's properties are encoded in the 1359 corresponding EntityProps object. EntityProps encodes one name/value 1360 pair for each property, where the property names are encoded as 1361 strings of type PropertyName. A protocol implementation SHOULD 1362 assume that the property value is either a JSONString or a JSON 1363 "null" value, and fail to parse if it is not, unless the 1364 implementation is using an extension to this document that indicates 1365 when and how property values of other data types are signaled. 1367 For each entity in the property map: 1369 * If the entity is in a resource-specific entity domain, the ALTO 1370 server SHOULD only return self-defined properties and resource- 1371 specific properties which depend on the same resource as the 1372 entity does. The ALTO client SHOULD ignore the resource-specific 1373 property in this entity if their mapping is not registered in the 1374 ALTO Resource Entity Property Transfer Registry of the type of the 1375 corresponding resource. 1377 * If the entity is in a shared entity domain, the ALTO server SHOULD 1378 return self-defined properties and all resource-specific 1379 properties defined for all resource-specific entities which have 1380 the same domain-specific entity identifier as this entity does. 1382 For efficiency, the ALTO server SHOULD omit property values that are 1383 inherited rather than explicitly defined; if a client needs inherited 1384 values, the client SHOULD use the entity domain's inheritance rules 1385 to deduce those values. 1387 8. Filtered Property Map 1389 A filtered property map returns the values of a set of properties for 1390 a set of entities selected by the client. 1392 Section 10.5, Section 10.6, Section 10.7 and Section 10.8 give 1393 examples of filtered property map requests and responses. 1395 8.1. Media Type 1397 The media type of a property map resource is "application/alto- 1398 propmap+json". 1400 8.2. HTTP Method 1402 The filtered property map is requested using the HTTP POST method. 1404 8.3. Accept Input Parameters 1406 The input parameters for a filtered property map request are supplied 1407 in the entity body of the POST request. This document specifies the 1408 input parameters with a data format indicated by the media type 1409 "application/alto-propmapparams+json", which is a JSON object of type 1410 ReqFilteredPropertyMap: 1412 object { 1413 EntityID entities<1..*>; 1414 EntityPropertyName properties<1..*>; 1415 } ReqFilteredPropertyMap; 1417 with fields: 1419 entities: List of entity identifiers for which the specified 1420 properties are to be returned. The ALTO server MUST interpret 1421 entries appearing multiple times as if they appeared only once. 1422 The domain of each entity MUST be included in the list of entity 1423 domains in this resource's "capabilities" field (see Section 8.4). 1425 properties: List of properties to be returned for each entity. Each 1426 specified property MUST be included in the list of properties in 1427 this resource's "capabilities" field (see Section 8.4). The ALTO 1428 server MUST interpret entries appearing multiple times as if they 1429 appeared only once. Note that the "entities" and "properties" 1430 fields MUST have at least one entry each. 1432 8.4. Capabilities 1434 The capabilities are defined by an object of type 1435 PropertyMapCapabilities, as defined in Section 7.4. 1437 8.5. Uses 1439 Same to the "uses" field of the Property Map resource (see 1440 Section 7.5). 1442 8.6. Filtered Property Map Response 1444 The response MUST indicate an error, using ALTO protocol error 1445 handling, as defined in Section 8.5 of [RFC7285], if the request is 1446 invalid. 1448 Specifically, a filtered property map request can be invalid in the 1449 following cases: 1451 * An entity identifier in the "entities" field of the request is 1452 invalid if: 1454 - The domain of this entity is not defined in the "entity- 1455 domains" capability of this resource in the IRD, 1457 - The entity identifier is not valid for the entity domain. 1459 A valid entity identifier does never generate an error, even if 1460 the filtered property map resource does not define any properties 1461 for it. 1463 If an entity identifier in the "entities" field of the request is 1464 invalid, the ALTO server MUST return an "E_INVALID_FIELD_VALUE" 1465 error defined in Section 8.5.2 of [RFC7285], and the "value" field 1466 of the error message SHOULD indicate the provided invalid entity 1467 identifier. 1469 * A property name in the "properties" field of the request is 1470 invalid if this property name is not defined in the "properties" 1471 capability of this resource in the IRD. 1473 When a filtered property map resource does not define a value for 1474 a property requested on a particular entity, it is not an error. 1475 In this case, the ALTO server MUST omit that property from the 1476 response for that endpoint. 1478 If a property name in "properties" in the request is invalid, the 1479 ALTO server MUST return an "E_INVALID_FIELD_VALUE" error defined 1480 in Section 8.5.2 of [RFC7285]. The "value" field of the error 1481 message SHOULD indicate the property name. 1483 The response to a valid request is the same as for the Property Map 1484 (see Section 7.6), except that: 1486 * If the requested entities include entities in the shared entity 1487 domain, the "dependent-vtags" field in its "meta" field MUST 1488 include version tags of all dependent resources appearing in the 1489 "uses" field. 1491 * If the requested entities only include entities in resource- 1492 specific entity domains, the "dependent-vtags" field in its "meta" 1493 field MUST include the version tags of the resources on which the 1494 requested resource-specific entity domains and the requested 1495 resource-specific properties are dependent on. 1497 * The response only includes the entities and properties requested 1498 by the client. If an entity in the request is identified by a 1499 hierarchical identifier (e.g., a "ipv4" or "ipv6" prefix), the 1500 response MUST cover properties for all identifiers in this 1501 hierarchical identifier. 1503 The filtered property map response MUST include all the inherited 1504 property values for the requested entities and all the entities which 1505 are able to inherit property values from the requested entities. To 1506 achieve this goal, the ALTO server MAY follow three rules: 1508 * If a property for a requested entity is inherited from another 1509 entity not included in the request, the response SHOULD include 1510 this property for the requested entity. For example, A full 1511 property map may skip a property P for an entity A (e.g., 1512 ipv4:192.0.2.0/31) if P can be derived using inheritance from 1513 another entity B (e.g., ipv4:192.0.2.0/30). A filtered property 1514 map request may include only A but not B. In such a case, the 1515 property P SHOULD be included in the response for A. 1517 * If there are entities covered by a requested entity but having 1518 different values for the requested properties, the response SHOULD 1519 include all those entities and the different property values for 1520 them. For example, considering a request for property P of entity 1521 A (e.g., ipv4:192.0.2.0/31), if P has value v1 for 1522 A1=ipv4:192.0.2.0/32 and v2 for A2=ipv4:192.0.2.1/32, then, the 1523 response SHOULD include A1 and A2. 1525 * If an entity identifier in the response is already covered by 1526 other entities identifiers in the same response, it SHOULD be 1527 removed from the response, for the sake of compactness. In the 1528 previous example, the entity A = ipv4:192.0.2.0/31 SHOULD be 1529 removed because A1 and A2 cover all the addresses in A. 1531 An ALTO client should be aware that the entities in the response MAY 1532 be different from the entities in its request. 1534 8.7. Entity property type defined in this document 1536 This document defines the entity property type "pid". This property 1537 type extends the ALTO Endpoint Property Type "pid" defined in section 1538 7.1.1 of [RFC7285] as follows: the property has the same semantics 1539 and applies to IPv4 and IPv6 addresses; the difference is that the 1540 IPv4 and IPv6 addresses have evolved from the status of endpoints to 1541 the status of entities. 1543 The defining information resource for property type MUST be a network 1544 map. This document requests a IANA registration for this property 1546 8.7.1. Entity Property Type: pid 1548 1. Identifier: pid 1550 2. Semantics: the intended semantics are the same as in [RFC7285] 1551 for the ALTO Endpoint Property Type "pid" 1553 3. Media type of defining information resource: application/alto- 1554 networkmap+json 1556 4. Security considerations: for entity property type "pid" are the 1557 same as documented in [RFC7285] for the ALTO Endpoint Property 1558 Type "pid". 1560 9. Impact on Legacy ALTO Servers and ALTO Clients 1561 9.1. Impact on Endpoint Property Service 1563 Since the Property Map and the Filtered Property Map defined in this 1564 document provide a functionality that covers the Endpoint Property 1565 Service (EPS) defined in Section 11.4 of [RFC7285], ALTO servers may 1566 prefer to provide Property Map and Filtered Property Map in place of 1567 EPS. However, for the legacy endpoint properties, it is recommended 1568 that ALTO servers also provide EPS so that legacy clients can still 1569 be supported. 1571 9.2. Impact on Resource-Specific Properties 1573 Section 10.8 of [RFC7285] defines two categories of endpoint 1574 properties: "resource-specific" and "global". Resource-specific 1575 property names are prefixed with the ID of the resource they depend 1576 on, while global property names have no such prefix. The property 1577 map and the filtered property map defined in this document define 1578 similar categories of entity properties. The difference is that 1579 entity property maps do not define "global" entity properties. 1580 Instead, they define "self-defined" entity properties as a special 1581 case of "resource-specific" entity properties, where the specific 1582 resource is the property map itself. This means that "self-defined" 1583 properties are defined within the scope of the property map. 1585 9.3. Impact on Other Properties 1587 In the present extension, properties can now be defined on sets of 1588 entity addresses, rather than just individual endpoint addresses as 1589 is is the case in RFC7285. This might change the semantics of a 1590 property. These sets can be for example hierachical IP address 1591 blocks. For instance, a property such as fictitious "geo-location", 1592 defined on a set of IP addresses would have a value corresponding to 1593 the barycenter of this set of addresses. 1595 10. Examples 1597 10.1. Network Map 1599 The examples in this section use a very simple default network map: 1601 defaultpid: ipv4:0.0.0.0/0 ipv6:::0/0 1602 pid1: ipv4:192.0.2.0/25 1603 pid2: ipv4:192.0.2.0/27 1604 pid3: ipv4:192.0.3.0/28 1605 pid4: ipv4:192.0.3.16/28 1607 Figure 3: Example Default Network Map 1609 And another simple alternative network map: 1611 defaultpid: ipv4:0.0.0.0/0 ipv6:::0/0 1612 pid1: ipv4:192.0.2.0/27 1613 pid2: ipv4:192.0.3.0/27 1615 Figure 4: Example Alternative Network Map 1617 10.2. Property Definitions 1619 Beyond "pid", the examples in this section use four additional 1620 properties for Internet address domains, "ISP", "ASN", "country" and 1621 "state", with the following values: 1623 ISP ASN country state 1624 ipv4:192.0.2.0/23: BitsRus - us - 1625 ipv4:192.0.2.0/28: - 12345 - NJ 1626 ipv4:192.0.2.16/28: - 12345 - CT 1627 ipv4:192.0.2.1: - - - PA 1628 ipv4:192.0.3.0/28: - 12346 - TX 1629 ipv4:192.0.3.16/28: - 12346 - MN 1631 Figure 5: Example Property Values for Internet Address Domains 1633 And the examples in this section use the property "region" for the 1634 PID domain of the default network map with the following values: 1636 region 1637 pid:defaultpid: - 1638 pid:pid1: us-west 1639 pid:pid2: us-east 1640 pid:pid3: us-south 1641 pid:pid4: us-north 1643 Figure 6: Example Property Values for Default Network Map's PID 1644 Domain 1646 Note that "-" means the value of the property for the entity is 1647 "undefined". So the entity would inherit a value for this property 1648 by the inheritance rule if possible. For example, the value of the 1649 "ISP" property for "ipv4:192.0.2.1" is "BitsRus" because of 1650 "ipv4:192.0.2.0/24". But the "region" property for "pid:defaultpid" 1651 has no value because no entity from which it can inherit. 1653 Similar to the PID domain of the default network map, the examples in 1654 this section use the property "ASN" for the PID domain of the 1655 alternative network map with the following values: 1657 ASN 1658 pid:defaultpid: - 1659 pid:pid1: 12345 1660 pid:pid2: 12346 1662 Figure 7: Example Property Values for Alternative Network Map's 1663 PID Domain 1665 10.3. Information Resource Directory (IRD) 1667 The following IRD defines ALTO Server information resources that are 1668 relevant to the Entity Property Service. It provides two property 1669 maps: one for the "ISP" and "ASN" properties, and another one for the 1670 "country" and "state" properties. The server could have provided a 1671 single property map for all four properties, but does not, presumably 1672 because the organization that runs the ALTO server believes that a 1673 client is not necessarily interested in getting all four properties. 1675 The server provides several filtered property maps. The first 1676 returns all four properties, and the second returns only the "pid" 1677 property for the default network map. 1679 The filtered property maps for the "ISP", "ASN", "country" and 1680 "state" properties do not depend on the default network map (it does 1681 not have a "uses" capability), because the definitions of those 1682 properties do not depend on the default network map. The Filtered 1683 Property Map providing the "pid" property does have a "uses" 1684 capability for the default network map, because the default network 1685 map defines the values of the "pid" property. 1687 Note that for legacy clients, the ALTO server provides an Endpoint 1688 Property Service for the "pid" property defined on the endpoints of 1689 the default network map. 1691 The server provides another filtered Property map resource, named 1692 "ane-dc-property-map", that returns a fictitious properties named 1693 "storage-capacity", "ram" and "cpu" for ANEs that have a persistent 1694 identifier. The entity domain to which the ANEs belong is "self- 1695 defined" and valid only within the property map. 1697 GET /directory HTTP/1.1 1698 Host: alto.example.com 1699 Accept: application/alto-directory+json,application/alto-error+json 1701 HTTP/1.1 200 OK 1702 Content-Length: 2827 1703 Content-Type: application/alto-directory+json 1704 { 1705 "meta" : { 1706 "default-alto-network-map" : "default-network-map" 1707 }, 1708 "resources" : { 1709 "default-network-map" : { 1710 "uri" : "http://alto.example.com/networkmap/default", 1711 "media-type" : "application/alto-networkmap+json" 1712 }, 1713 "alt-network-map" : { 1714 "uri" : "http://alto.example.com/networkmap/alt", 1715 "media-type" : "application/alto-networkmap+json" 1716 }, 1717 "ia-property-map" : { 1718 "uri" : "http://alto.example.com/propmap/full/inet-ia", 1719 "media-type" : "application/alto-propmap+json", 1720 "uses": [ "default-network-map", "alt-network-map" ], 1721 "capabilities" : { 1722 "mappings": { 1723 "ipv4": [ ".ISP", ".ASN" ], 1724 "ipv6": [ ".ISP", ".ASN" ] 1725 } 1726 } 1727 }, 1728 "iacs-property-map" : { 1729 "uri" : "http://alto.example.com/propmap/lookup/inet-iacs", 1730 "media-type" : "application/alto-propmap+json", 1731 "accepts": "application/alto-propmapparams+json", 1732 "uses": [ "default-network-map", "alt-network-map" ], 1733 "capabilities" : { 1734 "mappings": { 1735 "ipv4": [ ".ISP", ".ASN", ".country", ".state" ], 1736 "ipv6": [ ".ISP", ".ASN", ".country", ".state" ] 1737 } 1738 } 1739 }, 1740 "region-property-map": { 1741 "uri": "http://alto.example.com/propmap/lookup/region", 1742 "media-type": "application/alto-propmap+json", 1743 "accepts": "application/alto-propmapparams+json", 1744 "uses" : [ "default-network-map", "alt-network-map" ], 1745 "capabilities": { 1746 "mappings": { 1747 "default-network-map.pid": [ ".region" ], 1748 "alt-network-map.pid": [ ".ASN" ] 1749 } 1750 } 1751 }, 1752 "ip-pid-property-map" : { 1753 "uri" : "http://alto.example.com/propmap/lookup/pid", 1754 "media-type" : "application/alto-propmap+json", 1755 "accepts" : "application/alto-propmapparams+json", 1756 "uses" : [ "default-network-map", "alt-network-map" ], 1757 "capabilities" : { 1758 "mappings": { 1759 "ipv4": [ "default-network-map.pid", 1760 "alt-network-map.pid" ], 1761 "ipv6": [ "default-network-map.pid", 1762 "alt-network-map.pid" ] 1763 } 1764 } 1765 }, 1766 "legacy-endpoint-property" : { 1767 "uri" : "http://alto.example.com/legacy/eps-pid", 1768 "media-type" : "application/alto-endpointprop+json", 1769 "accepts" : "application/alto-endpointpropparams+json", 1770 "capabilities" : { 1771 "properties" : [ "default-network-map.pid", 1772 "alt-network-map.pid" ] 1773 } 1774 }, 1775 "ane-dc-property-map": { 1776 "uri" : "http://alto.example.com/propmap/lookup/ane-dc", 1777 "media-type" : "application/alto-propmap+json", 1778 "accepts": "application/alto-propmapparams+json", 1779 "capabilities": { 1780 "mappings": { 1781 ".ane" : [ "storage-capacity", "ram", "cpu" ] 1782 } 1783 } 1784 } 1785 } 1786 } 1788 Figure 8: Example IRD 1790 10.4. Full Property Map Example 1792 The following example uses the properties and IRD defined above in 1793 Section 10.3 to retrieve a Property Map for entities with the "ISP" 1794 and "ASN" properties. 1796 Note that, to be compact, the response does not include the entity 1797 "ipv4:192.0.2.0", because values of all those properties for this 1798 entity are inherited from other entities. 1800 Also note that the entities "ipv4:192.0.2.0/28" and 1801 "ipv4:192.0.2.16/28" are merged into "ipv4:192.0.2.0/27", because 1802 they have the same value of the "ASN" property. The same rule 1803 applies to the entities "ipv4:192.0.3.0/28" and "ipv4:192.0.3.0/28". 1804 Both of "ipv4:192.0.2.0/27" and "ipv4:192.0.3.0/27" omit the value 1805 for the "ISP" property, because it is inherited from 1806 "ipv4:192.0.2.0/23". 1808 GET /propmap/full/inet-ia HTTP/1.1 1809 Host: alto.example.com 1810 Accept: application/alto-propmap+json,application/alto-error+json 1812 HTTP/1.1 200 OK 1813 Content-Length: 418 1814 Content-Type: application/alto-propmap+json 1816 { 1817 "meta": { 1818 "dependent-vtags": [ 1819 {"resource-id": "default-network-map", 1820 "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"}, 1821 {"resource-id": "alt-network-map", 1822 "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"} 1823 ] 1824 }, 1825 "property-map": { 1826 "ipv4:192.0.2.0/23": {".ISP": "BitsRus"}, 1827 "ipv4:192.0.2.0/27": {".ASN": "12345"}, 1828 "ipv4:192.0.3.0/27": {".ASN": "12346"} 1829 } 1830 } 1832 10.5. Filtered Property Map Example #1 1834 The following example uses the filtered property map resource to 1835 request the "ISP", "ASN" and "state" properties for several IPv4 1836 addresses. 1838 Note that the value of "state" for "ipv4:192.0.2.0" is the only 1839 explicitly defined property; the other values are all derived by the 1840 inheritance rules for Internet address entities. 1842 POST /propmap/lookup/inet-iacs HTTP/1.1 1843 Host: alto.example.com 1844 Accept: application/alto-propmap+json,application/alto-error+json 1845 Content-Length: 158 1846 Content-Type: application/alto-propmapparams+json 1848 { 1849 "entities" : [ "ipv4:192.0.2.0", 1850 "ipv4:192.0.2.1", 1851 "ipv4:192.0.2.17" ], 1852 "properties" : [ ".ISP", ".ASN", ".state" ] 1853 } 1855 HTTP/1.1 200 OK 1856 Content-Length: 540 1857 Content-Type: application/alto-propmap+json 1859 { 1860 "meta": { 1861 "dependent-vtags": [ 1862 {"resource-id": "default-network-map", 1863 "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"}, 1864 {"resource-id": "alt-network-map", 1865 "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"} 1866 ] 1867 }, 1868 "property-map": { 1869 "ipv4:192.0.2.0": 1870 {".ISP": "BitsRus", ".ASN": "12345", ".state": "PA"}, 1871 "ipv4:192.0.2.1": 1872 {".ISP": "BitsRus", ".ASN": "12345", ".state": "NJ"}, 1873 "ipv4:192.0.2.17": 1874 {".ISP": "BitsRus", ".ASN": "12345", ".state": "CT"} 1875 } 1876 } 1878 10.6. Filtered Property Map Example #2 1880 The following example uses the filtered property map resource to 1881 request the "ASN", "country" and "state" properties for several IPv4 1882 prefixes. 1884 Note that the property values for both entities "ipv4:192.0.2.0/26" 1885 and "ipv4:192.0.3.0/26" are not explicitly defined. They are 1886 inherited from the entity "ipv4:192.0.2.0/23". 1888 Also note that some entities like "ipv4:192.0.2.0/28" and 1889 "ipv4:192.0.2.16/28" in the response are not explicitly listed in the 1890 request. The response includes them because they are refinements of 1891 the requested entities and have different values for the requested 1892 properties. 1894 The entity "ipv4:192.0.4.0/26" is not included in the response, 1895 because there are neither entities which it is inherited from, nor 1896 entities inherited from it. 1898 POST /propmap/lookup/inet-iacs HTTP/1.1 1899 Host: alto.example.com 1900 Accept: application/alto-propmap+json,application/alto-error+json 1901 Content-Length: 170 1902 Content-Type: application/alto-propmapparams+json 1904 { 1905 "entities" : [ "ipv4:192.0.2.0/26", 1906 "ipv4:192.0.3.0/26", 1907 "ipv4:192.0.4.0/26" ], 1908 "properties" : [ ".ASN", ".country", ".state" ] 1909 } 1910 HTTP/1.1 200 OK 1911 Content-Length: 766 1912 Content-Type: application/alto-propmap+json 1914 { 1915 "meta": { 1916 "dependent-vtags": [ 1917 {"resource-id": "default-network-map", 1918 "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"}, 1919 {"resource-id": "alt-network-map", 1920 "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"} 1921 ] 1922 }, 1923 "property-map": { 1924 "ipv4:192.0.2.0/26": {".country": "us"}, 1925 "ipv4:192.0.2.0/28": {".ASN": "12345", 1926 ".state": "NJ"}, 1927 "ipv4:192.0.2.16/28": {".ASN": "12345", 1928 ".state": "CT"}, 1929 "ipv4:192.0.2.0": {".state": "PA"}, 1930 "ipv4:192.0.3.0/26": {".country": "us"}, 1931 "ipv4:192.0.3.0/28": {".ASN": "12345", 1932 ".state": "TX"}, 1933 "ipv4:192.0.3.16/28": {".ASN": "12345", 1934 ".state": "MN"} 1935 } 1936 } 1938 10.7. Filtered Property Map Example #3 1940 The following example uses the filtered property map resource to 1941 request the "default-network-map.pid" property and the "alt-network- 1942 map.pid" property for a set of IPv4 addresses and prefixes. 1944 Note that the entity "ipv4:192.0.3.0/27" is decomposed into two 1945 entities "ipv4:192.0.3.0/28" and "ipv4:192.0.3.16/28", as they have 1946 different "default-network-map.pid" property values. 1948 POST /propmap/lookup/pid HTTP/1.1 1949 Host: alto.example.com 1950 Accept: application/alto-propmap+json,application/alto-error+json 1951 Content-Length: 221 1952 Content-Type: application/alto-propmapparams+json 1954 { 1955 "entities" : [ 1956 "ipv4:192.0.2.128", 1957 "ipv4:192.0.2.0/27", 1958 "ipv4:192.0.3.0/27" ], 1959 "properties" : [ "default-network-map.pid", 1960 "alt-network-map.pid ] 1961 } 1963 HTTP/1.1 200 OK 1964 Content-Length: 774 1965 Content-Type: application/alto-propmap+json 1967 { 1968 "meta": { 1969 "dependent-vtags": [ 1970 {"resource-id": "default-network-map", 1971 "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"}, 1972 {"resource-id": "alt-network-map", 1973 "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"} 1974 ] 1975 }, 1976 "property-map": { 1977 "ipv4:192.0.2.128": {"default-network-map.pid": "defaultpid", 1978 "alt-network-map.pid": "defaultpid"}, 1979 "ipv4:192.0.2.0/27": {"default-network-map.pid": "pid2", 1980 "alt-network-map.pid": "pid1"}, 1981 "ipv4:192.0.3.0/28": {"default-network-map.pid": "pid3", 1982 "alt-network-map.pid": "pid2"}, 1983 "ipv4:192.0.3.16/28": {"default-network-map.pid": "pid4", 1984 "alt-network-map.pid": "pid2"} 1985 } 1986 } 1988 10.8. Filtered Property Map Example #4 1990 Here is an example of using the filtered property map to query the 1991 regions for several PIDs in "default-network-map". The "region" 1992 property is specified as a "self-defined" property, i.e., the values 1993 of this property are defined by this property map resource. 1995 POST /propmap/lookup/region HTTP/1.1 1996 Host: alto.example.com 1997 Accept: application/alto-propmap+json,application/alto-error+json 1998 Content-Length: 132 1999 Content-Type: application/alto-propmapparams+json 2001 { 2002 "entities" : ["default-network-map.pid:pid1", 2003 "default-network-map.pid:pid2"], 2004 "properties" : [ ".region" ] 2005 } 2007 HTTP/1.1 200 OK 2008 Content-Length: 326 2009 Content-Type: application/alto-propmap+json 2011 { 2012 "meta" : { 2013 "dependent-vtags" : [ 2014 {"resource-id": "default-network-map", 2015 "tag": "7915dc0290c2705481c491a2b4ffbec482b3cf62"} 2016 ] 2017 }, 2018 "property-map": { 2019 "default-network-map.pid:pid1": { 2020 ".region": "us-west" 2021 }, 2022 "default-network-map.pid:pid2": { 2023 ".region": "us-east" 2024 } 2025 } 2026 } 2028 10.9. Filtered Property Map for ANEs Example #5 2030 The following example uses the filtered property map resource "ane- 2031 dc-property-map" to request properties "storage-capacity" and "cpu" 2032 on several ANEs defined in this property map. 2034 POST /propmap/lookup/ane-dc HTTP/1.1 2035 Host: alto.example.com 2036 Accept: application/alto-propmap+json,application/alto-error+json 2037 Content-Length: 155 2038 Content-Type: application/alto-propmapparams+json 2040 { 2041 "entities" : [".ane:dc21", 2042 ".ane:dc45.srv9", 2043 ".ane:dc6.srv-cluster8"], 2044 "properties" : [ "storage-capacity", "cpu"] 2045 } 2047 HTTP/1.1 200 OK 2048 Content-Length: 295 2049 Content-Type: application/alto-propmap+json 2051 { 2052 "meta" : { 2053 }, 2054 "property-map": { 2055 ".ane:dc21": 2056 {"storage-capacity" : 40000 Gbytes, "cpu" : 500 Cores}, 2057 ".ane:dc45.srv9": 2058 {"storage-capacity" : 100 Gbytes, "cpu" : 20 Cores}, 2059 ".ane:dc6.srv-cluster8": 2060 {"storage-capacity" : 6000 Gbytes, "cpu" : 100 Cores} 2061 } 2062 } 2064 11. Security Considerations 2066 Both Property Map and Filtered Property Map defined in this document 2067 fit into the architecture of the ALTO base protocol, and hence the 2068 Security Considerations (Section 15 of [RFC7285]) of the base 2069 protocol fully apply: authenticity and integrity of ALTO information 2070 (i.e., authenticity and integrity of Property Maps), potential 2071 undesirable guidance from authenticated ALTO information (e.g., 2072 potentially imprecise or even wrong value of a property such as geo- 2073 location), confidentiality of ALTO information (e.g., exposure of a 2074 potentially sensitive entity property such as geo-location), privacy 2075 for ALTO users, and availability of ALTO services should all be 2076 considered. 2078 ALTO clients using this extension should in addition be aware that 2079 the entity properties they require may convey more details than the 2080 endpoint properties conveyed by using [RFC7285]. Client requests may 2081 reveal details on their activity or plans thereof, that a malicious 2082 usage may monetize or use for attacks or undesired surveillance. 2083 Likewise, ALTO Servers expose entities and properties related to 2084 specific parts of the infrastructure that reveal details on 2085 capabilities, locations, or resource availability. These details may 2086 be maliciously used for competition purposes, or to cause resources 2087 shortage or undesired publication. 2089 To address these concerns, the Property Maps provided by this 2090 extension require additional attention on two security considerations 2091 discussed in [RFC7285]: "potential undesirable guidance from 2092 authenticated ALTO information" (Section 15.2 of [RFC7285]) and 2093 "confidentiality of ALTO information" (Section 15.3 of [RFC7285]). 2094 Threats to the availability of the ALTO Service caused by highly 2095 demanding queries should be addressed as specified in Section 15.5 of 2096 [RFC7285]. 2098 * Potential undesirable guidance from authenticated ALTO 2099 information: it can be caused by Property values that change over 2100 time and thus lead to performance degradation or system rejection 2101 of application requests. 2103 To avoid these consequences, a more robust ALTO client should 2104 adopt and extend protection strategies specified in Section 15.2 2105 of [RFC7285]. For example, to be notified immediately when a 2106 particular ALTO value that the Client depends on changes, it is 2107 RECOMMENDED that both the ALTO Client and ALTO Server using this 2108 extension implement "Application-Layer Traffic Optimization (ALTO) 2109 Incremental Updates Using Server-Sent Events (SSE)" [RFC8895]. 2111 * Confidentiality of ALTO information: as discussed in Section 15 of 2112 [RFC7285], properties may have sensitive customer-specific 2113 information. If this is the case, an ALTO Server may limit access 2114 to those properties by providing several different property maps. 2115 For non-sensitive properties, the ALTO Server would provide a URI 2116 which accepts requests from any client. Sensitive properties, on 2117 the other hand, would only be available via a secure URI which 2118 would require client authentication. Another way is to expose 2119 highly abstracted coarse-grained property values to all Clients 2120 while restricting access to URIs exposing more fine-grained values 2121 to authorized Clients. Restricted access URIs may be gathered in 2122 delegate IRDs as specified in Section 9.2.4 of [RFC7285]. 2124 Also, while technically this document does not introduce any 2125 security risks not inherent in the Endpoint Property Service 2126 defined by [RFC7285], the GET-mode property map resource defined 2127 in this document does make it easier for a client to download 2128 large numbers of property values. Accordingly, an ALTO Server 2129 should limit GET-mode property maps to properties that do not 2130 contain sensitive data. 2132 Section 12 on IANA considerations of this document specifies that 2133 the ALTO service provider MUST be aware of the potential 2134 sensitiveness of exposed entity domains and properties. 2135 Section 12.2.2. (ALTO Entity Domain Type Registration Process) of 2136 this document specifies that when the registration of an entity 2137 domain type is requested at the IANA, the request MUST include 2138 security considerations that show awareness of how the exposed 2139 entity addresses may be related to private information about an 2140 ALTO client or an infrastructure service provider. Likewise, 2141 Section 12.3. (ALTO Entity Property Type Registry) of this 2142 document specifies that when the registration of a property type 2143 is requested at the IANA, the request MUST include security 2144 considerations that explain why this property type is required for 2145 ALTO-based operations. 2147 The risk of ALTO information being leaked to malicious Clients or 2148 third parties is addressed similarly to in Section 7 of [RFC8896]. 2149 ALTO Clients and Servers SHOULD support both TLS 1.3 [RFC8446] and 2150 TLS 1.2 [RFC5246] and MAY support and use newer versions of TLS as 2151 long as the negotiation process succeeds. 2153 12. IANA Considerations 2155 This document defines additional application/alto-* media types. It 2156 defines an ALTO Entity Domain Type Registry that extends the ALTO 2157 Address Type Registry defined in [RFC7285]. It also defines an ALTO 2158 Entity Property Type Registry that extends the ALTO endpoint property 2159 registry defined in [RFC7285]. 2161 12.1. application/alto-* Media Types 2163 This document registers two additional ALTO media types, listed in 2164 Table 1. 2166 +=============+=========================+===============+ 2167 | Type | Subtype | Specification | 2168 +=============+=========================+===============+ 2169 | application | alto-propmap+json | Section 7.1 | 2170 +-------------+-------------------------+---------------+ 2171 | application | alto-propmapparams+json | Section 8.3 | 2172 +-------------+-------------------------+---------------+ 2174 Table 1: Additional ALTO Media Types. 2176 Type name: 2177 application 2179 Subtype name: 2180 This document registers multiple subtypes, as listed in Table 1. 2182 Required parameters: 2183 n/a 2185 Optional parameters: 2186 n/a 2188 Encoding considerations: 2189 Encoding considerations are identical to those specified for the 2190 "application/json" media type. See [RFC8259]. 2192 Security considerations: 2193 Security considerations related to the generation and consumption 2194 of ALTO Protocol messages are discussed in Section 15 of 2195 [RFC7285]. 2197 Interoperability considerations: 2198 This document specifies formats of conforming messages and the 2199 interpretation thereof. 2201 Published specification: 2202 This document is the specification for these media types; see 2203 Table 1 for the section documenting each media type. 2205 Applications that use this media type: 2206 ALTO servers and ALTO clients either stand alone or are embedded 2207 within other applications. 2209 Additional information: 2210 Magic number(s): n/a 2212 File extension(s): This document uses the mime type to refer to 2213 protocol messages and thus does not require a file extension. 2215 Macintosh file type code(s): n/a 2217 Person & email address to contact for further information: 2218 See Authors' Addresses section. 2220 Intended usage: 2221 COMMON 2223 Restrictions on usage: 2224 n/a 2226 Author: 2227 See Authors' Addresses section. 2229 Change controller: 2230 Internet Engineering Task Force (mailto:iesg@ietf.org). 2232 12.2. ALTO Entity Domain Type Registry 2234 This document requests IANA to create and maintain the "ALTO Entity 2235 Domain Type Registry", listed in Table 2. 2237 +============+============+=============+======================+ 2238 | Identifier | Entity | Hierarchy & | Media Type of | 2239 | | Identifier | Inheritance | Defining Resource | 2240 | | Encoding | | | 2241 +============+============+=============+======================+ 2242 | ipv4 | See | See Section | application/alto- | 2243 | | Section | 6.1.3 | networkmap+json | 2244 | | 6.1.1 | | | 2245 +------------+------------+-------------+----------------------+ 2246 | ipv6 | See | See Section | application/alto- | 2247 | | Section | 6.1.3 | networkmap+json | 2248 | | 6.1.2 | | | 2249 +------------+------------+-------------+----------------------+ 2250 | pid | See | None | application/alto- | 2251 | | Section | | networkmap+json | 2252 | | 6.2 | | | 2253 +------------+------------+-------------+----------------------+ 2255 Table 2: ALTO Entity Domain Types 2257 This registry serves two purposes. First, it ensures uniqueness of 2258 identifiers referring to ALTO entity domain types. Second, it states 2259 the requirements for allocated entity domain types. 2261 12.2.1. Consistency Procedure between ALTO Address Type Registry and 2262 ALTO Entity Domain Type Registry 2264 One potential issue of introducing the "ALTO Entity Domain Type 2265 Registry" is its relationship with the "ALTO Address Types Registry" 2266 already defined in Section 14.4 of [RFC7285]. In particular, the 2267 entity identifier of a type of an entity domain registered in the 2268 "ALTO Entity Domain Type Registry" MAY match an address type defined 2269 in "ALTO Address Type Registry". It is necessary to precisely define 2270 and guarantee the consistency between "ALTO Address Type Registry" 2271 and "ALTO Entity Domain Registry". 2273 We define that the ALTO Entity Domain Type Registry is consistent 2274 with ALTO Address Type Registry if two conditions are satisfied: 2276 * When an address type is already or able to be registered in the 2277 ALTO Address Type Registry [RFC7285], the same identifier MUST be 2278 used when a corresponding entity domain type is registered in the 2279 ALTO Entity Domain Type Registry. 2281 * If an ALTO entity domain type has the same identifier as an ALTO 2282 address type, their addresses encoding MUST be compatible. 2284 To achieve this consistency, the following items MUST be checked 2285 before registering a new ALTO entity domain type in a future 2286 document: 2288 * Whether the ALTO Address Type Registry contains an address type 2289 that can be used as an identifier for the candidate entity domain 2290 type identifier. This has been done for the identifiers "ipv4" 2291 and "ipv6" of Table 2. 2293 * Whether the candidate entity domain type identifier can 2294 potentially be an endpoint address type, as defined in Sections 2295 2.1 and 2.2 of [RFC7285]. 2297 When a new ALTO entity domain type is registered, the consistency 2298 with the ALTO Address Type Registry MUST be ensured by the following 2299 procedure: 2301 * Test: Do corresponding entity domain type identifiers match a 2302 known "network" address type? 2304 - If yes (e.g., cell, MAC or socket addresses): 2306 o Test: Is such an address type present in the ALTO Address 2307 Type Registry? 2308 + If yes: Set the new ALTO entity domain type identifier to 2309 be the found ALTO address type identifier. 2311 + If no: Define a new ALTO entity domain type identifier 2312 and use it to register a new address type in the ALTO 2313 Address Type Registry following Section 14.4 of 2314 [RFC7285]. 2316 o Use the new ALTO entity domain type identifier to register a 2317 new ALTO entity domain type in the ALTO Entity Domain Type 2318 Registry following Section 12.2.2 of this document. 2320 - If no (e.g., pid name, ane name or country code): Proceed with 2321 the ALTO Entity Domain Type registration as described in 2322 Section 12.2.2. 2324 12.2.2. ALTO Entity Domain Type Registration Process 2326 New ALTO entity domain types are assigned after IETF Review [RFC8126] 2327 to ensure that proper documentation regarding the new ALTO entity 2328 domain types and their security considerations has been provided. 2329 RFCs defining new entity domain types SHOULD indicate how an entity 2330 in a registered type of domain is encoded as an EntityID, and, if 2331 applicable, the rules defining the entity hierarchy and property 2332 inheritance. Updates and deletions of ALTO entity domains types 2333 follow the same procedure. 2335 Registered ALTO entity domain type identifiers MUST conform to the 2336 syntactical requirements specified in Section 5.1.2. Identifiers are 2337 to be recorded and displayed as strings. 2339 Requests to the IANA to add a new value to the Entity Domain Type 2340 registry MUST include the following information: 2342 * Identifier: The name of the desired ALTO entity domain type. 2344 * Entity Identifier Encoding: The procedure for encoding the 2345 identifier of an entity of the registered domain type as an 2346 EntityID (see Section 5.1.3). If corresponding entity identifiers 2347 of an entity domain type match a known "network" address type, the 2348 Entity Identifier Encoding of this domain identifier MUST include 2349 both Address Encoding and Prefix Encoding of the same identifier 2350 registered in the ALTO Address Type Registry [RFC7285]. To define 2351 properties, an individual entity identifier and the corresponding 2352 full-length prefix MUST be considered aliases for the same entity. 2354 * Hierarchy: If the entities form a hierarchy, the procedure for 2355 determining that hierarchy. 2357 * Inheritance: If entities can inherit property values from other 2358 entities, the procedure for determining that inheritance. 2360 * Media type of defining information resource: Some entity domain 2361 types allow an entity domain name to be combined with an 2362 information resource name to define a resource-specific entity 2363 domain. Such an information resource is called "defining 2364 information resource". In this case, the authorized media type of 2365 the defining information resources MUST be unique and MUST be 2366 specified in the document defining the entity domain type. When 2367 an entity domain type allows combinations with defining resources, 2368 this MUST be indicated here, together with the authorized media 2369 type for the defining resources. The defining information 2370 resource for a resource-specific entity domain is the one that: 2372 - has an entry in the IRD, 2374 - defines these entities, 2376 - does not use another information resource that defines these 2377 entities, 2379 - defines and exposes entity identifiers that are all persistent. 2381 - has a unique media type equal to the one specified in the 2382 document defining the entity domain type. 2384 * Knowing the media type of the defining information resource is 2385 useful when Servers indicate resource specific entity domains in 2386 the property map capabilities. Clients need to know if the 2387 combination of information resource type and entity domain type is 2388 allowed. See also, Section 4.6 and Section 5.1 for more 2389 information. 2391 * Mapping to ALTO Address Type: A boolean value to indicate if the 2392 entity domain type can be mapped to the ALTO address type with the 2393 same identifier. 2395 * Security Considerations: In some usage scenarios, entity 2396 identifiers carried in ALTO Protocol messages may reveal 2397 information about an ALTO client or an ALTO service provider. 2398 Applications and ALTO service providers using addresses of the 2399 registered type should be cognizant of how (or if) the addressing 2400 scheme relates to private information and network proximity. 2402 This specification requests registration of the identifiers "ipv4", 2403 "ipv6" and "pid", as shown in Table 2. 2405 12.3. ALTO Entity Property Type Registry 2407 This document requests IANA to create and maintain the "ALTO Entity 2408 Property Type Registry", listed in Table 3. 2410 This registry extends the "ALTO Endpoint Property Type Registry", 2411 defined in [RFC7285], in that a property type is defined on one or 2412 more entity domains, rather than just on IPv4 and IPv6 Internet 2413 address domains. An entry in this registry is an ALTO entity 2414 property type defined in Section 5.2.1. Thus, a registered ALTO 2415 entity property type identifier MUST conform to the syntactical 2416 requirements specified in that section. 2418 +============+====================+=================================+ 2419 | Identifier | Intended Semantics | Media Type of | 2420 | | | Defining Resource | 2421 +============+====================+=================================+ 2422 | pid | See Section 7.1.1 | application/alto- | 2423 | | of [RFC7285] | networkmap+json | 2424 +------------+--------------------+---------------------------------+ 2426 Table 3: ALTO Entity Property Types. 2428 Requests to the IANA to add a new value to the registry MUST include 2429 the following information: 2431 * Identifier: The unique id for the desired ALTO entity property 2432 type. The format MUST be as defined in Section 5.2.1 of this 2433 document. It includes the information of the applied ALTO entity 2434 domain and the property name. 2436 * Intended Semantics: ALTO entity properties carry with them 2437 semantics to guide their usage by ALTO clients. Hence, a document 2438 defining a new type SHOULD provide guidance to both ALTO service 2439 providers and applications utilizing ALTO clients as to how values 2440 of the registered ALTO entity property should be interpreted. 2442 * Media type of defining information resource: when the property 2443 type allows values to be defined relatively to a given information 2444 resource, the latter is referred to as the "defining information 2445 resource", see also description in Section 4.7. The media type of 2446 the possibly used defining information resource MUST be unique and 2447 MUST be specified here, as well as in the document that defines 2448 the property type. 2450 * Security Considerations: ALTO entity properties expose information 2451 to ALTO clients. ALTO service providers should be cognizant of 2452 the security ramifications related to the exposure of an entity 2453 property. 2455 In security considerations, the request should also discuss the 2456 sensitivity of the information, and why it is required for ALTO-based 2457 operations. Regarding this discussion, the request SHOULD follow the 2458 recommendations of Section 14.3. ALTO Endpoint Property Type 2459 Registry in [RFC7285]. 2461 This document requests registration of the identifier "pid", listed 2462 in Table 3. Semantics for this property are documented in 2463 Section 7.1.1 of [RFC7285]. No security issues related to the 2464 exposure of a "pid" identifier are considered, as it is exposed with 2465 the Network Map Service defined and mandated in [RFC7285]. 2467 13. Acknowledgments 2469 The authors would like to thank Dawn Chen (Tongji University), and 2470 Shenshen Chen (Tongji/Yale University) for their contributions to 2471 earlier drafts. Thank you also to Qiao Xiang (Yale University), 2472 Shawn Lin, Xin Wang and Vijay Gurbani (Vail systems) for fruitful 2473 discussions. Last, big thanks to Danny Perez (University of 2474 Campinas) and Luis Contreras (Telefonica) for their substantial 2475 review feedback and suggestions to improve this document. 2477 14. References 2479 14.1. Normative References 2481 [ISO3166-1] 2482 ISO (International Organization for Standardization), ., 2483 "ISO 3166-1: Codes for the representation of names of 2484 countries and their subdivisions -- Part 1: Country 2485 codes", 2020. 2487 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2488 Requirement Levels", BCP 14, RFC 2119, 2489 DOI 10.17487/RFC2119, March 1997, 2490 . 2492 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2493 Resource Identifier (URI): Generic Syntax", STD 66, 2494 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2495 . 2497 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2498 (CIDR): The Internet Address Assignment and Aggregation 2499 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2500 2006, . 2502 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2503 (TLS) Protocol Version 1.2", RFC 5246, 2504 DOI 10.17487/RFC5246, August 2008, 2505 . 2507 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 2508 Address Text Representation", RFC 5952, 2509 DOI 10.17487/RFC5952, August 2010, 2510 . 2512 [RFC7285] Alimi, R., Ed., Penno, R., Ed., Yang, Y., Ed., Kiesel, S., 2513 Previdi, S., Roome, W., Shalunov, S., and R. Woundy, 2514 "Application-Layer Traffic Optimization (ALTO) Protocol", 2515 RFC 7285, DOI 10.17487/RFC7285, September 2014, 2516 . 2518 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2519 Writing an IANA Considerations Section in RFCs", BCP 26, 2520 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2521 . 2523 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2524 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2525 May 2017, . 2527 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2528 Interchange Format", STD 90, RFC 8259, 2529 DOI 10.17487/RFC8259, December 2017, 2530 . 2532 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2533 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2534 . 2536 14.2. Informative References 2538 [I-D.gao-alto-fcs] 2539 Zhang, J., Gao, K., Wang, J., and Y. Yang, "ALTO 2540 Extension: Flow-based Cost Query", Work in Progress, 2541 Internet-Draft, draft-gao-alto-fcs-07, 16 March 2020, 2542 . 2545 [I-D.ietf-alto-cdni-request-routing-alto] 2546 Seedorf, J., Yang, Y., Ma, K., Peterson, J., and J. Zhang, 2547 "Content Delivery Network Interconnection (CDNI) Request 2548 Routing: CDNI Footprint and Capabilities Advertisement 2549 using ALTO", Work in Progress, Internet-Draft, draft-ietf- 2550 alto-cdni-request-routing-alto-16, 12 January 2021, 2551 . 2554 [I-D.ietf-alto-path-vector] 2555 Gao, K., Lee, Y., Randriamasy, S., Yang, Y., and J. Zhang, 2556 "ALTO Extension: Path Vector", Work in Progress, Internet- 2557 Draft, draft-ietf-alto-path-vector-13, 20 November 2020, 2558 . 2561 [RFC7011] Claise, B., Ed., Trammell, B., Ed., and P. Aitken, 2562 "Specification of the IP Flow Information Export (IPFIX) 2563 Protocol for the Exchange of Flow Information", STD 77, 2564 RFC 7011, DOI 10.17487/RFC7011, September 2013, 2565 . 2567 [RFC7921] Atlas, A., Halpern, J., Hares, S., Ward, D., and T. 2568 Nadeau, "An Architecture for the Interface to the Routing 2569 System", RFC 7921, DOI 10.17487/RFC7921, June 2016, 2570 . 2572 [RFC8895] Roome, W. and Y. Yang, "Application-Layer Traffic 2573 Optimization (ALTO) Incremental Updates Using Server-Sent 2574 Events (SSE)", RFC 8895, DOI 10.17487/RFC8895, November 2575 2020, . 2577 [RFC8896] Randriamasy, S., Yang, R., Wu, Q., Deng, L., and N. 2578 Schwan, "Application-Layer Traffic Optimization (ALTO) 2579 Cost Calendar", RFC 8896, DOI 10.17487/RFC8896, November 2580 2020, . 2582 Appendix A. Features introduced with the Entity Property Maps extension 2584 The Entity Property Maps extension described in this document 2585 introduces a number of features that are summarized in table below. 2586 The first column provides the name of the feature. The second column 2587 provides the section number of this document that gives a high level 2588 description of the feature. The third column provides the section 2589 number of this document that gives a normative description relating 2590 to the feature, when applicable. 2592 +======================+=============+==============================+ 2593 | Feature | High-level | Related normative | 2594 | | description | description | 2595 +======================+=============+==============================+ 2596 | Entity | Section 3.1 | Section 5.1.3 | 2597 +----------------------+-------------+------------------------------+ 2598 | Entity domain | Section 3.2 | | 2599 | (ED) | | | 2600 +----------------------+-------------+------------------------------+ 2601 | Entity domain | Section | Section 5.1.1 | 2602 | type | 3.2.1 | | 2603 +----------------------+-------------+------------------------------+ 2604 | Entity domain | Section | Section 5.1.2 | 2605 | name | 3.2.2 | | 2606 +----------------------+-------------+------------------------------+ 2607 | Entity property | Section 3.3 | Section 5.2, Section 5.2.1, | 2608 | (EP) type | | Section 5.2.2, Section 5.2.3 | 2609 +----------------------+-------------+------------------------------+ 2610 | Entity property | Section 3.4 | Section 7, Section 8 | 2611 | map | | | 2612 +----------------------+-------------+------------------------------+ 2613 | Resource-specific | Section 4.2 | Section 5.1.2, | 2614 | ED name | | Section 5.1.2.1 | 2615 +----------------------+-------------+------------------------------+ 2616 | Resource-specific | Section 4.3 | Section 5.2.3 | 2617 | EP value | | | 2618 +----------------------+-------------+------------------------------+ 2619 | Entity Hierarchy | Section 4.4 | Section 5.1.4 | 2620 | and property | | | 2621 | inheritance | | | 2622 +----------------------+-------------+------------------------------+ 2623 | Defining | Section | Section 12.2.2, Section 12.3 | 2624 | information | 4.6, | | 2625 | resource | Section 4.7 | | 2626 +----------------------+-------------+------------------------------+ 2628 Table 4: Features introduced with ALTO Entity Property Maps 2630 Authors' Addresses 2632 Wendy Roome 2633 Nokia Bell Labs (Retired) 2634 124 Burlington Rd 2635 Murray Hill, NJ 07974 2636 United States of America 2638 Phone: +1-908-464-6975 2639 Email: wendy@wdroome.com 2640 Sabine Randriamasy 2641 Nokia Bell Labs 2642 Route de Villejust 2643 91460 NOZAY 2644 France 2646 Email: Sabine.Randriamasy@nokia-bell-labs.com 2648 Y. Richard Yang 2649 Yale University 2650 51 Prospect Street 2651 New Haven, CT 06511 2652 United States of America 2654 Phone: +1-203-432-6400 2655 Email: yry@cs.yale.edu 2657 Jingxuan Jensen Zhang 2658 Tongji University 2659 4800 Cao'An Hwy 2660 Shanghai 2661 201804 2662 China 2664 Email: jingxuan.n.zhang@gmail.com 2666 Kai Gao 2667 Sichuan University 2668 No.24 South Section 1, Yihuan Road 2669 Chengdu 2670 610000 2671 China 2673 Email: kaigao@scu.edu.cn