Content Delivery Network Interconnection (CDNI) Edge Control Metadata

Introduction Content Delivery Networks (CDN) and Open Caching systems typically require a set of configuration metadata to provide directives for processing responses downstream (at the edge and in the user agent). This document defines CDNI Generic Metadata ( see Section 4.1.7 ) objects to meet those requirements, defining edge processing rules such as Cross-Origin Resource Sharing (CORS) handling, response compression, and client connection failures. The objects defined in this document address the delivery of publicly accessible resources by a CDN. Cross-origin delivery of resources that require credentials, in the sense of a request whose credentials mode is "include" in Section 3.2.5 of , is outside their scope: this specification does not define how a dCDN is to combine the CORS protocol with the authentication and authorization mechanisms of the CDNI Metadata Interface. Deployments that need cross-origin delivery of authenticated resources require behaviour that cannot be expressed by configuration alone. These objects are deployed through the CDNI Metadata Interface as specified in This specification introduces no additional deployment steps beyond those already required to distribute CDNI Metadata between a uCDN and a dCDN.

Terminology The following terms are used throughout this document:

CDN: Content Delivery Network
CORS: Cross Origin Resource Sharing
FQDN: Fully Qualified Domain Name
Origin header: Request header as defined in Section 7 of
Synthetic response: A response generated by the dCDN itself, without contacting the uCDN, using the configuration conveyed by the MI objects defined in this document.
UA: User Agent

Additionally, this document reuses the terminology defined in , and . Specifically, we use the following CDNI acronyms:

MI: Metadata Interface (see )
uCDN: Upstream CDN (see )
dCDN: Downstream CDN (see )

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

MI.CrossoriginPolicy

Overview When a user interacts with a Content Provider (CP) application, such as a streaming app on a smartphone or a web browser, the device initiates a request for content distributed by a CDN. This process typically begins with an initial request to the CP's URL using a Fully Qualified Domain Name (FQDN) within the CP's own domain. Depending on the CDN architecture, the response may trigger an HTTP redirection to a different FQDN, usually one belonging to the CDN's domain. While this transition is necessary for delivery, many User Agents apply strict 'same-origin' security restrictions to these network requests, which can block the content unless specific access rules are defined. Cross-origin resource sharing (CORS) is a protocol that allows a web application running in a User Agent (UA) to access restricted resources from a server on a domain different from the domain that served the original request. It is defined by the Web Hypertext Application Technology Working Group (WHATWG) Fetch Living Standard . Unlike most web security mechanisms, the enforcement point of the CORS protocol is the UA rather than the server. The CORS response headers are instructions to a conforming UA about whether to expose a response to a script running in a given origin, and they have no effect on a client that does not implement CORS. In this document, where the dCDN is said not to include the CORS response headers, the dCDN still serves the response. CORS is based on HTTP request and response headers, which must be managed appropriately. For clarification, it is important to note that the concept of an Origin in the CDN context is different from that in the CORS context. The former indicates the source from where the CDN acquires content (the Origin Server), while the latter identifies the security context (scheme, host, and port) of the web application making the request as defined in Section 3.2 To permit shared cross-origin network requests, the CORS protocol defines a set of request and response headers that allow servers and UAs to selectively relax the same-origin policy and grant access to these restricted resources. At least, two situations can occur when one or more CDNs are involved in processing these requests:

CDNs forward the User-Agent (UA) request headers to the CP servers, and they forward the response headers generated back to the UA.
CDNs include logic to dynamically generate the required response headers based on the UA request without contacting the CP servers.

The dynamic generation of CORS headers is typical in delegated HTTP request processing and avoids forwarding CORS headers to the upstream CDN (uCDN), thereby reducing the load between downstream CDN (dCDN) and uCDN when the content to be delivered is already cached in the dCDN. Also consider that there are two types of requests involved in the CORS protocol as defined in Section 3.2.2 of :

A CORS request is any HTTP request that includes an Origin header, as defined in Section 7
A CORS preflight request is a CORS request to check whether the CORS protocol is understood by the delivery server, and to ensure that it includes valid CORS response headers. It uses the OPTIONS method along with some other specific request headers to indicate which method and headers will be used in a future CORS request to the same resource.

