RFC 8006
Content Delivery Network Interconnection (CDNI) Metadata
RFC 8006 🎀 Content Delivery Network Interconnection (CDNI) Metadata
The title block, bestie: This is RFC 8006, published in December 2016 by the IETF with ISSN 2070-1721. It's a Standards Track doc, so it's a real spec that implementers are meant to follow ✨. The authors are B. Niven-Jenkins, R. Murray (Nokia), M. Caulfield (Cisco Systems), and K. Ma (Ericsson). Nothing in the title block says it obsoletes or updates any other RFC 💅.
Abstract 🌸
Okay so the CDNI Metadata interface is how interconnected CDNs swap content distribution metadata 🦋. That's what lets them actually grab content and deliver it. The metadata for a piece of content gives a downstream CDN everything it needs to serve content requests on behalf of an upstream CDN, and this doc lays out a base set of that metadata plus the protocol for passing it around 💖.
Status of This Memo 📜
This is an Internet Standards Track document ✨.
It's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 7841 🧚.
For the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc8006 🔥.
Copyright Notice ⚖️
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved 💜.
This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stood on the publication date. Read those carefully, because they spell out your rights and restrictions for this document 🙈. Code Components pulled out of this document must include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as the Simplified BSD License says 🫶.
Table of Contents 🗂️
1. Introduction ....................................................5
1.1. Terminology ................................................5
1.2. Supported Metadata Capabilities ............................6
2. Design Principles ...............................................7
3. CDNI Metadata Object Model ......................................8
3.1. HostIndex, HostMatch, HostMetadata, PathMatch,
PatternMatch, and PathMetadata Objects .....................9
3.2. Generic CDNI Metadata Objects .............................11
3.3. Metadata Inheritance and Override .........................14
4. CDNI Metadata Objects ..........................................15
4.1. Definitions of the CDNI Structural Metadata Objects .......16
4.1.1. HostIndex ..........................................16
4.1.2. HostMatch ..........................................17
4.1.3. HostMetadata .......................................18
4.1.4. PathMatch ..........................................19
4.1.5. PatternMatch .......................................20
4.1.6. PathMetadata .......................................21
4.1.7. GenericMetadata ....................................23
4.2. Definitions of the Initial Set of CDNI
GenericMetadata Objects ...................................24
4.2.1. SourceMetadata .....................................24
4.2.1.1. Source ....................................25
4.2.2. LocationACL Metadata ...............................26
4.2.2.1. LocationRule ..............................28
4.2.2.2. Footprint .................................29
4.2.3. TimeWindowACL ......................................30
4.2.3.1. TimeWindowRule ............................31
4.2.3.2. TimeWindow ................................32
4.2.4. ProtocolACL Metadata ...............................33
4.2.4.1. ProtocolRule ..............................34
4.2.5. DeliveryAuthorization Metadata .....................35
4.2.6. Cache ..............................................35
4.2.7. Auth ...............................................37
4.2.8. Grouping ...........................................38
4.3. CDNI Metadata Simple Data Type Descriptions ...............39
4.3.1. Link ...............................................39
4.3.1.1. Link Loop Prevention ......................40
4.3.2. Protocol ...........................................40
4.3.3. Endpoint ...........................................40
4.3.4. Time ...............................................41
4.3.5. IPv4CIDR ...........................................41
4.3.6. IPv6CIDR ...........................................42
4.3.7. ASN ................................................42
4.3.8. Country Code .......................................42
5. CDNI Metadata Capabilities .....................................42
6. CDNI Metadata Interface ........................................43
6.1. Transport .................................................44
6.2. Retrieval of CDNI Metadata Resources ......................44
6.3. Bootstrapping .............................................45
6.4. Encoding ..................................................46
6.5. Extensibility .............................................46
6.6. Metadata Enforcement ......................................47
6.7. Metadata Conflicts ........................................47
6.8. Versioning ................................................48
6.9. Media Types ...............................................49
6.10. Complete CDNI Metadata Example ...........................50
7. IANA Considerations ............................................54
7.1. CDNI Payload Types ........................................54
7.1.1. CDNI MI HostIndex Payload Type .....................54
7.1.2. CDNI MI HostMatch Payload Type .....................55
7.1.3. CDNI MI HostMetadata Payload Type ..................55
7.1.4. CDNI MI PathMatch Payload Type .....................55
7.1.5. CDNI MI PatternMatch Payload Type ..................55
7.1.6. CDNI MI PathMetadata Payload Type ..................55
7.1.7. CDNI MI SourceMetadata Payload Type ................56
7.1.8. CDNI MI Source Payload Type ........................56
7.1.9. CDNI MI LocationACL Payload Type ...................56
7.1.10. CDNI MI LocationRule Payload Type .................56
7.1.11. CDNI MI Footprint Payload Type ....................56
7.1.12. CDNI MI TimeWindowACL Payload Type ................57
7.1.13. CDNI MI TimeWindowRule Payload Type ...............57
7.1.14. CDNI MI TimeWindow Payload Type ...................57
7.1.15. CDNI MI ProtocolACL Payload Type ..................57
7.1.16. CDNI MI ProtocolRule Payload Type .................57
7.1.17. CDNI MI DeliveryAuthorization Payload Type ........58
7.1.18. CDNI MI Cache Payload Type ........................58
7.1.19. CDNI MI Auth Payload Type .........................58
7.1.20. CDNI MI Grouping Payload Type .....................58
7.2. "CDNI Metadata Footprint Types" Registry ..................58
7.3. "CDNI Metadata Protocol Types" Registry ...................59
8. Security Considerations ........................................60
8.1. Authentication and Integrity ..............................60
8.2. Confidentiality and Privacy ...............................60
8.3. Securing the CDNI Metadata Interface ......................61
9. References .....................................................62
9.1. Normative References ......................................62
9.2. Informative References ....................................63
Acknowledgments ...................................................65
Contributors ......................................................65
Authors' Addresses ................................................661. Introduction 🦋
Okay, so Content Delivery Network Interconnection (CDNI) [RFC6707] lets a downstream CDN (dCDN) serve content requests on behalf of an upstream CDN (uCDN) 💅.
The CDNI Metadata interface (MI) gets covered in [RFC7336], which also covers four other interfaces you can mix together to build a CDNI solution: the CDNI Control interface, the CDNI Request Routing Redirection interface, the CDNI Footprint & Capabilities Advertisement interface (FCI), and the CDNI Logging interface. [RFC7336] explains each one and how they relate to each other. The requirements for the CDNI Metadata interface are in [RFC7337] 🧚.
The CDNI Metadata for a piece of content (or a whole set of content) gives a dCDN enough info to serve content requests for a uCDN, following the policies the uCDN set 🎀.
This doc defines a CDNI Metadata interface so a dCDN can get CDNI Metadata from a uCDN. That way the dCDN can properly process and respond to:
- Redirection requests that come in over the CDNI Request Routing Redirection interface [RFC7975] 🌈.
- Content requests that come straight from User Agents 💖.
Specifically, this doc defines:
- A data structure for mapping content requests and redirection requests to CDNI Metadata objects (Sections 3 and 4.1) ✨.
- An initial set of CDNI GenericMetadata objects (Section 4.2) 🍓.
- An HTTP web service for transferring CDNI Metadata (Section 6) 👑.
1.1. Terminology 💜
This doc reuses the terminology defined in [RFC6707] 🫶.
On top of that, these terms show up all over the place and are defined like this:
- Object - a collection of properties.
- Property - a key and value pair where the key is a property name and the value is the property value or another object.
For simplicity, this doc says "[Object] A contains [Object] B" even though the strictly accurate phrase would be "[Object] A contains or references (via a Link object) [Object] B" 🙈.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] 🔥.
To be continued... part 2 of 12 is coming, bestie! 🌈💅✨
1.2. Supported Metadata Capabilities ✨
okay so only a small set of starter capabilities gets specified in this doc 🎀 that's the minimum metadata needed for basic CDN interop, and it still hits every requirement from [RFC7337]. no cap, that's the bare minimum and it's giving clean 💅
these high-level features can be configured through the CDNI Metadata objects in Section 4:
- Acquisition Source: metadata that lets a dCDN fetch content from a uCDN 🦋
- Delivery Access Control: metadata for restricting (or allowing) access to content based on:
- Location 📍
- Time window ⏰
- Delivery protocol 🔌
- Delivery Authorization: metadata for authorizing dCDN User Agent requests 🔐
- Cache Control: metadata for controlling how the dCDN caches stuff 🧠
the metadata encoding in this doc is extensible, so more stuff can be added to this list later on 🌈 future-proof queen behavior
this doc only covers the starter capabilities above 🫶 it's only meant to support CDNI for delivering content by a dCDN over HTTP/1.1 [RFC7230], and for a dCDN to acquire content from a uCDN over either HTTP/1.1 or HTTP/1.1 over Transport Layer Security (TLS) [RFC2818].
if you want CDNI delivery over unencrypted HTTP/2 [RFC7540] (or acquiring content over unencrypted HTTP/2 or HTTP/2 over TLS), those protocol names have to get registered in the "CDNI Metadata Protocol Types" registry (Section 7.3) first 📝 that's a whole separate glow-up step
delivery over HTTP/1.1 over TLS or HTTP/2 over TLS SHOULD follow the guidelines in [RFC7525] 🔒 and offline configuration of TLS parameters between CDNs is beyond the scope of this doc, so don't look for it here 🙈
2. Design Principles 💜
the CDNI Metadata interface was built around five main goals, bestie 👑
- Cacheability of CDNI Metadata objects 🗂️
- Deterministic mapping from redirection requests and content requests to CDNI Metadata properties 🎯
- Support for DNS redirection as well as application-specific redirection (for example, HTTP redirection) 🔀
- Minimal duplication of CDNI Metadata 🧹
- Leveraging of existing protocols 🧩
cacheability is huge because it cuts down how long it takes to grab metadata, while keeping it fresh and accurate 🌸 that means content requests and redirection requests get served faster too, without losing accuracy. the CDNI Metadata interface uses HTTP and its existing caching mechanisms to get this cacheability 💖
deterministic mapping means content always maps to the same metadata properties, so there's zero ambiguity and every dCDN applies the policies the same way ✨ literally no drama
supporting both HTTP and DNS redirection means the metadata works the same way for both HTTP-based and DNS-based redirection 🦋
minimal duplication saves storage in the CDNs, which is very much a "efficient and iconic" situation 💅
leveraging existing protocols means we don't reinvent the wheel 🛞 for data structure encoding it uses I-JSON (Internet JSON) [RFC7493], and for data transport it uses HTTP [RFC7230] 🎀
3. CDNI Metadata Object Model 🧚
okay the CDNI Metadata object model is a data structure that maps redirection requests and content requests to metadata properties 🗺️ those properties describe how to acquire content from a uCDN, how to authorize access to it, and how a dCDN delivers it. the big assumption here is that these properties can be grouped by the content's hostname and then by its resource path (URI) 🌈
so a hostname gets a set of CDNI Metadata properties, and that set is the default for all content delivered under that hostname 💜 then specific paths within a URI can override that default with their own properties. main character energy for sure 👑
different hostnames and URI paths end up with different property sets, which tells a dCDN Surrogate or request router how to handle User Agent requests for that hostname and path 🦋 but here's the tea: a lot of properties end up being the same across hostnames, paths within a hostname, and paths on different hostnames 🫠 for example, which User Agent IP addresses get grouped into one network or geographic location is probably going to be common across lots of hostnames. a uCDN might have several geo-blocking policies, but a single geo-blocking policy could easily get applied to multiple hostnames delivered through the CDN 🌍
so to avoid repeating stuff, the CDNI Metadata interface splits the metadata into separate objects 🧩 that way one CDNI Metadata object, shared across hostnames and/or URI paths, gets retrieved and stored by a dCDN just once, even when it's referenced by the metadata for multiple hostnames and/or URI paths. storage efficiency is literally iconic 🔥
Important Note: any CDNI Metadata object A that contains another CDNI Metadata object B can include a Link object with a URI that can be used to retrieve object B, instead of embedding object B inside object A. the rest of this doc uses the phrase "[Object] A contains [Object] B" for simplicity, when the strictly accurate phrase would be "[Object] A contains or references (via a Link object) [Object] B". it's generally a deployment choice for the uCDN implementation to decide when to embed CDNI Metadata objects and when to reference separate resources via Link objects 🫶
Section 3.1 gives a high-level description of the HostIndex, HostMatch, HostMetadata, PathMatch, PatternMatch, and PathMetadata objects, and explains how they relate to each other 🧠
Section 3.2 gives a high-level description of the CDNI GenericMetadata object, which is the level where metadata override happens between HostMetadata and PathMetadata objects 💖
Section 4 goes into detail on the specific CDNI Metadata objects and properties this doc specifies that can be contained within a CDNI GenericMetadata object 🎀
that's the whole vibe of the object model, bestie 💜
Okay bestie, let's get into the juicy part: the metadata object web! 💖
3.1. HostIndex, HostMatch, HostMetadata, PathMatch, PatternMatch, and PathMetadata Objects
okay so the relationships between the HostIndex, HostMatch, HostMetadata, PathMatch, PatternMatch, and PathMetadata objects are all laid out in Figure 1 🦋 no cap, it's giving diagram energy 😭
+---------+ +---------+ +------------+
|HostIndex+-(*)->|HostMatch+-(1)->|HostMetadata+-------(*)------+
+---------+ +---------+ +------+-----+ |
| |
(*) |
| V
--> Contains or references V *****************
(1) One and only one +---------+ *GenericMetadata*
(*) Zero or more +--->|PathMatch| * Objects *
| +----+---++ *****************
| | | ^
(*) (1) (1) +------------+ |
| | +->|PatternMatch| |
| V +------------+ |
| +------------+ |
+--+PathMetadata+-------(*)------+
+------------+Figure 1: Relationships between CDNI Metadata Objects (Diagram Representation)
so a HostIndex object (see Section 4.1.1) contains an array of HostMatch objects (see Section 4.1.2) that hold hostnames (and/or IP addresses) that content requests might get delegated to the dCDN for 💅 the HostIndex is literally the starting point for getting to the uCDN CDNI Metadata data store ✨ it lets the dCDN deterministically figure out which CDNI Metadata objects it needs to deliver a given piece of content. the way that's so iconic 🫶
the HostIndex links hostnames (and/or IP addresses) to HostMetadata objects (see Section 4.1.3) through HostMatch objects. a HostMatch object defines a hostname (or IP address) to match against a requested host and contains a HostMetadata object 🎀
HostMetadata objects contain the default GenericMetadata objects (see Section 4.1.7) needed to serve content for that host. when the dCDN looks up CDNI Metadata, it checks the requested hostname (or IP address) against the HostMatch entries in the HostIndex. from there it can find HostMetadata, which describes the default metadata properties for each host, as well as PathMetadata objects (see Section 4.1.6), via PathMatch objects (see Section 4.1.4). PathMatch objects define patterns, held inside PatternMatch objects (see Section 4.1.5), to match against the requested URI path. PatternMatch objects hold the pattern strings and flags that describe which URI path a PathMatch applies to 🌸 PathMetadata objects contain the GenericMetadata objects that apply to content requests matching that URI path pattern. PathMetadata properties override properties previously defined in HostMetadata or in less-specific PathMatch paths. and PathMetadata objects can contain additional PathMatch objects to recursively define more-specific URI paths that GenericMetadata properties might be applied to. main character energy, literally 👑
a GenericMetadata object contains individual CDNI Metadata objects that define the specific policies and attributes needed to deliver the associated content properly. for example, a GenericMetadata object could describe the source a CDN can acquire a piece of content from 🧚 the GenericMetadata object is an atomic unit that can be referenced by HostMetadata or PathMetadata objects 💜
let's do an example, bestie 🍓 if "example.com" is a content provider, a HostMatch object could include an entry for "example.com" with the URI of the associated HostMetadata object. the HostMetadata object for "example.com" describes the metadata properties that apply to "example.com" and could contain PathMatches for "example.com/movies/" and "example.com/music/", which in turn reference the matching PathMetadata objects that hold the properties for those more-specific URI paths. the PathMetadata object for "example.com/movies/" describes the properties that apply to that URI path. it could also contain a PathMatch object for "example.com/movies/hd/", which would reference the corresponding PathMetadata object for the "example.com/movies/hd/" path prefix. nested paths, iykyk 🙈
the relationships in Figure 1 are also shown in table form in Table 1 below. the tea is served 🍵
+--------------+----------------------------------------------------+
| Data Object | Objects it contains or references |
+--------------+----------------------------------------------------+
| HostIndex | 0 or more HostMatch objects. |
| | |
| HostMatch | 1 HostMetadata object. |
| | |
| HostMetadata | 0 or more PathMatch objects. 0 or more |
| | GenericMetadata objects. |
| | |
| PathMatch | 1 PatternMatch object. 1 PathMetadata object. |
| | |
| PatternMatch | Does not contain or reference any other objects. |
| | |
| PathMetadata | 0 or more PathMatch objects. 0 or more |
| | GenericMetadata objects. |
+--------------+----------------------------------------------------+Table 1: Relationships between CDNI Metadata Objects (Table Representation)
3.2. Generic CDNI Metadata Objects ✨
okay so HostMetadata and PathMetadata are basically boxes 📦 that hold OTHER CDNI Metadata objects, and those are the juicy bits that tell a CDN how to handle User Agent requests for content. like, where to grab the content from, what authorization rules apply, geo-blocking restrictions, the whole vibe 💅 every one of those inner objects is a specialization of a CDNI GenericMetadata object. GenericMetadata is the chill base that gives you just the basic info you need for metadata override and distribution, and hides the specifics of each property (its semantics, enforcement options, etc.) 🧚
GenericMetadata also defines the properties inside it and whether each one is "mandatory-to-enforce" 🔥 if the dCDN doesn't understand or support a mandatory-to-enforce property, the dCDN MUST NOT serve the content. 💀 that's the hard rule. but if the property is not mandatory-to-enforce, that GenericMetadata object can be safely ignored and the request gets processed according to the rest of the CDNI Metadata 🫶
ngl this next part is the real plot twist 🙈 a CDN MUST NOT serve content to a User Agent if a mandatory-to-enforce property can't be enforced. BUT it could still be totally safe to redistribute that metadata (the "safe-to-redistribute" property) to another CDN without changing it 🦋 for example, in the cascaded CDN case, a transit CDN (tCDN) could pass mandatory-to-enforce metadata along to a dCDN. for metadata that doesn't need customization or translation (so, safe-to-redistribute), the data representation received off the wire MAY be stored and redistributed even if the tCDN doesn't understand or support it. however, for metadata that DOES need translation, transparently passing along the uCDN metadata values might not be appropriate 🌸 some metadata can be safely (though maybe not optimally) redistributed unmodified. like, a source acquisition address might not be optimal if it's passed along transparently, but it might still work ✨
Redistribution safety MUST be specified for each GenericMetadata property. if a CDN doesn't understand or support a given GenericMetadata property that is not safe-to-redistribute, the CDN MUST set the "incomprehensible" flag to true for that GenericMetadata object before redistributing the metadata. the "incomprehensible" flag tells a dCDN that the metadata wasn't properly transformed by the tCDN 🚩 and a CDN MUST NOT attempt to use metadata that a uCDN has marked as "incomprehensible". 🙅♀️
tCDNs MUST NOT change the value of mandatory-to-enforce or safe-to-redistribute when passing metadata on to a dCDN. a tCDN can set "incomprehensible" to true, sure, but a tCDN MUST NOT change "incomprehensible" from true back to false. no undoing that 💅
Table 2 is the cheat sheet for what a tCDN does with each combo of MtE and StR properties, depending on whether the tCDN understands the metadata or not 📋
+-------+-------+------------+--------------------------------------+
| MtE | StR | Metadata | Action |
| | | Understood | |
| | | by tCDN | |
+-------+-------+------------+--------------------------------------+
| False | True | True | Can serve and redistribute. |
| | | | |
| False | True | False | Can serve and redistribute. |
| | | | |
| False | False | False | Can serve. MUST set |
| | | | "incomprehensible" to true when |
| | | | redistributing. |
| | | | |
| False | False | True | Can serve. Can redistribute after |
| | | | transforming the metadata (if the |
| | | | CDN knows how to do so safely); |
| | | | otherwise, MUST set |
| | | | "incomprehensible" to true when |
| | | | redistributing. |
| | | | |
| True | True | True | Can serve and redistribute. |
| | | | |
| True | True | False | MUST NOT serve but can redistribute. |
| | | | |
| True | False | True | Can serve. Can redistribute after |
| | | | transforming the metadata (if the |
| | | | CDN knows how to do so safely); |
| | | | otherwise, MUST set |
| | | | "incomprehensible" to true when |
| | | | redistributing. |
| | | | |
| True | False | False | MUST NOT serve. MUST set |
| | | | "incomprehensible" to true when |
| | | | redistributing. |
+-------+-------+------------+--------------------------------------+
Table 2: Action to Be Taken by a tCDN for the
Different Combinations of MtE and StR PropertiesTable 3 is the dCDN's version of the cheat sheet 🍓 it covers the combos of mandatory-to-enforce and "incomprehensible" (Incomp) properties, again depending on whether the dCDN understands the metadata 👑
+-------+--------+--------------+-----------------------------------+
| MtE | Incomp | Metadata | Action |
| | | Understood | |
| | | by dCDN | |
+-------+--------+--------------+-----------------------------------+
| False | False | True | Can serve. |
| | | | |
| False | True | True | Can serve but MUST NOT |
| | | | interpret/apply any metadata |
| | | | marked as "incomprehensible". |
| | | | |
| False | False | False | Can serve. |
| | | | |
| False | True | False | Can serve but MUST NOT |
| | | | interpret/apply any metadata |
| | | | marked as "incomprehensible". |
| | | | |
| True | False | True | Can serve. |
| | | | |
| True | True | True | MUST NOT serve. |
| | | | |
| True | False | False | MUST NOT serve. |
| | | | |
| True | True | False | MUST NOT serve. |
+-------+--------+--------------+-----------------------------------+
Table 3: Action to Be Taken by a dCDN for the
Different Combinations of MtE and Incomp Properties3.3. Metadata Inheritance and Override 🦋
okay this is the family tree energy 🌳 in the metadata object model, a HostMetadata object can hold multiple PathMetadata objects (through PathMatch objects), and each PathMetadata object can hold other PathMetadata objects too. HostMetadata and PathMetadata objects form an inheritance tree where every node either inherits or overrides the property values set by its parent 👑
here's the rule of thumb 💖 GenericMetadata objects of a given type override ALL GenericMetadata objects of that same type set by any parent object up the tree. and GenericMetadata objects of a given type set by a parent are inherited when the child object doesn't define one of that same type 🫶 for example, say HostMetadata for the host example.com has GenericMetadata objects of types LocationACL and TimeWindowACL (where "ACL" means "Access Control List"), and a PathMetadata object that applies to example.com/movies/* defines its own alternate GenericMetadata object of type TimeWindowACL. then:
- The TimeWindowACL defined in the PathMetadata would override the TimeWindowACL defined in the HostMetadata for all User Agent requests for content under
example.com/movies/, and - The LocationACL defined in the HostMetadata would be inherited for all User Agent requests for content under
example.com/movies/.
warning bestie 🚨 a single HostMetadata or PathMetadata object MUST NOT contain multiple GenericMetadata objects of the same type. and if an array of GenericMetadata has objects with duplicate types, the receiver MUST ignore all but the first object of each type. 🙈
4. CDNI Metadata Objects ✨
Okay so this section is where the actual building blocks live 💅 Section 4.1 defines every metadata object type that Section 3 introduced. These are the structural metadata objects. They're the scaffolding for host and URI path-based inheritance, and they figure out which GenericMetadata objects apply to a given User Agent content request 🦋
Section 4.2 covers a base set of core metadata objects that can live inside a GenericMetadata object. These are the ones that govern how User Agent requests for content get handled 🔥 GenericMetadata objects can hold other GenericMetadata objects as properties, and those are called sub-objects. Like every CDNI Metadata object, a sub-object's value can be either its complete serialized form, or a Link object containing a URI that can be dereferenced to fetch that complete form 🔗
Section 6.5 is about extending the base set of GenericMetadata objects with more standards-based or vendor-specific ones, which might get defined later in separate documents 🌈
dCDNs and tCDNs MUST support parsing all CDNI Metadata objects in this document 💖 A dCDN doesn't have to implement the functionality behind non-structural GenericMetadata objects, though skipping that might limit what content it can serve 🙈 uCDNs, as generators of CDNI Metadata, only need to generate the CDNI Metadata they need in order to express the policies the content they describe requires. See Section 6.4 for the specific encoding rules for CDNI Metadata objects 🧚
Note: In the sections below, "mandatory-to-specify" tells you which properties MUST be included for a given structural or GenericMetadata object. When mandatory-to-specify is "Yes" for a property, that means if the object holding it shows up in a metadata response, that property MUST also be included in the response, either directly or by reference. For example, a HostMatch object without a host to match against makes zero sense, so the "host" property is mandatory-to-specify inside a HostMatch object 💀
4.1. Definitions of the CDNI Structural Metadata Objects
The subsections below describe the structural objects introduced in Section 3.1 🌸
4.1.1. HostIndex
The HostIndex object is the entry point into the CDNI Metadata hierarchy 👑 It holds an array of HostMatch objects. An incoming content request gets checked against the hostname (or IP address) in each listed HostMatch object, until it finds the HostMatch object that applies to that request.
- Property:
hosts- Description: Array of HostMatch objects. Hosts (HostMatch objects) MUST be evaluated in the order they appear, and the first HostMatch object that matches the content request being processed MUST be used.
- Type: Array of HostMatch objects
- Mandatory-to-Specify: Yes.
Here's an example HostIndex object with two HostMatch objects. The first one is embedded and the second one is referenced ✨
{
"hosts": [
{
<Properties of embedded HostMatch object>
},
{
"type": "MI.HostMatch",
"href": "https://metadata.ucdn.example/hostmatch1234"
}
]
}4.1.2. HostMatch
The HostMatch object holds a hostname or IP address to match against content requests 🎀 It also holds a HostMetadata object to apply if a match is found.
- Property:
host- Description: The hostname or IP address, plus an optional port, to match against the requested host. That's the host and port as described in [RFC3986]. For a content request's hostname or IP address to match the "host" property, the value from the content request, once converted to lowercase, MUST be identical to the "host" property's value once converted to lowercase. All implementations MUST support IPv4 addresses encoded as the "IPv4address" rule in Section 3.2.2 of [RFC3986]. IPv6 addresses MUST be encoded in one of the IPv6 address formats specified in [RFC5952], although receivers MUST support all IPv6 address formats specified in [RFC4291]. Hostnames MUST conform to the Domain Name System (DNS) syntax defined in [RFC1034] and [RFC1123]. Internationalized Domain Names (IDNs) need to first be transformed to the A-label form [RFC5890] as per [RFC5891] 🌍
- Type: Endpoint
- Mandatory-to-Specify: Yes.
- Property:
host-metadata- Description: CDNI Metadata to apply when delivering content that matches this host.
- Type: HostMetadata
- Mandatory-to-Specify: Yes.
Example HostMatch object with an embedded HostMetadata object:
{
"host": "video.example.com",
"host-metadata": {
<Properties of embedded HostMetadata object>
}
}Example HostMatch object referencing a HostMetadata object (via a Link object; see Section 4.3.1):
{
"host": "video.example.com",
"host-metadata": {
"type": "MI.HostMetadata",
"href": "https://metadata.ucdn.example/host1234"
}
}4.1.3. HostMetadata
A HostMetadata object holds the CDNI Metadata properties for content served for a particular host (the one defined in the HostMatch object). It can also have child PathMatch objects 🧁
- Property:
metadata- Description: Array of host-related metadata.
- Type: Array of GenericMetadata objects
- Mandatory-to-Specify: Yes.
- Property:
paths- Description: Path-specific rules. Path patterns (PathMatch objects) MUST be evaluated in the order they appear, and the first (and only the first) PathMatch object that matches the content request being processed MUST be used.
- Type: Array of PathMatch objects
- Mandatory-to-Specify: No. Default is that there are no more-specific paths to evaluate (i.e., an empty list).
Here's an example HostMetadata object. It has a bunch of embedded GenericMetadata objects that describe the default metadata for the host, plus an embedded PathMatch object for a path that overrides that default 🦋
{
"metadata": [
{
<Properties of first embedded GenericMetadata object>
},
{
<Properties of second embedded GenericMetadata object>
},
...
{
<Properties of Nth embedded GenericMetadata object>
}
],
"paths": [
{
<Properties of embedded PathMatch object>
}
]
}4.1.4. PathMatch
A PathMatch object holds a PatternMatch object with a path to match against a resource's URI path, plus how to handle URI query parameters 🔍 It also holds a PathMetadata object with GenericMetadata to apply if the resource's URI matches the pattern inside the PatternMatch object.
- Property:
path-pattern- Description: Pattern to match against the requested resource's URI.
- Type: PatternMatch
- Mandatory-to-Specify: Yes.
- Property:
path-metadata- Description: CDNI Metadata to apply when delivering content that matches the associated PatternMatch.
- Type: PathMetadata
- Mandatory-to-Specify: Yes.
Example PathMatch object referencing the PathMetadata object to use for URIs that match the case-sensitive URI path pattern /movies/* (contained within an embedded PatternMatch object) 🎬
{
"path-pattern": {
"pattern": "/movies/*",
"case-sensitive": true
},
"path-metadata": {
"type": "MI.PathMetadata",
"href": "https://metadata.ucdn.example/host1234/pathDCE"
}
}4.1.5. PatternMatch
A PatternMatch object holds the pattern string and the flags that describe how the pattern expression works 🧩
- Property:
pattern- Description: A pattern for matching against the URI path, i.e., against the path-absolute [RFC3986]. The pattern can contain the wildcards
*and?.*matches any sequence of pchar [RFC3986] or/characters (including the empty string), and?matches exactly one pchar character. The three literals$,*, and?MUST be escaped as$$,$*, and$?(where$is the designated escape character). All other characters are treated as literals. - Type: String
- Mandatory-to-Specify: Yes.
- Description: A pattern for matching against the URI path, i.e., against the path-absolute [RFC3986]. The pattern can contain the wildcards
- Property:
case-sensitive- Description: Flag that says whether matching is case-sensitive or not. Note: Case insensitivity applies to ALPHA characters in the URI path prior to percent-decoding [RFC3986] 🔤
- Type: Boolean
- Mandatory-to-Specify: No. Default is case-insensitive match (i.e., a value of
False).
Example PatternMatch object that matches the case-sensitive URI path pattern /movies/*:
{
"pattern": "/movies/*",
"case-sensitive": true
}4.1.6. PathMetadata
A PathMetadata object holds the CDNI Metadata properties for content requests that match the associated URI path (the one defined in a PathMatch object) 🌷
Heads up: If DNS-based redirection is employed, a dCDN can't evaluate any metadata at the PathMetadata level or below. That's because only the hostname of the content request is available at Request Routing time 😭 dCDNs SHOULD still process all PathMetadata for the host before responding to the redirection request, so they can detect any unsupported metadata that's specified. If any metadata not supported by the dCDN is marked as mandatory-to-enforce, the dCDN SHOULD NOT accept the content redirection request. That way it avoids receiving content requests it won't be able to satisfy/serve 🙅♀️
- Property:
metadata- Description: Array of path-related metadata.
- Type: Array of GenericMetadata objects
- Mandatory-to-Specify: Yes.
- Property:
paths- Description: Path-specific rules. Path patterns (PathMatch objects) MUST be evaluated in the order they appear, and the first (and only the first) PathMatch object that matches the content request being processed MUST be used.
- Type: Array of PathMatch objects
- Mandatory-to-Specify: No. Default is that there are no more-specific paths to evaluate (i.e., an empty list).
Here's an example PathMetadata object. It has embedded GenericMetadata objects that describe the metadata for the URI path defined in the parent PathMatch object, plus a more-specific PathMatch object ✨
{
"metadata": [
{
<Properties of first embedded GenericMetadata object>
},
{
<Properties of second embedded GenericMetadata object>
},
...
{
<Properties of Nth embedded GenericMetadata object>
}
],
"paths": [
{
<Properties of embedded PathMatch object>
}
]
}4.1.7. GenericMetadata ✨
Okay so GenericMetadata is basically a little gift wrapper 🎁 for one CDNI Metadata property. It carries that property around in an opaque way, so the CDNs in the chain don't have to open it up to pass it along. Iconic. 💅
generic-metadata-type- Description: Case-insensitive CDNI Metadata object type.
- Type: String containing the CDNI Payload Type [RFC7736] of the object contained in the generic-metadata-value property (see Table 4).
- Mandatory-to-Specify: Yes.
generic-metadata-value- Description: CDNI Metadata object.
- Type: Format/Type is defined by the value of the generic-metadata-type property above.
- Note: generic-metadata-values MUST NOT name any properties "href" (see Section 4.3.1).
- Mandatory-to-Specify: Yes.
mandatory-to-enforce- Description: Flag identifying whether or not the enforcement of the property metadata is required.
- Type: Boolean
- Mandatory-to-Specify: No. Default is to treat metadata as mandatory-to-enforce (i.e., a value of True).
safe-to-redistribute- Description: Flag identifying whether or not the property metadata can be safely redistributed without modification.
- Type: Boolean
- Mandatory-to-Specify: No. Default is to allow transparent redistribution (i.e., a value of True).
incomprehensible- Description: Flag identifying whether or not any CDN in the chain of delegation has failed to understand and/or failed to properly transform this metadata object. Note: This flag only applies to metadata objects whose safe-to-redistribute property has a value of False.
- Type: Boolean
- Mandatory-to-Specify: No. Default is comprehensible (i.e., a value of False).
Here's an example GenericMetadata object wrapping a metadata object that applies to the applicable URI path and/or host (within a parent PathMetadata and/or HostMetadata object, respectively):
{
"mandatory-to-enforce": true,
"safe-to-redistribute": true,
"incomprehensible": false,
"generic-metadata-type": <CDNI Payload Type of this metadata object>,
"generic-metadata-value":
{
<Properties of this metadata object>
}
}4.2. Definitions of the Initial Set of CDNI GenericMetadata Objects 🌈
The objects below are meant to go inside the GenericMetadata object's generic-metadata-value field (see Section 4.1.7). Their generic-metadata-type property MUST be set to the matching CDNI Payload Type from Table 4. 🫶
4.2.1. SourceMetadata 📦
Source metadata tells the dCDN where to get the content from: how to reach a uCDN Surrogate or an origin server. These sources aren't always the actual origin servers run by the Content Service Provider (CSP). They might just be a set of Surrogates in the uCDN. 🧚
sources- Description: Sources from which the dCDN can acquire content, listed in order of preference.
- Type: Array of Source objects (see Section 4.2.1.1)
- Mandatory-to-Specify: No. Default is to use static configuration, out-of-band from the CDNI Metadata interface.
Here's an example SourceMetadata object (with two Source objects) showing which servers the dCDN should use to acquire content for the applicable URI path and/or host:
{
"generic-metadata-type": "MI.SourceMetadata",
"generic-metadata-value":
{
"sources": [
{
"endpoints": [
"a.service123.ucdn.example",
"b.service123.ucdn.example"
],
"protocol": "http/1.1"
},
{
"endpoints": ["origin.service123.example"],
"protocol": "http/1.1"
}
]
}
}4.2.1.1. Source 🎀
A Source object describes the source the dCDN uses for content acquisition (like a Surrogate in the uCDN or an alternate origin server), the protocol to use, and any authentication method to use when contacting that source. 💖
Endpoints within a Source object MUST be treated as equivalent/equal. A uCDN can list an array of sources, ordered by preference, inside a SourceMetadata object. Then, for each Source object ranked by preference, a uCDN can list an array of endpoints that are equivalent (e.g., a pool of servers that aren't behind a load balancer). 🍓
acquisition-auth- Description: Authentication method to use when requesting content from this source.
- Type: Auth (see Section 4.2.7)
- Mandatory-to-Specify: No. Default is no authentication required.
endpoints- Description: Origins from which the dCDN can acquire content. If multiple endpoints are specified, they are all equal, i.e., the list is not ordered by preference.
- Type: Array of Endpoint objects (see Section 4.3.3)
- Mandatory-to-Specify: Yes.
protocol- Description: Network retrieval protocol to use when requesting content from this source.
- Type: Protocol (see Section 4.3.2)
- Mandatory-to-Specify: Yes.
Here's an example Source object describing a pair of endpoints (servers) the dCDN can use to acquire content for the applicable host and/or URI path:
{
"endpoints": [
"a.service123.ucdn.example",
"b.service123.ucdn.example"
],
"protocol": "http/1.1"
}4.2.2. LocationACL Metadata 🌍
LocationACL metadata decides which locations a User Agent needs to be in to be able to receive the associated content.
A LocationACL without a "locations" property ends up as an action of "allow all", which means delivery can happen no matter where the User Agent is. Otherwise, a CDN MUST take the action from the first footprint that matches against the User Agent's location. If two or more footprints overlap, the first footprint that matches against the User Agent's location determines the action a CDN MUST take. If the "locations" property is included but is empty, or if none of the listed footprints match the User Agent's location, then the result is an action of "deny". 🙈
Even though the LocationACL, TimeWindowACL (see Section 4.2.3), and ProtocolACL (see Section 4.2.4) are independent GenericMetadata objects, they can give a dCDN conflicting info. Like, a content request could be allowed by the LocationACL and denied by the TimeWindowACL at the same time. 💀 The dCDN MUST use the logical AND of all ACLs (where "allow" is true and "deny" is false) to decide whether or not a request should be allowed. ✨
locations- Description: ACL that allows or denies (blocks) delivery based on the User Agent's location.
- Type: Array of LocationRule objects (see Section 4.2.2.1)
- Mandatory-to-Specify: No. Default is to allow all locations.
Here's an example LocationACL object that lets the dCDN deliver content to any location / IP address:
{
"generic-metadata-type": "MI.LocationACL",
"generic-metadata-value":
{
}
}Here's an example LocationACL object (containing a LocationRule object, which in turn contains a Footprint object) that only lets the dCDN deliver content to User Agents in the USA 🇺🇸:
{
"generic-metadata-type": "MI.LocationACL",
"generic-metadata-value":
{
"locations": [
{
"action": "allow",
"footprints": [
{
"footprint-type": "countrycode",
"footprint-value": ["us"]
}
]
}
]
}
}4.2.2.1. LocationRule 🦋
A LocationRule contains or references an array of Footprint objects, plus the matching action. 👑
footprints- Description: Array of footprints to which the rule applies.
- Type: Array of Footprint objects (see Section 4.2.2.2)
- Mandatory-to-Specify: Yes.
action- Description: Defines whether the rule specifies locations to allow or deny.
- Type: Enumeration [allow|deny] encoded as a lowercase string
- Mandatory-to-Specify: No. Default is "deny".
Here's an example LocationRule object (containing a Footprint object) that lets the dCDN deliver content to clients in the USA:
{
"action": "allow",
"footprints": [
{
"footprint-type": "countrycode",
"footprint-value": ["us"]
}
]
}4.2.2.2. Footprint 🌸
A Footprint object describes the footprint a LocationRule can apply to, like an IPv4 address range or a geographic location. 🗺️
footprint-type- Description: Registered footprint type (see Section 7.2). The footprint types specified by this document are "ipv4cidr" (IPv4CIDR; see Section 4.3.5), "ipv6cidr" (IPv6CIDR; see Section 4.3.6), "asn" (Autonomous System Number; see Section 4.3.7), and "countrycode" (Country Code; see Section 4.3.8).
- Type: Lowercase string
- Mandatory-to-Specify: Yes.
footprint-value- Description: Array of footprint values conforming to the specification associated with the registered footprint type. Footprint values can be simple strings (e.g., IPv4CIDR, IPv6CIDR, ASN, and Country Code); however, other Footprint objects can be defined in the future, along with a more complex encoding (e.g., GPS coordinate tuples).
- Type: Array of footprints
- Mandatory-to-Specify: Yes.
Here are some example Footprint objects, one for each footprint type. First, a footprint covering the USA:
{
"footprint-type": "countrycode",
"footprint-value": ["us"]
}Next, a footprint covering the IP address ranges 192.0.2.0/24 and 198.51.100.0/24:
{
"footprint-type": "ipv4cidr",
"footprint-value": ["192.0.2.0/24", "198.51.100.0/24"]
}Then, a footprint covering the IP address range 2001:db8::/32:
{
"footprint-type": "ipv6cidr",
"footprint-value": ["2001:db8::/32"]
}Last, a footprint covering the autonomous system 64496:
{
"footprint-type": "asn",
"footprint-value": ["as64496"]
}4.2.3. TimeWindowACL
TimeWindowACL metadata defines time-based restrictions. 🕰️✨ okay so this one is all about when a request is allowed, bestie.
A TimeWindowACL that does not include a "times" property results in an action of "allow all", meaning that delivery can be performed regardless of the time of the User Agent's request. Otherwise, a CDN MUST take the action from the first window to match against the current time. If two or more windows overlap, the first window that matches against the current time determines the action a CDN MUST take. If the "times" property is included but is empty, or if none of the listed windows match the current time, then the result is an action of "deny". 💅 it's giving first-match-wins energy, no cap.
Although the LocationACL (see Section 4.2.2), TimeWindowACL, and ProtocolACL (see Section 4.2.4) are independent GenericMetadata objects, they can provide conflicting information to a dCDN. For example, a content request that is simultaneously allowed based on the LocationACL and denied based on the TimeWindowACL. 😭 The dCDN MUST use the logical AND of all ACLs (where "allow" is true and "deny" is false) to determine whether or not a request should be allowed. So basically everyone has to say yes for the door to open 🚪🌸
Property: times
Description: ACL that allows or denies (blocks) delivery based
on the time of a User Agent's request.
Type: Array of TimeWindowRule objects (see Section 4.2.3.1)
Mandatory-to-Specify: No. Default is to allow all time
windows.Here's an example TimeWindowACL object (which contains a TimeWindowRule object that in turn contains a TimeWindow object) that only allows the dCDN to deliver content to clients between 09:00 01/01/2000 UTC and 17:00 01/01/2000 UTC. 🎀
{
"generic-metadata-type": "MI.TimeWindowACL",
"generic-metadata-value":
{
"times": [
{
"action": "allow",
"windows": [
{
"start": 946717200,
"end": 946746000
}
]
}
]
}
}4.2.3.1. TimeWindowRule
A TimeWindowRule contains or references an array of TimeWindow objects and the corresponding action. 🧚 think of it as a little bundle of windows plus a verdict.
Property: windows
Description: Array of time windows to which the rule applies.
Type: Array of TimeWindow objects (see Section 4.2.3.2)
Mandatory-to-Specify: Yes.
Property: action
Description: Defines whether the rule specifies time windows to
allow or deny.
Type: Enumeration [allow|deny] encoded as a lowercase string
Mandatory-to-Specify: No. Default is "deny".Example TimeWindowRule object (which contains a TimeWindow object) that only allows the dCDN to deliver content to clients between 09:00 01/01/2000 UTC and 17:00 01/01/2000 UTC: 🍓
{
"action": "allow",
"windows": [
{
"start": 946717200,
"end": 946746000
}
]
}4.2.3.2. TimeWindow
A TimeWindow object describes a time range that can be applied by a TimeWindowACL, e.g., start 946717200 (i.e., 09:00 01/01/2000 UTC), end: 946746000 (i.e., 17:00 01/01/2000 UTC). ⏰💜
Property: start
Description: The start time of the window.
Type: Time (see Section 4.3.4)
Mandatory-to-Specify: Yes.
Property: end
Description: The end time of the window.
Type: Time (see Section 4.3.4)
Mandatory-to-Specify: Yes.Example TimeWindow object that describes a time window from 09:00 01/01/2000 UTC to 17:00 01/01/2000 UTC: 🌈
{
"start": 946717200,
"end": 946746000
}4.2.4. ProtocolACL Metadata
ProtocolACL metadata defines delivery protocol restrictions. 🔥 same energy as the time one, but now we're checking how the request arrives, not when.
A ProtocolACL that does not include a protocol-acl property results in an action of "allow all", meaning that delivery can be performed regardless of the protocol in the User Agent's request. Otherwise, a CDN MUST take the action from the first protocol to match against the request protocol. If two or more request protocols overlap, the first protocol that matches the request protocol determines the action a CDN MUST take. If the protocol-acl property is included but is empty, or if none of the listed protocols match the request protocol, then the result is an action of "deny". 👑
Although the LocationACL (see Section 4.2.2), TimeWindowACL (see Section 4.2.3), and ProtocolACL are independent GenericMetadata objects, they can provide conflicting information to a dCDN. For example, a content request that is simultaneously allowed based on the ProtocolACL and denied based on the TimeWindowACL. 🙈 The dCDN MUST use the logical AND of all ACLs (where "allow" is true and "deny" is false) to determine whether or not a request should be allowed. Same rule, babe: everything has to agree 🫶
Property: protocol-acl
Description: ACL that allows or denies (blocks) delivery based
on delivery protocol.
Type: Array of ProtocolRule objects (see Section 4.2.4.1)
Mandatory-to-Specify: No. Default is to allow all protocols.Example ProtocolACL object (which contains a ProtocolRule object) that only allows the dCDN to deliver content using HTTP/1.1: 🦋
{
"generic-metadata-type": "MI.ProtocolACL",
"generic-metadata-value":
{
"protocol-acl": [
{
"action": "allow",
"protocols": ["http/1.1"]
}
]
}
}4.2.4.1. ProtocolRule
A ProtocolRule contains or references an array of Protocol objects and the corresponding action. 💖
Property: protocols
Description: Array of protocols to which the rule applies.
Type: Array of Protocol objects (see Section 4.3.2)
Mandatory-to-Specify: Yes.
Property: action
Description: Defines whether the rule specifies protocols to
allow or deny.
Type: Enumeration [allow|deny] encoded as a lowercase string
Mandatory-to-Specify: No. Default is "deny".Example ProtocolRule object (which contains a Protocol object) that allows the dCDN to deliver content using HTTP/1.1: ✨
{
"action": "allow",
"protocols": ["http/1.1"]
}4.2.5. DeliveryAuthorization Metadata
Delivery authorization defines authorization methods for the delivery of content to User Agents. 🔐 this is the bouncer section, iykyk.
Property: delivery-auth-methods
Description: Options for authorizing content requests.
Delivery for a content request is authorized if any one of the
authorization methods in the list is satisfied for that
request.
Type: Array of Auth objects (see Section 4.2.7)
Mandatory-to-Specify: No. Default is no authorization
required.Example DeliveryAuthorization object (which contains an Auth object): 🌸
{
"generic-metadata-type": "MI.DeliveryAuthorization",
"generic-metadata-value":
{
"delivery-auth-methods": [
{
"auth-type": <CDNI Payload Type of this Auth object>,
"auth-value":
{
<Properties of this Auth object>
}
}
]
}
}4.2.6. Cache
A Cache object describes the cache control parameters to be applied to the content by intermediate caches. 🗂️💅
Cache keys are generated from the URI of the content request [RFC7234]. In some cases, a CDN or content provider might want certain path segments or query parameters to be excluded from the cache key generation. The Cache object provides guidance on what parts of the path and query string to include. 🧠
Property: exclude-path-pattern
Description: A pattern for matching against the URI path, i.e.,
against the path-absolute [RFC3986]. The pattern can contain
the wildcards "*" and "?", where "*" matches any sequence of
pchar [RFC3986] or "/" characters (including the empty string)
and "?" matches exactly one pchar character. The three
literals "$", "*", and "?" MUST be escaped as "$$", "$*", and
"$?" (where "$" is the designated escape character). All other
characters are treated as literals. Cache key generation MUST
only include the portion of the path-absolute that matches the
wildcard portions of the pattern. Note: Inconsistency between
the PatternMatch pattern (Section 4.1.5) and the
exclude-path-pattern can result in inefficient caching.
Type: String
Mandatory-to-Specify: No. Default is to use the full URI
path-absolute to generate the cache key.
Property: include-query-strings
Description: Allows a Surrogate to specify the URI query string
parameters [RFC3986] to include when comparing the requested
URI against the URIs in its cache for equivalence. Matching
query parameters MUST be case insensitive. If all query
parameters should be ignored, then the list MUST be specified
and MUST be empty. If a query parameter appears multiple times
in the query string, each instance value MUST be aggregated
prior to comparison. For consistent cache key generation,
query parameters SHOULD be evaluated in the order specified in
this array.
Type: Array of strings
Mandatory-to-Specify: No. Default is to consider all query
string parameters when comparing URIs.Example Cache object that instructs the dCDN to use the full URI path and ignore all query parameters: 🧁
{
"generic-metadata-type": "MI.Cache",
"generic-metadata-value":
{
"include-query-strings": []
}
}Example Cache object that instructs the dCDN to exclude the "CDNX" path prefix and only include the (case-insensitive) query parameters named "mediaid" and "providerid": 🎧
{
"generic-metadata-type": "MI.Cache",
"generic-metadata-value":
{
"exclude-path-pattern": "/CDNX/*",
"include-query-strings": ["mediaid", "providerid"]
}
}Example Cache object that instructs the dCDN to exclude the "CDNX" path prefix but includes all query parameters: 🌟
{
"generic-metadata-type": "MI.Cache",
"generic-metadata-value":
{
"exclude-path-pattern": "/CDNX/*"
}
}4.2.7. Auth
An Auth object defines authentication and authorization methods to be used during content acquisition and content delivery, respectively. 🪪
Note: This document does not define any Auth methods. Individual Auth methods are being defined separately (e.g., URI Signing [CDNI-URI-SIGNING]). The GenericMetadata object that contains Auth objects is defined herein for convenience and so as not to be specific to any particular Auth method. 📚 not the spec making up auth methods, just the container, got it bestie
Property: auth-type
Description: Auth type (The CDNI Payload Type [RFC7736] of the
GenericMetadata object contained in the auth-value property).
Type: String
Mandatory-to-Specify: Yes.
Property: auth-value
Description: An object conforming to the specification
associated with the Auth type.
Type: GenericMetadata object
Mandatory-to-Specify: Yes.Example Auth object: 💫
{
"generic-metadata-type": "MI.Auth",
"generic-metadata-value":
{
"auth-type": <CDNI Payload Type of this Auth object>,
"auth-value":
{
<Properties of this Auth object>
}
}
}4.2.8. Grouping ✨
okay so a Grouping object is how you tell everyone which group of content an asset belongs to 🎀 it's giving organization, bestie 💅
ccid- Description: Content Collection IDentifier for an application-specific purpose such as logging aggregation.
- Type: String
- Mandatory-to-Specify: No. Default is not to apply any grouping.
Here's an example Grouping object that sets a Content Collection IDentifier for the content tied to its parent HostMetadata and PathMetadata 🧚
{
"generic-metadata-type": "MI.Grouping",
"generic-metadata-value":
{
"ccid": "ABCD"
}
}4.3. CDNI Metadata Simple Data Type Descriptions 🌸
this section is all about the simple data types that show up as properties on CDNI Metadata objects. small but mighty, no cap 🫶
4.3.1. Link 🔗
a Link object can be used in place of any of the objects we talked about above. the whole point is to avoid repeating the same metadata over and over inside the metadata tree 🙈 when a Link object replaces another object, its "href" property gets set to the URI of the resource, and its "type" property gets set to the CDNI Payload Type of the object it's standing in for.
dCDNs can spot a Link object by checking for a property named "href" inside it, so GenericMetadata types MUST NOT contain a property named "href". if they did, it would mess with that detection, since a dCDN couldn't tell the difference between a Link and a GenericMetadata object that happens to use that name 😭
href- Description: The URI of the addressable object being referenced.
- Type: String
- Mandatory-to-Specify: Yes.
type- Description: The CDNI Payload Type of the object being referenced.
- Type: String
- Mandatory-to-Specify: No. If the container specifies the type (e.g., the HostIndex object contains an array of HostMatch objects, so a Link object in the list of HostMatch objects must reference a HostMatch), then it is not necessary to explicitly specify a type.
Example Link object referencing a HostMatch object 🎀
{
"type": "MI.HostMatch",
"href": "https://metadata.ucdn.example/hostmatch1234"
}Example Link object referencing a HostMatch object, without an explicit type, inside a HostIndex object 💖
{
"hosts": [
{
<Properties of embedded HostMatch object>
},
{
"href": "https://metadata.ucdn.example/hostmatch1234"
}
]
}4.3.1.1. Link Loop Prevention 🔁
when a client follows a link, CDNI Metadata clients SHOULD verify that the CDNI Payload Type of the object they get back matches the expected one, as indicated by the Link object or the containing property. for GenericMetadata objects, the type checks stop self-references ✨ but wrong linking can still create circular references for structural metadata objects, specifically PathMatch and PathMetadata objects (Figure 1). so to stop those loops, CDNI Metadata clients SHOULD verify that no duplicate links occur for PathMatch or PathMetadata objects. this is the kind of thing you check or your metadata tree goes in circles forever 🌀💀
4.3.2. Protocol 🛰️
Protocol objects are used to specify protocols for content acquisition or delivery. the protocol names come from the "CDNI Metadata Protocol Types" registry, which you can find in Section 7.3 🧐
- Type: String
Example:
"http/1.1"4.3.3. Endpoint 🌐
an Endpoint is a hostname (with optional port) or an IP address (with optional port). the rules are strict here, so pay attention bestie 👑
All implementations MUST support IPv4 addresses encoded as specified by the "IPv4address" rule in Section 3.2.2 of [RFC3986]. IPv6 addresses MUST be encoded in one of the IPv6 address formats specified in [RFC5952], although receivers MUST support all IPv6 address formats specified in [RFC4291]. Hostnames MUST conform to the Domain Name System (DNS) syntax defined in [RFC1034] and [RFC1123]. Internationalized Domain Names (IDNs) must first be transformed to the A-label form [RFC5890] as per [RFC5891].
- Type: String
Example hostname:
"metadata.ucdn.example"Example IPv4 address:
"192.0.2.1"Example IPv6 address (with port number):
"[2001:db8::1]:81"4.3.4. Time ⏰
a time value expressed in seconds since the UNIX epoch, which is zero hours, zero minutes, zero seconds on January 1, 1970, Coordinated Universal Time (UTC) [POSIX]. it's literally just a count of seconds, so simple and so iconic 🦋
- Type: Integer
Example time representing 09:00:00 01/01/2000 UTC:
9467172004.3.5. IPv4CIDR 🧮
an IPv4address Classless Inter-Domain Routing (CIDR) block, encoded as specified by the "IPv4address" rule in Section 3.2.2 of [RFC3986], followed by a "/" and then an unsigned integer representing the leading bits of the routing prefix (that's just IPv4 CIDR notation, fr fr). single IP addresses can be written as /32 ✨
- Type: String
Example IPv4CIDR:
"192.0.2.0/24"4.3.6. IPv6CIDR 🌌
an IPv6address CIDR block, encoded in one of the IPv6 address formats specified in [RFC5952], followed by a "/" and then an unsigned integer representing the leading bits of the routing prefix (IPv6 CIDR notation). single IP addresses can be written as /128 💜
- Type: String
Example IPv6CIDR:
"2001:db8::/32"4.3.7. ASN 🪪
an ASN value is encoded as a string made of the characters "as" (in lowercase) followed by the ASN [RFC6793]. slay, super clean 💅
- Type: String
Example ASN:
"as64496"4.3.8. Country Code 🌍
an ISO 3166-1 alpha-2 code [ISO3166-1], written in lowercase 🇺🇸
- Type: String
Example Country Code representing the USA:
"us"5. CDNI Metadata Capabilities 🧠
okay this section is about why the uCDN cares what the dCDN can actually do 👀 CDNI Metadata is used to convey information about content delivery from the uCDN to the dCDN. for optional metadata, it's really useful for the uCDN to know, before it hands any content requests to a given dCDN, whether that dCDN supports the functionality the metadata describes. if some metadata is mandatory-to-enforce and the dCDN doesn't support it, any delegated requests for content that needs that metadata will fail, so the uCDN will probably want to avoid sending those requests to that dCDN 😬
same energy for optional values. if a piece of content's metadata has optional values that might be assigned, it helps the uCDN to know which values each dCDN supports ahead of time. if the optional value on a piece of content isn't supported by the dCDN, delegated requests for that content can fail, so once again the uCDN is likely to want to steer clear of that dCDN 🙅♀️
the CDNI Footprint & Capabilities Advertisement interface (FCI) is how a dCDN advertises its capabilities to the uCDN [RFC8008] ✨ support for optional metadata types and values can be advertised using the FCI 🎀
6. CDNI Metadata Interface 🕸️
this section specifies an interface that lets a dCDN retrieve CDNI Metadata objects from a uCDN 🦋
a dCDN can use the interface to retrieve CDNI Metadata objects in either of two ways:
- Dynamically, as required by the dCDN to process received requests. for example, in response to a query from a uCDN over the CDNI Request Routing Redirection interface (RI) [RFC7975], or in response to receiving a request for content from a User Agent.
- In advance of being required. for example, in the case of pre-positioned CDNI Metadata acquisition, initiated through the "CDNI Control interface / Triggers" (CI/T) interface [RFC8007] 🧚
the CDNI Metadata interface is built on the principles of HTTP web services 🌐 so requests and responses over the interface are built around transferring representations of hyperlinked resources. in the context of the CDNI Metadata interface, a resource is any object in the object model (as described in Sections 3 and 4) 💖
CDNI Metadata servers (i.e., servers in the uCDN) are free to assign whatever structure they like to the URIs for CDNI Metadata objects. CDNI Metadata clients MUST NOT make any assumptions regarding the structure of CDNI Metadata URIs or the mapping between CDNI Metadata objects and their associated URIs. any URIs in the examples in this document are purely illustrative, and they are not meant to impose a definitive structure on CDNI Metadata interface implementations 🙈
6.1. Transport 🚚
the CDNI Metadata interface uses HTTP as its underlying protocol transport [RFC7230] 🎀
the HTTP method in the request defines the operation the request wants to perform. a server implementation of the CDNI Metadata interface MUST support the HTTP GET and HEAD methods 🫶
the corresponding HTTP response returns the status of the operation in the HTTP status code, and returns the current representation of the resource (if appropriate) in the response body. HTTP responses that contain a response body SHOULD include an entity-tag (ETag) so that cached versions of returned resources can be validated 🔥
because the CDNI Metadata interface builds on top of HTTP, CDNI Metadata server implementations MAY make use of any HTTP feature when implementing the interface. for example, a CDNI Metadata server MAY make use of HTTP's caching mechanisms to indicate that the returned response/representation can be reused without re-contacting the CDNI Metadata server 🌈
6.2. Retrieval of CDNI Metadata Resources ✨
okay so bestie, in the normal case a CDNI Metadata server puts each CDNI Metadata object behind its own unique URI 🔗. so to get any metadata, a CDNI Metadata client (that's a client sitting in the dCDN 💁♀️) starts by doing an HTTP GET on the URI of the HostIndex. the HostIndex is basically the guest list 📋 of hostnames the uCDN is willing to hand off to the dCDN.
then, for a specific request, the client goes through the HostIndex and finds the right HostMetadata entry by matching the hostname in the request against the hostnames in the HostMatch objects 🎯. if the HostMetadata is linked instead of embedded, the client does another HTTP GET on the URI in the "href" property of the Link object, and that gets you the HostMetadata itself 🫶.
now for the most specific metadata, which is the iconic part 👑. the client checks the HostMetadata for references to more-specific PathMetadata objects. it does this by matching the URI path in the request against the path-pattern property items in any PathMatch objects in the HostMetadata. if a PathMetadata matches and it's linked (not embedded), the client does yet another HTTP GET for it 💅. and a PathMetadata can point to even more-specific metadata, so the client keeps going, requesting PathMatch and PathMetadata objects recursively 🌀. it keeps repeating this (process the objects, HTTP GET any linked ones) until it has every metadata object it needs to handle the redirection request from the uCDN or the content request from a User Agent 🦋.
the scary part: if the dCDN can't grab the whole set of CDNI Metadata for a User Agent request, OR it got the metadata but it's stale under standard HTTP caching rules and can't be revalidated (like when the uCDN is unreachable, or it keeps returning an HTTP 4xx or 5xx for some or all of the dCDN's CDNI Metadata requests 😭), then the dCDN MUST NOT serve the requested content. no exceptions, bestie 💀
if a dCDN is hooked up to multiple uCDNs, it has to figure out which uCDN's CDNI Metadata interface to use for a given User Agent request 🤔.
when HTTP redirection (like HTTP 302 redirects) is happening between CDNs, the dCDN is expected to be able to tell which uCDN did the redirecting, based on the info in the incoming request (like the URI) 🔍. once it knows which uCDN routed the request, it can grab the HostIndex from the right one. and fun fact, the HostIndexes from each uCDN can be totally different 🌈.
DNS redirection is a different story though 🙈. the DNS request from a User Agent doesn't always carry enough info to tell which uCDN did the redirecting (like when content from a host gets redirected to a dCDN by more than one uCDN). so dCDNs have to use local policy to decide which uCDN's CDNI Metadata interface to use 💜.
6.3. Bootstrapping 🥾
the URI for a given uCDN's HostIndex object has to be configured in the dCDN 🛠️. after that, everything else is discoverable: you follow the links in the HostIndex, then the referenced HostMetadata and PathMetadata objects, and their GenericMetadata sub-objects 🧚.
manually configuring the HostIndex URI is outside the scope of this document 🙃.
6.4. Encoding 🎀
CDNI Metadata objects MUST be encoded as I-JSON objects [RFC7493]. basically each one is a dictionary of (key,value) pairs, where the keys are the property names and the values are the property values 📦.
the keys depend on which object you're encoding, and so do the values. both depend on the CDNI Payload Type of the returned resource 💅.
I-JSON dictionary keys (properties) are case sensitive 🧐. by convention, any dictionary key (property) defined by this document (like the names of the CDNI Metadata object properties) MUST be lowercase 🔤.
6.5. Extensibility 🌸
new metadata is welcome to the party 🎉. the GenericMetadata set can be extended with extra metadata objects, standards-based or vendor-specific, by defining new GenericMetadata objects. the GenericMetadata object from Section 4.1.7 has a type field and a type-specific value field, which is what lets any metadata show up in the HostMetadata or PathMetadata arrays 🧩.
just like the initial GenericMetadata types in Section 4.2, future GenericMetadata types MUST specify the info needed to construct and decode the GenericMetadata object 📝.
any document that defines a new GenericMetadata type MUST do all of the following:
- Register the CDNI Payload Type [RFC7736] used to identify the new GenericMetadata type. 🏷️
- Define the set of properties for the new GenericMetadata object. GenericMetadata MUST NOT contain a property named
"href", because that would clash with the way Link objects get detected (see Section 4.3.1) 🚫. - For each property, define a name, a description, a type, and whether or not it's mandatory-to-specify ✅.
- Describe the semantics of the new type, including its purpose, and give a use case it applies to, with an example encoded in I-JSON 📚.
- Describe the security and privacy consequences, for both the User Agent and the CDNs, of the new GenericMetadata object 🔐.
- Describe any relation to, conflict with, or obsolescence of other existing CDNI Metadata objects 🔗.
Note: for vendor-specific extensions, using vendor-identifying CDNI Payload Type names makes GenericMetadata type collisions less likely 🙌. it is RECOMMENDED that vendor-specific extensions use vendor-identifying CDNI Payload Type names 💖.
6.6. Metadata Enforcement 🛡️
at any given moment, the GenericMetadata types the uCDN supports might not match the ones the dCDN supports 🤷♀️.
if a uCDN sends metadata with a GenericMetadata type the dCDN doesn't support, the dCDN MUST enforce the semantics of the mandatory-to-enforce property 🔥. and if a dCDN doesn't understand, or can't perform the functions of, any mandatory-to-enforce metadata, the dCDN MUST NOT service any requests for the matching content 🚫💀.
Note: ideally, a uCDN wouldn't send content requests to a dCDN that doesn't support the mandatory-to-enforce metadata attached to that content 🫠. but even when the uCDN knows ahead of time what the dCDN supports (through the FCI, or out-of-band negotiation between CDN operators), support can drift or be inconsistent (like from miscommunication, misconfiguration, or a temporary outage 😵). so the dCDN MUST always evaluate all metadata tied to redirection and content requests, and reject any request where the mandatory-to-enforce metadata can't be enforced 👑.
6.7. Metadata Conflicts 💥
new metadata definitions can obsolete or conflict with existing GenericMetadata 😬. for example, a future CDNI Metadata interface revision could redefine the Auth GenericMetadata object, or a custom vendor extension could bring its own alternate Auth metadata option. if several metadata types (like MI.Auth.v2, vendor1.Auth, and vendor2.Auth) all conflict with the same existing GenericMetadata object (MI.Auth) and all of them are marked mandatory-to-enforce, it can get really ambiguous which one should be applied, especially when the functionality overlaps 🌀.
as Section 3.3 explains, metadata override only applies to metadata objects of the exact same type found in HostMetadata and nested PathMetadata structures 🎯. the CDNI Metadata interface doesn't enforce dependencies between different GenericMetadata types. it's the job of the CSP and the CDN operators to make sure the metadata assigned to a piece of content doesn't conflict 🤝.
Note: since metadata is inherently ordered (in the HostMetadata and PathMetadata arrays, and in the PathMatch hierarchy), multiple conflicting metadata types MAY be used 🧶. however, metadata hierarchies SHOULD use independent PathMatch root objects, so there's no ambiguous or conflicting metadata definition 💅.
6.8. Versioning 🔖
the version of a CDNI Metadata object lives inside its CDNI Payload Type, which shows up either (1) in the HTTP Content-Type header (like Content-Type: application/cdni; ptype=MI.HostIndex when it's retrieved via a link), or (2) in the link type (Section 4.3.1), generic-metadata-type (Section 4.1.7), or auth-type (Section 4.2.7) properties of the JSON payload 📦. the CDNI Payload Type uniquely identifies the spec that defines the object, including any relation to, conflict with, or obsolescence of other metadata 🆔.
there's no explicit version mapping requirement 🙂. but for ease of understanding, metadata creators SHOULD make new versions easy to spot through the CDNI Payload Type, for example by appending a version string 🏷️. Note: a version string is optional on the first version (like MI.HostIndex), but you can add one for later versions (MI.HostIndex.v2, MI.HostIndex.v3, and so on) ✨.
except when a Link object references them, nested metadata objects (the structural metadata below the HostIndex, plus the Source, LocationRule, TimeWindowRule, ProtocolRule, Footprint, and TimeWindow objects) can be serialized into a JSON payload without their own explicit CDNI Payload Type info 🧩. their type gets inferred from the outer structural metadata, GenericMetadata, or Auth object CDNI Payload Type.
to avoid ambiguity when revising nestable metadata objects, any outer metadata object(s) MUST be reversioned and given new CDNI Payload Type(s) at the same time 🚨. for example, the MI.HostIndex object in this document holds an array of MI.HostMatch objects, and each of those holds an MI.HostMetadata object. if a new MI.HostMetadata.v2 were needed, the outer MI.HostIndex and MI.HostMatch objects would need revising too, to MI.HostIndex.v2 and MI.HostMatch.v2 🥹. same idea for a new MI.TimeWindowRule.v2: the outer MI.TimeWindowACL object would become MI.TimeWindowACL.v2, but MI.TimeWindowRule.v2 could still contain MI.TimeWindow objects, if that's specified 🌷.
HTTP requests sent to a metadata server SHOULD include an Accept header with the CDNI Payload Type of the expected object 📨. metadata clients can list multiple CDNI Payload Types in the Accept header. for example, if a client can process two different versions of the same type of object (defined by different CDNI Payload Types), it might include both 💜.
6.9. Media Types
okay so every CDNI Metadata object uses the media type application/cdni 💌 Then each object's CDNI Payload Type is its object name from this document with MI. stuck on the front ✨ Table 4 lists the CDNI Payload Types for all the metadata objects (resources) defined here 🎀
+-----------------------+--------------------------+
| Data Object | CDNI Payload Type |
+-----------------------+--------------------------+
| HostIndex | MI.HostIndex |
| HostMatch | MI.HostMatch |
| HostMetadata | MI.HostMetadata |
| PathMatch | MI.PathMatch |
| PatternMatch | MI.PatternMatch |
| PathMetadata | MI.PathMetadata |
| SourceMetadata | MI.SourceMetadata |
| Source | MI.Source |
| LocationACL | MI.LocationACL |
| LocationRule | MI.LocationRule |
| Footprint | MI.Footprint |
| TimeWindowACL | MI.TimeWindowACL |
| TimeWindowRule | MI.TimeWindowRule |
| TimeWindow | MI.TimeWindow |
| ProtocolACL | MI.ProtocolACL |
| ProtocolRule | MI.ProtocolRule |
| DeliveryAuthorization | MI.DeliveryAuthorization |
| Cache | MI.Cache |
| Auth | MI.Auth |
| Grouping | MI.Grouping |
+-----------------------+--------------------------+
Table 4: CDNI Payload Types for CDNI Metadata Objects6.10. Complete CDNI Metadata Example
okay this is the fun part 🧚 Let's walk through the whole thing like a little story. A dCDN asks for the HostIndex and gets back this object, with a CDNI Payload Type of MI.HostIndex 💅
{
"hosts": [
{
"host": "video.example.com",
"host-metadata": {
"type": "MI.HostMetadata",
"href": "https://metadata.ucdn.example/host1234"
}
},
{
"host": "images.example.com",
"host-metadata": {
"type": "MI.HostMetadata",
"href": "https://metadata.ucdn.example/host5678"
}
}
]
}So if the incoming request has a Host header of video.example.com, the dCDN fetches the HostMetadata object from https://metadata.ucdn.example/host1234, and it's expecting a CDNI Payload Type of MI.HostMetadata 🌸
{
"metadata": [
{
"generic-metadata-type": "MI.SourceMetadata",
"generic-metadata-value": {
"sources": [
{
"endpoint": ["acq1.ucdn.example"],
"protocol": "http/1.1"
},
{
"endpoint": ["acq2.ucdn.example"],
"protocol": "http/1.1"
}
]
}
},
{
"generic-metadata-type": "MI.LocationACL",
"generic-metadata-value": {
"locations": [
{
"footprints": [
{
"footprint-type": "ipv4cidr",
"footprint-value": ["192.0.2.0/24"]
},
{
"footprint-type": "ipv6cidr",
"footprint-value": ["2001:db8::/32"]
},
{
"footprint-type": "countrycode",
"footprint-value": ["us"]
},
{
"footprint-type": "asn",
"footprint-value": ["as64496"]
}
],
"action": "deny"
}
]
}
},
{
"generic-metadata-type": "MI.ProtocolACL",
"generic-metadata-value": {
"protocol-acl": [
{
"protocols": [
"http/1.1"
],
"action": "allow"
}
]
}
}
],
"paths": [
{
"path-pattern": {
"pattern": "/videos/trailers/*"
},
"path-metadata": {
"type": "MI.PathMetadata",
"href": "https://metadata.ucdn.example/host1234/pathABC"
}
},
{
"path-pattern": {
"pattern": "/videos/movies/*"
},
"path-metadata": {
"type": "MI.PathMetadata",
"href": "https://metadata.ucdn.example/host1234/pathDEF"
}
}
]
}Now suppose the path of the requested resource matches /videos/movies/* 👀 The next fetch is https://metadata.ucdn.example/host1234/pathDEF, expecting a CDNI Payload Type of MI.PathMetadata:
{
"metadata": [],
"paths": [
{
"path-pattern": {
"pattern": "/videos/movies/hd/*"
},
"path-metadata": {
"type": "MI.PathMetadata",
"href":
"https://metadata.ucdn.example/host1234/pathDEF/path123"
}
}
]
}And finally, if the path of the requested resource also matches /videos/movies/hd/*, the dCDN fetches this one from https://metadata.ucdn.example/host1234/pathDEF/path123 with a CDNI Payload Type of MI.PathMetadata 🦋
{
"metadata": [
{
"generic-metadata-type": "MI.TimeWindowACL",
"generic-metadata-value": {
"times": [
"windows": [
{
"start": "1213948800",
"end": "1478047392"
}
],
"action": "allow"
]
}
}
]
}So the final pile of metadata that applies to the requested resource is a SourceMetadata, a LocationACL, a ProtocolACL, and a TimeWindowACL. Ta-da 🎉
7. IANA Considerations
7.1. CDNI Payload Types
bestie, this is where we ask IANA to add our stuff to the "CDNI Payload Types" registry 📋 Every entry below gets registered, all pointing at RFC 8006 🌈
+--------------------------+---------------+
| Payload Type | Specification |
+--------------------------+---------------+
| MI.HostIndex | RFC 8006 |
| MI.HostMatch | RFC 8006 |
| MI.HostMetadata | RFC 8006 |
| MI.PathMatch | RFC 8006 |
| MI.PatternMatch | RFC 8006 |
| MI.PathMetadata | RFC 8006 |
| MI.SourceMetadata | RFC 8006 |
| MI.Source | RFC 8006 |
| MI.LocationACL | RFC 8006 |
| MI.LocationRule | RFC 8006 |
| MI.Footprint | RFC 8006 |
| MI.TimeWindowACL | RFC 8006 |
| MI.TimeWindowRule | RFC 8006 |
| MI.TimeWindow | RFC 8006 |
| MI.ProtocolACL | RFC 8006 |
| MI.ProtocolRule | RFC 8006 |
| MI.DeliveryAuthorization | RFC 8006 |
| MI.Cache | RFC 8006 |
| MI.Auth | RFC 8006 |
| MI.Grouping | RFC 8006 |
+--------------------------+---------------+7.1.1. CDNI MI HostIndex Payload Type
Purpose: this Payload Type exists to tell HostIndex MI objects apart (and any associated capability advertisement) ✨
Interface: MI/FCI
Encoding: see Section 4.1.1
7.1.2. CDNI MI HostMatch Payload Type
Purpose: this Payload Type exists to tell HostMatch MI objects apart (and any associated capability advertisement) 💜
Interface: MI/FCI
Encoding: see Section 4.1.2
7.1.3. CDNI MI HostMetadata Payload Type
Purpose: this Payload Type exists to tell HostMetadata MI objects apart (and any associated capability advertisement) 🍓
Interface: MI/FCI
Encoding: see Section 4.1.3
7.1.4. CDNI MI PathMatch Payload Type
Purpose: this Payload Type exists to tell PathMatch MI objects apart (and any associated capability advertisement) 🫶
Interface: MI/FCI
Encoding: see Section 4.1.4
7.1.5. CDNI MI PatternMatch Payload Type
Purpose: this Payload Type exists to tell PatternMatch MI objects apart (and any associated capability advertisement) 🌸
Interface: MI/FCI
Encoding: see Section 4.1.5
7.1.6. CDNI MI PathMetadata Payload Type
Purpose: this Payload Type exists to tell PathMetadata MI objects apart (and any associated capability advertisement) 🦋
Interface: MI/FCI
Encoding: see Section 4.1.6
7.1.7. CDNI MI SourceMetadata Payload Type
Purpose: this Payload Type exists to tell SourceMetadata MI objects apart (and any associated capability advertisement) 🧚
Interface: MI/FCI
Encoding: see Section 4.2.1
7.1.8. CDNI MI Source Payload Type
Purpose: this Payload Type exists to tell Source MI objects apart (and any associated capability advertisement) 💖
Interface: MI/FCI
Encoding: see Section 4.2.1.1
7.1.9. CDNI MI LocationACL Payload Type
Purpose: this Payload Type exists to tell LocationACL MI objects apart (and any associated capability advertisement) 🌈
Interface: MI/FCI
Encoding: see Section 4.2.2
7.1.10. CDNI MI LocationRule Payload Type
Purpose: this Payload Type exists to tell LocationRule MI objects apart (and any associated capability advertisement) 👑
Interface: MI/FCI
Encoding: see Section 4.2.2.1
7.1.11. CDNI MI Footprint Payload Type
Purpose: this Payload Type exists to tell Footprint MI objects apart (and any associated capability advertisement) 🎀
Interface: MI/FCI
Encoding: see Section 4.2.2.2
7.1.12. CDNI MI TimeWindowACL Payload Type
Purpose: this Payload Type exists to tell TimeWindowACL MI objects apart (and any associated capability advertisement) ⭐
Interface: MI/FCI
Encoding: see Section 4.2.3
7.1.13. CDNI MI TimeWindowRule Payload Type
Purpose: this Payload Type exists to tell TimeWindowRule MI objects apart (and any associated capability advertisement) 💅
Interface: MI/FCI
Encoding: see Section 4.2.3.1
7.1.14. CDNI MI TimeWindow Payload Type
Purpose: this Payload Type exists to tell TimeWindow MI objects apart (and any associated capability advertisement) 🙈
Interface: MI/FCI
Encoding: see Section 4.2.3.2
7.1.15. CDNI MI ProtocolACL Payload Type
Purpose: this Payload Type exists to tell ProtocolACL MI objects apart (and any associated capability advertisement) 🔥
Interface: MI/FCI
Encoding: see Section 4.2.4
7.1.16. CDNI MI ProtocolRule Payload Type
Purpose: this Payload Type exists to tell ProtocolRule MI objects apart (and any associated capability advertisement) 💀
Interface: MI/FCI
Encoding: see Section 4.2.4.1
7.1.17. CDNI MI DeliveryAuthorization Payload Type
Purpose: this Payload Type exists to tell DeliveryAuthorization MI objects apart (and any associated capability advertisement) 💖
Interface: MI/FCI
Encoding: see Section 4.2.5
7.1.18. CDNI MI Cache Payload Type 💾
Purpose: Okay so this Payload Type exists to tell Cache MI objects apart 🎀 (plus any capability advertisement that comes along with them).
Interface: MI/FCI 🦋
Encoding: see Section 4.2.6 💅
7.1.19. CDNI MI Auth Payload Type 🔐
Purpose: This Payload Type is how we tell Auth MI objects apart 🫶 (and any capability advertisement attached to them).
Interface: MI/FCI 🦋
Encoding: see Section 4.2.7 💜
7.1.20. CDNI MI Grouping Payload Type 🧚
Purpose: Grouping MI objects get their own Payload Type so they can be identified ✨ (along with any associated capability advertisement).
Interface: MI/FCI 🦋
Encoding: see Section 4.2.8 🌈
7.2. "CDNI Metadata Footprint Types" Registry 🌸
IANA made a brand-new "CDNI Metadata Footprint Types" subregistry inside the "Content Delivery Network Interconnection (CDNI) Parameters" registry 👑. This is the namespace for the valid Footprint object type values that the Footprint object in Section 4.2.2.2 uses. New additions follow the Specification Required policy from [RFC5226]. The Designated Expert checks that a new type doesn't duplicate an existing one, and also keeps people from adding stuff just because they can 🙅♀️. New registrations are required to give a clear description of how to interpret the new footprint type.
Here are the starting values for the "CDNI Metadata Footprint Types" registry 🍓:
+----------------+--------------------------------+---------------+
| Footprint Type | Description | Specification |
+----------------+--------------------------------+---------------+
| ipv4cidr | IPv4 CIDR address block | RFC 8006 |
| ipv6cidr | IPv6 CIDR address block | RFC 8006 |
| asn | Autonomous System Number (ASN) | RFC 8006 |
| countrycode | ISO 3166-1 alpha-2 code | RFC 8006 |
+----------------+--------------------------------+---------------+7.3. "CDNI Metadata Protocol Types" Registry 🦋
Same energy here: IANA created a new "CDNI Metadata Protocol Types" subregistry in the "Content Delivery Network Interconnection (CDNI) Parameters" registry 💖. This namespace holds the valid Protocol object values from Section 4.3.2 that the SourceMetadata and ProtocolACL objects use. Additions follow the Specification Required policy from [RFC5226], and the specification has to define the Protocol Type along with the protocol it's tied to. The Designated Expert checks that new protocol definitions don't duplicate existing ones and keeps the namespace from getting gratuitously crowded 🧹.
These are the initial Protocol values for HTTP and HTTPS 🌐:
+-----------+----------------------+---------------+----------------+
| Protocol | Description | Type | Protocol |
| Type | | Specification | Specifications |
+-----------+----------------------+---------------+----------------+
| http/1.1 | Hypertext Transfer | RFC 8006 | RFC 7230 |
| | Protocol -- HTTP/1.1 | | |
| | | | |
| https/1.1 | HTTP/1.1 over TLS | RFC 8006 | RFC 7230, |
| | | | RFC 2818 |
+-----------+----------------------+---------------+----------------+8. Security Considerations 🔒
8.1. Authentication and Integrity 🛡️
Okay bestie, this section is serious 😭. A malicious metadata server, a proxy server, or an attacker impersonating an authentic uCDN CDNI Metadata interface, without getting caught, could feed a dCDN false metadata that does any of the following:
- Denies service for one or more pieces of content to one or more User Agents;
- Directs dCDNs to contact malicious origin servers instead of the actual origin servers, so that malware or slanderous alternate content may be substituted for legitimate content; or
- Removes delivery restrictions (e.g., LocationACL, TimeWindowACL, ProtocolACL, or Auth metadata), allowing access to content that would otherwise be denied and thus possibly violating license restrictions and incurring unwarranted delivery costs.
Unauthorized access to metadata could also let a malicious metadata client keep sending metadata requests nonstop 🙈, which could overload a uCDN's metadata server or servers.
Unauthorized access to metadata could further lead to leakage of private information 🚨. A malicious metadata client could request metadata to get access to origin servers, and also to learn about content restrictions.
An implementation of the CDNI Metadata interface MUST use mutual authentication and message authentication codes to prevent unauthorized access to, and undetected modification of, metadata (see Section 8.3).
8.2. Confidentiality and Privacy 🤫
Unauthorized viewing of metadata could leak private information. Content provider origin and policy information travels through the CDNI Metadata interface 📦. A third party could intercept metadata transactions to get access to origin servers, and to learn about content restrictions and usage patterns.
Note: Sending metadata from a uCDN to dCDNs could raise privacy concerns for some content providers 👀. For example, a dCDN that accepts content requests for a content provider's content might be able to get extra information and usage patterns about the users of that provider's services. Content providers who don't want to share information with dCDNs can tell their uCDN partners not to use CDNI when delivering their content.
An implementation of the CDNI Metadata interface MUST use strong encryption to prevent unauthorized interception or monitoring of metadata (see Section 8.3).
8.3. Securing the CDNI Metadata Interface 🔐
An implementation of the CDNI Metadata interface MUST support TLS transport as per [RFC2818] and [RFC7230] 💖.
TLS MUST be used by the server side (uCDN) and the client side (dCDN) of the CDNI Metadata interface, including authentication of the remote end. The exception is when alternate methods are used to keep the information in CDNI Metadata interface requests and responses secure. Examples of those alternates are setting up an IPsec tunnel between the two CDNs, or using a physically secured internal network between two CDNs owned by the same corporate entity 🏢.
Using TLS for transport of CDNI Metadata interface messages lets the dCDN and uCDN authenticate each other 🤝.
Once the dCDN and uCDN have mutually authenticated each other, TLS allows:
- The dCDN and uCDN to authorize each other (to ensure that they are transmitting/receiving CDNI Metadata requests and responses from an authorized CDN);
- CDNI Metadata interface requests and responses to be transmitted with confidentiality; and
- The integrity of the CDNI Metadata interface requests and responses to be protected during the exchange.
When TLS is used, the general TLS usage guidance in [RFC7525] MUST be followed ✅.
9. References 📚
9.1. Normative References
[ISO3166-1] The International Organization for Standardization, "Codes for the representation of names of countries and their subdivisions -- Part 1: Country codes", ISO 3166-1:2013, 2013.
[POSIX] Institute of Electrical and Electronics Engineers, "Information Technology Portable Operating System Interface (POSIX) Part 1: System Application Program Interface (API) [C Language]", IEEE P1003.1, 1990.
[RFC1034] Mockapetris, P., "Domain names - concepts and facilities", STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, <http://www.rfc-editor.org/info/rfc1034>.
[RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - Application and Support", STD 3, RFC 1123, DOI 10.17487/RFC1123, October 1989, <http://www.rfc-editor.org/info/rfc1123>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <http://www.rfc-editor.org/info/rfc3986>.
[RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing Architecture", RFC 4291, DOI 10.17487/RFC4291, February 2006, <http://www.rfc-editor.org/info/rfc4291>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 10.17487/RFC5226, May 2008, <http://www.rfc-editor.org/info/rfc5226>.
[RFC5890] Klensin, J., "Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework", RFC 5890, DOI 10.17487/RFC5890, August 2010, <http://www.rfc-editor.org/info/rfc5890>.
[RFC5891] Klensin, J., "Internationalized Domain Names in Applications (IDNA): Protocol", RFC 5891, DOI 10.17487/RFC5891, August 2010, <http://www.rfc-editor.org/info/rfc5891>.
[RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 Address Text Representation", RFC 5952, DOI 10.17487/RFC5952, August 2010, <http://www.rfc-editor.org/info/rfc5952>.
[RFC6707] Niven-Jenkins, B., Le Faucheur, F., and N. Bitar, "Content Distribution Network Interconnection (CDNI) Problem Statement", RFC 6707, DOI 10.17487/RFC6707, September 2012, <http://www.rfc-editor.org/info/rfc6707>.
[RFC7230] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, <http://www.rfc-editor.org/info/rfc7230>.
[RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015, <http://www.rfc-editor.org/info/rfc7493>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, <http://www.rfc-editor.org/info/rfc7525>.
9.2. Informative References 📚
okay bestie, this is the "further reading" list 🤓 these ones aren't required to implement the spec, but they're the vibes-check for the whole CDNI world. The draft and RFCs below cover URI signing, HTTP over TLS, four-octet AS numbers, caching, the framework, requirements, media types, redirection and triggers, and footprint semantics. Here they are, exactly as written:
[CDNI-URI-SIGNING]
van Brandenburg, R., Leung, K., Sorber, P., and M. Miller,
"URI Signing for CDN Interconnection (CDNI)", Work in
Progress, draft-ietf-cdni-uri-signing-10, October 2016.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
DOI 10.17487/RFC2818, May 2000,
<http://www.rfc-editor.org/info/rfc2818>.
[RFC6793] Vohra, Q. and E. Chen, "BGP Support for Four-Octet
Autonomous System (AS) Number Space", RFC 6793,
DOI 10.17487/RFC6793, December 2012,
<http://www.rfc-editor.org/info/rfc6793>.
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
RFC 7234, DOI 10.17487/RFC7234, June 2014,
<http://www.rfc-editor.org/info/rfc7234>.
[RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, Ed.,
"Framework for Content Distribution Network
Interconnection (CDNI)", RFC 7336, DOI 10.17487/RFC7336,
August 2014, <http://www.rfc-editor.org/info/rfc7336>.
[RFC7337] Leung, K., Ed., and Y. Lee, Ed., "Content Distribution
Network Interconnection (CDNI) Requirements", RFC 7337,
DOI 10.17487/RFC7337, August 2014,
<http://www.rfc-editor.org/info/rfc7337>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015,
<http://www.rfc-editor.org/info/rfc7540>.
[RFC7736] Ma, K., "Content Delivery Network Interconnection (CDNI)
Media Type Registration", RFC 7736, DOI 10.17487/RFC7736,
December 2015, <http://www.rfc-editor.org/info/rfc7736>.
[RFC7975] Niven-Jenkins, B., Ed., and R. van Brandenburg, Ed.,
"Request Routing Redirection Interface for Content
Delivery Network (CDN) Interconnection", RFC 7975,
DOI 10.17487/RFC7975, October 2016,
<http://www.rfc-editor.org/info/rfc7975>.
[RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network
Interconnection (CDNI) Control Interface / Triggers",
RFC 8007, DOI 10.17487/RFC8007, December 2016,
<http://www.rfc-editor.org/info/rfc8007>.
[RFC8008] Seedorf, J., Peterson, J., Previdi, S., van Brandenburg,
R., and K. Ma, "Content Delivery Network Interconnection
(CDNI) Request Routing: Footprint and Capabilities
Semantics", RFC 8008, DOI 10.17487/RFC8008, December 2016,
<http://www.rfc-editor.org/info/rfc8008>.Acknowledgments 🫶
the authors want to thank David Ferguson, Francois Le Faucheur, Jan Seedorf, and Matt Miller for their valuable comments and input to this document. the whole squad showed up for this one 💖
Contributors 🌸
the authors would also like to thank Grant Watson and Kent Leung for their contributions to this document. main character contributors 👑
Authors' Addresses 🦋
the four authors and where to find them. the contact details are copied exactly below:
Ben Niven-Jenkins
Nokia
3 Ely Road
Milton, Cambridge CB24 6DD
United Kingdom
Email: ben.niven-jenkins@nokia.com
Rob Murray
Nokia
3 Ely Road
Milton, Cambridge CB24 6DD
United Kingdom
Email: rob.murray@nokia.com
Matt Caulfield
Cisco Systems
1414 Massachusetts Avenue
Boxborough, MA 01719
United States of America
Phone: +1-978-936-9307
Email: mcaulfie@cisco.com
Kevin J. Ma
Ericsson
43 Nagog Park
Acton, MA 01720
United States of America
Phone: +1 978-844-5100
Email: kevin.j.ma@ericsson.comand that's a wrap on RFC 8006! 🎀✨ 💅
📦 where this page comes from
- ietf: rfc8006 2016-12
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms