idnits 2.17.1 draft-ietf-cdni-metadata-02.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 8 characters in excess of 72. == There are 4 instances of lines with non-RFC2606-compliant FQDNs in the document. -- 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 -- The document date (July 15, 2013) is 3938 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) == Missing Reference: 'I-D.jenkins-cdni-names' is mentioned on line 823, but not defined == Unused Reference: 'I-D.zyp-json-schema' is defined on line 1822, but no explicit reference was found in the text == Unused Reference: 'RFC4151' is defined on line 1831, but no explicit reference was found in the text == Unused Reference: 'RFC4287' is defined on line 1834, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) == Outdated reference: A later version (-14) exists of draft-ietf-cdni-framework-03 == Outdated reference: A later version (-17) exists of draft-ietf-cdni-requirements-05 == Outdated reference: A later version (-04) exists of draft-zyp-json-schema-03 Summary: 3 errors (**), 0 flaws (~~), 9 warnings (==), 3 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: January 16, 2014 Velocix (Alcatel-Lucent) 6 M. Caulfield 7 K. Leung 8 Cisco Systems 9 K. Ma 10 Azuki Systems, Inc. 11 July 15, 2013 13 CDN Interconnect Metadata 14 draft-ietf-cdni-metadata-02 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 January 16, 2014. 49 Copyright Notice 51 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . 10 74 4. Encoding-Independent CDNI Metadata Object Descriptions . . . 11 75 4.1. CDNI Metadata Structural Object Descriptions . . . . . . 12 76 4.1.1. HostIndex . . . . . . . . . . . . . . . . . . . . . . 12 77 4.1.2. HostMatch . . . . . . . . . . . . . . . . . . . . . . 12 78 4.1.3. HostMetadata . . . . . . . . . . . . . . . . . . . . 13 79 4.1.4. PathMatch . . . . . . . . . . . . . . . . . . . . . . 13 80 4.1.5. PathMetadata . . . . . . . . . . . . . . . . . . . . 14 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. Location . . . . . . . . . . . . . . . . . . . . 17 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 . . . . . . . . . . . . . . . . . . 19 94 4.2.5. Authorization Metadata . . . . . . . . . . . . . . . 20 95 4.2.6. Auth . . . . . . . . . . . . . . . . . . . . . . . . 20 96 4.2.7. Cache . . . . . . . . . . . . . . . . . . . . . . . . 21 97 4.2.8. Grouping . . . . . . . . . . . . . . . . . . . . . . 21 98 4.3. CDNI Metadata Simple Data Type Descriptions . . . . . . . 22 99 4.3.1. Link . . . . . . . . . . . . . . . . . . . . . . . . 22 100 4.3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . 22 101 4.3.3. RedirectionMethod . . . . . . . . . . . . . . . . . . 23 102 4.3.4. Endpoint . . . . . . . . . . . . . . . . . . . . . . 23 103 4.3.5. IPRange . . . . . . . . . . . . . . . . . . . . . . . 23 104 4.3.6. URI . . . . . . . . . . . . . . . . . . . . . . . . . 23 105 4.3.7. Time . . . . . . . . . . . . . . . . . . . . . . . . 23 106 5. CDNI Metadata Capabilities . . . . . . . . . . . . . . . . . 24 107 5.1. Protocol ACL Capabilities . . . . . . . . . . . . . . . . 24 108 5.2. Authorization Metadata Capabilities . . . . . . . . . . . 25 109 5.3. Host Metadata Capabilities . . . . . . . . . . . . . . . 25 110 6. CDNI Metadata interface . . . . . . . . . . . . . . . . . . . 25 111 6.1. Transport . . . . . . . . . . . . . . . . . . . . . . . . 26 112 6.2. Retrieval of CDNI Metadata resources . . . . . . . . . . 27 113 6.3. Bootstrapping . . . . . . . . . . . . . . . . . . . . . . 28 114 6.4. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 28 115 6.4.1. MIME Media Types . . . . . . . . . . . . . . . . . . 28 116 6.4.2. JSON Encoding of Objects . . . . . . . . . . . . . . 29 117 6.4.2.1. JSON Example . . . . . . . . . . . . . . . . . . 30 118 6.4.3. XML Encoding of Objects . . . . . . . . . . . . . . . 33 119 6.4.3.1. XML Example . . . . . . . . . . . . . . . . . . . 34 120 6.5. Extensibility . . . . . . . . . . . . . . . . . . . . . . 36 121 6.5.1. Metadata Enforcement . . . . . . . . . . . . . . . . 36 122 6.5.2. Metadata Override . . . . . . . . . . . . . . . . . . 37 123 6.6. Versioning . . . . . . . . . . . . . . . . . . . . . . . 37 124 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 125 8. Security Considerations . . . . . . . . . . . . . . . . . . . 38 126 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 38 127 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 128 10.1. Normative References . . . . . . . . . . . . . . . . . . 38 129 10.2. Informative References . . . . . . . . . . . . . . . . . 39 130 Appendix A. Relationship to the CDNI Requirements . . . . . . . 40 131 Appendix B. Metadata Rewriting . . . . . . . . . . . . . . . . . 40 132 B.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 41 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 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, authorize, and deliver 227 content from a downstream CDN. The data model relies on the 228 assumption that these metadata properties may be aggregated based on 229 the hostname of the content and subsequently on the resource path of 230 the content. The data model associates a set of CDNI Metadata 231 properties with a Hostname to form a default set of metadata 232 properties for content delivered for that Hostname. That default set 233 of metadata properties can be overridden by properties that apply to 234 specific paths within a URI. 236 Different Hostnames and URI paths will be associated with different 237 sets of CDNI Metadata properties in order to describe the required 238 behaviour when a dCDN surrogate is processing User Agent requests for 239 content at that Hostname or URI path. As a result of this structure, 240 significant commonality may exist between the CDNI Metadata 241 properties specified for different Hostnames, different URI paths 242 within a Hostname and different URI paths on different Hostnames. 243 For example the definition of which User Agent IP addresses should be 244 treated as being grouped together into a single network or geographic 245 location is likely to be common for a number of different Hostnames. 246 Another example is that although a uCDN is likely to have several 247 different policies configured to express geo-blocking rules, it is 248 likely that a single geo-blocking policy would be applied to multiple 249 Hostnames delivered through the CDN. 251 In order to enable the CDNI Metadata for a given Hostname or URI Path 252 to be decomposed into sets of CDNI Metadata properties that can be 253 reused by multiple Hostnames and URI Paths, the CDNI Metadata 254 interface specified in this document splits the CDNI Metadata into a 255 number of objects. Efficiency is improved by enabling a single CDNI 256 Metadata object (that is shared across Hostname and/or URI paths) to 257 be retrieved by a dCDN once, even if it is referenced by the CDNI 258 Metadata of multiple Hostnames. 260 Section 3.1 introduces a high level description of the HostIndex, 261 HostMetadata and PathMetadata objects and describes the relationships 262 between those objects. 264 Section 3.2 introduces a high level description of the CDNI 265 GenericMetadata object which represents the level at which CDNI 266 Metadata override occurs between HostMetadata and PathMetadata 267 objects. 269 Section 4 describes in detail the specific CDNI Metadata objects and 270 properties which may be contained within a CDNI GenericMetadata 271 object. 273 3.1. HostIndex, HostMetadata & PathMetadata objects 275 A HostIndex object contains a list of Hostnames (and/or IP addresses) 276 for which content requests may be delegated to the downstream CDN. 277 The HostIndex is the starting point for accessing the uCDN's CDNI 278 Metadata data store. It enables surrogates in the dCDN to 279 deterministically discover, on receipt of a User Agent request for 280 content, which other CDNI Metadata objects it requires in order to 281 deliver the requested content. 283 The HostIndex links Hostnames (and/or IP addresses) to HostMetadata 284 objects via HostMatch objects. HostMetadata objects contain (or 285 reference) the default CDNI Metadata required to serve content for 286 that host. When looking up CDNI Metadata, the downstream CDN looks 287 up the requested Hostname (or IP address) in the HostIndex, from 288 there it can find HostMetadata which describes properties for a host 289 and PathMetadata which may override those properties for given URI 290 paths within the host. 292 As well as containing the default CDNI Metadata for the specified 293 Hostname, HostMetadata and PathMetadata objects may also contain 294 PathMatch objects which in turn contain PathMetadata objects. 295 PathMatch objects override the CDNI Metadata in the HostMetadata 296 object or one or more preceding PathMetadata objects with more 297 specific CDNI Metadata that applies to content requests matching the 298 pattern defined in that PathMatch object. 300 For the purposes of retrieving CDNI Metadata all other required CDNI 301 Metadata objects and their properties are discoverable from the 302 appropriate HostMetadata, PathMatch and PathMetadata objects for the 303 requested content. 305 The relationships between the HostIndex, HostMatch, HostMetadata, 306 PathMatch and PathMetadata objects are described in Figure 1. 308 +---------+ +---------+ +------------+ 309 |HostIndex+-(*)->|HostMatch|-(1)->|HostMetadata+-------(*)------+ 310 +---------+ +---------+ +------+-----+ | 311 | | 312 (*) | 313 | | 314 --> References V V 315 (1) One and only one +---------+ ************************** 316 (*) Zero or more +--->|PathMatch| *Generic Metadata Objects* 317 | +---------+ ************************** 318 | | ^ 319 (*) (1) | 320 | | | 321 | V | 322 | +------------+ | 323 +--|PathMetadata+-------(*)------+ 324 +------------+ 326 Key: ----> = References 328 Figure 1: Relationships between the HostIndex, HostMetadata & 329 PathMetadata CDNI Metadata Objects 331 The relationships in Figure 1 are summarised in Table 1 below. 333 +--------------------+----------------------------------------------+ 334 | Data Object | Objects it References | 335 +--------------------+----------------------------------------------+ 336 | HostIndex | 0 or more HostMatch objects. | 337 | HostMatch | 1 HostMetadata object. | 338 | HostMetadata | 0 or more PathMatch objects. 0 or more | 339 | | GenericMetadata objects. | 340 | PathMatch | 1 PathMetadata object. | 341 | PathMetadata | 0 or more PathMatch objects. 0 or more | 342 | | GenericMetadata objects. | 343 +--------------------+----------------------------------------------+ 345 Table 1: Relationships between CDNI Metadata Objects 347 The table below describes the HostIndex, HostMetadata and 348 PathMetadata objects in more detail. 350 +-----------------+-------------------------------------------------+ 351 | Data Object | Description | 352 +-----------------+-------------------------------------------------+ 353 | HostIndex | A HostIndex object lists HostMatch objects | 354 | HostMatch | A HostMatch object defines a hostname to match | 355 | | against a requested host, and contains or | 356 | | references a HostMetadata object which contains | 357 | | CDNI Metadata objects to be applied when a | 358 | | request matches against the hostname. For | 359 | | example, if "example.com" is a content | 360 | | provider, a HostMatch object may include an | 361 | | entry for "example.com" with the URI of the | 362 | | associated HostMetadata object. | 363 | HostMetadata | A HostMetadata object contains (or references) | 364 | | the default CDNI Metadata objects for content | 365 | | served from that host, i.e. the CDNI Metadata | 366 | | objects for content requests that do not match | 367 | | any of the PathMatch objects contained or | 368 | | referenced by that HostMetadata object. For | 369 | | example, a HostMetadata object may describe the | 370 | | metadata properties which apply to | 371 | | "example.com" and may contain PathMatches for | 372 | | "example.com/movies/*" and | 373 | | "example.com/music/*" which reference | 374 | | corresponding PathMetadata objects that contain | 375 | | the CDNI Metadata objects for those more | 376 | | specific URI paths. | 377 | PathMatch | A PathMatch object defines a pattern to match | 378 | | against the requested URI path, and contains or | 379 | | references a PathMetadata object which contains | 380 | | (or references) the CDNI Metadata objects to be | 381 | | applied when a content request matches against | 382 | | the defined URI path pattern. | 383 | PathMetadata | A PathMetadata object contains the CDNI | 384 | | GenericMetadata objects for content served with | 385 | | the associated URI path (defined in a PathMatch | 386 | | object). A PathMetadata object may also contain | 387 | | PathMatch objects in order to recursively | 388 | | define more specific URI paths that require | 389 | | different (e.g. more specific) CDNI Metadata to | 390 | | this one. For example, the PathMetadata object | 391 | | which applies to "example.com/movies/*" may | 392 | | describe CDNI Metadata which apply to that | 393 | | resource path and may contain a PathMatch | 394 | | object for "example.com/movies/hd/*" which | 395 | | would reference the corresponding PathMetadata | 396 | | object for the "example.com/movies/hd/" path | 397 | | prefix. | 398 | GenericMetadata | A GenericMetadata object contains individual | 399 | | CDNI Metadata objects which define the specific | 400 | | policies and attributes needed to properly | 401 | | deliver the associated content. | 402 +-----------------+-------------------------------------------------+ 404 Table 2: HostIndex, HostMetadata and PathMetadata CDNI Metadata 405 Objects 407 3.2. Generic CDNI Metadata Object Properties 409 The HostMetadata and PathMetadata objects contain or can reference 410 other CDNI Metadata objects that contain properties which describe 411 how User Agent requests for content should be processed, for example 412 where to acquire the content, authorization rules that should be 413 applied, delivery location restrictions and so on. Each such CDNI 414 Metadata object is a specialization of a CDNI GenericMetadata object. 415 The GenericMetadata object abstracts the basic information required 416 for Metadata override and opaque Metadata distribution, from the 417 specifics of any given property (e.g., property semantics, 418 enforcement options, etc.). 420 The GenericMetadata object defines the type of properties contained 421 within it as well as whether or not the properties are mandatory to 422 enforce. If the dCDN does not understand or support the property 423 type and the property type is mandatory to enforce, the dCDN MUST NOT 424 serve the content to the User Agent. If the dCDN does not understand 425 or support the property type it is also not going to be able to 426 properly propagate the Metadata for cascaded distribution. If the 427 dCDN does not understand or support the property type and the 428 property type is not mandatory to enforce, then the GenericMetadata 429 object may be safely ignored. 431 Although a CDN cannot serve content to a User Agent if a mandatory 432 property cannot be enforced, it may be safe to redistribute that 433 metadata to another CDN without modification. For example, in the 434 cascaded CDN case, a transit CDN may pass through mandatory-to- 435 enforce metadata to the delivery CDN. For Metadata which does not 436 require customization, the data representation received off the wire 437 MAY be stored and redistributed without being natively understood or 438 supported by the transit CDN. However, for Metadata which require 439 translations, transparent redistribution of the uCDN Metadata values 440 may not be appropriate. Certain Metadata may be safely, though 441 possibly not optimially, redistributed unmodified, e.g., source 442 acquisition address may not be optimal if transparently 443 redistributed, but may still work. Redistribution safety MUST be 444 specified for each GenericMetadata. 446 3.3. Metadata Inheritance and Override 448 In the data model, a HostMetadata object may contain (or reference) 449 multiple PathMetadata objects (via PathMatch objects). Each 450 PathMetadata object may in turn contain (or reference) other 451 PathMetadata objects. HostMetadata and PathMetadata objects form an 452 inheritance tree where each node in the tree inherits or overrides 453 the property values set by its parent. 455 GenericMetadata objects of a given type override all GenericMetadata 456 objects of the same type previously defined by any parent object in 457 the tree. GenericMetadata objects of a given type previously defined 458 by a parent object in the tree are inherited when no object of the 459 same type is defined by the child object. For example, if 460 HostMetadata for the host "example.com" contains GenericMetadata 461 objects of type LocationACL and TimeWindowACL, while a PathMetadata 462 object which applies to "example.com/movies/*" defines an alternate 463 GenericMetadata object of type TimeWindowACL, then: 465 the TimeWindowACL defined in the PathMetadata would override the 466 TimeWindowACL defined in the HostMetadata 468 the LocationACL defined in the HostMetadata would be inherited for 469 all User Agent requests for content under "example.com/movies". 471 The PathMetadata defined TimeWindowACL would override the 472 TimeWindowACL defined in the HostMetadata for all User Agent requests 473 for movies. 475 3.4. Metadata Naming 476 GenericMetadata objects are identified by their type. The type 477 SHOULD be descriptive, and MAY be hierarchical to support aggregating 478 groups of properties for the purpose of readability and for avoiding 479 name conflicts between vendor extensions. A dotted alpha-numeric 480 notation is suggested for human readability. 482 Metadata types defined by this document are not hierarchical. 484 Examples of GenericMetadata object type names: 486 LocationACL 488 ext.vendor1.featurex 490 ext.vendor1.featurey 492 ext.vendor2.featurex 494 [Ed. It is intended that Metadata capability advertisements will 495 allow either individual Metadata names or Metadata bundle identifiers 496 to be used. Need to have a procedure for defining and distributing 497 bundle information to be used in Metadata capability advertisement.] 499 4. Encoding-Independent CDNI Metadata Object Descriptions 501 Section 4.1 provides the definitions of each object type declared in 502 Section 3. These objects are described as structural objects as they 503 provide the structure for the inheritance tree and identifying which 504 specific properties apply to a given User Agent content request. 506 Section 4.2 provides the definitions for the set of core metadata 507 objects which may be contained within a GenericMetadata object. 508 These objects are described as property objects as they define the 509 semantics, enforcement options, and serialization rules for specific 510 properties. These properties govern how User Agent requests for 511 content are handled. Property objects may be composed of or contain 512 references to other objects. In those cases the value of the 513 property can be either an object of that type (the object is 514 embedded) or a Link object that contains a URI and relationship that 515 can be dereferenced to retrieve the CDNI Metadata object that 516 represents the value of that property. 518 Note: In the following sections, the term "mandatory-to-specify" is 519 used to convey which objects or properties must be specified for a 520 given parent object or property. When mandatory-to-specify is set to 521 true, it implies that if the parent object is specified, then the 522 defined object or property MUST also be specified, e.g., a HostMatch 523 object without a host to match against does not make sense, 524 therefore, the host is mandatory-to-specify inside a parent HostMatch 525 object. 527 4.1. CDNI Metadata Structural Object Descriptions 529 Each of the sub-sections below describe the structural objects 530 defined in Table 2. 532 4.1.1. HostIndex 534 The HostIndex object is the entry point into the CDNI Metadata 535 hierarchy. It contains a list of HostMatch objects. An incoming 536 content request is matched against the hostname inside of each of the 537 listed HostMatch objects to find the HostMatch object which applies 538 to the request. 540 Property: hosts 542 Description: List of HostMatch objects, in priority order. 544 Type: List of HostMatch objects 546 Mandatory-to-Specify: Yes. 548 4.1.2. HostMatch 550 The HostMatch object contains a hostname or IP address to match 551 against content requests. The HostMatch object also contains a 552 reference to Metadata objects to apply if a match is found. 554 Property: host 556 Description: String (hostname or IP address) to match against 557 the requested host. 559 Type: String 561 Mandatory-to-Specify: Yes. 563 Property: host-metadata 565 Description: CDNI Metadata to apply when delivering content 566 that matches this host. 568 Type: HostMetadata 570 Mandatory-to-Specify: Yes. 572 4.1.3. HostMetadata 574 The HostMetadata object contains both Metadata that applies to 575 content requests for a particular host and a list of pattern matches 576 for finding more specific Metadata based on the resource path in a 577 content request. 579 Property: metadata 581 Description: List of host related metadata. 583 Type: List of GenericMetadata objects 585 Mandatory-to-Specify: Yes. 587 Property: paths 589 Description: Path specific rules. First match applies. 591 Type: List of PathMatch objects 593 Mandatory-to-Specify: No. 595 Property: modes 597 Description: Defines which redirection methods are supported. 599 Type: List of RedirectionMethod 601 Mandatory-to-Specify: Yes. 603 4.1.4. PathMatch 605 The PathMatch object contains an expression given as a PatternMatch 606 object to match against a resource URI path and Metadata objects to 607 apply if a match is found. 609 Property: path-pattern 611 Description: Pattern to match against the requested path, i.e. 612 against the [RFC3986] path-absolute. 614 Type: PatternMatch 616 Mandatory-to-Specify: Yes. 618 Property: path-metadata 619 Description: CDNI Metadata to apply when delivering content 620 that matches this pattern. 622 Type: PathMetadata 624 Mandatory-to-Specify: Yes. 626 4.1.5. PathMetadata 628 A PathMetadata object contains the CDNI Metadata properties for 629 content served with the associated URI path (defined in a PathMatch 630 object). Note that if CDNI metadata is used as an input to CDNI 631 request routing and DNS-based redirection is employed, then any 632 metadata at the PathMetadata level or below will be inaccessible at 633 request routing time. 635 Property: metadata 637 Description: List of path related metadata. 639 Type: List of GenericMetadata objects 641 Mandatory-to-Specify: Yes. 643 Property: paths 645 Description: Path specific rules. First match applies. 647 Type: List of PathMatch objects 649 Mandatory-to-Specify: No. 651 4.1.6. PatternMatch 653 A PatternMatch object contains the pattern string and flags that 654 describe the PathMatch expression. 656 Property: pattern 658 Description: A pattern for string matching. The pattern may 659 contain the wildcards * and ?, where * matches any sequence of 660 characters (including the empty string) and ? matches exactly 661 one character. The three literals \ , * and ? should be 662 escaped as \\, \* and \? 664 Type: String 666 Mandatory-to-Specify: Yes. 668 Property: case-sensitive 670 Description: Flag indicating whether or not case-sensitive 671 matching should be used. 673 Type: Boolean 675 Mandatory-to-Specify: No. Default is case-insensitive match. 677 Property: match-query-string 679 Description: Flag indicating whether or not the query string 680 should be included in the pattern match. 682 Type: Boolean 684 Mandatory-to-Specify: No. Default is not to include query 685 strings when matching. 687 4.1.7. GenericMetadata 689 A GenericMetadata object is a abstraction for managing individual 690 CDNI Metadata properties in an opaque manner. 692 Property: type 694 Description: CDNI Metadata property object type. 696 Type: String 698 Mandatory-to-Specify: Yes. 700 Property: value 702 Description: CDNI Metadata property object. 704 Type: matches the type property above 706 Mandatory-to-Specify: Yes. 708 Property: mandatory-to-enforce 710 Description: Flag identifying whether or not the enforcement of 711 the property Metadata is required. 713 Type: Boolean 715 Mandatory-to-Specify: Yes. 717 Property: safe-to-redistribute 719 Description: Flag identifying whether or not the property 720 Metadata may be safely redistributed without modification. 722 Type: Boolean 724 Mandatory-to-Specify: No. Default is allow transparent 725 redistribution. 727 4.2. CDNI Metadata Property Object Descriptions 729 4.2.1. Source Metadata 731 Source Metadata provides the dCDN information about content 732 acquisition e.g. how to contact an uCDN Surrogate or an Origin Server 733 to obtain the content to be served. The sources are not necessarily 734 the actual Origin Servers operated by the CSP but might be a set of 735 Surrogates in the uCDN. 737 Property: sources 739 Description: Sources from which the dCDN can acquire content, 740 listed in priority order. 742 Type: List of Source objects 744 Mandatory-to-Specify: No. Default is to use static 745 configuration, out of band of the metadata interface. 747 4.2.1.1. Source 749 A Source object describes the Source which should be used by the dCDN 750 for content acquisition, e.g. a Surrogate within the uCDN or an 751 alternate Origin Server, the protocol to be used and any 752 authentication method. 754 Property: auth 756 Description: Authentication method to use when requesting 757 content from this source. 759 Type: Auth 761 Mandatory-to-Specify: No. Default is no authentication is 762 required. 764 Property: endpoints 765 Description: Origins from which the dCDN can acquire content. 767 Type: List of EndPoint objects 769 Mandatory-to-Specify: Yes. 771 4.2.2. LocationACL Metadata 773 LocationACL Metadata defines location-based restrictions. 775 Property: locations 777 Description: Access control list which applies restrictions to 778 delivery based on client location. 780 Type: List of LocationRule objects 782 Mandatory-to-Specify: No. Default is allow all locations. 784 4.2.2.1. LocationRule 786 A LocationRule contains or references a list of Location objects and 787 the corresponding action. 789 Property: locations 791 Description: List of locations to which the rule applies. 793 Type: List of Location objects 795 Mandatory-to-Specify: Yes. 797 [Ed: reusing locations as a property name is confusing and should 798 likely be changed] 800 Property: action 802 Description: Defines whether the rule specifies locations to 803 allow or deny. 805 Type: Enumeration [allow|deny] 807 Mandatory-to-Specify: No. Default is deny. 809 4.2.2.2. Location 810 A Location object describes a Location which may be applied by a 811 LocationRule, e.g. a Location may be an IPv4 address range or a 812 geographic location. 814 Property: iprange 816 Description: A set of IP Addresses. 818 Type: List of IPRange objects 820 Mandatory-to-Specify: Yes. 822 [Ed: Location as specified above only supports the Class 1a names 823 described in [I-D.jenkins-cdni-names]. Need to add support for Class 824 1b names to a later version.] 826 4.2.3. TimeWindowACL Metadata 828 TimeWindowACL Metadata defines time-based restrictions. 830 Property: times 832 Description: Access control list which applies restrictions to 833 delivery based on request time. 835 Type: List of TimeWindowRule objects 837 Mandatory-to-Specify: No. Default is allow all time windows. 839 4.2.3.1. TimeWindowRule 841 A TimeWindowRule contains or references a list of TimeWindow objects 842 and the corresponding action. 844 Property: times 846 Description: List of time windows to which the rule applies. 848 Type: List of TimeWindow objects 850 Mandatory-to-Specify: Yes. 852 Property: action 854 Description: Defines whether the rule specifies time windows to 855 allow or deny. 857 Type: Enumeration [allow|deny] 858 Mandatory-to-Specify: No. Default is deny. 860 4.2.3.2. TimeWindow 862 A TimeWindow object describes a time range which may be applied by an 863 ACLRule, e.g. Start 09:00AM 01/01/2000 UTC End 17:00PM 01/01/2000 864 UTC. 866 Property: start 868 Description: The start time of the window. 870 Type: Time 872 Mandatory-to-Specify: Yes. 874 Property: end 876 Description: The end time of the window. 878 Type: Time 880 Mandatory-to-Specify: Yes. 882 4.2.4. ProtocolACL Metadata 884 ProtocolACL Metadata defines delivery protocol restrictions. 886 Property: protocols 888 Description: Access control list which applies restrictions to 889 delivery based on delivery protocol. 891 Type: List of ProtocolRule objects 893 Mandatory-to-Specify: No. Default is allow all protocols. 895 4.2.4.1. ProtocolRule 897 A ProtocolRule contains or references a list of Protocol objects. 898 ProtocolRule objects are used to construct a ProtocolACL to apply 899 restrictions to content acquisition or delivery. 901 Property: protocols 903 Description: List of protocols to which the rule applies. 905 Type: List of protocol objects 906 Mandatory-to-Specify: Yes. 908 Property: action 910 Description: Defines whether the rule specifies protocols to 911 allow or deny. 913 Type: Enumeration [allow|deny]+ 915 Mandatory-to-Specify: No. Default is allow all protocols. 917 Property: direction 919 Description: Defines whether the ProtocolRule specifies 920 protocols for acquisition or delivery. 922 Type: Enumeration [acquisition|delivery] 924 Mandatory-to-Specify: No. Default is to apply the rule to both 925 acquisition and delivery. 927 4.2.5. Authorization Metadata 929 Authorization Metadata define content authorization methods. 931 Property: methods 933 Description: Options for authenticating content requests. All 934 options in the list are equally valid. 936 Type: List of Auth objects 938 Mandatory-to-Specify: No. Default is no authorization 939 required. 941 4.2.6. Auth 943 An Auth object defines authentication and authorization methods to be 944 used during content delivery and content acquisition, e.g. methods 945 such as tokenization and URL Signing. 947 [Ed. Need to synchronize authentication configuration with CDNI URL 948 signing draft definitions.] 950 [Ed. Need to consider how to separate protocol specific method 951 configuration (e.g., HTTP basic/digest authentication), which must 952 match the HostMatch protocol, from protocol agnostic method 953 configurations (e.g., URL signing/tokenization).] 954 Property: direction 956 Description: Defines whether the Auth object applies to 957 acquisition or delivery requests. 959 Type: Enumeration [acquisition|delivery] 961 Mandatory-to-Specify: No. Default is to apply the rule to both 962 acquisition and delivery. 964 4.2.7. Cache 966 A Cache object describes the cache control parameters to be applied 967 to the content by intermediate caches. 969 Property: ignore-query-string 971 Description: Allows a cache to ignore URI query string 972 parameters while comparing URIs for equivalence. 974 Type: Boolean 976 Mandatory-to-Specify: No. Default is to consider query string 977 parameters when comparing URIs. 979 4.2.8. Grouping 981 A Grouping object identifies a large group of content to which this 982 content belongs. 984 Property: ccid 986 Description: Content Collection identifier for an application- 987 specific purpose such as logging. 989 Type: String 991 Mandatory-to-Specify: No. Default is an empty string. 993 Property: sid 995 Description: Session identifier for an application-specific 996 purpose such as logging. 998 Type: String 1000 Mandatory-to-Specify: No. Default is an empty string. 1002 4.3. CDNI Metadata Simple Data Type Descriptions 1004 This section describes the simpler data types that are used for 1005 properties of CDNI Metadata objects. 1007 4.3.1. Link 1009 A link object may be used in place of any of the objects or 1010 properties described above. Links can be used to avoid duplication 1011 if the same metadata information is repeated within the metadata 1012 tree. When a link replaces an object, its href property is set to 1013 the URI of the resource, its rel property is set to the name of the 1014 property it is replacing, and its type property is set to the type of 1015 the object it is replacing. 1017 Property: href 1019 Description: The URI of the of the addressable object being 1020 referenced. 1022 Type: URI 1024 Mandatory: Yes 1026 Property: rel 1028 Description: The Relationship between the referring object and 1029 the object it is referencing. 1031 Type: String 1033 Mandatory: Yes 1035 Property: type 1037 Description: The type of the object being referenced. 1039 Type: String 1041 Mandatory: Yes 1043 4.3.2. Protocol 1045 Protocol objects are used to specify registered protocols for content 1046 acquisition or delivery. 1048 [Ed. Need to reference protocol registry.] 1049 Type: Enumeration [HTTP|RTSP|RTMP] 1051 4.3.3. RedirectionMethod 1053 RedirectionMethod objects are used to specify registered content 1054 redirection modes. 1056 [Ed. Need to reference redirection method registry.] 1058 Type: Enumeration [HTTP-I|HTTP-R|DNS-I|DNS-R] 1060 4.3.4. Endpoint 1062 A hostname (with optional port) or an IP address (with optional 1063 port). 1065 Note: All implementations MUST support IPv4 addresses encoded as 1066 specified by the 'IPv4address' rule in Section 3.2.2 of [RFC3986] and 1067 MUST support all IPv6 address formats specified in [RFC4291]. Server 1068 implementations SHOULD use IPv6 address formats specified in 1069 [RFC5952]. 1071 4.3.5. IPRange 1073 One of: 1075 o A range of consecutive IP addresses (IPv4 or IPv6) expressed as 1076 Address1-Address2 which does not have to be to power of two 1077 aligned, for example the range 192.0.2.1-192.0.2.10 is valid. The 1078 first Address in the range MUST be 'lower' than the final address 1079 in the range. 1081 o A valid IP subnet (IPv4 or IPv6) expressed using CIDR notation. 1083 o A single IP address (IPv4 or IPv6). 1085 Note: Client implementations MUST support IPv4 addresses encoded as 1086 specified by the 'IPv4address' rule in Section 3.2.2 of [RFC3986] and 1087 MUST support all IPv6 address formats specified in [RFC4291]. Server 1088 implementations SHOULD use IPv6 address formats specified in 1089 [RFC5952]. 1091 4.3.6. URI 1093 A URI as specified in [RFC3986]. 1095 4.3.7. Time 1096 A time value expressed in seconds since Unix epoch in the UTC 1097 timezone. 1099 5. CDNI Metadata Capabilities 1101 CDNI Metadata is used to convey information pertaining to content 1102 delivery from uCDN to dCDN. For optional metadata, it may be useful 1103 for the uCDN to know if the dCDN supports the metadata, prior to 1104 delegating any content requests to the dCDN. If optional-to- 1105 implement metadata is mandatory-to-enforce and the dCDN does not 1106 support it, any delegated requests for that content will fail, so 1107 there is no reason to delegate those requests. Likewise, for any 1108 metadata which may be assigned optional values, it may be useful for 1109 the uCDN to know which values the dCDN supports, prior to delegating 1110 any content requests to the dCDN. If a the optional value assigned 1111 to a given piece of content's metadata is not supported by the dCDN, 1112 any delegated requests for that content may fail, so there is likely 1113 no reason to delegate those requests. 1115 The CDNI Footprint and Capabilities Interface provides a means of 1116 advertising capabilities from dCDN to uCDN. Support for optional 1117 metadata and support for optional metadata values may be advertised 1118 using the capabilities interface. This section describes the 1119 capabilities advertisement requirements for the metadata defined in 1120 Section 4.2 1122 5.1. Protocol ACL Capabilities 1124 The ProtoclACL object contains a list of Protocol values. The dCDN 1125 MUST advertise which delivery protocols it supports so that the uCDN 1126 knows what type of content requests it can redirect to the dCDN. If 1127 the dCDN does not support a given acquisition or delivery protocol, 1128 the uCDN should not delegate requests requiring those protocols to 1129 the dCDN as the dCDN will not be able to properly acquire or deliver 1130 the content. 1132 ProtocolRules are defined for either acquisition or delivery. For 1133 some CDNs, certain combinations of acquisition and delivery protocols 1134 may not make sense (e.g., RTSP acquisition for HTTP delivery), while 1135 other CDNs may support customized protocol adaptation. ProtocolACL 1136 capabilities are not intended to define which combinations of 1137 protocols should be used. ProtocolACL capabilties are only intended 1138 to describe which protocols the dCDN does or does not support. 1139 Protocol combination restrictions are specified in the metadata 1140 itself and associated with specific groups of content assets. 1142 [Ed. Need to register delivery protocol capability ID.] 1144 [Ed. Need to reference protocol registry, and discuss specification 1145 of overlapping protocol values.] 1147 5.2. Authorization Metadata Capabilities 1149 The Authorization object contains a list of Auth values. The dCDN 1150 MUST advertise which authorization algorithms it supports so that the 1151 uCDN knows what type of content requests it can redirect to the dCDN. 1152 If the dCDN does not support a given authorization algorithm, the 1153 uCDN should not delegate requests requiring that algorithm to the 1154 dCDN as the dCDN will not be able to properly acquire the content or 1155 enforce delivery restrictions. 1157 [Ed. Need to register authorization algorithm capability ID.] 1159 [Ed. Need to reference auth registry, and discuss specification of 1160 overlapping auth values.] 1162 5.3. Host Metadata Capabilities 1164 The HostMetadata object contains a list of redirection method values. 1165 The dCDN MUST advertise which redirection modes it supports so that 1166 the uCDN knows how to redirect content requests to the dCDN. If the 1167 dCDN does not support a given redirection method, the uCDN should not 1168 delegate requests to the dCDN using that method as the dCDN will not 1169 be able to properly handle the redirection. 1171 [Ed. Need to register redirection method capability ID.] 1173 [Ed. Need to reference redirection method registry.] 1175 6. CDNI Metadata interface 1177 This section specifies an interface to enable a Downstream CDN to 1178 retrieve CDNI Metadata objects from an Upstream CDN. 1180 The interface can be used by a Downstream CDN to retrieve CDNI 1181 Metadata objects either dynamically as required by the Downstream CDN 1182 to process received requests (for example in response to receiving a 1183 CDNI Request Routing request from an Upstream CDN or in response to 1184 receiving a request for content from a User Agent) or in advance of 1185 being required (for example in case of prepositioned CDNI Metadata 1186 acquisition). 1188 The CDNI Metadata interface is built on the principles of RESTful web 1189 services. This means that requests and responses over the interface 1190 are built around the transfer of representations of hyperlinked 1191 resources. A resource in the context of the CDNI Metadata interface 1192 is any object in the Data Model (as described in Section 3 through 1193 Section 4). 1195 In the general case a CDNI Metadata server makes each instance of an 1196 addressable CDNI Metadata object available via a unique URI that 1197 returns a representation of that instance of that CDNI Metadata 1198 object. When an object needs to reference another addressable CDNI 1199 Metadata object (for example a HostIndex object referencing a 1200 HostMetadata object) it does so by including a link to the referenced 1201 object. 1203 CDNI Metadata servers are free to assign whatever structure they 1204 desire to the URIs for CDNI Metadata objects and CDNI Metadata 1205 clients MUST NOT make any assumptions regarding the structure of CDNI 1206 Metadata URIs or the mapping between CDNI Metadata objects and their 1207 associated URIs. Therefore any URIs present in the examples below 1208 are purely illustrative and are not intended to impose a definitive 1209 structure on CDNI Metadata interface implementations. 1211 6.1. Transport 1213 The CDNI Metadata interface uses HTTP as the underlying protocol 1214 transport. 1216 The HTTP Method in the request defines the operation the request 1217 would like to perform. Servers implementing the CDNI Metadata 1218 interface MUST support the HTTP GET and HEAD methods. 1220 The corresponding HTTP Response returns the status of the operation 1221 in the HTTP Status Code and returns the current representation of the 1222 resource (if appropriate) in the Response Body. HTTP Responses from 1223 servers implementing the CDNI Metadata interface that contain a 1224 response body SHOULD include an ETag to enable validation of cached 1225 versions of returned resources. 1227 The CDNI Metadata interface specified in this document is a read-only 1228 interface. Therefore support for other HTTP methods such as PUT, 1229 POST and DELETE etc. is not specified. Server implementations of 1230 this interface SHOULD reject all methods other than GET and HEAD. 1232 As the CDNI Metadata interface builds on top of HTTP, CDNI Metadata 1233 servers may make use of any HTTP feature when implementing the CDNI 1234 Metadata interface, for example a CDNI Metadata server may make use 1235 of HTTP's caching mechanisms to indicate that the returned response/ 1236 representation can be reused without re-contacting the CDNI Metadata 1237 server. 1239 6.2. Retrieval of CDNI Metadata resources 1241 In the general case a CDNI Metadata server makes each instance of an 1242 addressable CDNI Metadata object available via a unique URI and 1243 therefore in order to retrieve CDNI Metadata, a CDNI Metadata client 1244 first makes a HTTP GET request for the URI of the HostIndex which 1245 provides the CDNI Metadata client with a list of Hostnames for which 1246 the upstream CDN may delegate content delivery to the downstream CDN. 1248 In order to retrieve the CDNI Metadata for a particular request the 1249 CDNI Metadata client processes the received HostIndex object and 1250 finds the corresponding HostMetadata entry (by matching the hostname 1251 in the request against the hostnames in the HostMatch). If the 1252 HostMetadata is linked (rather than embedded), the CDNI metadata 1253 client then makes a GET request for the URI specified in the href 1254 property of the Link object which points to the HostMetadata object 1255 itself. 1257 In order to retrieve the most specific metadata for a particular 1258 request, the CDNI metadata client inspects the HostMetadata for 1259 references to more specific PathMetadata objects. If any 1260 PathMetadata match the request (and are linked rather than embedded), 1261 the CDNI metadata client makes another GET request for the 1262 PathMetadata. Each PathMetadata object may also include references 1263 to yet more specific metadata. If this is the case, the CDNI 1264 metadata client continues requesting PathMetadata recursively. 1266 Where a downstream CDN is interconnected with multiple upstream CDNs, 1267 the downstream CDN must decide which upstream CDN's CDNI metadata 1268 should be used to handle a particular User Agent request. 1270 When application level redirection (e.g. HTTP 302 redirects) is being 1271 used between CDNs, it is expected that the downstream CDN will be 1272 able to determine the upstream CDN that redirected a particular 1273 request from information contained in the received request (e.g. via 1274 the URI). With knowledge of which upstream CDN routed the request, 1275 the downstream CDN can choose the correct metadata server from which 1276 to obtain the HostIndex. Note that the HostIndex served by each uCDN 1277 may be unique. 1279 In the case of DNS redirection there is not always sufficient 1280 information carried in the DNS request from User Agents to determine 1281 the upstream CDN that redirected a particular request (e.g. when 1282 content from a given host is redirected to a given downstream CDN by 1283 more than one upstream CDN) and therefore downstream CDNs may have to 1284 apply local policy when deciding which upstream CDN's metadata to 1285 apply. 1287 6.3. Bootstrapping 1289 The URI for the HostIndex object of a given upstream CDN needs to be 1290 either discovered by or configured in the downstream CDN. All other 1291 objects/resources are then discoverable from the HostIndex object by 1292 following the links in the HostIndex object and the referenced 1293 HostMetadata and PathMetadata objects. 1295 If the URI for the HostIndex object is not manually configured in the 1296 downstream CDN then the HostIndex URI could be discovered. A 1297 mechanism allowing the downstream CDN to discover the URI of the 1298 HostIndex is outside the scope of this document. 1300 6.4. Encoding 1302 Object are resources that may be: 1304 o Addressable, where the object is a resource that may be retrieved 1305 or referenced via its own URI. 1307 o Embedded, where the object is contained (or inlined) within a 1308 property of an addressable object. 1310 In the descriptions of objects we use the term "X contains Y" to mean 1311 either Y is directly embedded in X or that Y is linked to by X. It is 1312 generally a deployment choice for the uCDN implementation to decide 1313 when and which CDNI Metadata objects to embed and which are 1314 separately addressable. 1316 6.4.1. MIME Media Types 1318 All MIME types are prefixed with "application/cdni." The MIME type 1319 for each object matches the type name of that object as defined by 1320 this document. Table 3 lists a few examples of the MIME Media Type 1321 for each object (resource) that is retrievable through the CDNI 1322 Metadata interface. The MIME type suffix depends on the metadata 1323 encoding, either "+xml" or "+json". 1325 +--------------+-------------------------------+ 1326 | Data Object | MIME Media Type | 1327 +--------------+-------------------------------+ 1328 | HostIndex | application/cdni.HostIndex | 1329 | HostMatch | application/cdni.HostMatch | 1330 | HostMetadata | application/cdni.HostMetadata | 1331 | PathMatch | application/cdni.PathMatch | 1332 | PathMetadata | application/cdni.PathMetadata | 1333 +--------------+-------------------------------+ 1335 Table 3: Example MIME Media Types for CDNI Metadata objects 1337 See http://www.iana.org/assignments/media-types/index.html for 1338 reference. 1340 6.4.2. JSON Encoding of Objects 1342 One possible encoding for a CDNI Metadata object is a JSON object 1343 containing a dictionary of (key,value) pairs where the keys are the 1344 property names and the values are the associated property values. 1346 The keys of the dictionary are the names of the properties associated 1347 with the object and are therefore dependent on the specific object 1348 being encoded (i.e. dependent on the MIME Media Type of the returned 1349 resource). Likewise, the values associated with each key are 1350 dependent on the specific object being encoded (i.e. dependent on the 1351 MIME Media Type of the returned resource). 1353 Dictionary keys in JSON are case sensitive and therefore by 1354 convention any dictionary key defined by this document (for example 1355 the names of CDNI Metadata object properties) MUST be represented in 1356 lowercase. 1358 In addition to the properties specific to each object type, the keys 1359 defined below may be present in any object. 1361 Key: base 1363 Description: Provides a prefix for any relative URLs in the 1364 object. This is similar to the XML base tag [XML-BASE]. If 1365 absent, all URLs in the remainder of the document must be 1366 absolute URLs. 1368 Type: URI 1370 Mandatory: No 1372 Key: links 1373 Description: The links of this object to other addressable 1374 objects. Any property may be replaced by a link to an object 1375 with the same type as the property it replaces. 1377 Type: List of Link objects 1379 Mandatory: Yes 1381 6.4.2.1. JSON Example 1383 A downstream CDN may request the HostIndex and receive the following 1384 object of type "application/cdni.HostIndex+json": 1386 { 1387 "hosts": [ 1388 { 1389 "host": "video.example.com", 1390 "links": [ 1391 { 1392 "rel": "host-metadata", 1393 "type": "application/cdni.HostMetadata", 1394 "href": "http://metadata.example.ucdn.com/video" 1395 } 1396 ] 1397 }, 1398 { 1399 "host": "images.example.com", 1400 "links": [ 1401 { 1402 "rel": "host-metadata", 1403 "type": "application/cdni.HostMetadata", 1404 "href": "http://metadata.ucdn.example.com/images" 1405 } 1406 ] 1407 } 1408 ] 1409 } 1411 If the incoming request has a Host header with "video.example.com" 1412 then the downstream CDN would fetch from the next metadata object 1413 from "http://metadata.ucdn.example.com/video" expecting a MIME type 1414 of "application/cdni.HostMetadata+json": 1416 { 1417 "metadata": [ 1418 { 1419 "type": "application/cdni.SourceMetadata", 1420 "value": { 1421 "sources": [ 1422 { 1423 "links": [{ 1424 "rel": "auth", 1425 "type": "application/cdni.Auth", 1426 "href": "http://metadata.ucdn.example.com/auth1234" 1427 }], 1428 "endpoint": "acq1.ucdn.example.com", 1429 "protocol": "ftp" 1430 }, 1431 { 1432 "links": [{ 1433 "rel": "auth", 1434 "type": "application/cdni.Auth", 1435 "href": "http://metadata.ucdn.example.com/auth1234" 1436 }], 1437 "endpoint": "acq2.ucdn.example.com", 1438 "protocol": "http" 1439 } 1440 ] 1441 } 1442 }, 1443 { 1444 "type": "application/cdni.LocationACL", 1445 "value": { 1446 "locations": [ 1447 { 1448 "locations": [ 1449 { "iprange": "192.168.0.0/16" } 1450 ], 1451 "action": "deny" 1452 } 1453 ] 1454 } 1455 }, 1456 { 1457 "type": "application/cdni.ProtocolACL", 1458 "value": { 1459 "protocols": [ 1460 { 1461 "protocols": [ 1462 "ftp" 1463 ], 1464 "action": "deny" 1465 } 1466 ] 1467 } 1469 } 1470 ], 1471 "paths": [ 1472 { 1473 "path-pattern": { 1474 "pattern": "/videos/trailers/*" 1475 }, 1476 "links": [{ 1477 "rel": "path-metadata", 1478 "type": "application/cdni.PathMetadata", 1479 "href": "http://metadata.ucdn.example.com/videos/trailers" 1480 }] 1481 }, 1482 { 1483 "path-pattern": { 1484 "pattern": "/videos/movies/*" 1485 }, 1486 "links": [{ 1487 "rel": "pathmetadata", 1488 "type": "application/cdni.PathMetadata", 1489 "href": "http://metadata.ucdn.example.com/videos/movies" 1490 }] 1491 } 1492 ] 1493 } 1495 Suppose the path of the requested resource matches the "/video/movies 1496 /*" pattern, the next metadata requested would be for "http:// 1497 metadata.ucdn.example.com/video/movies" with an expected type of 1498 "application/cdni.PathMetadata": 1500 { 1501 "metadata": [], 1502 "paths": [ 1503 { 1504 "path-pattern": { 1505 "pattern": "/videos/movies/hd/*" 1506 }, 1507 "links": [{ 1508 "rel": "pathmetadata", 1509 "type": "application/cdni.PathMetadata", 1510 "href": "http://metadata.ucdn.example.com/videos/movies/hd" 1511 }] 1512 } 1513 ] 1514 } 1515 Finally, if the path of the requested resource also matches the "/ 1516 videos/movies/hd/*" pattern, the downstream CDN would also fetch the 1517 following object from "http://metadata.ucdn.example.com/videos/movies 1518 /hd" with MIME type "application/cdni.PathMetadata": 1520 { 1521 "metadata": [ 1522 { 1523 "type": "application/cdni.TimeWindowACL", 1524 "value": { 1525 "times": [ 1526 "times": [ 1527 { 1528 "start": "1213948800", 1529 "end": "1327393200" 1530 } 1531 ], 1532 "type": "allow" 1533 ] 1534 } 1535 } 1536 ] 1537 } 1539 6.4.3. XML Encoding of Objects 1541 Another possible encoding for a CDNI Metadata object is an XML 1542 document containing elements with tag names which match property 1543 names and values which match the associated property values. 1545 Tag names of elements are the names of the properties associated with 1546 the object and are therefore dependent on the specific object being 1547 encoded (i.e. dependent on the MIME Media Type of the returned 1548 resource). Likewise, the values associated with each element are 1549 dependent on the specific object being encoded (i.e. dependent on the 1550 MIME Media Type of the returned resource). 1552 Lists are encoded by repeating the singular form of a property name. 1553 For example the "hosts" property is a list of "HostMatch" objects. 1554 This list would be encoded as multiple "host" elements. 1556 Link objects are a special case. If a Link object replaces a 1557 property then a "link" element replaces the expected element. The 1558 properties of the Link object are encoded as XML attributes. The 1559 type attribute is set to the MIME type of the target object. The 1560 href attribute is set to the URI of the target object. The rel 1561 attribute is set to the name of the element being replaced. 1563 6.4.3.1. XML Example 1565 A downstream CDN may request the HostIndex and receive the following 1566 object of type "application/cdni.HostIndex+xml": 1568 1569 1570 video.example.com 1571 1573 1574 1575 images.example.com 1576 1578 1579 1581 If the incoming request has a Host header with "video.example.com" 1582 then the downstream CDN would fetch from the next metadata object 1583 from "http://metadata.ucdn.example.com/video" expecting a MIME type 1584 of "application/cdni.HostMetadata+xml": 1586 1587 1588 application/cdni.SourceMetadata 1589 1590 1591 1593 acq1.ucdn.example.com 1594 ftp 1595 1596 1597 1599 acq2.ucdn.example.com 1600 http 1601 1602 1603 1604 1605 application/cdni.LocationACL 1606 1607 1608 1609 192.168.0.0/16 1611 1612 deny 1613 1614 1615 1616 1617 application/cdni.ProtocolACL 1618 1619 1620 ftp 1621 deny 1622 1623 1624 1625 1626 1627 /videos/trailers/*" 1628 1629 1631 1632 1633 1634 /videos/movies/*" 1635 1636 1638 1639 1641 Suppose the path of the requested resource matches the "/video/movies 1642 /*" pattern, the next metadata requested would be for "http:// 1643 metadata.ucdn.example.com/video/movies" with an expected type of 1644 "application/cdni.PathMetadata": 1646 1647 1648 1649 /videos/movies/hd/* 1650 1651 1653 1654 1655 Finally, if the path of the requested resource also matches the "/ 1656 videos/movies/hd/*" pattern, the downstream CDN would also fetch the 1657 following object from "http://metadata.ucdn.example.com/videos/movies 1658 /hd" with MIME type "application/cdni.PathMetadata": 1660 1661 1662 application/cdni.TimeWindowACL 1663 1664 1671 1672 1674 6.5. Extensibility 1676 The set of property Metadata may be extended with proprietary and/or 1677 custom property Metadata. The GenericMetadata object defined in 1678 Section 4.1.7 allows any Metadata property to be included in either 1679 the HostMetadata or PathMetadata lists. As described in Section 3.4, 1680 any proprietary and/or custom property Metadata SHOULD be identified 1681 by the "ext." prefix in an appropriately descriptive type which 1682 conveys the organization defining the property Metadata and the 1683 function of the property Metadata. 1685 Note: Identification of the property Metadata defining organization 1686 in the property Metadata type decreases the possibility of property 1687 Metadata type collision. The fully-qualified domain name of the 1688 organization in reverse order may be used for this purpose. 1690 6.5.1. Metadata Enforcement 1692 At any given time, the set of property Metadata supported by the uCDN 1693 may not match the set of property Metadata supported by the dCDN. 1694 The uCDN may or may not know which property Metadata the dCDN 1695 supports. In cases where the uCDN supports Metadata that the dCDN 1696 does not, the dCDN MUST be aware of any Metadata marked as 1697 "mandatory-to-enforce". If a CDN does not understand or is unable to 1698 perform the functions associated with any "mandatory-to-enforce" 1699 Metadata, the CDN MUST NOT service any requests for the corresponding 1700 content. 1702 Note: Ideally, uCDNs would not delegate content requests to a dCDN 1703 which does not support the mandatory-to-enforce Metadata associated 1704 with the content being requested. However, even if the uCDN has a 1705 priori knowledge of the Metadata supported by the dCDN (e.g., via the 1706 CDNI capabilities interface or through out-of-band negotiation 1707 between CDN operators) Metadata support may fluctuate or be 1708 inconsistent (e.g., due to mis-communication, mis-configuration, or 1709 temporary outage). Thus, the dCDN MUST evaluate all Metadata 1710 associated with content requests and reject any requests where 1711 "mandatory-to-enforce" Metadata associated with the content cannot be 1712 enforced. 1714 6.5.2. Metadata Override 1716 It is possible that new Metadata definitions may obsolete or override 1717 existing property Metadata (e.g., a future revision of the CDNI 1718 Metadata interface may redefine the Auth Metadata or a custom vendor 1719 extension may implement an alternate Auth Metadata option). If 1720 multiple Metadata (e.g., cdni.v2.Auth, ext.vendor1.Auth, and 1721 ext.vendor2.Auth) all override an existing Metadata (e.g., cdni.Auth) 1722 and all are marked as "mandatory-to-enforce", it may be ambiguous 1723 which Metadata should be applied, especially if the functionality of 1724 the Metadata conflict. 1726 As described in Section 3.3, Metadata override only applies to 1727 Metadata objects of the same exact type, found in HostMetadata and 1728 nested PathMetadata structures. The CDNI Metadata interface does not 1729 support enforcement of dependencies between different Metadata types. 1730 It is the responsibility of the CSP and the CDN operators to ensure 1731 that Metadata assigned to a given content do not conflict. 1733 Note: Because Metadata is inherently ordered in GenericMetadata 1734 lists, as well as in the PathMetadata hierarchy and PathMatch lists, 1735 multiple conflicting Metadata types MAY be used, however, Metadata 1736 hierarchies MUST ensure that independent PathMatch root objects are 1737 used to prevent ambiguous or conflicting Metadata definitions. 1739 6.6. Versioning 1741 The version of CDNI Metadata Structural objects is specified by the 1742 HTTP Content-Type header. Upon responding to a request for an 1743 object, a metadata server MUST include a Content-Type header with the 1744 MIME-type and verison number of the object. HTTP requests sent to a 1745 metadata server SHOULD include an Accept header with the MIME-type 1746 and version of the expected object. Unless stated otherwise, the 1747 verison of each object defined by this document is version 1. For 1748 example: "Content-Type: application/cdni.HostIndex.v1":. 1750 GenericMetadata objects include a "type" property which specifies the 1751 MIME-type of the GenericMetadata value. This MIME-type should also 1752 include a version. Any document which defines a new type of 1753 GenericMetadata should specify the version number which it describes. 1754 For example: "application/cdni.Location.v1". 1756 7. IANA Considerations 1758 This document requests the registration of the "application/cdni" 1759 MIME Media Type under the IANA MIME Media Type registry (http:// 1760 www.iana.org/assignments/media-types/index.html). 1762 [Ed. Need to consider a registry for Metadata type identifiers.] 1764 8. Security Considerations 1766 The CDNI Metadata Interface is expected to be secured as a function 1767 of the transport protocol (e.g. HTTP authentication [RFC2617], HTTPS 1768 [RFC2818], or inter-domain IPSec). 1770 If a malicious metadata server is contacted by a downstream CDN, the 1771 malicious server may provide metadata to the downstream CDN which 1772 denies service for any piece of content to any user agent. The 1773 malicious server may also provide metadata which directs a downstream 1774 CDN to a malicious origin server instead of the actual origin server. 1775 The dCDN is expected to authenticate the server to prevent this 1776 situation (e.g. by using HTTPS and validating the server's 1777 certificate). 1779 A malicious metadata client could request metadata for a piece of 1780 content from an upstream CDN. The metadata information may then be 1781 used to glean information regarding the uCDN or to contact an 1782 upstream origin server. The uCDN is expected to authenticate client 1783 requests to prevent this situation. 1785 9. Acknowledgements 1787 The authors would like to thank David Ferguson and Francois le 1788 Faucheur for their valuable comments and input to this document. 1790 10. References 1792 10.1. Normative References 1794 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1795 Requirement Levels", BCP 14, RFC 2119, March 1997. 1797 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1798 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1799 Authentication: Basic and Digest Access Authentication", 1800 RFC 2617, June 1999. 1802 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1804 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1805 Architecture", RFC 4291, February 2006. 1807 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1808 Address Text Representation", RFC 5952, August 2010. 1810 10.2. Informative References 1812 [I-D.ietf-cdni-framework] 1813 Peterson, L. and B. Davie, "Framework for CDN 1814 Interconnection", draft-ietf-cdni-framework-03 (work in 1815 progress), February 2013. 1817 [I-D.ietf-cdni-requirements] 1818 Leung, K. and Y. Lee, "Content Distribution Network 1819 Interconnection (CDNI) Requirements", draft-ietf-cdni- 1820 requirements-05 (work in progress), February 2013. 1822 [I-D.zyp-json-schema] 1823 Zyp, K. and G. Court, "A JSON Media Type for Describing 1824 the Structure and Meaning of JSON Documents", draft-zyp- 1825 json-schema-03 (work in progress), November 2010. 1827 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1828 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1829 3986, January 2005. 1831 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC 1832 4151, October 2005. 1834 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1835 Syndication Format", RFC 4287, December 2005. 1837 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 1838 Distribution Network Interconnection (CDNI) Problem 1839 Statement", RFC 6707, September 2012. 1841 [XML-BASE] 1842 Marsh, J., Ed. and R. Tobin, Ed., "XML Base (Second 1843 Edition) - http://www.w3.org/TR/xmlbase/", January 2009. 1845 Appendix A. Relationship to the CDNI Requirements 1847 Section 6 of [I-D.ietf-cdni-requirements] lists the requirements for 1848 the CDNI Metadata Distribution interface. This section outlines 1849 which of those requirements are met by the CDNI Metadata interface 1850 specified in this document. 1852 All metadata requirements are met either directly or indirectly by 1853 the CDNI Metadata Interface described in this document, with the 1854 clarifications or exceptions described in the following paragraphs. 1856 Requirements related to pre-positioning of metadata are met by this 1857 document on the assumption that other CDNI Interfaces are to be used 1858 by the upstream CDN to trigger the pre-positioning of metadata by the 1859 downstream CDN via the CDNI Metadata Interface. Triggering metadata 1860 pre-positioning is beyond the scope of the CDNI Metadata interface. 1861 However, the interface as described by this document supports pulling 1862 metadata on-demand for the purpose of pre-positioning. 1864 Requirement META-7 relating to modification of metadata by the 1865 upstream CDN is met both by allowing timeouts on the cacheability of 1866 metadata objects and by allowing other CDNI interfaces to initiate a 1867 refetch or purge of metadata. 1869 Requirement META-18 relating to surrogate cache behavior parameters 1870 is supported via extensibility. However, the example parameters in 1871 META-18 are not described in this document. 1873 Appendix B. Metadata Rewriting 1875 For some use cases, one CDN in a chain of interconnected CDNs must be 1876 able to rewrite CDNI Metadata received from its upstream CDN before 1877 presenting that CDNI Metadata to its downstream CDN. 1879 The CDN which is performing the metadata rewriting is referred to as 1880 the 'Transit' CDN (tCDN), its upstream CDN as the uCDN and its 1881 downstream CDN as the dCDN. 1883 Two (non-exhaustive) examples of when rewriting are: 1885 Allowing the dCDN is to acquire content from the tCDN instead of 1886 (or as well as) the uCDN. The tCDN must modify the appropriate 1887 CDNI Source Metadata objects to include itself as a possible 1888 source for the content. 1890 If the tCDN is transforming the original URI as part of CDNI 1891 request redirection on-route to the dCDN, the tCDN may need to 1892 modify the PatternMatch objects in any PathMetadata to take 1893 account of any URI path transformation it has performed. 1895 When performing HTTP redirection between CDNs, the dCDN must be able 1896 to map an UA request to a host and path which are meaningful to the 1897 tCDN. The dCDN needs only to identify its immediate upstream 1898 neighbor and does not need to map (or understand) the entire chain of 1899 CDNs that precede the tCDN. 1901 A dCDN may encode the identity of the tCDN in the URI it returns to 1902 the UA as part of request redirection (either directly or via the 1903 CDNI Request Routing Redirection interface). The exact method the 1904 dCDN uses to encode the information it requires is a local 1905 implementation decision provided it enables the dCDN to identify the 1906 correct upstream CDN (tCDN) and to map the request to the appropriate 1907 host and path so that the dCDN can find and retrieve the correct CDNI 1908 Metadata from tCDN. 1910 B.1. Example 1912 The example in this section is not necessarily representative of URL 1913 rewriting in practice. 1915 The UA requests the following URI from the uCDN: 1917 http://video.example/foo/bar 1919 The uCDN makes a CDNI Request Routing Redirection request to tCDN and 1920 tCDN returns a redirection URI of: 1922 http://tcdn.example/tcdn-prefix/foo/bar 1924 The tcdn-prefix/ encodes sufficient information for tCDN to identify 1925 uCDN as its upstream CDN neighbor. The tCDN makes a CDNI Request 1926 Routing Redirection request to dCDN and dCDN returns a redirection 1927 URI of: 1929 http://dcdn.example/dcdn-prefix/tcdn-prefix/foo/bar 1931 Therefore when dCDN receives a request for: 1933 http://dcdn.example/dcdn-prefix/tcdn-prefix/foo/bar 1934 The dCDN can use /dcdn-prefix/ to identify tCDN as its upstream CDN 1935 neighbor and reconstruct the URI tCDN expects. The tCDN can in turn 1936 use /tcdn-prefix/ to identify uCDN as its upstream CDN neighbour and 1937 reconstruct the URI uCDN expects. 1939 Authors' Addresses 1941 Ben Niven-Jenkins 1942 Velocix (Alcatel-Lucent) 1943 3 Ely Road 1944 Milton, Cambridge CB24 6AA 1945 UK 1947 Email: ben@velocix.com 1949 Rob Murray 1950 Velocix (Alcatel-Lucent) 1951 3 Ely Road 1952 Milton, Cambridge CB24 6AA 1953 UK 1955 Email: rmurray@velocix.com 1957 Grant Watson 1958 Velocix (Alcatel-Lucent) 1959 3 Ely Road 1960 Milton, Cambridge CB24 6AA 1961 UK 1963 Email: gwatson@velocix.com 1965 Matt Caulfield 1966 Cisco Systems 1967 1414 Massachusetts Avenue 1968 Boxborough, MA 01719 1969 USA 1971 Phone: +1 978 936 9307 1972 Email: mcaulfie@cisco.com 1973 Kent Leung 1974 Cisco Systems 1975 3625 Cisco Way 1976 San Jose 95134 1977 USA 1979 Phone: +1 408 526 5030 1980 Email: kleung@cisco.com 1982 Kevin J. Ma 1983 Azuki Systems, Inc. 1984 43 Nagog Park 1985 Acton, MA 01720 1986 USA 1988 Phone: +1 978-844-5100 1989 Email: kevin.ma@azukisystems.com