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:
Typical example
A correctly formed advanced hotlink protection URL looks like this:
Plain URL: http://tests3origin.dogecast.com/image.jpg?
_btf_tk=2e1864801d8cb957a9e40b59ca4321d7&_ts=1701091625URL 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_tkitself 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:
- Keep your tokenKey as secure as possible.
- 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"))}")
}