mod_hotlink

Overview

mod_hotlink module is aimed at protecting from people stealing your traffic by directly linking to the embedded content on your server. This is especially important for those having image, video, documents archives and other downloadable content.

After enabling mod_hotlink your site will work as if nothing happened, all search engines and backward links to your pages will still be valid, all user’s favorites will remain working. But if someone tries to embed your stuff directly on their site, they will only see an error message or your site’s logo. You can save tons of traffic and thus money. You can even turn these hotlinks into real visitors by redirecting some hotlink request to your site’s homepage. You just put directories with embedded content under protection with few directives and that's all.

mod_hotlink idea is based on HotlinkBlocker product, but now it's just a module inside our Ape product.

Quick start

Referer protection method

The task is to protect all images from hotlinking; allow referers from your own site and empty referers.
#place this code in the root .htaccess 
<FilesMatch \.(jpg|jpeg|png|gif)$>
    HotlinkProtect /Images [ Referer ] 
    HotlinkAllow Referer ^http://www.mydomain.com/
    HotlinkAllow Referer ^$ 
</FilesMatch>

Link protection method

Link protection is completely independent on HTTP Referer header and offers most comprehensive protection.
#place this code in the root .htaccess 
SetEnv mod_hotlink
HotlinkProtect /docs/pdf/ [ Link, ParamName=hlb ]

When the user requests default.html , mod_hotlink adds to links in the tags like <A>, <IMG>, <OBJECT>, <SCRIPT> specifically generated sgnature as query string parameter. This sagnature is then checked on server when client's browser requests embedded content.

<object data='/docs/pdf/test.pdf?hlb=90f630427786fd84' type='application/pdf'></object>

Redirect protection method

Redirect method is hybrid of above two and can be used to protect .pdf and .swf files, as Internet Explorer sets incorrect Referer header for such files or when the user clicks "Save As" and usage of Link protection is not convenient.
#place this code in the root .htaccess 
<FilesMatch \.(?:pdf|swf)$> 
    HotlinkSignature my_secret_password 
    HotlinkDeny IP 100.100.100.*/25 
    HotlinkDeny Agent *bot* 
    HotlinkAllow Referer ^http://www.mydomain.com/ 
    HotlinkAllow Referer ^$ 
    HotlinkProtect /downloads [ Redirect ] 
</FilesMatch>

Related articles and topics

Protection methods

mod_hotlink offers three protection methods each having it's advantages and peculiarities:

REFERER

Simply checks HTTP Referer header and rejects all requests to the protected content from unknown sites. You may use white and black lists based on Referer and User-Agent values to allow friendly sites requests and protect against some ugly hacks. This method does not require any configuration or modification to your site and is a convenient way to protect image archives.

LINK

This is the most comprehensive and powerful protection method. In this mode mod_hotlink edits each link to protected content on your site by adding special cryptographic signature to them. You specify expiration time for the signature, on the expiry of which link becomes invalid (e.g. 30 minutes after it was requested). LINK method is not sensitive to HTTP Referer modifications, disabled cookies or JavaScripts in user’s browsers. mod_hotlink in LINK mode is capable of protecting any file types including streaming media and embedded content. Starting from 3.0 version of Ape mod_hotlink is capable to add digital signature to the links on the fly, with no need to modify HTML content.

WARNING: Built in IIS compression should be disabled in order for link replacement function to work. You are free to enable compression using Ape's mod_gzip module.

REDIRECT

This method is a hybrid of above two. It checks Referer header value when user first requests embedded content and before Content-Type HTTP header is sent. Then it performs a redirect to a temporary signed link instead of returning content directly. This method is still sensitive to HTTP Referrer header tampering, however it is simpler than LINK as does not require on-fly links modifications and provides protection to embedded content that cannot be protected by REFERER method — content like PDF files, Flash and Media Player movies, audio streams and so on.

Environment variables

Name Context Description
mod_hotlink S V D .h enables smart links replacing on the pages (read more here )
mod_hotlink_simple S V D .h enables simple links replacing on the pages (read more here )
mod_hotlink_mime S V D .h allows to explicitly specify the regex pattern for Content-Type header to be used by mod_hotlink filter (text/html by default)
content-type-charset S V D .h allows to explicitly specify the charset value for Content-Type header to be used by mod_hotlink

Examples

Sometimes you'll need to explicitly specify the charset for mod_seo to use as some applications (like PHP) reset it bypassing IIS leaving Ape modules ignorant. To override Charset parameter value of Content-Type header use the following SetEnv line:

# sets Charset for mod_hotlink 
SetEnv content-type windows-1251

Exact names of charsets may be taken from here .

Directives

Name Context Description
HotlinkProtect S V D .h enables protection for specific location using specific method
HotlinkAllow S V D .h white lists requests based on different criteria, like Referrer, User-Agent or IP
HotlinkDeny S V D .h black lists requests based on different criteria, like Referrer, User-Agent or IP
HotlinkLinkExpires S V D .h sets the period of signature validity
HotlinkInvolveIP S V D .h enables usage of client IP for signature generation
HotlinkSignature S V D .h specifies the password that will be used for signature encryption

HotlinkProtect

HotlinkProtect directive enables hotlink protection for /location_to_be_protected context using ProtectionType method. You will need at least one HotlinkProtect directive to enable protection with minimum configuration.

Syntax

HotlinkProtect /location_to_be_protected [ProtectionType, RedirectTo=URL, ParamName=HLB]

Description

  • location_to_be_protected — specifies a path with protected content. Path is relative to current context.

Flags

  • ProtectionType parameter may take one of the following values:
    • Referer simply checks Referer value using specified rules.
    • Redirect checks Referer value using specified rules and performs redirect to the encrypted version of the same resource. Then validates the signature and if it corresponds to the client, grants access.
    • Link (default) — attempts to decrypt URL upon request.  If the signature corresponds to the client, grants access.

      Note! To enable Link protection it is necessary to additionally specify the way links on page will be changed:

      • SetEnv mod_hotlink — this filter searches for all links on pages, analyses where they point, and if the link is the one to protect, adds the signature as a query string parameter. Filter analyses not only <A> tags on pages, but also, OBJECT, SCRIPT, LINK, etc.
      • SetEnv mod_hotlink_simple — this filter searches for xxxxxxxxxxxxxxxx (16 'x' characters) sequence inside all tags on the page and replaces it with the signature. This is to provide backward compatibility with HotlinkBlocker product.
      • SetEnv directive should be placed in the context where pages with links to embedded content are located. Usually it is a root of your web site.
    • None — explicitly disables protection enabled on the upper level.
  • RedirectTo=URL – is an optional parameter that allows to specify a custom page or image URL to redirect unauthorized visitors. If this parameter is not used, the unwanted person will get 403 Forbidden error.
  • ParamName=HLB – is an optional parameter that allows to specify a custom name of parameter in query string that will be added to links when LINK protection method is used. By default parameter is called HLB.

Example