The CDN Interconnection (CDNI) metadata model requires extensions to permit a uCDN to declare how a dCDN evaluates and dynamically generates the necessary CORS response headers, based on the uCDN's configuration, avoiding the forwarding of CORS requests and/or preflight requests to the uCDN. Using this GenericMetadata object permits the uCDN to configure the following dCDN behaviors:

Set a default value for CORS response headers independent of the value of the Origin request header.
Match the value of the Origin request header with a list of valid values. If it is successful, the dCDN will inject the appropriate CORS response headers.
Set a list of custom response headers that are allowed to be exposed to the client using CORS response headers.
Dynamically generate CORS response headers to CORS preflight requests including custom header validation, expose headers, and methods.
Support credentials validation within CORS.

dCDN Required behavior The dCDN MUST implement the following behavior as determined by the GenericMetadata object MI.CrossoriginPolicy:

Validation of the Origin request header - If MI.CrossoriginPolicy defines a list of domains to validate against, and the Origin request header does not match any of them, the CORS response headers MUST NOT be included in the dCDN response. UA compliance with Section 3.2 of with "same-origin" restrictions will prevent access to the resource. Returning CORS response headers in that case would have no effect: the CORS check in Section 4.9 of fails on the absence of Access-Control-Allow-Origin, so no other CORS response header is consulted, and including one that the User Agent accepts would grant access to an origin the allow-list excludes. Returning an error response to a request whose Origin request header does not match is outside the scope of this document: the CORS protocol is enforced by the User Agent, and a response status that depended on the Origin request header would be a form of request filtering rather than CORS. Access control of that kind is expressed in the CDNI Metadata Interface by the access control objects defined in .
Wildcard usage - If the Origin request header is valid, depending on the configuration, the value of the CORS response header to include in the response will be the same as the Origin request header, or a wildcard.
The uCDN is able to configure a list of default values for CORS response headers in MI.CrossoriginPolicy Generic Metadata object that the dCDN MUST add if present independent of the value of the Origin request header.
If the UA is expected to use CORS preflight requests, the uCDN can also configure the dCDN to dynamically generate synthetic responses to HTTP OPTIONS method requests as defined in Section 3.2.2 of

When MI.CrossoriginPolicy includes an MI.AccessControlAllowOrigin object with an allow-list property, the CORS response headers that the dCDN includes in a response depend on the Origin request header and therefore differ between requests for the same target URI. In that case:

The dCDN MUST NOT store the CORS response headers it generates as part of the cached representation. The dCDN generates them for each response from the configuration in effect.
The dCDN MUST include in the Vary header field of the response the name of every CORS request header field that was present in the request, in addition to any field names already present in a Vary header field received from the uCDN. For a response other than a response to a CORS preflight request this is the Origin header field.

Without the Vary header field, a shared cache between the dCDN and the User Agent, or the User Agent's own HTTP cache, can reuse a stored response together with the CORS response headers that were generated for a different Origin request header (Section 4.1 of ). When MI.CrossoriginPolicy does not define an allow-list, the CORS response headers do not depend on the Origin request header and this requirement does not apply. When an uCDN configures one or more of the expose-headers, allow-methods, allow-headers, allow-credentials and max-age properties as a parameter of MI.CrossoriginPolicy, the dCDN MUST generate synthetic responses to any CORS preflight request without contacting the uCDN servers. In this case the dCDN will add the corresponding CORS response headers to every non-empty parameter. If none of those parameters are set in the configuration, the dCDN MUST forward every CORS preflight request (OPTIONS method) to the uCDN servers and process their responses before responding to the UAs. This requirement does not override any protection a dCDN applies against excessive request rates. Responses to the OPTIONS method are not cacheable (Section 9.3.7 of ). The outcome of a CORS preflight request is retained by the User Agent in the CORS-preflight cache defined in Section 4.8 of , whose entries include the byte-serialized origin of the request and expire according to the max-age property. The Vary header field therefore plays no role in the reuse of preflight results.

