idnits 2.17.1 draft-ietf-cdni-metadata-03.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. == There are 2 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 21, 2013) is 3840 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) == Unused Reference: 'I-D.zyp-json-schema' is defined on line 1779, but no explicit reference was found in the text == Unused Reference: 'RFC4151' is defined on line 1788, but no explicit reference was found in the text == Unused Reference: 'RFC4287' is defined on line 1791, 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) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) == 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: 4 errors (**), 0 flaws (~~), 9 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Niven-Jenkins 3 Internet-Draft R. Murray 4 Intended status: Standards Track G. Watson 5 Expires: April 24, 2014 Velocix (Alcatel-Lucent) 6 M. Caulfield 7 K. Leung 8 Cisco Systems 9 K. Ma 10 Azuki Systems, Inc. 11 October 21, 2013 13 CDN Interconnect Metadata 14 draft-ietf-cdni-metadata-03 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 April 24, 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 . . . . . . 11 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. Footprint . . . . . . . . . . . . . . . . . . . . 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.6.1. Credentials Auth Type . . . . . . . . . . . . . . 21 98 4.2.7. Cache . . . . . . . . . . . . . . . . . . . . . . . . 21 99 4.2.8. Grouping . . . . . . . . . . . . . . . . . . . . . . 22 100 4.3. CDNI Metadata Simple Data Type Descriptions . . . . . . . 22 101 4.3.1. Link . . . . . . . . . . . . . . . . . . . . . . . . 22 102 4.3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . 23 103 4.3.3. Endpoint . . . . . . . . . . . . . . . . . . . . . . 23 104 4.3.4. URI . . . . . . . . . . . . . . . . . . . . . . . . . 23 105 4.3.5. Time . . . . . . . . . . . . . . . . . . . . . . . . 23 106 5. CDNI Metadata Capabilities . . . . . . . . . . . . . . . . . 24 107 5.1. Protocol ACL Capabilities . . . . . . . . . . . . . . . . 24 108 5.2. Authorization Metadata Capabilities . . . . . . . . . . . 24 109 6. CDNI Metadata interface . . . . . . . . . . . . . . . . . . . 25 110 6.1. Transport . . . . . . . . . . . . . . . . . . . . . . . . 25 111 6.2. Retrieval of CDNI Metadata resources . . . . . . . . . . 26 112 6.3. Bootstrapping . . . . . . . . . . . . . . . . . . . . . . 27 113 6.4. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 28 114 6.4.1. MIME Media Types . . . . . . . . . . . . . . . . . . 28 115 6.4.2. JSON Encoding of Objects . . . . . . . . . . . . . . 28 116 6.4.2.1. JSON Example . . . . . . . . . . . . . . . . . . 29 117 6.5. Extensibility . . . . . . . . . . . . . . . . . . . . . . 33 118 6.5.1. Metadata Enforcement . . . . . . . . . . . . . . . . 33 119 6.5.2. Metadata Override . . . . . . . . . . . . . . . . . . 33 120 6.6. Versioning . . . . . . . . . . . . . . . . . . . . . . . 34 121 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 122 7.1. GenericMetadata Type Registry . . . . . . . . . . . . . . 34 123 7.1.1. GenericMetadata Sub-Registries . . . . . . . . . . . 35 124 7.1.1.1. Footprint Sub-Registry . . . . . . . . . . . . . 35 125 7.1.1.2. Protocol Sub-Registry . . . . . . . . . . . . . . 36 126 7.1.1.3. Authentication Sub-Registry . . . . . . . . . . . 37 127 8. Security Considerations . . . . . . . . . . . . . . . . . . . 37 128 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 129 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 130 10.1. Normative References . . . . . . . . . . . . . . . . . . 38 131 10.2. Informative References . . . . . . . . . . . . . . . . . 38 132 Appendix A. Relationship to the CDNI Requirements . . . . . . . 39 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 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 4. Encoding-Independent CDNI Metadata Object Descriptions 496 Section 4.1 provides the definitions of each object type declared in 497 Section 3. These objects are described as structural objects as they 498 provide the structure for the inheritance tree and identifying which 499 specific properties apply to a given User Agent content request. 501 Section 4.2 provides the definitions for the set of core metadata 502 objects which may be contained within a GenericMetadata object. 503 These objects are described as property objects as they define the 504 semantics, enforcement options, and serialization rules for specific 505 properties. These properties govern how User Agent requests for 506 content are handled. Property objects may be composed of or contain 507 references to other objects. In those cases the value of the 508 property can be either an object of that type (the object is 509 embedded) or a Link object that contains a URI and relationship that 510 can be dereferenced to retrieve the CDNI Metadata object that 511 represents the value of that property. 513 Note: In the following sections, the term "mandatory-to-specify" is 514 used to convey which objects or properties must be specified for a 515 given parent object or property. When mandatory-to-specify is set to 516 true, it implies that if the parent object is specified, then the 517 defined object or property MUST also be specified, e.g., a HostMatch 518 object without a host to match against does not make sense, 519 therefore, the host is mandatory-to-specify inside a parent HostMatch 520 object. 522 4.1. CDNI Metadata Structural Object Descriptions 523 Each of the sub-sections below describe the structural objects 524 defined in Table 2. 526 4.1.1. HostIndex 528 The HostIndex object is the entry point into the CDNI Metadata 529 hierarchy. It contains a list of HostMatch objects. An incoming 530 content request is matched against the hostname inside of each of the 531 listed HostMatch objects to find the HostMatch object which applies 532 to the request. 534 Property: hosts 536 Description: List of HostMatch objects, in priority order. 538 Type: List of HostMatch objects 540 Mandatory-to-Specify: Yes. 542 4.1.2. HostMatch 544 The HostMatch object contains a hostname or IP address to match 545 against content requests. The HostMatch object also contains a 546 reference to Metadata objects to apply if a match is found. 548 Property: host 550 Description: String (hostname or IP address) to match against 551 the requested host. 553 Type: String 555 Mandatory-to-Specify: Yes. 557 Property: host-metadata 559 Description: CDNI Metadata to apply when delivering content 560 that matches this host. 562 Type: HostMetadata 564 Mandatory-to-Specify: Yes. 566 4.1.3. HostMetadata 568 The HostMetadata object contains both Metadata that applies to 569 content requests for a particular host and a list of pattern matches 570 for finding more specific Metadata based on the resource path in a 571 content request. 573 Property: metadata 575 Description: List of host related metadata. 577 Type: List of GenericMetadata objects 579 Mandatory-to-Specify: Yes. 581 Property: paths 583 Description: Path specific rules. First match applies. 585 Type: List of PathMatch objects 587 Mandatory-to-Specify: No. 589 4.1.4. PathMatch 591 The PathMatch object contains an expression given as a PatternMatch 592 object to match against a resource URI path and Metadata objects to 593 apply if a match is found. 595 Property: path-pattern 597 Description: Pattern to match against the requested path, i.e. 598 against the [RFC3986] path-absolute. 600 Type: PatternMatch 602 Mandatory-to-Specify: Yes. 604 Property: path-metadata 606 Description: CDNI Metadata to apply when delivering content 607 that matches this pattern. 609 Type: PathMetadata 611 Mandatory-to-Specify: Yes. 613 4.1.5. PathMetadata 615 A PathMetadata object contains the CDNI Metadata properties for 616 content served with the associated URI path (defined in a PathMatch 617 object). Note that if CDNI metadata is used as an input to CDNI 618 request routing and DNS-based redirection is employed, then any 619 metadata at the PathMetadata level or below will be inaccessible at 620 request routing time. 622 Property: metadata 624 Description: List of path related metadata. 626 Type: List of GenericMetadata objects 628 Mandatory-to-Specify: Yes. 630 Property: paths 632 Description: Path specific rules. First match applies. 634 Type: List of PathMatch objects 636 Mandatory-to-Specify: No. 638 4.1.6. PatternMatch 640 A PatternMatch object contains the pattern string and flags that 641 describe the PathMatch expression. 643 Property: pattern 645 Description: A pattern for string matching. The pattern may 646 contain the wildcards * and ?, where * matches any sequence of 647 characters (including the empty string) and ? matches exactly 648 one character. The three literals \ , * and ? should be 649 escaped as \\, \* and \? 651 Type: String 653 Mandatory-to-Specify: Yes. 655 Property: case-sensitive 657 Description: Flag indicating whether or not case-sensitive 658 matching should be used. 660 Type: Boolean 661 Mandatory-to-Specify: No. Default is case-insensitive match. 663 Property: ignore-query-string 665 Description: List of query parameters which should be ignored 666 when searching for a pattern match. If all query parameters 667 should be ignored then the list MUST be empty. 669 Type: List of String 671 Mandatory-to-Specify: No. Default is to include query strings 672 when matching. 674 4.1.7. GenericMetadata 676 A GenericMetadata object is a abstraction for managing individual 677 CDNI Metadata properties in an opaque manner. 679 Property: type 681 Description: CDNI Metadata property object type. 683 Type: String 685 Mandatory-to-Specify: Yes. 687 Property: value 689 Description: CDNI Metadata property object. 691 Type: matches the type property above 693 Mandatory-to-Specify: Yes. 695 Property: mandatory-to-enforce 697 Description: Flag identifying whether or not the enforcement of 698 the property Metadata is required. 700 Type: Boolean 702 Mandatory-to-Specify: Yes. 704 Property: safe-to-redistribute 706 Description: Flag identifying whether or not the property 707 Metadata may be safely redistributed without modification. 709 Type: Boolean 711 Mandatory-to-Specify: No. Default is allow transparent 712 redistribution. 714 4.2. CDNI Metadata Property Object Descriptions 716 4.2.1. Source Metadata 718 Source Metadata provides the dCDN information about content 719 acquisition e.g. how to contact an uCDN Surrogate or an Origin Server 720 to obtain the content to be served. The sources are not necessarily 721 the actual Origin Servers operated by the CSP but might be a set of 722 Surrogates in the uCDN. 724 Property: sources 726 Description: Sources from which the dCDN can acquire content, 727 listed in priority order. 729 Type: List of Source objects 731 Mandatory-to-Specify: No. Default is to use static 732 configuration, out of band of the metadata interface. 734 4.2.1.1. Source 736 A Source object describes the Source which should be used by the dCDN 737 for content acquisition, e.g. a Surrogate within the uCDN or an 738 alternate Origin Server, the protocol to be used and any 739 authentication method. 741 Property: auth 743 Description: Authentication method to use when requesting 744 content from this source. 746 Type: Auth 748 Mandatory-to-Specify: No. Default is no authentication is 749 required. 751 Property: endpoints 753 Description: Origins from which the dCDN can acquire content. 755 Type: List of EndPoint objects 756 Mandatory-to-Specify: Yes. 758 Property: protocol 760 Description: Network retrieval protocol to use when requesting 761 content from this source. 763 Type: Protocol 765 Mandatory-to-Specify: Yes. 767 4.2.2. LocationACL Metadata 769 LocationACL Metadata defines location-based restrictions. 771 Property: locations 773 Description: Access control list which applies restrictions to 774 delivery based on client location. 776 Type: List of LocationRule objects 778 Mandatory-to-Specify: No. Default is allow all locations. 780 4.2.2.1. LocationRule 782 A LocationRule contains or references a list of Location objects and 783 the corresponding action. 785 Property: footprints 787 Description: List of footprints to which the rule applies. 789 Type: List of Footprint objects 791 Mandatory-to-Specify: Yes. 793 Property: action 795 Description: Defines whether the rule specifies locations to 796 allow or deny. 798 Type: Enumeration [allow|deny] 800 Mandatory-to-Specify: No. Default is deny. 802 4.2.2.2. Footprint 803 A Footprint object describes the footprint to which a LocationRule 804 may be applied by, e.g. an IPv4 address range or a geographic 805 location. 807 Property: type 809 Description: Registered footprint type (see Section 7.1.1.1). 811 Type: String 813 Mandatory-to-Specify: Yes. 815 Property: value 817 Description: Footprint object conforming to the specification 818 associated with the registered footprint type. 820 Type: String 822 Mandatory-to-Specify: Yes. 824 4.2.3. TimeWindowACL Metadata 826 TimeWindowACL Metadata defines time-based restrictions. 828 Property: times 830 Description: Access control list which applies restrictions to 831 delivery based on request time. 833 Type: List of TimeWindowRule objects 835 Mandatory-to-Specify: No. Default is allow all time windows. 837 4.2.3.1. TimeWindowRule 839 A TimeWindowRule contains or references a list of TimeWindow objects 840 and the corresponding action. 842 Property: times 844 Description: List of time windows to which the rule applies. 846 Type: List of TimeWindow objects 848 Mandatory-to-Specify: Yes. 850 Property: action 851 Description: Defines whether the rule specifies time windows to 852 allow or deny. 854 Type: Enumeration [allow|deny] 856 Mandatory-to-Specify: No. Default is deny. 858 4.2.3.2. TimeWindow 860 A TimeWindow object describes a time range which may be applied by an 861 ACLRule, e.g. Start 09:00AM 01/01/2000 UTC End 17:00PM 01/01/2000 862 UTC. 864 Property: start 866 Description: The start time of the window. 868 Type: Time 870 Mandatory-to-Specify: Yes. 872 Property: end 874 Description: The end time of the window. 876 Type: Time 878 Mandatory-to-Specify: Yes. 880 4.2.4. ProtocolACL Metadata 882 ProtocolACL Metadata defines delivery protocol restrictions. 884 Property: protocols 886 Description: Access control list which applies restrictions to 887 delivery based on delivery protocol. 889 Type: List of ProtocolRule objects 891 Mandatory-to-Specify: No. Default is allow all protocols. 893 4.2.4.1. ProtocolRule 895 A ProtocolRule contains or references a list of Protocol objects. 896 ProtocolRule objects are used to construct a ProtocolACL to apply 897 restrictions to content acquisition or delivery. 899 Property: protocols 901 Description: List of protocols to which the rule applies. 903 Type: List of protocol objects 905 Mandatory-to-Specify: Yes. 907 Property: action 909 Description: Defines whether the rule specifies protocols to 910 allow or deny. 912 Type: Enumeration [allow|deny]+ 914 Mandatory-to-Specify: No. Default is allow all protocols. 916 Property: direction 918 Description: Defines whether the ProtocolRule specifies 919 protocols for acquisition or delivery. 921 Type: Enumeration [acquisition|delivery] 923 Mandatory-to-Specify: No. Default is to apply the rule to both 924 acquisition and delivery. 926 4.2.5. Authorization Metadata 928 Authorization Metadata define content authorization methods. 930 Property: methods 932 Description: Options for authenticating content requests. All 933 options in the list are equally valid. 935 Type: List of Auth objects 937 Mandatory-to-Specify: No. Default is no authorization 938 required. 940 4.2.6. Auth 942 An Auth object defines authentication and authorization methods to be 943 used during content delivery and content acquisition. 945 Property: type 946 Description: Registered Auth type (see Section 7.1.1.3). 948 Type: String 950 Mandatory-to-Specify: Yes. 952 Property: value 954 Description: Auth object conforming to the specification 955 associated with the registered Auth type. 957 Type: String 959 Mandatory-to-Specify: Yes. 961 4.2.6.1. Credentials Auth Type 963 Credentials Auth is a type of Auth object with type "credentials" 964 (see Section 7.1.1.3). The CredentialsAuth object contains the 965 following properties: 967 Property: username 969 Description: Identification of user. 971 Type: String 973 Mandatory-to-Specify: Yes. 975 Property: password 977 Description: Password for user identified by username property. 979 Type: String 981 Mandatory-to-Specify: Yes. 983 4.2.7. Cache 985 A Cache object describes the cache control parameters to be applied 986 to the content by intermediate caches. 988 Property: ignore-query-string 990 Description: Allows a cache to ignore URI query string 991 parameters while comparing URIs for equivalence. Each query 992 parameter to ignore is specified in the list. If all query 993 parameters should be ignored, then the list MUST be empty. 995 Type: List of String 997 Mandatory-to-Specify: No. Default is to consider query string 998 parameters when comparing URIs or to rely on other properties 999 of the Cache object. 1001 4.2.8. Grouping 1003 A Grouping object identifies a large group of content to which this 1004 content belongs. 1006 Property: ccid 1008 Description: Content Collection identifier for an application- 1009 specific purpose such as logging. 1011 Type: String 1013 Mandatory-to-Specify: No. Default is an empty string. 1015 Property: sid 1017 Description: Session identifier for an application-specific 1018 purpose such as logging. 1020 Type: String 1022 Mandatory-to-Specify: No. Default is an empty string. 1024 4.3. CDNI Metadata Simple Data Type Descriptions 1026 This section describes the simpler data types that are used for 1027 properties of CDNI Metadata objects. 1029 4.3.1. Link 1031 A link object may be used in place of any of the objects or 1032 properties described above. Links can be used to avoid duplication 1033 if the same metadata information is repeated within the metadata 1034 tree. When a link replaces an object, its href property is set to 1035 the URI of the resource, its rel property is set to the name of the 1036 property it is replacing, and its type property is set to the type of 1037 the object it is replacing. 1039 Property: href 1041 Description: The URI of the of the addressable object being 1042 referenced. 1044 Type: URI 1046 Mandatory-to-Specify: Yes 1048 Property: rel 1050 Description: The Relationship between the referring object and 1051 the object it is referencing. 1053 Type: String 1055 Mandatory-to-Specify: Yes 1057 Property: type 1059 Description: The type of the object being referenced. 1061 Type: String 1063 Mandatory-to-Specify: Yes 1065 4.3.2. Protocol 1067 Protocol objects are used to specify registered protocols for content 1068 acquisition or delivery (see Section 7.1.1.2). 1070 Type: String 1072 Mandatory-to-Specify: Yes 1074 4.3.3. Endpoint 1076 A hostname (with optional port) or an IP address (with optional 1077 port). 1079 Note: All implementations MUST support IPv4 addresses encoded as 1080 specified by the 'IPv4address' rule in Section 3.2.2 of [RFC3986] and 1081 MUST support all IPv6 address formats specified in [RFC4291]. Server 1082 implementations SHOULD use IPv6 address formats specified in 1083 [RFC5952]. 1085 4.3.4. URI 1087 A URI as specified in [RFC3986]. 1089 4.3.5. Time 1090 A time value expressed in seconds since Unix epoch in the UTC 1091 timezone. 1093 5. CDNI Metadata Capabilities 1095 CDNI Metadata is used to convey information pertaining to content 1096 delivery from uCDN to dCDN. For optional metadata, it may be useful 1097 for the uCDN to know if the dCDN supports the metadata, prior to 1098 delegating any content requests to the dCDN. If optional-to- 1099 implement metadata is mandatory-to-enforce and the dCDN does not 1100 support it, any delegated requests for that content will fail, so 1101 there is no reason to delegate those requests. Likewise, for any 1102 metadata which may be assigned optional values, it may be useful for 1103 the uCDN to know which values the dCDN supports, prior to delegating 1104 any content requests to the dCDN. If a the optional value assigned 1105 to a given piece of content's metadata is not supported by the dCDN, 1106 any delegated requests for that content may fail, so there is likely 1107 no reason to delegate those requests. 1109 The CDNI Footprint and Capabilities Interface provides a means of 1110 advertising capabilities from dCDN to uCDN. Support for optional 1111 metadata and support for optional metadata values may be advertised 1112 using the capabilities interface. This section describes the 1113 capabilities advertisement requirements for the metadata defined in 1114 Section 4.2 1116 5.1. Protocol ACL Capabilities 1118 The ProtoclACL object contains a list of Protocol values. The dCDN 1119 MUST advertise which delivery protocols it supports so that the uCDN 1120 knows what type of content requests it can redirect to the dCDN. If 1121 the dCDN does not support a given acquisition or delivery protocol, 1122 the uCDN should not delegate requests requiring those protocols to 1123 the dCDN as the dCDN will not be able to properly acquire or deliver 1124 the content. 1126 ProtocolRules are defined for either acquisition or delivery. For 1127 some CDNs, certain combinations of acquisition and delivery protocols 1128 may not make sense (e.g., RTSP acquisition for HTTP delivery), while 1129 other CDNs may support customized protocol adaptation. ProtocolACL 1130 capabilities are not intended to define which combinations of 1131 protocols should be used. ProtocolACL capabilties are only intended 1132 to describe which protocols the dCDN does or does not support. 1133 Protocol combination restrictions are specified in the metadata 1134 itself and associated with specific groups of content assets. 1136 5.2. Authorization Metadata Capabilities 1137 The Authorization object contains a list of Auth values. The dCDN 1138 MUST advertise which authorization algorithms it supports so that the 1139 uCDN knows what type of content requests it can redirect to the dCDN. 1140 If the dCDN does not support a given authorization algorithm, the 1141 uCDN should not delegate requests requiring that algorithm to the 1142 dCDN as the dCDN will not be able to properly acquire the content or 1143 enforce delivery restrictions. 1145 6. CDNI Metadata interface 1147 This section specifies an interface to enable a Downstream CDN to 1148 retrieve CDNI Metadata objects from an Upstream CDN. 1150 The interface can be used by a Downstream CDN to retrieve CDNI 1151 Metadata objects either dynamically as required by the Downstream CDN 1152 to process received requests (for example in response to receiving a 1153 CDNI Request Routing request from an Upstream CDN or in response to 1154 receiving a request for content from a User Agent) or in advance of 1155 being required (for example in case of prepositioned CDNI Metadata 1156 acquisition). 1158 The CDNI Metadata interface is built on the principles of RESTful web 1159 services. This means that requests and responses over the interface 1160 are built around the transfer of representations of hyperlinked 1161 resources. A resource in the context of the CDNI Metadata interface 1162 is any object in the Data Model (as described in Section 3 through 1163 Section 4). 1165 In the general case a CDNI Metadata server makes each instance of an 1166 addressable CDNI Metadata object available via a unique URI that 1167 returns a representation of that instance of that CDNI Metadata 1168 object. When an object needs to reference another addressable CDNI 1169 Metadata object (for example a HostIndex object referencing a 1170 HostMetadata object) it does so by including a link to the referenced 1171 object. 1173 CDNI Metadata servers are free to assign whatever structure they 1174 desire to the URIs for CDNI Metadata objects and CDNI Metadata 1175 clients MUST NOT make any assumptions regarding the structure of CDNI 1176 Metadata URIs or the mapping between CDNI Metadata objects and their 1177 associated URIs. Therefore any URIs present in the examples below 1178 are purely illustrative and are not intended to impose a definitive 1179 structure on CDNI Metadata interface implementations. 1181 6.1. Transport 1183 The CDNI Metadata interface uses HTTP as the underlying protocol 1184 transport. 1186 The HTTP Method in the request defines the operation the request 1187 would like to perform. Servers implementing the CDNI Metadata 1188 interface MUST support the HTTP GET and HEAD methods. 1190 The corresponding HTTP Response returns the status of the operation 1191 in the HTTP Status Code and returns the current representation of the 1192 resource (if appropriate) in the Response Body. HTTP Responses from 1193 servers implementing the CDNI Metadata interface that contain a 1194 response body SHOULD include an ETag to enable validation of cached 1195 versions of returned resources. 1197 The CDNI Metadata interface specified in this document is a read-only 1198 interface. Therefore support for other HTTP methods such as PUT, 1199 POST and DELETE etc. is not specified. Server implementations of 1200 this interface SHOULD reject all methods other than GET and HEAD. 1202 As the CDNI Metadata interface builds on top of HTTP, CDNI Metadata 1203 servers may make use of any HTTP feature when implementing the CDNI 1204 Metadata interface, for example a CDNI Metadata server may make use 1205 of HTTP's caching mechanisms to indicate that the returned response/ 1206 representation can be reused without re-contacting the CDNI Metadata 1207 server. 1209 6.2. Retrieval of CDNI Metadata resources 1211 In the general case a CDNI Metadata server makes each instance of an 1212 addressable CDNI Metadata object available via a unique URI and 1213 therefore in order to retrieve CDNI Metadata, a CDNI Metadata client 1214 first makes a HTTP GET request for the URI of the HostIndex which 1215 provides the CDNI Metadata client with a list of Hostnames for which 1216 the upstream CDN may delegate content delivery to the downstream CDN. 1218 In order to retrieve the CDNI Metadata for a particular request the 1219 CDNI Metadata client processes the received HostIndex object and 1220 finds the corresponding HostMetadata entry (by matching the hostname 1221 in the request against the hostnames in the HostMatch). If the 1222 HostMetadata is linked (rather than embedded), the CDNI metadata 1223 client then makes a GET request for the URI specified in the href 1224 property of the Link object which points to the HostMetadata object 1225 itself. 1227 In order to retrieve the most specific metadata for a particular 1228 request, the CDNI metadata client inspects the HostMetadata for 1229 references to more specific PathMetadata objects. If any 1230 PathMetadata match the request (and are linked rather than embedded), 1231 the CDNI metadata client makes another GET request for the 1232 PathMetadata. Each PathMetadata object may also include references 1233 to yet more specific metadata. If this is the case, the CDNI 1234 metadata client continues requesting PathMetadata recursively. 1236 Where a downstream CDN is interconnected with multiple upstream CDNs, 1237 the downstream CDN must decide which upstream CDN's CDNI metadata 1238 should be used to handle a particular User Agent request. 1240 When application level redirection (e.g. HTTP 302 redirects) is being 1241 used between CDNs, it is expected that the downstream CDN will be 1242 able to determine the upstream CDN that redirected a particular 1243 request from information contained in the received request (e.g. via 1244 the URI). With knowledge of which upstream CDN routed the request, 1245 the downstream CDN can choose the correct metadata server from which 1246 to obtain the HostIndex. Note that the HostIndex served by each uCDN 1247 may be unique. 1249 In the case of DNS redirection there is not always sufficient 1250 information carried in the DNS request from User Agents to determine 1251 the upstream CDN that redirected a particular request (e.g. when 1252 content from a given host is redirected to a given downstream CDN by 1253 more than one upstream CDN) and therefore downstream CDNs may have to 1254 apply local policy when deciding which upstream CDN's metadata to 1255 apply. 1257 6.3. Bootstrapping 1259 The URI for the HostIndex object of a given upstream CDN needs to be 1260 either discovered by or configured in the downstream CDN. All other 1261 objects/resources are then discoverable from the HostIndex object by 1262 following the links in the HostIndex object and the referenced 1263 HostMetadata and PathMetadata objects. 1265 If the URI for the HostIndex object is not manually configured in the 1266 downstream CDN then the HostIndex URI could be discovered. A 1267 mechanism allowing the downstream CDN to discover the URI of the 1268 HostIndex is outside the scope of this document. 1270 6.4. Encoding 1272 Object are resources that may be: 1274 o Addressable, where the object is a resource that may be retrieved 1275 or referenced via its own URI. 1277 o Embedded, where the object is contained (or inlined) within a 1278 property of an addressable object. 1280 In the descriptions of objects we use the term "X contains Y" to mean 1281 either Y is directly embedded in X or that Y is linked to by X. It is 1282 generally a deployment choice for the uCDN implementation to decide 1283 when and which CDNI Metadata objects to embed and which are 1284 separately addressable. 1286 6.4.1. MIME Media Types 1288 All MIME types are prefixed with "application/cdni." The MIME type 1289 for each object matches the type name of that object as defined by 1290 this document. Table 3 lists a few examples of the MIME Media Type 1291 for each object (resource) that is retrievable through the CDNI 1292 Metadata interface. 1294 +--------------+-------------------------------+ 1295 | Data Object | MIME Media Type | 1296 +--------------+-------------------------------+ 1297 | HostIndex | application/cdni.HostIndex | 1298 | HostMatch | application/cdni.HostMatch | 1299 | HostMetadata | application/cdni.HostMetadata | 1300 | PathMatch | application/cdni.PathMatch | 1301 | PathMetadata | application/cdni.PathMetadata | 1302 +--------------+-------------------------------+ 1304 Table 3: Example MIME Media Types for CDNI Metadata objects 1306 See http://www.iana.org/assignments/media-types/index.html for 1307 reference. 1309 6.4.2. JSON Encoding of Objects 1311 CDNI Metadata objects are encoded as JSON objects containing a 1312 dictionary of (key,value) pairs where the keys are the property names 1313 and the values are the associated property values. 1315 The keys of the dictionary are the names of the properties associated 1316 with the object and are therefore dependent on the specific object 1317 being encoded (i.e. dependent on the MIME Media Type of the returned 1318 resource). Likewise, the values associated with each key are 1319 dependent on the specific object being encoded (i.e. dependent on the 1320 MIME Media Type of the returned resource). 1322 Dictionary keys in JSON are case sensitive and therefore by 1323 convention any dictionary key defined by this document (for example 1324 the names of CDNI Metadata object properties) MUST be represented in 1325 lowercase. 1327 In addition to the properties specific to each object type, the keys 1328 defined below may be present in any object. 1330 Key: base 1332 Description: Provides a prefix for any relative URLs in the 1333 object. This is similar to the XML base tag [XML-BASE]. If 1334 absent, all URLs in the remainder of the document must be 1335 absolute URLs. 1337 Type: URI 1339 Mandatory: No 1341 Key: links 1343 Description: The links of this object to other addressable 1344 objects. Any property may be replaced by a link to an object 1345 with the same type as the property it replaces. 1347 Type: List of Link objects 1349 Mandatory: Yes 1351 6.4.2.1. JSON Example 1353 A downstream CDN may request the HostIndex and receive the following 1354 object of type "application/cdni.HostIndex+json": 1356 { 1357 "hosts": [ 1358 { 1359 "host": "video.example.com", 1360 "links": [ 1361 { 1362 "rel": "host-metadata", 1363 "type": "application/cdni.HostMetadata", 1364 "href": "http://metadata.example.ucdn.com/video" 1365 } 1367 ] 1368 }, 1369 { 1370 "host": "images.example.com", 1371 "links": [ 1372 { 1373 "rel": "host-metadata", 1374 "type": "application/cdni.HostMetadata", 1375 "href": "http://metadata.ucdn.example.com/images" 1376 } 1377 ] 1378 } 1379 ] 1380 } 1382 If the incoming request has a Host header with "video.example.com" 1383 then the downstream CDN would fetch from the next metadata object 1384 from "http://metadata.ucdn.example.com/video" expecting a MIME type 1385 of "application/cdni.HostMetadata+json": 1387 { 1388 "metadata": [ 1389 { 1390 "type": "application/cdni.SourceMetadata", 1391 "value": { 1392 "sources": [ 1393 { 1394 "links": [{ 1395 "rel": "auth", 1396 "type": "application/cdni.Auth", 1397 "href": "http://metadata.ucdn.example.com/auth1234" 1398 }], 1399 "endpoint": "acq1.ucdn.example.com", 1400 "protocol": "ftp" 1401 }, 1402 { 1403 "links": [{ 1404 "rel": "auth", 1405 "type": "application/cdni.Auth", 1406 "href": "http://metadata.ucdn.example.com/auth1234" 1407 }], 1408 "endpoint": "acq2.ucdn.example.com", 1409 "protocol": "http" 1410 } 1411 ] 1412 } 1413 }, 1414 { 1415 "type": "application/cdni.LocationACL", 1416 "value": { 1417 "locations": [ 1418 { 1419 "locations": [ 1420 { "iprange": "192.168.0.0/16" } 1421 ], 1422 "action": "deny" 1423 } 1424 ] 1425 } 1426 }, 1427 { 1428 "type": "application/cdni.ProtocolACL", 1429 "value": { 1430 "protocols": [ 1431 { 1432 "protocols": [ 1433 "ftp" 1434 ], 1435 "action": "deny" 1436 } 1437 ] 1438 } 1439 } 1440 ], 1441 "paths": [ 1442 { 1443 "path-pattern": { 1444 "pattern": "/videos/trailers/*" 1445 }, 1446 "links": [{ 1447 "rel": "path-metadata", 1448 "type": "application/cdni.PathMetadata", 1449 "href": "http://metadata.ucdn.example.com/videos/trailers" 1450 }] 1451 }, 1452 { 1453 "path-pattern": { 1454 "pattern": "/videos/movies/*" 1455 }, 1456 "links": [{ 1457 "rel": "pathmetadata", 1458 "type": "application/cdni.PathMetadata", 1459 "href": "http://metadata.ucdn.example.com/videos/movies" 1460 }] 1461 } 1463 ] 1464 } 1466 Suppose the path of the requested resource matches the "/video/movies 1467 /*" pattern, the next metadata requested would be for "http:// 1468 metadata.ucdn.example.com/video/movies" with an expected type of 1469 "application/cdni.PathMetadata": 1471 { 1472 "metadata": [], 1473 "paths": [ 1474 { 1475 "path-pattern": { 1476 "pattern": "/videos/movies/hd/*" 1477 }, 1478 "links": [{ 1479 "rel": "pathmetadata", 1480 "type": "application/cdni.PathMetadata", 1481 "href": "http://metadata.ucdn.example.com/videos/movies/hd" 1482 }] 1483 } 1484 ] 1485 } 1487 Finally, if the path of the requested resource also matches the "/ 1488 videos/movies/hd/*" pattern, the downstream CDN would also fetch the 1489 following object from "http://metadata.ucdn.example.com/videos/movies 1490 /hd" with MIME type "application/cdni.PathMetadata": 1492 { 1493 "metadata": [ 1494 { 1495 "type": "application/cdni.TimeWindowACL", 1496 "value": { 1497 "times": [ 1498 "times": [ 1499 { 1500 "start": "1213948800", 1501 "end": "1327393200" 1502 } 1503 ], 1504 "type": "allow" 1505 ] 1506 } 1507 } 1508 ] 1510 } 1512 6.5. Extensibility 1514 The set of property Metadata may be extended with proprietary and/or 1515 custom property Metadata. The GenericMetadata object defined in 1516 Section 4.1.7 allows any Metadata property to be included in either 1517 the HostMetadata or PathMetadata lists. As described in Section 3.4, 1518 any proprietary and/or custom property Metadata SHOULD be identified 1519 by the "ext." prefix in an appropriately descriptive type which 1520 conveys the organization defining the property Metadata and the 1521 function of the property Metadata. 1523 Note: Identification of the property Metadata defining organization 1524 in the property Metadata type decreases the possibility of property 1525 Metadata type collision. The fully-qualified domain name of the 1526 organization in reverse order may be used for this purpose. 1528 6.5.1. Metadata Enforcement 1530 At any given time, the set of property Metadata supported by the uCDN 1531 may not match the set of property Metadata supported by the dCDN. 1532 The uCDN may or may not know which property Metadata the dCDN 1533 supports. In cases where the uCDN supports Metadata that the dCDN 1534 does not, the dCDN MUST be aware of any Metadata marked as 1535 "mandatory-to-enforce". If a CDN does not understand or is unable to 1536 perform the functions associated with any "mandatory-to-enforce" 1537 Metadata, the CDN MUST NOT service any requests for the corresponding 1538 content. 1540 Any standard which defines a new GenericMetadata Type SHOULD also 1541 define whether or not the new metadata is mandatory-to-enforce. 1543 Note: Ideally, uCDNs would not delegate content requests to a dCDN 1544 which does not support the mandatory-to-enforce Metadata associated 1545 with the content being requested. However, even if the uCDN has a 1546 priori knowledge of the Metadata supported by the dCDN (e.g., via the 1547 CDNI capabilities interface or through out-of-band negotiation 1548 between CDN operators) Metadata support may fluctuate or be 1549 inconsistent (e.g., due to mis-communication, mis-configuration, or 1550 temporary outage). Thus, the dCDN MUST evaluate all Metadata 1551 associated with content requests and reject any requests where 1552 "mandatory-to-enforce" Metadata associated with the content cannot be 1553 enforced. 1555 6.5.2. Metadata Override 1556 It is possible that new Metadata definitions may obsolete or override 1557 existing property Metadata (e.g., a future revision of the CDNI 1558 Metadata interface may redefine the Auth Metadata or a custom vendor 1559 extension may implement an alternate Auth Metadata option). If 1560 multiple Metadata (e.g., cdni.v2.Auth, ext.vendor1.Auth, and 1561 ext.vendor2.Auth) all override an existing Metadata (e.g., cdni.Auth) 1562 and all are marked as "mandatory-to-enforce", it may be ambiguous 1563 which Metadata should be applied, especially if the functionality of 1564 the Metadata conflict. 1566 As described in Section 3.3, Metadata override only applies to 1567 Metadata objects of the same exact type, found in HostMetadata and 1568 nested PathMetadata structures. The CDNI Metadata interface does not 1569 support enforcement of dependencies between different Metadata types. 1570 It is the responsibility of the CSP and the CDN operators to ensure 1571 that Metadata assigned to a given content do not conflict. 1573 Note: Because Metadata is inherently ordered in GenericMetadata 1574 lists, as well as in the PathMetadata hierarchy and PathMatch lists, 1575 multiple conflicting Metadata types MAY be used, however, Metadata 1576 hierarchies MUST ensure that independent PathMatch root objects are 1577 used to prevent ambiguous or conflicting Metadata definitions. 1579 6.6. Versioning 1581 The version of CDNI Metadata Structural objects is specified by the 1582 HTTP Content-Type header. Upon responding to a request for an 1583 object, a metadata server MUST include a Content-Type header with the 1584 MIME-type and verison number of the object. HTTP requests sent to a 1585 metadata server SHOULD include an Accept header with the MIME-type 1586 and version of the expected object. Unless stated otherwise, the 1587 verison of each object defined by this document is version 1. For 1588 example: "Content-Type: application/cdni.HostIndex.v1":. 1590 GenericMetadata objects include a "type" property which specifies the 1591 MIME-type of the GenericMetadata value. This MIME-type should also 1592 include a version. Any document which defines a new type of 1593 GenericMetadata should specify the version number which it describes. 1594 For example: "application/cdni.Location.v1". 1596 7. IANA Considerations 1598 This document requests the registration of the "application/cdni" 1599 MIME Media Type under the IANA MIME Media Type registry (http:// 1600 www.iana.org/assignments/media-types/index.html). 1602 7.1. GenericMetadata Type Registry 1603 CDNI Metadata is distributed as a list of GenericMetadata objects 1604 which specify a type field and a type-specific value field, as 1605 described in Section 4.1.7. In order to prevent namespace collisions 1606 for GenericMetadata object types a new IANA registry is requested for 1607 "CDNI GenericMetadata Types" namespace. The namespace shall be split 1608 into two partitions: standard and vendor defined. As described in 1609 Section 4.1.7 and Section 6.5, the vendor defined namespace partition 1610 SHOULD use a namespace prefix of "ext.", while the standard namespace 1611 partition MUST NOT. 1613 The standard namespace partition MUST conform to the "RFC Required" 1614 policy as defined in [RFC5226]. The vendor defined namespace 1615 partition should be further partitioned into vendor specific 1616 partitions with the prefix "ext.vendor_name.". The vendor defined 1617 partition SHOULD conform to the "Expert Review" policy as defined in 1618 [RFC5226]. The expert review is simply to prevent namespace 1619 hoarding. The vendor specific partitions MAY conform to the "First 1620 Come First Served" policy as defined in [RFC5226], however, vendors 1621 defining new GenericMetadata types which conflict with other 1622 GenericMetadata types SHOULD follow the guidelines for the 1623 "Specification Required" policy as defined in [RFC5226]. 1625 The following table defines the initial values for the standard 1626 partition: 1628 +----------------+---------------+ 1629 | type name | Specification | 1630 +----------------+---------------+ 1631 | SourceMetadata | RFCthis | 1632 | LocationACL | RFCthis | 1633 | TimeWindowACL | RFCthis | 1634 | ProtocolACL | RFCthis | 1635 | Auth | RFCthis | 1636 | Cache | RFCthis | 1637 | Grouping | RFCthis | 1638 +----------------+---------------+ 1640 7.1.1. GenericMetadata Sub-Registries 1642 Some of the initial standard GenericMetadata objects contain 1643 enumerated types which require registration (i.e., LocationACL 1644 footprint types, ProtocolACL protocols, and Auth protocols). The 1645 following sections define the initial values for these 1646 GenericMetadata type sub-registries. 1648 7.1.1.1. Footprint Sub-Registry 1649 The "CDNI Metadata Footprint Types" namespace defines the valid 1650 Footprint object type values used by the Footprint object in 1651 Section 4.2.2.2. Additions to the Footprint type namespace MUST 1652 conform to the "Expert Review" policy as defined in [RFC5226]. The 1653 expert review should verify that new type definitions do not 1654 duplicate existing type definitions and prevent gratuitous additions 1655 to the namespace. 1657 The following table defines the initial Footprint type values: 1659 +---------------+---------------------------------------------------+ 1660 | type name | definition | 1661 +---------------+---------------------------------------------------+ 1662 | IPv4 | Single IPv4 address | 1663 | IPv6 | Single IPv6 address | 1664 | IPv4Range | List of contiguous IPv4 addresses denoted by a | 1665 | | start address and an end address separated by a | 1666 | | dash (e.g., 192.168.0.1-192.168.0.20), inclusive. | 1667 | IPv6Range | List of contiguous IPv6 addresses denoted by a | 1668 | | start address and an end address separated by a | 1669 | | dash (e.g., fc80::0001-fc80::0014), inclusive. | 1670 | IPv4CIDR | IPv4 address block using slash prefix length | 1671 | | notation (e.g., 192.168.0.16/28). | 1672 | IPv6CIDR | IPv6 address block using slash prefix length | 1673 | | notation (e.g., fc80::0010/124). | 1674 | ASN | Autonomous System (AS) Number | 1675 | CountryCode | ISO 3166-1 alpha-2 code | 1676 | DVDRegion | DVD Region code (i.e., integer in the range 0-6). | 1677 +---------------+---------------------------------------------------+ 1679 7.1.1.2. Protocol Sub-Registry 1681 The "CDNI Metadata Protocols" namespace defines the valid Protocol 1682 object values in Section 4.3.2, used by the SourceMetadata and 1683 ProtocolACL objects. Additions to the Protocol namespace MUST 1684 conform to the "Expert Review" policy as defined in [RFC5226]. The 1685 expert review should verify that new type definitions do not 1686 duplicate existing type definitions and prevent gratuitous additions 1687 to the namespace. 1689 The following table defines the initial Protocol values: 1691 +---------------+------------+ 1692 | protocol name | definition | 1693 +---------------+------------+ 1694 | HTTP | TBD | 1695 | HTTPS | TBD | 1696 | RTSP | TBD | 1697 | RTMP | TBD | 1698 +---------------+------------+ 1700 7.1.1.3. Authentication Sub-Registry 1702 The "CDNI Metadata Auth" namespace defines the valid Auth object 1703 types used by the Auth object in Section 4.2.6. Additions to the 1704 Footprint type namespace MUST conform to the "Expert Review" policy 1705 as defined in [RFC5226]. The expert review should verify that new 1706 type definitions do not duplicate existing type definitions and 1707 prevent gratuitous additions to the namespace. 1709 The following table defines the initial Auth type values: 1711 +------------------+------------------------------------------------+ 1712 | type name | definition | 1713 +------------------+------------------------------------------------+ 1714 | credentials | Simple username and password authentication as | 1715 | | defined by Section 4.2.6.1. | 1716 +------------------+------------------------------------------------+ 1718 8. Security Considerations 1720 The CDNI Metadata Interface is expected to be secured as a function 1721 of the transport protocol (e.g. HTTP authentication [RFC2617], HTTPS 1722 [RFC2818], or inter-domain IPSec). 1724 If a malicious metadata server is contacted by a downstream CDN, the 1725 malicious server may provide metadata to the downstream CDN which 1726 denies service for any piece of content to any user agent. The 1727 malicious server may also provide metadata which directs a downstream 1728 CDN to a malicious origin server instead of the actual origin server. 1729 The dCDN is expected to authenticate the server to prevent this 1730 situation (e.g. by using HTTPS and validating the server's 1731 certificate). 1733 A malicious metadata client could request metadata for a piece of 1734 content from an upstream CDN. The metadata information may then be 1735 used to glean information regarding the uCDN or to contact an 1736 upstream origin server. The uCDN is expected to authenticate client 1737 requests to prevent this situation. 1739 9. Acknowledgements 1740 The authors would like to thank David Ferguson and Francois le 1741 Faucheur for their valuable comments and input to this document. 1743 10. References 1745 10.1. Normative References 1747 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1748 Requirement Levels", BCP 14, RFC 2119, March 1997. 1750 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1751 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1752 Authentication: Basic and Digest Access Authentication", 1753 RFC 2617, June 1999. 1755 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1757 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1758 Architecture", RFC 4291, February 2006. 1760 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1761 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1762 May 2008. 1764 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1765 Address Text Representation", RFC 5952, August 2010. 1767 10.2. Informative References 1769 [I-D.ietf-cdni-framework] 1770 Peterson, L. and B. Davie, "Framework for CDN 1771 Interconnection", draft-ietf-cdni-framework-03 (work in 1772 progress), February 2013. 1774 [I-D.ietf-cdni-requirements] 1775 Leung, K. and Y. Lee, "Content Distribution Network 1776 Interconnection (CDNI) Requirements", draft-ietf-cdni- 1777 requirements-05 (work in progress), February 2013. 1779 [I-D.zyp-json-schema] 1780 Zyp, K. and G. Court, "A JSON Media Type for Describing 1781 the Structure and Meaning of JSON Documents", draft-zyp- 1782 json-schema-03 (work in progress), November 2010. 1784 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1785 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1786 3986, January 2005. 1788 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC 1789 4151, October 2005. 1791 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1792 Syndication Format", RFC 4287, December 2005. 1794 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 1795 Distribution Network Interconnection (CDNI) Problem 1796 Statement", RFC 6707, September 2012. 1798 [XML-BASE] 1799 Marsh, J., Ed. and R. Tobin, Ed., "XML Base (Second 1800 Edition) - http://www.w3.org/TR/xmlbase/", January 2009. 1802 Appendix A. Relationship to the CDNI Requirements 1804 Section 6 of [I-D.ietf-cdni-requirements] lists the requirements for 1805 the CDNI Metadata Distribution interface. This section outlines 1806 which of those requirements are met by the CDNI Metadata interface 1807 specified in this document. 1809 All metadata requirements are met either directly or indirectly by 1810 the CDNI Metadata Interface described in this document, with the 1811 clarifications or exceptions described in the following paragraphs. 1813 Requirements related to pre-positioning of metadata are met by this 1814 document on the assumption that other CDNI Interfaces are to be used 1815 by the upstream CDN to trigger the pre-positioning of metadata by the 1816 downstream CDN via the CDNI Metadata Interface. Triggering metadata 1817 pre-positioning is beyond the scope of the CDNI Metadata interface. 1818 However, the interface as described by this document supports pulling 1819 metadata on-demand for the purpose of pre-positioning. 1821 Requirement META-7 relating to modification of metadata by the 1822 upstream CDN is met both by allowing timeouts on the cacheability of 1823 metadata objects and by allowing other CDNI interfaces to initiate a 1824 refetch or purge of metadata. 1826 Requirement META-18 relating to surrogate cache behavior parameters 1827 is supported via extensibility. However, the example parameters in 1828 META-18 are not described in this document. 1830 Authors' Addresses 1831 Ben Niven-Jenkins 1832 Velocix (Alcatel-Lucent) 1833 3 Ely Road 1834 Milton, Cambridge CB24 6AA 1835 UK 1837 Email: ben@velocix.com 1839 Rob Murray 1840 Velocix (Alcatel-Lucent) 1841 3 Ely Road 1842 Milton, Cambridge CB24 6AA 1843 UK 1845 Email: rmurray@velocix.com 1847 Grant Watson 1848 Velocix (Alcatel-Lucent) 1849 3 Ely Road 1850 Milton, Cambridge CB24 6AA 1851 UK 1853 Email: gwatson@velocix.com 1855 Matt Caulfield 1856 Cisco Systems 1857 1414 Massachusetts Avenue 1858 Boxborough, MA 01719 1859 USA 1861 Phone: +1 978 936 9307 1862 Email: mcaulfie@cisco.com 1864 Kent Leung 1865 Cisco Systems 1866 3625 Cisco Way 1867 San Jose 95134 1868 USA 1870 Phone: +1 408 526 5030 1871 Email: kleung@cisco.com 1872 Kevin J. Ma 1873 Azuki Systems, Inc. 1874 43 Nagog Park 1875 Acton, MA 01720 1876 USA 1878 Phone: +1 978-844-5100 1879 Email: kevin.ma@azukisystems.com