idnits 2.17.1 draft-ma-cdni-metadata-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 16, 2012) is 4273 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) == Outdated reference: A later version (-17) exists of draft-ietf-cdni-requirements-02 == Outdated reference: A later version (-10) exists of draft-ietf-cdni-use-cases-04 Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group K. Ma 3 Internet-Draft Azuki Systems, Inc. 4 Intended status: Standards Track July 16, 2012 5 Expires: January 17, 2013 7 Content Distribution Network Interconnection (CDNI) Metadata Interface 8 draft-ma-cdni-metadata-03 10 Abstract 12 Content publishers (CPs) often use multiple Content Delivery Networks 13 (CDNs) to deliver content to consumers. Though existing interactions 14 between CPs and individual CDNs are beyond the scope of CDN 15 interconnection (CDNI), it is important to understand the management 16 capabilities and features available with existing non-interconnected 17 multi-CDN deployments. Before migrating to CDNI, CPs must first 18 assess the suitability of CDNI as a replacement for their existing 19 non-interconnected multi-CDN deployments. CDN feature configuration 20 and capability advertisement and enforcement is likely to occur 21 through the CDNI metadata interface (MI). This document describes an 22 approach to implementing the CDNI MI through the use of an extensible 23 metadata model and a light-weight HTTP-based API. 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 17, 2013. 48 Copyright Notice 49 Copyright (c) 2012 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 66 1.2. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 5 67 2. CDNI Metadata Data Model . . . . . . . . . . . . . . . . . . . 6 68 2.1. Domain Table . . . . . . . . . . . . . . . . . . . . . . . 7 69 2.2. Base Address Table . . . . . . . . . . . . . . . . . . . . 7 70 2.2.1. Hierarchical Base Addresses . . . . . . . . . . . . . 9 71 2.3. Agent Table . . . . . . . . . . . . . . . . . . . . . . . 9 72 2.4. Metadata Table . . . . . . . . . . . . . . . . . . . . . . 11 73 2.4.1. Hierarchical Metadata . . . . . . . . . . . . . . . . 12 74 3. CDNI Metadata Bootstrapping . . . . . . . . . . . . . . . . . 14 75 4. CDNI Metadata Management . . . . . . . . . . . . . . . . . . . 15 76 4.1. Metadata API . . . . . . . . . . . . . . . . . . . . . . . 16 77 4.1.1. Metadata Creation . . . . . . . . . . . . . . . . . . 17 78 4.1.2. Metadata Update . . . . . . . . . . . . . . . . . . . 18 79 4.1.3. Metadata Refresh Trigger . . . . . . . . . . . . . . . 19 80 4.1.4. Metadata Retrieval . . . . . . . . . . . . . . . . . . 20 81 4.1.5. Metadata Removal . . . . . . . . . . . . . . . . . . . 22 82 4.1.6. Metadata Errors . . . . . . . . . . . . . . . . . . . 23 83 4.1.7. Metadata Prepositioning . . . . . . . . . . . . . . . 23 84 5. Metadata Definitions . . . . . . . . . . . . . . . . . . . . . 24 85 5.1. Origin Server . . . . . . . . . . . . . . . . . . . . . . 24 86 5.2. Activation Time . . . . . . . . . . . . . . . . . . . . . 24 87 5.3. Deactivation Time . . . . . . . . . . . . . . . . . . . . 25 88 5.4. Administrative Disable . . . . . . . . . . . . . . . . . . 25 89 5.5. Delegation Depth . . . . . . . . . . . . . . . . . . . . . 26 90 5.6. Footprint Filter . . . . . . . . . . . . . . . . . . . . . 26 91 5.7. HTTP Header Filter . . . . . . . . . . . . . . . . . . . . 27 92 5.8. HTTP Header Logging . . . . . . . . . . . . . . . . . . . 27 93 5.9. Protocol Filter . . . . . . . . . . . . . . . . . . . . . 27 94 5.10. SSL Required . . . . . . . . . . . . . . . . . . . . . . . 28 95 5.11. SSL Client Authentication Required . . . . . . . . . . . . 28 96 5.12. URL Hash . . . . . . . . . . . . . . . . . . . . . . . . . 29 97 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 98 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29 99 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 30 100 9. Appendix A: Domain API . . . . . . . . . . . . . . . . . . . . 30 101 9.1. Domain Creation . . . . . . . . . . . . . . . . . . . . . 31 102 9.2. Domain Update . . . . . . . . . . . . . . . . . . . . . . 31 103 9.3. Domain Retrieval . . . . . . . . . . . . . . . . . . . . . 31 104 9.4. Domain Removal . . . . . . . . . . . . . . . . . . . . . . 32 105 9.5. Domain Errors . . . . . . . . . . . . . . . . . . . . . . 32 106 10. Appendix B: Agent API . . . . . . . . . . . . . . . . . . . . 32 107 10.1. Agent Creation . . . . . . . . . . . . . . . . . . . . . . 33 108 10.2. Agent Update . . . . . . . . . . . . . . . . . . . . . . . 34 109 10.3. Agent Retrieval . . . . . . . . . . . . . . . . . . . . . 35 110 10.4. Agent Removal . . . . . . . . . . . . . . . . . . . . . . 35 111 10.5. Agent Errors . . . . . . . . . . . . . . . . . . . . . . . 35 112 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 36 113 11.1. Normative References . . . . . . . . . . . . . . . . . . . 36 114 11.2. Informative References . . . . . . . . . . . . . . . . . . 36 115 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 36 117 1. Introduction 119 The use cases described in the CDNI use case document 120 [I-D.ietf-cdni-use-cases] provide motivational use cases for CDN 121 interconnection (CDNI). They describe reasons and situations where 122 CDNI provides a benefit to CDN vendors as well as content service 123 providers (CSPs). Additional use cases exist which describe how CDNs 124 are used today, however, these use cases often involve specific 125 features (e.g., customized content transformations, content security, 126 client authentication and filtering, content acquisition optimization 127 and redundancy, etc.) which are beyond the scope of CDNI. Though the 128 features themselves are not relevant to CDNI, the ability to support 129 those features or enforce policies related to those features in a 130 generic and extensible manner should be considered when designing 131 CDNI interfaces. The ability to support feature parity with existing 132 deployment models (i.e., non-CDNI-based CDN federation) may help to 133 remove barriers to CDNI adoption. 135 Though certain interfaces are out of scope of CDNI, e.g.: 137 o upstream CDN (uCDN) configuration by the CP 139 o uCDN content acquisition 141 o uCDN content delivery 143 o downstream CDN (dCDN) content acquisition 145 o end user (EU) content acquisition 147 o third party workflow management 149 o third party request routing 151 An awareness of these interfaces and an understanding of the 152 restrictions which they may impose on CDNI request routing is useful 153 for understanding the needs of the CDNI metadata interface (MI). As 154 described in the "Dynamic CDNI Metadata Acquisition Example" section 155 in the CDNI framework document [I-D.davie-cdni-framework], upon 156 receiving a request routing interface (RRI) request, the MI MAY be 157 used to retrieve metadata that is "considered" before responding to 158 the RRI request. To that end, the MI MUST define a deterministic 159 method for handling metadata processing. Though the definition and 160 interpretation of any individual piece of metadata is beyond the 161 scope of CDNI, a well-defined method for how to respond to a RRI 162 request when any unknown metadata value is encountered MUST be 163 supported. 165 This document describes a simple data model for representing CDNI 166 metadata and a simple protocol for creating and retrieving CDNI 167 metadata in an opaque manner. The term opaque, in this case, should 168 be understood to mean: without understanding the underlying meaning 169 or interpretation of the metadata being represented. The metadata 170 model and retrieval protocol SHOULD be completely independent of the 171 definition of individual metadata values. The metadata model and 172 retrieval protocol MUST also define default behaviors for dealing 173 with metadata processing errors. The document defines a list of 174 metadata which are likely applicable to a broad range of CDNI 175 deployments. The document also provides a separate list of metadata 176 which are likely to be desirable to content publishers (CPs). This 177 document is not intended to suggest that any additional interfaces or 178 requirements are needed beyond those already specified in the CDNI 179 requirements document [I-D.ietf-cdni-requirements], nor is this 180 document intended to suggest that any out of scope interfaces or 181 content publisher feature functionality should be brought into scope. 182 The metadata examples provided are intended only to illustrate 183 possible features that interconnected CDNs may wish to support and 184 the extensibility of the metadata model to handle those situations. 186 1.1. Terminology 188 [Ed. insert terminology reference] 190 1.2. Abbreviations 192 o CDN: Content Distribution Network 194 o uCDN: Upstream Content Distribution Network 196 o dCDN: Downstream Content Distribution Network 198 o CDNI: Content Distribution Network Interconnection 200 o CP: Content Publisher 202 o CSP: Content Service Provider 204 o EU: End User 206 o NSP: Network Service Provider 208 o RRI: Request Routing Interface 210 o MI: Metadata Interface 211 o CI: Control Interface 213 2. CDNI Metadata Data Model 215 The simple data model is shown in Figure 1 below. It includes a top 216 level Domain object which describes the site(s) to which metadata is 217 associated. The term site, in this case, should be understood to 218 mean a collection of related content assets accessed through a single 219 portal or Web-site. The Domain is associated with zero or more 220 opaque Metadata objects. Each Metadata object is associated with one 221 or more Base Address objects. The Metadata objects are each 222 associated with a URI extension, applicable to any of the associated 223 Base Addresses. A combination of Base Address and URI prefix 224 matching is used identify Metadata to allow for hierarchical 225 associations between individual Metadata and sets of content items. 226 Each Domain is also associated with one or more Agent objects. 227 Agents represent entities which require access to metadata (e.g., 228 CPs, uCDNs, dCDNs, or local operators). An Agent is associated with 229 each Metadata entry allowing different Metadata values to be returned 230 to different Agents. 232 +----------+ 233 | | 1 234 | Agent +---------------+ 235 | | | 236 +----+-----+ | 237 | 1..* | 238 | | 239 | 1 | 0..* 240 +----+-----+ +----+-----+ +----------+ 241 | | 1 0..* | | 1 1..* | | 242 | Domain +----------+ Metadata +----------+ BaseAddr | 243 | | | | | | 244 +----+-----+ +----------+ +----------+ 246 Figure 1: CDNI Metadata Data Model 248 Note: The data model described above provides the basic components 249 required for distributing Metadata and implementing the CDNI MI. The 250 specific semantics of individual pieces of metadata are abstracted to 251 allow for opaque distribution of metadata. Not all of the 252 information described need be distributed through the MI. Some 253 information (e.g., Domains and Agents) may be necessary for the MI to 254 function, but MAY be negotiated or implemented out-of-band. They 255 could be configured either by the CDN as part of a non-CDNI process, 256 or through the CDNI control interface (CI) bootstrapping process, or 257 using the MI APIs described herein. The MI APIs may also be used by 258 CDNs, internally, to configure themselves. The complete data model 259 and full set of APIs are provided as part of a holistic MI 260 description. 262 The following sections describe an example implementation of the 263 metadata scheme described above using a standard SQL database. 265 2.1. Domain Table 267 The Domain object contains basic information related to the site 268 being described. The example shown contains a primary key index and 269 a unique name for the site. An OPTIONAL site description (e.g., a 270 textual description of the site and its content) and site provider 271 (e.g., the name of the CP or CSP which owns the content) information 272 is also included. 274 CREATE TABLE "domain" ("domain_id" serial primary key, 275 "name" character varying(255) NOT NULL, 276 "provider" character varying(255), 277 "description" character varying(4095)); 278 CREATE UNIQUE INDEX index_domain ON domain (name); 280 The Domain is the central object for binding Metadata. The example 281 Domain shown below highlights the descriptive nature of the Domain 282 object: 284 domain_id: 1 285 name: acme 286 provider: acme rocket-powered products, inc 287 description: fine purveyors of high quality anvils, rubber bands, 288 bird seed, and rocket-powered footwear. 290 2.2. Base Address Table 292 The Base Address object contains basic hostname and base URI 293 information related to the site being accessed. The example shown 294 requires a primary key index, a string containing the hostname and 295 base URI, and a foreign key reference to the Metadata to which this 296 Base Address is associated. A uniqueness constraint is imposed on 297 baseaddr/metadata_id pairs to prevent duplicate Base Address entries 298 for a given Metadata. 300 CREATE TABLE "baseaddr" ("baseaddr_id" serial primary key, 301 "baseaddr" character varying(255) NOT NULL, 302 "metadata_id" integer NOT NULL); 303 CREATE UNIQUE INDEX index_baseaddr ON baseaddr (baseaddr, 304 metadata_id); 306 Base Address Table Definition 308 The Base Address objects allows multiple hostname and base URI pairs 309 to be associated with each Metadata object denoting the list of Base 310 Addresses through which content within the Domain may be accessed. 311 There are many cases where different Base Addresses are used to 312 access the same content, e.g.: 314 o internal vs. external addresses: content may be accessible via 315 both internal 10-net IP addresses and their associated DNS 316 addresses and base URIs, as well as publicly routable external IP 317 addresses and their associated DNS addresses and base URIs, where 318 all of the addresses point to the same content servers and the 319 base URIs are mapped to the same base directories, 321 o service white-labeling: multiple CSPs may provide access to the 322 same content through different branded services where each branded 323 service has its own DNS address and/or base URI, but all of the 324 services point to the same content, or 326 o analytics partitioning: redirects from other sites may use 327 different DNS addresses and/or base URIs, so that they may be 328 easily accounted for, while still pointing at the same content. 330 The example Base Addresses shown below represent two DNS addresses 331 through which content may be accessed as well as an internal IP 332 address which may be used for staging: 334 baseaddr_id: 1 335 baseaddr: wile.e.coyote.acme.com 336 metadata_id: 1 338 baseaddr_id: 2 339 baseaddr: road.runner.acme.com 340 metadata_id: 1 342 baseaddr_id: 3 343 baseaddr: 10.10.10.10/meemeep 344 metadata_id: 1 346 Note: The exact schema described above may result in heavy 347 duplication of Base Addresses. It is presented as an example for its 348 simplicity, however, it may be optimized by using other table joining 349 implementation schemes. 351 2.2.1. Hierarchical Base Addresses 353 In order to support hierarchical Base Addresses, the wildcard '*.' 354 SHOULD be allowed as the first part of DNS-type Base Addresses. The 355 wildcard does not make sense at the beginning of IP Address-type Base 356 Addresses. Though a wildcard at the end of IP Address-type Base 357 Addresses would make more sense, support for IP Address-type Base 358 Addresses is OPTIONAL. The wildcard signifies the applicability of 359 the associated Metadata value to all Base Addresses which match the 360 address suffix. 362 The following two Base Addresses condense the previous example by 363 allowing all acme.com DNS addresses: 365 baseaddr_id: 1 366 baseaddr: *.acme.com 367 metadata_id: 1 369 baseaddr_id: 2 370 baseaddr: 10.10.10.10/meemeep 371 metadata_id: 1 373 Note: There is no explicit enforcement that Base Addresses associated 374 with a given piece of Metadata not overlap, however, for performance 375 reasons, Base Addresses associated with a given piece of Metadata 376 SHOULD NOT be allowed to overlap. 378 2.3. Agent Table 380 The Agent object contains basic information for authenticating 381 entities which require access to Metadata. The example shown 382 contains a primary key index, a string containing the username, an 383 OPTIONAL string containing the password (possibly hashed or 384 encrypted), a boolean value for differentiating between full read/ 385 write access (e.g., for uCDNs) and read only access (e.g., for 386 dCDNs), and a foreign key reference to the Domain to which this Agent 387 is associated. A uniqueness constraint is imposed on username/ 388 domain_id pairs to prevent duplicate Agent entries for a given 389 Domain. 391 CREATE TABLE "agent" ("agent_id" serial primary key, 392 "username" character varying(255) NOT NULL, 393 "password" character varying(255), 394 "read_only" boolean DEFAULT false NOT NULL, 395 "domain_id" integer NOT NULL); 396 CREATE UNIQUE INDEX index_agent ON agent (username, domain_id); 398 Agent Table Definition 400 Note: The password field is included to support the HTTP 401 authentication described in the API sections, however, if alternate 402 authentication schemes are used, the password may not be necessary. 404 The Agent objects manage Metadata access rights. The Agent 405 functionality as described attempts to address two issues: 407 o security concerns: where unauthorized injection or deletion of 408 Metadata may alter the functionality of a content service and MUST 409 be prevented, as described in the Security Considerations section, 410 and 412 o customization requirements: where retrieval of certain metadata 413 may require different responses depending on the Agent who is 414 accessing the Metadata (e.g., with multiple and/or cascaded 415 dCDNs). 417 Note: Though both of the above issues could be addressed through 418 means outside of the MI, or through a means common to all of the CDNI 419 interfaces, the Agent serves the purpose of addressing these needs 420 within the context of the MI, in lieu of a consensus alternative and 421 as per the CDNI framework document [I-D.davie-cdni-framework]. 423 The example Agents shown below represent a uCDN Agent with write 424 privileges and two dCDN Agents with read-only permissions: 426 agent_id: 1 427 username: ucdn 428 password: xxx 429 read_only: false 430 domain_id: 1 432 agent_id: 2 433 username: dcdn1 434 password: yyy 435 read_only: true 436 domain_id: 1 438 agent_id: 3 439 username: dcdn2 440 password: zzz 441 read_only: true 442 domain_id: 1 444 2.4. Metadata Table 446 The Metadata object contains the actual individual pieces of metadata 447 for the site being described. The example shown contains a primary 448 key index, a string containing the URI(s) to which the metadata 449 applies, a name/value pair of strings which represent the name and 450 value of the Metadata, respectively, as well as a boolean value 451 stating whether or not the given Metadata must be enforced. An 452 OPTIONAL priority value is included for creating order lists of 453 values for a given named Metadata. An OPTIONAL ttl value and timeout 454 field are included to support metadata invalidation. The table also 455 contains a foreign key reference to the Domain to which this Metadata 456 is associated and a foreign key reference to the Agent to whom this 457 Metadata is intended. A compound uniqueness constraint is also 458 applied to each uri/name/priority/domain_id/agent_id tuple to prevent 459 a given Metadata from being ambiguously applied multiple times to the 460 same URI in a given Domain for a given Agent. 462 CREATE TABLE "metadata" ("metadata_id" serial primary key, 463 "uri" character varying(4095) NOT NULL, 464 "name" character varying(511) NOT NULL, 465 "value" character varying(65535) NOT NULL, 466 "must_enforce" boolean DEFAULT true NOT NULL, 467 "priority" integer DEFAULT 0 NOT NULL, 468 "ttl" integer DEFAULT 0 NOT NULL, 469 "timeout" timestamp without time zone, 470 "domain_id" integer NOT NULL, 471 "agent_id" integer NOT NULL); 472 CREATE UNIQUE INDEX index_metadata ON metadata (uri, name, priority, 473 domain_id, agent_id); 475 The name/value pair is represented as simple opaque strings. The MI 476 does not require and understanding of the semantics or inherent 477 meaning of Metadata names or values to distribute the Metadata. 478 Though, each piece of Metadata MUST have a defined set of semantics 479 in order to be enforced, distributing the Metadata and determining 480 whether or not the Metadata is supported does not require any 481 understanding of the Metadata semantics, but rather, only an ability 482 to identify supported Metadata by their name is REQUIRED. Metadata 483 names SHOULD be properly defined and registered, and any implied 484 functionality SHOULD be agreed upon and documented. A base set of 485 CDNI Metadata is provided in the Metadata Definitions Section. 487 The intent of the must_enforce boolean is to identify Metadata that 488 MUST be enforced by all CDNs. If a CDN is unable to understand or is 489 unable to comply with the Metadata, it MUST NOT deliver the content 490 being requested. For dCDNs, the must_enforce flag defines how to 491 respond to MI and RRI requests when unknown or unsupported Metadata 492 is encountered. If Metadata is marked as must_enforce, then the dCDN 493 MUST NOT accept any RRI request if it is unable to enforce that piece 494 of Metadata (e.g., the named Metadata is not supported, the Metadata 495 value is invalid, or the Metadata value is not supported). If the MI 496 request resulted from a "recursive" RRI request, then the dCDN MUST 497 return an error to the uCDN. If the MI request resulted from an 498 "iterative" RRI request, then the dCDN MUST respond with a 403 499 Forbidden status code to the EU and report the failure to the uCDN. 501 In the case of cascaded CDN deployments, though a given CDN may not 502 be able to enforce a given piece of Metadata, other CDNs further down 503 stream may be able to enforce that Metadata. When a Metadata 504 rejection occurs, the CDN SHOULD still store the Metadata so that it 505 can be provided to other dCDNs. 507 The OPTIONAL priority value is provided to allow configuration of 508 ordered Metadata lists. When specifying multiple values for a given 509 named Metadata, each value MUST be specified with a unique priority 510 value. The explicit priority value enforces a deterministic ordering 511 across MI implementations. 513 The OPTIONAL ttl value is provided to allow configuration of a 514 Metadata TTLs. If the ttl is specified, it MUST be specified in 515 seconds and the timeout field SHOULD be populated by the local MI 516 processor and used internally, to prevent the need for clock 517 synchronization between MI processors. 519 The association of each Metadata to an Agent allows different Agents 520 to retrieve different Metadata values for a given URI in the given 521 Domain. This is intended to allow CDNs to separate upstream Metadata 522 from downstream Metadata (e.g., a uCDN content acquisition URL may 523 point to a CP origin, however, the content acquisition URL that the 524 dCDN retrieves from the uCDN may point at a surrogate in the uCDN; 525 likewise the content acquisition URLs for different dCDNs may point 526 at different surrogates in the uCDN). Though this information could 527 be hidden within a CDN's implementation, the security aspects related 528 to deterministically associating an authenticated Agent with the 529 proper metadata should be considered as part of the MI. Explicitly 530 representing this in the data model reduces ambiguity in Metadata 531 retrieval. 533 2.4.1. Hierarchical Metadata 535 In order to support hierarchical metadata, '/*' SHOULD be allowed as 536 the last part of the URI hierarchy, signifying the application of 537 this Metadata value to all URIs which match this URI prefix. If 538 multiple Metadata are defined with overlapping prefixes, the URI with 539 the longest prefix match MUST be used. The uniqueness constraint on 540 the uri/name/priority/domain_id tuple allows for unambiguous 541 resolution of Metadata priority. 543 Note: The wildcard is only supported at the end of the URI string to 544 provide a well-defined ordering for URI prefixes (i.e., longest 545 prefix matching). Use of generalized regular expression matching 546 requires ordering rules to ensure deterministically coherent results 547 across multiple MI implementations. It is assumed that the URI path 548 extensions (beyond the base paths provided in the Base Address) for 549 content will be the same across CDNs. Any CDN specific URL rewrites 550 MUST only affect the Base Address portion of the URL as defined in 551 the Base Address. 553 Note: It is often desirable to separate specific types of files which 554 may live in the same directory (e.g., .m3u8 vs .ts). Wildcard 555 support in the URI support for file extension differentiation, i.e., 556 '/*[.extension]', is OPTIONAL. 558 Given the following four Metadata objects, the value of color is 559 defined five times, for three different URIs, all within the same 560 Domain, but for different Agents: 562 metadata_id: 1 563 uri: /* 564 name: color 565 value: blue 566 must_enforce: false 567 priority: 0 568 ttl: 0 569 domain_id: 1 570 agent_id: 2 572 metadata_id: 2 573 uri: /* 574 name: color 575 value: gold 576 must_enforce: false 577 priority: 0 578 ttl: 0 579 domain_id: 1 580 agent_id: 1 582 metadata_id: 3 583 uri: /* 584 name: color 585 value: blue 586 must_enforce: false 587 priority: 1 588 ttl: 0 589 domain_id: 1 590 agent_id: 1 592 metadata_id: 4 593 uri: /grass/* 594 name: color 595 value: brown 596 must_enforce: false 597 priority: 0 598 ttl: 0 599 domain_id: 1 600 agent_id: 2 602 metadata_id: 5 603 uri: /grass/on/the/other/side/* 604 name: color 605 value: green 606 must_enforce: false 607 priority: 0 608 ttl: 0 609 domain_id: 1 610 agent_id: 2 612 The default value for the color metadata (signified by the all 613 encompassing URI "/*") is blue for the dCDN Agent and gold for the 614 uCDN Agent, though the default color may be blue for the uCDN as well 615 (as signified by the lower priority alternate color value). 616 Alternate colors are associated with requests from the dCDN Agent for 617 URIs that begin with "/grass". By default "/grass" has a color of 618 brown, except when requesting "/grass/on/the/other/side/" which is 619 green. 621 3. CDNI Metadata Bootstrapping 623 It is assumed that a well-known hostname to which MI requests should 624 be sent is configured through the CDNI bootstrap data. Bootstrap 625 information is sent through the CDNI CI, as described in the CDNI 626 requirements document [I-D.ietf-cdni-requirements]. The MI APIs 627 described herein are intended to be serviced by the MI running on 628 that host. 630 Domain and Agent configurations must exist prior to Metadata 631 creation/retrieval. Domains and Agents MAY be created as a part of 632 an off-line business negotiation process or as a part of the CDNI 633 bootstrapping process. Domain and Agent API descriptions are 634 included in Appendix A and Appendix B, respectively. When the Domain 635 and Agent APIs described are used, access to the APIs SHOULD be 636 secured using SSL with client authentication as described in the 637 Security Considerations section. 639 Two sets of Agent configurations are also REQUIRED: 641 o Upstream Agent Configuration: Agent credentials for all external 642 agents who require access to the local CDN MI, e.g. for dCDNs to 643 retrieve Metadata or for uCDNs to trigger Metadata. 645 o Downstream Agent Configuration: Agent credentials for the local 646 CDN to use when accessing uCDN MIs for retrieving Metadata or 647 triggering Metadata responses. Separate credentials may be 648 required for each uCDN and Domain combination from which content 649 redirections may originate. 651 4. CDNI Metadata Management 653 The Metadata creation, modification, retrieval and removal protocols 654 are defined in the following sections. All use a simple HTTP-based 655 approach. The protocol, in general, SHOULD be data format agnostic. 656 The examples shown herein use an XML representation for MI requests/ 657 responses, however, other well-defined representations (e.g., JSON) 658 are also acceptable. The examples shown illustrate functionality 659 required to support the data model described in Section 2, however, 660 any protocol which allows for the forced retrieval, invalidation, and 661 removal of Metadata could also be acceptable. 663 Metadata creation/update is distinguished from retrieval by the HTTP 664 method. Metadata creation/update MUST use the POST method. Metadata 665 retrieval MUST use the GET method. Metadata MUST be removed if the 666 value field is empty (i.e., updating the value to be an empty string 667 MUST force removal of the entire Metadata entry and all associated 668 Base Address entries). 670 A trigger API is also specified to initiate retrieval of Metadata. 671 The uCDN may issue a trigger to the dCDN to force (re)acquisition of 672 Metadata by the dCDN. The trigger API MUST use the POST method. 674 In addition to being secured using SSL with client authentication as 675 described in the Security Considerations section, the MI SHOULD also 676 employ an additional Agent authentication mechanism to filter 677 requests and results. In the examples shown below, HTTP basic 678 authentication is used for Agent authentication, though other methods 679 (e.g., HTTP digest authentication or URL hashing) could also be used. 681 4.1. Metadata API 683 The Metadata for a Domain is created/modified/retrieved using the 684 "/CDNI/MI/metadata" API. The metadata API REQUIRES a single query 685 string argument "domain" which specifies the name of the Domain to 686 which the Metadata being created/modified/retrieved belongs. Three 687 additional OPTIONAL arguments MAY also be provided when retrieving 688 metadata: "name" which specifies the name of the Metadata field to 689 create/modify/retrieve, "uri" which specifies the URI for which the 690 Metadata must apply, and/or "agent" which specifies the agent(s) to 691 which the Metadata is associated, as a comma separated list. The 692 "agent" option MUST only be allowed for agents with full read/write 693 permissions. 695 A simple XML representation of the information provided to the 696 metadata creation/update API or returned from the metadata retrieval 697 API is shown below: 699 700 701 702 703 704 705 706 707 708 ... 709 710 711 712 713 714 715 ... 716 717 718 ... 719 721 Metadata retrieval for a Domain may be triggered using the "/CDNI/MI/ 722 trigger" API. The trigger API provides the information required to 723 issue a metadata API retrieval request (i.e., the "domain", "name, 724 and "uri" query string arguments). The metadata API REQUIRES a 725 single query string argument "action" which specifies what type of 726 action is being triggered. 728 The following actions MUST be supported: 730 o refresh: The dCDN MUST retrieve and update all Metadata specified 731 in the trigger. 733 The following actions are considered OPTIONAL: 735 o preposition: The dCDN SHOULD retrieve and update all Metadata 736 specified in the trigger. 738 A simple XML representation of the information provided to the 739 trigger API is shown below: 741 742 743 744 745 746 747 748 ... 749 751 4.1.1. Metadata Creation 753 The following example creates three new Metadata "color" for the 754 "dcdn" Agent in the "acme" Domain, issued by the "ucdn" Agent to the 755 uCDN MI: 757 POST /CDNI/MI/metadata?domain=acme HTTP/1.1 758 Host: ucdn.mi.cdni.example.com 759 Accept: */* 760 Authorization: Basic dWNkbjp4eHg= 761 Content-Length: 1053 762 Content-Type: application/x-www-form-urlencoded 764 765 766 /grass/* 767 color 768 769 770 brown 771 0 772 773 774 false 775 776 dcdn 777 778 *.acme.com 779 780 781 782 /grass/on/the/other/side/* 783 color 784 785 786 green 787 0 788 789 790 true 791 792 dcdn 793 794 *.acme.com 795 796 797 798 /glasses/* 799 color 800 801 802 violet 803 0 804 805 806 false 807 808 ucdn 809 810 *.acme.com 811 812 813 815 4.1.2. Metadata Update 817 The following example updates the "color" Metadata for the 818 "/glasses/*" portion of the "acme" Domain and "dcdn" Agent, issued by 819 the "ucdn" Agent to the uCDN MI: 821 POST /CDNI/MI/metadata?domain=acme HTTP/1.1 822 Host: ucdn.mi.cdni.example.com 823 Accept: */* 824 Authorization: Basic dWNkbjp4eHg= 825 Content-Length: 361 826 Content-Type: application/x-www-form-urlencoded 828 829 830 /glasses/* 831 color 832 833 834 rose 835 0 836 837 838 violet 839 2 840 841 842 true 843 844 ucdn 845 846 *.acme.com 847 848 849 851 4.1.3. Metadata Refresh Trigger 853 The following example triggers the refresh of all "color" Metadata 854 for the "acme" Domain. The trigger is issued by the "ucdn" Agent to 855 the dCDN MI and is intended to force the "dcdn" Agent to retrieve 856 Metadata from the uCDN MI. 858 POST /CDNI/MI/trigger?action=refresh HTTP/1.1 859 Host: dcdn.mi.cdni.example.com 860 Accept: */* 861 Authorization: Basic dWNkbjp4eHg= 862 Content-Length: 155 863 Content-Type: application/x-www-form-urlencoded 865 866 867 ucdn.mi.cdni.example.com 868 acme 869 color 870 871 872 874 The following example triggers the refresh of all Metadata for the 875 URI "/grass/on/this/side", in the "acme" Domain. The trigger is 876 issued by the "ucdn" Agent to the dCDN MI and is intended to force 877 the "dcdn" Agent to retrieve Metadata from the uCDN MI. 879 POST /CDNI/MI/trigger?action=refresh HTTP/1.1 880 Host: dcdn.mi.cdni.example.com 881 Accept: */* 882 Authorization: Basic dWNkbjp4eHg= 883 Content-Length: 169 884 Content-Type: application/x-www-form-urlencoded 886 887 888 ucdn.mi.cdni.example.com 889 acme 890 891 /grass/on/this/side 892 893 895 4.1.4. Metadata Retrieval 897 The following example retrieves all "color" Metadata for the "acme" 898 Domain. The request was issued by the "dcdn" Agent to the uCDN MI, 899 and the results are filtered for the "dcdn" Agent: 901 GET /CDNI/MI/metadata?domain=acme&name=color HTTP/1.1 902 Host: ucdn.mi.cdni.example.com 903 Accept: */* 904 Authorization: Basic ZGNkbjp5eXk= 906 HTTP/1.1 200 OK 907 Content-Length: 714 908 Connection: close 909 Content-Type: text/xml 911 912 913 /grass/* 914 color 915 916 917 brown 918 0 919 920 921 false 922 923 dcdn 924 925 *.acme.com 926 927 928 929 /grass/on/the/other/side/* 930 color 931 932 933 green 934 0 935 936 937 true 938 939 dcdn 940 941 *.acme.com 942 943 944 946 The following example retrieves the Metadata for the URI "/grass/on/ 947 this/side" in the "acme" Domain. The request was issued by and the 948 results are filtered for the "dcdn" Agent: 950 GET /CDNI/MI/metadata?domain=acme&uri=/grass/on/this/side HTTP/1.1 951 Host: ucdn.mi.cdni.example.com 952 Accept: */* 953 Authorization: Basic ZGNkbjp5eXk= 955 HTTP/1.1 200 OK 956 Content-Length: 361 957 Connection: close 958 Content-Type: text/xml 960 961 962 /grass/* 963 color 964 965 966 brown 967 0 968 969 970 false 971 972 dcdn 973 974 *.acme.com 975 976 977 979 4.1.5. Metadata Removal 981 The following example removes the violet "color" Metadata value for 982 the URI "/glasses/*" and the "ucdn" Agent in the "acme" Domain by 983 setting the value to an empty string, issued by the "ucdn" Agent to 984 the uCDN MI: 986 POST /CDNI/MI/metadata?domain=acme HTTP/1.1 987 Host: ucdn.mi.cdni.example.com 988 Accept: */* 989 Authorization: Basic dWNkbjp4eHg= 990 Content-Length: 225 991 Content-Type: application/x-www-form-urlencoded 993 994 995 /glasses/* 996 color 997 998 999 1000 2 1001 1002 1003 ucdn 1004 1005 1007 4.1.6. Metadata Errors 1009 For any update, retrieval, or trigger request with malformed XML, the 1010 MI SHOULD respond with a 400 Bad Request status code. Ancillary 1011 unknown tags MAY be ignored. 1013 For any trigger requests with an unsupported action, the MI SHOULD 1014 respond with a 403 Forbidden status code. 1016 For any update or retrieval request for a uri/name/domain_id tuple 1017 which does not exist, the MI SHOULD respond with a 404 Not Found 1018 status code. 1020 For any request which lacks a valid Agent authorization, the MI MUST 1021 respond with a 401 Unauthorized status code. This includes Agents 1022 with valid credentials, but who are marked as read_only and have 1023 requested Metadata associated with an alternate Agent through the 1024 specification of an "agent" query string parameter. 1026 For any request which results in Metadata with an expired TTL, and 1027 for which an update cannot be retrieved from an upstream MI, the MI 1028 MUST respond to with a 500 Internal Server status code. 1030 4.1.7. Metadata Prepositioning 1032 The metadata creation/modification/removal APIs discussed above 1033 SHOULD only be used by uCDNs to manage Metadata in the local CDN. 1035 Though the metadata creation/modification/removal APIs could be used 1036 to preposition metadata in dCDNs, the trigger API allows the uCDN to 1037 force refresh of the dCDN Metadata without directly posting Metadata 1038 to the dCDN. This allows the dCDNs to manage retrieval of Metadata 1039 using lazy updates. 1041 dCDNs SHOULD NOT modify metadata dictated by a uCDN. dCDNs SHOULD 1042 only be assigned Agents with read_only access and SHOULD NOT have 1043 access to uCDN Domain or Agent APIs (restricted through the use of 1044 different SSL client authentication certificates, as described in the 1045 Security Considerations section). 1047 5. Metadata Definitions 1049 This section defines a base set of Metadata which SHOULD be supported 1050 by all CDNI implementations. 1052 5.1. Origin Server 1054 Content which is not pre-positioned must be acquired by the CDN from 1055 an origin server. The origin server Metadata specifies the base URL 1056 to which the content request URI may be appended in order to acquire 1057 the content. The origin server Metadata is defined as having the 1058 name "origin_server", with valid values containing a comma separated 1059 list of base URLs, and the must_enforce flag set to false: 1061 name: origin_server 1062 value: 1063 must_enforce: false 1065 In some cases, multiple non-load balanced origin servers may be 1066 available for content acquisition. The origin server Metadata SHOULD 1067 support an unprioritized comma separate list of base URL values. 1069 Note: The origin list Metadata is not a must_enforce, since, if the 1070 content cannot be acquired, there is no threat of unauthorized 1071 content distribution. Other Metadata or content pre-positioning may 1072 negate the need for origin server Metadata. 1074 5.2. Activation Time 1076 Content may be pre-positioned in anticipation of demand, however, the 1077 content license may have restrictions on delivery timeframe. The 1078 activation time Metadata specifies the first time at which the 1079 content may be delivered. The activation time Metadata is defined as 1080 having the name "activation_time", with valid timestamp values that 1081 MUST conform to RFC3339 [RFC3339], and the must_enforce flag set to 1082 true: 1084 name: activation_time 1085 value: 1086 must_enforce: true 1088 If the activation time Metadata is set and the current time is less 1089 than the specified activation time, the CDN MUST respond to requests 1090 for that content with a 403 Forbidden status code (or equivalent for 1091 the given non-HTTP request protocol). 1093 5.3. Deactivation Time 1095 Content may be pre-positioned in anticipation of demand, however, the 1096 content license may have restrictions on delivery timeframe. The 1097 deactivation time Metadata specifies the last time at which the 1098 content may be delivered. The deactivation time Metadata is defined 1099 as having the name "deactivation_time", with valid timestamp values 1100 that MUST conform to RFC3339 [RFC3339], and the must_enforce flag set 1101 to true: 1103 name: deactivation_time 1104 value: 1105 must_enforce: true 1107 If the deactivation time Metadata is set and the current time is 1108 greater than the specified activation time, the CDN MUST respond to 1109 requests for that content with a 403 Forbidden status code (or 1110 equivalent for the given non-HTTP request protocol). 1112 5.4. Administrative Disable 1114 It is sometimes necessary to temporarily disable the distribution of 1115 certain media (e.g., inappropriate content, irregular access 1116 patterns, etc.) within a set accessibility period (i.e., the 1117 activation/deactivation time range). The administrative disable 1118 Metadata instructs the CDN not to deliver the specified content under 1119 any circumstances. The administrative disable Metadata is defined as 1120 having the name "admin_disable", with two valid values "true" and 1121 "false", and the must_enforce flag set to true: 1123 name: admin_disable 1124 value: [true | false] 1125 must_enforce: true 1127 If the administrative disable Metadata is set to "true", the CDN MUST 1128 respond to requests for that content with a 403 Forbidden status code 1129 (or equivalent for the given non-HTTP request protocol). 1131 5.5. Delegation Depth 1133 CSPs may wish to prevent cascading CDNs to enforce licensing 1134 restrictions. The delegation depth Metadata instructs the CDN to 1135 only delegate requests for the specified content if the delegation 1136 depth is greater than zero. If the depth is less than or equal to 1137 zero, a uCDN should not delegate requests for the specified content 1138 to any dCDNs under any circumstances. When distributing the 1139 delegation depth Metadata the uCDN MUST decrement the value of 1140 delegation depth by at least one if the current value is greater than 1141 zero. The uCDN MAY choose not to decrement the value if the value is 1142 already less than or equal to zero. The uCDN MAY decrement by more 1143 than one in order to get to zero. The delegation depth Metadata is 1144 defined as having the name "delegate_depth", with an integer value 1145 and the must_enforce flag set to true: 1147 name: delegate_depth 1148 value: 1149 must_enforce: true 1151 If the delegation depth Metadata is less than or equal to 0, the CDN 1152 MUST either service the content requests itself or respond to 1153 requests for that content with a 504 Server Busy status code (or 1154 equivalent for the given non-HTTP request protocol). 1156 5.6. Footprint Filter 1158 CSPs often purchase rights to content which are only valid when 1159 accessed from certain locations (e.g., within a given country or 1160 through a given access network). The footprint filter Metadata 1161 provides a list of valid source IP subnets from which content 1162 requests may be accepted. The footprint filter Metadata is defined 1163 as having the name "footprint", with valid values containing a comma 1164 separated list of IP subnet definitions, and the must_enforce flag 1165 set to true: 1167 name: footprint 1168 value: [, ]... 1169 must_enforce: true 1171 If the footprint filter Metadata is set and the source address of a 1172 requesting client does not match any of the IP subnets listed, the 1173 CDN MUST respond to the content request with a 403 Forbidden status 1174 code (or equivalent for the given non-HTTP request protocol). 1176 5.7. HTTP Header Filter 1178 CSPs often desire the ability to filter requests based on the 1179 existence of specific HTTP header fields and values (e.g., User-Agent 1180 headers for device detection or custom headers inserted by client- 1181 side applications). The HTTP header filter Metadata provides a list 1182 of HTTP header names and values which MUST be verified. The HTTP 1183 header filter Metadata is defined as having the name 1184 "http_filter_headers", with valid values containing a comma separated 1185 list of HTTP header names and regular expression matching criteria 1186 definitions, and the must_enforce flag set to true: 1188 name: http_filter_headers 1189 value: : [, :]... 1190 must_enforce: true 1192 If the HTTP header filter Metadata is set and the HTTP headers of the 1193 content request do not match all of the filters specified, the CDN 1194 MUST respond to the content request with a 403 Forbidden status code 1195 (or equivalent for the given non-HTTP request protocol). 1197 5.8. HTTP Header Logging 1199 CSP client applications often include proprietary headers in their 1200 content requests (e.g., for user tracking or analaytics collection) 1201 which may be needed for business reasons (e.g., billing) or may be 1202 useful for debugging purposes. The HTTP header logging Metadata 1203 provides a list of HTTP header names whose values MUST be extracted 1204 and logged with the normal per-request information passed through the 1205 CDNI logging interface. The HTTP header logging Metadata is defined 1206 as having the name "http_logging_headers", with valid values 1207 containing a comma separated list of HTTP header names, and the 1208 must_enforce flag flag optionally set to true (depending on the 1209 application): 1211 name: http_logging_headers 1212 value: [, ]... 1213 must_enforce: [true | false] 1215 If the HTTP header logging Metadata is set and the content request 1216 contains HTTP headers which match any of the header names listed, the 1217 CDN MUST extract all matching headers and add them to the per-request 1218 log message. 1220 5.9. Protocol Filter 1222 Though content is typically only accessible using specific a protocol 1223 (e.g., HTTP, RTMP, or RTSP), a CSP may wish to explicitly allow/ 1224 disallow access to certain content for a given protocol. The 1225 protocol filter Metadata provides a list of allowed protocols via 1226 which content may be delivered. The protocol filter Metadata is 1227 defined as having the name "protocol", with valid values containing a 1228 comma separate list of protocol strings, and the must_enforce flag 1229 set to true: 1231 name: protocols 1232 value: [, ]... 1233 must_enforce: true 1235 If the protocol filter Metadata is set and the request protocol does 1236 not match any protocol in the list, the CDN MUST respond to the 1237 content request with a 403 Forbidden status code (or equivalent for 1238 the given non-HTTP request protocol). 1240 5.10. SSL Required 1242 CSPs which require delivery privacy may require dCDNs to support the 1243 same SSL configurations which were applied to the uCDN. The SSL 1244 required Metadata expresses the requirement to enforce SSL on content 1245 request connections and provides the necessary key and certificate 1246 information required for server authentication. The SSL required 1247 Metadata is defined as having the name "ssl_required", with valid 1248 values containing two URLs (comma separated) which point to the key 1249 and certificate, respectively, and the must_enforce flag set to true: 1251 name: ssl_required 1252 value: , 1253 must_enforce: true 1255 If the SSL required Metadata is set and the request is not received 1256 over an SSL channel, the CDN MUST respond to the content request with 1257 a 403 Forbidden status code (or equivalent for the given non-HTTP 1258 request protocol). 1260 Note: Retrieval of server key and certificate information SHOULD be 1261 performed in a secure manner. Retrieval could be implemented through 1262 the CDNI MI, however, this is not required. 1264 5.11. SSL Client Authentication Required 1266 CSPs which require client authentication may require dCDNs to support 1267 a SSL client authentication configuration which was applied to the 1268 uCDN. The SSL client authentication required Metadata expresses the 1269 requirement to enforce SSL client authentication on content requests 1270 and provides the necessary certificate authority (CA) information for 1271 authenticating clients. The SSL client authentication required 1272 Metadata is defined as having the name "ssl_auth_required", with 1273 valid values containing a single URL which points to the CA 1274 certificate to be used in client verification, and the must_enforce 1275 flag set to true: 1277 name: ssl_auth_required 1278 value: 1279 must_enforce: true 1281 If the SSL client authentication required Metadata is set and the 1282 client certificate cannot be verified using the CA certificate, the 1283 CDN MUST respond with a handshake_failure alert. 1285 5.12. URL Hash 1287 TBD. 1289 [Ed. Note: There are many proprietary URL hashing techniques in use 1290 today with varying timestamp formats, query string parameter names, 1291 hashing algorithm combinations, etc. A generic definition of URL 1292 hashing algorithm parameters, capable of supporting all algorithms 1293 would be best. An alternative of defining specific algorithms and 1294 assigning each and enumerated identifier would also work.] 1296 6. IANA Considerations 1298 This memo includes no request to IANA. 1300 7. Security Considerations 1302 There are a number of security concerns associated with the MI as 1303 Metadata may be used to influence CDNI request routing. Metadata may 1304 describe content acquisition parameters or content security 1305 restrictions. Altering Metadata or inhibiting Metadata discovery may 1306 impact content distribution. Some MI concerns include: 1308 o intercepting and discarding Metadata requests to prevent content 1309 acquisition may be used as a denial of service attack, 1311 o altering content acquisition Metadata to prevent content 1312 acquisition may be used as a denial of service attack, and 1314 o spoofing content security Metadata to disable delivery 1315 restrictions may be used to circumvent rights management. 1317 To combat these concerns, unauthorized access to the MI MUST be 1318 prevented. The use of SSL with client authentication SHOULD be used 1319 for all MI APIs. Deployments in controlled environments where 1320 physical security and IP address white-listing is employed MAY choose 1321 not to use SSL. Different client authentication certificates SHOULD 1322 be used to protect access to Domain and Agent APIs, as well as uCDN 1323 access to the Metadata API, differently from dCDN access to the 1324 Metadata API. Deployments where uCDNs and dCDNs are mutually trusted 1325 entities (e.g., when uCDNs and dCDNs are controlled by the same 1326 corporate organization) MAY choose to use a single client 1327 authentication certificate. 1329 8. Acknowledgements 1331 The authors would like to thank Daniel Biagini, Susan He, Francois Le 1332 Faucheur, Kent Leung, Ben Niven-Jenkins, Gilles Bertrand, and Raj 1333 Nair for their helpful reviews and comments. 1335 9. Appendix A: Domain API 1337 Domain creation, modification, retrieval, and removal protocols are 1338 defined in the following sections. All use a simple HTTP-based 1339 approach. The protocol, in general, SHOULD be data format agnostic. 1340 The examples shown herein use an XML representation for MI requests/ 1341 responses, however, other well-defined representations (e.g., JSON) 1342 are also acceptable. The examples shown illustrate the functionality 1343 required to support the data model described in Section 2, however, 1344 any protocol which allows for the creation, modification, retrieval, 1345 and removal of Domains could also be acceptable. 1347 Domain creation/update is distinguished from domain retrieval and 1348 removal by the HTTP method. Domain creation/update MUST use the POST 1349 method. Domain retrieval MUST use the GET method. Domain removal 1350 MUST use the DELETE method. 1352 All Agents and Metadata MUST be associated with a Domain. A Domain 1353 is created/modified/retrieved/removed using the "/CDNI/MI/domain" 1354 API. The domain API REQUIRES a single query string argument "domain" 1355 which specifies the name of the Domain to be created/modified/ 1356 retrieved. 1358 A simple XML representation of the information provided to the domain 1359 creation/update API or returned from the domain retrieval API is 1360 shown below: 1362 1363 1364 1365 1367 9.1. Domain Creation 1369 The following example creates a new Domain "acme": 1371 POST /CDNI/MI/domain?domain=acme HTTP/1.1 1372 Host: host.mi.cdni.example.com 1373 Accept: */* 1374 Content-Length: 81 1375 Content-Type: application/x-www-form-urlencoded 1377 1378 acme 1379 acme 1380 1382 9.2. Domain Update 1384 The following example updates the "acme" Domain: 1386 POST /CDNI/MI/domain?domain=acme HTTP/1.1 1387 Host: host.mi.cdni.example.com 1388 Accept: */* 1389 Content-Length: 209 1390 Content-Type: application/x-www-form-urlencoded 1392 1393 acme rocket-powered products, inc 1394 fine purveyors of high quality anvils, rubber bands, 1395 bird seed, and rocket-powered footwear. 1396 1398 9.3. Domain Retrieval 1400 The following example retrieves the updated "acme" Domain 1401 information: 1403 GET /CDNI/MI/domain?domain=acme HTTP/1.1 1404 Host: host.mi.cdni.example.com 1405 Accept: */* 1407 HTTP/1.1 200 OK 1408 Content-Length: 209 1409 Connection: close 1410 Content-Type: text/xml 1412 1413 acme rocket-powered products, inc 1414 fine purveyors of high quality anvils, rubber bands, 1415 bird seed, and rocket powered footwear 1416 1418 The MI MAY support bulk retrieval of Domains through the use of a 1419 comma separated list of Domain names in the domain query string 1420 parameter. 1422 9.4. Domain Removal 1424 The following example removes the "acme" Domain: 1426 DELETE /CDNI/MI/domain?domain=acme HTTP/1.1 1427 Host: host.mi.cdni.example.com 1428 Accept: */* 1430 9.5. Domain Errors 1432 Any update or retrieval request with malformed XML SHOULD respond 1433 with a 400 Bad Request status code. Ancillary unknown tags MAY be 1434 ignored. 1436 Any update or retrieval request for a Domain which does not exist 1437 SHOULD respond with a 404 Not Found status code. 1439 10. Appendix B: Agent API 1441 Agent creation, modification, retrieval, and removal protocols are 1442 defined in the following sections. All use a simple HTTP-based 1443 approach. The protocol, in general, SHOULD be data format agnostic. 1444 The examples shown herein use an XML representation for MI requests/ 1445 responses, however, other well-defined representations (e.g., JSON) 1446 are also acceptable. The examples shown illustrate the functionality 1447 required to support the data model described in Section 2, however, 1448 any protocol which allows for the creation, modification, retrieval, 1449 and removal of Agents could also be acceptable. 1451 Agent creation/update is distinguished from Agent retrieval and 1452 removal by the HTTP method. Agent creation/update MUST use the POST 1453 method. Agent retrieval MUST use the GET method. Agent removal MUST 1454 use the DELETE method and specify the Agent name(s) in the query 1455 string. 1457 All Metadata MUST be associated with an Agent. An Agent is created/ 1458 modified/retrieved/removed using the "/CDNI/MI/agent" API. The agent 1459 API REQUIRES a single query string argument "domain" which specifies 1460 the name of the Domain to which the Agent has access. In the case of 1461 DELETEs, the agent API also REQUIRES a query string argument "agent" 1462 which specifies the name(s) of the Agent(s) to remove, as a comma 1463 separated list. 1465 A simple XML representation of the information provided to the agent 1466 creation/update API or returned from the agent retrieval API is shown 1467 below: 1469 1470 1471 1472 1473 1474 1475 ... 1476 1478 10.1. Agent Creation 1480 The following example creates three new Agents "ucdn", "dcdn1", and 1481 "dcdn2" for the "acme" Domain: 1483 POST /CDNI/MI/agent?domain=acme HTTP/1.1 1484 Host: host.mi.cdni.example.com 1485 Accept: */* 1486 Content-Length: 362 1487 Content-Type: application/x-www-form-urlencoded 1489 1490 1491 ucdn 1492 xxx 1493 false 1494 1495 1496 dcdn1 1497 aaa 1498 false 1499 1500 1501 dcdn2 1502 bbb 1503 false 1504 1505 1507 10.2. Agent Update 1509 The following example updates the "dcdn1" and "dcdn2" Agents in the 1510 "acme" Domain: 1512 POST /CDNI/MI/agent?domain=acme HTTP/1.1 1513 Host: host.mi.cdni.example.com 1514 Accept: */* 1515 Content-Length: 245 1516 Content-Type: application/x-www-form-urlencoded 1518 1519 1520 dcdn1 1521 yyy 1522 true 1523 1524 1525 dcdn2 1526 zzz 1527 true 1528 1529 1531 10.3. Agent Retrieval 1533 The following example retrieves the updated Agent information for the 1534 "acme" Domain: 1536 GET /CDNI/MI/agent?domain=acme HTTP/1.1 1537 Host: host.mi.cdni.example.com 1538 Accept: */* 1540 HTTP/1.1 200 OK 1541 Content-Length: 360 1542 Connection: close 1543 Content-Type: text/xml 1545 1546 1547 ucdn 1548 xxx 1549 false 1550 1551 1552 dcdn1 1553 yyy 1554 true 1555 1556 1557 dcdn2 1558 zzz 1559 true 1560 1561 1563 10.4. Agent Removal 1565 The following example removes the "dcdn1" Agent from the "acme" 1566 Domain: 1568 DELETE /CDNI/MI/agent?domain=acme&agent=dcdn1 HTTP/1.1 1569 Host: host.mi.cdni.example.com 1570 Accept: */* 1572 10.5. Agent Errors 1574 Any update or retrieval request with malformed XML SHOULD respond 1575 with a 400 Bad Request status code. Ancillary unknown tags MAY be 1576 ignored. 1578 Any update or retrieval requests for an Agent which does not exist 1579 SHOULD respond with a 404 Not Found status code. 1581 11. References 1583 11.1. Normative References 1585 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1586 Requirement Levels", BCP 14, RFC 2119, March 1997. 1588 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1589 Timestamps", RFC 3339, July 2002. 1591 11.2. Informative References 1593 [I-D.davie-cdni-framework] 1594 Davie, B., Ed. and L. Peterson, Ed., "Framework for CDN 1595 Interconnection draft-davie-cdni-framework-01", 1596 October 2011. 1598 [I-D.ietf-cdni-requirements] 1599 Leung, K. and Y. Lee, "Content Distribution Network 1600 Interconnection (CDNI) Requirements 1601 draft-ietf-cdni-requirements-02", December 2011. 1603 [I-D.ietf-cdni-use-cases] 1604 Bertrand, G., Stephan, E., Watson, G., Burbridge, T., 1605 Eardley, P., and K. Ma, "Use Cases for Content Delivery 1606 Network Interconnection draft-ietf-cdni-use-cases-04", 1607 March 2012. 1609 Author's Address 1611 Kevin J. Ma 1612 Azuki Systems, Inc. 1613 43 Nagog Park 1614 Acton, MA 01720 1615 USA 1617 Phone: +1 978-844-5100 1618 Email: kevin.ma@azukisystems.com