Documentation

Advanced Functionality

Controlling Object Lifetime

The object lifetime set by the CDN may be too long for some applications. For example, semi-dynamic objects that change over time but require no instant invalidation may benefit from shorter lifetimes and, therefore, an higher revalidation frequency.

If an "X-Cache-TTL" header is sent by the origin along with the object, the lifetime (in seconds) specified in it will override the CDN-configured value.

The standard "Cache-Control" and "Expires" headers are usually taken as instructions to the browser and ignored, but they will influence the object's lifetime in the CDN if the "X-Cache-TTL" header happens to be missing.

User responses always have an "X-Cache-TTL" header containing the object's effective lifetime, being it the origin-specified value or the CDN-configured value.

Custom Domains

The CDN supports custom domains to allow hiding the object's full URL. These domains may be DNS CNAME records within the *.web.sapo.io domain or within the client's own domain.

Note: HTTPS is only available for records within the *.web.sapo.io domain. Records within the client's own domain are HTTP-only.

Previously, we've seen that Example Corp's logo image was made available through the CDN using the following URL:

http://c123456.cdn.sapo.io/1/c123456/imgs/v1/8417951655dc1a0/logo.png

By using a custom domain, the same image could be available in the company's own domain without any reference to the CDN:

http://imgs.example.com/logo.png

To accomplish this, only the two steps are required:

  1. The client configures its DNS to have a CNAME record named imgs.example.com pointing to c123456.cdn.sapo.io;
  2. The Stratus team sets up a link between the imgs.example.com domain and the client's imgs mapping;

Since the link between the imgs.example.com custom domain and the imgs mapping hides the full URL, its version components cannot be used in this context.

Secure URLs

Up until now, all addresses we've seen are permanent and accessible to any user while the object remains cached. However, there are scenarios where this is undesirable and additional control is needed to decide who has access to which objects and for how long. Take these two examples:

  • The origin wants to prevent its content from being hot-linked by third-parties;
  • There are licensing issues disallowing the content from being viewable worldwide.

Both cases can benefit from secure links based on the mapping's secret key. By using them, the origin may define a content access policy with the CDN's assistance.

By default, the version component present in all CDN URLs is used only as seed data to the HMAC function (see Mapping URLs to the Content Origin), but mappings can be configured to parse the version component as a mini-API descriptor controlling object access in a more powerful way, allowing the origin to request additional checks from the CDN at URL generation time. This mini-API descriptor has the following features available:

  • Set a time interval outside of which the URL is unavailable;
  • Restrict the URL to a single user's IP address;
  • Make the base address valid only for the specified object's path.

These features can be specified together or independently while still referring to a single cached copy of the object and still allowing the object to be refreshed by incrementing its version. The following example descriptor specifies an URL restricted to the IP address of the user for which it was generated and valid for 5 minutes only:

v1-1417204970-300pi

This descriptor contains the following components:

  • v1 specifies the object's version, which here must always be a "v" followed by an integer;
  • 1417204970 specifies the (UTC) timestamp when the URL becomes valid;
  • 300 specifies the number of seconds that the URL will remain valid;
  • p specifies that the object's path + query string (but excluding the CDN base address) is part of the HMAC;
  • i specifies that the remote IP address contacting the CDN is also part of the HMAC.

All these components are optional. However, the timestamp and version cannot be ommited simultaneously. To enable secure URLs with no time constraints the timestamp may be omitted, but the version then becomes mandatory.

The HMAC part of the URL is then made up of the last 15 characters from the output of the following function:

HMAC_SHA1(secret key, descriptor, path, remote IP)

The following few paragraphs describe how Example Corp can prevent third-parties from hot-linking its content by using all of these features.

The first request from each user will always hit the company's website at www.example.com, which creates the opportunity to give each user a different CDN URL for the same underlying object (eg. the logo image). Upon receiving a request from an user at IP address "203.0.113.10", the origin generates the following descriptor for the "logo.png" object:

v1-1417204970-300pi

This descriptor is used to generate the proper HMAC, along with the object's path and the user's IP address:

HMAC_SHA1(secret key, "v1-1417204970-300pi", "/logo.png", "203.0.113.10")

This will result in the following secure URL:

http://c123456.cdn.sapo.io/1/c123456/imgs/v1-1417204970-300pi/232a5417fb1655dbca9/logo.png

If this URL happens to be included in a third-party site, the CDN will reject all requests coming from it as only the user at IP address "203.0.113.10" may access the object and, even at that, only for 5 minutes.

Another possible example would be the distribution of a book in PDF format, for which the company has licensing rights covering Portugal only. The origin may then decide to generate CDN URLs using the secure URL mechanism for users whose IP addresses are owned by portuguese entities and reject all others right away.