MI.CrossoriginPolicy MI.CrossoriginPolicy is a GenericMetadata object that allows configuring dynamically generated CORS headers. Property: allow-origin

Description: Determines, for a CORS request, whether the dCDN includes CORS response headers in the response and what value it places in the Access-Control-Allow-Origin response header.
Type: Object MI.AccessControlAllowOrigin
Mandatory-to-Specify: Yes

Property: expose-headers

Description: A list of header names the dCDN will include in the Access-Control-Expose-Headers response header of a CORS response other than a response to a preflight request.
Type: Array of Field Names as defined in Section 5.1 of
Mandatory-to-Specify: No. If not specified, the default behavior is not to add the header in the response.

Property: allow-methods

Description: A list of request method tokens the dCDN will include in the Access-Control-Allow-Methods response header to a CORS preflight request.
Type: Array of method tokens as defined in Section 9.1 of
Mandatory-to-Specify: No. If not specified, the default behavior is not to add the header in the response.

Property: allow-headers

Description: A list of header names the dCDN will include in the Access-Control-Allow-Headers response header to a CORS preflight request.
Type: Array of Field Names as defined in Section 5.1 of
Mandatory-to-Specify: No. If not specified, the default behavior is not to add the header in the response.

Property: allow-credentials

Description: The value the dCDN will include in the Access-Control-Allow-Credentials response header of a CORS response. Within the scope of this document as described in Introduction the expected value is "false", by which a uCDN states explicitly that the dCDN is not to grant credentialed cross-origin access to the resource. Cross-origin delivery of resources that require credentials is outside the scope of this document, which therefore does not define the use of the value "true".
Type: Boolean. Section 4.9 of assigns meaning only to the value "true": the CORS check fails for a request whose credentials mode is "include" unless the header is present with that value. A value of "false" therefore has the same effect at the User Agent as the absence of the header, and is used by a uCDN that wants the policy stated explicitly in the response.
Mandatory-to-Specify: No. If not specified, the default behavior is not to add the header in the response.

Property: max-age

Description: The value the dCDN will include in the Access-Control-Max-Age response header to a CORS preflight request, in seconds. (See Section 3.2.3 of ).
Type: Integer
Mandatory-to-Specify: No. If not specified, the default behavior is not to add the header in the response.

Property: no-origin-response-headers

Description: In the case of a request that has no Origin field, return this set of headers with the response. Content providers need to deal with devices or applications that, even not sending the Origin header in the request, are expecting to receive the Access-Control-* headers in the response. The name property of each MI.AccessControlHeader object MUST be the name of a CORS response header, that is, a header field name beginning with "Access-Control-". A dCDN MUST ignore any entry whose name does not meet that condition, and MUST NOT use this property to replace a header field it generates from the other properties of MI.CrossoriginPolicy.
Type: Array of MI.AccessControlHeader objects.
Mandatory-to-Specify: No. If not specified, the default behavior is not to add any CORS response headers.

Property: preflight-only

Description: If this flag is set to "true" the dCDN will only generate synthetic responses to OPTIONS requests with proper CORS response headers.
Type: Boolean
Mandatory-to-Specify: No. The default is "false", so CORS response headers logic will be executed for all HTTP methods.

MI.AccessControlAllowOrigin The MI.AccessControlAllowOrigin object has the following properties: Property: allow-list

Description: List of valid expressions that will be used to match the request Origin header. The Origin header is an HTTP extension. Its value is a variation of the Referer header that does not reveal a path in some specific requests and is used for cross-origin requests. Permitted values for the Origin header are of the form schema://host[:port] as defined in Sections 3.1, 3.2.2, and 3.2.3 of
Type: Array of objects, each with a single property "pattern" whose value is a String. The pattern is matched against the serialized origin of the request, as defined in Section 3.1 of , which has the form scheme://host[:port]. The wildcard "*" matches any sequence of characters within a single component of the origin and MUST NOT be used to match across the "://" or ":" delimiters. All other characters are matched literally. The comparison is byte-for-byte and no case folding is applied.
Mandatory-to-Specify: Yes

Property: wildcard-return

