Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_secure_link_module.xml @ 3039:e6b785b7e308

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Minor fixes in njs documentation.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 06 Feb 2024 08:52:52 +0000
parents 4add6ae1296f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
580
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 348
diff changeset
3 <!--
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 348
diff changeset
4 Copyright (C) Igor Sysoev
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 348
diff changeset
5 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 348
diff changeset
6 -->
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 348
diff changeset
7
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 <module name="Module ngx_http_secure_link_module"
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 link="/en/docs/http/ngx_http_secure_link_module.html"
589
764fbac1b8b4 Added document revision.
Ruslan Ermilov <ru@nginx.com>
parents: 580
diff changeset
12 lang="en"
1923
66a30a380fba Fixed links to tools.ietf.org.
Ruslan Ermilov <ru@nginx.com>
parents: 1155
diff changeset
13 rev="4">
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15 <section id="summary">
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
17 <para>
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
18 The <literal>ngx_http_secure_link_module</literal> module (0.7.18)
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
19 is used to check authenticity of requested links,
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
20 protect resources from unauthorized access,
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
21 and limit link lifetime.
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
22 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
23
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
24 <para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
25 The authenticity of a requested link is verified by comparing the
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
26 checksum value passed in a request with the value computed
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
27 for the request.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
28 If a link has a limited lifetime and the time has expired,
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
29 the link is considered outdated.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
30 The status of these checks is made available in the
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
31 <var>$secure_link</var> variable.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
32 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
33
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
34 <para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
35 The module provides two alternative operation modes.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
36 The first mode is enabled by the <link id="secure_link_secret"/>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
37 directive and is used to check authenticity of requested links
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
38 as well as protect resources from unauthorized access.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
39 The second mode (0.8.50) is enabled by the
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
40 <link id="secure_link"/> and <link id="secure_link_md5"/>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
41 directives and is also used to limit lifetime of links.
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
42 </para>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
43
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
44 <para>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
45 This module is not built by default, it should be enabled with the
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
46 <literal>--with-http_secure_link_module</literal>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
47 configuration parameter.
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48 </para>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
50 </section>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
53 <section id="directives" name="Directives">
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
54
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
55 <directive name="secure_link">
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
56 <syntax><value>expression</value></syntax>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
57 <default/>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
58 <context>http</context>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
59 <context>server</context>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
60 <context>location</context>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
61
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
62 <para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
63 Defines a string with variables from which the
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
64 checksum value and lifetime of a link will be extracted.
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
65 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
66
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
67 <para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
68 Variables used in an <value>expression</value> are usually associated
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
69 with a request; see <link id="secure_link_md5">example</link> below.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
70 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
71
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
72 <para>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
73 The checksum value extracted from the string is compared with
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
74 the MD5 hash value of the expression defined by the
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
75 <link id="secure_link_md5"/> directive.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
76 If the checksums are different, the <var>$secure_link</var> variable
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
77 is set to an empty string.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
78 If the checksums are the same, the link lifetime is checked.
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
79 If the link has a limited lifetime and the time has expired,
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
80 the <var>$secure_link</var> variable is set to “<literal>0</literal>”.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
81 Otherwise, it is set to “<literal>1</literal>”.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
82 The MD5 hash value passed in a request is encoded in
2831
4add6ae1296f Updated links to datatracker.ietf.org.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1923
diff changeset
83 <link url="https://datatracker.ietf.org/doc/html/rfc4648#section-5">base64url</link>.
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
84 </para>
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86 <para>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
87 If a link has a limited lifetime, the expiration time
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
88 is set in seconds since Epoch (Thu, 01 Jan 1970 00:00:00 GMT).
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
89 The value is specified in the expression after the MD5 hash,
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
90 and is separated by a comma.
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
91 The expiration time passed in a request is available through
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
92 the <var>$secure_link_expires</var> variable for a use in
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
93 the <link id="secure_link_md5"/> directive.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
94 If the expiration time is not specified, a link has the unlimited
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
95 lifetime.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
96 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
97
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
98 </directive>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
99
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
100
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
101 <directive name="secure_link_md5">
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
102 <syntax><value>expression</value></syntax>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
103 <default/>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
104 <context>http</context>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
105 <context>server</context>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
106 <context>location</context>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
107
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
108 <para>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
109 Defines an expression for which the MD5 hash value will
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
110 be computed and compared with the value passed in a request.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
111 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
112
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
113 <para>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
114 The expression should contain the secured part of a link (resource)
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
115 and a secret ingredient.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
116 If the link has a limited lifetime,
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
117 the expression should also contain <var>$secure_link_expires</var>.
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
118 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
119
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
120 <para>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
121 To prevent unauthorized access, the expression may contain some
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
122 information about the client, such as its address and browser version.
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
123 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
124
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
125 <para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
126 Example:
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
127 <example>
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
128 location /s/ {
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
129 secure_link $arg_md5,$arg_expires;
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
130 secure_link_md5 "$secure_link_expires$uri$remote_addr secret";
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132 if ($secure_link = "") {
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133 return 403;
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
134 }
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
135
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
136 if ($secure_link = "0") {
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
137 return 410;
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
138 }
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
139
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
140 ...
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
141 }
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
142 </example>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
143 The
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
144 “<literal>/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&amp;expires=2147483647</literal>”
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
145 link
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
146 restricts access to “<literal>/s/link</literal>” for the client with the
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
147 IP address 127.0.0.1.
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
148 The link also has the limited lifetime until January 19, 2038 (GMT).
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
149 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
150
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
151 <para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
152 On UNIX, the <value>md5</value> request argument value can be obtained as:
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
153 <example>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
154 echo -n '2147483647/s/link127.0.0.1 secret' | \
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
155 openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
156 </example>
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
157 </para>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
158
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
159 </directive>
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
160
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
161
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
162 <directive name="secure_link_secret">
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
163 <syntax><value>word</value></syntax>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
164 <default/>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
165 <context>location</context>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
166
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
167 <para>
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
168 Defines a secret <value>word</value> used to check authenticity
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
169 of requested links.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
170 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
171
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
172 <para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
173 The full URI of a requested link looks as follows:
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
174 <example>
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
175 /<value>prefix</value>/<value>hash</value>/<value>link</value>
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
176 </example>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
177 where <value>hash</value> is a hexadecimal representation of the
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
178 MD5 hash computed for the concatenation of the link and secret word,
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
179 and <value>prefix</value> is an arbitrary string without slashes.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
180 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
181
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
182 <para>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
183 If the requested link passes the authenticity check,
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
184 the <var>$secure_link</var> variable is set to the link
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
185 extracted from the request URI.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
186 Otherwise, the <var>$secure_link</var> variable
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
187 is set to an empty string.
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
188 </para>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
189
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
190 <para>
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
191 Example:
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
192 <example>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
193 location /p/ {
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
194 secure_link_secret secret;
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
195
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
196 if ($secure_link = "") {
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
197 return 403;
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
198 }
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
199
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
200 rewrite ^ /secure/$secure_link;
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
201 }
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
202
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
203 location /secure/ {
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
204 internal;
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
205 }
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
206 </example>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
207 A request of “<literal>/p/5e814704a28d9bc1914ff19fa0c4a00a/link</literal>”
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
208 will be internally redirected to
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
209 “<literal>/secure/link</literal>”.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
210 </para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
211
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
212 <para>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
213 On UNIX, the hash value for this example can be obtained as:
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
214 <example>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
215 echo -n 'linksecret' | openssl md5 -hex
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
216 </example>
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
217 </para>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
218
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
219 </directive>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
220
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
221 </section>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
222
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
223
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
224 <section id="variables" name="Embedded Variables">
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
225
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
226 <para>
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
227 <list type="tag" compact="no">
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
228
1155
07402a11fd8d Assigned IDs to tags describing variables.
Vladimir Homutov <vl@nginx.com>
parents: 966
diff changeset
229 <tag-name id="var_secure_link"><var>$secure_link</var></tag-name>
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
230 <tag-desc>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
231 The status of a link check.
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
232 The specific value depends on the selected operation mode.
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
233 </tag-desc>
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
234
1155
07402a11fd8d Assigned IDs to tags describing variables.
Vladimir Homutov <vl@nginx.com>
parents: 966
diff changeset
235 <tag-name id="var_secure_link_expires"><var>$secure_link_expires</var>
07402a11fd8d Assigned IDs to tags describing variables.
Vladimir Homutov <vl@nginx.com>
parents: 966
diff changeset
236 </tag-name>
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
237 <tag-desc>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 830
diff changeset
238 The lifetime of a link passed in a request;
830
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
239 intended to be used only in the
42750c1b8d1b Secure_link: documented newer operation mode.
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
240 <link id="secure_link_md5"/> directive.
348
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
241 </tag-desc>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
242
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
243 </list>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
244 </para>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
245
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
246 </section>
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
247
5a848934a12d English translation of ngx_http_geoip_module, ngx_http_map_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
248 </module>