Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_secure_link_module.xml @ 830:42750c1b8d1b

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