<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_secure_link_module"
        link="/en/docs/http/ngx_http_secure_link_module.html"
        lang="en"
        rev="4">

<section id="summary">

<para>
The <literal>ngx_http_secure_link_module</literal> module (0.7.18)
is used to check authenticity of requested links,
protect resources from unauthorized access,
and limit link lifetime.
</para>

<para>
The authenticity of a requested link is verified by comparing the
checksum value passed in a request with the value computed
for the request.
If a link has a limited lifetime and the time has expired,
the link is considered outdated.
The status of these checks is made available in the
<var>$secure_link</var> variable.
</para>

<para>
The module provides two alternative operation modes.
The first mode is enabled by the <link id="secure_link_secret"/>
directive and is used to check authenticity of requested links
as well as protect resources from unauthorized access.
The second mode (0.8.50) is enabled by the
<link id="secure_link"/> and <link id="secure_link_md5"/>
directives and is also used to limit lifetime of links.
</para>

<para>
This module is not built by default, it should be enabled with the
<literal>--with-http_secure_link_module</literal>
configuration parameter.
</para>

</section>


<section id="directives" name="Directives">

<directive name="secure_link">
<syntax><value>expression</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Defines a string with variables from which the
checksum value and lifetime of a link will be extracted.
</para>

<para>
Variables used in an <value>expression</value> are usually associated
with a request; see <link id="secure_link_md5">example</link> below.
</para>

<para>
The checksum value extracted from the string is compared with
the MD5 hash value of the expression defined by the
<link id="secure_link_md5"/> directive.
If the checksums are different, the <var>$secure_link</var> variable
is set to an empty string.
If the checksums are the same, the link lifetime is checked.
If the link has a limited lifetime and the time has expired,
the <var>$secure_link</var> variable is set to “<literal>0</literal>”.
Otherwise, it is set to “<literal>1</literal>”.
The MD5 hash value passed in a request is encoded in
<link url="https://datatracker.ietf.org/doc/html/rfc4648#section-5">base64url</link>.
</para>

<para>
If a link has a limited lifetime, the expiration time
is set in seconds since Epoch (Thu, 01 Jan 1970 00:00:00 GMT).
The value is specified in the expression after the MD5 hash,
and is separated by a comma.
The expiration time passed in a request is available through
the <var>$secure_link_expires</var> variable for a use in
the <link id="secure_link_md5"/> directive.
If the expiration time is not specified, a link has the unlimited
lifetime.
</para>

</directive>


<directive name="secure_link_md5">
<syntax><value>expression</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Defines an expression for which the MD5 hash value will
be computed and compared with the value passed in a request.
</para>

<para>
The expression should contain the secured part of a link (resource)
and a secret ingredient.
If the link has a limited lifetime,
the expression should also contain <var>$secure_link_expires</var>.
</para>

<para>
To prevent unauthorized access, the expression may contain some
information about the client, such as its address and browser version.
</para>

<para>
Example:
<example>
location /s/ {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "$secure_link_expires$uri$remote_addr secret";

    if ($secure_link = "") {
        return 403;
    }

    if ($secure_link = "0") {
        return 410;
    }

    ...
}
</example>
The
“<literal>/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&amp;expires=2147483647</literal>”
link
restricts access to “<literal>/s/link</literal>” for the client with the
IP address 127.0.0.1.
The link also has the limited lifetime until January 19, 2038 (GMT).
</para>

<para>
On UNIX, the <value>md5</value> request argument value can be obtained as:
<example>
echo -n '2147483647/s/link127.0.0.1 secret' | \
    openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
</example>
</para>

</directive>


<directive name="secure_link_secret">
<syntax><value>word</value></syntax>
<default/>
<context>location</context>

<para>
Defines a secret <value>word</value> used to check authenticity
of requested links.
</para>

<para>
The full URI of a requested link looks as follows:
<example>
/<value>prefix</value>/<value>hash</value>/<value>link</value>
</example>
where <value>hash</value> is a hexadecimal representation of the
MD5 hash computed for the concatenation of the link and secret word,
and <value>prefix</value> is an arbitrary string without slashes.
</para>

<para>
If the requested link passes the authenticity check,
the <var>$secure_link</var> variable is set to the link
extracted from the request URI.
Otherwise, the <var>$secure_link</var> variable
is set to an empty string.
</para>

<para>
Example:
<example>
location /p/ {
    secure_link_secret secret;

    if ($secure_link = "") {
        return 403;
    }

    rewrite ^ /secure/$secure_link;
}

location /secure/ {
    internal;
}
</example>
A request of “<literal>/p/5e814704a28d9bc1914ff19fa0c4a00a/link</literal>”
will be internally redirected to
“<literal>/secure/link</literal>”.
</para>

<para>
On UNIX, the hash value for this example can be obtained as:
<example>
echo -n 'linksecret' | openssl md5 -hex
</example>
</para>

</directive>

</section>


<section id="variables" name="Embedded Variables">

<para>
<list type="tag" compact="no">

<tag-name id="var_secure_link"><var>$secure_link</var></tag-name>
<tag-desc>
The status of a link check.
The specific value depends on the selected operation mode.
</tag-desc>

<tag-name id="var_secure_link_expires"><var>$secure_link_expires</var>
</tag-name>
<tag-desc>
The lifetime of a link passed in a request;
intended to be used only in the
<link id="secure_link_md5"/> directive.
</tag-desc>

</list>
</para>

</section>

</module>