mod_hotlink

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.

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 a protection folder.

mod_hotlink directives

HotlinkProtect

Description: Enables protection for specific location with specific method
Syntax: HotlinkProtect /location_to_be_protected [ProtectionType, RedirectTo=URL, ParamName=HLB]
Context: server config, virtual host, directory, .htaccess
Module: mod_hotlink

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.

location_to_be_protected specifies a path with protected content. Path is relative from current context.

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:

    • SetOutputFilter "HotLink" - this filter searches all links on pages, analyses where they point and 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.
    • SetOutputFilter "HotLinkSimple" - this filter searches xxxxxxxxxxxxxxxx sequence inside all tags on the page and replaces it with the signature. This method provides backward compatibility with older HotlinkBlocker products.
  • 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 querystring that will be added to links when LINK protection method is used. By default parameter parameter is called HLB.

Example:

SetOutputFilter Hotlink
<Files *.jpg>
  HotlinkProtect / 
</Files>
# Protect all images on pages located within current directory

HotlinkAllow

Description: White lists requests based on different criteria, like Referrer, User-Agent or IP
Syntax: HotlinkAllow Referer|Agent|IP regex|ipmask
Context: server config, virtual host, directory, .htaccess
Module: mod_hotlink

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

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 Referer http://domain.com
HotlinkAllow Agent Googlebot
HotlinkAllow IP 192.168.1.*/25

HotlinkDeny

Description: Black lists requests based on different criteria, like Referrer, User-Agent or IP
Syntax: HotlinkDeny Referer|Agent|IP regex|ipmask
Context: server config, virtual host, directory, .htaccess
Module: mod_hotlink

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

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.

HotlinkExpires

Description: Sets the time of signature validity
Syntax: HotlinkExpires time_in_secs
Default: HotlinkExpires 3600
Context: server config, virtual host, directory, .htaccess
Module: mod_hotlink

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

HotlinkInvolveIP

Description: Enables usage of client IP for signature generation
Syntax: HotlinkInvolveIP On|Off
Default: HotlinkInvolveIP On
Context: server config, virtual host, directory, .htaccess
Module: mod_hotlink

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.

HotlinkSignature

Description: Specifies the secret phrase or password to be used for signature encryption
Syntax: HotlinkSignature password
Context: server config, virtual host, directory, .htaccess
Module: mod_hotlink

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.

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.

Examples

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

SetOutputFilter Hotlink
<Files *.pdf>
  HotlinkProtect / [ 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.

2. 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 / [ 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.

3. 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 / [ 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.