Description: If set to "true", the dCDN will include a wildcard (*) in the Access-Control-Allow-Origin response header. If "false", the dCDN MUST reflect the value of the Origin request header in the Access-Control-Allow-Origin response header. wildcard-return and allow-credentials MUST NOT both be set to "true": the CORS check in Section 4.9 of fails for a request whose credentials mode is "include" when the value of Access-Control-Allow-Origin is "*".
Type: Boolean
Mandatory-to-Specify: Yes

MI.AccessControlHeader The MI.AccessControlHeader object has the following properties: Property: name

Description: The name of the HTTP header.
Type: String
Mandatory-to-Specify: Yes

Property: value

Description: The value of the named HTTP header.
Type: String. A static string.
Mandatory-to-Specify: Yes

Examples The informative examples below demonstrate how to configure response headers dynamically for CORS validation. The following shows a CORS validation configuration that does not include CORS preflight requests. The dCDN verifies the Origin request header against the allow-list and, for a request that matches, returns the wildcard value rather than the requesting origin; a request that does not match receives no CORS response headers. See the description of wildcard-return in MI.AccessControlAllowOrigin for when this is appropriate and for its dependency on the Vary header field:

The following shows a configuration to the dCDN to generate synthetic responses to CORS requests and CORS preflight requests:

MI.AllowCompress Downstream CDNs often have the ability to compress HTTP response bodies in cases where the client has declared that it can accept compressed responses (via an Accept-Encoding header), but the source/origin has returned an uncompressed response. The specific compression algorithm used by the dCDN is negotiated by the client's Accept-Encoding header according to Section 12.5.3 (including "q=" preferences) and the compression capabilities available on the dCDN. In addition, HeaderTransform allows the uCDN to normalize, or modify, the Accept-Encoding header to allow for fine-grain control over the selection of the compression algorithm (e.g., gzip, compress, deflate, br, etc.). MI.AllowCompress is a GenericMetadata object that allows the dCDN to compress content before sending it to the client. Property: allow-compress

Description: If set to "true", the dCDN SHOULD try to compress the response to the client based on the Accept-Encoding request header and its available capabilities. Following the fallback defined in Section 12.5.3 , if a non-empty Accept-Encoding header field is present in the request and none of the representations available to the dCDN has a content coding listed as acceptable, the dCDN SHOULD send the response without any content coding unless the identity coding is indicated as unacceptable.
Type: Boolean
Mandatory-to-Specify: No. The default is "false".

Examples The following shows an example of the usage of MI.AllowCompress:

MI.ClientConnectionControl Configuration metadata is required to define how connections to a client are maintained by a dCDN. In some use cases, like video streaming or other critical object delivery, UA applications' connection to the cache server must be managed to ensure the best possible user experience. This metadata allows a uCDN to accommodate device-specific constraints and performance optimization. A dCDN can also benefit from this configuration metadata to meet its security and resource consumption requirements. MI.ClientConnectionControl is a GenericMetadata object that specifies how the uCDN wants the dCDN manages its connections to UAs. Property: connection-keep-alive-time-ms

Description: Specifies the time, in milliseconds, to keep an idle connection open before trying to close it.
Type: Integer
Mandatory-to-Specify: No. When not specified, a default value selected by the dCDN will be used.

Examples The following shows how a keep-alive timeout of 3 seconds can be set for idle client connections to a dCDN:

A dCDN can retrieve the current value of any MI object defined in this document using the CDNI Metadata retrieval interface specified in Section 6.2 of . This provides a means to confirm what configuration is currently in effect. It is the responsibility of the dCDN to apply the received MI objects correctly. CDN operators can compare the retrieved configuration against observed behavior to detect misconfiguration or unexpected deviation between a uCDN and a dCDN. This document does not define additional error tracking or monitoring mechanisms beyond what already provides for the CDNI Metadata Interface. The configuration conveyed by these objects takes effect when it reaches the dCDN. A uCDN that makes a resource available before the corresponding MI.CrossoriginPolicy has been applied by the dCDN should expect the dCDN to serve that resource without the CORS response headers until the configuration is in effect. A User Agent treats that as a failed CORS check rather than as unrestricted access. The wildcard value of the wildcard-return property defined in MI.AccessControlAllowOrigin is intended for deployments in which the uCDN needs the dCDN to verify the Origin request header against the allow-list, but needs the Access-Control-Allow-Origin response header to carry "*" rather than the requesting origin. This arises where a Content Provider has to keep an installed base of User Agents working, including User Agents that do not correctly handle a response that echoes their own origin. In this configuration the allow-list remains the point at which access is decided: a request whose Origin request header does not match receives no CORS response headers at all. Because the response returned to a matching origin does not itself identify that origin, the effectiveness of the allow-list in this configuration depends on the Vary header field required in dCDN Required Behaviour section. Without it, a shared cache can serve a response carrying "*" to a request from an origin that the allow-list excludes.

The FCI and MI objects defined in this document are transferred via the interfaces defined in CDNI which describes how to secure these interfaces by protecting integrity and confidentiality while ensuring the authenticity of the dCDN and uCDN. The CORS and connection-control policies expressed by the MI objects in this document directly control which origins and headers a dCDN will accept, and unauthorized modification of these values could weaken the access control a uCDN intends to enforce. The integrity protection referenced above is therefore particularly important for these objects. The CORS response headers that a dCDN generates depend on the Origin request header of each request. If those headers are reused for a request carrying a different Origin, the set of origins the uCDN intended to accept is no longer enforced. Section dCDN Required Behaviour requires the dCDN to declare that dependency with the Vary header field so that shared caches between the dCDN and the User Agent, and the User Agent's own HTTP cache, key their stored responses accordingly. A deployment in which the Vary header field is stripped or ignored reduces the configured allow-list to a best-effort measure. A delay between a uCDN making a resource available and the corresponding configuration taking effect at the dCDN does not result in unrestricted cross-origin access; see . CORS is enforced by the User Agent. The headers defined by the CORS protocol instruct a User Agent whether to expose a response to a script running in a given origin; they do not prevent any client from retrieving the resource. The objects defined in this document therefore control what a conforming User Agent will allow, and are not a substitute for the access control mechanisms available in the CDNI Metadata Interface, such as MI.LocationACL, MI.TimeWindowACL, MI.ProtocolACL or MI.Auth .

This document requests the registration of the following entries under the "CDNI Payload Types" registry hosted by IANA: CDNI Payload Types

Payload Type	Specification
MI.CrossoriginPolicy	RFCthis
MI.AccessControlAllowOrigin	RFCthis
MI.AllowCompress	RFCthis
MI.ClientConnectionControl	RFCthis
MI.AccessControlHeader	RFCthis

[RFC Editor: Please replace RFCthis with the published RFC number for this document.]

Purpose: The purpose of this Payload Type is to distinguish CrossoriginPolicy MI objects (and any associated capability advertisement) Interface: MI Encoding: See

Purpose: The purpose of this Payload Type is to distinguish AccessControlAllowOrigin MI objects (and any associated capability advertisement) Interface: MI Encoding: See

Purpose: The purpose of this Payload Type is to distinguish AllowCompress MI objects (and any associated capability advertisement) Interface: MI Encoding: See

Purpose: The purpose of this Payload Type is to distinguish ClientConnectionControl MI objects (and any associated capability advertisement) Interface: MI Encoding: See

Purpose: The purpose of this Payload Type is to distinguish AccessControlHeader MI objects (and any associated capability advertisement) Interface: MI Encoding: See

The authors would like to express their gratitude to the members of the Streaming Video Technology Alliance Open Caching Working Group for their contributions and guidance. Particularly the following people contribute in vairous ways to the content of this draft:

Guillaume Bichot (Broadpeak)
Christoph Neumann (Broadpeak)
Chris Lemmons (Comcast)
Pankaj Chaudhari (Disney Streaming)
Robert Colantuoni (Disney Streaming)
Will Power (Lumen)
Rajeev RK (picoNETS)
Shmuel Asafi (Qwilt)
Yoav Gressel (Qwilt)
Nir Sopher (Qwilt)
Arnon Warshavsky (Qwilt)
Eric Klein (Sirius XM)
Francisco Cano Hila (Telefonica)
Ben Rosenblum (Vecima)