Mercurial > hg > nginx-site

comparison xml/ru/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 07402a11fd8d
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="Модуль ngx_http_secure_link_module" 10 <module name="Модуль ngx_http_secure_link_module"
11 link="/ru/docs/http/ngx_http_secure_link_module.html" 11 link="/ru/docs/http/ngx_http_secure_link_module.html"
12 lang="ru" 12 lang="ru"
13 rev="1"> 13 rev="2">
14 14
15 <section id="summary"> 15 <section id="summary">
16 16
17 <para> 17 <para>
18 Модуль <literal>ngx_http_secure_link_module</literal> (0.7.18+) проверяет 18 Модуль <literal>ngx_http_secure_link_module</literal> (0.7.18)
19 правильность запрашиваемой ссылки. 19 позволяет проверять аутентичность запрашиваемых ссылок,
20 защищать ресурсы от несанкционированного доступа,
21 а также ограничивать срок действия ссылок.
22 </para>
23
24 <para>
25 Правильность запрашиваемой ссылки проверяется сравнением переданного
26 в запросе значения контрольной суммы со значением,
27 вычисляемым для запроса.
28 Если ссылка имеет ограниченный срок действия и он истёк,
29 ссылка считается устаревшей.
30 Результат этих проверок делается доступным в переменной
31 <var>$secure_link</var>.
32 </para>
33
34 <para>
35 Модуль реализует два альтернативных режима работы.
36 В первом режиме, который включается директивой
37 <link id="secure_link_secret"/>, можно проверить аутентичность
38 запрашиваемых ссылок и защитить их от несанкционированного доступа.
39 Второй режим (0.8.50) включается директивами
40 <link id="secure_link"/> и <link id="secure_link_md5"/>,
41 и позволяет также ограничить срок действия ссылок.
20 </para> 42 </para>
21 43
22 <para> 44 <para>
23 По умолчанию этот модуль не собирается, его сборку необходимо 45 По умолчанию этот модуль не собирается, его сборку необходимо
24 разрешить с помощью конфигурационного параметра 46 разрешить с помощью конфигурационного параметра
26 </para> 48 </para>
27 49
28 </section> 50 </section>
29 51
30 52
31 <section id="example" name="Пример конфигурации"> 53 <section id="directives" name="Директивы">
32 54
33 <para> 55 <directive name="secure_link">
34 <example> 56 <syntax><value>выражение</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 Задаёт строку с переменными, из которой будет выделено значение
64 контрольной суммы и время действия ссылки.
65 </para>
66
67 <para>
68 Используемые в выражении переменные обычно связаны с запросом;
69 см. <link id="secure_link_md5">пример</link> ниже.
70 </para>
71
72 <para>
73 Выделенное из строки значение контрольной суммы сравнивается со
74 значением MD5-хэша, вычисляемым для выражения, заданного
75 директивой <link id="secure_link_md5"/>.
76 Если контрольные суммы не совпадают, значением переменной
77 <var>$secure_link</var> становится пустая строка.
78 Если контрольные суммы совпадают, проверяется время действия ссылки.
79 Если срок действия ссылки задан и истёк, переменная
80 <var>$secure_link</var> получает значение “<literal>0</literal>”.
81 В противном случае она получает значение “<literal>1</literal>”.
82 Значение MD5-хэш передаётся в запросе закодированным в
83 <link url="http://tools.ietf.org/html/rfc4648#section-5">base64url</link>.
84 </para>
85
86 <para>
87 Если ссылка имеет ограниченный срок действия, время её действия
88 задаётся в секундах с начала эпохи (1 января 1970 года 00:00:00 GMT).
89 Значение указывается в выражении после MD5-хэша
90 и отделяется от него запятой.
91 Время действия ссылки, переданное в запросе, делается доступным
92 в переменной <var>$secure_link_expires</var> для использования
93 в директиве <link id="secure_link_md5"/>.
94 Если время действия ссылки не задано, ссылка имеет неограниченный
95 срок действия.
96 </para>
97
98 </directive>
99
100
101 <directive name="secure_link_md5">
102 <syntax><value>выражение</value></syntax>
103 <default/>
104 <context>http</context>
105 <context>server</context>
106 <context>location</context>
107
108 <para>
109 Задаёт выражение, для которого считается значение MD5-хэш,
110 сравниваемое с переданным в запросе.
111 </para>
112
113 <para>
114 Выражение должно содержать защищаемую часть ссылки (ресурс)
115 и секретную составляющую.
116 Если ссылка имеет ограниченный срок действия,
117 выражение также должно содержать <var>$secure_link_expires</var>.
118 </para>
119
120 <para>
121 Для предотвращения несанкционированного доступа выражение
122 может содержать информацию о клиенте, например, его адрес и
123 версию браузера.
124 </para>
125
126 <para>
127 Пример:
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 Ссылка
44 145 “<literal>/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&amp;expires=2147483647</literal>”
45 </section> 146 ограничивает доступ к “<literal>/s/link</literal>” для клиента с IP-адресом
46 147 127.0.0.1.
47 148 Ссылка также имеет ограниченный срок действия до 19 января 2038 года (GMT).
48 <section id="directives" name="Директивы"> 149 </para>
150
151 <para>
152 Значение аргумента запроса <value>md5</value> на UNIX можно получить так:
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>слово</value></syntax> 163 <syntax><value>слово</value></syntax>
52 <default/> 164 <default/>
53 <context>location</context> 165 <context>location</context>
54 166
55 <para> 167 <para>
56 Задаёт секретное <value>слово</value> для проверки правильности ссылки. 168 Задаёт секретное <value>слово</value> для проверки аутентичности
57 Полный URL защищённой ссылки выглядит так: 169 запрашиваемых ссылок.
58 <example> 170 </para>
59 /prefix/<value>hash</value>/<value>ссылка</value> 171
60 </example> 172 <para>
61 где <value>hash</value> считается как 173 Полный URI запрашиваемой ссылки выглядит так:
62 <example> 174 <example>
63 md5(ссылка, секретное_слово); 175 /<value>префикс</value>/<value>хэш</value>/<value>ссылка</value>
64 </example> 176 </example>
65 </para> 177 где <value>хэш</value> — MD5-хэш в шестнадцатеричном виде,
66 178 вычисленный для конкатенации ссылки и секретного слова,
67 <para> 179 а <value>префикс</value> — произвольная строка без слэшей.
68 Префикс — произвольная строка, не включающая слэш. 180 </para>
181
182 <para>
183 Если запрашиваемая ссылка проходит проверку на аутентичность,
184 значением переменной <var>$secure_link</var> становится ссылка,
185 выделенная из URI запроса.
186 В противном случае значением переменной <var>$secure_link</var>
187 становится пустая строка.
188 </para>
189
190 <para>
191 Пример:
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 По запросу “<literal>/p/5e814704a28d9bc1914ff19fa0c4a00a/link</literal>”
208 будет выполнено внутреннее перенаправление на
209 “<literal>/secure/link</literal>”.
210 </para>
211
212 <para>
213 Значение хэша для данного примера на UNIX можно получить так:
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="Встроенные переменные"> 224 <section id="variables" name="Встроенные переменные">
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 равна ссылке, выделенной из полного URL’а. 231 Результат проверки ссылки.
84 Если хэш неверный, то переменная равна пустой строке. 232 Конкретное значение зависит от выбранного режима работы.
85 </tag-desc> 233 </tag-desc>
86 234
235 <tag-name><var>$secure_link_expires</var></tag-name>
236 <tag-desc>
237 Время действия ссылки, переданное в запросе.
238 Предназначено исключительно для использования в директиве
239 <link id="secure_link_md5"/>.
240 </tag-desc>
241
87 </list> 242 </list>
88 </para> 243 </para>
89 244
90 </section> 245 </section>
91 246