idnits 2.17.1 draft-ietf-cdni-metadata-06.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 : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 5 characters in excess of 72. == There are 2 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 14, 2014) is 3717 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) == Outdated reference: A later version (-14) exists of draft-ietf-cdni-framework-09 Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Niven-Jenkins 3 Internet-Draft R. Murray 4 Intended status: Standards Track G. Watson 5 Expires: August 18, 2014 Velocix (Alcatel-Lucent) 6 M. Caulfield 7 K. Leung 8 Cisco Systems 9 K. Ma 10 Azuki Systems, Inc. 11 February 14, 2014 13 CDN Interconnect Metadata 14 draft-ietf-cdni-metadata-06 16 Abstract 18 The CDNI Metadata Interface enables interconnected CDNs to exchange 19 content distribution metadata in order to enable content acquisition 20 and delivery. The CDNI metadata associated with a piece of content 21 provides a downstream CDN with sufficient information for the 22 downstream CDN to service content requests on behalf of an upstream 23 CDN. This document describes both the core set of CDNI metadata and 24 the protocol for exchanging that metadata. 26 Requirements Language 28 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 29 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 30 document are to be interpreted as described in RFC 2119 [RFC2119]. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on August 18, 2014. 49 Copyright Notice 51 Copyright (c) 2014 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. Design Principles . . . . . . . . . . . . . . . . . . . . . . 4 69 3. CDNI Metadata Data Model . . . . . . . . . . . . . . . . . . 5 70 3.1. HostIndex, HostMetadata & PathMetadata objects . . . . . 6 71 3.2. Generic CDNI Metadata Object Properties . . . . . . . . . 9 72 3.3. Metadata Inheritance and Override . . . . . . . . . . . . 10 73 3.4. Metadata Naming . . . . . . . . . . . . . . . . . . . . . 11 74 4. Encoding-Independent CDNI Metadata Object Descriptions . . . 11 75 4.1. CDNI Metadata Structural Object Descriptions . . . . . . 11 76 4.1.1. HostIndex . . . . . . . . . . . . . . . . . . . . . . 12 77 4.1.2. HostMatch . . . . . . . . . . . . . . . . . . . . . . 12 78 4.1.3. HostMetadata . . . . . . . . . . . . . . . . . . . . 12 79 4.1.4. PathMatch . . . . . . . . . . . . . . . . . . . . . . 13 80 4.1.5. PathMetadata . . . . . . . . . . . . . . . . . . . . 13 81 4.1.6. PatternMatch . . . . . . . . . . . . . . . . . . . . 14 82 4.1.7. GenericMetadata . . . . . . . . . . . . . . . . . . . 15 83 4.2. CDNI Metadata Property Object Descriptions . . . . . . . 16 84 4.2.1. Source Metadata . . . . . . . . . . . . . . . . . . . 16 85 4.2.1.1. Source . . . . . . . . . . . . . . . . . . . . . 16 86 4.2.2. LocationACL Metadata . . . . . . . . . . . . . . . . 17 87 4.2.2.1. LocationRule . . . . . . . . . . . . . . . . . . 17 88 4.2.2.2. Footprint . . . . . . . . . . . . . . . . . . . . 18 89 4.2.3. TimeWindowACL Metadata . . . . . . . . . . . . . . . 18 90 4.2.3.1. TimeWindowRule . . . . . . . . . . . . . . . . . 18 91 4.2.3.2. TimeWindow . . . . . . . . . . . . . . . . . . . 19 92 4.2.4. ProtocolACL Metadata . . . . . . . . . . . . . . . . 19 93 4.2.4.1. ProtocolRule . . . . . . . . . . . . . . . . . . 20 94 4.2.5. Authorization Metadata . . . . . . . . . . . . . . . 20 95 4.2.6. Auth . . . . . . . . . . . . . . . . . . . . . . . . 21 96 4.2.6.1. Credentials Auth Type . . . . . . . . . . . . . . 21 98 4.2.7. Cache . . . . . . . . . . . . . . . . . . . . . . . . 22 99 4.2.8. Grouping . . . . . . . . . . . . . . . . . . . . . . 22 100 4.3. CDNI Metadata Simple Data Type Descriptions . . . . . . . 22 101 4.3.1. Link . . . . . . . . . . . . . . . . . . . . . . . . 23 102 4.3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . 23 103 4.3.3. Endpoint . . . . . . . . . . . . . . . . . . . . . . 23 104 4.3.4. URI . . . . . . . . . . . . . . . . . . . . . . . . . 24 105 4.3.5. Time . . . . . . . . . . . . . . . . . . . . . . . . 24 106 5. CDNI Metadata Capabilities . . . . . . . . . . . . . . . . . 24 107 5.1. Protocol ACL Capabilities . . . . . . . . . . . . . . . . 24 108 5.2. Authorization Metadata Capabilities . . . . . . . . . . . 25 109 6. CDNI Metadata interface . . . . . . . . . . . . . . . . . . . 25 110 6.1. Transport . . . . . . . . . . . . . . . . . . . . . . . . 26 111 6.2. Retrieval of CDNI Metadata resources . . . . . . . . . . 26 112 6.3. Bootstrapping . . . . . . . . . . . . . . . . . . . . . . 27 113 6.4. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 27 114 6.4.1. MIME Media Types . . . . . . . . . . . . . . . . . . 28 115 6.4.2. JSON Encoding of Objects . . . . . . . . . . . . . . 28 116 6.4.2.1. JSON Example . . . . . . . . . . . . . . . . . . 29 117 6.5. Extensibility . . . . . . . . . . . . . . . . . . . . . . 33 118 6.5.1. Metadata Enforcement . . . . . . . . . . . . . . . . 33 119 6.5.2. Metadata Override . . . . . . . . . . . . . . . . . . 34 120 6.6. Versioning . . . . . . . . . . . . . . . . . . . . . . . 34 121 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 122 7.1. GenericMetadata Type Registry . . . . . . . . . . . . . . 35 123 7.1.1. GenericMetadata Sub-Registries . . . . . . . . . . . 36 124 7.1.1.1. Footprint Sub-Registry . . . . . . . . . . . . . 36 125 7.1.1.2. Protocol Sub-Registry . . . . . . . . . . . . . . 37 126 7.1.1.3. Authentication Sub-Registry . . . . . . . . . . . 38 127 8. Security Considerations . . . . . . . . . . . . . . . . . . . 39 128 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39 129 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 130 10.1. Normative References . . . . . . . . . . . . . . . . . . 39 131 10.2. Informative References . . . . . . . . . . . . . . . . . 40 132 Appendix A. Relationship to the CDNI Requirements . . . . . . . 40 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 135 1. Introduction 137 CDNI enables a downstream CDN to service content requests on behalf 138 of an upstream CDN. The CDNI metadata associated with a piece of 139 content (or with a set of contents) provides a downstream CDN with 140 sufficient information for servicing content requests on behalf of an 141 upstream CDN in accordance with the policies defined by the upstream 142 CDN. 144 The CDNI Metadata Interface is introduced by [RFC6707] along with 145 three other interfaces that may be used to compose a CDNI solution 146 (Control, Request Routing and Logging). [I-D.ietf-cdni-framework] 147 expands on the information provided in [RFC6707] and describes each 148 interface, and the relationships between them, in more detail. The 149 requirements for the CDNI metadata interface are specified in 150 [I-D.ietf-cdni-requirements]. 152 This document focuses on the CDNI Metadata interface which enables a 153 downstream CDN to obtain CDNI Metadata from an upstream CDN so that 154 the downstream CDN can properly process and respond to: 156 o Redirection Requests received over the CDNI Request Routing 157 protocol. 159 o Content Requests received directly from User Agents. 161 Specifically, this document proposes: 163 o A data structure for mapping content requests to CDNI Metadata 164 properties (Section 3). 166 o An initial set of CDNI Metadata properties (Section 4.2). 168 o A RESTful web service for the transfer of CDNI Metadata 169 (Section 6). 171 1.1. Terminology 173 This document reuses the terminology defined in [RFC6707]. 175 Additionally, the following terms are used throughout this document 176 and are defined as follows: 178 o Object - a collection of properties 180 o Property - a key and value pair where the key is a property name 181 and the value is the property value or an object. 183 2. Design Principles 185 The proposed CDNI Metadata Interface was designed to achieve the 186 following objectives: 188 1. Cacheability of CDNI metadata objects 190 2. Deterministic mapping from redirection and content requests to 191 CDNI metadata properties 193 3. Support for DNS redirection as well as application-specific 194 redirection (for example HTTP redirection) 196 4. Minimal duplication of CDNI metadata 198 5. Leverage existing protocols 200 Cacheability improves the latency of acquiring metadata while 201 maintaining its freshness and therefore improves the latency of 202 serving content requests. The CDNI Metadata Interface uses HTTP to 203 achieve cacheability. 205 Deterministic mappings from content to metadata properties eliminates 206 ambiguity and ensures that policies are applied consistently by all 207 downstream CDNs. 209 Support for both HTTP and DNS redirection ensures that the CDNI 210 Metadata Interface can be used for HTTP and DNS redirection and also 211 meets the same design principles for both HTTP and DNS based 212 redirection schemes. 214 Minimal duplication of CDNI metadata provides space efficiency on 215 storage in the CDNs, on caches in the network, and across the network 216 between CDNs. 218 Leveraging existing protocols avoids reinventing common mechanisms 219 such as data structure encoding (e.g. XML, JSON) and data transport 220 (e.g. HTTP). 222 3. CDNI Metadata Data Model 224 The CDNI Metadata Model describes a data structure for mapping 225 redirection requests and content requests to metadata properties. 226 Metadata properties describe how to acquire content from an upstream 227 CDN, authorize access to content, and deliver content from a 228 downstream CDN. The data model relies on the assumption that these 229 metadata properties may be aggregated based on the hostname of the 230 content and subsequently on the resource path of the content. The 231 data model associates a set of CDNI Metadata properties with a 232 Hostname to form a default set of metadata properties for content 233 delivered on behalf of that Hostname. That default set of metadata 234 properties can be overridden by properties that apply to specific 235 paths within a URI. 237 Different Hostnames and URI paths will be associated with different 238 sets of CDNI Metadata properties in order to describe the required 239 behaviour when a dCDN surrogate is processing User Agent requests for 240 content at that Hostname or URI path. As a result of this structure, 241 significant commonality may exist between the CDNI Metadata 242 properties specified for different Hostnames, different URI paths 243 within a Hostname and different URI paths on different Hostnames. 244 For example the definition of which User Agent IP addresses should be 245 treated as being grouped together into a single network or geographic 246 location is likely to be common for a number of different Hostnames. 247 Another example is that although a uCDN is likely to have several 248 different policies configured to express geo-blocking rules, it is 249 likely that a single geo-blocking policy would be applied to multiple 250 Hostnames delivered through the CDN. 252 In order to enable the CDNI Metadata for a given Hostname or URI Path 253 to be decomposed into sets of CDNI Metadata properties that can be 254 reused by multiple Hostnames and URI Paths, the CDNI Metadata 255 interface specified in this document splits the CDNI Metadata into a 256 number of objects. Efficiency is improved by enabling a single CDNI 257 Metadata object (that is shared across Hostname and/or URI paths) to 258 be retrieved by a dCDN once, even if it is referenced by the CDNI 259 Metadata of multiple Hostnames. 261 Section 3.1 introduces a high level description of the HostIndex, 262 HostMetadata and PathMetadata objects and describes the relationships 263 between those objects. 265 Section 3.2 introduces a high level description of the CDNI 266 GenericMetadata object which represents the level at which CDNI 267 Metadata override occurs between HostMetadata and PathMetadata 268 objects. 270 Section 4 describes in detail the specific CDNI Metadata objects and 271 properties which may be contained within a CDNI GenericMetadata 272 object. 274 3.1. HostIndex, HostMetadata & PathMetadata objects 276 A HostIndex object contains a list of Hostnames (and/or IP addresses) 277 for which content requests may be delegated to the downstream CDN. 278 The HostIndex is the starting point for accessing the uCDN's CDNI 279 Metadata data store. It enables surrogates in the dCDN to 280 deterministically discover, on receipt of a User Agent request for 281 content, which other CDNI Metadata objects it requires in order to 282 deliver the requested content. 284 The HostIndex links Hostnames (and/or IP addresses) to HostMetadata 285 objects via HostMatch objects. HostMetadata objects contain (or 286 reference) the default CDNI Metadata required to serve content for 287 that host. When looking up CDNI Metadata, the downstream CDN looks 288 up the requested Hostname (or IP address) in the HostIndex, from 289 there it can find HostMetadata which describes properties for a host 290 and PathMetadata which may override those properties for given URI 291 paths within the host. 293 Besides containing the default CDNI Metadata for the specified 294 Hostname, HostMetadata and PathMetadata objects may also contain 295 PathMatch objects which in turn contain PathMetadata objects. 296 PathMatch objects override the CDNI Metadata in the HostMetadata 297 object or one or more preceding PathMetadata objects with more 298 specific CDNI Metadata that applies to content requests matching the 299 pattern defined in that PathMatch object. 301 For the purposes of retrieving CDNI Metadata all other required CDNI 302 Metadata objects and their properties are discoverable from the 303 appropriate HostMetadata, PathMatch and PathMetadata objects for the 304 requested content. 306 The relationships between the HostIndex, HostMatch, HostMetadata, 307 PathMatch and PathMetadata objects are described in Figure 1. 309 +---------+ +---------+ +------------+ 310 |HostIndex+-(*)->|HostMatch|-(1)->|HostMetadata+-------(*)------+ 311 +---------+ +---------+ +------+-----+ | 312 | | 313 (*) | 314 | | 315 --> References V V 316 (1) One and only one +---------+ ************************** 317 (*) Zero or more +--->|PathMatch| *Generic Metadata Objects* 318 | +---------+ ************************** 319 | | ^ 320 (*) (1) | 321 | | | 322 | V | 323 | +------------+ | 324 +--|PathMetadata+-------(*)------+ 325 +------------+ 327 Figure 1: Relationships between the HostIndex, HostMetadata & 328 PathMetadata CDNI Metadata Objects 330 The relationships in Figure 1 are summarised in Table 1 below. 332 +--------------+----------------------------------------------------+ 333 | Data Object | Objects it References | 334 +--------------+----------------------------------------------------+ 335 | HostIndex | 0 or more HostMatch objects. | 336 | HostMatch | 1 HostMetadata object. | 337 | HostMetadata | 0 or more PathMatch objects. 0 or more | 338 | | GenericMetadata objects. | 339 | PathMatch | 1 PathMetadata object. | 340 | PathMetadata | 0 or more PathMatch objects. 0 or more | 341 | | GenericMetadata objects. | 342 +--------------+----------------------------------------------------+ 344 Table 1: Relationships between CDNI Metadata Objects 346 The table below describes the HostIndex, HostMetadata and 347 PathMetadata objects in more detail. 349 +-----------------+-------------------------------------------------+ 350 | Data Object | Description | 351 +-----------------+-------------------------------------------------+ 352 | HostIndex | A HostIndex object lists HostMatch objects | 353 | HostMatch | A HostMatch object defines a hostname to match | 354 | | against a requested host, and contains or | 355 | | references a HostMetadata object which contains | 356 | | CDNI Metadata objects to be applied when a | 357 | | request matches against the hostname. For | 358 | | example, if "example.com" is a content | 359 | | provider, a HostMatch object may include an | 360 | | entry for "example.com" with the URI of the | 361 | | associated HostMetadata object. | 362 | HostMetadata | A HostMetadata object contains (or references) | 363 | | the default CDNI Metadata objects for content | 364 | | served from that host, i.e. the CDNI Metadata | 365 | | objects for content requests that do not match | 366 | | any of the PathMatch objects contained or | 367 | | referenced by that HostMetadata object. For | 368 | | example, a HostMetadata object may describe the | 369 | | metadata properties which apply to | 370 | | "example.com" and may contain PathMatches for | 371 | | "example.com/movies/*" and | 372 | | "example.com/music/*" which reference | 373 | | corresponding PathMetadata objects that contain | 374 | | the CDNI Metadata objects for those more | 375 | | specific URI paths. | 376 | PathMatch | A PathMatch object defines a pattern to match | 377 | | against the requested URI path, and contains or | 378 | | references a PathMetadata object which contains | 379 | | (or references) the CDNI Metadata objects to be | 380 | | applied when a content request matches against | 381 | | the defined URI path pattern. For example, a | 382 | | PathMatch object may include a pattern for the | 383 | | path "/movies/*" and may reference a | 384 | | PathMetadata object which contains the CDNI | 385 | | Metadata for content with that path. | 386 | PathMetadata | A PathMetadata object contains the CDNI | 387 | | GenericMetadata objects for content served with | 388 | | the associated URI path (defined in a PathMatch | 389 | | object). A PathMetadata object may also contain | 390 | | PathMatch objects in order to recursively | 391 | | define more specific URI paths that require | 392 | | different (e.g. more specific) CDNI Metadata to | 393 | | this one. For example, the PathMetadata object | 394 | | which applies to "example.com/movies/*" may | 395 | | describe CDNI Metadata which apply to that | 396 | | resource path and may contain a PathMatch | 397 | | object for "example.com/movies/hd/*" which | 398 | | would reference the corresponding PathMetadata | 399 | | object for the "example.com/movies/hd/" path | 400 | | prefix. | 401 | GenericMetadata | A GenericMetadata object contains individual | 402 | | CDNI Metadata objects which define the specific | 403 | | policies and attributes needed to properly | 404 | | deliver the associated content. For example, a | 405 | | GenericMetadata object may describe the source | 406 | | from which a CDN may acquire a piece of | 407 | | content. | 408 +-----------------+-------------------------------------------------+ 410 Table 2: HostIndex, HostMetadata and PathMetadata CDNI Metadata 411 Objects 413 3.2. Generic CDNI Metadata Object Properties 415 The HostMetadata and PathMetadata objects contain or can reference 416 other CDNI Metadata objects that contain properties which describe 417 how User Agent requests for content should be processed, for example 418 where to acquire the content, authorization rules that should be 419 applied, delivery location restrictions and so on. Each such CDNI 420 Metadata object is a specialization of a CDNI GenericMetadata object. 421 The GenericMetadata object abstracts the basic information required 422 for Metadata override and Metadata distribution, from the specifics 423 of any given property (e.g., property semantics, enforcement options, 424 etc.). 426 The GenericMetadata object defines the type of properties contained 427 within it as well as whether or not the properties are mandatory to 428 enforce. If the dCDN does not understand or support the property 429 type and the property type is mandatory to enforce, the dCDN MUST NOT 430 serve the content to the User Agent. If the dCDN does not understand 431 or support the property type it is also not going to be able to 432 properly propagate the Metadata for cascaded distribution. If the 433 dCDN does not understand or support the property type and the 434 property type is not mandatory to enforce, then the GenericMetadata 435 object may be safely ignored. 437 Although a CDN cannot serve content to a User Agent if a mandatory 438 property cannot be enforced, it may be safe to redistribute that 439 metadata to another CDN without modification. For example, in the 440 cascaded CDN case, a transit CDN may pass through mandatory-to- 441 enforce metadata to the delivery CDN. For Metadata which does not 442 require customization, the data representation received off the wire 443 MAY be stored and redistributed without being natively understood or 444 supported by the transit CDN. However, for Metadata which require 445 translations, transparent redistribution of the uCDN Metadata values 446 may not be appropriate. Certain Metadata may be safely, though 447 possibly not optimially, redistributed unmodified, e.g., source 448 acquisition address may not be optimal if transparently 449 redistributed, but may still work. Redistribution safety MUST be 450 specified for each GenericMetadata. 452 3.3. Metadata Inheritance and Override 454 In the data model, a HostMetadata object may contain (or reference) 455 multiple PathMetadata objects (via PathMatch objects). Each 456 PathMetadata object may in turn contain (or reference) other 457 PathMetadata objects. HostMetadata and PathMetadata objects form an 458 inheritance tree where each node in the tree inherits or overrides 459 the property values set by its parent. 461 GenericMetadata objects of a given type override all GenericMetadata 462 objects of the same type previously defined by any parent object in 463 the tree. GenericMetadata objects of a given type previously defined 464 by a parent object in the tree are inherited when no object of the 465 same type is defined by the child object. For example, if 466 HostMetadata for the host "example.com" contains GenericMetadata 467 objects of type LocationACL and TimeWindowACL, while a PathMetadata 468 object which applies to "example.com/movies/*" defines an alternate 469 GenericMetadata object of type TimeWindowACL, then: 471 the TimeWindowACL defined in the PathMetadata would override the 472 TimeWindowACL defined in the HostMetadata 474 the LocationACL defined in the HostMetadata would be inherited for 475 all User Agent requests for content under "example.com/movies". 477 The PathMetadata defined TimeWindowACL would override the 478 TimeWindowACL defined in the HostMetadata for all User Agent requests 479 for movies. 481 3.4. Metadata Naming 483 GenericMetadata objects are identified by their type. The type 484 SHOULD be descriptive, and MAY be hierarchical to support aggregating 485 groups of properties for the purpose of readability and for avoiding 486 name conflicts between vendor extensions. A dotted alpha-numeric 487 notation is suggested for human readability. 489 Metadata types defined by this document are not hierarchical. 491 4. Encoding-Independent CDNI Metadata Object Descriptions 493 Section 4.1 provides the definitions of each object type declared in 494 Section 3. These objects are described as structural objects as they 495 provide the structure for the inheritance tree and identifying which 496 specific properties apply to a given User Agent content request. 498 Section 4.2 provides the definitions for the set of core metadata 499 objects which may be contained within a GenericMetadata object. 500 These objects are described as property objects as they define the 501 semantics, enforcement options, and serialization rules for specific 502 properties. These properties govern how User Agent requests for 503 content are handled. Property objects may be composed of or contain 504 references to other objects. In those cases the value of the 505 property can be either an object of that type (the object is 506 embedded) or a Link object that contains a URI and relationship that 507 can be dereferenced to retrieve the CDNI Metadata object that 508 represents the value of that property. 510 Note: In the following sections, the term "mandatory-to-specify" is 511 used to convey which objects or properties must be specified for a 512 given parent object or property. When mandatory-to-specify is set to 513 true, it implies that if the parent object is specified, then the 514 defined object or property MUST also be specified, e.g., a HostMatch 515 object without a host to match against does not make sense, 516 therefore, the host is mandatory-to-specify inside a parent HostMatch 517 object. 519 4.1. CDNI Metadata Structural Object Descriptions 521 Each of the sub-sections below describe the structural objects 522 defined in Table 2. 524 4.1.1. HostIndex 526 The HostIndex object is the entry point into the CDNI Metadata 527 hierarchy. It contains a list of HostMatch objects. An incoming 528 content request is matched against the hostname inside of each of the 529 listed HostMatch objects to find the HostMatch object which applies 530 to the request. 532 Property: hosts 534 Description: List of HostMatch objects, in priority order. 536 Type: List of HostMatch objects 538 Mandatory-to-Specify: Yes. 540 4.1.2. HostMatch 542 The HostMatch object contains a hostname or IP address to match 543 against content requests. The HostMatch object also contains a 544 reference to Metadata objects to apply if a match is found. 546 Property: host 548 Description: String (hostname or IP address) to match against 549 the requested host. 551 Type: String 553 Mandatory-to-Specify: Yes. 555 Property: host-metadata 557 Description: CDNI Metadata to apply when delivering content 558 that matches this host. 560 Type: HostMetadata 562 Mandatory-to-Specify: Yes. 564 4.1.3. HostMetadata 566 The HostMetadata object contains both Metadata that applies to 567 content requests for a particular host and a list of pattern matches 568 for finding more specific Metadata based on the resource path in a 569 content request. 571 Property: metadata 572 Description: List of host related metadata. 574 Type: List of GenericMetadata objects 576 Mandatory-to-Specify: Yes. 578 Property: paths 580 Description: Path specific rules. First match applies. 582 Type: List of PathMatch objects 584 Mandatory-to-Specify: No. 586 4.1.4. PathMatch 588 The PathMatch object contains an expression given as a PatternMatch 589 object to match against a resource URI path and Metadata objects to 590 apply if a match is found. 592 Property: path-pattern 594 Description: Pattern to match against the requested path, i.e. 595 against the [RFC3986] path-absolute. 597 Type: PatternMatch 599 Mandatory-to-Specify: Yes. 601 Property: path-metadata 603 Description: CDNI Metadata to apply when delivering content 604 that matches this pattern. 606 Type: PathMetadata 608 Mandatory-to-Specify: Yes. 610 4.1.5. PathMetadata 612 A PathMetadata object contains the CDNI Metadata properties for 613 content served with the associated URI path (defined in a PathMatch 614 object). Note that if CDNI metadata is used as an input to CDNI 615 request routing and DNS-based redirection is employed, then any 616 metadata at the PathMetadata level or below will be inaccessible at 617 request routing time. 619 Property: metadata 620 Description: List of path related metadata. 622 Type: List of GenericMetadata objects 624 Mandatory-to-Specify: Yes. 626 Property: paths 628 Description: Path specific rules. First match applies. 630 Type: List of PathMatch objects 632 Mandatory-to-Specify: No. 634 4.1.6. PatternMatch 636 A PatternMatch object contains the pattern string and flags that 637 describe the PathMatch expression. 639 Property: pattern 641 Description: A pattern for string matching. The pattern may 642 contain the wildcards * and ?, where * matches any sequence of 643 characters (including the empty string) and ? matches exactly 644 one character. The three literals \ , * and ? should be 645 escaped as \\, \* and \?. All other characters are treated as 646 literals. 648 Type: String 650 Mandatory-to-Specify: Yes. 652 Property: case-sensitive 654 Description: Flag indicating whether or not case-sensitive 655 matching should be used. 657 Type: Boolean 659 Mandatory-to-Specify: No. Default is case-insensitive match. 661 Property: ignore-query-string 663 Description: List of query parameters which should be ignored 664 when searching for a pattern match. If all query parameters 665 should be ignored then the list MUST be empty. 667 Type: List of String 668 Mandatory-to-Specify: No. Default is to include query strings 669 when matching. 671 4.1.7. GenericMetadata 673 A GenericMetadata object is a abstraction for managing individual 674 CDNI Metadata properties in an opaque manner. 676 Property: type 678 Description: CDNI Metadata property object type. 680 Type: String 682 Mandatory-to-Specify: Yes. 684 Property: value 686 Description: CDNI Metadata property object. 688 Type: matches the type property above 690 Mandatory-to-Specify: Yes. 692 Property: mandatory-to-enforce 694 Description: Flag identifying whether or not the enforcement of 695 the property Metadata is required. 697 Type: Boolean 699 Mandatory-to-Specify: No. Default is to treat metadata as 700 mandatory to enforce. 702 Property: safe-to-redistribute 704 Description: Flag identifying whether or not the property 705 Metadata may be safely redistributed without modification. 707 Type: Boolean 709 Mandatory-to-Specify: No. Default is allow transparent 710 redistribution. 712 4.2. CDNI Metadata Property Object Descriptions 714 The property objects defined below are intended to be used in the 715 GenericMetadata object value field as defined in Section 4.1.7. All 716 of the objects defined below are considered both mandatory to enforce 717 and safe to redistribute. 719 4.2.1. Source Metadata 721 Source Metadata provides the dCDN information about content 722 acquisition e.g. how to contact an uCDN Surrogate or an Origin Server 723 to obtain the content to be served. The sources are not necessarily 724 the actual Origin Servers operated by the CSP but might be a set of 725 Surrogates in the uCDN. 727 Property: sources 729 Description: Sources from which the dCDN can acquire content, 730 listed in priority order. 732 Type: List of Source objects 734 Mandatory-to-Specify: No. Default is to use static 735 configuration, out of band of the metadata interface. 737 4.2.1.1. Source 739 A Source object describes the Source which should be used by the dCDN 740 for content acquisition, e.g. a Surrogate within the uCDN or an 741 alternate Origin Server, the protocol to be used and any 742 authentication method. 744 Property: auth 746 Description: Authentication method to use when requesting 747 content from this source. 749 Type: Auth 751 Mandatory-to-Specify: No. Default is no authentication is 752 required. 754 Property: endpoints 756 Description: Origins from which the dCDN can acquire content. 758 Type: List of EndPoint objects 759 Mandatory-to-Specify: Yes. 761 Property: protocol 763 Description: Network retrieval protocol to use when requesting 764 content from this source. 766 Type: Protocol 768 Mandatory-to-Specify: Yes. 770 4.2.2. LocationACL Metadata 772 LocationACL Metadata defines location-based restrictions. 774 Property: locations 776 Description: Access control list which applies restrictions to 777 delivery based on client location. 779 Type: List of LocationRule objects 781 Mandatory-to-Specify: No. Default is allow all locations. 783 4.2.2.1. LocationRule 785 A LocationRule contains or references a list of Footprint objects and 786 the corresponding action. 788 Property: footprints 790 Description: List of footprints to which the rule applies. 792 Type: List of Footprint objects 794 Mandatory-to-Specify: Yes. 796 Property: action 798 Description: Defines whether the rule specifies locations to 799 allow or deny. 801 Type: Enumeration [allow|deny] 803 Mandatory-to-Specify: No. Default is deny. 805 4.2.2.2. Footprint 807 A Footprint object describes the footprint to which a LocationRule 808 may be applied by, e.g. an IPv4 address range or a geographic 809 location. 811 Property: type 813 Description: Registered footprint type (see Section 7.1.1.1). 815 Type: String 817 Mandatory-to-Specify: Yes. 819 Property: value 821 Description: Footprint object conforming to the specification 822 associated with the registered footprint type. 824 Type: String 826 Mandatory-to-Specify: Yes. 828 4.2.3. TimeWindowACL Metadata 830 TimeWindowACL Metadata defines time-based restrictions. 832 Property: times 834 Description: Access control list which applies restrictions to 835 delivery based on request time. 837 Type: List of TimeWindowRule objects 839 Mandatory-to-Specify: No. Default is allow all time windows. 841 4.2.3.1. TimeWindowRule 843 A TimeWindowRule contains or references a list of TimeWindow objects 844 and the corresponding action. 846 Property: times 848 Description: List of time windows to which the rule applies. 850 Type: List of TimeWindow objects 852 Mandatory-to-Specify: Yes. 854 Property: action 856 Description: Defines whether the rule specifies time windows to 857 allow or deny. 859 Type: Enumeration [allow|deny] 861 Mandatory-to-Specify: No. Default is deny. 863 4.2.3.2. TimeWindow 865 A TimeWindow object describes a time range which may be applied by an 866 ACLRule, e.g. Start 09:00AM 01/01/2000 UTC End 17:00PM 01/01/2000 867 UTC. 869 Property: start 871 Description: The start time of the window. 873 Type: Time 875 Mandatory-to-Specify: Yes. 877 Property: end 879 Description: The end time of the window. 881 Type: Time 883 Mandatory-to-Specify: Yes. 885 4.2.4. ProtocolACL Metadata 887 ProtocolACL Metadata defines delivery protocol restrictions. 889 Property: protocols 891 Description: Access control list which applies restrictions to 892 delivery based on delivery protocol. 894 Type: List of ProtocolRule objects 896 Mandatory-to-Specify: No. Default is allow all protocols. 898 4.2.4.1. ProtocolRule 900 A ProtocolRule contains or references a list of Protocol objects. 901 ProtocolRule objects are used to construct a ProtocolACL to apply 902 restrictions to content acquisition or delivery. 904 Property: protocols 906 Description: List of protocols to which the rule applies. 908 Type: List of protocol objects 910 Mandatory-to-Specify: Yes. 912 Property: action 914 Description: Defines whether the rule specifies protocols to 915 allow or deny. 917 Type: Enumeration [allow|deny]+ 919 Mandatory-to-Specify: No. Default is allow all protocols. 921 Property: direction 923 Description: Defines whether the ProtocolRule specifies 924 protocols for acquisition or delivery. 926 Type: Enumeration [acquisition|delivery] 928 Mandatory-to-Specify: No. Default is to apply the rule to both 929 acquisition and delivery. 931 4.2.5. Authorization Metadata 933 Authorization Metadata define content authorization methods. 935 Property: methods 937 Description: Options for authenticating content requests. All 938 options in the list are equally valid. 940 Type: List of Auth objects 942 Mandatory-to-Specify: No. Default is no authorization 943 required. 945 4.2.6. Auth 947 An Auth object defines authentication and authorization methods to be 948 used during content delivery and content acquisition. 950 Property: type 952 Description: Registered Auth type (see Section 7.1.1.3). 954 Type: String 956 Mandatory-to-Specify: Yes. 958 Property: value 960 Description: Auth object conforming to the specification 961 associated with the registered Auth type. 963 Type: String 965 Mandatory-to-Specify: Yes. 967 4.2.6.1. Credentials Auth Type 969 Credentials Auth is a type of Auth object with type "credentials" 970 (see Section 7.1.1.3). The CredentialsAuth object contains the 971 following properties: 973 Property: username 975 Description: Identification of user. 977 Type: String 979 Mandatory-to-Specify: Yes. 981 Property: password 983 Description: Password for user identified by username property. 985 Type: String 987 Mandatory-to-Specify: Yes. 989 4.2.7. Cache 991 A Cache object describes the cache control parameters to be applied 992 to the content by intermediate caches. 994 Property: ignore-query-string 996 Description: Allows a cache to ignore URI query string 997 parameters while comparing URIs for equivalence. Each query 998 parameter to ignore is specified in the list. If all query 999 parameters should be ignored, then the list MUST be empty. 1001 Type: List of String 1003 Mandatory-to-Specify: No. Default is to consider query string 1004 parameters when comparing URIs or to rely on other properties 1005 of the Cache object. 1007 4.2.8. Grouping 1009 A Grouping object identifies a large group of content to which this 1010 content belongs. 1012 Property: ccid 1014 Description: Content Collection identifier for an application- 1015 specific purpose such as logging. 1017 Type: String 1019 Mandatory-to-Specify: No. Default is an empty string. 1021 Property: sid 1023 Description: Session identifier for an application-specific 1024 purpose such as logging. 1026 Type: String 1028 Mandatory-to-Specify: No. Default is an empty string. 1030 4.3. CDNI Metadata Simple Data Type Descriptions 1032 This section describes the simpler data types that are used for 1033 properties of CDNI Metadata objects. 1035 4.3.1. Link 1037 A link object may be used in place of any of the objects or 1038 properties described above. Links can be used to avoid duplication 1039 if the same metadata information is repeated within the metadata 1040 tree. When a link replaces an object, its href property is set to 1041 the URI of the resource and its type property is set to the type of 1042 the object it is replacing. 1044 Property: href 1046 Description: The URI of the of the addressable object being 1047 referenced. 1049 Type: URI 1051 Mandatory-to-Specify: Yes 1053 Property: type 1055 Description: The type of the object being referenced. 1057 Type: String 1059 Mandatory-to-Specify: No 1061 4.3.2. Protocol 1063 Protocol objects are used to specify registered protocols for content 1064 acquisition or delivery (see Section 7.1.1.2). 1066 Type: String 1068 Mandatory-to-Specify: Yes 1070 4.3.3. Endpoint 1072 A hostname (with optional port) or an IP address (with optional 1073 port). 1075 Note: All implementations MUST support IPv4 addresses encoded as 1076 specified by the 'IPv4address' rule in Section 3.2.2 of [RFC3986] and 1077 MUST support all IPv6 address formats specified in [RFC4291]. Server 1078 implementations SHOULD use IPv6 address formats specified in 1079 [RFC5952]. 1081 4.3.4. URI 1083 A URI as specified in [RFC3986]. 1085 4.3.5. Time 1087 A time value expressed in seconds since Unix epoch in the UTC 1088 timezone. 1090 5. CDNI Metadata Capabilities 1092 CDNI Metadata is used to convey information pertaining to content 1093 delivery from uCDN to dCDN. For optional metadata, it may be useful 1094 for the uCDN to know if the dCDN supports the metadata, prior to 1095 delegating any content requests to the dCDN. If optional-to- 1096 implement metadata is mandatory-to-enforce and the dCDN does not 1097 support it, any delegated requests for that content will fail, so 1098 there is no reason to delegate those requests. Likewise, for any 1099 metadata which may be assigned optional values, it may be useful for 1100 the uCDN to know which values the dCDN supports, prior to delegating 1101 any content requests to the dCDN. If a the optional value assigned 1102 to a given piece of content's metadata is not supported by the dCDN, 1103 any delegated requests for that content may fail, so there is likely 1104 no reason to delegate those requests. 1106 The CDNI Footprint and Capabilities Interface provides a means of 1107 advertising capabilities from dCDN to uCDN. Support for optional 1108 metadata and support for optional metadata values may be advertised 1109 using the capabilities interface. This section describes the 1110 capabilities advertisement requirements for the metadata defined in 1111 Section 4.2 1113 5.1. Protocol ACL Capabilities 1115 The ProtoclACL object contains a list of Protocol values. The dCDN 1116 MUST advertise which delivery protocols it supports so that the uCDN 1117 knows what type of content requests it can redirect to the dCDN. If 1118 the dCDN does not support a given acquisition or delivery protocol, 1119 the uCDN should not delegate requests requiring those protocols to 1120 the dCDN as the dCDN will not be able to properly acquire or deliver 1121 the content. 1123 ProtocolRules are defined for either acquisition or delivery. For 1124 some CDNs, certain combinations of acquisition and delivery protocols 1125 may not make sense (e.g., RTSP acquisition for HTTP delivery), while 1126 other CDNs may support customized protocol adaptation. ProtocolACL 1127 capabilities are not intended to define which combinations of 1128 protocols should be used. ProtocolACL capabilties are only intended 1129 to describe which protocols the dCDN does or does not support. 1130 Protocol combination restrictions are specified in the metadata 1131 itself and associated with specific groups of content assets. 1133 5.2. Authorization Metadata Capabilities 1135 The Authorization object contains a list of Auth values. The dCDN 1136 MUST advertise which authorization algorithms it supports so that the 1137 uCDN knows what type of content requests it can redirect to the dCDN. 1138 If the dCDN does not support a given authorization algorithm, the 1139 uCDN should not delegate requests requiring that algorithm to the 1140 dCDN as the dCDN will not be able to properly acquire the content or 1141 enforce delivery restrictions. 1143 6. CDNI Metadata interface 1145 This section specifies an interface to enable a Downstream CDN to 1146 retrieve CDNI Metadata objects from an Upstream CDN. 1148 The interface can be used by a Downstream CDN to retrieve CDNI 1149 Metadata objects either dynamically as required by the Downstream CDN 1150 to process received requests (for example in response to receiving a 1151 CDNI Request Routing request from an Upstream CDN or in response to 1152 receiving a request for content from a User Agent) or in advance of 1153 being required (for example in case of prepositioned CDNI Metadata 1154 acquisition). 1156 The CDNI Metadata interface is built on the principles of RESTful web 1157 services. This means that requests and responses over the interface 1158 are built around the transfer of representations of hyperlinked 1159 resources. A resource in the context of the CDNI Metadata interface 1160 is any object in the Data Model (as described in Section 3 through 1161 Section 4). 1163 In the general case a CDNI Metadata server makes each instance of an 1164 addressable CDNI Metadata object available via a unique URI that 1165 returns a representation of that instance of that CDNI Metadata 1166 object. When an object needs to reference another addressable CDNI 1167 Metadata object (for example a HostIndex object referencing a 1168 HostMetadata object) it does so by including a link to the referenced 1169 object. 1171 CDNI Metadata servers are free to assign whatever structure they 1172 desire to the URIs for CDNI Metadata objects and CDNI Metadata 1173 clients MUST NOT make any assumptions regarding the structure of CDNI 1174 Metadata URIs or the mapping between CDNI Metadata objects and their 1175 associated URIs. Therefore any URIs present in the examples below 1176 are purely illustrative and are not intended to impose a definitive 1177 structure on CDNI Metadata interface implementations. 1179 6.1. Transport 1181 The CDNI Metadata interface uses HTTP as the underlying protocol 1182 transport. 1184 The HTTP Method in the request defines the operation the request 1185 would like to perform. Servers implementing the CDNI Metadata 1186 interface MUST support the HTTP GET and HEAD methods. 1188 The corresponding HTTP Response returns the status of the operation 1189 in the HTTP Status Code and returns the current representation of the 1190 resource (if appropriate) in the Response Body. HTTP Responses from 1191 servers implementing the CDNI Metadata interface that contain a 1192 response body SHOULD include an ETag to enable validation of cached 1193 versions of returned resources. 1195 The CDNI Metadata interface specified in this document is a read-only 1196 interface. Therefore support for other HTTP methods such as PUT, 1197 POST and DELETE etc. is not specified. Server implementations of 1198 this interface SHOULD reject all methods other than GET and HEAD. 1200 As the CDNI Metadata interface builds on top of HTTP, CDNI Metadata 1201 servers may make use of any HTTP feature when implementing the CDNI 1202 Metadata interface, for example a CDNI Metadata server may make use 1203 of HTTP's caching mechanisms to indicate that the returned response/ 1204 representation can be reused without re-contacting the CDNI Metadata 1205 server. 1207 6.2. Retrieval of CDNI Metadata resources 1209 In the general case a CDNI Metadata server makes each instance of an 1210 addressable CDNI Metadata object available via a unique URI and 1211 therefore in order to retrieve CDNI Metadata, a CDNI Metadata client 1212 first makes a HTTP GET request for the URI of the HostIndex which 1213 provides the CDNI Metadata client with a list of Hostnames for which 1214 the upstream CDN may delegate content delivery to the downstream CDN. 1216 In order to retrieve the CDNI Metadata for a particular request the 1217 CDNI Metadata client processes the received HostIndex object and 1218 finds the corresponding HostMetadata entry (by matching the hostname 1219 in the request against the hostnames in the HostMatch). If the 1220 HostMetadata is linked (rather than embedded), the CDNI metadata 1221 client then makes a GET request for the URI specified in the href 1222 property of the Link object which points to the HostMetadata object 1223 itself. 1225 In order to retrieve the most specific metadata for a particular 1226 request, the CDNI metadata client inspects the HostMetadata for 1227 references to more specific PathMetadata objects. If any 1228 PathMetadata match the request (and are linked rather than embedded), 1229 the CDNI metadata client makes another GET request for the 1230 PathMetadata. Each PathMetadata object may also include references 1231 to yet more specific metadata. If this is the case, the CDNI 1232 metadata client continues requesting PathMetadata recursively. 1234 Where a downstream CDN is interconnected with multiple upstream CDNs, 1235 the downstream CDN must decide which upstream CDN's CDNI metadata 1236 should be used to handle a particular User Agent request. 1238 When application level redirection (e.g. HTTP 302 redirects) is being 1239 used between CDNs, it is expected that the downstream CDN will be 1240 able to determine the upstream CDN that redirected a particular 1241 request from information contained in the received request (e.g. via 1242 the URI). With knowledge of which upstream CDN routed the request, 1243 the downstream CDN can choose the correct metadata server from which 1244 to obtain the HostIndex. Note that the HostIndex served by each uCDN 1245 may be unique. 1247 In the case of DNS redirection there is not always sufficient 1248 information carried in the DNS request from User Agents to determine 1249 the upstream CDN that redirected a particular request (e.g. when 1250 content from a given host is redirected to a given downstream CDN by 1251 more than one upstream CDN) and therefore downstream CDNs may have to 1252 apply local policy when deciding which upstream CDN's metadata to 1253 apply. 1255 6.3. Bootstrapping 1257 The URI for the HostIndex object of a given upstream CDN needs to be 1258 either discovered by or configured in the downstream CDN. All other 1259 objects/resources are then discoverable from the HostIndex object by 1260 following the links in the HostIndex object and the referenced 1261 HostMetadata and PathMetadata objects. 1263 If the URI for the HostIndex object is not manually configured in the 1264 downstream CDN then the HostIndex URI could be discovered. A 1265 mechanism allowing the downstream CDN to discover the URI of the 1266 HostIndex is outside the scope of this document. 1268 6.4. Encoding 1270 Object are resources that may be: 1272 o Addressable, where the object is a resource that may be retrieved 1273 or referenced via its own URI. 1275 o Embedded, where the object is contained (or inlined) within a 1276 property of an addressable object. 1278 In the descriptions of objects we use the term "X contains Y" to mean 1279 either Y is directly embedded in X or that Y is linked to by X. It 1280 is generally a deployment choice for the uCDN implementation to 1281 decide when and which CDNI Metadata objects to embed and which are 1282 separately addressable. 1284 6.4.1. MIME Media Types 1286 All MIME types are prefixed with "application/cdni." The MIME type 1287 for each object matches the type name of that object as defined by 1288 this document. The object type name is followed by ".v" and the 1289 version number of the object type (e.g. ".v1"). Finally, the 1290 encoding type "+json" is appended. Table 3 lists a few examples of 1291 the MIME Media Type for each object (resource) that is retrievable 1292 through the CDNI Metadata interface. 1294 +--------------+---------------------------------------+ 1295 | Data Object | MIME Media Type | 1296 +--------------+---------------------------------------+ 1297 | HostIndex | application/cdni.HostIndex.v1+json | 1298 | HostMatch | application/cdni.HostMatch.v1+json | 1299 | HostMetadata | application/cdni.HostMetadata.v1+json | 1300 | PathMatch | application/cdni.PathMatch.v1+json | 1301 | PathMetadata | application/cdni.PathMetadata.v1+json | 1302 | Source | application/cdni.Source.v1+json | 1303 | LocationACL | application/cdni.LocationACL.v1+json | 1304 | LocationRule | application/cdni.LocationRule.v1+json | 1305 +--------------+---------------------------------------+ 1307 Table 3: Example MIME Media Types for CDNI Metadata objects 1309 See http://www.iana.org/assignments/media-types/index.html for 1310 reference. 1312 6.4.2. JSON Encoding of Objects 1314 CDNI Metadata objects are encoded as JSON objects containing a 1315 dictionary of (key,value) pairs where the keys are the property names 1316 and the values are the associated property values. 1318 The keys of the dictionary are the names of the properties associated 1319 with the object and are therefore dependent on the specific object 1320 being encoded (i.e. dependent on the MIME Media Type of the returned 1321 resource). Likewise, the values associated with each key are 1322 dependent on the specific object being encoded (i.e. dependent on 1323 the MIME Media Type of the returned resource). 1325 Dictionary keys in JSON are case sensitive and therefore by 1326 convention any dictionary key defined by this document (for example 1327 the names of CDNI Metadata object properties) MUST be represented in 1328 lowercase. 1330 In addition to the properties specific to each object type, the keys 1331 defined below may be present in any object. 1333 Key: base 1335 Description: Provides a prefix for any relative URLs in the 1336 object. This is similar to the XML base tag [XML-BASE]. If 1337 absent, all URLs in the remainder of the document must be 1338 absolute URLs. 1340 Type: URI 1342 Mandatory: No 1344 Key: _links 1346 Description: The links of this object to other addressable 1347 objects. Any property may be replaced by a link to an object 1348 with the same type as the property it replaces. The keys of 1349 the _links dictionary are the names of the properties being 1350 replaced. The values of the dictionary are Link objects with 1351 href set to the URI of the object and type set to the MIME type 1352 of the object being replaced. 1354 Type: Dictionary object of Link objects 1356 Mandatory: Yes 1358 6.4.2.1. JSON Example 1360 A downstream CDN may request the HostIndex and receive the following 1361 object of type "application/cdni.HostIndex.v1+json": 1363 { 1364 "hosts": [ 1365 { 1366 "host": "video.example.com", 1367 "_links": { 1368 "host-metadata" : { 1369 "type": "application/cdni.HostMetadata.v1+json", 1370 "href": "http://metadata.example.ucdn.com/video" 1371 } 1372 } 1373 }, 1374 { 1375 "host": "images.example.com", 1376 "_links": { 1377 "host-metadata" : { 1378 "type": "application/cdni.HostMetadata.v1+json", 1379 "href": "http://metadata.example.ucdn.com/images" 1380 } 1381 } 1382 } 1383 ] 1384 } 1386 If the incoming request has a Host header with "video.example.com" 1387 then the downstream CDN would fetch the next metadata object from 1388 "http://metadata.ucdn.example.com/video" expecting a MIME type of 1389 "application/cdni.HostMetadata.v1+json": 1391 { 1392 "metadata": [ 1393 { 1394 "type": "application/cdni.SourceMetadata.v1+json", 1395 "value": { 1396 "sources": [ 1397 { 1398 "_links": { 1399 "auth": { 1400 "type": "application/cdni.Auth.v1+json", 1401 "href": "http://metadata.ucdn.example.com/auth1234" 1402 } 1403 }, 1404 "endpoint": "acq1.ucdn.example.com", 1405 "protocol": "ftp" 1406 }, 1407 { 1408 "_links": { 1409 "auth": { 1410 "type": "application/cdni.Auth.v1+json", 1411 "href": "http://metadata.ucdn.example.com/auth1234" 1412 } 1413 }, 1414 "endpoint": "acq2.ucdn.example.com", 1415 "protocol": "http" 1416 } 1417 ] 1418 } 1419 }, 1420 { 1421 "type": "application/cdni.LocationACL.v1+json", 1422 "value": { 1423 "locations": [ 1424 { 1425 "locations": [ 1426 { "iprange": "192.168.0.0/16" } 1427 ], 1428 "action": "deny" 1429 } 1430 ] 1431 } 1432 }, 1433 { 1434 "type": "application/cdni.ProtocolACL.v1+json", 1435 "value": { 1436 "protocols": [ 1437 { 1438 "protocols": [ 1439 "ftp" 1440 ], 1441 "action": "deny" 1442 } 1443 ] 1444 } 1445 } 1446 ], 1447 "paths": [ 1448 { 1449 "path-pattern": { 1450 "pattern": "/videos/trailers/*" 1451 }, 1452 "_links": { 1453 "path-metadata": { 1454 "type": "application/cdni.PathMetadata.v1+json", 1455 "href": "http://metadata.ucdn.example.com/videos/trailers" 1456 } 1457 } 1458 }, 1459 { 1460 "path-pattern": { 1461 "pattern": "/videos/movies/*" 1462 }, 1463 "_links": { 1464 "pathmetadata": { 1465 "type": "application/cdni.PathMetadata.v1+json", 1466 "href": "http://metadata.ucdn.example.com/videos/movies" 1467 } 1468 } 1469 } 1470 ] 1471 } 1473 Suppose the path of the requested resource matches the "/video/movies 1474 /*" pattern, the next metadata requested would be for "http:// 1475 metadata.ucdn.example.com/video/movies" with an expected type of 1476 "application/cdni.PathMetadata.v1+json": 1478 { 1479 "metadata": [], 1480 "paths": [ 1481 { 1482 "path-pattern": { 1483 "pattern": "/videos/movies/hd/*" 1484 }, 1485 "_links": { 1486 "pathmetadata": { 1487 "type": "application/cdni.PathMetadata.v1+json", 1488 "href": "http://metadata.ucdn.example.com/videos/movies/hd" 1489 } 1490 } 1491 } 1492 ] 1493 } 1495 Finally, if the path of the requested resource also matches the "/ 1496 videos/movies/hd/*" pattern, the downstream CDN would also fetch the 1497 following object from "http://metadata.ucdn.example.com/videos/movies 1498 /hd" with MIME type "application/cdni.PathMetadata.v1+json": 1500 { 1501 "metadata": [ 1502 { 1503 "type": "application/cdni.TimeWindowACL.v1+json", 1504 "value": { 1505 "times": [ 1506 "times": [ 1507 { 1508 "start": "1213948800", 1509 "end": "1327393200" 1510 } 1511 ], 1512 "type": "allow" 1513 ] 1514 } 1515 } 1516 ] 1517 } 1519 6.5. Extensibility 1521 The set of property Metadata may be extended with proprietary and/or 1522 custom property Metadata. The GenericMetadata object defined in 1523 Section 4.1.7 allows any Metadata property to be included in either 1524 the HostMetadata or PathMetadata lists. 1526 Note: Identification of the property Metadata defining organization 1527 in the property Metadata type decreases the possibility of property 1528 Metadata type collision. The fully-qualified domain name of the 1529 organization in reverse order may be used for this purpose. 1531 6.5.1. Metadata Enforcement 1533 At any given time, the set of property Metadata supported by the uCDN 1534 may not match the set of property Metadata supported by the dCDN. 1535 The uCDN may or may not know which property Metadata the dCDN 1536 supports. In cases where the uCDN supports Metadata that the dCDN 1537 does not, the dCDN MUST be aware of any Metadata marked as 1538 "mandatory-to-enforce". If a CDN does not understand or is unable to 1539 perform the functions associated with any "mandatory-to-enforce" 1540 Metadata, the CDN MUST NOT service any requests for the corresponding 1541 content. 1543 Any standard which defines a new GenericMetadata Type MUST also 1544 define whether or not the new metadata is mandatory-to-enforce. 1546 Note: Ideally, uCDNs would not delegate content requests to a dCDN 1547 which does not support the mandatory-to-enforce Metadata associated 1548 with the content being requested. However, even if the uCDN has a 1549 priori knowledge of the Metadata supported by the dCDN (e.g., via the 1550 CDNI capabilities interface or through out-of-band negotiation 1551 between CDN operators) Metadata support may fluctuate or be 1552 inconsistent (e.g., due to mis-communication, mis-configuration, or 1553 temporary outage). Thus, the dCDN MUST evaluate all Metadata 1554 associated with content requests and reject any requests where 1555 "mandatory-to-enforce" Metadata associated with the content cannot be 1556 enforced. 1558 6.5.2. Metadata Override 1560 It is possible that new Metadata definitions may obsolete or override 1561 existing property Metadata (e.g., a future revision of the CDNI 1562 Metadata interface may redefine the Auth Metadata or a custom vendor 1563 extension may implement an alternate Auth Metadata option). If 1564 multiple Metadata (e.g., cdni.v2.Auth, vendor1.Auth, and 1565 vendor2.Auth) all override an existing Metadata (e.g., cdni.Auth) and 1566 all are marked as "mandatory-to-enforce", it may be ambiguous which 1567 Metadata should be applied, especially if the functionality of the 1568 Metadata conflict. 1570 As described in Section 3.3, Metadata override only applies to 1571 Metadata objects of the same exact type, found in HostMetadata and 1572 nested PathMetadata structures. The CDNI Metadata interface does not 1573 support enforcement of dependencies between different Metadata types. 1574 It is the responsibility of the CSP and the CDN operators to ensure 1575 that Metadata assigned to a given content do not conflict. 1577 Note: Because Metadata is inherently ordered in GenericMetadata 1578 lists, as well as in the PathMetadata hierarchy and PathMatch lists, 1579 multiple conflicting Metadata types MAY be used, however, Metadata 1580 hierarchies MUST ensure that independent PathMatch root objects are 1581 used to prevent ambiguous or conflicting Metadata definitions. 1583 6.6. Versioning 1585 The version of CDNI Metadata Structural objects is specified by the 1586 HTTP Content-Type header. Upon responding to a request for an 1587 object, a metadata server MUST include a Content-Type header with the 1588 MIME-type and version number of the object. HTTP requests sent to a 1589 metadata server SHOULD include an Accept header with the MIME-type 1590 and version of the expected object. Unless stated otherwise, the 1591 version of each object defined by this document is version 1. For 1592 example: "Content-Type: application/cdni.HostIndex.v1+json". 1594 GenericMetadata objects include a "type" property which specifies the 1595 MIME-type of the GenericMetadata value. This MIME-type should also 1596 include a version. Any document which defines a new type of 1597 GenericMetadata should specify the version number which it describes. 1598 For example: "application/cdni.Location.v1+json". 1600 7. IANA Considerations 1602 This document requests the registration of the prefix "application/ 1603 cdni" MIME Media Type under the IANA MIME Media Type registry (http:/ 1604 /www.iana.org/assignments/media-types/index.html). 1606 7.1. GenericMetadata Type Registry 1608 CDNI Metadata is distributed as a list of GenericMetadata objects 1609 which specify a type field and a type-specific value field, as 1610 described in Section 4.1.7. In order to prevent namespace collisions 1611 for GenericMetadata object types a new IANA registry is requested for 1612 "CDNI GenericMetadata Types" namespace. The namespace shall be split 1613 into two partitions: standard and optional. 1615 The standard namespace partition is intended to contain mandatory to 1616 implement capabilities and conforms to the "IETF Review" policy as 1617 defined in [RFC5226]. The registry contains the generic metadata 1618 type name, the RFC number of the specification defining the metadata 1619 type, the version number of the GenericMetadata set to which the 1620 standard capability applies, and boolean values indicating whether or 1621 not the new type is considered mandatory-to-enforce or safe-to- 1622 redistribute (as defined in Section 4.1.7). 1624 The following table defines the initial values for the standard 1625 partition: 1627 +----------------+---------------+---------+------+------+ 1628 | Type name | Specification | Version | MTE | STR | 1629 +----------------+---------------+---------+------+------+ 1630 | SourceMetadata | RFCthis | 1 | true | true | 1631 | LocationACL | RFCthis | 1 | true | true | 1632 | TimeWindowACL | RFCthis | 1 | true | true | 1633 | ProtocolACL | RFCthis | 1 | true | true | 1634 | Auth | RFCthis | 1 | true | true | 1635 | Cache | RFCthis | 1 | true | true | 1636 | Grouping | RFCthis | 1 | true | true | 1637 +----------------+---------------+---------+------+------+ 1639 The initial MI version number is set to 1. All of the initial 1640 GenericMetadata types are considered mandatory to implement for 1641 version 1. The version field should be incremented when new 1642 GenericMetadata type sets are added to the registry. 1644 The "optional" namespace partition conforms to the "Expert Review" 1645 policy as defined in [RFC5226]. The expert review is intended to 1646 prevent namespace hoarding and to prevent the definition of redundant 1647 GenericMetadata types. Vendors defining new GenericMetadata types 1648 which conflict with existing GenericMetadata types follow the 1649 guidelines for the "Specification Required" policy as defined in 1650 [RFC5226]. The Version field in the registry is set to "-1" 1651 (negative one) for non-standard GenericMetadata types. 1653 As with the initial GenericMetadata types defined in Section 4.2, 1654 future GenericMetadata type registrations will specify the 1655 information necessary for constructing and decoding the 1656 GenericMetadata object. This information includes the list of 1657 properties contained within the GenericMetadata object, and for each 1658 property, the specification should include a description, a type, and 1659 whether or not the given property is mandatory to specify. 1661 Any document which defines a new GenericMetadata type MUST: 1663 1. Allocate a new type in the GenericMetadata Type Registry 1664 (Section 7). 1666 2. Define the set of properties associated with the new type. 1668 3. For each property, define a name, description, type, and whether 1669 or not the property is mandatory-to-specify. 1671 4. Specify whether or not the new type is mandatory-to-enforce (vs 1672 optional-to-enforce). 1674 5. Describe the semantics of the new type including its purpose and 1675 example of a use case to which it applies. 1677 7.1.1. GenericMetadata Sub-Registries 1679 Some of the initial standard GenericMetadata objects contain 1680 enumerated types which require registration (i.e., LocationACL 1681 footprint types, ProtocolACL protocols, and Auth protocols). The 1682 following sections define the initial values for these 1683 GenericMetadata type sub-registries. 1685 7.1.1.1. Footprint Sub-Registry 1687 The "CDNI Metadata Footprint Types" namespace defines the valid 1688 Footprint object type values used by the Footprint object in 1689 Section 4.2.2.2. Additions to the Footprint type namespace conform 1690 to the "Expert Review" policy as defined in [RFC5226]. The expert 1691 review should verify that new type definitions do not duplicate 1692 existing type definitions and prevent gratuitous additions to the 1693 namespace. 1695 The following table defines the initial Footprint type values: 1697 +-------------+-------------------------------------+---------------+ 1698 | Type name | Description | Specification | 1699 +-------------+-------------------------------------+---------------+ 1700 | IPv4 | Single IPv4 address | RFCthis | 1701 | IPv6 | Single IPv6 address | RFCthis | 1702 | IPv4Range | List of contiguous IPv4 addresses | RFCthis | 1703 | | denoted by a start address and an | | 1704 | | end address separated by a dash | | 1705 | | (e.g., 192.168.0.1-192.168.0.20), | | 1706 | | inclusive. | | 1707 | IPv6Range | List of contiguous IPv6 addresses | RFCthis | 1708 | | denoted by a start address and an | | 1709 | | end address separated by a dash | | 1710 | | (e.g., fc80::0001-fc80::0014), | | 1711 | | inclusive. | | 1712 | IPv4CIDR | IPv4 address block using slash | RFCthis | 1713 | | prefix length notation (e.g., | | 1714 | | 192.168.0.16/28). | | 1715 | IPv6CIDR | IPv6 address block using slash | RFCthis | 1716 | | prefix length notation (e.g., | | 1717 | | fc80::0010/124). | | 1718 | ASN | Autonomous System (AS) Number | RFCthis | 1719 | CountryCode | ISO 3166-1 alpha-2 code | RFCthis | 1720 | DVDRegion | DVD Region code (i.e., integer in | RFCthis | 1721 | | the range 0-6). | | 1722 +-------------+-------------------------------------+---------------+ 1724 7.1.1.2. Protocol Sub-Registry 1726 The "CDNI Metadata Protocols" namespace defines the valid Protocol 1727 object values in Section 4.3.2, used by the SourceMetadata and 1728 ProtocolACL objects. Additions to the Protocol namespace conform to 1729 the "Expert Review" policy as defined in [RFC5226]. The expert 1730 review should verify that new type definitions do not duplicate 1731 existing type definitions and prevent gratuitous additions to the 1732 namespace. 1734 The following table defines the initial Protocol values: 1736 +----------+----------------+---------------------------------------+ 1737 | Protocol | Description | Specification | 1738 +----------+----------------+---------------------------------------+ 1739 | HTTP | Hypertext | RFC2616 | 1740 | | Transfer | | 1741 | | Protocol -- | | 1742 | | HTTP/1.1 | | 1743 | HTTPS | HTTP Over TLS | RFC2818 | 1744 | RTSP | Real Time | RFC2326 | 1745 | | Streaming | | 1746 | | Protocol | | 1747 | RTMP | Real-Time | http://www.adobe.com/devnet/rtmp.html | 1748 | | Messaging | | 1749 | | Protocol | | 1750 | FTP | FILE TRANSFER | RFC959 | 1751 | | PROTOCOL | | 1752 | SFTP | SSH File | N/A | 1753 | | Transfer | | 1754 | | Protocol | | 1755 | SCP | Secure Copy | N/A | 1756 | fasp | Aspera fast, | N/A | 1757 | | adaptive, | | 1758 | | secure | | 1759 | | protocol | | 1760 +----------+----------------+---------------------------------------+ 1762 7.1.1.3. Authentication Sub-Registry 1764 The "CDNI Metadata Auth" namespace defines the valid Auth object 1765 types used by the Auth object in Section 4.2.6. Additions to the 1766 Auth namespace conform to the "Expert Review" policy as defined in 1767 [RFC5226]. The expert review should verify that new type definitions 1768 do not duplicate existing type definitions and prevent gratuitous 1769 additions to the namespace. 1771 The following table defines the initial Auth type values: 1773 +-------------+-------------------------------------+---------------+ 1774 | Type name | Description | Specification | 1775 +-------------+-------------------------------------+---------------+ 1776 | credentials | Simple username and password | RFCthis | 1777 | | authentication as defined by | | 1778 | | Section 4.2.6.1. | | 1779 +-------------+-------------------------------------+---------------+ 1781 8. Security Considerations 1783 The CDNI Metadata Interface is expected to be secured as a function 1784 of the transport protocol (e.g. HTTP authentication [RFC2617], HTTPS 1785 [RFC2818], or inter-domain IPSec). 1787 If a malicious metadata server is contacted by a downstream CDN, the 1788 malicious server may provide metadata to the downstream CDN which 1789 denies service for any piece of content to any user agent. The 1790 malicious server may also provide metadata which directs a downstream 1791 CDN to a malicious origin server instead of the actual origin server. 1792 The dCDN is expected to authenticate the server to prevent this 1793 situation (e.g. by using HTTPS and validating the server's 1794 certificate). 1796 A malicious metadata client could request metadata for a piece of 1797 content from an upstream CDN. The metadata information may then be 1798 used to glean information regarding the uCDN or to contact an 1799 upstream origin server. The uCDN is expected to authenticate client 1800 requests to prevent this situation. 1802 9. Acknowledgements 1804 The authors would like to thank David Ferguson and Francois le 1805 Faucheur for their valuable comments and input to this document. 1807 10. References 1809 10.1. Normative References 1811 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1812 Requirement Levels", BCP 14, RFC 2119, March 1997. 1814 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1815 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1816 Authentication: Basic and Digest Access Authentication", 1817 RFC 2617, June 1999. 1819 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1821 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1822 Architecture", RFC 4291, February 2006. 1824 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1825 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1826 May 2008. 1828 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1829 Address Text Representation", RFC 5952, August 2010. 1831 10.2. Informative References 1833 [I-D.ietf-cdni-framework] 1834 Peterson, L., Davie, B., and R. Brandenburg, "Framework 1835 for CDN Interconnection", draft-ietf-cdni-framework-09 1836 (work in progress), January 2014. 1838 [I-D.ietf-cdni-requirements] 1839 Leung, K. and Y. Lee, "Content Distribution Network 1840 Interconnection (CDNI) Requirements", draft-ietf-cdni- 1841 requirements-17 (work in progress), January 2014. 1843 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1844 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1845 3986, January 2005. 1847 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 1848 Distribution Network Interconnection (CDNI) Problem 1849 Statement", RFC 6707, September 2012. 1851 [XML-BASE] 1852 Marsh, J., Ed. and R. Tobin, Ed., "XML Base (Second 1853 Edition) - http://www.w3.org/TR/xmlbase/", January 2009. 1855 Appendix A. Relationship to the CDNI Requirements 1857 Section 6 of [I-D.ietf-cdni-requirements] lists the requirements for 1858 the CDNI Metadata Distribution interface. This section outlines 1859 which of those requirements are met by the CDNI Metadata interface 1860 specified in this document. 1862 All metadata requirements are met either directly or indirectly by 1863 the CDNI Metadata Interface described in this document, with the 1864 clarifications or exceptions described in the following paragraphs. 1866 Requirements related to pre-positioning of metadata are met by this 1867 document on the assumption that other CDNI Interfaces are to be used 1868 by the upstream CDN to trigger the pre-positioning of metadata by the 1869 downstream CDN via the CDNI Metadata Interface. Triggering metadata 1870 pre-positioning is beyond the scope of the CDNI Metadata interface. 1871 However, the interface as described by this document supports pulling 1872 metadata on-demand for the purpose of pre-positioning. 1874 Requirement META-7 relating to modification of metadata by the 1875 upstream CDN is met both by allowing timeouts on the cacheability of 1876 metadata objects and by allowing other CDNI interfaces to initiate a 1877 refetch or purge of metadata. 1879 Requirement META-18 relating to surrogate cache behavior parameters 1880 is supported via extensibility. However, the example parameters in 1881 META-18 are not described in this document. 1883 Authors' Addresses 1885 Ben Niven-Jenkins 1886 Velocix (Alcatel-Lucent) 1887 3 Ely Road 1888 Milton, Cambridge CB24 6AA 1889 UK 1891 Email: ben@velocix.com 1893 Rob Murray 1894 Velocix (Alcatel-Lucent) 1895 3 Ely Road 1896 Milton, Cambridge CB24 6AA 1897 UK 1899 Email: rmurray@velocix.com 1901 Grant Watson 1902 Velocix (Alcatel-Lucent) 1903 3 Ely Road 1904 Milton, Cambridge CB24 6AA 1905 UK 1907 Email: gwatson@velocix.com 1909 Matt Caulfield 1910 Cisco Systems 1911 1414 Massachusetts Avenue 1912 Boxborough, MA 01719 1913 USA 1915 Phone: +1 978 936 9307 1916 Email: mcaulfie@cisco.com 1917 Kent Leung 1918 Cisco Systems 1919 3625 Cisco Way 1920 San Jose 95134 1921 USA 1923 Phone: +1 408 526 5030 1924 Email: kleung@cisco.com 1926 Kevin J. Ma 1927 Azuki Systems, Inc. 1928 43 Nagog Park 1929 Acton, MA 01720 1930 USA 1932 Phone: +1 978-844-5100 1933 Email: kevin.ma@azukisystems.com