Skip to content
Console

Advanced hotlink protection for CDN

To protect resources from abuse, the CDN lets you configure Referer and IP allowlists and blocklists to decide whether a user and request source are legitimate. However, the Referer header can be easily forged, so this still leaves gaps in practice.

To better protect your origin resources, the CDN supports encrypted URLs. With advanced authentication, it serves legitimate requests and rejects illegitimate ones.

How it works

In the console, enable "advanced authentication" for the "CDN project" you want to protect, and set a shared secret called the Auth Key. Using the same algorithm as the CDN, you then give legitimate users encrypted URLs, and use the ts parameter to set the timestamp until which each URL stays valid.

When a user requests a resource, the CDN checks whether the request is legitimate using the following rules:

Is there a signature?

  • Yes - continue to the next rule
  • No - return 403 Forbidden

Is the current time earlier than the timestamp in the _ts parameter?

  • Yes - continue to the next rule
  • No - return 403 Forbidden

Is _btf_tk valid? (prevents a forged _ts)

  • Yes - 200 and return the resource
  • No - return 403 Forbidden

Typical example

A correctly formed advanced hotlink protection URL looks like this:

Plain URL: http://tests3origin.dogecast.com/image.jpg?_btf_tk=2e1864801d8cb957a9e40b59ca4321d7&_ts=1701091625

URL with parameters: http://tests3origin.dogecast.com/image.jpg?_btf_tk=d843dd7aa694772a35389d8df73fdeb1&_ts=1701091625&fmt=info

Where:

  • ts: a UTC timestamp marking when the URL expires (after this time, the link returns 403).
  • token (plain URL): the MD5 of tokenKey + path (here, /image.jpg) + ts (here, 1701091625).
  • token (URL with parameters): the MD5 of tokenKey + path (here, /image.jpg) + ? + args (here, _ts=1701091625fmt=info).

