# HG changeset patch
# User Ruslan Ermilov <ru@nginx.com>
# Date 1359987235 -14400
# Node ID 42750c1b8d1bc355118f211dcacb553ea7cb6168
# Parent  eb4f221921fa42f6c880033ada859103e61fbf96
Secure_link: documented newer operation mode.

diff --git a/xml/en/docs/http/ngx_http_secure_link_module.xml b/xml/en/docs/http/ngx_http_secure_link_module.xml
--- a/xml/en/docs/http/ngx_http_secure_link_module.xml
+++ b/xml/en/docs/http/ngx_http_secure_link_module.xml
@@ -10,13 +10,35 @@
 <module name="Module ngx_http_secure_link_module"
         link="/en/docs/http/ngx_http_secure_link_module.html"
         lang="en"
-        rev="1">
+        rev="2">
 
 <section id="summary">
 
 <para>
-The <literal>ngx_http_secure_link_module</literal> module (0.7.18+) checks
-the validity of the requested link.
+The <literal>ngx_http_secure_link_module</literal> module (0.7.18)
+allows to check authenticity of requested links,
+protect resources from unauthorized access,
+and limit lifetime of links.
+</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 link has a limited lifetime and the time has expired,
+the link is considered outdated.
+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 allows 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 also allows to limit lifetime of links.
 </para>
 
 <para>
@@ -28,44 +50,170 @@ configuration parameter.
 </section>
 
 
-<section id="example" name="Example Configuration">
+<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 are to 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>
+Checksum value extracted from the string is compared with
+MD5 hash value computed for expression defined by the
+<link id="secure_link_md5"/> directive.
+If checksums are different, the <var>$secure_link</var> variable
+is set to an empty string.
+If checksums are the same, lifetime of a link is checked.
+If 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>”.
+MD5 hash value passed in a request is encoded in
+<link url="http://tools.ietf.org/html/rfc4648#section-5">base64url</link>.
+</para>
 
 <para>
+If link has a limited lifetime, an expiration time
+is set in seconds since Epoch (Thu, 01 Jan 1970 00:00:00 GMT).
+The value is specified in an expression after MD5 hash,
+and is separated by comma.
+An expiration time passed in a request is made available in
+the <var>$secure_link_expires</var> variable for use in
+the <link id="secure_link_md5"/> directive.
+If expiration time is not specified, a link has 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 is to
+be computed and compared with the value passed in a request.
+</para>
+
+<para>
+An expression should contain the secured part of a link (resource)
+and a secret ingredient.
+If link has a limited lifetime,
+an expression should also contain <var>$secure_link_expires</var>.
+</para>
+
+<para>
+To prevent unauthorized access, an expression may contain some
+information about the client, such as its address and version
+of the browser.
+</para>
+
+<para>
+Example:
 <example>