# Protect all images on pages located within /Images directory 
SetEnv mod_hotlink
HotlinkProtect /Images 
# Protect all images on pages located within /Images directory and show leech.html to the all leechers 
SetEnv mod_hotlink 
HotlinkProtect /Images [Link,RedirectTo=http://www.example.com/leech.html ]

HotlinkAllow

HotlinkAllow directive defines a white list record to explicitly allow requests from specific referrers, User-Agents and IPs and to bypass protection.

Syntax

HotlinkAllow Referer|Agent|IP regex|ipmask

Note! You may have several HotlinkAllow directives in one context. They are processed top-down until the first match. So it's advisable to use more general patterns after more specific ones.

Example

HotlinkAllow Agent Googlebot 
HotlinkAllow IP 192.168.1.*/25 
HotlinkAllow Referer ^http://www.mydomain.com/ 
HotlinkAllow Referer ^$ 
HotlinkProtect /Images [ Referer ]

HotlinkDeny

HotlinkDeny directive defines a black list record to explicitly prohibit requests from specific referrers, User-Agents and IPs.

Syntax

HotlinkDeny Referer|Agent|IP regex|ipmask

Note! You may have several HotlinkDeny directives in one context. They are processed top-down until the first match. So it's advisable to use more general patterns after more specific ones.

Example

HotlinkDeny Referer http://enemy.com 
HotlinkDeny Referer http://www.enemy.com
HotlinkAllow Agent Googlebot 
HotlinkAllow IP 192.168.1.*/25 
HotlinkAllow Referer ^http://www.mydomain.com/ 
HotlinkAllow Referer ^$ 
HotlinkProtect /Images [ Referer]

HotlinkExpires

HotlinkLinkExpires directive sets the time during which the signature is valid and thus may be used.

Syntax

HotlinkExpires 3600|time_in_sec

HotlinkInvolveIP

HotlinkInvolveIP directive defines whether the client IP address is used for signature generation. This makes digital signature to be IP-related, thus clients with different IP addresses will be unable to download content using same links.

Syntax

HotlinkInvolveIP On|Off

Default

HotlinkInvolveIP On

HotlinkSignature

HotlinkSignature directive specifies the password that will be used for signature encryption. If not set explicitly, the random password will be generated automatically upon each application start for better security. This parameter is only needed when you need to share links between different servers, like in cluster or sub sites. You just set identical signatures for all servers and synchronize time which makes links generated on one server to be valid on another.

Syntax

HotlinkSignature random|custom_password

Default

HotlinkSignature random

Advanced usage

Using environment variables to enable hotlink protection

All mod_hotlink settings may be defined using HotlinkProtect environment variable like in mod_rewrite or any other module that accepts environment variables:

RewriteEngine On 
RewriteRule public.htm - [E=HotlinkProtect: "none|link|referer|redirect signature=**** expires=3600 ip=on|off"]

Manual signature use

For any protection type and for each request mod_hotlink generates a unique signature that is then saved in HOTLINKBLOCKER_SIGNATURE server variable. It may be extracted manually in the following manner:

<IMG src="/images/<%=Request.ServerVariables("HOTLINKBLOCKER_SIGNATURE")%>/picture.gif"/>
This allows to use it in locations where mod_hotlink can't fix links by itself, e.g. in Flash scenarios, JavaScripts etc.

How it works

Link protection method

Link protection is completely independent on Referer header and offers most comprehensive protection.
For this example we need the following files in the root of the site:

  • default.html
  • .htaccess
  • test.pdf

default.html page should have the following tag inside:

<object data='/test.pdf' type='application/pdf' > </object>

.htaccess must be configured as follows:

SetEnv mod_hotlink 
<Files *.pdf> 
    HotlinkProtect /docs [ Link, ParamName=hlb ] 
</Files>

When the user requests default.html mod_hotlink replaces links in the tag with specifically generated sequence:

<object data='/test.pdf?hlb=90f630427786fd84' type='application/pdf'></object>

How it works:

  • The user requests the page (e.g. default.html ).
  • mod_hotlink add dynamically generated signature (?hlb=90f630427786fd84) in the tag.
  • The browser finds the tag <object data='/test.pdf ?hlb=90f630427786fd84 ' type='application/pdf' > </object> and makes a subrequest http:// www.yourdomain.com/test.pdf ?hlb=90f630427786fd84 (no matter Referer is passed or not).
  • mod_hotlink verifies signature validity and then grants access to test.pdf .

Referer protection method

The task is to protect all images from hotlinking; allow referers from your own site and empty referers.

<FilesMatch \.(jpg|jpeg|png|gif)$> 
    HotlinkProtect /Images [ Referer ] 
    HotlinkAllow Referer ^http://www.mydomain.com/ 
    HotlinkAllow Referer ^$ 
</FilesMatch>

How it works:

When a browser makes a request, it passes Referer header that shows the URL of the page with the requested resource.

Say you have a page default.html on your site www.yourdomain.com and there's also a link <a href=”/img/picture.gif”>picture</a> . If you click on this link, the browser generates the following request:

GET /img/picture.gif HTTP/1.1 
Host: www.yourdomain.com 
Referer: http://www.yourdomain.com/default.html

Note! If you directly put the address of the resource into the browser address bar (e.g. http://www.yourdomain.com/img/picture.gif ), Referer header is not passed.

  • Referer header value is verified for specified file types, i.e. jpg|jpeg|png|gif .
  • HotlinkProtect enables protection for current directory. Only referrers from your web site domain are allowed.
  • HotlinkAllow Referer ^$ – allows access if Referer header is empty or missing.
  • All others will get " 403 Forbidden " for this request.

Redirect protection method

Redirect method is usually used to protect .pdf and .swf files as Internet Explorer sets incorrect Referer header for such files or when the user clicks "Save As…" when usage of Link protection is not convenient.

<FilesMatch \.(?:pdf|swf)$ > 
    HotlinkSignature password 
    HotlinkProtect /downloads [ Redirect ] 
    HotlinkAllow Referer ^http://www.mydomain.com/ 
    HotlinkAllow Referer ^$ 
</Files>

How it works:

  • The user requests the page (e.g. default.html ). This page has a tag <a href="/doc/test.pdf">pdf</a> .
  • The browser requests http://www.yourdomain.com/doc/test.pdf and passes Referer http://www.yourdomain.com/default.html .
  • mod_hotlink checks the rules (given above).
  • Instead of granting direct access to test.pdf mod_hotlink performs redirect to a dynamically generated address http://www.yourdomain.com/doc/ 90f630427786fd84/ test.pdf.
  • Browser requests http://www.yourdomain.com/doc/ 90f630427786fd84/ test.pdf.
  • mod_hotlink verifies signature validity and then grants access to test.pdf .

All this stuff is necessary to bypass noncompliance of some browsers with the standards (especially this refers to Internet Explorer) as they sometimes don't set Referer header for successive requests to the same resource.