Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_secure_link_module.xml @ 2559:82e6029db0c0
Updated with Netcraft June 2020 Web Server Survey stats.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 25 Jun 2020 13:12:56 +0100 |
parents | 66a30a380fba |
children | 4add6ae1296f |
line wrap: on
line source
<?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://tools.ietf.org/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&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>