-location /p/ {
-    secure_link_secret some_secret_word;
+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 link
+“<literal>/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&amp;expires=2147483647</literal>”
+restricts access to “<literal>/s/link</literal>” for the client with IP address
+127.0.0.1.
+The link also has a 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>
 
-</section>
+</directive>
 
 
-<section id="directives" name="Directives">
-
 <directive name="secure_link_secret">
 <syntax><value>word</value></syntax>
 <default/>
 <context>location</context>
 
 <para>
-Defines a secret <value>word</value> used to check the validity of the link.
-The full URL of the protected link looks as follows:
+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>
-/prefix/<value>hash</value>/<value>link</value>
+/<value>prefix</value>/<value>hash</value>/<value>link</value>
 </example>
-where <value>hash</value> is computed as
-<example>
-md5(link, secret_word);
-</example>
+where <value>hash</value> is a hexadecimal representation of an
+MD5 hash computed for the concatenation of link and secret word,
+and <value>prefix</value> is an arbitrary string without slashes.
+</para>
+
+<para>
+If 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>
-A prefix is an arbitrary string not including a slash.
+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>
@@ -76,12 +224,19 @@ A prefix is an arbitrary string not incl
 <section id="variables" name="Embedded Variables">
 
 <para>
-<list type="tag">
+<list type="tag" compact="no">
 
 <tag-name><var>$secure_link</var></tag-name>
 <tag-desc>
-equals to the link extracted from the full URL.
-If hash is incorrect, this variable is set to an empty string.
+Status of a link check.
+The specific value depends on the selected operation mode.
+</tag-desc>
+
+<tag-name><var>$secure_link_expires</var></tag-name>
+<tag-desc>
+Lifetime of a link passed in a request;
+intended to be used only in the
+<link id="secure_link_md5"/> directive.
 </tag-desc>
 
 </list>
diff --git a/xml/ru/docs/http/ngx_http_secure_link_module.xml b/xml/ru/docs/http/ngx_http_secure_link_module.xml
--- a/xml/ru/docs/http/ngx_http_secure_link_module.xml
+++ b/xml/ru/docs/http/ngx_http_secure_link_module.xml
@@ -10,13 +10,35 @@
 <module name="Модуль ngx_http_secure_link_module"
         link="/ru/docs/http/ngx_http_secure_link_module.html"
         lang="ru"
-        rev="1">
+        rev="2">
 
 <section id="summary">
 
 <para>
-Модуль <literal>ngx_http_secure_link_module</literal> (0.7.18+) проверяет
-правильность запрашиваемой ссылки.
+Модуль <literal>ngx_http_secure_link_module</literal> (0.7.18)
+позволяет проверять аутентичность запрашиваемых ссылок,
+защищать ресурсы от несанкционированного доступа,
+а также ограничивать срок действия ссылок.
+</para>
+
+<para>
+Правильность запрашиваемой ссылки проверяется сравнением переданного
+в запросе значения контрольной суммы со значением,
+вычисляемым для запроса.
+Если ссылка имеет ограниченный срок действия и он истёк,
+ссылка считается устаревшей.
+Результат этих проверок делается доступным в переменной
+<var>$secure_link</var>.
+</para>
+
+<para>
+Модуль реализует два альтернативных режима работы.
+В первом режиме, который включается директивой
+<link id="secure_link_secret"/>, можно проверить аутентичность
+запрашиваемых ссылок и защитить их от несанкционированного доступа.
+Второй режим (0.8.50) включается директивами
+<link id="secure_link"/> и <link id="secure_link_md5"/>,
+и позволяет также ограничить срок действия ссылок.
 </para>
 
 <para>
@@ -28,44 +50,170 @@
 </section>
 
 
-<section id="example" name="Пример конфигурации">
+<section id="directives" name="Директивы">
+
+<directive name="secure_link">
+<syntax><value>выражение</value></syntax>
+<default/>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+Задаёт строку с переменными, из которой будет выделено значение
+контрольной суммы и время действия ссылки.
+</para>
+
+<para>
+Используемые в выражении переменные обычно связаны с запросом;
+см. <link id="secure_link_md5">пример</link> ниже.
+</para>
+
+<para>
+Выделенное из строки значение контрольной суммы сравнивается со
+значением MD5-хэша, вычисляемым для выражения, заданного
+директивой <link id="secure_link_md5"/>.
+Если контрольные суммы не совпадают, значением переменной
+<var>$secure_link</var> становится пустая строка.
+Если контрольные суммы совпадают, проверяется время действия ссылки.
+Если срок действия ссылки задан и истёк, переменная
+<var>$secure_link</var> получает значение “<literal>0</literal>”.
+В противном случае она получает значение “<literal>1</literal>”.
+Значение MD5-хэш передаётся в запросе закодированным в
+<link url="http://tools.ietf.org/html/rfc4648#section-5">base64url</link>.
+</para>
 
 <para>
+Если ссылка имеет ограниченный срок действия, время её действия
+задаётся в секундах с начала эпохи (1 января 1970 года 00:00:00 GMT).
+Значение указывается в выражении после MD5-хэша
+и отделяется от него запятой.
+Время действия ссылки, переданное в запросе, делается доступным
+в переменной <var>$secure_link_expires</var> для использования
+в директиве <link id="secure_link_md5"/>.
+Если время действия ссылки не задано, ссылка имеет неограниченный
+срок действия.
+</para>
+
+</directive>
+
+
+<directive name="secure_link_md5">
+<syntax><value>выражение</value></syntax>
+<default/>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+Задаёт выражение, для которого считается значение MD5-хэш,
+сравниваемое с переданным в запросе.
+</para>
+
+<para>
+Выражение должно содержать защищаемую часть ссылки (ресурс)
+и секретную составляющую.
+Если ссылка имеет ограниченный срок действия,
+выражение также должно содержать <var>$secure_link_expires</var>.
+</para>
+
+<para>
+Для предотвращения несанкционированного доступа выражение
+может содержать информацию о клиенте, например, его адрес и
+версию браузера.
+</para>
+
+<para>
+Пример:
 <example>
-location /p/ {
-    secure_link_secret some_secret_word;
+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>
+Ссылка
+“<literal>/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&amp;expires=2147483647</literal>”
+ограничивает доступ к “<literal>/s/link</literal>” для клиента с IP-адресом
+127.0.0.1.
+Ссылка также имеет ограниченный срок действия до 19 января 2038 года (GMT).
+</para>
+
+<para>
+Значение аргумента запроса <value>md5</value> на UNIX можно получить так:
+<example>
+echo -n '2147483647/s/link127.0.0.1 secret' | \
+    openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
+</example>
 </para>
 
-</section>
+</directive>
 
 
-<section id="directives" name="Директивы">
-
 <directive name="secure_link_secret">
 <syntax><value>слово</value></syntax>
 <default/>
 <context>location</context>
 
 <para>
-Задаёт секретное <value>слово</value> для проверки правильности ссылки.
-Полный URL защищённой ссылки выглядит так:
+Задаёт секретное <value>слово</value> для проверки аутентичности
+запрашиваемых ссылок.
+</para>
+
+<para>
+Полный URI запрашиваемой ссылки выглядит так:
 <example>
-/prefix/<value>hash</value>/<value>ссылка</value>
+/<value>префикс</value>/<value>хэш</value>/<value>ссылка</value>
 </example>
-где <value>hash</value> считается как
-<example>
-md5(ссылка, секретное_слово);
-</example>
+где <value>хэш</value> — MD5-хэш в шестнадцатеричном виде,
+вычисленный для конкатенации ссылки и секретного слова,
+а <value>префикс</value> — произвольная строка без слэшей.
+</para>
+
+<para>
+Если запрашиваемая ссылка проходит проверку на аутентичность,
+значением переменной <var>$secure_link</var> становится ссылка,
+выделенная из URI запроса.
+В противном случае значением переменной <var>$secure_link</var>
+становится пустая строка.
 </para>
 
 <para>
-Префикс — произвольная строка, не включающая слэш.
+Пример:
+<example>
+location /p/ {
+    secure_link_secret secret;
+
+    if ($secure_link = "") {
+        return 403;
+    }
+
+    rewrite ^ /secure/$secure_link;
+}
+
+location /secure/ {
+    internal;
+}
+</example>
+По запросу “<literal>/p/5e814704a28d9bc1914ff19fa0c4a00a/link</literal>”
+будет выполнено внутреннее перенаправление на
+“<literal>/secure/link</literal>”.
+</para>
+
+<para>
+Значение хэша для данного примера на UNIX можно получить так:
+<example>
+echo -n 'linksecret' | openssl md5 -hex
+</example>
 </para>
 
 </directive>
@@ -76,12 +224,19 @@ md5(ссылка, секретное_слово);
 <section id="variables" name="Встроенные переменные">
 
 <para>
-<list type="tag">
+<list type="tag" compact="no">
 
 <tag-name><var>$secure_link</var></tag-name>
 <tag-desc>
-равна ссылке, выделенной из полного URL’а.
-Если хэш неверный, то переменная равна пустой строке.
+Результат проверки ссылки.
+Конкретное значение зависит от выбранного режима работы.
+</tag-desc>
+
+<tag-name><var>$secure_link_expires</var></tag-name>
+<tag-desc>
+Время действия ссылки, переданное в запросе.
+Предназначено исключительно для использования в директиве
+<link id="secure_link_md5"/>.
 </tag-desc>
 
 </list>