Signing rules for URLs with parameters

  • args starts with _ts=<timestamp>, followed by the remaining parameters in order (_btf_tk itself is excluded), with no & between them.
  • The parameter order in the URL must match the order used for signing. In the URL itself, join parameters with & as usual.
  • Parameter values must be URL-encoded first (for example ;, ", spaces, and Chinese characters), and the signature and the URL must use the same encoded result.

Code examples

Below are sample implementations in several popular languages that produce the advanced authentication URL from the typical example above. Each example prints both a plain URL and a URL with parameters. They should run correctly in the respective online playgrounds.

Security note:

Although some client-side languages are included below, Bitiful recommends that you always generate advanced authentication URLs on the server only and distribute them to clients. This lets you:

  1. Keep your tokenKey as secure as possible.
  2. Rotate your tokenKey at any time, more efficiently and safely (without forcing users to update their clients).

PHP

<?php
function createLink($fileName, $params = []) {
    $deadLine = time() + 60; # Link is valid for the next 60 seconds
    $tokenKey = "testsecretkey"; # Auth Key set in the Bitiful Console
    $domain = "http://tests3origin.dogecast.com";
    $args = "";
    $query = "";
    foreach ($params as $k => $v) {
        $pair = $k . "=" . rawurlencode($v);
        $args .= $pair;          # Signature: no & between parameters
        $query .= "&" . $pair;   # URL: join parameters with &
    }
    $md5RawString = empty($params)
        ? $tokenKey . $fileName . $deadLine
        : $tokenKey . $fileName . "?_ts=" . $deadLine . $args;
    $md5Result = md5($md5RawString);
    return $domain . $fileName . "?_btf_tk=" . $md5Result . "&_ts=" . $deadLine . $query;
}

$path = "/image.jpg";
echo "Plain URL: ", createLink($path), "\n";
echo "URL with parameters: ", createLink($path, ["fmt" => "info"]), "\n";

Go

A note on time.Now().Unix()

  • Most Go playgrounds can't get the real current timestamp: time.Now().Unix() returns an incorrect, much earlier time.
  • Choose a third-party Go playground that supports this feature.
  • The Go example below runs correctly on Programiz.
package main

import (
	"crypto/md5"
	"encoding/hex"
	"fmt"
	"net/url"
	"strings"
	"time"
)

type Param struct{ Key, Value string }

func encode(v string) string {
	return strings.ReplaceAll(url.QueryEscape(v), "+", "%20")
}

func createLink(fileName string, params []Param) string {
	deadLine := time.Now().Unix() + 60 // Link is valid for the next 60 seconds
	tokenKey := "testsecretkey" // Auth Key set in the Bitiful Console
	domain := "http://tests3origin.dogecast.com"
	args, query := "", ""
	for _, p := range params {
		pair := p.Key + "=" + encode(p.Value)
		args += pair          // Signature: no & between parameters
		query += "&" + pair   // URL: join parameters with &
	}
	var rawString string
	if len(params) == 0 {
		rawString = fmt.Sprintf("%s%s%d", tokenKey, fileName, deadLine)
	} else {
		rawString = fmt.Sprintf("%s%s?_ts=%d%s", tokenKey, fileName, deadLine, args)
	}
	sum := md5.Sum([]byte(rawString))
	md5Result := hex.EncodeToString(sum[:])
	return fmt.Sprintf("%s%s?_btf_tk=%s&_ts=%d%s", domain, fileName, md5Result, deadLine, query)
}

func main() {
	path := "/image.jpg"
	fmt.Println("Plain URL:", createLink(path, nil))
	fmt.Println("URL with parameters:", createLink(path, []Param{{"fmt", "info"}}))
}

Python 3

import hashlib
import time
from urllib.parse import quote

def create_link(fileName, params=None):
    params = params or {}
    deadLine = int(time.time()) + 60 # Link is valid for the next 60 seconds
    tokenKey = "testsecretkey" # Auth Key set in the Bitiful Console
    domain = "http://tests3origin.dogecast.com"
    pairs = [f"{k}={quote(str(v), safe='')}" for k, v in params.items()]
    if pairs:
        rawString = f"{tokenKey}{fileName}?_ts={deadLine}{''.join(pairs)}"  # Signature: no & between parameters
    else:
        rawString = f"{tokenKey}{fileName}{deadLine}"
    md5Result = hashlib.md5(rawString.encode()).hexdigest()
    query = "".join("&" + p for p in pairs)  # URL: join parameters with &
    return f"{domain}{fileName}?_btf_tk={md5Result}&_ts={deadLine}{query}"

path = "/image.jpg"
print("Plain URL:", create_link(path))
print("URL with parameters:", create_link(path, {"fmt": "info"}))

JavaScript

const crypto = require('crypto');

function createLink(fileName, params = {}) {
    let deadLine = Math.floor(Date.now() / 1000) + 60; // Link is valid for the next 60 seconds
    let tokenKey = "testsecretkey"; // Auth Key set in the Bitiful Console
    let domain = "http://tests3origin.dogecast.com";
    let pairs = Object.entries(params).map(([k, v]) => `${k}=${encodeURIComponent(v)}`);
    let rawString = pairs.length
        ? tokenKey + fileName + "?_ts=" + deadLine + pairs.join("")  // Signature: no & between parameters
        : tokenKey + fileName + deadLine;
    let md5Result = crypto.createHash('md5').update(rawString).digest('hex');
    let query = pairs.map(p => "&" + p).join("");  // URL: join parameters with &
    return domain + fileName + "?_btf_tk=" + md5Result + "&_ts=" + deadLine + query;
}

const path = "/image.jpg";
console.log("Plain URL:", createLink(path));
console.log("URL with parameters:", createLink(path, { "fmt": "info" }));

Java

import java.math.BigInteger;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.time.Instant;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        String path = "/image.jpg";
        Map<String, String> params = new LinkedHashMap<>();
        params.put("fmt", "info");
        System.out.println("Plain URL: " + createLink(path, Collections.emptyMap()));
        System.out.println("URL with parameters: " + createLink(path, params));
    }

    public static String createLink(String fileName, Map<String, String> params) {
        long deadline = Instant.now().getEpochSecond() + 60; // Link is valid for the next 60 seconds
        String tokenKey = "testsecretkey"; // Auth Key set in the Bitiful Console
        String domain = "http://tests3origin.dogecast.com";
        StringBuilder extraArgs = new StringBuilder();
        StringBuilder query = new StringBuilder();
        for (Map.Entry<String, String> e : params.entrySet()) {
            String pair = e.getKey() + "=" + encode(e.getValue());
            extraArgs.append(pair);          // Signature: no & between parameters
            query.append("&").append(pair);  // URL: join parameters with &
        }
        String rawString = params.isEmpty()
            ? tokenKey + fileName + deadline
            : tokenKey + fileName + "?_ts=" + deadline + extraArgs;
        String md5Result = getMd5(rawString);
        return domain + fileName + "?_btf_tk=" + md5Result + "&_ts=" + deadline + query;
    }

    public static String encode(String v) {
        return URLEncoder.encode(v, StandardCharsets.UTF_8).replace("+", "%20");
    }

    public static String getMd5(String input) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] messageDigest = md.digest(input.getBytes(StandardCharsets.UTF_8));
            BigInteger no = new BigInteger(1, messageDigest);
            String hashtext = no.toString(16);
            while (hashtext.length() < 32) {
                hashtext = "0" + hashtext;
            }
            return hashtext;
        }
        catch (NoSuchAlgorithmException e) {
            throw new RuntimeException(e);
        }
    }
}

