mod_hotlink

Overview

mod_hotlink module is aimed at protecting your web server from people stealing your traffic by directly linking to the 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 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 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 is based on HotlinkBlocker product, but now it's just a piece of our Ape product.

Quick start

Link protection method

Link protection is completely independent on 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 replaces links in the tag with specifically generated sequence:

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

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 ^$
</FilesMatch>

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" 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 ^$
HotlinkProtect /downloads [ Redirect ]
</FilesMatch>

Related articles and topics

Protection methods

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

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. 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.

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.

REDIRECT

Checks Referer header value but performs a redirect to a temporary signed link instead of returning content. It may be difficult to understand the theory of this method, but the only thing you need to know is that it provides moderate protection level to preserve some embedded content that cannot be protected by REFERER method — content like PDF files, Flash and Media Player movies, audio and so on. Just as in the previous method you don’t have to change anything — just enable mod_hotlink and specify the folder(s) to protect.

Environment variables

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

Context Name Description
S V D .h HotlinkProtect enables protection for specific location using specific method
S V D .h HotlinkAllow white lists requests based on different criteria, like Referrer, User-Agent or IP
S V D .h HotlinkDeny black lists requests based on different criteria, like Referrer, User-Agent or IP
S V D .h HotlinkLinkExpires sets the period of signature validity
S V D .h HotlinkInvolveIP enables usage of client IP for signature generation
S V D .h HotlinkSignature 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 sequence inside all tags on the page and replaces it with the signature. This method provides backward compatibility with HotlinkBlocker product.
    • 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://domain.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://domain.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 signatures.

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. 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 ^$
</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 ^$
</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.