idnits 2.17.1 draft-roome-alto-unified-props-01.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. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. == There are 5 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 552 has weird spacing: '...rtyName prop...' == Line 675 has weird spacing: '...country stat...' -- The document date (July 8, 2016) is 2849 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-02' -- Possible downref: Non-RFC (?) normative reference: ref. 'ID-draft-yang-alto-topology-06' Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 4 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 July 8, 2016 5 Expires: January 9, 2017 7 Extensible Property Maps for the ALTO Protocol 8 draft-roome-alto-unified-props-01 10 Abstract 12 This document extends the Application-Layer Traffic Optimization 13 (ALTO) Protocol [RFC7285] by generalizing the concept of "endpoint 14 properties" to other entity domains, and by presenting those 15 properties as maps, similar to the network and cost maps in ALTO. 17 Requirements Language 19 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 20 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 21 document are to be interpreted as described in RFC 2119 [RFC2119]. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on January 9, 2017. 40 Copyright Notice 42 Copyright (c) 2016 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Definitions and Concepts . . . . . . . . . . . . . . . . . . . 5 59 2.1. Entities . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 2.2. Domains . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 2.3. Entity Addresses . . . . . . . . . . . . . . . . . . . . . 5 62 2.4. Domain Names . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.5. Property Names . . . . . . . . . . . . . . . . . . . . . . 6 64 2.6. Relationship to Network Maps . . . . . . . . . . . . . . . 6 65 3. Entity Domains . . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.1. Internet Address Domains . . . . . . . . . . . . . . . . . 7 67 3.1.1. IPV4 Domain . . . . . . . . . . . . . . . . . . . . . 7 68 3.1.2. IPV6 Domain . . . . . . . . . . . . . . . . . . . . . 8 69 3.1.3. Heirarchy And Inheritance . . . . . . . . . . . . . . 8 70 3.1.4. Relationship To Network Maps . . . . . . . . . . . . . 9 71 3.2. PID Domain . . . . . . . . . . . . . . . . . . . . . . . . 9 72 3.2.1. Domain Name . . . . . . . . . . . . . . . . . . . . . 9 73 3.2.2. Domain-Specific Entity Addresses . . . . . . . . . . . 10 74 3.2.3. Heirarchy And Inheritance . . . . . . . . . . . . . . 10 75 3.2.4. Relationship To Internet Addresses Domains . . . . . . 10 76 3.3. Internet Address Properties vs. PID Properties . . . . . . 10 77 4. Property Map Resource . . . . . . . . . . . . . . . . . . . . 10 78 4.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . . 11 79 4.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 11 80 4.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 11 81 4.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . . 11 82 4.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 83 4.6. Response . . . . . . . . . . . . . . . . . . . . . . . . . 11 84 5. Filtered Property Map Resource . . . . . . . . . . . . . . . . 12 85 5.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . . 13 86 5.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 13 87 5.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 13 88 5.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . . 14 89 5.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 90 5.6. Response . . . . . . . . . . . . . . . . . . . . . . . . . 14 91 6. Impact On Legacy Servers And Clients . . . . . . . . . . . . . 14 92 6.1. Impact on Endpoint Property Service . . . . . . . . . . . 14 93 6.2. Impact on Resource-Specific Properties . . . . . . . . . . 14 94 6.3. Impact on the "pid" Property . . . . . . . . . . . . . . . 15 95 6.4. Impact on Other Properties . . . . . . . . . . . . . . . . 15 97 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 98 7.1. Network Map . . . . . . . . . . . . . . . . . . . . . . . 15 99 7.2. Property Definitions . . . . . . . . . . . . . . . . . . . 16 100 7.3. Information Resource Directory (IRD) . . . . . . . . . . . 16 101 7.4. Property Map Example . . . . . . . . . . . . . . . . . . . 18 102 7.5. Filtered Property Map Example #1 . . . . . . . . . . . . . 18 103 7.6. Filtered Property Map Example #2 . . . . . . . . . . . . . 19 104 7.7. Filtered Property Map Example #3 . . . . . . . . . . . . . 20 105 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 106 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 107 9.1. application/alto-* Media Types . . . . . . . . . . . . . . 22 108 9.2. ALTO Entity Domain Registry . . . . . . . . . . . . . . . 23 109 9.3. ALTO Endpoint Property Type Registry . . . . . . . . . . . 24 110 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 111 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 25 113 1. Introduction 115 The ALTO protocol [RFC7285] introduced the concept of "properties" 116 attached to "endpoint addresses," and defined the Endpoint Property 117 Service (EPS) to allow clients to retrieve those properties. While 118 useful, the EPS, as defined in RFC7285, has at least two limitations. 120 First, it only allows properties to be associated with a particular 121 domain of entities, namely individual IP addresses. It is reasonable 122 to think that collections of endpoints, as defined by CIDRs or PIDs, 123 may also have properties. Furthermore, recent proposals 124 ([ID-draft-yang-alto-path-vector-02] and 125 [ID-draft-yang-alto-topology-06]) have suggested new classes of 126 entities with properties. The EPS cannot be extended to new entity 127 domains. Instead, new services, with new request and response 128 messages, would have to be defined for each new entity domain. 130 Second, the EPS is only defined as a POST-mode service. Clients must 131 request the properties for an explicit set of addresses. By 132 contrast, [RFC7285] defines a GET-mode Cost Map resource which 133 returns all available costs, so a client can get the full set of 134 costs once, and then lookup costs without querying the ALTO server. 135 RFC7285 does not define an equivalent service for endpoint 136 properties. Granted, it is not be practical to enumerate the 137 properties for every possible internet address. But it is unlikely a 138 property will be defined for every possible address. It is very 139 likely that properties will only be defined for a subset of 140 addresses, and that subset would be small enough to enumerate. This 141 is particularly true if blocks of addresses with a common prefix 142 (e.g., a CIDR) have the same value for a property. Furthermore, 143 entities in other domains may very well be enumerable. 145 This document proposes a new approach to ALTO properties. 146 Specifically, it defines two new resource types, namely Property Maps 147 and Filtered Property Maps. The former are GET-mode resources which 148 return the property values for all entities in a domain, and are 149 analogous the ALTO's Network Map and Cost Map resources. The latter 150 are POST-mode resources which return the values for a set of 151 properties and entities requested by the client, and are analogous to 152 ALTO's Filtered Network Maps and Filtered Cost Maps. 154 Entity domains and property names are extensible, so that new domains 155 can be defined without revising the messages defined in this 156 document, in the same way that new cost metrics and new endpoint 157 properties can be defined without revising the messages defined by 158 the ALTO protocol. 160 This proposal would subsume the Endpoint Property Service defined in 161 RFC7285, although that service may be retained for legacy clients 162 (see Section 6). 164 2. Definitions and Concepts 166 2.1. Entities 168 An entity is an object with a (possibly empty) set of properties. 169 Every entity is in a domain, such as the IPv4 and IPv6 domains, and 170 has a unique address. 172 2.2. Domains 174 A domain is a family of entities. Examples are the internet address 175 and PID domains (see Section 3.1 and Section 3.2). Another example 176 is the proposed domain of Abstract Network Elements associated with 177 topology and routing, as suggested by 178 [ID-draft-yang-alto-path-vector-02]. 180 2.3. Entity Addresses 182 Each entity has a unique name of the form: 184 domain-name : domain-specific-entity-address 186 Examples from the IP domain include individual addresses such as 187 "ipv4:192.0.2.14" and "ipv6:2001:db8::12", as well as address blocks 188 such as "ipv4:192.0.2.0/26" and "ipv6:2001:db8:1/48". 190 The type EntityAddr denotes a JSON string with an entity address in 191 this format. 193 The format of the second part of an entity address depends on the 194 domain, and must be specified when registering a new domain. 195 Addresses may be hierarchical, and properties may be inherited based 196 on that hierarchy. Again, the rules defining any hierarchy or 197 inheritance must be defined when the domain is registered. 199 Note that entity addresses do NOT have a unique textual 200 representation. For example, the strings "ipv6:2001:db8::1" and 201 "ipv6:2001:db8:0:0:0:0:0:1" refer to the same entity. 203 2.4. Domain Names 205 Each domain has a unique name. A domain name MUST be no more than 32 206 characters, and MUST NOT contain characters other than US-ASCII 207 alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and U+0061- 208 U+007A), hyphen ('-', U+002D), and low line ('_', U+005F). For 209 example, the names "ipv4" and "ipv6" identify objects in the internet 210 address domain (Section 3.1). 212 The type DomainName denotes a JSON string with a domain name in this 213 format. 215 Domain names must be registered with the IANA, and the format of the 216 entity addresses in that domain, as well as any hierarchical or 217 inheritance rules for those entities, must be specified at the same 218 time. 220 2.5. Property Names 222 The space of property names associated with entities defined by this 223 document is the same as, and is shared with, the endpoint property 224 names defined by [RFC7285]. Thus entity property names are as 225 defined in Section 10.8.2 of that document, and must be registered 226 with the "ALTO Endpoint Property Type Registry" defined in Section 227 14.3 of that document. 229 The type PropertyName denotes a JSON string with a property name in 230 this format. 232 Property names are not specific to a domain, although some properties 233 may only be applicable for particular domains, and the interpretation 234 of the value may depend on the domain. For example, suppose the 235 "geo-location" property is defined as the coordinates of a point, 236 encoded as (say) "latitude longitude [altitude]." When applied to an 237 entity that represents a specific host computer, such as an internet 238 address, the property defines the host's location. When applied to 239 an entity that represents a set of computers, such as a CIDR, the 240 property would be the location of the center of that set. If it is 241 necessary to represent the bounding box of a set of hosts, another 242 property, such as "geo-region", should be defined. 244 2.6. Relationship to Network Maps 246 [RFC7285] recognizes that some properties may be specific to another 247 ALTO resource, such as a network map. Accordingly [RFC7285] defines 248 the concept of "resource-specific endpoint properties" (Section 249 10.8.1), and indicates that dependency by prefixing the property name 250 with the ID of the resource on which it depends. That document 251 defines one resource-specific property, namely the "pid" property, 252 whose value is the name of the name of the PID containing that 253 endpoint in the associated network map. 255 This document takes a different approach. Instead of defining the 256 dependency by qualifying the property name, this document attaches 257 the dependency to the property map as a whole. Thus all properties 258 in a given property map depend on the same resource. Furthermore, 259 entity addresses may depend on a network map (for example, the 260 Abstract Network Elements suggested by 261 [ID-draft-yang-alto-path-vector-02]). Associating the dependency 262 with the property map handles any entity address dependencies as 263 well. 265 The "uses" field in an IRD entry defines the dependencies of a 266 property map resource, and the "dependent-vtags" field in a property 267 map response defines the dependencies of that map. These fields are 268 defined in Sections 9.1.5 and 11.1 of [RFC7285], respectively. 270 This is similar to how RFC7285 handles dependencies between cost 271 metrics and network maps. Recall that cost maps present the costs 272 between PIDs, and PID names depend on a network map. If an ALTO 273 server provides the "routingcost" metric for the network maps "net1" 274 and "net2", then the server defines two separate cost maps, one for 275 "net1" and the other for "net2". 277 According to [RFC7285], an ALTO server with two network maps, with 278 resource IDs "net1" and "net2", could offer a single Endpoint 279 Property Service for the two properties "net1.pid" and "net2.pid". 280 Instead, an ALTO server which supports the extensions in this 281 document would offer two different property maps for the "pid" 282 property, one depending on "net1", the other on "net2". 284 3. Entity Domains 286 This document defines the following entity domains. 288 3.1. Internet Address Domains 290 The domain of internet addresses consists of two domains (IPv4 and 291 IPv6). Both domains include individual addresses and blocks of 292 addresses. 294 3.1.1. IPV4 Domain 295 3.1.1.1. Domain Name 297 ipv4 299 3.1.1.2. Domain-Specific Entity Addresses 301 Individual addresses are strings as specified by the IPv4Addresses 302 rule of Section 3.2.2 of [RFC3986]. Blocks of addresses are prefix- 303 match strings as specified in Section 3.1 of [RFC4632]. 305 For the purpose of defining properties, an individual internet 306 address and the corresponding full-length prefix are considered 307 aliases for the same entity. Thus "ipv4:192.0.2.0" and "ipv4: 308 192.0.2.0/32" are equivalent, and have the same set of properties, as 309 are "ipv6:2001:db8::" and "ipv6:2001:db8::/128". 311 3.1.2. IPV6 Domain 313 3.1.2.1. Domain Name 315 ipv6 317 3.1.2.2. Domain-Specific Entity Addresses 319 Individual addresses are strings as specified by Section 4 of 320 [RFC5952]. Blocks of addresses are prefix-match strings as specified 321 in Section 7 of [RFC5952]. 323 For the purpose of defining properties, an individual internet 324 address and the corresponding 128-bit prefix are considered aliases 325 for the same entity. That is, "ipv6:2001:db8::1" and "ipv:2001:db8:: 326 1/128" are equivalent, and have the same set of properties. 328 3.1.3. Heirarchy And Inheritance 330 Both domains allow property values to be inherited. Specifically, if 331 a property P is not defined for a specific internet address IP, but P 332 is defined for some block C which prefix-matches IP, then the address 333 IP inherits the value of P defined for block C. If more than one such 334 block defines a value for P, IP inherits the value of P in the block 335 with the longest prefix. 337 Address blocks can also inherit properties: if property P is not 338 defined for a block C, but is defined for some block C' prefix- 339 matches C, and C' has a shorter mask than C, then block C inherits 340 the property from C'. If there are several such blocks C', C 341 inherits from the block with the longest prefix. 343 As an example, suppose that a server defines the property P for the 344 following entities: 346 ipv4:192.0.2.0/26: P=v1 347 ipv4:192.0.2.0/28: P=v2 348 ipv4:192.0.2.0/30: P=v3 349 ipv4:192.0.2.0: P=v4 351 Defined Property Values 353 Then the following entities have the indicated values: 355 ipv4:192.0.2.0: P=v4 356 ipv4:192.0.2.1: P=v3 357 ipv4:192.0.2.16: P=v2 358 ipv4:192.0.2.32: P=v1 359 ipv4:192.0.2.64: (not defined) 360 ipv4:192.0.2.0/32: P=v4 361 ipv4:192.0.2.0/31: P=v3 362 ipv4:192.0.2.0/29: P=v2 363 ipv4:192.0.2.0/27: P=v1 364 ipv4:192.0.2.0/25: (not defined) 366 Inherited Property Values 368 3.1.4. Relationship To Network Maps 370 An internet address domain may or may not be associated with an ALTO 371 network map resource. Logically, there is a map of internet address 372 entities to property values for each network map defined by the ALTO 373 server, plus an additional property map for internet address entities 374 which are not associated with a network map. These maps are separate 375 from each other. The prefixes in the property map do not have to 376 correspond to the prefixes defining the network map's PIDs. For 377 example, the property map for a network map may assign properties to 378 "ipv4:192.0.2.0/24" even if that prefix is not associated with any 379 PID in the network map. 381 3.2. PID Domain 383 The PID domain associates property values with the PIDs in a network 384 map. Accordingly, this domain always depends on a network map. 386 3.2.1. Domain Name 388 pid 390 3.2.2. Domain-Specific Entity Addresses 392 The entity addresses are the PID names of the associated network map. 394 3.2.3. Heirarchy And Inheritance 396 There is no hierarchy or inheritance for properties associated with 397 PIDs. 399 3.2.4. Relationship To Internet Addresses Domains 401 The PID domain and the internet address domains are completely 402 independent; the properties associated with a PID have no relation to 403 the properties associated with the prefixes or endpoint addresses in 404 that PID. An ALTO server MAY choose to assign some or all properties 405 of a PID to the prefixes in that PID, but is not required to do so. 407 For example, suppose "PID1" consists of the prefix "ipv4: 408 192.0.2.0/24", and has the property "P" with value "v1". The 409 internet address entities "ipv4:192.0.2.0" and "ipv4:192.0.2.0/24" 410 may or may not have a value for the property "P", and if they do, it 411 is not necessarily "v1". 413 3.3. Internet Address Properties vs. PID Properties 415 Because the internet address and PID domains are completely separate, 416 the question may arise as to which domain is best for a property. In 417 general, the internet address domain is best for properties that are 418 closely related to the internet address, or which are associated 419 with, and inherited through, blocks of addresses. 421 The PID domain is best for properties that arise from the definition 422 of the PID, rather than from the internet address prefixes in that 423 PID. 425 For example, because internet addresses are allocated to server 426 providers by blocks of prefixes, an "ISP" property would be best 427 associated with the internet address domain. On the other hand, a 428 property that explains why a PID was formed, or how it relates the a 429 provider's network, would best be associated with the PID domain. 431 4. Property Map Resource 433 A Property Map returns the properties defined for all entities in one 434 of more domains. 436 Section 7.4 gives an example of a property map request and response. 438 4.1. Media Type 440 The media type of an ALTO Property Map resource is "application/ 441 alto-propmap+json". 443 4.2. HTTP Method 445 An ALTO Property Map resource is requested using the HTTP GET method. 447 4.3. Accept Input Parameters 449 None. 451 4.4. Capabilities 453 The capabilities are defined by an object of type 454 PropertyMapCapabilities: 456 object { 457 DomainName domain-types<1..*>; 458 PropertyName prop-types<1..*>; 459 } PropertyMapCapabilities; 461 where "domain-types" is an array with the domains of the entities in 462 this property map, and "prop-types" is an array with the names of the 463 properties returned for entities in those domains. 465 4.5. Uses 467 An array with the resource ID(s) of resource(s) with which the 468 domains in this map are associated. In most cases, this array will 469 have at most one ID, and it will be for a network map resource. 471 4.6. Response 473 If the domains in this property map depend on other resources, the 474 "dependent-vtags" field in the "meta" field of the response MUST be 475 an array that includes the version tags of those resources. 477 The data component of a Property Map response is named "property- 478 map", which is a JSON object of type PropertyMapData, where: 480 object { 481 PropertyMapData property-map; 482 } InfoResourceProperties : ResponseEntityBase; 484 object-map { 485 EntityAddr -> EntityProps; 486 } PropertyMapData; 488 object { 489 PropertyName -> JSONValue; 490 } EntityProps; 492 The ResponseEntityBase type is defined in Section 8.4 of [RFC7285]. 494 Specifically, a PropertyMapData object has one member for each entity 495 in the Property Map. The entity's properties are encoded in the 496 corresponding EntityProps object. EntityProps encodes one name/value 497 pair for each property, where the property names are encoded as 498 strings of type PropertyName. A protocol implementation SHOULD 499 assume that the property value is either a JSONString or a JSON 500 "null" value, and fail to parse if it is not, unless the 501 implementation is using an extension to this document that indicates 502 when and how property values of other data types are signaled. 504 For each entity in the Property Map, the ALTO Server returns the 505 value defined for each of the properties specified in this resource's 506 "capabilities" list. For efficiency, the ALTO Server SHOULD omit 507 property values that are inherited rather than explicitly defined; if 508 a client needs inherited values, the client SHOULD use the domain's 509 inheritance rules to deduce those values. 511 An ALTO Server MAY explicitly define a property as not having a value 512 for a particular entity. That is, a server may say that a property 513 is "defined to have no value", as opposed to the property being 514 "undefined". If that entity would inherit a value for that property, 515 then the ALTO server MUST return a "null" value for that property, 516 and an ALTO client MUST recognize a "null" value means "do not apply 517 the inheritance rules for this property." If the entity would not 518 inherit a value, the ALTO server MAY return "null" or MAY just omit 519 the property. 521 If the ALTO Server does not define any properties for an entity, then 522 the server MAY omit that entity from the response. 524 5. Filtered Property Map Resource 526 A Filtered Property Map returns the values of a set of properties for 527 a set of entities selected by the client. 529 Section 7.5, Section 7.6 and Section 7.7 give examples of filtered 530 property map requests and responses. 532 5.1. Media Type 534 The media type of an ALTO Property Map resource is "application/ 535 alto-propmap+json". 537 5.2. HTTP Method 539 An ALTO Property Map resource is requested using the HTTP POST 540 method. 542 5.3. Accept Input Parameters 544 The input parameters for a Filtered Property Map request are supplied 545 in the entity body of the POST request. This document specifies the 546 input parameters with a data format indicated by the media type 547 "application/alto-propmapparams+json", which is a JSON object of type 548 ReqFilteredPropertyMap: 550 object { 551 EntityAddr entities<1..*> 552 PropertyName properties<1..*>; 553 } ReqFilteredPropertyMap; 555 with fields: 557 entities: List of entity addresses for which the specified 558 properties are to be returned. The ALTO server MUST interpret 559 entries appearing multiple times as if they appeared only once. 560 The domain of each entity MUST be included in the list of domains 561 in this resource's "capabilities" field (Section 5.4). 563 properties: List of properties to be returned for each entity. Each 564 specified property MUST be included in the list of properties in 565 this resource's "capabilities" field (Section 5.4). The ALTO 566 server MUST interpret entries appearing multiple times as if they 567 appeared only once. 569 Note that the "entities" and "properties" fields MUST have at 570 least one entry each. 572 5.4. Capabilities 574 The capabilities are defined by an object of type 575 PropertyMapCapabilities, as defined in Section 4.4. 577 5.5. Uses 579 An array with the resource ID(s) of resource(s) with which the 580 domains in this map are associated. In most cases, this array will 581 have at most one ID, and it will be for a network map resource. 583 5.6. Response 585 The response is the same as for the property map (Section 4.6), 586 except that it only includes the entities and properties requested by 587 the client. 589 Also, the Filtered Property Map response MUST include all inherited 590 property values for the specified entities (unlike the Full Property 591 Map, the Filtered Property Map response does not include enough 592 information for the client to calculate the inherited values). 594 6. Impact On Legacy Servers And Clients 596 6.1. Impact on Endpoint Property Service 598 The property maps defined in this document provide the same 599 functionality as the Endpoint Property Service (EPS) defined in 600 Section 11.4 of [RFC7285]. Accordingly, it is RECOMMENDED that the 601 EPS be deprecated in favor of property maps. However, ALTO servers 602 MAY provide an EPS for the benefit of legacy clients. 604 6.2. Impact on Resource-Specific Properties 606 Section 10.8 of [RFC7285] defines two categories of endpoint 607 properties: "resource-specific" and "global". Resource-specific 608 property names are prefixed with the ID of the resource they depended 609 upon, while global property names have no such prefix. The property 610 map resources defined in this document do not distinguish between 611 those two types of properties. Instead, if there is a dependency, it 612 is indicated by the "uses" capability of a property map, and is 613 shared by all properties and entity domains in that map. 614 Accordingly, it is RECOMMENDED that resource-specific endpoint 615 properties be deprecated, and no new resource-specific endpoint 616 properties be defined. 618 6.3. Impact on the "pid" Property 620 Section 7.1.1 of [RFC7285] defines the resource-specific endpoint 621 property "pid", whose value is the name of the PID containing that 622 endpoint. For compatibility with legacy clients, an ALTO server 623 which provides the "pid" property via the Endpoint Property Service 624 MUST use that definition, and that syntax, in the EPS resource. 626 However, when used with property maps, this document amends the 627 definition of the "pid" property as follows. 629 First, the name of the property is simply "pid"; the name is not 630 prefixed with the resource ID of a network map. The "uses" 631 capability of the property map resource indicates the associated 632 network map. This implies that a property map can only return the 633 "pid" property for one network map; if an ALTO server provides 634 several network maps, it must provide a property map resource for 635 each one. 637 Second, a client MAY request the "pid" property for a block of 638 addresses. An ALTO server determines the value of "pid" for an 639 address block C as follows. Let CS be the set of all address blocks 640 in the network map. If C is in CS, then the value of "pid" is the 641 name of the PID associated with C. Otherwise, find the longest block 642 C' in CS such that C' prefix-matches C, but is shorter than C. If 643 there is such a block C', the value of "pid" is the name of the PID 644 associated with C'. If not, then "pid" has no value for block C. 646 Note that although an ALTO server MAY provide a GET-mode property map 647 resource which returns the entire map for the "pid" property, there 648 is no need to do so, because that map is simply the inverse of the 649 network map. 651 6.4. Impact on Other Properties 653 In general, there should be little or no impact on other previously 654 defined properties. The only consideration is that properties can 655 now be defined on blocks of addresses, rather than just individual 656 addresses, which might change the semantics of a property. 658 7. Examples 660 7.1. Network Map 662 The examples in this section use a very simple default network map: 664 defaultpid: ipv4:0.0.0.0/0 ipv6:::0/0 665 pid1: ipv4:192.0.2.0/25 666 pid2: ipv4:192.0.2.0/28 ipv4:192.0.2.16/28 668 Figure 1: Example Network Map 670 7.2. Property Definitions 672 The examples in this section use four additional properties, "ISP", 673 "ASN", "country" and "state", with the following values: 675 ISP ASN country state 676 ipv4:192.0.2.0/24: BitsRus - us - 677 ipv4:192.0.2.0/28: - 12345 - NJ 678 ipv4:192.0.2.16/28: - 12345 - CT 679 ipv4:192.0.2.0: - - - PA 681 Figure 2: Example Property Values 683 7.3. Information Resource Directory (IRD) 685 The following IRD defines the relevant resources of the ALTO server. 686 It provides two Property Map resources, one for the "ISP" and "ASN" 687 properties, and another for the "country" and "state" properties. 688 The server could have provided a Property Map resource for all four 689 properties, but did not, presumably because the organization that 690 runs the ALTO server believes any given client is not interested in 691 all four properties. 693 The server provides two Filtered Property Maps. The first returns 694 all four properties, and the second just returns the "pid" property 695 for the default network map. 697 The Property Maps for the "ISP", "ASN", "country" and "state" 698 properties do not depend on the default network map (they do not have 699 a "uses" capability), because the definitions of those properties do 700 not depend on the default network map. The Filtered Property Map for 701 the "pid" property does have a "uses" capability for the default 702 network map, because that defines the values of the "pid" property. 704 Note that for legacy clients, the ALTO server provides an Endpoint 705 Property Service for the "pid" property for the default network map. 707 "meta": { ... }, 708 "resources" : { 709 "default-network-map" : { 710 "uri" : "http://alto.example.com/networkmap", 711 "media-type" : "application/alto-networkmap+json" 712 }, 713 .... cost map resources .... 714 "country-state-property-map" : { 715 "uri" : "http://alto.example.com/propmap/full/inet-cs", 716 "media-type" : "application/alto-propmap+json", 717 "capabilities" : { 718 "domain-types": [ "ipv4", "ipv6" ], 719 "prop-types" : [ "country", "state" ] 720 } 721 }, 722 "isp-asn-property-map" : { 723 "uri" : "http://alto.example.com/propmap/full/inet-ia", 724 "media-type" : "application/alto-propmap+json", 725 "capabilities" : { 726 "domain-types": [ "ipv4", "ipv6" ], 727 "prop-types" : [ "ISP", "ASN" ] 728 } 729 }, 730 "iacs-property-map" : { 731 "uri" : "http://alto.example.com/propmap/lookup/inet-iacs", 732 "media-type" : "application/alto-propmap+json", 733 "accepts" : "application/alto-propmapparams+json", 734 "capabilities" : { 735 "domain-types": [ "ipv4", "ipv6" ], 736 "prop-types" : [ "ISP", "ASN", "country", "state" ] 737 } 738 }, 739 "pid-property-map" : { 740 "uri" : "http://alto.example.com/propmap/lookup/pid", 741 "media-type" : "application/alto-propmap+json", 742 "accepts" : "application/alto-propmapparams+json", 743 "uses" : [ "default-network-map" ] 744 "capabilities" : { 745 "domain-types": [ "ipv4", "ipv6" ], 746 "prop-types" : [ "pid" ] 747 } 748 }, 749 "legacy-pid-property" : { 750 "uri" : "http://alto.example.com/legacy/eps-pid", 751 "media-type" : "application/alto-endpointprop+json", 752 "accepts" : "application/alto-endpointpropparams+json", 753 "capabilities" : { 754 "prop-types" : [ "default-network-map.pid" ] 755 } 756 } 757 } 758 Example IRD 760 7.4. Property Map Example 762 The following example uses the properties and IRD defined above to 763 retrieve a property map for entities with the "ISP" and "ASN" 764 properties. Note that the response does not include the entity 765 "ipv4:192.0.2.0", because it does not have a value for either of 766 those properties. Also note that the entities "ipv4:192.0.2.0/28" 767 and "ipv4:192.0.2.16/28" are refinements of "ipv4:192.0.2.0/24", and 768 hence inherit its value for "ISP" property. But because that value 769 is inherited, it is not explicitly listed in the property map. 771 GET /propmap/full/inet-ia HTTP/1.1 772 Host: alto.example.com 773 Accept: application/alto-propmap+json,application/alto-error+json 775 HTTP/1.1 200 OK 776 Content-Length: ### 777 Content-Type: application/alto-propmap+json 778 { 779 "property-map": { 780 "ipv4:192.0.2.0/24": {"ISP: "BitsRus"}, 781 "ipv4:192.0.2.0/28": {"ASN": "12345"}, 782 "ipv4:192.0.2.16/28": {"ASN": "12345"} 783 } 784 } 786 7.5. Filtered Property Map Example #1 788 The following example uses the Filtered Property Map resource to 789 request the "ISP", "ASN" and "state" properties for several IPv4 790 addresses. Note that the value of "state" for "ipv4:192.0.2.0" is 791 the only explicitly defined property; the other values are all 792 derived by the inheritance rules for internet address entities. 794 POST /propmap/lookup/inet-iacs HTTP/1.1 795 Host: alto.example.com 796 Accept: application/alto-propmap+json,application/alto-error+json 797 Content-Length: ### 798 Content-Type: application/alto-propmapparams+json 800 { 801 "entities" : [ "ipv4:192.0.2.0", 802 "ipv4:192.0.2.1", 803 "ipv4:192.0.2.17" ], 804 "properties" : [ "ISP", "ASN", "state" ] 805 } 807 HTTP/1.1 200 OK 808 Content-Length: ### 809 Content-Type: application/alto-propmap+json 810 { 811 "property-map": { 812 "ipv4:192.0.2.0": 813 {"ISP": "BitsRus", "ASN": "12345", "state": "PA"}, 814 "ipv4:192.0.2.1": 815 {"ISP": "BitsRus", "ASN": "12345", "state": "NJ"}, 816 "ipv4:192.0.2.17": 817 {"ISP": "BitsRus", "ASN": "12345", "state": "CT"} 818 } 819 } 821 7.6. Filtered Property Map Example #2 823 The following example uses the Filtered Property Map resource to 824 request the "ASN", "country" and "state" properties for several IPv4 825 prefixes. Note that none of the returned property values were 826 explicitly defined; all values are derived by the inheritance rules 827 for internet address entities. 829 Also note the "ASN" property has the value "12345" for both the 830 blocks "ipv4:192.0.2.0/28" and "ipv4:192.0.2.16/28", so every address 831 in the block "ipv4:192.0.2.0/27" has that property value. However 832 the block "ipv4:192.0.2.0/27" itself does not have a value for "ASN": 833 address blocks cannot inherit properties from blocks with longer 834 prefixes, even if every such block has the same value. 836 POST /propmap/lookup/inet-iacs HTTP/1.1 837 Host: alto.example.com 838 Accept: application/alto-propmap+json,application/alto-error+json 839 Content-Length: ### 840 Content-Type: application/alto-propmapparams+json 842 { 843 "entities" : [ "ipv4:192.0.2.0/26", 844 "ipv4:192.0.2.0/27", 845 "ipv4:192.0.2.0/28" ], 846 "properties" : [ "ASN", "country", "state" ] 847 } 849 HTTP/1.1 200 OK 850 Content-Length: ### 851 Content-Type: application/alto-propmap+json 852 { 853 "property-map": { 854 "ipv4:192.0.2.0/26": {"country": "us"}, 855 "ipv4:192.0.2.0/27": {"country": "us"}, 856 "ipv4:192.0.2.0/28": {"ASN": "12345", 857 "country": "us", 858 "state": "NJ"} 859 } 860 } 862 7.7. Filtered Property Map Example #3 864 The following example uses the Filtered Property Map resource to 865 request the "pid" property for several IPv4 addresses and prefixes. 867 Note that the value of "pid" for the prefix "ipv4:10.0.0.0/15" is 868 "pid1", even though all addresses in that block are in "pid2", 869 because "ipv4:10.0.0.0/8" is the longest prefix in the network map 870 which prefix-matches "ipv4:10.0.0.0/15", and that prefix is in 871 "pid1". 873 POST /propmap/lookup/pid HTTP/1.1 874 Host: alto.example.com 875 Accept: application/alto-propmap+json,application/alto-error+json 876 Content-Length: ### 877 Content-Type: application/alto-propmapparams+json 879 { 880 "entities" : [ 881 "ipv4:192.0.2.0 10.0.0.0", 882 "ipv4:192.0.2.16 10.1.0.0", 883 "ipv4:192.0.2.64 10.3.0.0", 884 "ipv4:192.0.2.128 11.0.0.0", 885 "ipv4:192.0.2.0/26 10.0.0.0/15", 886 "ipv4:192.0.2.0/30 10.0.0.0/17" ], 887 "properties" : [ "pid" ] 888 } 890 HTTP/1.1 200 OK 891 Content-Length: ### 892 Content-Type: application/alto-propmap+json 893 { 894 "meta" : { 895 "dependent-vtags" : [ 896 {"resource-id": "default-network-map", 897 "tag": "7915dc0290c2705481c491a2b4ffbec482b3cf62"} 898 ] 899 }, 900 "property-map": { 901 "ipv4:192.0.2.0": {"pid": "pid2"}, 902 "ipv4:192.0.2.16": {"pid": "pid2"}, 903 "ipv4:192.0.2.64": {"pid": "pid1"}, 904 "ipv4:192.0.2.128": {"pid": "defaultpid"}, 905 "ipv4:192.0.2.0/26": {"pid": "pid1"}, 906 "ipv4:192.0.2.0/30": {"pid": "pid2"} 907 } 908 } 910 8. Security Considerations 912 As discussed in Section 15 of [RFC7285], properties may have 913 sensitive customer-specific information. If this is the case, an 914 ALTO Server may limit access to those properties by providing several 915 different property maps. For non-sensitive properties, the ALTO 916 Server would provide a URI which accepts requests from any client. 917 Sensitive properties, on the other hand, would only be available via 918 a secure URI which would require client authentication. 920 Also, while technically this document does not introduce any security 921 risks not inherent in the Endpoint Property Service defined by 922 [RFC7285], the GET-mode property map resource defined in this 923 document does make it easier for a client to download large numbers 924 of property values. Accordingly, an ALTO Server should limit GET- 925 mode property maps for to properties which do not contain sensitive 926 data. 928 9. IANA Considerations 930 This document defines additional application/alto-* media types, and 931 extends the ALTO endpoint property registry. 933 9.1. application/alto-* Media Types 935 This document registers two additional ALTO media types, listed in 936 Table 1. 938 +-------------+-------------------------+---------------+ 939 | Type | Subtype | Specification | 940 +-------------+-------------------------+---------------+ 941 | application | alto-propmap+json | Section 4.1 | 942 | application | alto-propmapparams+json | Section 5.3 | 943 +-------------+-------------------------+---------------+ 945 Table 1: Additional ALTO Media Types 947 Type name: application 949 Subtype name: This documents registers multiple subtypes, as listed 950 in Table 1. 952 Required parameters: n/a 954 Optional parameters: n/a 956 Encoding considerations: Encoding considerations are identical to 957 those specified for the "application/json" media type. See 958 [RFC7159]. 960 Security considerations: Security considerations relating to the 961 generation and consumption of ALTO Protocol messages are discussed 962 in Section 15 of [RFC7285]. 964 Interoperability considerations: This document specifies format of 965 conforming messages and the interpretation thereof. 967 Published specification: This document is the specification for 968 these media types; see Table 1 for the section documenting each 969 media type. 971 Applications that use this media type: ALTO servers and ALTO clients 972 either stand alone or are embedded within other applications. 974 Additional information: 976 Magic number(s): n/a 978 File extension(s): This document uses the mime type to refer to 979 protocol messages and thus does not require a file extension. 981 Macintosh file type code(s): n/a 983 Person & email address to contact for further information: See 984 Authors' Addresses section. 986 Intended usage: COMMON 988 Restrictions on usage: n/a 990 Author: See Authors' Addresses section. 992 Change controller: Internet Engineering Task Force 993 (mailto:iesg@ietf.org). 995 9.2. ALTO Entity Domain Registry 997 This document requests IANA to create and maintain the "ALTO Entity 998 Domain Registry", listed in Table 2. 1000 +------------+-------------------------+-------------------------+ 1001 | Identifier | Entity Address Encoding | Hierarchy & Inheritance | 1002 +------------+-------------------------+-------------------------+ 1003 | ipv4 | See Section 3.1.1 | See Section 3.1.3 | 1004 | ipv6 | See Section 3.1.2 | See Section 3.1.3 | 1005 | pid | See Section 3.2 | None | 1006 +------------+-------------------------+-------------------------+ 1008 Table 2: ALTO Entity Domain Names 1010 This registry serves two purposes. First, it ensures uniqueness of 1011 identifiers referring to ALTO entity domains. Second, it states the 1012 requirements for allocated domain names. 1014 New ALTO entity domains are assigned after IETF Review [RFC5226] to 1015 ensure that proper documentation regarding the new ALTO entity 1016 domains and their security considerations has been provided. RFCs 1017 defining new entity domains should indicate how an entity in a 1018 registered domain is encoded as an EntityName, and, if applicable, 1019 the rules defining the entity hierarchy and property inheritance. 1020 Updates and deletions of ALTO entity domains follow the same 1021 procedure. 1023 Registered ALTO entity domain identifiers MUST conform to the 1024 syntactical requirements specified in Section 2.4. Identifiers are 1025 to be recorded and displayed as strings. 1027 Requests to add a new value to the registry MUST include the 1028 following information: 1030 o Identifier: The name of the desired ALTO entity domain. 1032 o Entity Address Encoding: The procedure for encoding the address of 1033 an entity of the registered type as an EntityAddr (see 1034 Section 2.3). 1036 o Hierarchy: If the entities form a hierarchy, the procedure for 1037 determining that hierarchy. 1039 o Inheritance: If entities can inherit property values from other 1040 entities, the procedure for determining that inheritance. 1042 o Security Considerations: In some usage scenarios, entity addresses 1043 carried in ALTO Protocol messages may reveal information about an 1044 ALTO client or an ALTO service provider. Applications and ALTO 1045 service providers using addresses of the registered type should be 1046 made aware of how (or if) the addressing scheme relates to private 1047 information and network proximity. 1049 This specification requests registration of the identifiers "ipv4", 1050 "ipv6" and "pid", as shown in Table 2. 1052 9.3. ALTO Endpoint Property Type Registry 1054 The ALTO Endpoint Property Type Registry was created by [RFC7285]. 1055 If possible, the name of that registry should be changed to "ALTO 1056 Entity Property Type Registry", to indicate that it is not restricted 1057 to Endpoint Properties. If it is not feasible to change the name, 1058 the description must be amended to indicate that it registers 1059 properties in all domains, rather than just the internet address 1060 domain. 1062 10. References 1064 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1065 Requirement Levels", RFC 2119, BCP 14, March 1997. 1067 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1068 Resource Identifier (URI): Generic Syntax", RFC 3986, 1069 January 2005. 1071 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 1072 (CIDR): The Internet Address Assignment and Aggregation 1073 Plan", RFC 4632, BCP 122, August 2006. 1075 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1076 IANA Considerations Section in RFCs", RFC 5226, BCP 26, 1077 May 2008. 1079 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1080 Address Text Representation", RFC 5952, August 2010. 1082 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1083 Interchange Format", RFC 7159, March 2014. 1085 [RFC7285] Almi, R., Penno, R., Yang, Y., Kiesel, S., Previdi, S., 1086 Roome, W., Shalunov, S., and R. Woundy, "Application-Layer 1087 Traffic Optimization (ALTO) Protocol", RFC 7285, 1088 September 2014. 1090 [ID-draft-yang-alto-path-vector-02] 1091 Bernstein, G., Gao, K., Lee, Y., Roome, W., Scharf, M., 1092 and Y. Yang, "ALTO Topology Extension: Path Vector as a 1093 Cost Mode", July 2016. 1095 [ID-draft-yang-alto-topology-06] 1096 Bernstein, G., Lee, Y., Roome, W., Scharf, M., and Y. 1097 Yang, "ALTO Topology Extensions: Node-Link Graphs", 1098 March 2015. 1100 Author's Address 1102 Wendy Roome 1103 Nokia Bell Labs 1104 600 Mountain Ave, Rm 3B-324 1105 Murray Hill, NJ 07974 1106 USA 1108 Phone: +1-908-582-7974 1109 Email: wendy.roome@nokia-bell-labs.com