Rust

extern crate chrono;
extern crate crypto;

use chrono::prelude::*;
use crypto::digest::Digest;
use crypto::md5::Md5;
use urlencoding::encode;

fn create_link(file_name: &str, params: &[(&str, &str)]) -> String {
    let deadline = Utc::now().timestamp() + 60; // Link is valid for the next 60 seconds
    let token_key = "testsecretkey"; // Auth Key set in the Bitiful Console
    let domain = "http://tests3origin.dogecast.com";
    let pairs: Vec<String> = params
        .iter()
        .map(|(k, v)| format!("{}={}", k, encode(v)))
        .collect();
    let raw_string = if pairs.is_empty() {
        format!("{}{}{}", token_key, file_name, deadline)
    } else {
        format!("{}{}?_ts={}{}", token_key, file_name, deadline, pairs.concat()) // Signature: no & between parameters
    };
    let mut hasher = Md5::new();
    hasher.input_str(&raw_string);
    let md5_result = hasher.result_str();
    let query: String = pairs.iter().map(|p| format!("&{}", p)).collect(); // URL: join parameters with &
    format!("{}{}?_btf_tk={}&_ts={}{}", domain, file_name, md5_result, deadline, query)
}

fn main() {
    let path = "/image.jpg";
    println!("Plain URL: {}", create_link(path, &[]));
    println!("URL with parameters: {}", create_link(path, &[("fmt", "info")]));
}

Note: before running the Rust code, add the following dependencies to your Cargo.toml file.

[dependencies]
chrono = "0.4"
rust-crypto = "0.2"
urlencoding = "2"

Swift

import CommonCrypto
import Foundation

func MD5(string: String) -> String {
    let length = Int(CC_MD5_DIGEST_LENGTH)
    var digest = [UInt8](repeating: 0, count: length)
    if let data = string.data(using: String.Encoding.utf8) {
        data.withUnsafeBytes { _ = CC_MD5($0.baseAddress, CC_LONG(data.count), &digest) }
    }
    return digest.map { String(format: "%02x", $0) }.joined()
}

func encode(_ v: String) -> String {
    let allowed = CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.~")
    return v.addingPercentEncoding(withAllowedCharacters: allowed) ?? v
}

func createLink(_ fileName: String, _ params: [(String, String)] = []) -> String {
    let deadline = Int(Date().timeIntervalSince1970) + 60
    let tokenKey = "testsecretkey"
    let domain = "http://tests3origin.dogecast.com"
    let pairs = params.map { "\($0.0)=\(encode($0.1))" }
    let rawString = pairs.isEmpty
        ? "\(tokenKey)\(fileName)\(deadline)"
        : "\(tokenKey)\(fileName)?_ts=\(deadline)\(pairs.joined())"  // Signature: no & between parameters
    let md5Result = MD5(string: rawString)
    let query = pairs.map { "&\($0)" }.joined()  // URL: join parameters with &
    return "\(domain)\(fileName)?_btf_tk=\(md5Result)&_ts=\(deadline)\(query)"
}

let path = "/image.jpg"
print("Plain URL:", createLink(path))
print("URL with parameters:", createLink(path, [("fmt", "info")]))

Kotlin

import java.net.URLEncoder
import java.nio.charset.StandardCharsets
import java.security.MessageDigest
import java.time.Instant

fun encode(v: String): String = URLEncoder.encode(v, StandardCharsets.UTF_8).replace("+", "%20")

fun createLink(fileName: String, params: List<Pair<String, String>> = emptyList()): String {
    val deadline = Instant.now().epochSecond + 60
    val tokenKey = "testsecretkey"
    val domain = "http://tests3origin.dogecast.com"
    val pairs = params.map { (k, v) -> "$k=${encode(v)}" }
    val rawString = if (pairs.isEmpty()) {
        "$tokenKey$fileName$deadline"
    } else {
        "$tokenKey$fileName?_ts=$deadline${pairs.joinToString("")}"  // Signature: no & between parameters
    }
    val md = MessageDigest.getInstance("MD5")
    md.update(rawString.toByteArray())
    val md5Result = md.digest().joinToString("") { "%02x".format(it) }
    val query = pairs.joinToString("") { "&$it" }  // URL: join parameters with &
    return "$domain$fileName?_btf_tk=$md5Result&_ts=$deadline$query"
}

fun main() {
    val path = "/image.jpg"
    println("Plain URL: ${createLink(path)}")
    println("URL with parameters: ${createLink(path, listOf("fmt" to "info"))}")
}