Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_secure_link_module.xml @ 966:95c3c3bbf1ce

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Text review.
author Egor Nikitin <yegor.nikitin@gmail.com>
date Wed, 14 Aug 2013 12:03:41 +0400
parents 42750c1b8d1b
children 07402a11fd8d
comparison
equal deleted inserted replaced
965:fadccc156188 966:95c3c3bbf1ce
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) 18 The <literal>ngx_http_secure_link_module</literal> module (0.7.18)
19 allows to check authenticity of requested links, 19 is used to check authenticity of requested links,
20 protect resources from unauthorized access, 20 protect resources from unauthorized access,
21 and limit lifetime of links. 21 and limit link lifetime.
22 </para> 22 </para>
23 23
24 <para> 24 <para>
25 The authenticity of a requested link is verified by comparing the 25 The authenticity of a requested link is verified by comparing the
26 checksum value passed in a request with the value computed 26 checksum value passed in a request with the value computed
27 for the request. 27 for the request.
28 If link has a limited lifetime and the time has expired, 28 If a link has a limited lifetime and the time has expired,
29 the link is considered outdated. 29 the link is considered outdated.
30 Status of these checks is made available in the 30 The status of these checks is made available in the
31 <var>$secure_link</var> variable. 31 <var>$secure_link</var> variable.
32 </para> 32 </para>
33 33
34 <para> 34 <para>
35 The module provides two alternative operation modes. 35 The module provides two alternative operation modes.
36 The first mode is enabled by the <link id="secure_link_secret"/> 36 The first mode is enabled by the <link id="secure_link_secret"/>
37 directive and allows to check authenticity of requested links 37 directive and is used to check authenticity of requested links
38 as well as protect resources from unauthorized access. 38 as well as protect resources from unauthorized access.
39 The second mode (0.8.50) is enabled by the 39 The second mode (0.8.50) is enabled by the
40 <link id="secure_link"/> and <link id="secure_link_md5"/> 40 <link id="secure_link"/> and <link id="secure_link_md5"/>
41 directives, and also allows to limit lifetime of links. 41 directives and is also used to limit lifetime of links.
42 </para> 42 </para>
43 43
44 <para> 44 <para>
45 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
46 <literal>--with-http_secure_link_module</literal> 46 <literal>--with-http_secure_link_module</literal>
59 <context>server</context> 59 <context>server</context>
60 <context>location</context> 60 <context>location</context>
61 61
62 <para> 62 <para>
63 Defines a string with variables from which the 63 Defines a string with variables from which the
64 checksum value and lifetime of a link are to be extracted. 64 checksum value and lifetime of a link will be extracted.
65 </para> 65 </para>
66 66
67 <para> 67 <para>
68 Variables used in an <value>expression</value> are usually associated 68 Variables used in an <value>expression</value> are usually associated
69 with a request; see <link id="secure_link_md5">example</link> below. 69 with a request; see <link id="secure_link_md5">example</link> below.
70 </para> 70 </para>
71 71
72 <para> 72 <para>
73 Checksum value extracted from the string is compared with 73 The checksum value extracted from the string is compared with
74 MD5 hash value computed for expression defined by the 74 the MD5 hash value of the expression defined by the
75 <link id="secure_link_md5"/> directive. 75 <link id="secure_link_md5"/> directive.
76 If checksums are different, the <var>$secure_link</var> variable 76 If the checksums are different, the <var>$secure_link</var> variable
77 is set to an empty string. 77 is set to an empty string.
78 If checksums are the same, lifetime of a link is checked. 78 If the checksums are the same, the link lifetime is checked.
79 If link has a limited lifetime and the time has expired, 79 If the link has a limited lifetime and the time has expired,
80 the <var>$secure_link</var> variable is set to “<literal>0</literal>”. 80 the <var>$secure_link</var> variable is set to “<literal>0</literal>”.
81 Otherwise, it is set to “<literal>1</literal>”. 81 Otherwise, it is set to “<literal>1</literal>”.
82 MD5 hash value passed in a request is encoded in 82 The MD5 hash value passed in a request is encoded in
83 <link url="http://tools.ietf.org/html/rfc4648#section-5">base64url</link>. 83 <link url="http://tools.ietf.org/html/rfc4648#section-5">base64url</link>.
84 </para> 84 </para>
85 85
86 <para> 86 <para>
87 If link has a limited lifetime, an expiration time 87 If a link has a limited lifetime, the expiration time
88 is set in seconds since Epoch (Thu, 01 Jan 1970 00:00:00 GMT). 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, 89 The value is specified in the expression after the MD5 hash,
90 and is separated by comma. 90 and is separated by a comma.
91 An expiration time passed in a request is made available in 91 The expiration time passed in a request is available through
92 the <var>$secure_link_expires</var> variable for use in 92 the <var>$secure_link_expires</var> variable for a use in
93 the <link id="secure_link_md5"/> directive. 93 the <link id="secure_link_md5"/> directive.
94 If expiration time is not specified, a link has unlimited 94 If the expiration time is not specified, a link has the unlimited
95 lifetime. 95 lifetime.
96 </para> 96 </para>
97 97
98 </directive> 98 </directive>
99 99
104 <context>http</context> 104 <context>http</context>
105 <context>server</context> 105 <context>server</context>
106 <context>location</context> 106 <context>location</context>
107 107
108 <para> 108 <para>
109 Defines an expression for which the MD5 hash value is to 109 Defines an expression for which the MD5 hash value will
110 be computed and compared with the value passed in a request. 110 be computed and compared with the value passed in a request.
111 </para> 111 </para>
112 112
113 <para> 113 <para>
114 An expression should contain the secured part of a link (resource) 114 The expression should contain the secured part of a link (resource)
115 and a secret ingredient. 115 and a secret ingredient.
116 If link has a limited lifetime, 116 If the link has a limited lifetime,
117 an expression should also contain <var>$secure_link_expires</var>. 117 the expression should also contain <var>$secure_link_expires</var>.
118 </para> 118 </para>
119 119
120 <para> 120 <para>
121 To prevent unauthorized access, an expression may contain some 121 To prevent unauthorized access, the expression may contain some
122 information about the client, such as its address and version 122 information about the client, such as its address and browser version.
123 of the browser.
124 </para> 123 </para>
125 124
126 <para> 125 <para>
127 Example: 126 Example:
128 <example> 127 <example>
139 } 138 }
140 139
141 ... 140 ...
142 } 141 }
143 </example> 142 </example>
144 The link 143 The
145 “<literal>/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&amp;expires=2147483647</literal>” 144 “<literal>/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&amp;expires=2147483647</literal>”
146 restricts access to “<literal>/s/link</literal>” for the client with IP address 145 link
147 127.0.0.1. 146 restricts access to “<literal>/s/link</literal>” for the client with the
148 The link also has a limited lifetime until January 19, 2038 (GMT). 147 IP address 127.0.0.1.
148 The link also has the limited lifetime until January 19, 2038 (GMT).
149 </para> 149 </para>
150 150
151 <para> 151 <para>
152 On UNIX, the <value>md5</value> request argument value can be obtained as: 152 On UNIX, the <value>md5</value> request argument value can be obtained as:
153 <example> 153 <example>
172 <para> 172 <para>
173 The full URI of a requested link looks as follows: 173 The full URI of a requested link looks as follows:
174 <example> 174 <example>
175 /<value>prefix</value>/<value>hash</value>/<value>link</value> 175 /<value>prefix</value>/<value>hash</value>/<value>link</value>
176 </example> 176 </example>
177 where <value>hash</value> is a hexadecimal representation of an 177 where <value>hash</value> is a hexadecimal representation of the
178 MD5 hash computed for the concatenation of link and secret word, 178 MD5 hash computed for the concatenation of the link and secret word,
179 and <value>prefix</value> is an arbitrary string without slashes. 179 and <value>prefix</value> is an arbitrary string without slashes.
180 </para> 180 </para>
181 181
182 <para> 182 <para>
183 If requested link passes the authenticity check, 183 If the requested link passes the authenticity check,
184 the <var>$secure_link</var> variable is set to the link 184 the <var>$secure_link</var> variable is set to the link
185 extracted from the request URI. 185 extracted from the request URI.
186 Otherwise, the <var>$secure_link</var> variable 186 Otherwise, the <var>$secure_link</var> variable
187 is set to an empty string. 187 is set to an empty string.
188 </para> 188 </para>
226 <para> 226 <para>
227 <list type="tag" compact="no"> 227 <list type="tag" compact="no">
228 228
229 <tag-name><var>$secure_link</var></tag-name> 229 <tag-name><var>$secure_link</var></tag-name>
230 <tag-desc> 230 <tag-desc>
231 Status of a link check. 231 The status of a link check.
232 The specific value depends on the selected operation mode. 232 The specific value depends on the selected operation mode.
233 </tag-desc> 233 </tag-desc>
234 234
235 <tag-name><var>$secure_link_expires</var></tag-name> 235 <tag-name><var>$secure_link_expires</var></tag-name>
236 <tag-desc> 236 <tag-desc>
237 Lifetime of a link passed in a request; 237 The lifetime of a link passed in a request;
238 intended to be used only in the 238 intended to be used only in the
239 <link id="secure_link_md5"/> directive. 239 <link id="secure_link_md5"/> directive.
240 </tag-desc> 240 </tag-desc>
241 241
242 </list> 242 </list>