idnits 2.17.1 draft-ietf-cdni-metadata-10.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 6, 2015) is 3189 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: 'Object' is mentioned on line 324, but not defined == Unused Reference: 'RFC5288' is defined on line 2366, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO3166-1' ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 5861 ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-20) exists of draft-ietf-cdni-redirection-10 -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 5 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 Velocix (Alcatel-Lucent) 5 Expires: January 7, 2016 M. Caulfield 6 Cisco Systems 7 K. Ma 8 Ericsson 9 July 6, 2015 11 CDN Interconnection Metadata 12 draft-ietf-cdni-metadata-10 14 Abstract 16 The Content Delivery Networks Interconnection (CDNI) Metadata 17 interface enables interconnected Content Delivery Networks (CDNs) to 18 exchange content distribution metadata in order to enable content 19 acquisition and delivery. The CDNI metadata associated with a piece 20 of content provides a downstream CDN with sufficient information for 21 the downstream CDN to service content requests on behalf of an 22 upstream CDN. This document describes both a base set of CDNI 23 metadata and the protocol for exchanging that metadata. 25 Requirements Language 27 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 28 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 29 document are to be interpreted as described in RFC 2119 [RFC2119]. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on January 7, 2016. 48 Copyright Notice 50 Copyright (c) 2015 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 66 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 67 1.2. Supported Metadata Capabilities . . . . . . . . . . . . . 5 68 2. Design Principles . . . . . . . . . . . . . . . . . . . . . . 6 69 3. CDNI Metadata model . . . . . . . . . . . . . . . . . . . . . 7 70 3.1. HostIndex, HostMatch, HostMetadata, PathMatch, 71 PatternMatch and PathMetadata objects . . . . . . . . . . 8 72 3.2. Generic CDNI Metadata Object Properties . . . . . . . . . 10 73 3.3. Metadata Inheritance and Override . . . . . . . . . . . . 13 74 4. CDNI Metadata objects . . . . . . . . . . . . . . . . . . . . 14 75 4.1. Definitions of the CDNI structural metadata objects . . . 15 76 4.1.1. HostIndex . . . . . . . . . . . . . . . . . . . . . . 15 77 4.1.2. HostMatch . . . . . . . . . . . . . . . . . . . . . . 16 78 4.1.3. HostMetadata . . . . . . . . . . . . . . . . . . . . 17 79 4.1.4. PathMatch . . . . . . . . . . . . . . . . . . . . . . 18 80 4.1.5. PatternMatch . . . . . . . . . . . . . . . . . . . . 19 81 4.1.6. PathMetadata . . . . . . . . . . . . . . . . . . . . 20 82 4.1.7. GenericMetadata . . . . . . . . . . . . . . . . . . . 21 83 4.2. Definitions of the initial set of CDNI Generic Metadata 84 objects . . . . . . . . . . . . . . . . . . . . . . . . . 23 85 4.2.1. SourceMetadata . . . . . . . . . . . . . . . . . . . 23 86 4.2.1.1. Source . . . . . . . . . . . . . . . . . . . . . 24 87 4.2.2. LocationACL Metadata . . . . . . . . . . . . . . . . 25 88 4.2.2.1. LocationRule . . . . . . . . . . . . . . . . . . 27 89 4.2.2.2. Footprint . . . . . . . . . . . . . . . . . . . . 28 90 4.2.3. TimeWindowACL Metadata . . . . . . . . . . . . . . . 28 91 4.2.3.1. TimeWindowRule . . . . . . . . . . . . . . . . . 29 92 4.2.3.2. TimeWindow . . . . . . . . . . . . . . . . . . . 29 93 4.2.4. ProtocolACL Metadata . . . . . . . . . . . . . . . . 30 94 4.2.4.1. ProtocolRule . . . . . . . . . . . . . . . . . . 30 95 4.2.5. DeliveryAuthorization Metadata . . . . . . . . . . . 31 96 4.2.6. Cache . . . . . . . . . . . . . . . . . . . . . . . . 31 97 4.2.7. Grouping . . . . . . . . . . . . . . . . . . . . . . 32 98 4.3. CDNI Metadata Simple Data Type Descriptions . . . . . . . 32 99 4.3.1. Link . . . . . . . . . . . . . . . . . . . . . . . . 32 100 4.3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . 33 101 4.3.3. Endpoint . . . . . . . . . . . . . . . . . . . . . . 33 102 4.3.4. URI . . . . . . . . . . . . . . . . . . . . . . . . . 33 103 4.3.5. Time . . . . . . . . . . . . . . . . . . . . . . . . 33 104 4.3.6. Auth . . . . . . . . . . . . . . . . . . . . . . . . 33 105 4.3.6.1. CredentialAuth Type . . . . . . . . . . . . . . . 34 106 4.3.7. IPv4CIDR . . . . . . . . . . . . . . . . . . . . . . 34 107 4.3.8. IPv6CIDR . . . . . . . . . . . . . . . . . . . . . . 35 108 4.3.9. ASN . . . . . . . . . . . . . . . . . . . . . . . . . 35 109 4.3.10. CountryCode . . . . . . . . . . . . . . . . . . . . . 35 110 5. CDNI Metadata Capabilities . . . . . . . . . . . . . . . . . 35 111 6. CDNI Metadata interface . . . . . . . . . . . . . . . . . . . 36 112 6.1. Transport . . . . . . . . . . . . . . . . . . . . . . . . 36 113 6.2. Retrieval of CDNI Metadata resources . . . . . . . . . . 37 114 6.3. Bootstrapping . . . . . . . . . . . . . . . . . . . . . . 38 115 6.4. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 39 116 6.4.1. MIME Media Types . . . . . . . . . . . . . . . . . . 39 117 6.4.2. I-JSON Encoding of Objects . . . . . . . . . . . . . 40 118 6.4.2.1. Encoded CDNI Metadata Example . . . . . . . . . . 41 119 6.5. Extensibility . . . . . . . . . . . . . . . . . . . . . . 45 120 6.6. Metadata Enforcement . . . . . . . . . . . . . . . . . . 46 121 6.7. Metadata Conflicts . . . . . . . . . . . . . . . . . . . 46 122 6.8. Versioning . . . . . . . . . . . . . . . . . . . . . . . 47 123 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 124 7.1. CDNI Metadata Footprint Types Registry . . . . . . . . . 48 125 7.2. CDNI Metadata Protocol Types Registry . . . . . . . . . . 49 126 7.3. CDNI Metadata Auth Types Registry . . . . . . . . . . . . 49 127 8. Security Considerations . . . . . . . . . . . . . . . . . . . 50 128 8.1. Authentication . . . . . . . . . . . . . . . . . . . . . 50 129 8.2. Confidentiality . . . . . . . . . . . . . . . . . . . . . 51 130 8.3. Integrity . . . . . . . . . . . . . . . . . . . . . . . . 51 131 8.4. Privacy . . . . . . . . . . . . . . . . . . . . . . . . . 51 132 8.5. Securing the CDNI Metadata interface . . . . . . . . . . 51 133 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 52 134 10. Contributing Authors . . . . . . . . . . . . . . . . . . . . 52 135 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 136 11.1. Normative References . . . . . . . . . . . . . . . . . . 53 137 11.2. Informative References . . . . . . . . . . . . . . . . . 53 138 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54 140 1. Introduction 142 Content Delivery Networks Interconnection (CDNI) ([RFC6707]) enables 143 a downstream Content Delivery Network (dCDN) to service content 144 requests on behalf of an upstream CDN (uCDN). 146 The CDNI Metadata interface is discussed in [RFC7336] along with four 147 other interfaces that may be used to compose a CDNI solution (CDNI 148 Control interface, CDNI Request Routing Redirection interface, CDNI 149 Footprint & Capabilities Advertisement interface and CDNI Logging 150 interface). [RFC7336] describes each interface, and the 151 relationships between them. The requirements for the CDNI metadata 152 interface are specified in [RFC7337]. 154 The CDNI metadata associated with a piece of content (or with a set 155 of content) provides a dCDN with sufficient information for servicing 156 content requests on behalf of an uCDN in accordance with the policies 157 defined by the uCDN. 159 This document focuses on the CDNI Metadata interface which enables a 160 dCDN to obtain CDNI Metadata from an uCDN so that the dCDN can 161 properly process and respond to: 163 o Redirection requests received over the CDNI Request Routing 164 Redirection interface [I-D.ietf-cdni-redirection]. 166 o Content requests received directly from User Agents. 168 Specifically, this document specifies: 170 o A data structure for mapping content requests and redirection 171 requests to CDNI Metadata objects (Section 3 and Section 4.1). 173 o An initial set of CDNI Generic Metadata objects (Section 4.2). 175 o A RESTful web service for the transfer of CDNI Metadata 176 (Section 6). 178 1.1. Terminology 180 This document reuses the terminology defined in [RFC6707]. 182 Additionally, the following terms are used throughout this document 183 and are defined as follows: 185 o Object - a collection of properties. 187 o Property - a key and value pair where the key is a property name 188 and the value is the property value or an object. 190 1.2. Supported Metadata Capabilities 192 Only the metadata for a small set of initial capabilities is 193 specified in this document. This set provides the minimum amount of 194 metadata for basic CDN interoperability while still meeting the 195 requirements set forth by [RFC7337]. 197 The following high-level functionality is configured via the metadata 198 described in Section 4: 200 o Acquisition Source: Metadata for allowing a dCDN to fetch content 201 from a uCDN. 203 o Delivery Access Control: Metadata for restricting (or permitting) 204 access to content based on any of the following factors: 206 * Location 208 * Time Window 210 * Delivery Protocol 212 o Delivery Authorization: Metadata for authorizing dCDN user agent 213 requests. 215 o Cache Control: Metadata for controlling cache behavior of the 216 dCDN. 218 The metadata encoding described by this document is extensible in 219 order to allow for future additions to this list. 221 The set of metadata specified in this document, covering the initial 222 capabilities above, is only able to support CDN interconnection for 223 the delivery of content by a dCDN using HTTPv1.1 [RFC7230] and for a 224 dCDN to be able to acquire content from a uCDN using either HTTPv1.1 225 or HTTPv1.1 over TLS [RFC2818]. 227 Supporting CDN interconnection for the delivery of content using 228 unencrypted HTTPv2.0 [I-D.ietf-httpbis-http2] (as well as for a dCDN 229 to acquire content using unencrypted HTTPv2.0 or HTTPv2.0 over TLS) 230 requires the registration of these protocol names in the CDNI 231 Metadata Protocol Registry. 233 Supporting CDN interconnection for the delivery of content using 234 HTTPv1.1 over TLS or HTTPv2.0 over TLS requires specifying additional 235 metadata objects to carry the properties required to establish a TLS 236 session, for example metadata to describe the certificate to use as 237 part of the TLS handshake. 239 2. Design Principles 241 The CDNI Metadata interface was designed to achieve the following 242 objectives: 244 1. Cacheability of CDNI metadata objects. 246 2. Deterministic mapping from redirection requests and content 247 requests to CDNI metadata properties. 249 3. Support for DNS redirection as well as application-specific 250 redirection (for example HTTP redirection). 252 4. Minimal duplication of CDNI metadata. 254 5. Leveraging of existing protocols. 256 Cacheability improves the latency of acquiring metadata while 257 maintaining its freshness, and therefore improves the latency of 258 serving content requests and redirection requests, without 259 sacrificing accuracy. The CDNI Metadata interface uses HTTP and its 260 existing caching mechanisms to achieve CDNI metadata cacheability. 262 Deterministic mappings from content to metadata properties eliminates 263 ambiguity and ensures that policies are applied consistently by all 264 dCDNs. 266 Support for both HTTP and DNS redirection ensures that the CDNI 267 Metadata interface can be used for HTTP and DNS redirection and also 268 meets the same design principles for both HTTP and DNS based 269 redirection schemes. 271 Minimal duplication of CDNI metadata provides space efficiency on 272 storage in the CDNs, on caches in the network, and across the network 273 between CDNs. 275 Leveraging existing protocols avoids reinventing common mechanisms 276 such as data structure encoding (e.g., I-JSON [RFC7492]) and data 277 transport (e.g., HTTP [RFC7230]). 279 3. CDNI Metadata model 281 The CDNI Metadata model describes a data structure for mapping 282 redirection requests and content requests to metadata properties. 283 Metadata properties describe how to acquire content from an uCDN, 284 authorize access to content, and deliver content from a dCDN. The 285 data model relies on the assumption that these metadata properties 286 may be aggregated based on the hostname of the content and 287 subsequently on the resource path of the content. The data model 288 associates a set of CDNI Metadata properties with a Hostname to form 289 a default set of metadata properties for content delivered on behalf 290 of that Hostname. That default set of metadata properties can be 291 overridden by properties that apply to specific paths within a URI. 293 Different Hostnames and URI paths will be associated with different 294 sets of CDNI Metadata properties in order to describe the required 295 behaviour when a dCDN surrogate is processing User Agent requests for 296 content at that Hostname or URI path. As a result of this structure, 297 significant commonality may exist between the CDNI Metadata 298 properties specified for different Hostnames, different URI paths 299 within a Hostname and different URI paths on different Hostnames. 300 For example the definition of which User Agent IP addresses should be 301 treated as being grouped together into a single network or geographic 302 location is likely to be common for a number of different Hostnames. 303 Another example is that although a uCDN is likely to have several 304 different policies configured to express geo-blocking rules, it is 305 likely that a single geo-blocking policy would be applied to multiple 306 Hostnames delivered through the CDN. 308 In order to enable the CDNI Metadata for a given Hostname or URI Path 309 to be decomposed into sets of CDNI Metadata properties that can be 310 reused by multiple Hostnames and URI Paths, the CDNI Metadata 311 interface specified in this document splits the CDNI Metadata into a 312 number of objects. Efficiency is improved by enabling a single CDNI 313 Metadata object (that is shared across Hostname and/or URI paths) to 314 be retrieved and stored by a dCDN once, even if it is referenced by 315 the CDNI Metadata of multiple Hostnames or of multiple URI paths. 317 Important Note: Any CDNI Metadata object that contains another CDNI 318 Metadata object may, instead of including the second object embedded 319 within itself, include a Link object that contains a URI that can be 320 dereferenced to retrieve the complete serialized representation of 321 the second metadata object. The remainder of this document uses the 322 phrase "[Object] X contains [Object] Y" for simplicity when a 323 strictly accurate phrase would be "[Object] X contains or references 324 (via a Link object) [Object] Y". 326 Section 3.1 introduces a high level description of the HostIndex, 327 HostMatch, HostMetadata, PathMatch, PatternMatch and PathMetadata 328 objects and describes the relationships between those objects. 330 Section 3.2 introduces a high level description of the CDNI 331 GenericMetadata object which represents the level at which CDNI 332 Metadata override occurs between HostMetadata and PathMetadata 333 objects. 335 Section 4 describes in detail the specific CDNI Metadata objects and 336 properties which may be contained within a CDNI GenericMetadata 337 object. 339 3.1. HostIndex, HostMatch, HostMetadata, PathMatch, PatternMatch and 340 PathMetadata objects 342 A HostIndex object (see Section 4.1.1) contains a list of HostMatch 343 objects (see Section 4.1.2) that contain Hostnames (and/or IP 344 addresses) for which content requests may be delegated to the dCDN. 345 The HostIndex is the starting point for accessing the uCDN CDNI 346 Metadata data store. It enables the dCDN to deterministically 347 discover, on receipt of a User Agent request for content, which other 348 CDNI Metadata objects it requires in order to deliver the requested 349 content. 351 The HostIndex links Hostnames (and/or IP addresses) to HostMetadata 352 objects (see Section 4.1.3) via HostMatch objects. A HostMatch 353 object defines a hostname (or IP address) to match against a 354 requested host and contains a HostMetadata object. 356 HostMetadata objects contain the default CDNI Metadata within 357 GenericMetadata objects (see Section 4.1.7) required to serve content 358 for that host. When looking up CDNI Metadata, the dCDN looks up the 359 requested Hostname (or IP address) against the HostMatch entries in 360 the HostIndex, from there it can find HostMetadata which describes 361 the default properties for each host as well as PathMetadata objects 362 (see Section 4.1.6), via PathMatch objects (see Section 4.1.4), which 363 may override those properties for given URI paths within the host. 364 The CDNI metadata contained in HostMetadata objects is applied to 365 content requests for which there is not more specific metadata, i.e. 366 for content requests that do not match any of the PathMatch objects 367 contained by that HostMetadata object and its child PathMetadata 368 objects. 370 HostMetadata may also contain PathMatch objects. PathMatch objects 371 define patterns, contained inside PatternMatch objects (see 372 Section 4.1.5), to match against the requested URI path, and contain 373 PathMetadata objects which contain the GenericMetadata objects to be 374 applied when a content request matches against the defined URI path 375 pattern. PatternMatch objects contain the pattern strings and flags 376 that describe the URI path that a PathMatch applies to. 378 PathMetadata objects override the CDNI Metadata in the HostMetadata 379 object or one or more preceding PathMetadata objects with more 380 specific CDNI Metadata that applies to content requests matching the 381 URI pattern defined in the PatternMatch object of that PathMatch 382 object. A PathMetadata object may also contain PathMatch objects in 383 order to recursively define more specific URI paths that require 384 different (e.g., more specific) CDNI Metadata to this one. 386 A GenericMetadata object contains individual CDNI Metadata objects 387 which define the specific policies and attributes needed to properly 388 deliver the associated content. For example, a GenericMetadata 389 object may describe the source from which a CDN may acquire a piece 390 of content. The GenericMetadata object is an atomic unit that may be 391 referenced by HostMetadata and/or PathMetadata objects. 393 For example, if "example.com" is a content provider, a HostMatch 394 object may include an entry for "example.com" with the URI of the 395 associated HostMetadata object. The HostMetadata object for 396 "example.com" describes the metadata properties which apply to 397 "example.com" and could contain PathMatches for "example.com/ 398 movies/*" and "example.com/music/*", which in turn reference 399 corresponding PathMetadata objects that contain the CDNI Metadata 400 objects for those more specific URI paths. The PathMetadata object 401 for "example.com/movies/*" describes CDNI Metadata which apply to 402 that URI path and could contain a PathMatch object for 403 "example.com/movies/hd/*" which would reference the corresponding 404 PathMetadata object for the "example.com/movies/hd/" path prefix. 406 The relationships between the HostIndex, HostMatch, HostMetadata, 407 PathMatch, PatternMatch and PathMetadata objects are described in 408 Figure 1. 410 +---------+ +---------+ +------------+ 411 |HostIndex+-(*)->|HostMatch+-(1)->|HostMetadata+-------(*)------+ 412 +---------+ +---------+ +------+-----+ | 413 | | 414 (*) | 415 | V 416 --> Contains or References V ****************** 417 (1) One and only one +---------+ *Generic Metadata* 418 (*) Zero or more +--->|PathMatch| * Objects * 419 | +----+---++ ****************** 420 | | | ^ 421 (*) (1) (1) +------------+ | 422 | | +->|PatternMatch| | 423 | V +------------+ | 424 | +------------+ | 425 +--+PathMetadata+-------(*)------+ 426 +------------+ 428 Figure 1: Relationships between CDNI Metadata Objects (Diagram 429 Representation) 431 The relationships in Figure 1 are also represented in tabular format 432 in Table 1 below. 434 +--------------+----------------------------------------------------+ 435 | Data Object | Objects it contains or references | 436 +--------------+----------------------------------------------------+ 437 | HostIndex | 0 or more HostMatch objects. | 438 | HostMatch | 1 HostMetadata object. | 439 | HostMetadata | 0 or more PathMatch objects. 0 or more | 440 | | GenericMetadata objects. | 441 | PathMatch | 1 PatternMatch object. 1 PathMetadata object. | 442 | PatternMatch | Does not contain or reference any other objects. | 443 | PathMetadata | 0 or more PathMatch objects. 0 or more | 444 | | GenericMetadata objects. | 445 +--------------+----------------------------------------------------+ 447 Table 1: Relationships between CDNI Metadata Objects 448 (Table Representation) 450 3.2. Generic CDNI Metadata Object Properties 452 The HostMetadata and PathMetadata objects contain or can reference 453 other CDNI Metadata objects that contain properties which describe 454 how User Agent requests for content should be processed, for example 455 where to acquire the content, authorization rules that should be 456 applied, delivery location restrictions and so on. Each such CDNI 457 Metadata object is a specialization of a CDNI GenericMetadata object. 459 The GenericMetadata object abstracts the basic information required 460 for Metadata override and Metadata distribution, from the specifics 461 of any given property (e.g., property semantics, enforcement options, 462 etc.). 464 The GenericMetadata object defines the type of properties contained 465 within it as well as whether or not the properties are "mandatory-to- 466 enforce". If the dCDN does not understand or support the property 467 type and the property type is "mandatory-to-enforce", the dCDN MUST 468 NOT serve the content to the User Agent. If the dCDN does not 469 understand or support the property type and the property type is not 470 "mandatory-to-enforce", then that GenericMetadata object may be 471 safely ignored and the dCDN MUST process the content request in 472 accordance with the rest of the CDNI metadata. 474 Although a CDN MUST NOT serve content to a User Agent if a 475 "mandatory-to-enforce" property cannot be enforced, it may be "safe- 476 to-redistribute" that metadata to another CDN without modification. 477 For example, in the cascaded CDN case, a transit CDN may pass through 478 "mandatory-to-enforce" metadata to a dCDN. For Metadata which does 479 not require customization or translation (i.e., metadata that is 480 "safe-to-redistribute"), the data representation received off the 481 wire MAY be stored and redistributed without being natively 482 understood or supported by the transit CDN. However, for Metadata 483 which requires translation, transparent redistribution of the uCDN 484 Metadata values might not be appropriate. Certain Metadata may be 485 safely, though possibly not optimally, redistributed unmodified. For 486 example, source acquisition address may not be optimal if 487 transparently redistributed, but might still work. 489 Redistribution safety MUST be specified for each GenericMetadata. If 490 a CDN does not understand or support a given GenericMetadata property 491 type and the property type is not "safe-to-redistribute", before 492 redistributing the metadata, the CDN MUST set the "incomprehensible" 493 flag for the GenericMetadata property that it did not understand and 494 was marked as not "safe-to-redistribute". The "incomprehensible" 495 flag signals to a dCDN that the metadata was not properly transformed 496 by the transit CDN. A CDN MUST NOT attempt to use metadata that has 497 been marked as "incomprehensible" by a uCDN. 499 Transit CDNs MUST NOT change the value of "mandatory-to-enforce" or 500 "safe-to-redistribute" when propagating metadata to a dCDN. Although 501 a transit CDN may set the value of "incomprehensible" to true, a 502 transit CDN MUST NOT change the value of "incomprehensible" from true 503 to false. 505 Table 2 describes the action to be taken by a transit CDN (tCDN) for 506 the different combinations of "mandatory-to-enforce" (MtE) and "safe- 507 to-redistribute" (StR) properties, when the tCDN either does or does 508 not understand the metadata in question: 510 +-------+-------+------------+--------------------------------------+ 511 | MtE | StR | Metadata | Action | 512 | | | Understood | | 513 | | | by tCDN | | 514 +-------+-------+------------+--------------------------------------+ 515 | False | True | True | Can serve and redistribute. | 516 | False | True | False | Can serve and redistribute. | 517 | False | False | False | Can serve. MUST set | 518 | | | | "incomprehensible" to True when | 519 | | | | redistributing. | 520 | False | False | True | Can serve. Can redistribute either | 521 | | | | by transforming not StR metadata (if | 522 | | | | the CDN knows how to do so safely), | 523 | | | | otherwise MUST set | 524 | | | | "incomprehensible" to True when | 525 | | | | redistributing. | 526 | True | True | True | Can serve and redistribute. | 527 | True | True | False | MUST NOT serve but can redistribute. | 528 | True | False | True | Can serve and redistribute. | 529 | True | False | False | MUST NOT serve. MUST set | 530 | | | | "incomprehensible" to True when | 531 | | | | redistributing. | 532 +-------+-------+------------+--------------------------------------+ 534 Table 2: Action to be taken by a tCDN for the different combinations 535 of MtE and StR properties 537 Table 3 describes the action to be taken by a dCDN for the different 538 combinations of "mandatory-to-enforce" (MtE) and "incomprehensible" 539 (Incomp) properties, when the dCDN either does or does not understand 540 the metadata in question: 542 +-------+--------------+--------+-----------------------------------+ 543 | MtE | Metadata | Incomp | Action | 544 | | Understood | | | 545 | | by dCDN | | | 546 +-------+--------------+--------+-----------------------------------+ 547 | False | True | False | Can serve. | 548 | False | True | True | Can serve but MUST NOT | 549 | | | | interpret/apply any metadata | 550 | | | | marked incomprehensible. | 551 | False | False | False | Can serve. | 552 | False | False | True | Can serve but MUST NOT | 553 | | | | interpret/apply any metadata | 554 | | | | marked incomprehensible. | 555 | True | True | False | Can serve. | 556 | True | True | True | MUST NOT serve. | 557 | True | False | False | MUST NOT serve. | 558 | True | False | True | MUST NOT serve. | 559 +-------+--------------+--------+-----------------------------------+ 561 Table 3: Action to be taken by a dCDN for the different combinations 562 of MtE and Incomp properties 564 3.3. Metadata Inheritance and Override 566 In the Metadata model, a HostMetadata object may contain (or 567 reference) multiple PathMetadata objects (via PathMatch objects). 568 Each PathMetadata object may in turn contain (or reference) other 569 PathMetadata objects. HostMetadata and PathMetadata objects form an 570 inheritance tree where each node in the tree inherits or overrides 571 the property values set by its parent. 573 GenericMetadata objects of a given type override all GenericMetadata 574 objects of the same type previously defined by any parent object in 575 the tree. GenericMetadata objects of a given type previously defined 576 by a parent object in the tree are inherited when no object of the 577 same type is defined by the child object. For example, if 578 HostMetadata for the host "example.com" contains GenericMetadata 579 objects of type LocationACL and TimeWindowACL, while a PathMetadata 580 object which applies to "example.com/movies/*" defines an alternate 581 GenericMetadata object of type TimeWindowACL, then: 583 o the TimeWindowACL defined in the PathMetadata would override the 584 TimeWindowACL defined in the HostMetadata for all User Agent 585 requests for content under "example.com/movies/", and 587 o the LocationACL defined in the HostMetadata would be inherited for 588 all User Agent requests for content under "example.com/movies/". 590 o A single HostMetadata or PathMetadata object SHOULD NOT contain 591 multiple GenericMetadata objects of the same type. If a list of 592 GenericMetadata contains objects of duplicate types, the receiver 593 MUST ignore all but the first object of each type. 595 4. CDNI Metadata objects 597 Section 4.1 provides the definitions of each metadata object type 598 introduced in Section 3. These metadata objects are described as 599 structural metadata objects as they provide the structure for the 600 inheritance tree and identify which specific properties apply to a 601 given User Agent content request. 603 Section 4.2 provides the definitions for a base set of core metadata 604 objects which may be contained within a GenericMetadata object. 605 These metadata objects are described as property objects, as they 606 define the structure, semantics, and enforcement options for specific 607 properties of the metadata being described. Property objects govern 608 how User Agent requests for content are handled. Property objects 609 may be composed of, or contain references to, other property sub- 610 objects (i.e., property objects contained within or referenced by the 611 property object that refers to that property sub-object). As with 612 all CDNI Metadata object, the value of the property sub-objects can 613 be either a complete serialized representation of the sub-object, or 614 a Link object that contains a URI that can be dereferenced to 615 retrieve the complete serialized representation of the property sub- 616 object. 618 Section 6.5 discusses the ability to extend the base set of metadata 619 objects specified in this document with additional standards based or 620 vendor specific property objects that may be defined in the future in 621 separate documents. 623 dCDNs and tCDNs MUST support parsing of all CDNI metadata objects 624 specified in this document. A dCDN does not have to implement the 625 underlying functionality represented by the metadata object, though 626 that may restrict the content that a given dCDN can serve. uCDNs as 627 generators of CDNI Metadata only need to support generating the CDNI 628 metadata that they need in order to express the policies and 629 treatment required by the content they are describing. 631 Note: In the following sections, the term "mandatory-to-specify" is 632 used to convey which properties MUST be included for a given 633 structural or property object. When mandatory-to-specify is 634 specified as "Yes" by this document for an individual property, it 635 means that if the object containing that property is included in a 636 metadata response, then the mandatory-to-specify property MUST also 637 be included (directly or by reference) in the response, e.g., a 638 HostMatch property object without a host to match against does not 639 make sense, therefore, the host property is mandatory-to-specify 640 inside a HostMatch object. 642 4.1. Definitions of the CDNI structural metadata objects 644 Each of the sub-sections below describe the structural objects 645 introduced in Section 3.1. 647 4.1.1. HostIndex 649 The HostIndex object is the entry point into the CDNI Metadata 650 hierarchy. It contains a list of HostMatch objects. An incoming 651 content request is checked against the hostname (or IP address) 652 specified by each of the listed HostMatch objects to find the 653 HostMatch object which applies to the request. 655 Property: hosts 657 Description: List of HostMatch objects. Hosts (HostMatch 658 objects) MUST be evaluated in the order they appear and the 659 first HostMatch object that matches the content request being 660 processed MUST be used. 662 Type: List of HostMatch objects 664 Mandatory-to-Specify: Yes. 666 Example HostIndex object containing two HostMatch objects, where the 667 first HostMatch object is embedded and the second HostMatch object is 668 referenced: 670 { 671 "hosts": [ 672 { 673 674 }, 675 { 676 "type": "application/cdni.HostMatch.v1+json", 677 "href": "http://metadata.ucdn.example/hostmatch1234" 678 } 679 ] 680 } 682 4.1.2. HostMatch 684 The HostMatch object contains a hostname or IP address to match 685 against content requests. The HostMatch object also contains or 686 references a HostMetadata object to apply if a match is found. 688 Property: host 690 Description: String (hostname or IP address) to match against 691 the requested host. In order for a hostname or IP address in a 692 content request to match the hostname or IP address in the host 693 property the value when converted to lowercase in the content 694 request MUST be identical to the value of the host property 695 when converted to lowercase. 697 Type: String 699 Mandatory-to-Specify: Yes. 701 Property: host-metadata 703 Description: CDNI Metadata to apply when delivering content 704 that matches this host. 706 Type: HostMetadata 708 Mandatory-to-Specify: Yes. 710 Example HostMatch object with an embedded HostMetadata object: 712 { 713 "host": "video.example.com", 714 "host-metadata" : { 715 716 } 717 } 719 Example HostMatch object referencing a HostMetadata object: 721 { 722 "host": "video.example.com", 723 "host-metadata" : { 724 "type": "application/cdni.HostMetadata.v1+json", 725 "href": "http://metadata.ucdn.example/host1234" 726 } 727 } 729 4.1.3. HostMetadata 731 A HostMetadata object contains (or references) the CDNI Metadata 732 properties for content served for a particular host (defined in the 733 HostMatch object) and possibly child PathMatch objects. 735 Property: metadata 737 Description: List of host related metadata. 739 Type: List of GenericMetadata objects 741 Mandatory-to-Specify: Yes. 743 Property: paths 745 Description: Path specific rules. Path patterns (PathMatch 746 objects) MUST be evaluated in the order they appear and the 747 first PathMatch object that matches the content request being 748 processed MUST be used. 750 Type: List of PathMatch objects 752 Mandatory-to-Specify: No. 754 Example HostMetadata object containing a number of embedded 755 GenericMetadata objects that will describe the default metadata for 756 the host and a single embedded PathMatch object that will describe 757 the CDNI metadata for that path which overrides the default metadata 758 for the host: 760 { 761 "metadata": [ 762 { 763 764 }, 765 { 766 767 }, 769 ... 771 { 772 773 } 774 ], 775 "paths": [ 776 { 777 778 } 779 ] 780 } 782 4.1.4. PathMatch 784 The PathMatch object contains (or references) an expression given as 785 a PatternMatch object to match against a resource URI path and 786 contains or references a PathMetadata object to apply if a match is 787 found. 789 Property: path-pattern 791 Description: Pattern to match against the requested path, i.e., 792 against the [RFC3986] path-absolute. 794 Type: PatternMatch 796 Mandatory-to-Specify: Yes. 798 Property: path-metadata 800 Description: CDNI Metadata to apply when delivering content 801 that matches this path. 803 Type: PathMetadata 805 Mandatory-to-Specify: Yes. 807 Example PathMatch object referencing the PathMetadata object to use 808 for URIs that match the case-sensitive URI path pattern "/movies/*" 809 (contained within an embedded PatternMatch object): 811 { 812 "path-pattern": { 813 "pattern": "/movies/*", 814 "case-sensitive": true 815 }, 816 "path-metadata": { 817 "type": "application/cdni.PathMetadata.v1+json", 818 "href": "http://metadata.ucdn.example/host1234/pathDCE" 819 } 820 } 822 4.1.5. PatternMatch 824 A PatternMatch object contains the pattern string and flags that 825 describe the PathMatch expression. 827 Property: pattern 829 Description: A pattern for string matching. The pattern may 830 contain the wildcards * and ?, where * matches any sequence of 831 characters (including the empty string) and ? matches exactly 832 one character. The three literals \ , * and ? should be 833 escaped as \\, \* and \?. All other characters are treated as 834 literals. 836 Type: String 838 Mandatory-to-Specify: Yes. 840 Property: case-sensitive 842 Description: Flag indicating whether or not case-sensitive 843 matching should be used. 845 Type: Boolean 847 Mandatory-to-Specify: No. Default is case-insensitive match. 849 Property: ignore-query-string 851 Description: List of query parameters which should be ignored 852 when searching for a pattern match. Matching against query 853 parameters to ignore MUST be case-insensitive. If all query 854 parameters should be ignored then the list MUST be empty. 856 Type: List of String 858 Mandatory-to-Specify: No. Default is to include query strings 859 when matching. 861 Example PatternMatch object that matches the case-sensitive URI path 862 pattern "/movies/*". The query parameter "sessionid" will be ignored 863 when matching URIs requested from surrogates by content clients 864 against this path pattern: 866 { 867 "pattern": "/movies/*", 868 "case-sensitive": true, 869 "ignore-query-string": ["sessionid"] 870 } 872 4.1.6. PathMetadata 874 A PathMetadata object contains (or references) the CDNI Metadata 875 properties for content served with the associated URI path (defined 876 in a PathMatch object) and possibly child PathMatch objects. 878 Note that if DNS-based redirection is employed, then a dCDN will be 879 unable to evaulate any metadata at the PathMetadata level or below 880 against the content redirection request at request routing time 881 because only the content request hostname is available at request 882 routing time. dCDNs SHOULD still process any metadata at the 883 PathMetadata level or below before responding to the redirection 884 request in order to detect if any unsupported metadata is specifed. 885 If any metadata is included that is not supported by the dCDN then 886 the dCDN SHOULD NOT redirect the the content redirection request to 887 itself in order to avoid receiving content requests that it is not 888 able to satisfy/serve. 890 Property: metadata 892 Description: List of path related metadata. 894 Type: List of GenericMetadata objects 896 Mandatory-to-Specify: Yes. 898 Property: paths 900 Description: Path specific rules. First match applies. 902 Type: List of PathMatch objects 903 Mandatory-to-Specify: No. 905 Example PathMetadata object containing a number of embedded 906 GenericMetadata objects that will describe the metadata to apply for 907 the path defined in the parent PathMatch object. that will describe 908 the CDNI metadata for that path which overrides the default metadata 909 for the host: 911 { 912 "metadata": [ 913 { 914 915 }, 916 { 917 918 }, 920 ... 922 { 923 924 } 925 ], 926 } 928 4.1.7. GenericMetadata 930 A GenericMetadata object is an abstraction for managing individual 931 CDNI Metadata properties in an opaque manner. 933 Property: generic-metadata-type 935 Description: Case-insensitive CDNI Metadata property object 936 type. 938 Type: String containing a MIME Media Type 940 Mandatory-to-Specify: Yes. 942 Property: generic-metadata-value 944 Description: CDNI Metadata property object. 946 Type: Format/Type is defined by the value of generic-metadata- 947 type property above. 949 Mandatory-to-Specify: Yes. 951 Property: mandatory-to-enforce 953 Description: Flag identifying whether or not the enforcement of 954 the property Metadata is required. 956 Type: Boolean 958 Mandatory-to-Specify: No. Default is to treat metadata as 959 mandatory to enforce (i.e., a value of True). 961 Property: safe-to-redistribute 963 Description: Flag identifying whether or not the property 964 Metadata may be safely redistributed without modification. 966 Type: Boolean 968 Mandatory-to-Specify: No. Default is allow transparent 969 redistribution (i.e., a value of True). 971 Property: incomprehensible 973 Description: Flag identifying whether or not any CDN in the 974 chain of delegation has failed to understand and/or failed to 975 properly transform this metadata object. Note: This flag only 976 applies to metadata objects whose safe-to-redistribute property 977 has a value of False. 979 Type: Boolean 981 Mandatory-to-Specify: No. Default is comprehensible (i.e., a 982 value of False). 984 Example GenericMetadata object containing a metadata object that 985 applies to the applicable URI path and/or host (within a parent 986 PathMetadata and/or HostMetadata object): 988 { 989 "mandatory-to-enforce": true, 990 "generic-metadata-type": , 991 "generic-metadata-value": 992 { 993 994 } 995 } 997 4.2. Definitions of the initial set of CDNI Generic Metadata objects 999 The property objects defined below are intended to be used in the 1000 GenericMetadata object generic-metadata-value field as defined in 1001 Section 4.1.7 and their generic-metadata-type property MUST be set to 1002 the appropriate Media Type as defined in Table 4. 1004 4.2.1. SourceMetadata 1006 Source Metadata provides the dCDN information about content 1007 acquisition, i.e., how to contact an uCDN Surrogate or an Origin 1008 Server to obtain the content to be served. The sources are not 1009 necessarily the actual Origin Servers operated by the CSP but might 1010 be a set of Surrogates in the uCDN. 1012 Endpoints within a source should be treated as equivalent/equal so 1013 one can specify a list of sources in preference order and for each 1014 source/preference rank one can specify a list of endpoints that are 1015 equivalent, e.g., a pool of servers that are not behind a load 1016 balancer. 1018 Property: sources 1020 Description: Sources from which the dCDN can acquire content, 1021 listed in order of preference. 1023 Type: List of Source objects 1025 Mandatory-to-Specify: No. Default is to use static 1026 configuration, out-of-band from the metadata interface. 1028 Example SourceMetadata object (which contains two Source objects) 1029 that describes which servers the dCDN should use for acquiring 1030 content for the applicable URI path and/or host: 1032 { 1033 "mandatory-to-enforce": true, 1034 "generic-metadata-type": "application/cdni.SourceMetadata.v1+json" 1035 "generic-metadata-value": 1036 { 1037 "sources": [ 1038 { 1039 "generic-metadata-type": 1040 "application/cdni.Source.v1+json" 1041 "generic-metadata-value": 1042 { 1043 "endpoints": [ 1044 "a.service123.ucdn.example", 1045 "b.service123.ucdn.example" 1046 ], 1047 "protocol": "HTTP1.1" 1048 } 1049 }, 1050 { 1051 "generic-metadata-type": 1052 "application/cdni.Source.v1+json" 1053 "generic-metadata-value": 1054 { 1055 "endpoints": ["origin.service123.example"], 1056 "protocol": "HTTP1.1" 1057 } 1058 } 1059 ] 1060 } 1061 } 1063 4.2.1.1. Source 1065 A Source object describes the Source which should be used by the dCDN 1066 for content acquisition, e.g., a Surrogate within the uCDN or an 1067 alternate Origin Server, the protocol to be used and any 1068 authentication method. 1070 Property: acquisition-auth 1072 Description: Authentication method to use when requesting 1073 content from this source. 1075 Type: Auth 1077 Mandatory-to-Specify: No. Default is no authentication 1078 required. 1080 Property: endpoints 1082 Description: Origins from which the dCDN can acquire content. 1083 If multiple endpoints are specified they are all equal, i.e., 1084 the list is not in preference order, for example a pool of 1085 servers behind a load balancer. 1087 Type: List of EndPoint objects 1089 Mandatory-to-Specify: Yes. 1091 Property: protocol 1093 Description: Network retrieval protocol to use when requesting 1094 content from this source. 1096 Type: Protocol 1098 Mandatory-to-Specify: Yes. 1100 Example Source object that describes a server the dCDN should use for 1101 acquiring content for the applicable URI path and/or host: 1103 { 1104 "generic-metadata-type": "application/cdni.Source.v1+json" 1105 "generic-metadata-value": 1106 { 1107 "endpoints": [ 1108 "a.service123.ucdn.example", 1109 "b.service123.ucdn.example" 1110 ], 1111 "protocol": "HTTP1.1" 1112 } 1113 } 1115 4.2.2. LocationACL Metadata 1117 LocationACL Metadata defines location-based restrictions. 1119 A LocationACL which does not include a locations property results in 1120 an action of allow, meaning that delivery can be performed regardless 1121 of the User Agent's location. The action from the first footprint to 1122 match against the User Agent's location is the action a CDN MUST 1123 take. If two or more footprints overlap, the first footprint that 1124 matches against the User Agent's location determines the action a CDN 1125 MUST take. If the locations property is included but is empty, or if 1126 none of the listed footprints matches the User Agent's location, then 1127 the result is an action of deny. 1129 Although the LocationACL, TimeWindowACL, and ProtocolACL are 1130 independent GenericMetadata objects, they may provide conflicting 1131 information to a dCDN, e.g., a content request which is 1132 simultaneously allowed based on the LocationACL and denied based on 1133 the TimeWindowACL. The dCDN MUST use the logical AND of all ACLs 1134 (where 'allow' is true and 'deny' is false) to determine whether or 1135 not a request should be allowed. Thus, in the example given, the 1136 request should be denied. 1138 Property: locations 1140 Description: Access control list which allows or denies 1141 (blocks) delivery based on client location. 1143 Type: List of LocationRule objects 1145 Mandatory-to-Specify: No. Default is allow all locations. 1147 Example LocationACL object that allows the dCDN to deliver content to 1148 any location/IP address: 1150 { 1151 "mandatory-to-enforce": true, 1152 "generic-metadata-type": "application/cdni.LocationACL.v1+json" 1153 "generic-metadata-value": 1154 { 1155 } 1156 } 1158 Example LocationACL object (which contains a LocationRule object 1159 which itself contains a Footprint object) that only allows the dCDN 1160 to deliver content to clients in the USA: 1162 { 1163 "mandatory-to-enforce": true, 1164 "generic-metadata-type": "application/cdni.LocationACL.v1+json" 1165 "generic-metadata-value": 1166 { 1167 "locationss": [ 1168 { 1169 "generic-metadata-type": 1170 "application/cdni.LocationRule.v1+json" 1171 "generic-metadata-value": 1172 { 1173 "action": "allow", 1174 "footprints": [ 1175 { 1176 "generic-metadata-type": 1177 "application/cdni.Footprint.v1+json" 1178 "generic-metadata-value": 1179 { 1180 "footprint-type": "countrycode", 1181 "footprint-value": "us" 1182 } 1183 } 1184 ] 1185 } 1186 } 1187 ] 1188 } 1189 } 1191 4.2.2.1. LocationRule 1193 A LocationRule contains or references a list of Footprint objects and 1194 the corresponding action. 1196 Property: footprints 1198 Description: List of footprints to which the rule applies. 1200 Type: List of Footprint objects 1202 Mandatory-to-Specify: Yes. 1204 Property: action 1206 Description: Defines whether the rule specifies locations to 1207 allow or deny. 1209 Type: Enumeration [allow|deny] encoded as a lowercase string 1210 Mandatory-to-Specify: No. Default is deny. 1212 4.2.2.2. Footprint 1214 A Footprint object describes the footprint to which a LocationRule 1215 may be applied to, e.g., an IPv4 address range or a geographic 1216 location. 1218 Property: footprint-type 1220 Description: Registered footprint type. The footprint types 1221 specified by this document are: "ipv4cidr" (IPv4CIDR, see 1222 Section 4.3.7), "ipv6cidr" (IPv6CIDR, see Section 4.3.8), "asn" 1223 (Autonomous System Number, see Section 4.3.9) and "countrycode" 1224 (Country Code, see Section 4.3.10). 1226 Type: Lowercase String 1228 Mandatory-to-Specify: Yes. 1230 Property: footprint-value 1232 Description: Footprint object conforming to the specification 1233 associated with the registered footprint type. 1235 Type: String 1237 Mandatory-to-Specify: Yes. 1239 4.2.3. TimeWindowACL Metadata 1241 TimeWindowACL Metadata defines time-based restrictions. 1243 A TimeWindowACL which does not include a times property results in an 1244 action of allow, meaning that delivery can be performed regardless of 1245 the time of the User Agent's request. The action from the first 1246 window to match against the current time is the action a CDN MUST 1247 take. If two or more windows overlap, the first window that matches 1248 against the current time determines the action a CDN MUST take. If 1249 the times property is included but is empty, or if none of the listed 1250 windows matches the current time, then the result is an action of 1251 deny. 1253 Although the LocationACL, TimeWindowACL, and ProtocolACL are 1254 independent GenericMetadata objects, they may provide conflicting 1255 information to a dCDN, e.g., a content request which is 1256 simultaneously allowed based on the LocationACL and denied based on 1257 the TimeWindowACL. The dCDN MUST use the logical AND of all ACLs 1258 (where 'allow' is true and 'deny' is false) to determine whether or 1259 not a request should be allowed. Thus, in the example given, the 1260 request should be denied. 1262 Property: times 1264 Description: Description: Access control list which allows or 1265 denies (blocks) delivery based on request time. 1267 Type: List of TimeWindowRule objects 1269 Mandatory-to-Specify: No. Default is allow all time windows. 1271 4.2.3.1. TimeWindowRule 1273 A TimeWindowRule contains or references a list of TimeWindow objects 1274 and the corresponding action. 1276 Property: windows 1278 Description: List of time windows to which the rule applies. 1280 Type: List of TimeWindow objects 1282 Mandatory-to-Specify: Yes. 1284 Property: action 1286 Description: Defines whether the rule specifies time windows to 1287 allow or deny. 1289 Type: Enumeration [allow|deny] encoded as a lowercase string 1291 Mandatory-to-Specify: No. Default is deny. 1293 4.2.3.2. TimeWindow 1295 A TimeWindow object describes a time range which may be applied by an 1296 TimeWindowACL, e.g., start 946717200 (i.e., 09:00AM 01/01/2000 UTC), 1297 end: 946746000 (i.e., 17:00AM 01/01/2000 UTC). 1299 Property: start 1301 Description: The start time of the window. 1303 Type: Time 1305 Mandatory-to-Specify: Yes. 1307 Property: end 1309 Description: The end time of the window. 1311 Type: Time 1313 Mandatory-to-Specify: Yes. 1315 4.2.4. ProtocolACL Metadata 1317 ProtocolACL Metadata defines delivery protocol restrictions. 1319 A ProtocolACL which does not include a protocol-acl property results 1320 in an action of allow, meaning that delivery can be performed 1321 regardless of the protocol of the User Agent's request. The action 1322 from the first protocol to match against the request protocol is the 1323 action a CDN MUST take. If two or more request protocols overlap, 1324 the first protocol that matches thre request protocol determines the 1325 action a CDN MUST take. If the protocol-acl property is included but 1326 is empty, or if none of the listed protocol matches the request 1327 protocol, then the result is an action of deny. 1329 Although the LocationACL, TimeWindowACL, and ProtocolACL are 1330 independent GenericMetadata objects, they may provide conflicting 1331 information to a dCDN, e.g., a content request which is 1332 simultaneously allowed based on the ProtocolACL and denied based on 1333 the TimeWindowACL. The dCDN MUST use the logical AND of all ACLs 1334 (where 'allow' is true and 'deny' is false) to determine whether or 1335 not a request should be allowed. Thus, in the example given, the 1336 request should be denied. 1338 Property: protocol-acl 1340 Description: Description: Access control list which allows or 1341 denies (blocks) delivery based on delivery protocol. 1343 Type: List of ProtocolRule objects 1345 Mandatory-to-Specify: No. Default is allow all protocols. 1347 4.2.4.1. ProtocolRule 1349 A ProtocolRule contains or references a list of Protocol objects. 1350 ProtocolRule objects are used to construct a ProtocolACL to apply 1351 restrictions to content acquisition or delivery. 1353 Property: protocols 1354 Description: List of protocols to which the rule applies. 1356 Type: List of Protocol objects 1358 Mandatory-to-Specify: Yes. 1360 Property: action 1362 Description: Defines whether the rule specifies protocols to 1363 allow or deny. 1365 Type: Enumeration [allow|deny] encoded as a lowercase string 1367 Mandatory-to-Specify: No. Default is deny. 1369 4.2.5. DeliveryAuthorization Metadata 1371 Delivery Authorization defines authorization methods for the delivery 1372 of content to User Agents. 1374 Property: delivery-auth-methods 1376 Description: Options for authorizing content requests. 1377 Delivery for a content request is authorized if any of the 1378 authorization method in the list is satisfied for that request. 1380 Type: List of Auth objects 1382 Mandatory-to-Specify: No. Default is no authorization 1383 required. 1385 4.2.6. Cache 1387 A Cache object describes the cache control parameters to be applied 1388 to the content by intermediate caches. 1390 Property: ignore-query-string 1392 Description: Allows a cache to ignore URI query string 1393 parameters while comparing URIs for equivalence. Matching 1394 against query parameters to ignore MUST be case-insensitive. 1395 Each query parameter to ignore is specified in the list. If 1396 all query parameters should be ignored, then the list MUST be 1397 specified and MUST be empty. 1399 Type: List of String 1400 Mandatory-to-Specify: No. Default is to consider query string 1401 parameters when comparing URIs. 1403 4.2.7. Grouping 1405 A Grouping object identifies a large group of content to which a 1406 given asset belongs. 1408 Property: ccid 1410 Description: Content Collection identifier for an application- 1411 specific purpose such as logging. 1413 Type: String 1415 Mandatory-to-Specify: No. Default is an empty string. 1417 Property: sid 1419 Description: Session identifier for an application-specific 1420 purpose such as logging. 1422 Type: String 1424 Mandatory-to-Specify: No. Default is an empty string. 1426 4.3. CDNI Metadata Simple Data Type Descriptions 1428 This section describes the simple data types that are used for 1429 properties of CDNI Metadata objects. 1431 4.3.1. Link 1433 A link object may be used in place of any of the objects or 1434 properties described above. Links can be used to avoid duplication 1435 if the same metadata information is repeated within the metadata 1436 tree. When a link replaces an object, its href property is set to 1437 the URI of the resource and its type property is set to the type of 1438 the object it is replacing. 1440 Property: href 1442 Description: The URI of the addressable object being 1443 referenced. 1445 Type: URI 1447 Mandatory-to-Specify: Yes 1449 Property: type 1451 Description: The type of the object being referenced. 1453 Type: String 1455 Mandatory-to-Specify: No 1457 4.3.2. Protocol 1459 Protocol objects are used to specify registered protocols for content 1460 acquisition or delivery (see Section 7.2). 1462 Type: String 1464 4.3.3. Endpoint 1466 A hostname (with optional port) or an IP address (with optional 1467 port). 1469 Note: All implementations MUST support IPv4 addresses encoded as 1470 specified by the 'IPv4address' rule in Section 3.2.2 of [RFC3986] and 1471 MUST support all IPv6 address formats specified in [RFC4291]. Server 1472 implementations SHOULD use IPv6 address formats specified in 1473 [RFC5952]. 1475 Type: String 1477 4.3.4. URI 1479 A URI as specified in [RFC3986]. 1481 Type: String 1483 4.3.5. Time 1485 A time value expressed in seconds since Unix epoch in the UTC 1486 timezone. 1488 Type: Integer 1490 4.3.6. Auth 1492 An Auth object defines authentication and authorization methods to be 1493 used during content acquisition and content delivery, respectively. 1495 Property: auth-type 1496 Description: Registered Auth type (see Section 4.3.6.1 and 1497 Section 7.3). 1499 Type: String 1501 Mandatory-to-Specify: Yes. 1503 Property: auth-value 1505 Description: An object conforming to the specification 1506 associated with the Registered Auth type. 1508 Type: String 1510 Mandatory-to-Specify: Yes. 1512 4.3.6.1. CredentialAuth Type 1514 CredentialAuth is a Registered Auth type defining an object for 1515 encapsulating user credentials (i.e., username and password) (see 1516 Section 7.3). The CredentialAuth object contains the following 1517 properties: 1519 Property: username 1521 Description: Identification of user. 1523 Type: String 1525 Mandatory-to-Specify: Yes. 1527 Property: password 1529 Description: Password for user identified by username property. 1531 Type: String 1533 Mandatory-to-Specify: Yes. 1535 4.3.7. IPv4CIDR 1537 An IPv4address CIDR block encoded as specified by the 'IPv4address' 1538 rule in Section 3.2.2 of [RFC3986] followed by a / followed by an 1539 unsigned integer representing the leading bits of the routing prefix 1540 (i.e. IPv4 CIDR notation). Single IP addresses can be expressed as 1541 /32. 1543 Type: String 1545 4.3.8. IPv6CIDR 1547 An IPv6address CIDR block encoded in one of the IPv6 address formats 1548 specified in [RFC5952] followed by a / followed by an unsigned 1549 integer representing the leading bits of the routing prefix (i.e. 1550 IPv6 CIDR notation). Single IP addresses can be expressed as /128. 1552 Type: String 1554 4.3.9. ASN 1556 An Autonomous System Number encoded as a string consisting of the 1557 characters AS (in uppercase) followed by the Autonomous System 1558 number. For example "AS64496". 1560 Type: String 1562 4.3.10. CountryCode 1564 An ISO 3166-1 alpha-2 code [ISO3166-1] in lowercase. 1566 Type: String 1568 5. CDNI Metadata Capabilities 1570 CDNI Metadata is used to convey information pertaining to content 1571 delivery from uCDN to dCDN. For optional metadata, it may be useful 1572 for the uCDN to know if the dCDN supports the metadata, prior to 1573 delegating any content requests to the dCDN. If optional-to- 1574 implement metadata is "mandatory-to-enforce", and the dCDN does not 1575 support it, any delegated requests for that content will fail. The 1576 uCDN will likely want to avoid delegating those requests to that 1577 dCDN. Likewise, for any metadata which may be assigned optional 1578 values, it may be useful for the uCDN to know which values a dCDN 1579 supports, prior to delegating any content requests to that dCDN. If 1580 the optional value assigned to a given piece of content's metadata is 1581 not supported by the dCDN, any delegated requests for that content 1582 may fail, so again the uCDN is likely to want to avoid delegating 1583 those requests to that dCDN. 1585 The CDNI Footprint and Capabilities Interface (FCI) [RFC7336] 1586 provides a means of advertising capabilities from dCDN to uCDN. 1587 Support for optional metadata and support for optional metadata 1588 values may be advertised using the FCI. 1590 6. CDNI Metadata interface 1592 This section specifies an interface to enable a dCDN to retrieve CDNI 1593 Metadata objects from a uCDN. 1595 The interface can be used by a dCDN to retrieve CDNI Metadata objects 1596 either: 1598 o Dynamically as required by the dCDN to process received requests. 1599 For example in response to a query from an uCDN over the CDNI 1600 Request Routing Redirection interface (RI) 1601 [I-D.ietf-cdni-redirection] or in response to receiving a request 1602 for content from a User Agent. Or; 1604 o In advance of being required. For example in the case of pre- 1605 positioned CDNI Metadata acquisition. 1607 The CDNI Metadata interface is built on the principles of RESTful web 1608 services. In particular, this means that requests and responses over 1609 the interface are built around the transfer of representations of 1610 hyperlinked resources. A resource in the context of the CDNI 1611 Metadata interface is any object in the Data Model (as described in 1612 Section 3 and Section 4). 1614 To retrieve CDNI metadata, a CDNI Metadata client (i.e., a client in 1615 the dCDN) first makes a HTTP GET request for the URI of the HostIndex 1616 which provides the CDNI Metadata client with a list of Hostnames for 1617 which the uCDN may delegate content delivery to the dCDN. The CDNI 1618 Metadata client can then obtain any other CDNI Metadata objects by 1619 making a HTTP GET requests for any linked Metadata objects it 1620 requires. 1622 CDNI Metadata servers (i.e., servers in the uCDN) are free to assign 1623 whatever structure they desire to the URIs for CDNI Metadata objects 1624 and CDNI Metadata clients MUST NOT make any assumptions regarding the 1625 structure of CDNI Metadata URIs or the mapping between CDNI Metadata 1626 objects and their associated URIs. Therefore any URIs present in the 1627 examples below are purely illustrative and are not intended to impose 1628 a definitive structure on CDNI Metadata interface implementations. 1630 6.1. Transport 1632 The CDNI Metadata interface uses HTTP as the underlying protocol 1633 transport. 1635 The HTTP Method in the request defines the operation the request 1636 would like to perform. A server implementation of the CDNI Metadata 1637 interface MUST support the HTTP GET and HEAD methods. 1639 The corresponding HTTP Response returns the status of the operation 1640 in the HTTP Status Code and returns the current representation of the 1641 resource (if appropriate) in the Response Body. HTTP Responses from 1642 servers implementing the CDNI Metadata interface that contain a 1643 response body SHOULD include an ETag to enable validation of cached 1644 versions of returned resources. 1646 The CDNI Metadata interface specified in this document is a read-only 1647 interface. Therefore support for other HTTP methods such as PUT, 1648 POST and DELETE etc. is not specified. A server implementation of 1649 the CDNI Metadata interface SHOULD reject all methods other than GET 1650 and HEAD. 1652 As the CDNI Metadata interface builds on top of HTTP, CDNI Metadata 1653 server implementations MAY make use of any HTTP feature when 1654 implementing the CDNI Metadata interface, for example a CDNI Metadata 1655 server MAY make use of HTTP's caching mechanisms to indicate that the 1656 returned response/representation can be reused without re-contacting 1657 the CDNI Metadata server. 1659 6.2. Retrieval of CDNI Metadata resources 1661 In the general case a CDNI Metadata server makes each instance of an 1662 addressable CDNI Metadata object available via a unique URI and 1663 therefore in order to retrieve CDNI Metadata, a CDNI Metadata client 1664 first makes a HTTP GET request for the URI of the HostIndex which 1665 provides the CDNI Metadata client with a list of Hostnames for which 1666 the uCDN may delegate content delivery to the dCDN. 1668 In order to retrieve the CDNI Metadata for a particular request the 1669 CDNI Metadata client processes the received HostIndex object and 1670 finds the corresponding HostMetadata entry (by matching the hostname 1671 in the request against the hostnames listed in the HostMatch 1672 objects). If the HostMetadata is linked (rather than embedded), the 1673 CDNI metadata client then makes a GET request for the URI specified 1674 in the href property of the Link object which points to the 1675 HostMetadata object itself. 1677 In order to retrieve the most specific metadata for a particular 1678 request, the CDNI metadata client inspects the HostMetadata for 1679 references to more specific PathMetadata objects (by matching the URI 1680 path in the request against the path-patterns in the PathMatch). If 1681 any PathMetadata match the request (and are linked rather than 1682 embedded), the CDNI metadata client makes another GET request for the 1683 PathMetadata. Each PathMetadata object may also include references 1684 to yet more specific metadata. If this is the case, the CDNI 1685 metadata client continues requesting PathMatch and PathMetadata 1686 objects recursively. 1688 In cases where a dCDN is not able to retrieve the entire set of CDNI 1689 metadata associated with a User Agent request, for example because 1690 the uCDN is uncontactable or returns an HTTP 4xx or 5xx status in 1691 response to some or all of the dCDN's CDNI metadata requests, the 1692 dCDN MUST NOT serve the requested content unless the dCDN has stale 1693 versions of all the required metadata and the stale-if-error Cache- 1694 Control extension [RFC5861] was included in all previous responses 1695 that are required but cannot currently be retrieved. The dCDN can 1696 continue to serve other content for which it can retrieve (or for 1697 which it has fresh responses cached) all the required metadata even 1698 if some non-applicable part of the metadata tree is missing. 1700 Where a dCDN is interconnected with multiple uCDNs, the dCDN needs to 1701 determine which uCDN's CDNI metadata should be used to handle a 1702 particular User Agent request. 1704 When application level redirection (e.g., HTTP 302 redirects) is 1705 being used between CDNs, it is expected that the dCDN will be able to 1706 determine the uCDN that redirected a particular request from 1707 information contained in the received request (e.g., via the URI). 1708 With knowledge of which uCDN routed the request, the dCDN can choose 1709 the correct metadata server from which to obtain the HostIndex. Note 1710 that the HostIndex served by each uCDN may be unique. 1712 In the case of DNS redirection there is not always sufficient 1713 information carried in the DNS request from User Agents to determine 1714 the uCDN that redirected a particular request (e.g., when content 1715 from a given host is redirected to a given dCDN by more than one 1716 uCDN) and therefore dCDNs may have to apply local policy when 1717 deciding which uCDN's metadata to apply. 1719 6.3. Bootstrapping 1721 The URI for the HostIndex object of a given uCDN needs to be either 1722 configured in, or discovered by, the dCDN. All other objects/ 1723 resources are then discoverable from the HostIndex object by 1724 following the links in the HostIndex object and the referenced 1725 HostMetadata and PathMetadata objects. 1727 If the URI for the HostIndex object is not manually configured in the 1728 dCDN then the HostIndex URI could be discovered. A mechanism 1729 allowing the dCDN to discover the URI of the HostIndex is outside the 1730 scope of this document. 1732 6.4. Encoding 1734 Objects are resources that may be: 1736 o Addressable, where the object is a resource that may be retrieved 1737 or referenced via its own URI. 1739 o Embedded, where the object is contained within a property of an 1740 addressable object. 1742 The descriptions of objects use the phrase "X contains Y" to mean 1743 that Y is either directly embedded in X or is linked to by X. It is 1744 generally a deployment choice for the uCDN implementation to decide 1745 when and which CDNI Metadata objects to embed and which are made 1746 separately addressable. 1748 6.4.1. MIME Media Types 1750 All MIME media types for CDNI Metadata objects are prefixed with 1751 "application/cdni.". The MIME media type for each object then 1752 contains the object name of that object as defined by this document. 1753 The object type name is followed by ".v" and the version number of 1754 the object type (e.g., ".v1"). Finally, the encoding type "+json" is 1755 appended. Table 4 lists the MIME media type for the metadata objects 1756 (resources) that are specified in this document. 1758 +-----------------------+-------------------------------------------+ 1759 | Data Object | MIME Media Type | 1760 +-----------------------+-------------------------------------------+ 1761 | HostIndex | application/cdni.HostIndex.v1+json | 1762 | HostMatch | application/cdni.HostMatch.v1+json | 1763 | HostMetadata | application/cdni.HostMetadata.v1+json | 1764 | PathMatch | application/cdni.PathMatch.v1+json | 1765 | PatternMatch | application/cdni.PatternMatch.v1+json | 1766 | PathMetadata | application/cdni.PathMetadata.v1+json | 1767 | GenericMetadata | application/cdni.GenericMetadata.v1+json | 1768 | SourceMetadata | application/cdni.SourceMetadata.v1+json | 1769 | Source | application/cdni.Source.v1+json | 1770 | LocationACL | application/cdni.LocationACL.v1+json | 1771 | LocationRule | application/cdni.LocationRule.v1+json | 1772 | Footprint | application/cdni.Footprint.v1+json | 1773 | TimeWindowACL | application/cdni.TimeWindowACL.v1+json | 1774 | TimeWindowRule | application/cdni.TimeWindowRule.v1+json | 1775 | TimeWindow | application/cdni.TineWindow.v1+json | 1776 | ProtocolACL | application/cdni.ProtocolACL.v1+json | 1777 | ProtocolRule | application/cdni.ProtocolRule.v1+json | 1778 | DeliveryAuthorization | application/ | 1779 | | cdni.DeliveryAuthorization.v1+json | 1780 | Cache | application/cdni.Cache.v1+json | 1781 | Grouping | application/cdni.Grouping.v1+json | 1782 | Auth | application/cdni.Auth.v1+json | 1783 | CredentialsAuth | application/cdni.CredentialAuth.v1+json | 1784 +-----------------------+-------------------------------------------+ 1786 Table 4: MIME Media Types for CDNI Metadata objects 1788 6.4.2. I-JSON Encoding of Objects 1790 A CDNI Metadata object is encoded as an I-JSON object [RFC7492] 1791 containing a dictionary of (key,value) pairs where the keys are the 1792 property names and the values are the associated property values. 1794 The keys of the dictionary are the names of the properties associated 1795 with the object and are therefore dependent on the specific object 1796 being encoded (i.e., dependent on the MIME Media Type of the returned 1797 resource). Likewise, the values associated with each key are 1798 dependent on the specific object being encoded (i.e., dependent on 1799 the MIME Media Type of the returned resource). 1801 Dictionary keys in JSON are case sensitive. By convention any 1802 dictionary key defined by this document (for example the names of 1803 CDNI Metadata object properties) MUST be represented in lowercase. 1805 In addition to the properties specified for each object type, the 1806 keys defined below may be present in any object. 1808 Key: base 1810 Description: Provides a prefix for any relative URLs in the 1811 object. This is similar to the XML base tag [XML-BASE]. If 1812 absent, all URLs in the remainder of the response MUST be 1813 absolute URLs. 1815 Type: URI 1817 Mandatory: No 1819 Key: _links 1821 Description: The links from this object to other addressable 1822 objects. Any property whose value is an object may be replaced 1823 by a link to an object with the same type as the property it 1824 replaces. The keys of the _links dictionary are the names of 1825 the properties being replaced. The values of the dictionary 1826 are Link objects with href set to the URI of the object and 1827 type set to the MIME media type of the object being replaced. 1829 Type: Dictionary object of Link objects 1831 Mandatory: No 1833 6.4.2.1. Encoded CDNI Metadata Example 1835 A dCDN may request the HostIndex and receive the following object of 1836 type "application/cdni.HostIndex.v1+json": 1838 { 1839 "hosts": [ 1840 { 1841 "host": "video.example.com", 1842 "_links": { 1843 "host-metadata" : { 1844 "type": "application/cdni.HostMetadata.v1+json", 1845 "href": "http://metadata.ucdn.example/host1234" 1846 } 1847 } 1848 }, 1849 { 1850 "host": "images.example.com", 1851 "_links": { 1852 "host-metadata" : { 1853 "type": "application/cdni.HostMetadata.v1+json", 1854 "href": "http://metadata.ucdn.example/host5678" 1855 } 1856 } 1857 } 1858 ] 1859 } 1861 If the incoming request has a Host header with "video.example.com" 1862 then the dCDN would fetch the next metadata object from 1863 "http://metadata.ucdn.example/host1234" expecting a MIME media type 1864 of "application/cdni.HostMetadata.v1+json": 1866 { 1867 "metadata": [ 1868 { 1869 "generic-metadata-type": 1870 "application/cdni.SourceMetadata.v1+json", 1871 "generic-metadata-value": { 1872 "sources": [ 1873 { 1874 "_links": { 1875 "acquisition-auth": { 1876 "auth-type": "application/cdni.Auth.v1+json", 1877 "href": "http://metadata.ucdn.example/auth1234" 1878 } 1879 }, 1880 "endpoint": "acq1.ucdn.example", 1881 "protocol": "HTTP1.1" 1882 }, 1883 { 1884 "_links": { 1885 "acquisition-auth": { 1886 "auth-type": "application/cdni.Auth.v1+json", 1887 "href": "http://metadata.ucdn.example/auth1234" 1888 } 1889 }, 1890 "endpoint": "acq2.ucdn.example", 1891 "protocol": "HTTP1.1" 1892 } 1893 ] 1894 } 1895 }, 1896 { 1897 "generic-metadata-type": 1898 "application/cdni.LocationACL.v1+json", 1899 "generic-metadata-value": { 1900 "locations": [ 1901 { 1902 "footprints": [ 1903 { 1904 "footprint-type": "IPv4CIDR", 1905 "footprint-value": "192.0.2.0/24" 1906 } 1907 ], 1908 "action": "deny" 1909 } 1910 ] 1911 } 1912 }, 1913 { 1914 "generic-metadata-type": 1915 "application/cdni.ProtocolACL.v1+json", 1916 "generic-metadata-value": { 1917 "protocol-acl": [ 1918 { 1919 "protocols": [ 1920 "HTTP1.1" 1921 ], 1922 "action": "allow" 1923 } 1924 ] 1925 } 1926 } 1927 ], 1928 "paths": [ 1929 { 1930 "path-pattern": { 1931 "pattern": "/video/trailers/*" 1932 }, 1933 "_links": { 1934 "path-metadata": { 1935 "type": "application/cdni.PathMetadata.v1+json", 1936 "href": "http://metadata.ucdn.example/host1234/pathABC" 1937 } 1938 } 1939 }, 1940 { 1941 "path-pattern": { 1942 "pattern": "/video/movies/*" 1943 }, 1944 "_links": { 1945 "path-metadata": { 1946 "type": "application/cdni.PathMetadata.v1+json", 1947 "href": "http://metadata.ucdn.example/host1234/pathDCE" 1948 } 1949 } 1950 } 1951 ] 1952 } 1954 Suppose the path of the requested resource matches the "/video/ 1955 movies/*" pattern, the next metadata requested would be for 1956 "http://metadata.ucdn.example/host1234/movies" with an expected type 1957 of "application/cdni.PathMetadata.v1+json": 1959 { 1960 "metadata": [], 1961 "paths": [ 1962 { 1963 "path-pattern": { 1964 "pattern": "/videos/movies/hd/*" 1965 }, 1966 "_links": { 1967 "pathmetadata": { 1968 "type": "application/cdni.PathMetadata.v1+json", 1969 "href": 1970 "http://metadata.ucdn.example/host1234/pathABC/path123" 1971 } 1972 } 1973 } 1974 ] 1975 } 1977 Finally, if the path of the requested resource also matches the 1978 "/videos/movies/hd/*" pattern, the dCDN would also fetch the 1979 following object from "http://metadata.ucdn.example/host1234/movies/ 1980 hd" with MIME media type "application/cdni.PathMetadata.v1+json": 1982 { 1983 "metadata": [ 1984 { 1985 "generic-metadata-type": 1986 "application/cdni.TimeWindowACL.v1+json", 1987 "generic-metadata-value": { 1988 "times": [ 1989 "windows": [ 1990 { 1991 "start": "1213948800", 1992 "end": "1327393200" 1993 } 1994 ], 1995 "action": "allow" 1996 ] 1997 } 1998 } 1999 ] 2000 } 2002 6.5. Extensibility 2004 The set of property Metadata may be extended with additional 2005 (standards based or vendor specific) property Metadata through the 2006 specification of new GenericMetadata objects. The GenericMetadata 2007 object defined in Section 4.1.7 specifies a type field and a type- 2008 specific value field that allows any Metadata property to be included 2009 in either the HostMetadata or PathMetadata lists. 2011 As with the initial GenericMetadata types defined in Section 4.2, 2012 future GenericMetadata types MUST specify the information necessary 2013 for constructing and decoding the GenericMetadata object. This 2014 information includes the list of properties contained within the 2015 GenericMetadata object, and for each property, the specification 2016 should include a description, a type, and whether or not the given 2017 property is mandatory-to-specify. 2019 Any document which defines a new GenericMetadata type has to: 2021 1. Specify the MIME Media Type used to identify the new 2022 GenericMetadata type being specified. 2024 2. Define the set of properties associated with the new type. 2026 3. For each property, define a name, description, type, and whether 2027 or not the property is mandatory-to-specify. 2029 4. Describe the semantics of the new type including its purpose and 2030 example of a use case to which it applies. 2032 Note: Identification, within the type name defined for a property 2033 Metadata object, of the organization that defined the extension 2034 property Metadata decreases the possibility of property Metadata type 2035 collisions. 2037 6.6. Metadata Enforcement 2039 At any given time, the set of GenericMetadata types supported by the 2040 uCDN may not match the set of GenericMetadata types supported by the 2041 dCDN. 2043 In the cases where a uCDN sends Metadata containing a GenericMetadata 2044 type that a dCDN does not support, the dCDN MUST enforce the 2045 semantics of the "mandatory-to-enforce" property. If a dCDN does not 2046 understand or is unable to perform the functions associated with any 2047 "mandatory-to-enforce" Metadata, the dCDN MUST NOT service any 2048 requests for the corresponding content. 2050 Note: Ideally, uCDNs would not delegate content requests to a dCDN 2051 which does not support the "mandatory-to-enforce" Metadata associated 2052 with the content being requested. However, even if the uCDN has a 2053 priori knowledge of the Metadata supported by the dCDN (e.g., via the 2054 CDNI capabilities interface or through out-of-band negotiation 2055 between CDN operators) Metadata support may fluctuate or be 2056 inconsistent (e.g., due to mis-communication, mis-configuration, or 2057 temporary outage). Thus, the dCDN MUST always evaluate all Metadata 2058 associated with content requests and reject any requests where 2059 "mandatory-to-enforce" Metadata associated with the content cannot be 2060 enforced. 2062 6.7. Metadata Conflicts 2064 It is possible that new Metadata definitions may obsolete or conflict 2065 with existing property Metadata (e.g., a future revision of the CDNI 2066 Metadata interface may redefine the Auth Metadata or a custom vendor 2067 extension may implement an alternate Auth Metadata option). If 2068 multiple Metadata (e.g., cdni.Auth.v2, vendor1.Auth, and 2069 vendor2.Auth) all conflict with an existing Metadata (e.g., 2070 cdni.Auth) and all are marked as "mandatory-to-enforce", it may be 2071 ambiguous which Metadata should be applied, especially if the 2072 functionality of the Metadata overlap. 2074 As described in Section 3.3, Metadata override only applies to 2075 Metadata objects of the same exact type, found in HostMetadata and 2076 nested PathMetadata structures. The CDNI Metadata interface does not 2077 support enforcement of dependencies between different Metadata types. 2078 It is the responsibility of the CSP and the CDN operators to ensure 2079 that Metadata assigned to a given content do not conflict. 2081 Note: Because Metadata is inherently ordered in GenericMetadata 2082 lists, as well as in the PathMetadata hierarchy and PathMatch lists, 2083 multiple conflicting Metadata types MAY be used, however, Metadata 2084 hierarchies MUST ensure that independent PathMatch root objects are 2085 used to prevent ambiguous or conflicting Metadata definitions. 2087 6.8. Versioning 2089 The version of CDNI Metadata Structural objects is conveyed inside 2090 the MIME media type that is included in the HTTP Content-Type header. 2091 Upon responding to a request for an object, a metadata server MUST 2092 include a Content-Type header with the MIME media type containing the 2093 version number of the object. HTTP requests sent to a metadata 2094 server SHOULD include an Accept header with the MIME media type 2095 (which includes the version) of the expected object. Metadata 2096 clients can specify multiple MIME media types in the Accept header, 2097 for example if a metadata client is capable of processing two 2098 different versions of the same type of object (defined by different 2099 MIME media types) it may decide to include both in the Accept header. 2100 The version of each object defined by this document is version 1. 2101 For example: "Content-Type: application/cdni.HostIndex.v1+json". 2103 GenericMetadata objects include a "type" property which specifies the 2104 MIME media type of the GenericMetadata value. This MIME media type 2105 should also include a version. Any document which defines a new type 2106 of GenericMetadata MUST specify the version number which it 2107 describes. For example: "application/cdni.Location.v1+json". 2109 7. IANA Considerations 2111 This document requests the registration of the following MIME Media 2112 Type under the IANA MIME Media Type registry 2113 (http://www.iana.org/assignments/media-types/index.html). 2115 application/cdni.HostIndex.v1+json 2117 application/cdni.HostMatch.v1+json 2119 application/cdni.HostMetadata.v1+json 2121 application/cdni.PathMatch.v1+json 2123 application/cdni.PatternMatch.v1+json 2124 application/cdni.PathMetadata.v1+json 2126 application/cdni.GenericMetadata.v1+json 2128 application/cdni.SourceMetadata.v1+json 2130 application/cdni.Source.v1+json 2132 application/cdni.LocationACL.v1+json 2134 application/cdni.LocationRule.v1+json 2136 application/cdni.Footprint.v1+json 2138 application/cdni.TimeWindowACL.v1+json 2140 application/cdni.TimeWindowRule.v1+json 2142 application/cdni.TimeWindow.v1+json 2144 application/cdni.ProtocolACL.v1+json 2146 application/cdni.ProtocolRule.v1+json 2148 application/cdni.DeliveryAuthorization.v1+json 2150 application/cdni.Cache.v1+json 2152 application/cdni.Grouping.v1+json 2154 application/cdni.Auth.v1+json 2156 application/cdni.CredentialsAuth.v1+json 2158 7.1. CDNI Metadata Footprint Types Registry 2160 The IANA is requested to create a new "CDNI Metadata Footprint Types" 2161 registry. The "CDNI Metadata Footprint Types" namespace defines the 2162 valid Footprint object type values used by the Footprint object in 2163 Section 4.2.2.2. Additions to the Footprint type namespace conform 2164 to the "Expert Review" policy as defined in [RFC5226]. The expert 2165 reviewer should verify that new type definitions do not duplicate 2166 existing type definitions and prevent gratuitous additions to the 2167 namespace. 2169 The following table defines the initial Footprint Registry values: 2171 +----------------+-------------------------------+---------------+ 2172 | Footprint Type | Description | Specification | 2173 +----------------+-------------------------------+---------------+ 2174 | ipv4cidr | IPv4 CIDR address block | RFCthis | 2175 | ipv6cidr | IPv6 CIDR address block | RFCthis | 2176 | asn | Autonomous System (AS) Number | RFCthis | 2177 | countrycode | ISO 3166-1 alpha-2 code | RFCthis | 2178 +----------------+-------------------------------+---------------+ 2180 7.2. CDNI Metadata Protocol Types Registry 2182 The IANA is requested to create a new "CDNI Metadata Protocol Types" 2183 registry. The "CDNI Metadata Protocol Types" namespace defines the 2184 valid Protocol object values in Section 4.3.2, used by the 2185 SourceMetadata and ProtocolACL objects. Additions to the Protocol 2186 namespace conform to the "Expert Review" policy as defined in 2187 [RFC5226]. The expert review should verify that new protocol 2188 definitions do not duplicate existing protocol definitions and 2189 prevent gratuitous additions to the namespace. 2191 The following table defines the initial Protocol values: 2193 +--------------+------------------------------------+---------------+ 2194 | Protocol | Description | Specification | 2195 | Type | | | 2196 +--------------+------------------------------------+---------------+ 2197 | HTTP1.1 | Hypertext Transfer Protocol -- | RFC7230 | 2198 | | HTTP/1.1 | | 2199 | HTTPS1.1 | HTTP/1.1 Over TLS | RFC2818 | 2200 +--------------+------------------------------------+---------------+ 2202 7.3. CDNI Metadata Auth Types Registry 2204 The IANA is requested to create a new "CDNI Metadata Auth Types" 2205 registry. The "CDNI Metadata Auth Type" namespace defines the valid 2206 Auth object types used by the Auth object in Section 4.3.6. 2207 Additions to the Auth Type namespace conform to the "Expert Review" 2208 policy as defined in [RFC5226]. The expert review should verify that 2209 new type definitions do not duplicate existing type definitions and 2210 prevent gratuitous additions to the namespace. 2212 The following table defines the initial Auth type values: 2214 +----------------+----------------------------------+---------------+ 2215 | Auth Type | Description | Specification | 2216 +----------------+----------------------------------+---------------+ 2217 | CredentialAuth | Simple username and password | RFCthis | 2218 | | authentication. | | 2219 +----------------+----------------------------------+---------------+ 2221 8. Security Considerations 2223 8.1. Authentication 2225 Unauthorized access to metadata could result in denial of service. A 2226 malicious metadata server, proxy server or an attacker performing a 2227 "man in the middle" attack" could provide metadata to a dCDN that 2228 denies service for one or more pieces of content to one or more user 2229 agents. A malicious metadata server (or an attacker performing a 2230 "Man in the middle" attack") could modify metadata so that dCDNs are 2231 directed to contact to malicious origin servers instead of the actual 2232 origin servers. A malicious metadata client could continuously issue 2233 large metadata requests to overload a uCDN's metadata server(s). 2235 Unauthorized access to metadata could result in denial of service. A 2236 malicious metadata server, proxy server or an attacker performing a 2237 "man in the middle" attack could provide metadata to a dCDN that 2238 either: 2240 o Denies service for one or more pieces of content to one or more 2241 User Agents; or 2243 o Directs dCDNs to contact malicious origin servers instead of the 2244 actual origin servers. 2246 Unauthorized access to metadata could also enable a malicious 2247 metadata client to continuously issue large metadata requests in 2248 order to overload a uCDN's metadata server(s). 2250 Unauthorized access to metadata could result in leakage of private 2251 information. A malicious metadata client could request metadata in 2252 order to gain access to origin servers, as well as information 2253 pertaining to content restrictions. 2255 An implementation of the CDNI Metadata interface SHOULD use mutual 2256 authentication to prevent unauthorized access to metadata. 2258 8.2. Confidentiality 2260 Unauthorized viewing of metadata could result in leakage of private 2261 information. A third party could intercept metadata transactions in 2262 order to gain access to origin servers, as well as information 2263 pertaining to content restrictions. 2265 An implementation of the CDNI Metadata interface SHOULD use strong 2266 encryption to prevent unauthorized viewing of metadata. 2268 8.3. Integrity 2270 Unauthorized modification of metadata could result in denial of 2271 service. A malicious metadata server, proxy server or an attacker 2272 performing a "man in the middle" attack" could modify metadata 2273 destined to a dCDN in order to deny service for one or more pieces of 2274 content to one or more user agents. A malicious metadata server, 2275 proxy server or an attacker performing a "Man in the middle" attack" 2276 could modify metadata so that dCDNs are directed to contact to 2277 malicious origin servers instead of the actual origin servers. 2279 An implementation of the CDNI Metadata interface SHOULD use strong 2280 encryption and mutual authentication to prevent unauthorized 2281 modification of metadata. 2283 8.4. Privacy 2285 Content provider origin and policy information is conveyed through 2286 the CDNI Metadata interface. The distribution of this information to 2287 another CDN may introduce potential privacy concerns for some content 2288 providers, for example because dCDNs accepting content requests for a 2289 content provider's content may be able to obtain additional 2290 information & usage patterns relating to the users of a content 2291 provider's services. Content providers with such concerns can 2292 instruct their CDN partners not to use CDN interconnects when 2293 delivering that content provider's content. 2295 8.5. Securing the CDNI Metadata interface 2297 An implementation of the CDNI Metadata interface MUST support TLS 2298 transport as per [RFC2818] and [RFC7230]. The use of TLS for 2299 transport of the CDNI Metadata interface messages allows: 2301 o The dCDN and uCDN to authenticate each other (to ensure they are 2302 transmitting/receiving CDNI Metadata requests & responses from an 2303 authenticated CDN). 2305 o CDNI Metadata interface requests and responses to be transmitted 2306 with confidentiality. 2308 o The integrity of the CDNI Metadata interface requests and 2309 responses to be protected during the exchange. 2311 In an environment where any such protection is required, TLS MUST be 2312 used (including authentication of the remote end) by the server-side 2313 (uCDN) and the client-side (dCDN) of the CDNI Metadata interface 2314 unless alternate methods are used for ensuring the confidentiality of 2315 the information in the CDNI Metadata interface requests and responses 2316 (such as setting up an IPsec tunnel between the two CDNs or using a 2317 physically secured internal network between two CDNs that are owned 2318 by the same corporate entity). 2320 When TLS is used, the general TLS usage guidance in [RFC7525] MUST be 2321 followed. 2323 9. Acknowledgements 2325 The authors would like to thank David Ferguson and Francois Le 2326 Faucheur for their valuable comments and input to this document. 2328 10. Contributing Authors 2330 [RFC Editor Note: Please move the contents of this section to the 2331 Authors' Addresses section prior to publication as an RFC.] 2333 Grant Watson 2334 Velocix (Alcatel-Lucent) 2335 3 Ely Road 2336 Milton, Cambridge CB24 6AA 2337 UK 2339 Email: gwatson@velocix.com 2341 Kent Leung 2342 Cisco Systems 2343 3625 Cisco Way 2344 San Jose, 95134 2345 USA 2347 Email: kleung@cisco.com 2349 11. References 2351 11.1. Normative References 2353 [ISO3166-1] 2354 "https://www.iso.org/obp/ui/#search". 2356 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2357 Requirement Levels", BCP 14, RFC 2119, March 1997. 2359 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 2360 Architecture", RFC 4291, February 2006. 2362 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2363 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2364 May 2008. 2366 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois 2367 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288, 2368 August 2008. 2370 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 2371 Content", RFC 5861, May 2010. 2373 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 2374 Address Text Representation", RFC 5952, August 2010. 2376 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2377 "Recommendations for Secure Use of Transport Layer 2378 Security (TLS) and Datagram Transport Layer Security 2379 (DTLS)", BCP 195, RFC 7525, May 2015. 2381 11.2. Informative References 2383 [I-D.ietf-cdni-redirection] 2384 Niven-Jenkins, B. and R. Brandenburg, "Request Routing 2385 Redirection Interface for CDN Interconnection", draft- 2386 ietf-cdni-redirection-10 (work in progress), July 2015. 2388 [I-D.ietf-httpbis-http2] 2389 Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer 2390 Protocol version 2", draft-ietf-httpbis-http2-17 (work in 2391 progress), February 2015. 2393 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2395 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2396 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2397 3986, January 2005. 2399 [RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content 2400 Distribution Network Interconnection (CDNI) Problem 2401 Statement", RFC 6707, September 2012. 2403 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2404 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2405 2014. 2407 [RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, 2408 "Framework for Content Distribution Network 2409 Interconnection (CDNI)", RFC 7336, August 2014. 2411 [RFC7337] Leung, K. and Y. Lee, "Content Distribution Network 2412 Interconnection (CDNI) Requirements", RFC 7337, August 2413 2014. 2415 [RFC7492] Bhatia, M., Zhang, D., and M. Jethanandani, "Analysis of 2416 Bidirectional Forwarding Detection (BFD) Security 2417 According to the Keying and Authentication for Routing 2418 Protocols (KARP) Design Guidelines", RFC 7492, March 2015. 2420 [XML-BASE] 2421 Marsh, J., Ed. and R. Tobin, Ed., "XML Base (Second 2422 Edition) - http://www.w3.org/TR/xmlbase/", January 2009. 2424 Authors' Addresses 2426 Ben Niven-Jenkins 2427 Velocix (Alcatel-Lucent) 2428 3 Ely Road 2429 Milton, Cambridge CB24 6AA 2430 UK 2432 Email: ben@velocix.com 2434 Rob Murray 2435 Velocix (Alcatel-Lucent) 2436 3 Ely Road 2437 Milton, Cambridge CB24 6AA 2438 UK 2440 Email: rmurray@velocix.com 2441 Matt Caulfield 2442 Cisco Systems 2443 1414 Massachusetts Avenue 2444 Boxborough, MA 01719 2445 USA 2447 Phone: +1 978 936 9307 2448 Email: mcaulfie@cisco.com 2450 Kevin J. Ma 2451 Ericsson 2452 43 Nagog Park 2453 Acton, MA 01720 2454 USA 2456 Phone: +1 978-844-5100 2457 Email: kevin.j.ma@ericsson.com