Mercurial > hg > nginx-site
changeset 830:42750c1b8d1b
Secure_link: documented newer operation mode.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 04 Feb 2013 18:13:55 +0400 |
parents | eb4f221921fa |
children | 8ae26032d011 |
files | xml/en/docs/http/ngx_http_secure_link_module.xml xml/ru/docs/http/ngx_http_secure_link_module.xml |
diffstat | 2 files changed, 350 insertions(+), 40 deletions(-) [+] |
line wrap: on
line diff
--- 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&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>
--- 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&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>