idnits 2.17.1 draft-ietf-cdni-metadata-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 5 characters in excess of 72. == There are 3 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 (February 25, 2013) is 4070 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 729, but not defined == Unused Reference: 'I-D.zyp-json-schema' is defined on line 1639, but no explicit reference was found in the text == Unused Reference: 'RFC4151' is defined on line 1649, but no explicit reference was found in the text == Unused Reference: 'RFC4287' is defined on line 1652, 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: August 29, 2013 Velocix (Alcatel-Lucent) 6 M. Caulfield 7 K. Leung 8 Cisco Systems 9 K. Ma 10 Azuki Systems, Inc. 11 February 25, 2013 13 CDN Interconnect Metadata 14 draft-ietf-cdni-metadata-01 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 29, 2013. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . 12 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 . . . . . . . . . . . . . . . . . . . 14 83 4.2. CDNI Metadata Property Object Descriptions . . . . . . . . 15 84 4.2.1. Source Metadata . . . . . . . . . . . . . . . . . . . 15 85 4.2.1.1. Source . . . . . . . . . . . . . . . . . . . . . . 15 86 4.2.2. LocationACL Metadata . . . . . . . . . . . . . . . . . 15 87 4.2.2.1. LocationRule . . . . . . . . . . . . . . . . . . . 16 88 4.2.2.2. Location . . . . . . . . . . . . . . . . . . . . . 16 89 4.2.3. TimeWindowACL Metadata . . . . . . . . . . . . . . . . 16 90 4.2.3.1. TimeWindowRule . . . . . . . . . . . . . . . . . . 17 91 4.2.3.2. TimeWindow . . . . . . . . . . . . . . . . . . . . 17 92 4.2.4. ProtocolACL Metadata . . . . . . . . . . . . . . . . . 17 93 4.2.4.1. ProtocolRule . . . . . . . . . . . . . . . . . . . 17 94 4.2.5. Authorization Metadata . . . . . . . . . . . . . . . . 18 95 4.2.6. Auth . . . . . . . . . . . . . . . . . . . . . . . . . 18 96 4.2.7. Cache . . . . . . . . . . . . . . . . . . . . . . . . 19 97 4.2.8. Logging . . . . . . . . . . . . . . . . . . . . . . . 19 98 4.3. CDNI Metadata Simple Data Type Descriptions . . . . . . . 19 99 4.3.1. Link . . . . . . . . . . . . . . . . . . . . . . . . . 19 100 4.3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . . 19 101 4.3.3. RedirectionMethod . . . . . . . . . . . . . . . . . . 20 102 4.3.4. Endpoint . . . . . . . . . . . . . . . . . . . . . . . 20 103 4.3.5. IPRange . . . . . . . . . . . . . . . . . . . . . . . 20 104 4.3.6. URI . . . . . . . . . . . . . . . . . . . . . . . . . 20 105 4.3.7. Time . . . . . . . . . . . . . . . . . . . . . . . . . 20 106 5. CDNI Metadata Capabilities . . . . . . . . . . . . . . . . . . 21 107 5.1. Protocol ACL Capabilities . . . . . . . . . . . . . . . . 21 108 5.2. Authorization Metadata Capabilities . . . . . . . . . . . 22 109 5.3. Host Metadata Capabilities . . . . . . . . . . . . . . . . 22 110 6. CDNI Metadata interface . . . . . . . . . . . . . . . . . . . 22 111 6.1. Transport . . . . . . . . . . . . . . . . . . . . . . . . 23 112 6.2. Retrieval of CDNI Metadata resources . . . . . . . . . . . 23 113 6.3. Bootstrapping . . . . . . . . . . . . . . . . . . . . . . 24 114 6.4. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . 25 115 6.4.1. MIME Media Types . . . . . . . . . . . . . . . . . . . 25 116 6.4.2. JSON Encoding of Objects . . . . . . . . . . . . . . . 26 117 6.4.2.1. JSON Example . . . . . . . . . . . . . . . . . . . 26 118 6.4.3. XML Encoding of Objects . . . . . . . . . . . . . . . 30 119 6.4.3.1. XML Example . . . . . . . . . . . . . . . . . . . 30 120 6.5. Extensibility . . . . . . . . . . . . . . . . . . . . . . 33 121 6.5.1. Metadata Enforcement . . . . . . . . . . . . . . . . . 33 122 6.5.2. Metadata Override . . . . . . . . . . . . . . . . . . 34 123 6.6. Versioning . . . . . . . . . . . . . . . . . . . . . . . . 34 124 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 125 8. Security Considerations . . . . . . . . . . . . . . . . . . . 35 126 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 35 127 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35 128 10.1. Normative References . . . . . . . . . . . . . . . . . . . 35 129 10.2. Informative References . . . . . . . . . . . . . . . . . . 36 130 Appendix A. Relationship to the CDNI Requirements . . . . . . . . 36 131 Appendix B. Metadata Rewriting . . . . . . . . . . . . . . . . . 37 132 B.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 38 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 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. 158 o Content Requests received directly from User Agents. 160 Specifically this document proposes: 162 o A data structure for mapping content requests to CDNI Metadata 163 properties (Section 3). 164 o An initial set of CDNI Metadata properties (Section 4.2). 165 o A RESTful web service for the transfer of CDNI Metadata 166 (Section 6). 168 1.1. Terminology 170 This document reuses the terminology defined in [RFC6707]. 172 Additionally, the following terms are used throughout this document 173 and are defined as follows: 174 o Object - a collection of properties 175 o Property - a key and value pair where the key is a property name 176 and the value is the property value or an object. 178 2. Design Principles 180 The proposed CDNI Metadata Interface was designed to achieve the 181 following objectives: 183 1. Cacheability of CDNI metadata objects 184 2. Deterministic mapping from redirection and content requests to 185 CDNI metadata properties 186 3. Support for DNS redirection as well as application-specific 187 redirection (for example HTTP redirection) 188 4. Minimal duplication of CDNI metadata 189 5. Leverage existing protocols 191 Cacheability improves the latency of acquiring metadata while 192 maintaining its freshness and therefore improves the latency of 193 serving content requests. The CDNI Metadata Interface uses HTTP to 194 achieve cacheability. 196 Deterministic mappings from content to metadata properties eliminates 197 ambiguity and ensures that policies are applied consistently by all 198 downstream CDNs. 200 Support for both HTTP and DNS redirection ensures that the CDNI 201 Metadata Interface can be used for HTTP and DNS redirection and also 202 meets the same design principles for both HTTP and DNS based 203 redirection schemes. 205 Minimal duplication of CDNI metadata provides space efficiency on 206 storage in the CDNs, on caches in the network, and across the network 207 between CDNs. 209 Leveraging existing protocols avoids reinventing common mechanisms 210 such as data structure encoding (e.g. XML, JSON) and data transport 211 (e.g. HTTP). 213 3. CDNI Metadata Data Model 215 The CDNI Metadata Model describes a data structure for mapping 216 redirection requests and content requests to metadata properties. 217 Metadata properties describe how to acquire, authorize, and deliver 218 content from a downstream CDN. The data model relies on the 219 assumption that these metadata properties may be aggregated based on 220 the hostname of the content and subsequently on the resource path of 221 the content. The data model associates a set of CDNI Metadata 222 properties with a Hostname to form a default set of metadata 223 properties for content delivered for that Hostname. That default set 224 of metadata properties can be overridden by properties that apply to 225 specific paths within a URI. 227 Different Hostnames and URI paths will be associated with different 228 sets of CDNI Metadata properties in order to describe the required 229 behaviour when a dCDN surrogate is processing User Agent requests for 230 content at that Hostname or URI path. As a result of this structure, 231 significant commonality may exist between the CDNI Metadata 232 properties specified for different Hostnames, different URI paths 233 within a Hostname and different URI paths on different Hostnames. 234 For example the definition of which User Agent IP addresses should be 235 treated as being grouped together into a single network or geographic 236 location is likely to be common for a number of different Hostnames. 237 Another example is that although a uCDN is likely to have several 238 different policies configured to express geo-blocking rules, it is 239 likely that a single geo-blocking policy would be applied to multiple 240 Hostnames delivered through the CDN. 242 In order to enable the CDNI Metadata for a given Hostname or URI Path 243 to be decomposed into sets of CDNI Metadata properties that can be 244 reused by multiple Hostnames and URI Paths, the CDNI Metadata 245 interface specified in this document splits the CDNI Metadata into a 246 number of objects. Efficiency is improved by enabling a single CDNI 247 Metadata object (that is shared across Hostname and/or URI paths) to 248 be retrieved by a dCDN once, even if it is referenced by the CDNI 249 Metadata of multiple Hostnames. 251 Section 3.1 introduces a high level description of the HostIndex, 252 HostMetadata and PathMetadata objects and describes the relationships 253 between those objects. 255 Section 3.2 introduces a high level description of the CDNI 256 GenericMetadata object which represents the level at which CDNI 257 Metadata override occurs between HostMetadata and PathMetadata 258 objects. 260 Section 4 describes in detail the specific CDNI Metadata objects and 261 properties which may be contained within a CDNI GenericMetadata 262 object. 264 3.1. HostIndex, HostMetadata & PathMetadata objects 266 A HostIndex object contains a list of Hostnames (and/or IP addresses) 267 for which content requests may be delegated to the downstream CDN. 268 The HostIndex is the starting point for accessing the uCDN's CDNI 269 Metadata data store. It enables surrogates in the dCDN to 270 deterministically discover, on receipt of a User Agent request for 271 content, which other CDNI Metadata objects it requires in order to 272 deliver the requested content. 274 The HostIndex links Hostnames (and/or IP addresses) to HostMetadata 275 objects via HostMatch objects. HostMetadata objects contain (or 276 reference) the default CDNI Metadata required to serve content for 277 that host. When looking up CDNI Metadata, the downstream CDN looks 278 up the requested Hostname (or IP address) in the HostIndex, from 279 there it can find HostMetadata which describes properties for a host 280 and PathMetadata which may override those properties for given URI 281 paths within the host. 283 As well as containing the default CDNI Metadata for the specified 284 Hostname, HostMetadata and PathMetadata objects may also contain 285 PathMatch objects which in turn contain PathMetadata objects. 286 PathMatch objects override the CDNI Metadata in the HostMetadata 287 object or one or more preceding PathMetadata objects with more 288 specific CDNI Metadata that applies to content requests matching the 289 pattern defined in that PathMatch object. 291 For the purposes of retrieving CDNI Metadata all other required CDNI 292 Metadata objects and their properties are discoverable from the 293 appropriate HostMetadata, PathMatch and PathMetadata objects for the 294 requested content. 296 The relationships between the HostIndex, HostMatch, HostMetadata, 297 PathMatch and PathMetadata objects are described in Figure 1. 299 +---------+ +---------+ +------------+ 300 |HostIndex+-(*)->|HostMatch|-(1)->|HostMetadata+-------(*)------+ 301 +---------+ +---------+ +------+-----+ | 302 | | 303 (*) | 304 | | 305 --> References V V 306 (1) One and only one +---------+ ************************** 307 (*) Zero or more +--->|PathMatch| *Generic Metadata Objects* 308 | +---------+ ************************** 309 | | ^ 310 (*) (1) | 311 | | | 312 | V | 313 | +------------+ | 314 +--|PathMetadata+-------(*)------+ 315 +------------+ 317 Key: ----> = References 319 Figure 1: Relationships between the HostIndex, HostMetadata & 320 PathMetadata CDNI Metadata Objects 322 The relationships in Figure 1 are summarised in Table 1 below. 324 +--------------+----------------------------------------------------+ 325 | Data Object | Objects it References | 326 +--------------+----------------------------------------------------+ 327 | HostIndex | 0 or more HostMatch objects. | 328 | HostMatch | 1 HostMetadata object. | 329 | HostMetadata | 0 or more PathMatch objects. 0 or more | 330 | | GenericMetadata objects. | 331 | PathMatch | 1 PathMetadata object. | 332 | PathMetadata | 0 or more PathMatch objects. 0 or more | 333 | | GenericMetadata objects. | 334 +--------------+----------------------------------------------------+ 336 Table 1: Relationships between CDNI Metadata Objects 338 The table below describes the HostIndex, HostMetadata and 339 PathMetadata objects in more detail. 341 +-----------------+-------------------------------------------------+ 342 | Data Object | Description | 343 +-----------------+-------------------------------------------------+ 344 | HostIndex | A HostIndex object lists HostMatch objects | 345 | HostMatch | A HostMatch object defines a hostname to match | 346 | | against a requested host, and contains or | 347 | | references a HostMetadata object which contains | 348 | | CDNI Metadata objects to be applied when a | 349 | | request matches against the hostname. For | 350 | | example, if "example.com" is a content | 351 | | provider, a HostMatch object may include an | 352 | | entry for "example.com" with the URI of the | 353 | | associated HostMetadata object. | 354 | HostMetadata | A HostMetadata object contains (or references) | 355 | | the default CDNI Metadata objects for content | 356 | | served from that host, i.e. the CDNI Metadata | 357 | | objects for content requests that do not match | 358 | | any of the PathMatch objects contained or | 359 | | referenced by that HostMetadata object. For | 360 | | example, a HostMetadata object may describe the | 361 | | metadata properties which apply to | 362 | | "example.com" and may contain PathMatches for | 363 | | "example.com/movies/*" and | 364 | | "example.com/music/*" which reference | 365 | | corresponding PathMetadata objects that contain | 366 | | the CDNI Metadata objects for those more | 367 | | specific URI paths. | 368 | PathMatch | A PathMatch object defines a pattern to match | 369 | | against the requested URI path, and contains or | 370 | | references a PathMetadata object which contains | 371 | | (or references) the CDNI Metadata objects to be | 372 | | applied when a content request matches against | 373 | | the defined URI path pattern. | 374 | PathMetadata | A PathMetadata object contains the CDNI | 375 | | GenericMetadata objects for content served with | 376 | | the associated URI path (defined in a PathMatch | 377 | | object). A PathMetadata object may also | 378 | | contain PathMatch objects in order to | 379 | | recursively define more specific URI paths that | 380 | | require different (e.g. more specific) CDNI | 381 | | Metadata to this one. For example, the | 382 | | PathMetadata object which applies to | 383 | | "example.com/movies/*" may describe CDNI | 384 | | Metadata which apply to that resource path and | 385 | | may contain a PathMatch object for | 386 | | "example.com/movies/hd/*" which would reference | 387 | | the corresponding PathMetadata object for the | 388 | | "example.com/movies/hd/" path prefix. | 389 | GenericMetadata | A GenericMetadata object contains individual | 390 | | CDNI Metadata objects which define the specific | 391 | | policies and attributes needed to properly | 392 | | deliver the associated content. | 393 +-----------------+-------------------------------------------------+ 395 Table 2: HostIndex, HostMetadata and PathMetadata CDNI Metadata 396 Objects 398 3.2. Generic CDNI Metadata Object Properties 400 The HostMetadata and PathMetadata objects contain or can reference 401 other CDNI Metadata objects that contain properties which describe 402 how User Agent requests for content should be processed, for example 403 where to acquire the content, authorization rules that should be 404 applied, delivery location restrictions and so on. Each such CDNI 405 Metadata object is a specialization of a CDNI GenericMetadata object. 406 The GenericMetadata object abstracts the basic information required 407 for Metadata override and opaque Metadata distribution, from the 408 specifics of any given property (e.g., property semantics, 409 enforcement options, etc.). 411 The GenericMetadata object defines the type of properties contained 412 within it as well as whether or not the properties are mandatory to 413 enforce. If the dCDN does not understand or support the property 414 type and the property type is mandatory to enforce, the dCDN MUST NOT 415 serve the content to the User Agent. If the dCDN does not understand 416 or support the property type it is also not going to be able to 417 properly propagate the Metadata for cascaded distribution. If the 418 dCDN does not understand or support the property type and the 419 property type is not mandatory to enforce, then the GenericMetadata 420 object may be safely ignored. 422 Although a CDN cannot serve content to a User Agent if a mandatory 423 property cannot be enforced, it may be safe to redistribute that 424 metadata to another CDN without modification. For example, in the 425 cascaded CDN case, a transit CDN may pass through mandatory-to- 426 enforce metadata to the delivery CDN. For Metadata which does not 427 require customization, the data representation received off the wire 428 MAY be stored and redistributed without being natively understood or 429 supported by the transit CDN. However, for Metadata which require 430 translations, transparent redistribution of the uCDN Metadata values 431 may not be appropriate. Certain Metadata may be safely, though 432 possibly not optimially, redistributed unmodified, e.g., source 433 acquisition address may not be optimal if transparently 434 redistributed, but may still work. Redistribution safety MUST be 435 specified for each GenericMetadata. 437 3.3. Metadata Inheritance and Override 439 In the data model, a HostMetadata object may contain (or reference) 440 multiple PathMetadata objects (via PathMatch objects). Each 441 PathMetadata object may in turn contain (or reference) other 442 PathMetadata objects. HostMetadata and PathMetadata objects form an 443 inheritance tree where each node in the tree inherits or overrides 444 the property values set by its parent. 446 GenericMetadata objects of a given type override all GenericMetadata 447 objects of the same type previously defined by any parent object in 448 the tree. GenericMetadata objects of a given type previously defined 449 by a parent object in the tree are inherited when no object of the 450 same type is defined by the child object. For example, if 451 HostMetadata for the host "example.com" contains GenericMetadata 452 objects of type LocationACL and TimeWindowACL, while a PathMetadata 453 object which applies to "example.com/movies/*" defines an alternate 454 GenericMetadata object of type TimeWindowACL, then: 455 the TimeWindowACL defined in the PathMetadata would override the 456 TimeWindowACL defined in the HostMetadata 457 the LocationACL defined in the HostMetadata would be inherited for 458 all User Agent requests for content under "example.com/movies". 459 The PathMetadata defined TimeWindowACL would override the 460 TimeWindowACL defined in the HostMetadata for all User Agent requests 461 for movies. 463 3.4. Metadata Naming 465 GenericMetadata objects are identified by their type. The type 466 SHOULD be descriptive, and MAY be hierarchical to support aggregating 467 groups of properties for the purpose of readability and for avoiding 468 name conflicts between vendor extensions. A dotted alpha-numeric 469 notation is suggested for human readability. 471 Metadata types defined by this document are not hierarchical. 473 Examples of GenericMetadata object type names: 474 LocationACL 475 ext.vendor1.featurex 476 ext.vendor1.featurey 477 ext.vendor2.featurex 479 [Ed. It is intended that Metadata capability advertisements will 480 allow either individual Metadata names or Metadata bundle identifiers 481 to be used. Need to have a procedure for defining and distributing 482 bundle information to be used in Metadata capability advertisement.] 484 4. Encoding-Independent CDNI Metadata Object Descriptions 486 Section 4.1 provides the definitions of each object type declared in 487 Section 3. These objects are described as structural objects as they 488 provide the structure for the inheritance tree and identifying which 489 specific properties apply to a given User Agent content request. 491 Section 4.2 provides the definitions for the set of core metadata 492 objects which may be contained within a GenericMetadata object. 493 These objects are described as property objects as they define the 494 semantics, enforcement options, and serialization rules for specific 495 properties. These properties govern how User Agent requests for 496 content are handled. Property objects may be composed of or contain 497 references to other objects. In those cases the value of the 498 property can be either an object of that type (the object is 499 embedded) or a Link object that contains a URI and relationship that 500 can be dereferenced to retrieve the CDNI Metadata object that 501 represents the value of that property. 503 Note: In the following sections, the term "mandatory-to-specify" is 504 used to convey which objects or properties must be specified for a 505 given parent object or property. When mandatory-to-specify is set to 506 true, it implies that if the parent object is specified, then the 507 defined object or property MUST also be specified, e.g., a HostMatch 508 object without a host to match against does not make sense, 509 therefore, the host is mandatory-to-specify inside a parent HostMatch 510 object. 512 4.1. CDNI Metadata Structural Object Descriptions 514 Each of the sub-sections below describe the structural objects 515 defined in Table 2. 517 4.1.1. HostIndex 519 The HostIndex object is the entry point into the CDNI Metadata 520 hierarchy. It contains a list of HostMatch objects. An incoming 521 content request is matched against the hostname inside of each of the 522 listed HostMatch objects to find the HostMatch object which applies 523 to the request. 525 Property: hosts 526 Description: List of HostMatch objects, in priority order. 527 Type: List of HostMatch objects 528 Mandatory-to-Specify: Yes. 530 4.1.2. HostMatch 532 The HostMatch object contains a hostname or IP address to match 533 against content requests. The HostMatch object also contains a 534 reference to Metadata objects to apply if a match is found. 536 Property: host 537 Description: String (hostname or IP address) to match against 538 the requested host. 539 Type: String 540 Mandatory-to-Specify: Yes. 541 Property: host-metadata 542 Description: CDNI Metadata to apply when delivering content 543 that matches this host. 544 Type: HostMetadata 545 Mandatory-to-Specify: Yes. 547 4.1.3. HostMetadata 549 The HostMetadata object contains both Metadata that applies to 550 content requests for a particular host and a list of pattern matches 551 for finding more specific Metadata based on the resource path in a 552 content request. 554 Property: metadata 555 Description: List of host related metadata. 557 Type: List of GenericMetadata objects 558 Mandatory-to-Specify: Yes. 559 Property: paths 560 Description: Path specific rules. First match applies. 561 Type: List of PathMatch objects 562 Mandatory-to-Specify: No. 563 Property: modes 564 Description: Defines which redirection methods are supported. 565 Type: List of RedirectionMethod 566 Mandatory-to-Specify: Yes. 568 4.1.4. PathMatch 570 The PathMatch object contains an expression given as a PatternMatch 571 object to match against a resource URI path and Metadata objects to 572 apply if a match is found. 574 Property: path-pattern 575 Description: Pattern to match against the requested path, i.e. 576 against the [RFC3986] path-absolute. 577 Type: PatternMatch 578 Mandatory-to-Specify: Yes. 579 Property: path-metadata 580 Description: CDNI Metadata to apply when delivering content 581 that matches this pattern. 582 Type: PathMetadata 583 Mandatory-to-Specify: Yes. 585 4.1.5. PathMetadata 587 A PathMetadata object contains the CDNI Metadata properties for 588 content served with the associated URI path (defined in a PathMatch 589 object). Note that if CDNI metadata is used as an input to CDNI 590 request routing and DNS-based redirection is employed, then any 591 metadata at the PathMetadata level or below will be inaccessible at 592 request routing time. 594 Property: metadata 595 Description: List of path related metadata. 596 Type: List of GenericMetadata objects 597 Mandatory-to-Specify: Yes. 598 Property: paths 599 Description: Path specific rules. First match applies. 600 Type: List of PathMatch objects 601 Mandatory-to-Specify: No. 603 4.1.6. PatternMatch 605 A PatternMatch object contains the pattern string and flags that 606 describe the PathMatch expression. 608 Property: pattern 609 Description: A pattern for string matching. The pattern may 610 contain the wildcards * and ?, where * matches any sequence of 611 characters (including the empty string) and ? matches exactly 612 one character. The three literals \ , * and ? should be 613 escaped as \\, \* and \? 614 Type: String 615 Mandatory-to-Specify: Yes. 616 Property: case-sensitive 617 Description: Flag indicating whether or not case-sensitive 618 matching should be used. 619 Type: Boolean 620 Mandatory-to-Specify: No. Default is case-insensitive match. 621 Property: match-query-string 622 Description: Flag indicating whether or not the query string 623 should be included in the pattern match. 624 Type: Boolean 625 Mandatory-to-Specify: No. Default is not to include query 626 strings when matching. 628 4.1.7. GenericMetadata 630 A GenericMetadata object is a abstraction for managing individual 631 CDNI Metadata properties in an opaque manner. 633 Property: type 634 Description: CDNI Metadata property object type. 635 Type: String 636 Mandatory-to-Specify: Yes. 637 Property: value 638 Description: CDNI Metadata property object. 639 Type: matches the type property above 640 Mandatory-to-Specify: Yes. 641 Property: mandatory-to-enforce 642 Description: Flag identifying whether or not the enforcement of 643 the property Metadata is required. 644 Type: Boolean 645 Mandatory-to-Specify: Yes. 646 Property: safe-to-redistribute 647 Description: Flag identifying whether or not the property 648 Metadata may be safely redistributed without modification. 650 Type: Boolean 651 Mandatory-to-Specify: No. Default is allow transparent 652 redistribution. 654 4.2. CDNI Metadata Property Object Descriptions 656 4.2.1. Source Metadata 658 Source Metadata provides the dCDN information about content 659 acquisition e.g. how to contact an uCDN Surrogate or an Origin Server 660 to obtain the content to be served. The sources are not necessarily 661 the actual Origin Servers operated by the CSP but might be a set of 662 Surrogates in the uCDN. 664 Property: sources 665 Description: Sources from which the dCDN can acquire content, 666 listed in priority order. 667 Type: List of Source objects 668 Mandatory-to-Specify: No. Default is to use static 669 configuration, out of band of the metadata interface. 671 4.2.1.1. Source 673 A Source object describes the Source which should be used by the dCDN 674 for content acquisition, e.g. a Surrogate within the uCDN or an 675 alternate Origin Server, the protocol to be used and any 676 authentication method. 678 Property: auth 679 Description: Authentication method to use when requesting 680 content from this source. 681 Type: Auth 682 Mandatory-to-Specify: No. Default is no authentication is 683 required. 684 Property: endpoints 685 Description: Origins from which the dCDN can acquire content. 686 Type: List of EndPoint objects 687 Mandatory-to-Specify: Yes. 689 4.2.2. LocationACL Metadata 691 LocationACL Metadata defines location-based restrictions. 693 Property: locations 694 Description: Access control list which applies restrictions to 695 delivery based on client location. 697 Type: List of LocationRule objects 698 Mandatory-to-Specify: No. Default is allow all locations. 700 4.2.2.1. LocationRule 702 A LocationRule contains or references a list of Location objects and 703 the corresponding action. 705 Property: locations 706 Description: List of locations to which the rule applies. 707 Type: List of Location objects 708 Mandatory-to-Specify: Yes. 709 [Ed: reusing locations as a property name is confusing and should 710 likely be changed] 711 Property: action 712 Description: Defines whether the rule specifies locations to 713 allow or deny. 714 Type: Enumeration [allow|deny] 715 Mandatory-to-Specify: No. Default is deny. 717 4.2.2.2. Location 719 A Location object describes a Location which may be applied by a 720 LocationRule, e.g. a Location may be an IPv4 address range or a 721 geographic location. 723 Property: iprange 724 Description: A set of IP Addresses. 725 Type: List of IPRange objects 726 Mandatory-to-Specify: Yes. 728 [Ed: Location as specified above only supports the Class 1a names 729 described in [I-D.jenkins-cdni-names]. Need to add support for Class 730 1b names to a later version.] 732 4.2.3. TimeWindowACL Metadata 734 TimeWindowACL Metadata defines time-based restrictions. 736 Property: times 737 Description: Access control list which applies restrictions to 738 delivery based on request time. 739 Type: List of TimeWindowRule objects 740 Mandatory-to-Specify: No. Default is allow all time windows. 742 4.2.3.1. TimeWindowRule 744 A TimeWindowRule contains or references a list of TimeWindow objects 745 and the corresponding action. 747 Property: times 748 Description: List of time windows to which the rule applies. 749 Type: List of TimeWindow objects 750 Mandatory-to-Specify: Yes. 751 Property: action 752 Description: Defines whether the rule specifies time windows to 753 allow or deny. 754 Type: Enumeration [allow|deny] 755 Mandatory-to-Specify: No. Default is deny. 757 4.2.3.2. TimeWindow 759 A TimeWindow object describes a time range which may be applied by an 760 ACLRule, e.g. Start 09:00AM 01/01/2000 UTC End 17:00PM 01/01/2000 761 UTC. 763 Property: start 764 Description: The start time of the window. 765 Type: Time 766 Mandatory-to-Specify: Yes. 767 Property: end 768 Description: The end time of the window. 769 Type: Time 770 Mandatory-to-Specify: Yes. 772 4.2.4. ProtocolACL Metadata 774 ProtocolACL Metadata defines delivery protocol restrictions. 776 Property: protocols 777 Description: Access control list which applies restrictions to 778 delivery based on delivery protocol. 779 Type: List of ProtocolRule objects 780 Mandatory-to-Specify: No. Default is allow all protocols. 782 4.2.4.1. ProtocolRule 784 A ProtocolRule contains or references a list of Protocol objects. 785 ProtocolRule objects are used to construct a ProtocolACL to apply 786 restrictions to content acquisition or delivery. 788 Property: protocols 789 Description: List of protocols to which the rule applies. 790 Type: List of protocol objects 791 Mandatory-to-Specify: Yes. 792 Property: action 793 Description: Defines whether the rule specifies protocols to 794 allow or deny. 795 Type: Enumeration [allow|deny] 796 Mandatory-to-Specify: No. Default is allow all protocols. 797 Property: direction 798 Description: Defines whether the ProtocolRule specifies 799 protocols for acquisition or delivery. 800 Type: Enumeration [acquisition|delivery] 801 Mandatory-to-Specify: No. Default is to apply the rule to both 802 acquisition and delivery. 804 4.2.5. Authorization Metadata 806 Authorization Metadata define content authorization methods. 808 Property: methods 809 Description: Options for authenticating content requests. All 810 options in the list are equally valid. 811 Type: List of Auth objects 812 Mandatory-to-Specify: No. Default is no authorization 813 required. 815 4.2.6. Auth 817 An Auth object defines authentication and authorization methods to be 818 used during content delivery and content acquisition, e.g. methods 819 such as tokenization and URL Signing. 821 [Ed. Need to synchronize authentication configuration with CDNI URL 822 signing draft definitions.] 824 [Ed. Need to consider how to separate protocol specific method 825 configuration (e.g., HTTP basic/digest authentication), which must 826 match the HostMatch protocol, from protocol agnostic method 827 configurations (e.g., URL signing/tokenization).] 829 Property: direction 830 Description: Defines whether the Auth object applies to 831 acquisition or delivery requests. 832 Type: Enumeration [acquisition|delivery] 833 Mandatory-to-Specify: No. Default is to apply the rule to both 834 acquisition and delivery. 836 4.2.7. Cache 838 [Ed. note: placeholder for cache control metadata - TBD] 840 4.2.8. Logging 842 [Ed. note: placeholder for logging metadata - TBD] 844 4.3. CDNI Metadata Simple Data Type Descriptions 846 This section describes the simpler data types that are used for 847 properties of CDNI Metadata objects. 849 4.3.1. Link 851 A link object may be used in place of any of the objects or 852 properties described above. Links can be used to avoid duplication 853 if the same metadata information is repeated within the metadata 854 tree. When a link replaces an object, its href property is set to 855 the URI of the resource, its rel property is set to the name of the 856 property it is replacing, and its type property is set to the type of 857 the object it is replacing. 859 Property: href 860 Description: The URI of the of the addressable object being 861 referenced. 862 Type: URI 863 Mandatory: Yes 864 Property: rel 865 Description: The Relationship between the referring object and 866 the object it is referencing. 867 Type: String 868 Mandatory: Yes 869 Property: type 870 Description: The type of the object being referenced. 871 Type: String 872 Mandatory: Yes 874 4.3.2. Protocol 876 Protocol objects are used to specify registered protocols for content 877 acquisition or delivery. 879 [Ed. Need to reference protocol registry.] 881 Type: Enumeration [HTTP|RTSP|RTMP] 883 4.3.3. RedirectionMethod 885 RedirectionMethod objects are used to specify registered content 886 redirection modes. 888 [Ed. Need to reference redirection method registry.] 890 Type: Enumeration [HTTP-I|HTTP-R|DNS-I|DNS-R] 892 4.3.4. Endpoint 894 A hostname (with optional port) or an IP address (with optional 895 port). 897 Note: All implementations MUST support IPv4 addresses encoded as 898 specified by the 'IPv4address' rule in Section 3.2.2 of [RFC3986] and 899 MUST support all IPv6 address formats specified in [RFC4291]. Server 900 implementations SHOULD use IPv6 address formats specified in 901 [RFC5952]. 903 4.3.5. IPRange 905 One of: 907 o A range of consecutive IP addresses (IPv4 or IPv6) expressed as 908 Address1-Address2 which does not have to be to power of two 909 aligned, for example the range 192.0.2.1-192.0.2.10 is valid. The 910 first Address in the range MUST be 'lower' than the final address 911 in the range. 912 o A valid IP subnet (IPv4 or IPv6) expressed using CIDR notation. 913 o A single IP address (IPv4 or IPv6). 915 Note: Client implementations MUST support IPv4 addresses encoded as 916 specified by the 'IPv4address' rule in Section 3.2.2 of [RFC3986] and 917 MUST support all IPv6 address formats specified in [RFC4291]. Server 918 implementations SHOULD use IPv6 address formats specified in 919 [RFC5952]. 921 4.3.6. URI 923 A URI as specified in [RFC3986]. 925 4.3.7. Time 927 A time value expressed in seconds since Unix epoch in the UTC 928 timezone. 930 5. CDNI Metadata Capabilities 932 CDNI Metadata is used to convey information pertaining to content 933 delivery from uCDN to dCDN. For optional metadata, it may be useful 934 for the uCDN to know if the dCDN supports the metadata, prior to 935 delegating any content requests to the dCDN. If optional-to- 936 implement metadata is mandatory-to-enforce and the dCDN does not 937 support it, any delegated requests for that content will fail, so 938 there is no reason to delegate those requests. Likewise, for any 939 metadata which may be assigned optional values, it may be useful for 940 the uCDN to know which values the dCDN supports, prior to delegating 941 any content requests to the dCDN. If a the optional value assigned 942 to a given piece of content's metadata is not supported by the dCDN, 943 any delegated requests for that content may fail, so there is likely 944 no reason to delegate those requests. 946 The CDNI Footprint and Capabilities Interface provides a means of 947 advertising capabilities from dCDN to uCDN. Support for optional 948 metadata and support for optional metadata values may be advertised 949 using the capabilities interface. This section describes the 950 capabilities advertisement requirements for the metadata defined in 951 Section 4.2 953 5.1. Protocol ACL Capabilities 955 The ProtoclACL object contains a list of Protocol values. The dCDN 956 MUST advertise which delivery protocols it supports so that the uCDN 957 knows what type of content requests it can redirect to the dCDN. If 958 the dCDN does not support a given acquisition or delivery protocol, 959 the uCDN should not delegate requests requiring those protocols to 960 the dCDN as the dCDN will not be able to properly acquire or deliver 961 the content. 963 ProtocolRules are defined for either acquisition or delivery. For 964 some CDNs, certain combinations of acquisition and delivery protocols 965 may not make sense (e.g., RTSP acquisition for HTTP delivery), while 966 other CDNs may support customized protocol adaptation. ProtocolACL 967 capabilities are not intended to define which combinations of 968 protocols should be used. ProtocolACL capabilties are only intended 969 to describe which protocols the dCDN does or does not support. 970 Protocol combination restrictions are specified in the metadata 971 itself and associated with specific groups of content assets. 973 [Ed. Need to register delivery protocol capability ID.] 975 [Ed. Need to reference protocol registry, and discuss specification 976 of overlapping protocol values.] 978 5.2. Authorization Metadata Capabilities 980 The Authorization object contains a list of Auth values. The dCDN 981 MUST advertise which authorization algorithms it supports so that the 982 uCDN knows what type of content requests it can redirect to the dCDN. 983 If the dCDN does not support a given authorization algorithm, the 984 uCDN should not delegate requests requiring that algorithm to the 985 dCDN as the dCDN will not be able to properly acquire the content or 986 enforce delivery restrictions. 988 [Ed. Need to register authorization algorithm capability ID.] 990 [Ed. Need to reference auth registry, and discuss specification of 991 overlapping auth values.] 993 5.3. Host Metadata Capabilities 995 The HostMetadata object contains a list of redirection method values. 996 The dCDN MUST advertise which redirection modes it supports so that 997 the uCDN knows how to redirect content requests to the dCDN. If the 998 dCDN does not support a given redirection method, the uCDN should not 999 delegate requests to the dCDN using that method as the dCDN will not 1000 be able to properly handle the redirection. 1002 [Ed. Need to register redirection method capability ID.] 1004 [Ed. Need to reference redirection method registry.] 1006 6. CDNI Metadata interface 1008 This section specifies an interface to enable a Downstream CDN to 1009 retrieve CDNI Metadata objects from an Upstream CDN. 1011 The interface can be used by a Downstream CDN to retrieve CDNI 1012 Metadata objects either dynamically as required by the Downstream CDN 1013 to process received requests (for example in response to receiving a 1014 CDNI Request Routing request from an Upstream CDN or in response to 1015 receiving a request for content from a User Agent) or in advance of 1016 being required (for example in case of prepositioned CDNI Metadata 1017 acquisition). 1019 The CDNI Metadata interface is built on the principles of RESTful web 1020 services. This means that requests and responses over the interface 1021 are built around the transfer of representations of hyperlinked 1022 resources. A resource in the context of the CDNI Metadata interface 1023 is any object in the Data Model (as described in Section 3 through 1024 Section 4). 1026 In the general case a CDNI Metadata server makes each instance of an 1027 addressable CDNI Metadata object available via a unique URI that 1028 returns a representation of that instance of that CDNI Metadata 1029 object. When an object needs to reference another addressable CDNI 1030 Metadata object (for example a HostIndex object referencing a 1031 HostMetadata object) it does so by including a link to the referenced 1032 object. 1034 CDNI Metadata servers are free to assign whatever structure they 1035 desire to the URIs for CDNI Metadata objects and CDNI Metadata 1036 clients MUST NOT make any assumptions regarding the structure of CDNI 1037 Metadata URIs or the mapping between CDNI Metadata objects and their 1038 associated URIs. Therefore any URIs present in the examples below 1039 are purely illustrative and are not intended to impose a definitive 1040 structure on CDNI Metadata interface implementations. 1042 6.1. Transport 1044 The CDNI Metadata interface uses HTTP as the underlying protocol 1045 transport. 1047 The HTTP Method in the request defines the operation the request 1048 would like to perform. Servers implementing the CDNI Metadata 1049 interface MUST support the HTTP GET and HEAD methods. 1051 The corresponding HTTP Response returns the status of the operation 1052 in the HTTP Status Code and returns the current representation of the 1053 resource (if appropriate) in the Response Body. HTTP Responses from 1054 servers implementing the CDNI Metadata interface that contain a 1055 response body SHOULD include an ETag to enable validation of cached 1056 versions of returned resources. 1058 The CDNI Metadata interface specified in this document is a read-only 1059 interface. Therefore support for other HTTP methods such as PUT, 1060 POST and DELETE etc. is not specified. Server implementations of 1061 this interface SHOULD reject all methods other than GET and HEAD. 1063 As the CDNI Metadata interface builds on top of HTTP, CDNI Metadata 1064 servers may make use of any HTTP feature when implementing the CDNI 1065 Metadata interface, for example a CDNI Metadata server may make use 1066 of HTTP's caching mechanisms to indicate that the returned response/ 1067 representation can be reused without re-contacting the CDNI Metadata 1068 server. 1070 6.2. Retrieval of CDNI Metadata resources 1072 In the general case a CDNI Metadata server makes each instance of an 1073 addressable CDNI Metadata object available via a unique URI and 1074 therefore in order to retrieve CDNI Metadata, a CDNI Metadata client 1075 first makes a HTTP GET request for the URI of the HostIndex which 1076 provides the CDNI Metadata client with a list of Hostnames for which 1077 the upstream CDN may delegate content delivery to the downstream CDN. 1079 In order to retrieve the CDNI Metadata for a particular request the 1080 CDNI Metadata client processes the received HostIndex object and 1081 finds the corresponding HostMetadata entry (by matching the hostname 1082 in the request against the hostnames in the HostMatch). If the 1083 HostMetadata is linked (rather than embedded), the CDNI metadata 1084 client then makes a GET request for the URI specified in the href 1085 property of the Link object which points to the HostMetadata object 1086 itself. 1088 In order to retrieve the most specific metadata for a particular 1089 request, the CDNI metadata client inspects the HostMetadata for 1090 references to more specific PathMetadata objects. If any 1091 PathMetadata match the request (and are linked rather than embedded), 1092 the CDNI metadata client makes another GET request for the 1093 PathMetadata. Each PathMetadata object may also include references 1094 to yet more specific metadata. If this is the case, the CDNI 1095 metadata client continues requesting PathMetadata recursively. 1097 Where a downstream CDN is interconnected with multiple upstream CDNs, 1098 the downstream CDN must decide which upstream CDN's CDNI metadata 1099 should be used to handle a particular User Agent request. 1101 When application level redirection (e.g. HTTP 302 redirects) is 1102 being used between CDNs, it is expected that the downstream CDN will 1103 be able to determine the upstream CDN that redirected a particular 1104 request from information contained in the received request (e.g. via 1105 the URI). With knowledge of which upstream CDN routed the request, 1106 the downstream CDN can choose the correct metadata server from which 1107 to obtain the HostIndex. Note that the HostIndex served by each uCDN 1108 may be unique. 1110 In the case of DNS redirection there is not always sufficient 1111 information carried in the DNS request from User Agents to determine 1112 the upstream CDN that redirected a particular request (e.g. when 1113 content from a given host is redirected to a given downstream CDN by 1114 more than one upstream CDN) and therefore downstream CDNs may have to 1115 apply local policy when deciding which upstream CDN's metadata to 1116 apply. 1118 6.3. Bootstrapping 1120 The URI for the HostIndex object of a given upstream CDN needs to be 1121 either discovered by or configured in the downstream CDN. All other 1122 objects/resources are then discoverable from the HostIndex object by 1123 following the links in the HostIndex object and the referenced 1124 HostMetadata and PathMetadata objects. 1126 If the URI for the HostIndex object is not manually configured in the 1127 downstream CDN then the HostIndex URI could be discovered. A 1128 mechanism allowing the downstream CDN to discover the URI of the 1129 HostIndex is outside the scope of this document. 1131 6.4. Encoding 1133 Object are resources that may be: 1135 o Addressable, where the object is a resource that may be retrieved 1136 or referenced via its own URI. 1137 o Embedded, where the object is contained (or inlined) within a 1138 property of an addressable object. 1140 In the descriptions of objects we use the term "X contains Y" to mean 1141 either Y is directly embedded in X or that Y is linked to by X. It is 1142 generally a deployment choice for the uCDN implementation to decide 1143 when and which CDNI Metadata objects to embed and which are 1144 separately addressable. 1146 6.4.1. MIME Media Types 1148 All MIME types are prefixed with "application/cdni." The MIME type 1149 for each object matches the type name of that object as defined by 1150 this document. Table 3 lists a few examples of the MIME Media Type 1151 for each object (resource) that is retrievable through the CDNI 1152 Metadata interface. The MIME type suffix depends on the metadata 1153 encoding, either "+xml" or "+json". 1155 +--------------+-------------------------------+ 1156 | Data Object | MIME Media Type | 1157 +--------------+-------------------------------+ 1158 | HostIndex | application/cdni.HostIndex | 1159 | HostMatch | application/cdni.HostMatch | 1160 | HostMetadata | application/cdni.HostMetadata | 1161 | PathMatch | application/cdni.PathMatch | 1162 | PathMetadata | application/cdni.PathMetadata | 1163 +--------------+-------------------------------+ 1165 Table 3: Example MIME Media Types for CDNI Metadata objects 1167 See http://www.iana.org/assignments/media-types/index.html for 1168 reference. 1170 6.4.2. JSON Encoding of Objects 1172 One possible encoding for a CDNI Metadata object is a JSON object 1173 containing a dictionary of (key,value) pairs where the keys are the 1174 property names and the values are the associated property values. 1176 The keys of the dictionary are the names of the properties associated 1177 with the object and are therefore dependent on the specific object 1178 being encoded (i.e. dependent on the MIME Media Type of the returned 1179 resource). Likewise, the values associated with each key are 1180 dependent on the specific object being encoded (i.e. dependent on the 1181 MIME Media Type of the returned resource). 1183 Dictionary keys in JSON are case sensitive and therefore by 1184 convention any dictionary key defined by this document (for example 1185 the names of CDNI Metadata object properties) MUST be represented in 1186 lowercase. 1188 In addition to the properties specific to each object type, the keys 1189 defined below may be present in any object. 1191 Key: base 1192 Description: Provides a prefix for any relative URLs in the 1193 object. This is similar to the XML base tag [XML-BASE]. If 1194 absent, all URLs in the remainder of the document must be 1195 absolute URLs. 1196 Type: URI 1197 Mandatory: No 1199 Key: links 1200 Description: The links of this object to other addressable 1201 objects. Any property may be replaced by a link to an object 1202 with the same type as the property it replaces. 1203 Type: List of Link objects 1204 Mandatory: Yes 1206 6.4.2.1. JSON Example 1208 A downstream CDN may request the HostIndex and receive the following 1209 object of type "application/cdni.HostIndex+json": 1211 { 1212 "hosts": [ 1213 { 1214 "host": "video.example.com", 1215 "links": [ 1216 { 1217 "rel": "host-metadata", 1218 "type": "application/cdni.HostMetadata", 1219 "href": "http://metadata.example.ucdn.com/video" 1220 } 1221 ] 1222 }, 1223 { 1224 "host": "images.example.com", 1225 "links": [ 1226 { 1227 "rel": "host-metadata", 1228 "type": "application/cdni.HostMetadata", 1229 "href": "http://metadata.ucdn.example.com/images" 1230 } 1231 ] 1232 } 1233 ] 1234 } 1236 If the incoming request has a Host header with "video.example.com" 1237 then the downstream CDN would fetch from the next metadata object 1238 from "http://metadata.ucdn.example.com/video" expecting a MIME type 1239 of "application/cdni.HostMetadata+json": 1241 { 1242 "metadata": [ 1243 { 1244 "type": "application/cdni.SourceMetadata", 1245 "value": { 1246 "sources": [ 1247 { 1248 "links": [{ 1249 "rel": "auth", 1250 "type": "application/cdni.Auth", 1251 "href": "http://metadata.ucdn.example.com/auth1234" 1252 }], 1253 "endpoint": "acq1.ucdn.example.com", 1254 "protocol": "ftp" 1255 }, 1256 { 1257 "links": [{ 1258 "rel": "auth", 1259 "type": "application/cdni.Auth", 1260 "href": "http://metadata.ucdn.example.com/auth1234" 1261 }], 1262 "endpoint": "acq2.ucdn.example.com", 1263 "protocol": "http" 1264 } 1265 ] 1266 } 1267 }, 1268 { 1269 "type": "application/cdni.LocationACL", 1270 "value": { 1271 "locations": [ 1272 { 1273 "locations": [ 1274 { "iprange": "192.168.0.0/16" } 1275 ], 1276 "action": "deny" 1277 } 1278 ] 1279 } 1280 }, 1281 { 1282 "type": "application/cdni.ProtocolACL", 1283 "value": { 1284 "protocols": [ 1285 { 1286 "protocols": [ 1287 "ftp" 1288 ], 1289 "action": "deny" 1290 } 1291 ] 1292 } 1293 } 1294 ], 1295 "paths": [ 1296 { 1297 "path-pattern": { 1298 "pattern": "/videos/trailers/*" 1299 }, 1300 "links": [{ 1301 "rel": "path-metadata", 1302 "type": "application/cdni.PathMetadata", 1303 "href": "http://metadata.ucdn.example.com/videos/trailers" 1304 }] 1305 }, 1306 { 1307 "path-pattern": { 1308 "pattern": "/videos/movies/*" 1309 }, 1310 "links": [{ 1311 "rel": "pathmetadata", 1312 "type": "application/cdni.PathMetadata", 1313 "href": "http://metadata.ucdn.example.com/videos/movies" 1314 }] 1315 } 1316 ] 1317 } 1319 Suppose the path of the requested resource matches the "/video/ 1320 movies/*" pattern, the next metadata requested would be for 1321 "http://metadata.ucdn.example.com/video/movies" with an expected type 1322 of "application/cdni.PathMetadata": 1324 { 1325 "metadata": [], 1326 "paths": [ 1327 { 1328 "path-pattern": { 1329 "pattern": "/videos/movies/hd/*" 1330 }, 1331 "links": [{ 1332 "rel": "pathmetadata", 1333 "type": "application/cdni.PathMetadata", 1334 "href": "http://metadata.ucdn.example.com/videos/movies/hd" 1335 }] 1336 } 1337 ] 1338 } 1340 Finally, if the path of the requested resource also matches the 1341 "/videos/movies/hd/*" pattern, the downstream CDN would also fetch 1342 the following object from 1343 "http://metadata.ucdn.example.com/videos/movies/hd" with MIME type 1344 "application/cdni.PathMetadata": 1346 { 1347 "metadata": [ 1348 { 1349 "type": "application/cdni.TimeWindowACL", 1350 "value": { 1351 "times": [ 1352 "times": [ 1353 { 1354 "start": "1213948800", 1355 "end": "1327393200" 1356 } 1357 ], 1358 "type": "allow" 1359 ] 1360 } 1361 } 1362 ] 1363 } 1365 6.4.3. XML Encoding of Objects 1367 Another possible encoding for a CDNI Metadata object is an XML 1368 document containing elements with tag names which match property 1369 names and values which match the associated property values. 1371 Tag names of elements are the names of the properties associated with 1372 the object and are therefore dependent on the specific object being 1373 encoded (i.e. dependent on the MIME Media Type of the returned 1374 resource). Likewise, the values associated with each element are 1375 dependent on the specific object being encoded (i.e. dependent on the 1376 MIME Media Type of the returned resource). 1378 Lists are encoded by repeating the singular form of a property name. 1379 For example the "hosts" property is a list of "HostMatch" objects. 1380 This list would be encoded as multiple "host" elements. 1382 Link objects are a special case. If a Link object replaces a 1383 property then a "link" element replaces the expected element. The 1384 properties of the Link object are encoded as XML attributes. The 1385 type attribute is set to the MIME type of the target object. The 1386 href attribute is set to the URI of the target object. The rel 1387 attribute is set to the name of the element being replaced. 1389 6.4.3.1. XML Example 1391 A downstream CDN may request the HostIndex and receive the following 1392 object of type "application/cdni.HostIndex+xml": 1394 1395 1396 video.example.com 1397 1399 1400 1401 images.example.com 1402 1404 1405 1407 If the incoming request has a Host header with "video.example.com" 1408 then the downstream CDN would fetch from the next metadata object 1409 from "http://metadata.ucdn.example.com/video" expecting a MIME type 1410 of "application/cdni.HostMetadata+xml": 1412 1413 1414 application/cdni.SourceMetadata 1415 1416 1417 1419 acq1.ucdn.example.com 1420 ftp 1421 1422 1423 1425 acq2.ucdn.example.com 1426 http 1427 1428 1429 1430 1431 application/cdni.LocationACL 1432 1433 1434 1435 192.168.0.0/16 1436 1437 deny 1438 1439 1440 1441 1442 application/cdni.ProtocolACL 1443 1444 1445 ftp 1446 deny 1447 1448 1449 1450 1451 1452 /videos/trailers/*" 1453 1454 1456 1457 1458 1459 /videos/movies/*" 1460 1461 1463 1464 1466 Suppose the path of the requested resource matches the "/video/ 1467 movies/*" pattern, the next metadata requested would be for 1468 "http://metadata.ucdn.example.com/video/movies" with an expected type 1469 of "application/cdni.PathMetadata": 1471 1472 1473 1474 /videos/movies/hd/* 1475 1476 1478 1479 1481 Finally, if the path of the requested resource also matches the 1482 "/videos/movies/hd/*" pattern, the downstream CDN would also fetch 1483 the following object from 1484 "http://metadata.ucdn.example.com/videos/movies/hd" with MIME type 1485 "application/cdni.PathMetadata": 1487 1488 1489 application/cdni.TimeWindowACL 1490 1491 1498 1499 1501 6.5. Extensibility 1503 The set of property Metadata may be extended with proprietary and/or 1504 custom property Metadata. The GenericMetadata object defined in 1505 Section 4.1.7 allows any Metadata property to be included in either 1506 the HostMetadata or PathMetadata lists. As described in Section 3.4, 1507 any proprietary and/or custom property Metadata SHOULD be identified 1508 by the "ext." prefix in an appropriately descriptive type which 1509 conveys the organization defining the property Metadata and the 1510 function of the property Metadata. 1512 Note: Identification of the property Metadata defining organization 1513 in the property Metadata type decreases the possibility of property 1514 Metadata type collision. The fully-qualified domain name of the 1515 organization in reverse order may be used for this purpose. 1517 6.5.1. Metadata Enforcement 1519 At any given time, the set of property Metadata supported by the uCDN 1520 may not match the set of property Metadata supported by the dCDN. 1521 The uCDN may or may not know which property Metadata the dCDN 1522 supports. In cases where the uCDN supports Metadata that the dCDN 1523 does not, the dCDN MUST be aware of any Metadata marked as 1524 "mandatory-to-enforce". If a CDN does not understand or is unable to 1525 perform the functions associated with any "mandatory-to-enforce" 1526 Metadata, the CDN MUST NOT service any requests for the corresponding 1527 content. 1529 Note: Ideally, uCDNs would not delegate content requests to a dCDN 1530 which does not support the mandatory-to-enforce Metadata associated 1531 with the content being requested. However, even if the uCDN has a 1532 priori knowledge of the Metadata supported by the dCDN (e.g., via the 1533 CDNI capabilities interface or through out-of-band negotiation 1534 between CDN operators) Metadata support may fluctuate or be 1535 inconsistent (e.g., due to mis-communication, mis-configuration, or 1536 temporary outage). Thus, the dCDN MUST evaluate all Metadata 1537 associated with content requests and reject any requests where 1538 "mandatory-to-enforce" Metadata associated with the content cannot be 1539 enforced. 1541 6.5.2. Metadata Override 1543 It is possible that new Metadata definitions may obsolete or override 1544 existing property Metadata (e.g., a future revision of the CDNI 1545 Metadata interface may redefine the Auth Metadata or a custom vendor 1546 extension may implement an alternate Auth Metadata option). If 1547 multiple Metadata (e.g., cdni.v2.Auth, ext.vendor1.Auth, and 1548 ext.vendor2.Auth) all override an existing Metadata (e.g., cdni.Auth) 1549 and all are marked as "mandatory-to-enforce", it may be ambiguous 1550 which Metadata should be applied, especially if the functionality of 1551 the Metadata conflict. 1553 As described in Section 3.3, Metadata override only applies to 1554 Metadata objects of the same exact type, found in HostMetadata and 1555 nested PathMetadata structures. The CDNI Metadata interface does not 1556 support enforcement of dependencies between different Metadata types. 1557 It is the responsibility of the CSP and the CDN operators to ensure 1558 that Metadata assigned to a given content do not conflict. 1560 Note: Because Metadata is inherently ordered in GenericMetadata 1561 lists, as well as in the PathMetadata hierarchy and PathMatch lists, 1562 multiple conflicting Metadata types MAY be used, however, Metadata 1563 hierarchies MUST ensure that independent PathMatch root objects are 1564 used to prevent ambiguous or conflicting Metadata definitions. 1566 6.6. Versioning 1568 The first version of the CDNI Metadata interface does not include 1569 version numbering. Subsequent versions will incorporate a syntax for 1570 versioning. 1572 7. IANA Considerations 1574 This document requests the registration of the "application/cdni" 1575 MIME Media Type under the IANA MIME Media Type registry 1576 (http://www.iana.org/assignments/media-types/index.html). 1578 [Ed. Need to consider a registry for Metadata type identifiers.] 1580 8. Security Considerations 1582 The CDNI Metadata Interface is expected to be secured as a function 1583 of the transport protocol (e.g. HTTP authentication [RFC2617], HTTPS 1584 [RFC2818], or inter-domain IPSec). 1586 If a malicious metadata server is contacted by a downstream CDN, the 1587 malicious server may provide metadata to the downstream CDN which 1588 denies service for any piece of content to any user agent. The 1589 malicious server may also provide metadata which directs a downstream 1590 CDN to a malicious origin server instead of the actual origin server. 1591 The dCDN is expected to authenticate the server to prevent this 1592 situation (e.g. by using HTTPS and validating the server's 1593 certificate). 1595 A malicious metadata client could request metadata for a piece of 1596 content from an upstream CDN. The metadata information may then be 1597 used to glean information regarding the uCDN or to contact an 1598 upstream origin server. The uCDN is expected to authenticate client 1599 requests to prevent this situation. 1601 9. Acknowledgements 1603 The authors would like to thank David Ferguson and Francois le 1604 Faucheur for their valuable comments and input to this document. 1606 10. References 1608 10.1. Normative References 1610 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1611 Requirement Levels", BCP 14, RFC 2119, March 1997. 1613 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1614 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1615 Authentication: Basic and Digest Access Authentication", 1616 RFC 2617, June 1999. 1618 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1620 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1621 Architecture", RFC 4291, February 2006. 1623 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1624 Address Text Representation", RFC 5952, August 2010. 1626 10.2. Informative References 1628 [I-D.ietf-cdni-framework] 1629 Peterson, L. and B. Davie, "Framework for CDN 1630 Interconnection", draft-ietf-cdni-framework-03 (work in 1631 progress), February 2013. 1633 [I-D.ietf-cdni-requirements] 1634 Leung, K. and Y. Lee, "Content Distribution Network 1635 Interconnection (CDNI) Requirements", 1636 draft-ietf-cdni-requirements-05 (work in progress), 1637 February 2013. 1639 [I-D.zyp-json-schema] 1640 Zyp, K. and G. Court, "A JSON Media Type for Describing 1641 the Structure and Meaning of JSON Documents", 1642 draft-zyp-json-schema-03 (work in progress), 1643 November 2010. 1645 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1646 Resource Identifier (URI): Generic Syntax", STD 66, 1647 RFC 3986, January 2005. 1649 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 1650 RFC 4151, October 2005. 1652 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1653 Syndication Format", RFC 4287, December 2005. 1655 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 1656 Distribution Network Interconnection (CDNI) Problem 1657 Statement", RFC 6707, September 2012. 1659 [XML-BASE] 1660 Marsh, J., Ed. and R. Tobin, Ed., "XML Base (Second 1661 Edition) - http://www.w3.org/TR/xmlbase/", January 2009. 1663 Appendix A. Relationship to the CDNI Requirements 1665 Section 6 of [I-D.ietf-cdni-requirements] lists the requirements for 1666 the CDNI Metadata Distribution interface. This section outlines 1667 which of those requirements are met by the CDNI Metadata interface 1668 specified in this document. 1670 All metadata requirements are met either directly or indirectly by 1671 the CDNI Metadata Interface described in this document, with the 1672 clarifications or exceptions described in the following paragraphs. 1674 Requirements related to pre-positioning of metadata are met by this 1675 document on the assumption that other CDNI Interfaces are to be used 1676 by the upstream CDN to trigger the pre-positioning of metadata by the 1677 downstream CDN via the CDNI Metadata Interface. Triggering metadata 1678 pre-positioning is beyond the scope of the CDNI Metadata interface. 1679 However, the interface as described by this document supports pulling 1680 metadata on-demand for the purpose of pre-positioning. 1682 Requirement META-7 relating to modification of metadata by the 1683 upstream CDN is met both by allowing timeouts on the cacheability of 1684 metadata objects and by allowing other CDNI interfaces to initiate a 1685 refetch or purge of metadata. 1687 Requirement META-18 relating to surrogate cache behavior parameters 1688 is supported via extensibility. However, the example parameters in 1689 META-18 are not described in this document. 1691 Appendix B. Metadata Rewriting 1693 For some use cases, one CDN in a chain of interconnected CDNs must be 1694 able to rewrite CDNI Metadata received from its upstream CDN before 1695 presenting that CDNI Metadata to its downstream CDN. 1697 The CDN which is performing the metadata rewriting is referred to as 1698 the 'Transit' CDN (tCDN), its upstream CDN as the uCDN and its 1699 downstream CDN as the dCDN. 1701 Two (non-exhaustive) examples of when rewriting are: 1702 Allowing the dCDN is to acquire content from the tCDN instead of 1703 (or as well as) the uCDN. The tCDN must modify the appropriate 1704 CDNI Source Metadata objects to include itself as a possible 1705 source for the content. 1706 If the tCDN is transforming the original URI as part of CDNI 1707 request redirection on-route to the dCDN, the tCDN may need to 1708 modify the PatternMatch objects in any PathMetadata to take 1709 account of any URI path transformation it has performed. 1711 When performing HTTP redirection between CDNs, the dCDN must be able 1712 to map an UA request to a host and path which are meaningful to the 1713 tCDN. The dCDN needs only to identify its immediate upstream 1714 neighbor and does not need to map (or understand) the entire chain of 1715 CDNs that precede the tCDN. 1717 A dCDN may encode the identity of the tCDN in the URI it returns to 1718 the UA as part of request redirection (either directly or via the 1719 CDNI Request Routing Redirection interface). The exact method the 1720 dCDN uses to encode the information it requires is a local 1721 implementation decision provided it enables the dCDN to identify the 1722 correct upstream CDN (tCDN) and to map the request to the appropriate 1723 host and path so that the dCDN can find and retrieve the correct CDNI 1724 Metadata from tCDN. 1726 B.1. Example 1728 The example in this section is not necessarily representative of URL 1729 rewriting in practice. 1731 The UA requests the following URI from the uCDN: 1733 http://video.example/foo/bar 1735 The uCDN makes a CDNI Request Routing Redirection request to tCDN and 1736 tCDN returns a redirection URI of: 1738 http://tcdn.example/tcdn-prefix/foo/bar 1740 The tcdn-prefix/ encodes sufficient information for tCDN to identify 1741 uCDN as its upstream CDN neighbor. The tCDN makes a CDNI Request 1742 Routing Redirection request to dCDN and dCDN returns a redirection 1743 URI of: 1745 http://dcdn.example/dcdn-prefix/tcdn-prefix/foo/bar 1747 Therefore when dCDN receives a request for: 1749 http://dcdn.example/dcdn-prefix/tcdn-prefix/foo/bar 1751 The dCDN can use /dcdn-prefix/ to identify tCDN as its upstream CDN 1752 neighbor and reconstruct the URI tCDN expects. The tCDN can in turn 1753 use /tcdn-prefix/ to identify uCDN as its upstream CDN neighbour and 1754 reconstruct the URI uCDN expects. 1756 Authors' Addresses 1758 Ben Niven-Jenkins 1759 Velocix (Alcatel-Lucent) 1760 3 Ely Road 1761 Milton, Cambridge CB24 6AA 1762 UK 1764 Email: ben@velocix.com 1765 Rob Murray 1766 Velocix (Alcatel-Lucent) 1767 3 Ely Road 1768 Milton, Cambridge CB24 6AA 1769 UK 1771 Email: rmurray@velocix.com 1773 Grant Watson 1774 Velocix (Alcatel-Lucent) 1775 3 Ely Road 1776 Milton, Cambridge CB24 6AA 1777 UK 1779 Email: gwatson@velocix.com 1781 Matt Caulfield 1782 Cisco Systems 1783 1414 Massachusetts Avenue 1784 Boxborough, MA 01719 1785 USA 1787 Phone: +1 978 936 9307 1788 Email: mcaulfie@cisco.com 1790 Kent Leung 1791 Cisco Systems 1792 3625 Cisco Way 1793 San Jose 95134 1794 USA 1796 Phone: +1 408 526 5030 1797 Email: kleung@cisco.com 1799 Kevin J. Ma 1800 Azuki Systems, Inc. 1801 43 Nagog Park 1802 Acton, MA 01720 1803 USA 1805 Phone: +1 978-844-5100 1806 Email: kevin.ma@azukisystems.com