Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_secure_link_module.xml @ 2846:fdf1464e1977
Moved banner to the external file to make partial rollout possible.
An idea is to have several banners and show them with different probability
specified by split directive in the nginx.conf
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Tue, 10 May 2022 18:07:27 +0400 |
parents | 4add6ae1296f |
children |
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://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&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>