idnits 2.17.1 draft-ietf-alto-unified-props-new-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC7285]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 671 has weird spacing: '...rtyName prop...' == Line 865 has weird spacing: '...country stat...' -- The document date (March 11, 2019) is 1865 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Downref: Normative reference to an Informational RFC: RFC 7921 Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ALTO WG W. Roome 3 Internet-Draft S. Randriamasy 4 Intended status: Standards Track Nokia Bell Labs 5 Expires: September 12, 2019 Y. Yang 6 Yale University 7 J. Zhang 8 Tongji University 9 March 11, 2019 11 Unified Properties for the ALTO Protocol 12 draft-ietf-alto-unified-props-new-07 14 Abstract 16 This document extends the Application-Layer Traffic Optimization 17 (ALTO) Protocol [RFC7285] by generalizing the concept of "endpoint 18 properties" to domains of other entities, and by presenting those 19 properties as maps, similar to the network and cost maps in ALTO. 21 Requirements Language 23 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 24 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 25 document are to be interpreted as described in RFC 2119 [RFC2119]. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on September 12, 2019. 44 Copyright Notice 46 Copyright (c) 2019 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Definitions and Concepts . . . . . . . . . . . . . . . . . . 4 63 2.1. Entity . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2.2. Entity Domain . . . . . . . . . . . . . . . . . . . . . . 5 65 2.3. Domain Name . . . . . . . . . . . . . . . . . . . . . . . 5 66 2.4. Entity Identifier . . . . . . . . . . . . . . . . . . . . 6 67 2.5. Property Type and Property Name . . . . . . . . . . . . . 6 68 2.6. Hierarchy and Inheritance . . . . . . . . . . . . . . . . 7 69 2.7. Relationship with Other ALTO Resources . . . . . . . . . 7 70 3. Entity Domains . . . . . . . . . . . . . . . . . . . . . . . 8 71 3.1. Internet Address Domains . . . . . . . . . . . . . . . . 9 72 3.1.1. IPv4 Domain . . . . . . . . . . . . . . . . . . . . . 9 73 3.1.2. IPv6 Domain . . . . . . . . . . . . . . . . . . . . . 9 74 3.1.3. Hierarchy and Inheritance of ipv4/ipv6 Domains . . . 9 75 3.2. PID Domain . . . . . . . . . . . . . . . . . . . . . . . 11 76 3.2.1. Domain Name . . . . . . . . . . . . . . . . . . . . . 11 77 3.2.2. Domain-Specific Entity Identifiers . . . . . . . . . 11 78 3.2.3. Hierarchy and Inheritance . . . . . . . . . . . . . . 11 79 3.2.4. Relationship To Internet Addresses Domains . . . . . 11 80 3.3. Internet Address Properties vs. PID Properties . . . . . 11 81 4. Property Map . . . . . . . . . . . . . . . . . . . . . . . . 12 82 4.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 12 83 4.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 12 84 4.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 12 85 4.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . 12 86 4.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 13 87 4.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 13 88 5. Filtered Property Map . . . . . . . . . . . . . . . . . . . . 14 89 5.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 14 90 5.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 14 91 5.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 14 92 5.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . 15 93 5.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 15 94 5.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 15 95 6. Impact on Legacy ALTO Servers and ALTO Clients . . . . . . . 17 96 6.1. Impact on Endpoint Property Service . . . . . . . . . . . 17 97 6.2. Impact on Resource-Specific Properties . . . . . . . . . 17 98 6.3. Impact on the pid Property . . . . . . . . . . . . . . . 17 99 6.4. Impact on Other Properties . . . . . . . . . . . . . . . 18 100 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 18 101 7.1. Network Map . . . . . . . . . . . . . . . . . . . . . . . 18 102 7.2. Property Definitions . . . . . . . . . . . . . . . . . . 18 103 7.3. Information Resource Directory (IRD) . . . . . . . . . . 19 104 7.4. Property Map Example . . . . . . . . . . . . . . . . . . 21 105 7.5. Filtered Property Map Example #1 . . . . . . . . . . . . 22 106 7.6. Filtered Property Map Example #2 . . . . . . . . . . . . 23 107 7.7. Filtered Property Map Example #3 . . . . . . . . . . . . 24 108 7.8. Filtered Property Map Example #4 . . . . . . . . . . . . 25 109 8. Security Considerations . . . . . . . . . . . . . . . . . . . 26 110 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 111 9.1. application/alto-* Media Types . . . . . . . . . . . . . 27 112 9.2. ALTO Entity Domain Registry . . . . . . . . . . . . . . . 28 113 9.2.1. Consistency Procedure between ALTO Address Type 114 Registry and ALTO Entity Domain Registry . . . . . . 29 115 9.2.2. ALTO Entity Domain Registration Process . . . . . . . 30 116 9.3. ALTO Entity Property Type Registry . . . . . . . . . . . 31 117 9.4. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 32 118 10. Normative References . . . . . . . . . . . . . . . . . . . . 32 119 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 121 1. Introduction 123 The ALTO protocol [RFC7285] introduces the concept of "properties" 124 attached to "endpoint addresses", and defines the Endpoint Property 125 Service (EPS) to allow ALTO clients to retrieve those properties. 126 While useful, the EPS, as defined in [RFC7285], has at least two 127 limitations. 129 First, it only allows properties to be associated with a particular 130 domain of entities, namely individual IP addresses. It is reasonable 131 to think that collections of endpoints, as defined by CIDRs [RFC4632] 132 or PIDs, may also have properties. Since the EPS cannot be extended 133 to new entity domains, new services, with new request and response 134 messages, would have to be defined for new entity domains. 136 Second, the EPS is only defined as a POST-mode service. Clients must 137 request the properties for an explicit set of endpoint addresses. By 138 contrast, [RFC7285] defines a GET-mode cost map resource which 139 returns all available costs, so a client can get a full set of costs 140 once, and then processes costs lookups without querying the ALTO 141 server. [RFC7285] does not define an equivalent service for endpoint 142 properties. At first a map of endpoint properties might seem 143 impractical, because it could require enumerating the property value 144 for every possible endpoint. But in practice, it is highly unlikely 145 that properties will be defined for every endpoint address. It is 146 much more likely that properties will only be defined for a subset of 147 endpoint addresses, and that subset would be small enough to be 148 enumerated. This is particularly true if blocks of endpoint 149 addresses with a common prefix (e.g., a CIDR) have the same value for 150 a property. Furthermore, entities in other domains may very well be 151 enumerable. 153 This document proposes a new approach to retrieve ALTO properties. 154 Specifically, it defines two new types of resources, namely Property 155 Map (see Section 4) and Filtered Property Map (see Section 5). The 156 former is a GET-mode resource which returns the property values for 157 all entities in a domain, and is analogous to a network map or a cost 158 map in [RFC7285]. The latter is a POST-mode resource which returns 159 the values for a set of properties and entities requested by the 160 client, and is analogous to a filtered network map or a filtered cost 161 map. 163 Additionally, this document introduces ALTO Entity Domains, where an 164 entity is a generalization of an endpoint to also represent, a PID, a 165 network element, or a cell in a cellular network, etc. As a 166 consequence, ALTO Entity Domains defined in this document are a 167 super-set of ALTO Address Types defined in [RFC7285]. Their exact 168 relationship is specified in Section 9.2.1. 170 Entity domains and property names are extensible. New entity domains 171 can be defined without revising the messages defined in this 172 document, in the same way that new cost metrics and new endpoint 173 properties can be defined without revising the messages defined in 174 [RFC7285]. 176 This proposal subsumes the Endpoint Property Service defined in 177 [RFC7285], although that service may be retained for legacy clients 178 (see Section 6). 180 2. Definitions and Concepts 182 2.1. Entity 184 The entity generalizes the concept of the endpoint defined in 185 Section 2.1 of [RFC7285]. An entity is an object that can be an 186 endpoint and is identified by its network address, but can also be an 187 object that has a defined mapping to a set of one or more network 188 addresses or is even not related to any network address. 190 Examples of eligible entities are: 192 o a PID, defined in [RFC7285], that has a provider defined human 193 readable abstract identifier and maps to a set of ipv4 and ipv6 194 addresses, 196 o an ASN number, that has a specified identifier and direct mapping 197 to network addresses, 199 o a country code, that specified in ISO 3166 format and that can be 200 retrieved from an IP of cellular address. As a consequence, all 201 endpoints are entities while not all entities are endpoints, 203 o a TCP/IP network flow, that has a server defined identifier and 204 represents in a TCP/IP 5-Tuple, 206 o a routing element, that specified in [RFC7921] and includes 207 routing capability information, 209 o an abstract network element, that has a server defined identifier 210 and represents a network node, link or their aggregation. 212 2.2. Entity Domain 214 Each entity MUST be in one and only one entity domain. An entity 215 domain is a class of entities. Examples of entity domains are the 216 Internet address domains (see Section 3.1 and the PID domain (see 217 Section 3.2). The future documents can define new entity domains to 218 satisfy the additional requirements such as cellular network 219 information and routing capability exposure. But they are not in the 220 scope of this document. 222 2.3. Domain Name 224 Each entity domain has a unique name. A domain name MUST be no more 225 than 32 characters, and MUST NOT contain characters other than US- 226 ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and 227 U+0061-U+007A), hyphen ("-", U+002D), and low line ("_", U+005F). 228 For example, the names "ipv4" and "ipv6" identify entities in the 229 Internet address domains (see Section 3.1). 231 The type DomainName is used in this document to denote a JSON string 232 with a domain name in this format. 234 Domain names MUST be registered with the IANA, and the format of the 235 entity addresses (see Section 2.4) in that entity domain, as well as 236 any hierarchical or inheritance rules (see Section 2.6) for those 237 entities, MUST be specified at the same time. 239 2.4. Entity Identifier 241 Each entity has an identifier of the format: 243 EntityId ::= DomainName : DomainSpecificEntityId 245 An entity identifier uniquely identifies a particular entity within 246 an ALTO property map resource (see Section 4). 248 Examples from the IP domains include individual IP addresses such as 249 "ipv4:192.0.2.14" and "ipv6:2001:db8::12", as well as address blocks 250 such as "ipv4:192.0.2.0/26" and "ipv6:2001:db8::1/48". 252 The type EntityId is used in this document to denote a JSON string 253 with an entity identifier in this format. 255 The format of the second part of an entity identifier depends on the 256 entity domain, and MUST be specified when registering a new entity 257 domain. Identifiers MAY be hierarchical, and properties MAY be 258 inherited based on that hierarchy. Again, the rules defining any 259 hierarchy or inheritance MUST be defined when the entity domain is 260 registered. 262 Note that an entity address MAY have different textual 263 representations, for a given entity domain. For example, the strings 264 "ipv6:2001:db8::1" and "ipv6:2001:db8:0:0:0:0:0:1" refer to the same 265 entity. 267 2.5. Property Type and Property Name 269 Every entity in some domain MAY have one or more properties. Every 270 property is identified by a Property Type and is specific to a 271 domain. Every property MUST have a unique Property Type. 273 This document defines property types in the domain-specific 274 semantics. Multiple property types with similar semantics MAY share 275 the same Property Name in different entity domains. But each 276 property type MUST be registered for a single specific entity domain 277 for the following reasons: 279 o Some properties may only be applicable for particular entity 280 domains, not all. For example, the "pid" property is not 281 applicable for entities in the "pid" domain. 283 o The interpretation of the value of a property may depend on the 284 entity domain. For different entity domains, not only the 285 intended semantics but also the dependent resource types may be 286 totally different. For example, suppose that the "geo-location" 287 property is defined as the coordinates of a point, encoded as 288 (say) "latitude longitude [altitude]." When applied to an entity 289 that represents a specific host computer, identified by an address 290 in the ipv4 or ipv6 domain, the property defines the host's 291 location and has no required dependency. However, when applied to 292 an entity in the "pid" domain, the property would indicate the 293 location of the center of all hosts in this "pid" entity and 294 depend on the Network Map defining this "pid" entity. 296 Therefore, each property type has a unique identifier encoded with 297 the following format: 299 PropertyType ::= DomainName : PropertyName 301 o The "DomainName" indicates which entity domain the property type 302 applies to. 304 o The "PropertyName" SHOULD relate to the semantics of this property 305 type. It does not have to be globally unique. In other words, 306 different property types could have the same property name applied 307 to different entity domains, if they have the similar semantics. 308 For example, the property types "ipv4:pid" and "ipv6:pid" have the 309 same property name "pid" applied to both "ipv4" and "ipv6" 310 domains. 312 Property types MUST be registered with the IANA, and the intended 313 semantics, as well as the media types of dependent resources and the 314 interpretation, MUST be specified at the same time. 316 2.6. Hierarchy and Inheritance 318 Entities in a given domain MAY form a hierarchy based on entity 319 identifiers, and introducing hierarchy allows the introduction of 320 inheritance. Each entity domain MUST define its own hierarchy and 321 inheritance rules when registered. The hierarchy and inheritance 322 rule makes it possible for an entity to inherit a property value from 323 another entity in the same domain. 325 2.7. Relationship with Other ALTO Resources 327 [RFC7285] recognizes that some properties for some entity domains MAY 328 be specific to an ALTO resource, such as a network map. Accordingly 329 Section 10.8.1 of [RFC7285] defines the concept of "resource-specific 330 endpoint properties", and indicates that dependency by prefixing the 331 property name with the ID of the resource on which it depends. That 332 document defines one resource-specific property, namely the "pid" 333 property, whose value is the name of the PID containing that endpoint 334 in the associated network map. 336 Because a property may be associated to more than one information 337 resources within an entity domain, this document takes a different 338 approach as follows: 340 o Firstly, instead of defining the dependency by prefixing the 341 property name with a specific dependent resource identifier, this 342 document introduces a Property Type that appends a property name 343 to an entity domain name, and registers the dependency types for 344 this Property Type. This gives a hint on the types of dependent 345 resources. For example, the fictitious property "pid:region" 346 applying to entities in the PID domain depends on the network map 347 in which the input PID entities have been defined; but the 348 fictitious property "ipv4:region" does not depend on any 349 information resource. 351 o Secondly, it sets a rule saying that in a property map, all 352 provided property types MUST have the same dependency types. For 353 example, "pid:region" and "ipv4:region" cannot be provided by an 354 individual property map. 356 o Finally, it identifies, in the IRD and Server responses, the 357 sequence of information resources associated to all provided 358 properties in a particular property map. If a property depends on 359 some different information resources from other properties, the 360 ALTO server should define a different property map to provide it. 361 For example, the property "ipv4:pid" provided by a particular 362 property map MUST depend on one and only one network map. If an 363 ALTO server wants to provide "ipv4:pid" for PIDs defined in both 364 network maps "net1" and "net2", it MUST define two individual 365 property maps. 367 To specify the aforementionned dependencies, this document uses the 368 "uses" and "dependent-vtags" fields defined respectively in Sections 369 9.1.5 and 11.1 of [RFC7285]. 371 o the "uses" field is included in the IRD entry of a resources- 372 dependent information resource and specifies the dependent IRD 373 resource. 375 o the "dependent-vtags" member is used in a Server response message 376 to specify the dependent resource. 378 3. Entity Domains 380 This document defines three entity domains. The definition of each 381 entity domain below includes the following: (1) domain name, (2) 382 domain-specific entity identifiers, and (3) hierarchy and inheritance 383 semantics. 385 3.1. Internet Address Domains 387 The document defines two entity domains (IPv4 and IPv6) for Internet 388 addresses. Both entity domains include individual addresses and 389 blocks of addresses. Since the two domains use the same hierarchy 390 and inheritance semantics, we define the semantics together, instead 391 of repeating for each. 393 3.1.1. IPv4 Domain 395 3.1.1.1. Domain Name 397 ipv4 399 3.1.1.2. Domain-Specific Entity Identifiers 401 Individual addresses are strings as specified by the IPv4Addresses 402 rule of Section 3.2.2 of [RFC3986]; blocks of addresses are prefix- 403 match strings as specified in Section 3.1 of [RFC4632]. For the 404 purpose of defining properties, an individual Internet address and 405 the corresponding full-length prefix are considered aliases for the 406 same entity. Thus "ipv4:192.0.2.0" and "ipv4:192.0.2.0/32" are 407 equivalent. 409 3.1.2. IPv6 Domain 411 3.1.2.1. Domain Name 413 ipv6 415 3.1.2.2. Domain-Specific Entity Identifiers 417 Individual addresses are strings as specified by Section 4 of 418 [RFC5952]; blocks of addresses are prefix-match strings as specified 419 in Section 7 of [RFC5952]. For the purpose of defining properties, 420 an individual Internet address and the corresponding 128-bit prefix 421 are considered aliases for the same entity. That is, 422 "ipv6:2001:db8::1" and "ipv6:2001:db8::1/128" are equivalent, and 423 have the same set of properties. 425 3.1.3. Hierarchy and Inheritance of ipv4/ipv6 Domains 427 Both Internet address domains allow property values to be inherited. 428 Specifically, if a property P is not defined for a specific Internet 429 address I, but P is defined for some block C which prefix-matches I, 430 then the address I inherits the value of P defined for block C. If 431 more than one such block defines a value for P, I inherits the value 432 of P in the block with the longest prefix. It is important to notice 433 that this longest prefix rule will ensure no multiple inheritance, 434 and hence no ambiguity. 436 Address blocks can also inherit properties: if a property P is not 437 defined for a block C, but is defined for some block C' which covers 438 all IP addresses in C, and C' has a shorter mask than C, then block C 439 inherits the property from C'. If there are several such blocks C', 440 C inherits from the block with the longest prefix. 442 As an example, suppose that a server defines a property P for the 443 following entities: 445 ipv4:192.0.2.0/26: P=v1 446 ipv4:192.0.2.0/28: P=v2 447 ipv4:192.0.2.0/30: P=v3 448 ipv4:192.0.2.0: P=v4 450 Figure 1: Defined Property Values. 452 Then the following entities have the indicated values: 454 ipv4:192.0.2.0: P=v4 455 ipv4:192.0.2.1: P=v3 456 ipv4:192.0.2.16: P=v1 457 ipv4:192.0.2.32: P=v1 458 ipv4:192.0.2.64: (not defined) 459 ipv4:192.0.2.0/32: P=v4 460 ipv4:192.0.2.0/31: P=v3 461 ipv4:192.0.2.0/29: P=v2 462 ipv4:192.0.2.0/27: P=v1 463 ipv4:192.0.2.0/25: (not defined) 465 Figure 2: Inherited Property Values. 467 An ALTO server MAY explicitly indicate a property as not having a 468 value for a particular entity. That is, a server MAY say that 469 property P of entity X is "defined to have no value", instead of 470 "undefined". To indicate "no value", a server MAY perform different 471 behaviours: 473 o If that entity would inherit a value for that property, then the 474 ALTO server MUST return a "null" value for that property. In this 475 case, the ALTO client MUST recognize a "null" value as "no value" 476 and "do not apply the inheritance rules for this property." 478 o If the entity would not inherit a value, then the ALTO server MAY 479 return "null" or just omit the property. In this case, the ALTO 480 client cannot infer the value for this property of this entity 481 from the Inheritance rules. So the client MUST interpret that 482 this property has no value. 484 If the ALTO server does not define any properties for an entity, then 485 the server MAY omit that entity from the response. 487 3.2. PID Domain 489 The PID domain associates property values with the PIDs in a network 490 map. Accordingly, this entity domain always depends on a network 491 map. 493 3.2.1. Domain Name 495 pid 497 3.2.2. Domain-Specific Entity Identifiers 499 The entity identifiers are the PID names of the associated network 500 map. 502 3.2.3. Hierarchy and Inheritance 504 There is no hierarchy or inheritance for properties associated with 505 PIDs. 507 3.2.4. Relationship To Internet Addresses Domains 509 The PID domain and the Internet address domains are completely 510 independent; the properties associated with a PID have no relation to 511 the properties associated with the prefixes or endpoint addresses in 512 that PID. An ALTO server MAY choose to assign some or all properties 513 of a PID to the prefixes in that PID. 515 For example, suppose "PID1" consists of the prefix 516 "ipv4:192.0.2.0/24", and has the property "P" with value "v1". The 517 Internet address entities "ipv4:192.0.2.0" and "ipv4:192.0.2.0/24", 518 in the IPv4 domain MAY have a value for the property "P", and if they 519 do, it is not necessarily "v1". 521 3.3. Internet Address Properties vs. PID Properties 523 Because the Internet address and PID domains are completely separate, 524 the question may arise as to which entity domain is the best for a 525 property. In general, the Internet address domains are RECOMMENDED 526 for properties that are closely related to the Internet address, or 527 are associated with, and inherited through, blocks of addresses. 529 The PID domain is RECOMMENDED for properties that arise from the 530 definition of the PID, rather than from the Internet address prefixes 531 in that PID. 533 For example, because Internet addresses are allocated to service 534 providers by blocks of prefixes, an "ISP" property would be best 535 associated with the Internet address domain. On the other hand, a 536 property that explains why a PID was formed, or how it relates a 537 provider's network, would best be associated with the PID domain. 539 4. Property Map 541 A property map returns the properties defined for all entities in one 542 or more domains, e.g., the "location" property of entities in "pid" 543 domain, and the "ASN" property of entities in "ipv4" and "ipv6" 544 domains. 546 Section 7.4 gives an example of a property map request and its 547 response. 549 4.1. Media Type 551 The media type of a property map is "application/alto-propmap+json". 553 4.2. HTTP Method 555 The property map is requested using the HTTP GET method. 557 4.3. Accept Input Parameters 559 None. 561 4.4. Capabilities 563 The capabilities are defined by an object of type 564 PropertyMapCapabilities: 566 object { 567 DomainName entity-domains<1..*>; 568 PropertyName properties<1..*>; 569 } PropertyMapCapabilities; 571 where "entity-domains" is an array specifying the entity domains, and 572 "properties" is an array specifying the property names returned for 573 entities in those domains. The semantics is that this property map 574 provides all property types generated by the cross product of 575 "entity-domains" and "properties". If a property in "properties" is 576 NOT supported by a domain in "entity-domains", the server can declare 577 different property maps to conform to the semantics. 579 For example, the capability {"entity-domains": ["ipv4", "ipv6"], 580 "properties": ["pid"]} means the property map provides both property 581 types "ipv4:pid" and "ipv6:pid". 583 4.5. Uses 585 The "uses" field of a property map resource in an IRD entry specifies 586 dependencies as discussed in Section 2.7. It is an array of the 587 resource ID(s) of the resource(s) that properties of entities in 588 domains specified in "entity-domains" depend on. 590 In a single property map, every property value of every entity 591 depends on the same array of resources. Thus, if properties 592 depending on different resources arrays would be provided, they MUST 593 be split into different property maps. 595 Note that according to [RFC7285], a legacy ALTO server with two 596 network maps, with resource IDs "net1" and "net2", could offer a 597 single Endpoint Property Service for the two properties "net1.pid" 598 and "net2.pid". An ALTO server which supports the property map 599 resource defined in this document, would, instead, offer two 600 different property maps for the "pid" property, one depending on 601 "net1", and the other on "net2". 603 4.6. Response 605 If the entity domains in this property map depend on other resources, 606 the "dependent-vtags" field in the "meta" field of the response MUST 607 be an array that includes the version tags of those resources, and 608 the order MUST be consistent with the "uses" field of this property 609 map resource. The data component of a property map response is named 610 "property-map", which is a JSON object of type PropertyMapData, 611 where: 613 object { 614 PropertyMapData property-map; 615 } InfoResourceProperties : ResponseEntityBase; 617 object-map { 618 EntityId -> EntityProps; 619 } PropertyMapData; 621 object { 622 PropertyName -> JSONValue; 623 } EntityProps; 625 The ResponseEntityBase type is defined in Section 8.4 of [RFC7285]. 627 Specifically, a PropertyMapData object has one member for each entity 628 in the property map. The entity's properties are encoded in the 629 corresponding EntityProps object. EntityProps encodes one name/value 630 pair for each property, where the property names are encoded as 631 strings of type PropertyName. A protocol implementation SHOULD 632 assume that the property value is either a JSONString or a JSON 633 "null" value, and fail to parse if it is not, unless the 634 implementation is using an extension to this document that indicates 635 when and how property values of other data types are signaled. 637 For each entity in the Property Map, the ALTO server returns the 638 value defined for each of the properties specified in this resource's 639 "capabilities" list. For efficiency, the ALTO server SHOULD omit 640 property values that are inherited rather than explicitly defined; if 641 a client needs inherited values, the client SHOULD use the entity 642 domain's inheritance rules to deduce those values. 644 5. Filtered Property Map 646 A filtered property map returns the values of a set of properties for 647 a set of entities selected by the client. 649 Section 7.5, Section 7.6, Section 7.7 and Section 7.8 give examples 650 of filtered property map requests and responses. 652 5.1. Media Type 654 The media type of a property map resource is "application/alto- 655 propmap+json". 657 5.2. HTTP Method 659 The filtered property map is requested using the HTTP POST method. 661 5.3. Accept Input Parameters 663 The input parameters for a filtered property map request are supplied 664 in the entity body of the POST request. This document specifies the 665 input parameters with a data format indicated by the media type 666 "application/alto-propmapparams+json", which is a JSON object of type 667 ReqFilteredPropertyMap: 669 object { 670 EntityId entities<1..*>; 671 PropertyName properties<1..*>; 672 } ReqFilteredPropertyMap; 674 with fields: 676 entities: List of entity identifiers for which the specified 677 properties are to be returned. The ALTO server MUST interpret 678 entries appearing multiple times as if they appeared only once. 679 The domain of each entity MUST be included in the list of entity 680 domains in this resource's "capabilities" field (see Section 5.4). 682 properties: List of properties to be returned for each entity. Each 683 specified property MUST be included in the list of properties in 684 this resource's "capabilities" field (see Section 5.4). The ALTO 685 server MUST interpret entries appearing multiple times as if they 686 appeared only once. 688 Note that the "entities" and "properties" fields MUST have at 689 least one entry each. 691 5.4. Capabilities 693 The capabilities are defined by an object of type 694 PropertyMapCapabilities, as defined in Section 4.4. 696 5.5. Uses 698 The "uses" field of a filtered property map is an array with the 699 resource ID(s) of resource(s) that each domain in "entity-domains" 700 depends on, in order to provide the properties specified in the 701 "properties" capability. The same "uses" rule as defined by the 702 property map resource applies (see Section 4.5). 704 5.6. Response 706 The response MUST indicate an error, using ALTO protocol error 707 handling, as defined in Section 8.5 of [RFC7285], if the request is 708 invalid. 710 Specifically, a filtered property map request can be invalid as 711 follows: 713 o An entity identifiers in "entities" in the request is invalid if: 715 * The domain of this entity is not defined in the "entity-domain- 716 types" capability of this resource in the IRD; 718 * The entity identifier is an invalid identifier in the entity 719 domain. 721 A valid entity identifier is never an error, even if this filtered 722 property map resource does not define any properties for it. 724 If an entity identifier in "entities" in the request is invalid, 725 the ALTO server MUST return an "E_INVALID_FIELD_VALUE" error 726 defined in Section 8.5.2 of [RFC7285], and the "value" field of 727 the error message SHOULD indicate this entity identifier. 729 o A property name in "properties" in the request is invalid if this 730 property name is not defined in the "property-types" capability of 731 this resource in the IRD. 733 It is not an error that a filtered property map resource does not 734 define a requested property's value for a particular entity. In 735 this case, the ALTO server MUST omit that property from the 736 response for that endpoint. 738 If a property name in "properties" in the request is invalid, the 739 ALTO server MUST return an "E_INVALID_FIELD_VALUE" error defined 740 in Section 8.5.2 of [RFC7285]. The "value" field of the error 741 message SHOULD indicate the property name. 743 The response to a valid request is the same as for the Property Map 744 (see Section 4.6), except that: 746 o The "dependent-vtags" field in its "meta" field only includes the 747 version tags of resources on which the requested properties of the 748 entity domains depend, and the order MUST be consistent with the 749 "uses" field of this filtered property map resource. 751 o It only includes the entities and properties requested by the 752 client. If an entity in the request is an identifier block (e.g., 753 an "ipv4" or "ipv6" entity), the response MUST cover properties 754 for all identifiers in this block. 756 It is important that the filtered property map response MUST include 757 all inherited property values for the requested entities and all the 758 entities which are able to inherit property values from them. To 759 achieve this goal, the ALTO server MAY follow three rules: 761 o If a property for a requested entity is inherited from another 762 entity not included in the request, the response SHOULD include 763 this property for the requested entity. For example, A full 764 property map may skip a property P for an entity A (e.g., 765 ipv4:192.0.2.0/31) if P can be derived using inheritance from 766 another entity B (e.g., ipv4:192.0.2.0/30). A filtered property 767 map request may include only A but not B. In such a case, the 768 property P SHOULD be included in the response for A. 770 o If there are entities covered by a requested entity but having 771 different values for the requested properties, the response SHOULD 772 include all those entities and the different property values for 773 them. For example, considering a request for property P of entity 774 A (e.g., ipv4:192.0.2.0/31), if P has value v1 for 775 A1=ipv4:192.0.2.0/32 and v2 for A2=ipv4:192.0.2.1/32, then, the 776 response SHOULD include A1 and A2. 778 o If an entity in the response is already covered by some other 779 entities in the same response, it SHOULD be removed from the 780 response for compactness. For example, in the previous example, 781 the entity A=ipv4:192.0.2.0/31 SHOULD be removed because A1 and A2 782 cover all the addresses in A. 784 An ALTO client should be aware that the entities in the response MAY 785 be different from the entities in its request. 787 6. Impact on Legacy ALTO Servers and ALTO Clients 789 6.1. Impact on Endpoint Property Service 791 Since the property map and the filtered property map defined in this 792 document provide the functionality of the Endpoint Property Service 793 (EPS) defined in Section 11.4 of [RFC7285], it is RECOMMENDED that 794 the EPS be deprecated in favor of Property Map and Filtered Property 795 Map. However, ALTO servers MAY provide an EPS for the benefit of 796 legacy clients. 798 6.2. Impact on Resource-Specific Properties 800 Section 10.8 of [RFC7285] defines two categories of endpoint 801 properties: "resource-specific" and "global". Resource-specific 802 property names are prefixed with the ID of the resource they depend 803 upon, while global property names have no such prefix. The property 804 map and the filtered property map defined in this document do not 805 distinguish between those two types of properties. Instead, if there 806 is a dependency, it is indicated by the "uses" capability of a 807 property map, and is shared by all properties and entity domains in 808 that map. Accordingly, it is RECOMMENDED that resource-specific 809 endpoint properties be deprecated, and no new resource-specific 810 endpoint properties be defined. 812 6.3. Impact on the pid Property 814 Section 7.1.1 of [RFC7285] defines the resource-specific endpoint 815 property name "pid", whose value is the name of the PID containing 816 that endpoint. For compatibility with legacy clients, an ALTO server 817 which provides the "pid" property via the EPS MUST use that 818 definition, and that syntax. 820 However, when used with property maps, this document amends the 821 definition of the "pid" property as follows. 823 First, the name of the property is simply "pid"; the name is not 824 prefixed with the resource ID of a network map. The "uses" 825 capability of the property map indicates the associated network map. 826 This implies that a property map can only return the "pid" property 827 for one network map; if an ALTO server provides several network maps, 828 it MUST provide a Property Map for each of the network maps. 830 Second, a client MAY request the "pid" property for a block of 831 Internet addresses. An ALTO server determines the value of "pid" for 832 an address block C as the rules defined in Section 5.6. 834 Note that although an ALTO server MAY provide a GET-mode property map 835 which returns the entire map for the "pid" property, there is no need 836 to do so, because that map is simply the inverse of the network map. 838 6.4. Impact on Other Properties 840 In general, there should be little or no impact on other previously 841 defined properties. The only consideration is that properties can 842 now be defined on blocks of identifiers, rather than just individual 843 identifiers, which might change the semantics of a property. 845 7. Examples 847 7.1. Network Map 849 The examples in this section use a very simple default network map: 851 defaultpid: ipv4:0.0.0.0/0 ipv6:::0/0 852 pid1: ipv4:192.0.2.0/25 853 pid2: ipv4:192.0.2.0/28 ipv4:192.0.2.16/28 854 pid3: ipv4:192.0.3.0/28 855 pid4: ipv4:192.0.3.16/28 857 Figure 3: Example Network Map 859 7.2. Property Definitions 861 Beyond "pid", the examples in this section use four additional 862 properties for Internet address domains, "ISP", "ASN", "country" and 863 "state", with the following values: 865 ISP ASN country state 866 ipv4:192.0.2.0/23: BitsRus - us - 867 ipv4:192.0.2.0/28: - 12345 - NJ 868 ipv4:192.0.2.16/28: - 12345 - CT 869 ipv4:192.0.2.0: - - - PA 870 ipv4:192.0.3.0/28: - 12346 - TX 871 ipv4:192.0.3.16/28: - 12346 - MN 873 Figure 4: Example Property Values for Internet Address Domains 875 And the examples in this section use the property "region" for PID 876 domain with the following values: 878 region 879 pid:defaultpid: - 880 pid:pid1: west 881 pid:pid2: east 882 pid:pid3: south 883 pid:pid4: north 885 Figure 5: Example Property Values for PID Domain 887 Note that "-" means the value of the property for the entity is 888 "undefined". So the entity would inherit a value for this property 889 by the inheritance rule if possible. For example, the value of the 890 "ISP" property for "ipv4:192.0.2.0" is "BitsRus" because of 891 "ipv4:192.0.2.0/24". But the "region" property for "pid:defaultpid" 892 has no value because no entity from which it can inherit. 894 7.3. Information Resource Directory (IRD) 896 The following IRD defines the relevant resources of the ALTO server. 897 It provides two property maps, one for the "ISP" and "ASN" 898 properties, and another for the "country" and "state" properties. 899 The server could have provided a single property map for all four 900 properties, but did not, presumably because the organization that 901 runs the ALTO server believes any given client is not interested in 902 all four properties. 904 The server provides two filtered property maps. The first returns 905 all four properties, and the second just returns the "pid" property 906 for the default network map. 908 The filtered property maps for the "ISP", "ASN", "country" and 909 "state" properties do not depend on the default network map (it does 910 not have a "uses" capability), because the definitions of those 911 properties do not depend on the default network map. The Filtered 912 Property Map for the "pid" property does have a "uses" capability for 913 the default network map, because that defines the values of the "pid" 914 property. 916 Note that for legacy clients, the ALTO server provides an Endpoint 917 Property Service for the "pid" property for the default network map. 919 "meta" : { 920 ... 921 "default-alto-network-map" : "default-network-map" 922 }, 923 "resources" : { 924 "default-network-map" : { 925 "uri" : "http://alto.example.com/networkmap", 926 "media-type" : "application/alto-networkmap+json" 927 }, 928 .... property map resources .... 929 "country-state-property-map" : { 930 "uri" : "http://alto.example.com/propmap/full/inet-cs", 931 "media-type" : "application/alto-propmap+json", 932 "capabilities" : { 933 "entity-domains": [ "ipv4", "ipv6" ], 934 "properties" : [ "country", "state" ] 935 } 936 }, 937 "isp-asn-property-map" : { 938 "uri" : "http://alto.example.com/propmap/full/inet-ia", 939 "media-type" : "application/alto-propmap+json", 940 "capabilities" : { 941 "entity-domains": [ "ipv4", "ipv6" ], 942 "properties" : [ "ISP", "ASN" ] 943 } 944 }, 945 "iacs-property-map" : { 946 "uri" : "http://alto.example.com/propmap/lookup/inet-iacs", 947 "media-type" : "application/alto-propmap+json", 948 "accepts" : "application/alto-propmapparams+json", 949 "capabilities" : { 950 "entity-domains": [ "ipv4", "ipv6" ], 951 "properties" : [ "ISP", "ASN", "country", "state" ] 952 } 953 }, 954 "pid-property-map" : { 955 "uri" : "http://alto.example.com/propmap/lookup/pid", 956 "media-type" : "application/alto-propmap+json", 957 "accepts" : "application/alto-propmapparams+json", 958 "uses" : [ "default-network-map" ] 959 "capabilities" : { 960 "entity-domains" : [ "ipv4", "ipv6" ], 961 "properties" : [ "pid" ] 962 } 963 }, 964 "region-property-map": { 965 "uri": "http://alto.exmaple.com/propmap/region", 966 "media-type": "application/alto-propmap+json", 967 "accepts": "application/alto-propmapparams+json", 968 "uses" : [ "default-network-map" ], 969 "capabilities": { 970 "domain-types": [ "pid" ], 971 "properties": [ "region" ] 972 } 973 }, 974 "legacy-pid-property" : { 975 "uri" : "http://alto.example.com/legacy/eps-pid", 976 "media-type" : "application/alto-endpointprop+json", 977 "accepts" : "application/alto-endpointpropparams+json", 978 "capabilities" : { 979 "properties" : [ "default-network-map.pid" ] 980 } 981 } 982 } 984 Figure 6: Example IRD 986 7.4. Property Map Example 988 The following example uses the properties and IRD defined above to 989 retrieve a Property Map for entities with the "ISP" and "ASN" 990 properties. 992 Note that, to be compact, the response does not includes the entity 993 "ipv4:192.0.2.0", because values of all those properties for this 994 entity are inherited from other entities. 996 Also note that the entities "ipv4:192.0.2.0/28" and 997 "ipv4:192.0.2.16/28" are merged into "ipv4:192.0.2.0/27", because 998 they have the same value of the "ASN" property. The same rule 999 applies to the entities "ipv4:192.0.3.0/28" and "ipv4:192.0.3.0/28". 1000 Both of "ipv4:192.0.2.0/27" and "ipv4:192.0.3.0/27" omit the value 1001 for the "ISP" property, because it is inherited from 1002 "ipv4:192.0.2.0/23". 1004 GET /propmap/full/inet-ia HTTP/1.1 1005 Host: alto.example.com 1006 Accept: application/alto-propmap+json,application/alto-error+json 1007 HTTP/1.1 200 OK 1008 Content-Length: ### 1009 Content-Type: application/alto-propmap+json 1011 { 1012 "property-map": { 1013 "ipv4:192.0.2.0/23": {"ISP": "BitsRus"}, 1014 "ipv4:192.0.2.0/27": {"ASN": "12345"}, 1015 "ipv4:192.0.3.0/27": {"ASN": "12346"} 1016 } 1017 } 1019 7.5. Filtered Property Map Example #1 1021 The following example uses the filtered property map resource to 1022 request the "ISP", "ASN" and "state" properties for several IPv4 1023 addresses. 1025 Note that the value of "state" for "ipv4:192.0.2.0" is the only 1026 explicitly defined property; the other values are all derived by the 1027 inheritance rules for Internet address entities. 1029 POST /propmap/lookup/inet-iacs HTTP/1.1 1030 Host: alto.example.com 1031 Accept: application/alto-propmap+json,application/alto-error+json 1032 Content-Length: ### 1033 Content-Type: application/alto-propmapparams+json 1035 { 1036 "entities" : [ "ipv4:192.0.2.0", 1037 "ipv4:192.0.2.1", 1038 "ipv4:192.0.2.17" ], 1039 "properties" : [ "ISP", "ASN", "state" ] 1040 } 1041 HTTP/1.1 200 OK 1042 Content-Length: ### 1043 Content-Type: application/alto-propmap+json 1045 { 1046 "property-map": { 1047 "ipv4:192.0.2.0": 1048 {"ISP": "BitsRus", "ASN": "12345", "state": "PA"}, 1049 "ipv4:192.0.2.1": 1050 {"ISP": "BitsRus", "ASN": "12345", "state": "NJ"}, 1051 "ipv4:192.0.2.17": 1052 {"ISP": "BitsRus", "ASN": "12345", "state": "CT"} 1053 } 1054 } 1056 7.6. Filtered Property Map Example #2 1058 The following example uses the filtered property map resource to 1059 request the "ASN", "country" and "state" properties for several IPv4 1060 prefixes. 1062 Note that the property values for both entities "ipv4:192.0.2.0/26" 1063 and "ipv4:192.0.3.0/26" are not explicitly defined. They are 1064 inherited from the entity "ipv4:192.0.2.0/23". 1066 Also note that some entities like "ipv4:192.0.2.0/28" and 1067 "ipv4:192.0.2.16/28" in the response are not listed in the request 1068 explicitly. The response includes them because they are refinements 1069 of the requested entities and have different values for the requested 1070 properties. 1072 The entity "ipv4:192.0.4.0/26" is not included in the response, 1073 because there are neither entities which it is inherited from, nor 1074 entities inherited from it. 1076 POST /propmap/lookup/inet-iacs HTTP/1.1 1077 Host: alto.example.com 1078 Accept: application/alto-propmap+json,application/alto-error+json 1079 Content-Length: ### 1080 Content-Type: application/alto-propmapparams+json 1082 { 1083 "entities" : [ "ipv4:192.0.2.0/26", 1084 "ipv4:192.0.3.0/26", 1085 "ipv4:192.0.4.0/26" ], 1086 "properties" : [ "ASN", "country", "state" ] 1087 } 1088 HTTP/1.1 200 OK 1089 Content-Length: ### 1090 Content-Type: application/alto-propmap+json 1092 { 1093 "property-map": { 1094 "ipv4:192.0.2.0/26": {"country": "us"}, 1095 "ipv4:192.0.2.0/28": {"ASN": "12345", 1096 "state": "NJ"}, 1097 "ipv4:192.0.2.16/28": {"ASN": "12345", 1098 "state": "CT"}, 1099 "ipv4:192.0.2.0": {"state": "PA"}, 1100 "ipv4:192.0.3.0/26": {"country": "us"}, 1101 "ipv4:192.0.3.0/28": {"ASN": "12345", 1102 "state": "TX"}, 1103 "ipv4:192.0.3.16/28": {"ASN": "12345", 1104 "state": "MN"} 1105 } 1106 } 1108 7.7. Filtered Property Map Example #3 1110 The following example uses the filtered property map resource to 1111 request the "pid" property for several IPv4 addresses and prefixes. 1113 Note that the entity "ipv4:192.0.3.0/27" is redundant in the 1114 response. Although it can inherit a value of "defaultpid" for the 1115 "pid" property from the entity "ipv4:0.0.0.0/0", none of addresses in 1116 it is in "defaultpid". Because blocks "ipv4:192.0.3.0/28" and 1117 "ipv4:192.0.3.16/28" have already cover all addresses in that block. 1118 So an ALTO server who wants a compact response can omit this entity. 1120 POST /propmap/lookup/pid HTTP/1.1 1121 Host: alto.example.com 1122 Accept: application/alto-propmap+json,application/alto-error+json 1123 Content-Length: ### 1124 Content-Type: application/alto-propmapparams+json 1126 { 1127 "entities" : [ 1128 "ipv4:192.0.2.128", 1129 "ipv4:192.0.3.0/27" ], 1130 "properties" : [ "pid" ] 1131 } 1132 HTTP/1.1 200 OK 1133 Content-Length: ### 1134 Content-Type: application/alto-propmap+json 1136 { 1137 "meta" : { 1138 "dependent-vtags" : [ 1139 {"resource-id": "default-network-map", 1140 "tag": "7915dc0290c2705481c491a2b4ffbec482b3cf62"} 1141 ] 1142 }, 1143 "property-map": { 1144 "ipv4:192.0.2.128": {"pid": "defaultpid"}, 1145 "ipv4:192.0.2.0/27": {"pid": "defaultpid"}, 1146 "ipv4:192.0.3.0/28": {"pid": "pid3"}, 1147 "ipv4:192.0.3.16/28": {"pid": "pid4"} 1148 } 1149 } 1151 7.8. Filtered Property Map Example #4 1153 The following example uses the filtered property map resource to 1154 request the "region" property for several PIDs defined in "default- 1155 network-map". The value of the "region" property for each PID is not 1156 defined by "default-network-map", but the reason why the PID is 1157 defined by the network operator. 1159 POST /propmap/lookup/region HTTP/1.1 1160 Host: alto.example.com 1161 Accept: application/alto-propmap+json,application/alto-error+json 1162 Content-Length: ### 1163 Content-Type: application/alto-propmapparams+json 1165 { 1166 "entities" : ["pid:pid1", 1167 "pid:pid2"], 1168 "properties" : [ "region" ] 1169 } 1170 HTTP/1.1 200 OK 1171 Content-Length: ### 1172 Content-Type: application/alto-propmap+json 1174 { 1175 "meta" : { 1176 "dependent-vtags" : [ 1177 {"resource-id": "default-network-map", 1178 "tag": "7915dc0290c2705481c491a2b4ffbec482b3cf62"} 1179 ] 1180 }, 1181 "property-map": { 1182 "pid:pid1": { 1183 "region": "west" 1184 }, 1185 "pid:pid2": { 1186 "region": "east" 1187 } 1188 } 1189 } 1191 8. Security Considerations 1193 Both Property Map and Filtered Property Map defined in this document 1194 fit into the architecture of the ALTO base protocol, and hence the 1195 Security Considerations (Section 15 of [RFC7285]) of the base 1196 protocol fully apply: authenticity and integrity of ALTO information 1197 (i.e., authenticity and integrity of Property Maps), potential 1198 undesirable guidance from authenticated ALTO information (e.g., 1199 potentially imprecise or even wrong value of a property such as geo- 1200 location), confidentiality of ALTO information (e.g., exposure of a 1201 potentially sensitive entity property such as geo-location), privacy 1202 for ALTO users, and availability of ALTO services should all be 1203 considered. 1205 A particular fundamental security consideration when an ALTO server 1206 provides a Property Map is to define precisely the policies on who 1207 can access what properties for which entities. Security mechanisms 1208 such as authentication and confidentiality mechanisms then should be 1209 applied to enforce the policy. For example, a policy can be that a 1210 property P can be accessed only by its owner (e.g., the customer who 1211 is allocated a given IP address). Then, the ALTO server will need to 1212 deploy corresponding mechanisms to realize the policy. The policy 1213 may allow non-owners to access a coarse-grained value of the property 1214 P. In such a case, the ALTO server may provide a different URI to 1215 provide the information. 1217 9. IANA Considerations 1219 This document defines additional application/alto-* media types, and 1220 extends the ALTO endpoint property registry. 1222 9.1. application/alto-* Media Types 1224 This document registers two additional ALTO media types, listed in 1225 Table 1. 1227 +--------------+--------------------------+-----------------------+ 1228 | Type | Subtype | Specification | 1229 +--------------+--------------------------+-----------------------+ 1230 | application | alto-propmap+json | Section 4.1 | 1231 | application | alto-propmapparams+json | Section 5.3 | 1232 +--------------+--------------------------+-----------------------+ 1234 Table 1: Additional ALTO Media Types. 1236 Type name: application 1238 Subtype name: This document registers multiple subtypes, as listed 1239 in Table 1. 1241 Required parameters: n/a 1243 Optional parameters: n/a 1245 Encoding considerations: Encoding considerations are identical to 1246 those specified for the "application/json" media type. See 1247 [RFC7159]. 1249 Security considerations: Security considerations related to the 1250 generation and consumption of ALTO Protocol messages are discussed 1251 in Section 15 of [RFC7285]. 1253 Interoperability considerations: This document specifies formats of 1254 conforming messages and the interpretation thereof. 1256 Published specification: This document is the specification for 1257 these media types; see Table 1 for the section documenting each 1258 media type. 1260 Applications that use this media type: ALTO servers and ALTO clients 1261 either stand alone or are embedded within other applications. 1263 Additional information: 1265 Magic number(s): n/a 1267 File extension(s): This document uses the mime type to refer to 1268 protocol messages and thus does not require a file extension. 1270 Macintosh file type code(s): n/a 1272 Person & email address to contact for further information: See 1273 Authors' Addresses section. 1275 Intended usage: COMMON 1277 Restrictions on usage: n/a 1279 Author: See Authors' Addresses section. 1281 Change controller: Internet Engineering Task Force 1282 (mailto:iesg@ietf.org). 1284 9.2. ALTO Entity Domain Registry 1286 This document requests IANA to create and maintain the "ALTO Entity 1287 Domain Registry", listed in Table 2. 1289 +------------+----------------+------------------+------------------+ 1290 | Identifier | Entity | Hierarchy & | Mapping to ALTO | 1291 | | Identifier | Inheritance | Address Type | 1292 | | Encoding | | | 1293 +------------+----------------+------------------+------------------+ 1294 | ipv4 | See | See | Yes | 1295 | | Section 3.1.1 | Section 3.1.3 | | 1296 | ipv6 | See | See | Yes | 1297 | | Section 3.1.2 | Section 3.1.3 | | 1298 | pid | See | None | No | 1299 | | Section 3.2 | | | 1300 +------------+----------------+------------------+------------------+ 1302 Table 2: ALTO Entity Domains. 1304 This registry serves two purposes. First, it ensures uniqueness of 1305 identifiers referring to ALTO entity domains. Second, it states the 1306 requirements for allocated entity domains. 1308 9.2.1. Consistency Procedure between ALTO Address Type Registry and 1309 ALTO Entity Domain Registry 1311 One potential issue of introducing the "ALTO Entity Domain Registry" 1312 is its relationship with the "ALTO Address Types Registry" already 1313 defined in Section 14.4 of [RFC7285]. In particular, the entity 1314 identifier of an entity domain registered in the "ALTO Entity Domain 1315 Registry" MAY match an address type defined in "ALTO Address Type 1316 Registry". It is necessary to precisely define and guarantee the 1317 consistency between "ALTO Address Type Registry" and "ALTO Entity 1318 Domain Registry". 1320 We define that the ALTO Entity Domain Registry is consistent with 1321 ALTO Address Type Registry if two conditions are satisfied: 1323 o When an address type is already or able to be registered in the 1324 ALTO Address Type Registry [RFC7285], the same identifier MUST be 1325 used when a corresponding entity domain is registered in the ALTO 1326 Entity Domain Registry. 1328 o If an ALTO entity domain has the same identifier as an ALTO 1329 address type, their addresses encoding MUST be compatible. 1331 To achieve this consistency, the following items MUST be checked 1332 before registering a new ALTO entity domain in a future document: 1334 o Whether the ALTO Address Type Registry contains an address type 1335 that can be used as an entity identifier for the candidate domain 1336 identifier. This has been done for the identifiers "ipv4" and 1337 "ipv6" in Table 2. 1339 o Whether the candidate entity identifier of the entity domain is 1340 able to be an endpoint address, as defined in Sections 2.1 and 2.2 1341 of [RFC7285]. 1343 When a new ALTO entity domain is registered, the consistency with the 1344 ALTO Address Type Registry MUST be ensured by the following 1345 procedure: 1347 o Test: Do corresponding entity identifiers match a known "network" 1348 address type? 1350 * If yes (e.g., cell, MAC or socket addresses): 1352 + Test: Is such an address type present in the ALTO Address 1353 Type Registry? 1354 - If yes: Set the new ALTO entity domain identifier to be 1355 the found ALTO address type identifier. 1357 - If no: Define a new ALTO entity domain identifier and use 1358 it to register a new address type in the ALTO Address 1359 Type Registry following Section 14.4 of [RFC7285]. 1361 + Use the new ALTO entity domain identifier to register a new 1362 ALTO entity domain in the ALTO Entity Domain Registry 1363 following Section 9.2.2 of this document. 1365 * If no (e.g., pid name, ane name or country code): Proceed with 1366 the ALTO Entity Domain registration as described in 1367 Section 9.2.2. 1369 9.2.2. ALTO Entity Domain Registration Process 1371 New ALTO entity domains are assigned after IETF Review [RFC5226] to 1372 ensure that proper documentation regarding the new ALTO entity 1373 domains and their security considerations has been provided. RFCs 1374 defining new entity domains SHOULD indicate how an entity in a 1375 registered domain is encoded as an EntityId, and, if applicable, the 1376 rules defining the entity hierarchy and property inheritance. 1377 Updates and deletions of ALTO entity domains follow the same 1378 procedure. 1380 Registered ALTO entity domain identifiers MUST conform to the 1381 syntactical requirements specified in Section 2.3. Identifiers are 1382 to be recorded and displayed as strings. 1384 Requests to the IANA to add a new value to the registry MUST include 1385 the following information: 1387 o Identifier: The name of the desired ALTO entity domain. 1389 o Entity Identifier Encoding: The procedure for encoding the 1390 identifier of an entity of the registered type as an EntityId (see 1391 Section 2.4). If corresponding entity identifiers of an entity 1392 domain match a known "network" address type, the Entity Identifier 1393 Encoding of this domain identifier MUST include both Address 1394 Encoding and Prefix Encoding of the same identifier registered in 1395 the ALTO Address Type Registry [RFC7285]. For the purpose of 1396 defining properties, an individual entity identifier and the 1397 corresponding full-length prefix MUST be considered aliases for 1398 the same entity. 1400 o Hierarchy: If the entities form a hierarchy, the procedure for 1401 determining that hierarchy. 1403 o Inheritance: If entities can inherit property values from other 1404 entities, the procedure for determining that inheritance. 1406 o Mapping to ALTO Address Type: A boolean value to indicate if the 1407 entity domain can be mapped to the ALTO address type with the same 1408 identifier. 1410 o Security Considerations: In some usage scenarios, entity 1411 identifiers carried in ALTO Protocol messages may reveal 1412 information about an ALTO client or an ALTO service provider. 1413 Applications and ALTO service providers using addresses of the 1414 registered type should be made aware of how (or if) the addressing 1415 scheme relates to private information and network proximity. 1417 This specification requests registration of the identifiers "ipv4", 1418 "ipv6" and "pid", as shown in Table 2. 1420 9.3. ALTO Entity Property Type Registry 1422 This document requests IANA to create and maintain the "ALTO Entity 1423 Property Type Registry", listed in Table 3. 1425 To distinguish with the "ALTO Endpoint Property Type Registry", each 1426 entry in this registry is an ALTO entity property type defined in 1427 Section 2.5. Thus, registered ALTO entity property type identifier 1428 MUST conform to the syntactical requirements specified in that 1429 section. 1431 The initial registered ALTO entity property types are listed in 1432 Table 3. 1434 +------------+------------------+-----------------------------------+ 1435 | Identifier | Intended | Dependencies and Interpretation | 1436 | | Semantics | | 1437 +------------+------------------+-----------------------------------+ 1438 | ipv4:pid | PID for the IPv4 | application/alto-networkmap+json, | 1439 | | entity | where the PID names are defined | 1440 | ipv6:pid | PID for the IPv6 | application/alto-networkmap+json, | 1441 | | entity | where the PID names are defined | 1442 +------------+------------------+-----------------------------------+ 1444 Table 3: ALTO Entity Property Types. 1446 Requests to the IANA to add a new value to the registry MUST include 1447 the following information: 1449 o Identifier: The unique id for the desired ALTO entity property 1450 type. The format MUST be as defined in Section 2.5 of this 1451 document. It includes the information of the applied ALTO entity 1452 domain and the property name. 1454 o Intended Semantics: ALTO entity properties carry with them 1455 semantics to guide their usage by ALTO clients. Hence, a document 1456 defining a new type SHOULD provide guidance to both ALTO service 1457 providers and applications utilizing ALTO clients as to how values 1458 of the registered ALTO entity property should be interpreted. 1460 o Dependencies and Interpretation: Dependent ALTO resources MAY be 1461 required by ALTO clients to interpret ALTO entity properties. 1462 Hence, a document defining a new type SHOULD provide a sequence of 1463 media types in which the dependent ALTO resources are and the 1464 guidance how ALTO clients use them to interpret the property. 1466 This specification requests registration of the identifiers 1467 "ipv4:pid" and "ipv6:pid", as shown in Table 3. 1469 9.4. Acknowledgments 1471 The authors would like to thank discussions with Kai Gao, Qiao Xiang, 1472 Shawn Lin, Xin Wang, Danny Perez, and Vijay Gurbani. The authors 1473 thank Dawn Chen (Tongji University), and Shenshen Chen (Tongji/Yale 1474 University) for their contributions to earlier drafts. 1476 10. Normative References 1478 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1479 Requirement Levels", BCP 14, RFC 2119, 1480 DOI 10.17487/RFC2119, March 1997, 1481 . 1483 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1484 Resource Identifier (URI): Generic Syntax", STD 66, 1485 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1486 . 1488 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 1489 (CIDR): The Internet Address Assignment and Aggregation 1490 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 1491 2006, . 1493 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1494 IANA Considerations Section in RFCs", RFC 5226, 1495 DOI 10.17487/RFC5226, May 2008, 1496 . 1498 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1499 Address Text Representation", RFC 5952, 1500 DOI 10.17487/RFC5952, August 2010, 1501 . 1503 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1504 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1505 2014, . 1507 [RFC7285] Alimi, R., Ed., Penno, R., Ed., Yang, Y., Ed., Kiesel, S., 1508 Previdi, S., Roome, W., Shalunov, S., and R. Woundy, 1509 "Application-Layer Traffic Optimization (ALTO) Protocol", 1510 RFC 7285, DOI 10.17487/RFC7285, September 2014, 1511 . 1513 [RFC7921] Atlas, A., Halpern, J., Hares, S., Ward, D., and T. 1514 Nadeau, "An Architecture for the Interface to the Routing 1515 System", RFC 7921, DOI 10.17487/RFC7921, June 2016, 1516 . 1518 Authors' Addresses 1520 Wendy Roome 1521 Nokia Bell Labs (Retired) 1522 124 Burlington Rd 1523 Murray Hill, NJ 07974 1524 USA 1526 Phone: +1-908-464-6975 1527 Email: wendy@wdroome.com 1529 Sabine Randriamasy 1530 Nokia Bell Labs 1531 Route de Villejust 1532 NOZAY 91460 1533 FRANCE 1535 Email: Sabine.Randriamasy@nokia-bell-labs.com 1536 Y. Richard Yang 1537 Yale University 1538 51 Prospect Street 1539 New Haven, CT 06511 1540 USA 1542 Phone: +1-203-432-6400 1543 Email: yry@cs.yale.edu 1545 Jingxuan Jensen Zhang 1546 Tongji University 1547 4800 Caoan Road 1548 Shanghai 201804 1549 China 1551 Email: jingxuan.n.zhang@gmail.com