idnits 2.17.1 draft-ietf-alto-unified-props-new-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** 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 603 has weird spacing: '...rtyName prop...' == Line 726 has weird spacing: '...country stat...' -- The document date (July 20, 2017) is 2471 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'ID-draft-yang-alto-path-vector-04' -- Possible downref: Non-RFC (?) normative reference: ref. 'ID-draft-yang-alto-topology-06' Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ALTO WG W. Roome 3 Internet-Draft Nokia Bell Labs 4 Intended status: Standards Track R. Yang 5 Expires: January 21, 2018 Yale University 6 July 20, 2017 8 Extensible Property Maps for the ALTO Protocol 9 draft-ietf-alto-unified-props-new-00 11 Abstract 13 This document extends the Application-Layer Traffic Optimization 14 (ALTO) Protocol [RFC7285] by generalizing the concept of "endpoint 15 properties" to other entity domains, and by presenting those 16 properties as maps, similar to the network and cost maps in ALTO. 18 Requirements Language 20 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 21 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 22 document are to be interpreted as described in RFC 2119 [RFC2119]. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on January 21, 2018. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Definitions and Concepts . . . . . . . . . . . . . . . . . . 4 60 2.1. Entities . . . . . . . . . . . . . . . . . . . . . . . . 4 61 2.2. Domains . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 2.3. Entity Addresses . . . . . . . . . . . . . . . . . . . . 4 63 2.4. Domain Names . . . . . . . . . . . . . . . . . . . . . . 5 64 2.5. Property Names . . . . . . . . . . . . . . . . . . . . . 5 65 2.6. Relationship to Network Maps . . . . . . . . . . . . . . 6 66 3. Entity Domains . . . . . . . . . . . . . . . . . . . . . . . 7 67 3.1. Internet Address Domains . . . . . . . . . . . . . . . . 7 68 3.1.1. IPV4 Domain . . . . . . . . . . . . . . . . . . . . . 7 69 3.1.2. IPV6 Domain . . . . . . . . . . . . . . . . . . . . . 7 70 3.1.3. Heirarchy And Inheritance of ipv4/ipv6 Domains . . . 8 71 3.1.4. Relationship To Network Maps . . . . . . . . . . . . 9 72 3.2. PID Domain . . . . . . . . . . . . . . . . . . . . . . . 9 73 3.2.1. Domain Name . . . . . . . . . . . . . . . . . . . . . 9 74 3.2.2. Domain-Specific Entity Addresses . . . . . . . . . . 9 75 3.2.3. Heirarchy And Inheritance . . . . . . . . . . . . . . 9 76 3.2.4. Relationship To Internet Addresses Domains . . . . . 9 77 3.3. Internet Address Properties vs. PID Properties . . . . . 10 78 3.4. ANE Domain . . . . . . . . . . . . . . . . . . . . . . . 10 79 3.4.1. Domain Name . . . . . . . . . . . . . . . . . . . . . 10 80 3.4.2. Domain-Specific Entity Addresses . . . . . . . . . . 10 81 3.4.3. Heirarchy And Inheritance . . . . . . . . . . . . . . 10 82 4. Property Map Resource . . . . . . . . . . . . . . . . . . . . 10 83 4.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 11 84 4.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 11 85 4.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 11 86 4.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . 11 87 4.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 11 88 4.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 12 89 5. Filtered Property Map Resource . . . . . . . . . . . . . . . 13 90 5.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 13 91 5.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 13 92 5.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 13 93 5.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . 14 94 5.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 14 95 5.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 14 96 6. Impact On Legacy Servers And Clients . . . . . . . . . . . . 14 97 6.1. Impact on Endpoint Property Service . . . . . . . . . . . 14 98 6.2. Impact on Resource-Specific Properties . . . . . . . . . 14 99 6.3. Impact on the "pid" Property . . . . . . . . . . . . . . 15 100 6.4. Impact on Other Properties . . . . . . . . . . . . . . . 15 101 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 15 102 7.1. Network Map . . . . . . . . . . . . . . . . . . . . . . . 15 103 7.2. Property Definitions . . . . . . . . . . . . . . . . . . 16 104 7.3. Information Resource Directory (IRD) . . . . . . . . . . 16 105 7.4. Property Map Example . . . . . . . . . . . . . . . . . . 18 106 7.5. Filtered Property Map Example #1 . . . . . . . . . . . . 18 107 7.6. Filtered Property Map Example #2 . . . . . . . . . . . . 19 108 7.7. Filtered Property Map Example #3 . . . . . . . . . . . . 20 109 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 110 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 111 9.1. application/alto-* Media Types . . . . . . . . . . . . . 22 112 9.2. ALTO Entity Domain Registry . . . . . . . . . . . . . . . 23 113 9.3. ALTO Endpoint Property Type Registry . . . . . . . . . . 24 114 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 117 1. Introduction 119 The ALTO protocol [RFC7285] introduced the concept of "properties" 120 attached to "endpoint addresses," and defined the Endpoint Property 121 Service (EPS) to allow clients to retrieve those properties. While 122 useful, the EPS, as defined in RFC7285, has at least two limitations. 124 First, it only allows properties to be associated with a particular 125 domain of entities, namely individual IP addresses. It is reasonable 126 to think that collections of endpoints, as defined by CIDRs or PIDs, 127 may also have properties. Furthermore, recent proposals 128 ([ID-draft-yang-alto-path-vector-04] and 129 [ID-draft-yang-alto-topology-06]) have suggested new classes of 130 entities with properties. The EPS cannot be extended to new entity 131 domains. Instead, new services, with new request and response 132 messages, would have to be defined for each new entity domain. 134 Second, the EPS is only defined as a POST-mode service. Clients must 135 request the properties for an explicit set of addresses. By 136 contrast, [RFC7285] defines a GET-mode Cost Map resource which 137 returns all available costs, so a client can get the full set of 138 costs once, and then lookup costs without querying the ALTO server. 139 RFC7285 does not define an equivalent service for endpoint 140 properties. Granted, it is not be practical to enumerate the 141 properties for every possible Internet address. But it is unlikely a 142 property will be defined for every possible address. It is very 143 likely that properties will only be defined for a subset of 144 addresses, and that subset would be small enough to enumerate. This 145 is particularly true if blocks of addresses with a common prefix 146 (e.g., a CIDR) have the same value for a property. Furthermore, 147 entities in other domains may very well be enumerable. 149 This document proposes a new approach to ALTO properties. 150 Specifically, it defines two new resource types, namely Property Maps 151 (see Section 4) and Filtered Property Maps (see Section 5). The 152 former are GET-mode resources which return the property values for 153 all entities in a domain, and are analogous the ALTO's Network Map 154 and Cost Map resources. The latter are POST-mode resources which 155 return the values for a set of properties and entities requested by 156 the client, and are analogous to ALTO's Filtered Network Maps and 157 Filtered Cost Maps. 159 Entity domains and property names are extensible, so that new domains 160 can be defined without revising the messages defined in this 161 document, in the same way that new cost metrics and new endpoint 162 properties can be defined without revising the messages defined by 163 the ALTO protocol. 165 This proposal would subsume the Endpoint Property Service defined in 166 RFC7285, although that service may be retained for legacy clients 167 (see Section 6). 169 2. Definitions and Concepts 171 2.1. Entities 173 An entity is an object with a (possibly empty) set of properties. 174 Every entity is in a domain, such as the IPv4 and IPv6 domains, and 175 has a unique address. 177 2.2. Domains 179 A domain is a family of entities. Two examples are the Internet 180 address and PID domains (see Section 3.1 and Section 3.2) that this 181 document will define. An additinoal example is the proposed domain 182 of Abstract Network Elements associated with topology and routing, as 183 suggested by [ID-draft-yang-alto-path-vector-04]. 185 2.3. Entity Addresses 187 Each entity has a unique address of the format: 189 domain-name : domain-specific-entity-address 191 Examples from the IP domain include individual addresses such as 192 "ipv4:192.0.2.14" and "ipv6:2001:db8::12", as well as address blocks 193 such as "ipv4:192.0.2.0/26" and "ipv6:2001:db8:1/48". 195 The type EntityAddr denotes a JSON string with an entity address in 196 this format. 198 The format of the second part of an entity address depends on the 199 domain, and must be specified when registering a new domain. 200 Addresses may be hierarchical, and properties may be inherited based 201 on that hierarchy. Again, the rules defining any hierarchy or 202 inheritance must be defined when the domain is registered. 204 Note that entity addresses may NOT have a unique textual 205 representation, for a given domain. For example, the strings 206 "ipv6:2001:db8::1" and "ipv6:2001:db8:0:0:0:0:0:1" refer to the same 207 entity. 209 2.4. Domain Names 211 Each domain has a unique name. A domain name MUST be no more than 32 212 characters, and MUST NOT contain characters other than US-ASCII 213 alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and 214 U+0061-U+007A), hyphen ('-', U+002D), and low line ('_', U+005F). 215 For example, the names "ipv4" and "ipv6" identify objects in the 216 Internet address domain (Section 3.1). 218 The type DomainName denotes a JSON string with a domain name in this 219 format. 221 Domain names must be registered with the IANA, and the format of the 222 entity addresses in that domain, as well as any hierarchical or 223 inheritance rules for those entities, MUST be specified at the same 224 time. 226 2.5. Property Names 228 The space of property names associated with entities defined by this 229 document is the same as, and is shared with, the endpoint property 230 names defined by [RFC7285]. Thus entity property names are as 231 defined in Section 10.8.2 of that document, and must be registered 232 with the "ALTO Endpoint Property Type Registry" defined in 233 Section 14.3 of that document. 235 The type PropertyName denotes a JSON string with a property name in 236 this format. 238 This document defines uniform property names specified in a single 239 property name sapce rather than being scoped by a specific domain, 240 although some properties may only be applicable for particular 241 domains. This design decision is to enforce a design so that similar 242 properties are named similarly. The interpretation of the value of a 243 property, howerver, may depend on the domain. For example, suppose 244 the "geo-location" property is defined as the coordinates of a point, 245 encoded as (say) "latitude longitude [altitude]." When applied to an 246 entity that represents a specific host computer, such as an Internet 247 address, the property defines the host's location. When applied to 248 an entity that represents a set of computers, such as a CIDR, the 249 property would be the location of the center of that set. If it is 250 necessary to represent the bounding box of a set of hosts, another 251 property, such as "geo-region", should be defined. 253 2.6. Relationship to Network Maps 255 [RFC7285] recognizes that some properties may be specific to an ALTO 256 resource, such as a network map. Accordingly [RFC7285] defines the 257 concept of "resource-specific endpoint properties" (Section 10.8.1), 258 and indicates that dependency by prefixing the property name with the 259 ID of the resource on which it depends. That document defines one 260 resource-specific property, namely the "pid" property, whose value is 261 the name of the PID containing that endpoint in the associated 262 network map. 264 This document takes a different approach. Instead of defining the 265 dependency by qualifying the property name, this document attaches 266 the dependency to the property map as a whole. Thus all properties 267 in a given property map depend on the same resource. Furthermore, 268 entity addresses may depend on a network map (for example, the 269 Abstract Network Elements suggested by 270 [ID-draft-yang-alto-path-vector-04]). Associating the dependency 271 with the property map handles any entity address dependencies as 272 well. 274 The "uses" field in an IRD entry defines the dependencies of a 275 property map resource, and the "dependent-vtags" field in a property 276 map response defines the dependencies of that map. These fields are 277 defined in Sections 9.1.5 and 11.1 of [RFC7285], respectively. 279 This is similar to how RFC7285 handles dependencies between cost maps 280 and network maps. Recall that cost maps present the costs between 281 PIDs, and PID names depend on a network map. If an ALTO server 282 provides the "routingcost" metric for the network maps "net1" and 283 "net2", then the server defines two separate cost maps, one for 284 "net1" and the other for "net2". 286 According to [RFC7285], an ALTO server with two network maps, with 287 resource IDs "net1" and "net2", could offer a single Endpoint 288 Property Service for the two properties "net1.pid" and "net2.pid". 289 An ALTO server which supports the extensions defined in this 290 document, would, instead, offer two different property maps for the 291 "pid" property, one depending on "net1", the other on "net2". 293 3. Entity Domains 295 This document defines the following entity domains. For the 296 definition of each domain, it includes the following template: domain 297 name, domain-specific addresses, and heirarchy and inheritance 298 semantics. 300 3.1. Internet Address Domains 302 The document defines two domains (IPv4 and IPv6) for Internet 303 addresses. Both domains include individual addresses and blocks of 304 addresses. 306 3.1.1. IPV4 Domain 308 3.1.1.1. Domain Name 310 ipv4 312 3.1.1.2. Domain-Specific Entity Addresses 314 Individual addresses are strings as specified by the IPv4Addresses 315 rule of Section 3.2.2 of [RFC3986]. Blocks of addresses are prefix- 316 match strings as specified in Section 3.1 of [RFC4632]. 318 For the purpose of defining properties, an individual Internet 319 address and the corresponding full-length prefix are considered 320 aliases for the same entity. Thus "ipv4:192.0.2.0" and 321 "ipv4:192.0.2.0/32" are equivalent. 323 3.1.2. IPV6 Domain 325 3.1.2.1. Domain Name 327 ipv6 329 3.1.2.2. Domain-Specific Entity Addresses 331 Individual addresses are strings as specified by Section 4 of 332 [RFC5952]. Blocks of addresses are prefix-match strings as specified 333 in Section 7 of [RFC5952]. 335 For the purpose of defining properties, an individual Internet 336 address and the corresponding 128-bit prefix are considered aliases 337 for the same entity. That is, "ipv6:2001:db8::1" and 338 "ipv6:2001:db8::1/128" are equivalent, and have the same set of 339 properties. 341 3.1.3. Heirarchy And Inheritance of ipv4/ipv6 Domains 343 Both domains allow property values to be inherited. Specifically, if 344 a property P is not defined for a specific Internet address IP, but P 345 is defined for some block C which prefix-matches IP, then the address 346 IP inherits the value of P defined for block C. If more than one 347 such block defines a value for P, IP inherits the value of P in the 348 block with the longest prefix. It is important to notice that this 349 longest prefix rule will ensure no multiple inheritance, and hence no 350 ambiguity. 352 Address blocks can also inherit properties: if property P is not 353 defined for a block C, but is defined for some block C' prefix- 354 matches C, and C' has a shorter mask than C, then block C inherits 355 the property from C'. If there are several such blocks C', C 356 inherits from the block with the longest prefix. 358 As an example, suppose that a server defines the property P for the 359 following entities: 361 ipv4:192.0.2.0/26: P=v1 362 ipv4:192.0.2.0/28: P=v2 363 ipv4:192.0.2.0/30: P=v3 364 ipv4:192.0.2.0: P=v4 366 Defined Property Values 368 Then the following entities have the indicated values: 370 ipv4:192.0.2.0: P=v4 371 ipv4:192.0.2.1: P=v3 372 ipv4:192.0.2.16: P=v1 373 ipv4:192.0.2.32: P=v1 374 ipv4:192.0.2.64: (not defined) 375 ipv4:192.0.2.0/32: P=v4 376 ipv4:192.0.2.0/31: P=v3 377 ipv4:192.0.2.0/29: P=v2 378 ipv4:192.0.2.0/27: P=v1 379 ipv4:192.0.2.0/25: (not defined) 381 Inherited Property Values 383 3.1.4. Relationship To Network Maps 385 An Internet address domain may or may not be associated with an ALTO 386 network map resource. Logically, there is a map of Internet address 387 entities to property values for each network map defined by the ALTO 388 server, plus an additional property map for Internet address entities 389 which are not associated with a network map. So, if there is n 390 network maps, the server can provide n+1 maps of Internet address 391 entities to property values.So, if there is n network maps, the 392 server may provide n+1 maps of Internet address entities to property 393 values. These maps are separate from each other. The prefixes in 394 the property map do not have to correspond to the prefixes defining 395 the network map's PIDs. For example, the property map for a network 396 map may assign properties to "ipv4:192.0.2.0/24" even if that prefix 397 is not associated with any PID in the network map. 399 3.2. PID Domain 401 The PID domain associates property values with the PIDs in a network 402 map. Accordingly, this domain always depends on a network map. 404 3.2.1. Domain Name 406 pid 408 3.2.2. Domain-Specific Entity Addresses 410 The entity addresses are the PID names of the associated network map. 412 3.2.3. Heirarchy And Inheritance 414 There is no hierarchy or inheritance for properties associated with 415 PIDs. 417 3.2.4. Relationship To Internet Addresses Domains 419 The PID domain and the Internet address domains are completely 420 independent; the properties associated with a PID have no relation to 421 the properties associated with the prefixes or endpoint addresses in 422 that PID. An ALTO server MAY choose to assign some or all properties 423 of a PID to the prefixes in that PID, but is not required to do so. 425 For example, suppose "PID1" consists of the prefix 426 "ipv4:192.0.2.0/24", and has the property "P" with value "v1". The 427 Internet address entities "ipv4:192.0.2.0" and "ipv4:192.0.2.0/24", 428 in the IPv4 domain may or may not have a value for the property "P", 429 and if they do, it is not necessarily "v1". 431 3.3. Internet Address Properties vs. PID Properties 433 Because the Internet address and PID domains are completely separate, 434 the question may arise as to which domain is best for a property. In 435 general, the Internet address domain is best for properties that are 436 closely related to the Internet address, or are associated with, and 437 inherited through, blocks of addresses. 439 The PID domain is best for properties that arise from the definition 440 of the PID, rather than from the Internet address prefixes in that 441 PID. 443 For example, because Internet addresses are allocated to service 444 providers by blocks of prefixes, an "ISP" property would be best 445 associated with the Internet address domain. On the other hand, a 446 property that explains why a PID was formed, or how it relates the a 447 provider's network, would best be associated with the PID domain. 449 3.4. ANE Domain 451 3.4.1. Domain Name 453 ane 455 3.4.2. Domain-Specific Entity Addresses 457 The entity address of ane domain is encoded as a JSON string. The 458 string MUST be no more than 64 characters, and it MUST NOT contain 459 characters other than US-ASCII alphanumeric characters 460 (U+0030-U+0039, U+0041-U+005A, and U+0061-U+007A), the hyphen ('-', 461 U+002D), the colon (':', U+003A), the at sign ('@', code point 462 U+0040), the low line ('_', U+005F), or the '.' separator (U+002E). 463 The '.' separator is reserved for future use and MUST NOT be used 464 unless specifically indicated in this document, or an extension 465 document. 467 3.4.3. Heirarchy And Inheritance 469 There is no hierarchy or inheritance for properties associated with 470 ANEs. 472 4. Property Map Resource 474 A Property Map returns the properties defined for all entities in one 475 or more domains. 477 Section 7.4 gives an example of a property map request and its 478 response. 480 4.1. Media Type 482 The media type of an ALTO Property Map resource is "application/alto- 483 propmap+json". 485 4.2. HTTP Method 487 An ALTO Property Map resource is requested using the HTTP GET method. 489 4.3. Accept Input Parameters 491 None. 493 4.4. Capabilities 495 The capabilities are defined by an object of type 496 PropertyMapCapabilities: 498 object { 499 DomainName domain-types<1..*>; 500 PropertyName prop-types<1..*>; 501 } PropertyMapCapabilities; 503 where "domain-types" is an array with the domains of the entities in 504 this property map, and "prop-types" is an array with the names of the 505 properties returned for entities in those domains. TODO: discuss 506 semantics and requirements of multiple domains. 508 If the server declares multiple domain-types and multiple prop-types 509 in the capability, each prop-type MUST be supported in each domain in 510 the "capabilities" field. In other words, if a prop-type is NOT 511 supported in a particular domain, the property map MUST be divided 512 into several maps. 514 4.5. Uses 516 An array with the resource ID(s) of resource(s) with which the 517 domains in this map are associated. In most cases, this array will 518 have at most one ID, for example, for a network map resource. TODO: 519 discuss semantics and requirements of multiple resources. However, 520 the "uses" field MUST NOT contain two resources of the same resource 521 type. For example, if a property map depends on network map 522 resource, the "uses" field MUST include exactly one network map 523 resource. 525 4.6. Response 527 If the domains in this property map depend on other resources, the 528 "dependent-vtags" field in the "meta" field of the response MUST be 529 an array that includes the version tags of those resources. 531 The data component of a Property Map response is named "property- 532 map", which is a JSON object of type PropertyMapData, where: 534 object { 535 PropertyMapData property-map; 536 } InfoResourceProperties : ResponseEntityBase; 538 object-map { 539 EntityAddr -> EntityProps; 540 } PropertyMapData; 542 object { 543 PropertyName -> JSONValue; 544 } EntityProps; 546 The ResponseEntityBase type is defined in Section 8.4 of [RFC7285]. 548 Specifically, a PropertyMapData object has one member for each entity 549 in the Property Map. The entity's properties are encoded in the 550 corresponding EntityProps object. EntityProps encodes one name/value 551 pair for each property, where the property names are encoded as 552 strings of type PropertyName. A protocol implementation SHOULD 553 assume that the property value is either a JSONString or a JSON 554 "null" value, and fail to parse if it is not, unless the 555 implementation is using an extension to this document that indicates 556 when and how property values of other data types are signaled. 558 For each entity in the Property Map, the ALTO Server returns the 559 value defined for each of the properties specified in this resource's 560 "capabilities" list. For efficiency, the ALTO Server SHOULD omit 561 property values that are inherited rather than explicitly defined; if 562 a client needs inherited values, the client SHOULD use the domain's 563 inheritance rules to deduce those values. 565 An ALTO Server MAY explicitly define a property as not having a value 566 for a particular entity. That is, a server may say that a property 567 is "defined to have no value", as opposed to the property being 568 "undefined". If the property for an entity is defined to have no 569 value, the server MUST set the property value to be a JSON null 570 value. 572 If the ALTO Server does not define any properties for an entity, then 573 the server MAY omit that entity from the response. 575 5. Filtered Property Map Resource 577 A Filtered Property Map returns the values of a set of properties for 578 a set of entities selected by the client. 580 Section 7.5, Section 7.6 and Section 7.7 give examples of filtered 581 property map requests and responses. 583 5.1. Media Type 585 The media type of an ALTO Property Map resource is "application/alto- 586 propmap+json". 588 5.2. HTTP Method 590 An ALTO Property Map resource is requested using the HTTP POST 591 method. 593 5.3. Accept Input Parameters 595 The input parameters for a Filtered Property Map request are supplied 596 in the entity body of the POST request. This document specifies the 597 input parameters with a data format indicated by the media type 598 "application/alto-propmapparams+json", which is a JSON object of type 599 ReqFilteredPropertyMap: 601 object { 602 EntityAddr entities<1..*>; 603 PropertyName properties<1..*>; 604 } ReqFilteredPropertyMap; 606 with fields: 608 entities: List of entity addresses for which the specified 609 properties are to be returned. The ALTO server MUST interpret 610 entries appearing multiple times as if they appeared only once. 611 The domain of each entity MUST be included in the list of domains 612 in this resource's "capabilities" field (Section 5.4). 614 properties: List of properties to be returned for each entity. Each 615 specified property MUST be included in the list of properties in 616 this resource's "capabilities" field (Section 5.4). The ALTO 617 server MUST interpret entries appearing multiple times as if they 618 appeared only once. 620 Note that the "entities" and "properties" fields MUST have at 621 least one entry each. 623 5.4. Capabilities 625 The capabilities are defined by an object of type 626 PropertyMapCapabilities, as defined in Section 4.4. 628 5.5. Uses 630 An array with the resource ID(s) of resource(s) with which the 631 domains in this map are associated. In most cases, this array will 632 have at most one ID, and it will be for a network map resource. 634 5.6. Response 636 The response is the same as for the property map (Section 4.6), 637 except that it only includes the entities and properties requested by 638 the client. 640 Also, the Filtered Property Map response MUST include all inherited 641 property values for the specified entities (unlike the Full Property 642 Map, the Filtered Property Map response does not include enough 643 information for the client to calculate the inherited values). 645 6. Impact On Legacy Servers And Clients 647 6.1. Impact on Endpoint Property Service 649 The property maps defined in this document provide the same 650 functionality as the Endpoint Property Service (EPS) defined in 651 Section 11.4 of [RFC7285]. Accordingly, it is RECOMMENDED that the 652 EPS be deprecated in favor of property maps. However, ALTO servers 653 MAY provide an EPS for the benefit of legacy clients. 655 6.2. Impact on Resource-Specific Properties 657 Section 10.8 of [RFC7285] defines two categories of endpoint 658 properties: "resource-specific" and "global". Resource-specific 659 property names are prefixed with the ID of the resource they depended 660 upon, while global property names have no such prefix. The property 661 map resources defined in this document do not distinguish between 662 those two types of properties. Instead, if there is a dependency, it 663 is indicated by the "uses" capability of a property map, and is 664 shared by all properties and entity domains in that map. 665 Accordingly, it is RECOMMENDED that resource-specific endpoint 666 properties be deprecated, and no new resource-specific endpoint 667 properties be defined. 669 6.3. Impact on the "pid" Property 671 Section 7.1.1 of [RFC7285] defines the resource-specific endpoint 672 property "pid", whose value is the name of the PID containing that 673 endpoint. For compatibility with legacy clients, an ALTO server 674 which provides the "pid" property via the Endpoint Property Service 675 MUST use that definition, and that syntax, in the EPS resource. 677 However, when used with property maps, this document amends the 678 definition of the "pid" property as follows. 680 First, the name of the property is simply "pid"; the name is not 681 prefixed with the resource ID of a network map. The "uses" 682 capability of the property map resource indicates the associated 683 network map. This implies that a property map can only return the 684 "pid" property for one network map; if an ALTO server provides 685 several network maps, it must provide a property map resource for 686 each one. 688 Second, a client MAY request the "pid" property for a block of 689 addresses. An ALTO server determines the value of "pid" for an 690 address block C as follows. Let CS be the set of all address blocks 691 in the network map. If C is in CS, then the value of "pid" is the 692 name of the PID associated with C. Otherwise, find the longest block 693 C' in CS such that C' prefix-matches C, but is shorter than C. If 694 there is such a block C', the value of "pid" is the name of the PID 695 associated with C'. If not, then "pid" has no value for block C. 697 Note that although an ALTO server MAY provide a GET-mode property map 698 resource which returns the entire map for the "pid" property, there 699 is no need to do so, because that map is simply the inverse of the 700 network map. 702 6.4. Impact on Other Properties 704 In general, there should be little or no impact on other previously 705 defined properties. The only consideration is that properties can 706 now be defined on blocks of addresses, rather than just individual 707 addresses, which might change the semantics of a property. 709 7. Examples 711 7.1. Network Map 713 The examples in this section use a very simple default network map: 715 defaultpid: ipv4:0.0.0.0/0 ipv6:::0/0 716 pid1: ipv4:192.0.2.0/25 717 pid2: ipv4:192.0.2.0/28 ipv4:192.0.2.16/28 719 Figure 1: Example Network Map 721 7.2. Property Definitions 723 The examples in this section use four additional properties, "ISP", 724 "ASN", "country" and "state", with the following values: 726 ISP ASN country state 727 ipv4:192.0.2.0/24: BitsRus - us - 728 ipv4:192.0.2.0/28: - 12345 - NJ 729 ipv4:192.0.2.16/28: - 12345 - CT 730 ipv4:192.0.2.0: - - - PA 732 Figure 2: Example Property Values 734 7.3. Information Resource Directory (IRD) 736 The following IRD defines the relevant resources of the ALTO server. 737 It provides two Property Map resources, one for the "ISP" and "ASN" 738 properties, and another for the "country" and "state" properties. 739 The server could have provided a Property Map resource for all four 740 properties, but did not, presumably because the organization that 741 runs the ALTO server believes any given client is not interested in 742 all four properties. 744 The server provides two Filtered Property Maps. The first returns 745 all four properties, and the second just returns the "pid" property 746 for the default network map. 748 The Property Maps for the "ISP", "ASN", "country" and "state" 749 properties do not depend on the default network map (they do not have 750 a "uses" capability), because the definitions of those properties do 751 not depend on the default network map. The Filtered Property Map for 752 the "pid" property does have a "uses" capability for the default 753 network map, because that defines the values of the "pid" property. 755 Note that for legacy clients, the ALTO server provides an Endpoint 756 Property Service for the "pid" property for the default network map. 758 "meta": { ... }, 759 "resources" : { 760 "default-network-map" : { 761 "uri" : "http://alto.example.com/networkmap", 762 "media-type" : "application/alto-networkmap+json" 764 }, 765 .... property map resources .... 766 "country-state-property-map" : { 767 "uri" : "http://alto.example.com/propmap/full/inet-cs", 768 "media-type" : "application/alto-propmap+json", 769 "capabilities" : { 770 "domain-types": [ "ipv4", "ipv6" ], 771 "prop-types" : [ "country", "state" ] 772 } 773 }, 774 "isp-asn-property-map" : { 775 "uri" : "http://alto.example.com/propmap/full/inet-ia", 776 "media-type" : "application/alto-propmap+json", 777 "capabilities" : { 778 "domain-types": [ "ipv4", "ipv6" ], 779 "prop-types" : [ "ISP", "ASN" ] 780 } 781 }, 782 "iacs-property-map" : { 783 "uri" : "http://alto.example.com/propmap/lookup/inet-iacs", 784 "media-type" : "application/alto-propmap+json", 785 "accepts" : "application/alto-propmapparams+json", 786 "capabilities" : { 787 "domain-types": [ "ipv4", "ipv6" ], 788 "prop-types" : [ "ISP", "ASN", "country", "state" ] 789 } 790 }, 791 "pid-property-map" : { 792 "uri" : "http://alto.example.com/propmap/lookup/pid", 793 "media-type" : "application/alto-propmap+json", 794 "accepts" : "application/alto-propmapparams+json", 795 "uses" : [ "default-network-map" ] 796 "capabilities" : { 797 "domain-types": [ "ipv4", "ipv6" ], 798 "prop-types" : [ "pid" ] 799 } 800 }, 801 "legacy-pid-property" : { 802 "uri" : "http://alto.example.com/legacy/eps-pid", 803 "media-type" : "application/alto-endpointprop+json", 804 "accepts" : "application/alto-endpointpropparams+json", 805 "capabilities" : { 806 "prop-types" : [ "default-network-map.pid" ] 807 } 808 } 809 } 810 Example IRD 812 7.4. Property Map Example 814 The following example uses the properties and IRD defined above to 815 retrieve a property map for entities with the "ISP" and "ASN" 816 properties. Note that the response does not include the entity 817 "ipv4:192.0.2.0", because it does not have a value for either of 818 those properties. Also note that the entities "ipv4:192.0.2.0/28" 819 and "ipv4:192.0.2.16/28" are refinements of "ipv4:192.0.2.0/24", and 820 hence inherit its value for "ISP" property. But because that value 821 is inherited, it is not explicitly listed in the property map. 823 GET /propmap/full/inet-ia HTTP/1.1 824 Host: alto.example.com 825 Accept: application/alto-propmap+json,application/alto-error+json 827 HTTP/1.1 200 OK 828 Content-Length: ### 829 Content-Type: application/alto-propmap+json 830 { 831 "property-map": { 832 "ipv4:192.0.2.0/24": {"ISP: "BitsRus"}, 833 "ipv4:192.0.2.0/28": {"ASN": "12345"}, 834 "ipv4:192.0.2.16/28": {"ASN": "12345"} 835 } 836 } 838 7.5. Filtered Property Map Example #1 840 The following example uses the Filtered Property Map resource to 841 request the "ISP", "ASN" and "state" properties for several IPv4 842 addresses. Note that the value of "state" for "ipv4:192.0.2.0" is 843 the only explicitly defined property; the other values are all 844 derived by the inheritance rules for Internet address entities. 846 POST /propmap/lookup/inet-iacs HTTP/1.1 847 Host: alto.example.com 848 Accept: application/alto-propmap+json,application/alto-error+json 849 Content-Length: ### 850 Content-Type: application/alto-propmapparams+json 852 { 853 "entities" : [ "ipv4:192.0.2.0", 854 "ipv4:192.0.2.1", 855 "ipv4:192.0.2.17" ], 856 "properties" : [ "ISP", "ASN", "state" ] 857 } 859 HTTP/1.1 200 OK 860 Content-Length: ### 861 Content-Type: application/alto-propmap+json 862 { 863 "property-map": { 864 "ipv4:192.0.2.0": 865 {"ISP": "BitsRus", "ASN": "12345", "state": "PA"}, 866 "ipv4:192.0.2.1": 867 {"ISP": "BitsRus", "ASN": "12345", "state": "NJ"}, 868 "ipv4:192.0.2.17": 869 {"ISP": "BitsRus", "ASN": "12345", "state": "CT"} 870 } 871 } 873 7.6. Filtered Property Map Example #2 875 The following example uses the Filtered Property Map resource to 876 request the "ASN", "country" and "state" properties for several IPv4 877 prefixes. Note that none of the returned property values were 878 explicitly defined; all values are derived by the inheritance rules 879 for Internet address entities. 881 Also note the "ASN" property has the value "12345" for both the 882 blocks "ipv4:192.0.2.0/28" and "ipv4:192.0.2.16/28", so every address 883 in the block "ipv4:192.0.2.0/27" has that property value. However 884 the block "ipv4:192.0.2.0/27" itself does not have a value for "ASN": 885 address blocks cannot inherit properties from blocks with longer 886 prefixes, even if every such block has the same value. 888 POST /propmap/lookup/inet-iacs HTTP/1.1 889 Host: alto.example.com 890 Accept: application/alto-propmap+json,application/alto-error+json 891 Content-Length: ### 892 Content-Type: application/alto-propmapparams+json 894 { 895 "entities" : [ "ipv4:192.0.2.0/26", 896 "ipv4:192.0.2.0/27", 897 "ipv4:192.0.2.0/28" ], 898 "properties" : [ "ASN", "country", "state" ] 899 } 901 HTTP/1.1 200 OK 902 Content-Length: ### 903 Content-Type: application/alto-propmap+json 904 { 905 "property-map": { 906 "ipv4:192.0.2.0/26": {"country": "us"}, 907 "ipv4:192.0.2.0/27": {"country": "us"}, 908 "ipv4:192.0.2.0/28": {"ASN": "12345", 909 "country": "us", 910 "state": "NJ"} 911 } 912 } 914 7.7. Filtered Property Map Example #3 916 The following example uses the Filtered Property Map resource to 917 request the "pid" property for several IPv4 addresses and prefixes. 919 Note that the value of "pid" for the prefix "ipv4:192.0.2.0/26" is 920 "pid1", even though all addresses in that block are in "pid2", 921 because "ipv4:192.0.2.0/8" is the longest prefix in the network map 922 which prefix-matches "ipv4:192.0.2.0/26", and that prefix is in 923 "pid1". 925 POST /propmap/lookup/pid HTTP/1.1 926 Host: alto.example.com 927 Accept: application/alto-propmap+json,application/alto-error+json 928 Content-Length: ### 929 Content-Type: application/alto-propmapparams+json 931 { 932 "entities" : [ 933 "ipv4:192.0.2.0", 934 "ipv4:192.0.2.16", 935 "ipv4:192.0.2.64", 936 "ipv4:192.0.2.128", 937 "ipv4:192.0.2.0/26", 938 "ipv4:192.0.2.0/30" ], 939 "properties" : [ "pid" ] 940 } 942 HTTP/1.1 200 OK 943 Content-Length: ### 944 Content-Type: application/alto-propmap+json 945 { 946 "meta" : { 947 "dependent-vtags" : [ 948 {"resource-id": "default-network-map", 949 "tag": "7915dc0290c2705481c491a2b4ffbec482b3cf62"} 950 ] 951 }, 952 "property-map": { 953 "ipv4:192.0.2.0": {"pid": "pid2"}, 954 "ipv4:192.0.2.16": {"pid": "pid2"}, 955 "ipv4:192.0.2.64": {"pid": "pid1"}, 956 "ipv4:192.0.2.128": {"pid": "defaultpid"}, 957 "ipv4:192.0.2.0/26": {"pid": "pid1"}, 958 "ipv4:192.0.2.0/30": {"pid": "pid2"} 959 } 960 } 962 8. Security Considerations 964 As discussed in Section 15 of [RFC7285], properties may have 965 sensitive customer-specific information. If this is the case, an 966 ALTO Server may limit access to those properties by providing several 967 different property maps. For non-sensitive properties, the ALTO 968 Server would provide a URI which accepts requests from any client. 969 Sensitive properties, on the other hand, would only be available via 970 a secure URI which would require client authentication. 972 Also, while technically this document does not introduce any security 973 risks not inherent in the Endpoint Property Service defined by 974 [RFC7285], the GET-mode property map resource defined in this 975 document does make it easier for a client to download large numbers 976 of property values. Accordingly, an ALTO Server should limit GET- 977 mode property maps for to properties which do not contain sensitive 978 data. 980 9. IANA Considerations 982 This document defines additional application/alto-* media types, and 983 extends the ALTO endpoint property registry. 985 9.1. application/alto-* Media Types 987 This document registers two additional ALTO media types, listed in 988 Table 1. 990 +-------------+-------------------------+---------------+ 991 | Type | Subtype | Specification | 992 +-------------+-------------------------+---------------+ 993 | application | alto-propmap+json | Section 4.1 | 994 | application | alto-propmapparams+json | Section 5.3 | 995 +-------------+-------------------------+---------------+ 997 Table 1: Additional ALTO Media Types 999 Type name: application 1001 Subtype name: This document registers multiple subtypes, as listed 1002 in Table 1. 1004 Required parameters: n/a 1006 Optional parameters: n/a 1008 Encoding considerations: Encoding considerations are identical to 1009 those specified for the "application/json" media type. See 1010 [RFC7159]. 1012 Security considerations: Security considerations relating to the 1013 generation and consumption of ALTO Protocol messages are discussed 1014 in Section 15 of [RFC7285]. 1016 Interoperability considerations: This document specifies format of 1017 conforming messages and the interpretation thereof. 1019 Published specification: This document is the specification for 1020 these media types; see Table 1 for the section documenting each 1021 media type. 1023 Applications that use this media type: ALTO servers and ALTO clients 1024 either stand alone or are embedded within other applications. 1026 Additional information: 1028 Magic number(s): n/a 1030 File extension(s): This document uses the mime type to refer to 1031 protocol messages and thus does not require a file extension. 1033 Macintosh file type code(s): n/a 1035 Person & email address to contact for further information: See 1036 Authors' Addresses section. 1038 Intended usage: COMMON 1040 Restrictions on usage: n/a 1042 Author: See Authors' Addresses section. 1044 Change controller: Internet Engineering Task Force 1045 (mailto:iesg@ietf.org). 1047 9.2. ALTO Entity Domain Registry 1049 This document requests IANA to create and maintain the "ALTO Entity 1050 Domain Registry", listed in Table 2. 1052 +------------+-------------------------+-------------------------+ 1053 | Identifier | Entity Address Encoding | Hierarchy & Inheritance | 1054 +------------+-------------------------+-------------------------+ 1055 | ipv4 | See Section 3.1.1 | See Section 3.1.3 | 1056 | ipv6 | See Section 3.1.2 | See Section 3.1.3 | 1057 | pid | See Section 3.2 | None | 1058 +------------+-------------------------+-------------------------+ 1060 Table 2: ALTO Entity Domain Names 1062 This registry serves two purposes. First, it ensures uniqueness of 1063 identifiers referring to ALTO entity domains. Second, it states the 1064 requirements for allocated domain names. 1066 New ALTO entity domains are assigned after IETF Review [RFC5226] to 1067 ensure that proper documentation regarding the new ALTO entity 1068 domains and their security considerations has been provided. RFCs 1069 defining new entity domains should indicate how an entity in a 1070 registered domain is encoded as an EntityName, and, if applicable, 1071 the rules defining the entity hierarchy and property inheritance. 1072 Updates and deletions of ALTO entity domains follow the same 1073 procedure. 1075 Registered ALTO entity domain identifiers MUST conform to the 1076 syntactical requirements specified in Section 2.4. Identifiers are 1077 to be recorded and displayed as strings. 1079 Requests to add a new value to the registry MUST include the 1080 following information: 1082 o Identifier: The name of the desired ALTO entity domain. 1084 o Entity Address Encoding: The procedure for encoding the address of 1085 an entity of the registered type as an EntityAddr (see 1086 Section 2.3). 1088 o Hierarchy: If the entities form a hierarchy, the procedure for 1089 determining that hierarchy. 1091 o Inheritance: If entities can inherit property values from other 1092 entities, the procedure for determining that inheritance. 1094 o Security Considerations: In some usage scenarios, entity addresses 1095 carried in ALTO Protocol messages may reveal information about an 1096 ALTO client or an ALTO service provider. Applications and ALTO 1097 service providers using addresses of the registered type should be 1098 made aware of how (or if) the addressing scheme relates to private 1099 information and network proximity. 1101 This specification requests registration of the identifiers "ipv4", 1102 "ipv6" and "pid", as shown in Table 2. 1104 9.3. ALTO Endpoint Property Type Registry 1106 The ALTO Endpoint Property Type Registry was created by [RFC7285]. 1107 If possible, the name of that registry should be changed to "ALTO 1108 Entity Property Type Registry", to indicate that it is not restricted 1109 to Endpoint Properties. If it is not feasible to change the name, 1110 the description must be amended to indicate that it registers 1111 properties in all domains, rather than just the Internet address 1112 domain. 1114 10. References 1116 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1117 Requirement Levels", RFC 2119, BCP 14, March 1997. 1119 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1120 Resource Identifier (URI): Generic Syntax", RFC 3986, 1121 January 2005. 1123 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 1124 (CIDR): The Internet Address Assignment and Aggregation 1125 Plan", RFC 4632, BCP 122, August 2006. 1127 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1128 IANA Considerations Section in RFCs", RFC 5226, BCP 26, 1129 May 2008. 1131 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1132 Address Text Representation", RFC 5952, August 2010. 1134 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1135 Interchange Format", RFC 7159, March 2014. 1137 [RFC7285] Almi, R., Penno, R., Yang, Y., Kiesel, S., Previdi, S., 1138 Roome, W., Shalunov, S., and R. Woundy, "Application-Layer 1139 Traffic Optimization (ALTO) Protocol", RFC 7285, September 1140 2014. 1142 [ID-draft-yang-alto-path-vector-04] 1143 Bernstein, G., Gao, K., Lee, Y., Roome, W., Scharf, M., 1144 and Y. Yang, "ALTO Topology Extension: Path Vector as a 1145 Cost Mode", March 2017. 1147 [ID-draft-yang-alto-topology-06] 1148 Bernstein, G., Lee, Y., Roome, W., Scharf, M., and Y. 1149 Yang, "ALTO Topology Extensions: Node-Link Graphs", March 1150 2015. 1152 Authors' Addresses 1154 Wendy Roome 1155 Nokia Bell Labs 1156 600 Mountain Ave, Rm 3B-324 1157 Murray Hill, NJ 07974 1158 USA 1160 Phone: +1-908-582-7974 1161 Email: wendy@roome.com 1162 Y. Yang 1163 Yale University 1164 51 Prospect Street 1165 New Haven, CT 06511 1166 USA 1168 Phone: +1-203-432-6400 1169 Email: yry@cs.yale.edu