CDNI Working Group Xiaomei Liu Internet Draft Lakshminarayanan Gunaseelan Intended status: Standards Track Xiaoyan He Expires: June 2012 Jincheng Li Huawei December 12, 2011 Content Distribution Network Interconnection (CDNI) Metadata Interface draft-liu-cdni-metadata-interface-00.txt Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html This Internet-Draft will expire on June 12, 2009. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with Liu & Guna Expires June 12, 2012 [Page 1] Internet-Draft CDNI Metadata Interface December 2011 respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Abstract The Metadata Interface is one of the core interfaces defined by the IETF Content Distribution Network Interconnection (CDNI) Working Group. The primary function of the CDNI Metadata Interface is to allow interconnected CDNs to communicate metadata in order to ensure content delivery and content acquisition. This document defines the metadata exchange protocol between an upstream CDN and a downstream CDN for the content delivery. It also defines metadata objects especially condition metadata object for CDNI. Table of Contents 1. Introduction ................................................ 3 1.1. Terminology ............................................ 3 2. CDNI Metadata Data Model .................................... 4 3. Metadata Extensibility ...................................... 5 4. Metadata Exchange Framework .................................. 5 4.1. Pre-positioned CDNI metadata acquisition ................ 5 4.2. Metadata delivery mechanism ............................. 6 4.3. Metadata encoding ...................................... 7 5. Metadata Objects Description ................................. 7 5.1. Domain Metadata Group Definition ........................ 7 5.1.1. Content origin object .............................. 7 5.1.2. Cache miss behavior Object ......................... 8 5.1.3. Cache control Object ............................... 9 5.1.4. Cache TTL Object ................................... 9 5.1.5. Downstream Cache TTL Object ........................ 9 5.1.6. Cache key Object .................................. 10 5.1.7. Access control Object ............................. 10 5.1.8. User authorization Object ......................... 11 5.1.9. Asset valid time window Object .................... 11 5.1.10. Rate limit Object ................................ 11 5.2. Condition Metadata Group Definition .................... 12 5.2.1. Condition Object .................................. 12 5.2.2. Condition Metadata Object ......................... 14 5.2.3. Examples ......................................... 14 5.3. Error Handling ........................................ 16 6. Examples ................................................... 17 7. Security Considerations .................................... 20 8. IANA Considerations ........................................ 20 Liu & Guna Expires June 12, 2012 [Page 2] Internet-Draft CDNI Metadata Interface December 2011 9. References ................................................. 20 9.1. Normative References................................... 20 9.2. Informative References ................................. 20 10. Acknowledgments ........................................... 21 1. Introduction The key functions of the CDNI metadata are for the upstream CDN (uCDN) to control the content distribution of the downstream CDN (dCDN). These functions of the metadata can be further divided into the following areas: O Content origin: it identifies where the content is located for a delivery service. The content origin specification must support multiple content origins for a delivery service with different redundancy schemes. When a content origin requires authentication, the authentication metadata should also be included. O Cache control policy: it controls the caching behavior of a downstream CDN. This includes whether to cache or not cache certain content, cache miss behavior (redirect or proxy through), cache key modification, cache TTL and downstream cache TTL. O Access control: it defines restriction for content delivery. This includes content availability time window, geo-blocking and user authorization. O Delivery policy: it further controls the content delivery such as the rate limit. This document focuses on enabling of the CDNI Metadata interface, which includes definition of the CDNI metadata exchanging protocol, CDNI metadata objects, especially the condition metadata, which provides great flexibility to refine the application scope of a metadata. 1.1. Terminology This document reuses the terminology defined in [I-D.draft-cdni problem-statement]. This document also uses the following terms: Delivery Domain: In CDN services, each delivery service is uniquely identified by a delivery domain. This is the hostname/CNAME accessed by end users for a delivery of content. This is usually the default metadata application scope for content distribution metadata. Liu & Guna Expires June 12, 2012 [Page 3] Internet-Draft CDNI Metadata Interface December 2011 Domain Metadata: The metadata whose application scope is a delivery domain, there is no any other additional condition to limit when or where to apply this metadata. Condition Metadata: The metadata which will only take effect when certain conditions represented by a list of condition objects are met. This kind of metadata has the precedence over the domain metadata. 2. CDNI Metadata Data Model The data model proposed in this document for CDNI is shown in the following Figure 1. It includes a top level object Delivery Domain, the metadata describing the Delivery Domain are further grouped into domain metadata group and condition metadata group. +-------------------+ 1 | Delivery Domain +-----------------+ +---------+---------+ | |1 | | |0...* |1 | +-----------+-----------+ +-------------+------------------------------+ | +-------------------+ | |+-------------------+ +-------------------+ | | |DomainMetadataList | | || Conditions | |ConditionMetadataList| | +---------+---------+ | |+---------+---------+ +---------+---------+ | | |1 | | |1 |1 | | | | | | | | | |1...* | | |1...* |1...* | | +---------+---------+ | |+---------+---------+ +---------+---------+ | | | MetadataObject | | || ConditionObject | | MetadataObject | | | +---------+---------+ | |+---------+---------+ +---------+---------+ | |Domain Metadata Group | | Condition Metadata Group | +-----------------------+ +--------------------------------------------+ Figure 1: CDNI Metadata Data Model A Domain metadata group is a list of metadata objects with the default metadata scope of a delivery domain. This draft proposes a list of such objects in section 5.1. A condition metadata group includes a list of rule match conditions, and a corresponding list of metadata that takes effect if the conditions are met. This is proposed to supports finer control of the downstream CDN beyond the default metadata scope. When multiple conditions are included in a condition metadata group, these conditions are used in a AND relation. When the same metadata is defined in both the domain metadata group and a condition Liu & Guna Expires June 12, 2012 [Page 4] Internet-Draft CDNI Metadata Interface December 2011 metadata group with matching conditions, the condition metadata takes precedence over the default metadata. In addition, multiple condition metadata groups can be used, in this case all these condition metadata groups are evaluated in the order received. If a metadata is defined in multiple condition metadata groups, and last condition metadata group with matching conditions takes effect. Rule matching operation can be performed on the following information: URI in a content request User agent header in a content request Referrer header in a content request Request arrival time Requesting client's information, e.g. IP address 3. Metadata Extensibility Metadata extensions to support proprietary data by the CDN providers should be allowed in the CDNI metadata interface. This document proposes that the name of such an extended metadata object should start with "X-". A downstream CDN that does not support the extended metadata should signal the unsupported metadata object in the response as described in section 5.3 error handling of this document. 4. Metadata Exchange Framework 4.1. Pre-positioned CDNI metadata acquisition In the CDNI framework, an upstream CDN directly contracts with content providers for the delivery of content. A downstream CDN delivers the content on behalf of the upstream CDN. An upstream CDN may utilize multiple downstream CDNs for the delivery of content. Taken this into account, the metadata for the delivery of a given content can be different for different downstream CDNs. Therefore, it is efficient for the content distribution metadata to be pushed from the uCDN to the dCDN. This document focuses on the pre-positioned CDNI metadata acquisition as defined in requirement draft [5] in this first version, i.e. metadata should be pushed from the upstream CDN to the Liu & Guna Expires June 12, 2012 [Page 5] Internet-Draft CDNI Metadata Interface December 2011 downstream CDN before the start of a delivery service, and will consider the Dynamic CDNI metadata acquisition in a future version. 4.2. Metadata delivery mechanism The HTTP web service model is used for the metadata exchange through this document. The RESTful design is proposed for the management of metadata service. With a RESTful model, HTTP is used as the underline message transport protocol. Four HTTP methods are used for the metadata exchange: POST metadata creation GET metadata read PUT metadata update DELETE metadata delete In the RESTful design, a resource is identified by a URI. For the CDNI metadata interface, each downstream CDN exposes a metadata interface URL. For example, the metadata interface for the downstream CDN is: http(s)://CDNi.dCDN.com/metadata/resource Each resource created will be identified by a resource identifier. In the metadata interface, the resource identifier is the same as the delivery domain FQDN. For example, http://CDNi.dCDN.com/metadata/dCDN.cp1.com represents the URI that is used to access metadata for the delivery service with a delivery domain name of dCDN.cp1.com To summarize, the metadata interface has the following mappings of the RESTful web service design: Client ? is the upstream CDN Server -- is the downstream CDN Resource -- delivery domain metadata The downstream CDN provides a service access point to the upstream CDN. The metadata resource is considered to be located at the Liu & Guna Expires June 12, 2012 [Page 6] Internet-Draft CDNI Metadata Interface December 2011 downstream CDN. The upstream CDN uses the metadata interface to create/read/update/delete metadata resources identified by the URI. 4.3. Metadata encoding Metadata encoding must support parameter value pair, listed values as well as structure and hierarchical data types. JSON is proposed for the metadata encoding for its flexibility in supporting the above requirements. In the JSON encoded message body, the domain metadata group is encoded first and then the condition metadata group is encoded. 5. Metadata Objects Description 5.1. Domain Metadata Group Definition The definition of the domain metadata group is as follows: { "domainMetaDataList": [ metadataObject1, metadataObject2, ... metadataObjectn] } where the metadataObject is of one of the metadata object types defined later in section 5.1.1 to 5.1.10. The following metadata objects are defined as the mandatory metadata for the CDNI metadata interface. In order to support a list of metadata objects with different object types, each metadata object is identified by the metadataType field, which is the first field of the metadata object. 5.1.1. Content origin object Content origin object defines the content origin for a delivery service. { "metaDataType": "contentOrigin", "object": { "origins": [ Liu & Guna Expires June 12, 2012 [Page 7] Internet-Draft CDNI Metadata Interface December 2011 { "location": "LOCATION", "authentication": { "type": "TYPE", "username": "NAME", "password": "PASSWORD" } }, ], "redundancy": "OPTION" } } Where LOCATION is the FQDN of the origin server The embedded authentication object defines the authentication information for an origin server. If no authentication is required by an origin server, the authentication object is null using JSON notation. In the authentication object definition, TYPE is "basic"|"digest" for HTTP basic and HTTP digest authentication type NAME is the string representation of username parameter of the authentication object PASSWORD is the string representation of password parameter of the authentication type Content origin supports a list of origin servers. The redundancy scheme supported OPTIONs are: "allActive" if all origins are actively used "priority" for priority based failover with the origin listed in decreasing priority 5.1.2. Cache miss behavior Object This metadata defines the cache miss behavior of the CDN. The CDN can redirect the request to a different location or pass throuth the request to the content origin. { "metadataType": "cacheMissBehavior", Liu & Guna Expires June 12, 2012 [Page 8] Internet-Draft CDNI Metadata Interface December 2011 "object": { "cacheMiss": "OPTION", "URL": "value" } } where OPTION is "redirect" | "passThru". The URL field is only relevant if the option is redirect. 5.1.3. Cache control Object This metadata defines if cache is turned on or off by the CDN { "metadataType":"cacheControl", "object":{ "cache":"OPTION" } } where OPTION is "on" | "off". 5.1.4. Cache TTL Object This metadata controls how long content is stored in the CDN cache before the content freshness is revalidated. { "metadataType": "cacheTTL", "object": { "TTL": "value" } } where the value is a integer number of seconds. 5.1.5. Downstream Cache TTL Object This metadata controls how the browser cache the content via cache control header in an HTTP response from the CDN to the client { "metadataType": "downstreamCacheTTL", Liu & Guna Expires June 12, 2012 [Page 9] Internet-Draft CDNI Metadata Interface December 2011 "object": { "TTL": "value" } } where the value is a integer number of seconds. 5.1.6. Cache key Object By default, CDN caches content based on the entire URI. Cache key mask can be used to exclude portions of the URI for the generation of cache key. { "metadataType": "cacheKey", "object": { "key": "value" } } Where the value is a regex string. Here is an example: http://dCDN.example.com/movie?cid=abcde&user=xxx&token=yyy In this example, the "user" field of the query is removed from the cache key. The regex replacement can be used as: "s/(.*)user.*(token.*)/$1$2/" 5.1.7. Access control Object This metadata defines whether to allow or deny a content request { "metadataType": "accessControl", "object": , { "action": "OPTION" } } where OPTION is "allow" | "deny". Liu & Guna Expires June 12, 2012 [Page 10] Internet-Draft CDNI Metadata Interface December 2011 5.1.8. User authorization Object This metadata defines the user authorization information a content request. { "metadataType": "userAuthorization", "object": { "type": "TYPE", "algorithm": "ALGORITHM", "keyType": "KEYTYPE", "key": "value" } } where TYPE is "urlSigning" | "urlToken" ALGORITHM is "MD5" | "SHA1". KEYTYPE is "symmetric" | "asymmetric". value is the public key if the keyType is "asymmetric". 5.1.9. Asset valid time window Object This metadata defines the content distribution time window. The CDN will only delivery the content if the request is within the asset window. { "metadataType": "assetWindow", "object": { "start": "time", "end": "time" } } The time format is defined by HTTP 1.1. For example: Sun, 06 Nov 1994 08:49:37 GMT. 5.1.10. Rate limit Object This metadata defines the CDN distribution aggregate bandwidth limitation. Liu & Guna Expires June 12, 2012 [Page 11] Internet-Draft CDNI Metadata Interface December 2011 { "metadataType": "rateLimit", "object": { "limit": "value" } } Where value is in the unit of kbps. 5.2. Condition Metadata Group Definition The condition metadata group encapsulation is as follows: { "conditions", [ conditionObject1, conditionObject2, ..., conditionObjectN ], "ConditionMetadataList", [ metadataObject1, metadataObject2, ... metadataObjectn ] } Where the conditionObject is of one of the metadata condition object type defined in section 5.2.1 and metadataObject is of one of the metadata object type defined in section 5.1.1 to section 5.1.10. Multiple condition metadata groups can exist in the metadata interface and an example can be found in the example of section 6. 5.2.1. Condition Object The condition object is designed to support generic rule setting and scope limiting. It includes match field, match type and match value. The match field is evaluated against the match value based on the match type. The result is either a True or a False. Several Liu & Guna Expires June 12, 2012 [Page 12] Internet-Draft CDNI Metadata Interface December 2011 mandatory match fields, match types are defined in this version of the spec with future extensibility. The condition object is defined as { "condition": { "matchField": "FIELDS", "matchType": "MATCHTYPES", "matchValue": { "valueType": "VALUETYPE", "value": [ valueObjects ] } } } where the FIELDS can be "URI" | "userAgent" | "client" | "referrerURL" where the MATCHTYPES can be "ifMatch" | "ifNoneMatch" | "ifRange". for the "ifMatch" match type, the result is true if any of the value in the value list is a match. for the "ifNoneMatch" match type, the result is true if none of the value in the value list is a match for the "ifRange" match type, the value list can only have two objects that defines the range. The result is true if the field is in the range defined by the value list. where the VALUETYPE can be "regex" | "ip" | "region" | "number" | "time". For the "regex" value type, the value object is a string representing regex For the "ip" value type, the value object is a list of IP object defined as: { "ipAddress": "value", "subnetMask": "value"} where the value is the dotted notation of ip address For the "region value type", the value object is the region defined as: Liu & Guna Expires June 12, 2012 [Page 13] Internet-Draft CDNI Metadata Interface December 2011 { "country": "string", "region", "string" } the country code is defined in ISO-3166-1 the region code is defined in ISO-3166-2 For the "number" value type, the value object is numeric values For the "time" value type, the value object is defined by the HTTP1.1 5.2.2. Condition Metadata Object The metadataObject is of one of the metadata object type defined in section 5.1.1 to section 5.1.10. 5.2.3. Examples Here are a few examples of the conditions: Example 1: Set the cache TTL to 1 day for content whose URI has */movie/* in the path. { "Conditions": [ { "condition": { "matchField": "URI", "matchType": "ifMatch", "matchValue": { "valueType": "regex", "value": [ "/movie/" ] } } } ], "metadataList": [ { Liu & Guna Expires June 12, 2012 [Page 14] Internet-Draft CDNI Metadata Interface December 2011 "metadatatype": "cacheTTL", "object": { "TTL": "3600" } } ] } Example 2: Restrict the content delivery to only California, United States: { "conditions": [ { "condition": { "matchField": "client", "matchType": "ifNoneMatch", "matchValue": { "valueType": "region", "value": [ { "country": "US", "region": "california" } ] } } } ], "metadataList": [ { "metadatatype": "accessControl", "object": { "action": "deny" } } ] } Liu & Guna Expires June 12, 2012 [Page 15] Internet-Draft CDNI Metadata Interface December 2011 5.3. Error Handling The metadata interface uses HTTP status to reflect the success or failure of the operation. In addition, if there is an error in the operation, detailed information is provided in the response body with JSON encoding. In the failure condition, the detailed error information only includes the first error encountered, such as the JSON encoding of the problem matching condition or metadata. Note that the unsupported extended metadata will be included also. To simplify the design, there is no notion of partial success. Only when all metadata operations are accepted will the success result be returned. The following HTTP status code is used: POST operation: 201 Created (Success) 400 Bad request (Failure) GET operation: 200 Success 404 Not found (resource not found) PUT operation: 200 Success 400 Bad request (Failure) 404 Not found (resource not found) DELETE operation: 200 Success 404 Not found (resource not found) When the HTTP response code is 400 (Bad request), metadata interface specific error code used in the JSON are: 1000 Unknown metadata type Liu & Guna Expires June 12, 2012 [Page 16] Internet-Draft CDNI Metadata Interface December 2011 1001 Invalid metadata value 1002 Unknown condition type 1003 Invalid condition value Example error encodings in responses body are: { "error code": "1000", metadataObject} where the metadataObject is the first metadata object that has the error condition { "error code": "1003", conditionObject} where condition is the first condition that has the error 6. Examples This section provides an example of metadata interface messages. This example creates one domain metadata group (origin, cacheTTL, assetWindow, cacheMissBehavior,caheKey) and two condition metadata groups for the delivery domain of dCDN.cp1.com. In the first condition metadata group, if the content URL path include movie, the cacheTTL metadata is reset. In the second condition metadata group, if the content URL path includes private, the cache is turned off using cacheControl metadata. POST /metadata/dCDN.cp1.com HTTP/1.1 Host: CDNi.dCDN.com Accept: application/jsonrequest Content-Length: 500 Content-Type: application/jsonrequest [ { "domainMetadataList" [ { "metaDataType": "contentOrigin", "object": { "origins": [ Liu & Guna Expires June 12, 2012 [Page 17] Internet-Draft CDNI Metadata Interface December 2011 { "location": "origin1.example.com", "authentication": { "type": "basic", "username": "abc", "password": "123" } }, { "location": "origin2.example.com", "authentication": null } ], "redundancy": "priority" } }, { "metadataType": "cacheMissBehavior", "object": { "cacheMiss": "passThru", "URL": "" } }, { "metadataType": "assetWindow", "object": { "start": "Sun, 04 Dec 2011 08:00:00 GMT", "end": "Sun, 04 Mar 2012 08:00:00 GMT" } }, { "metadataType": "cacheTTL", "object": { "TTL": "3600" } }, { "metadataType": "cacheKey", "object": { "key": "s/(.*)user.*(token.*)/$1$2/" } Liu & Guna Expires June 12, 2012 [Page 18] Internet-Draft CDNI Metadata Interface December 2011 } ] }, { "Conditions": [ { "condition": { "matchField": "URI", "matchType": "ifMatch", "matchValue": { "valueType": "regex", "value": [ "/movie/" ] } } } ], "metadataList": [ { "metadatatype": "cacheTTL", "object": { "TTL": "86400" } } ] } { "Conditions": [ { "condition": { "matchField": "URI", "matchType": "ifMatch", "matchValue": { "valueType": "regex", "value": [ "/private/" ] } } Liu & Guna Expires June 12, 2012 [Page 19] Internet-Draft CDNI Metadata Interface December 2011 } ], "metadataList": [ { "metadatatype": "cacheControl", "object":{ "cache":"off" } } ] } ] Here is the HTTP response: HTTP/1.1 200 OK 7. Security Considerations The security concerns on CDNI metadata interface may be addressed via upstream CDN and downstream CDN exchanging metadata in a secured fashion. This can be via VPN, transport security via SSL etc. The authentication can be based on username/password or SSL certificate. 8. IANA Considerations This memo includes no request to IANA. 9. References 9.1. Normative References 9.2. Informative References [1] Davie and Peterson, "Framework for CDN Interconnection", draft-davie-cdni-framework-01 (work in progress), July 2011. [2] Niven-Jenkins, Faucheur and Bitar, "Content Distribution Network Interconnection (CDNI) Problem Statement", draft-ietf- cdni-problem-statement-01 (work in progress), September 2011. [3] Caulfield and Leung, Ledraft-caulfield-cdni-metadata-core-00 "Content Distribution Network Interconnect (CDNI) Core Metadata", October 2011. Liu & Guna Expires June 12, 2012 [Page 20] Internet-Draft CDNI Metadata Interface December 2011 [4] Stephen, Bertrand, Fieau and Pages, "metadata for CDNs Interconnection" draft-stephan-cdni-usecases-metadata-00, " October, 2011 [5] [I-D.draft-cdni-requirements] "Content Distribution Network Interconnection (CDNI) Requirements", Kent Leung, Yiu Lee, 9-Sep-11, . [6] RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1, June 1999 10. Acknowledgments This document was prepared using 2-Word-v2.0.template.dot. Liu & Guna Expires June 12, 2012 [Page 21] Internet-Draft CDNI Metadata Interface December 2011 Authors' Addresses Xiaomei Liu 2330 Central Expressway Santa Clara, CA 95050 USA Phone: +1 408 330 5198 Email: xiaomei.sc.liu@huawei.com Lakshminarayanan Gunaseelan 2330 Central Expressway Santa Clara, CA 95050 USA Phone: +1 408 330 5088 Email: guna@huawei.com Xiaoyan He Huawei B2, Huawei Industrial Base, 518129 China Email: hexiaoyan@huawei.com Jincheng Li Huawei B2, Huawei Industrial Base, 518129 China Email: lijincheng@huawei.com Liu & Guna Expires June 12, 2012 [Page 22]