Mercurial > hg > nginx-site
view xml/ru/docs/mail/ngx_mail_auth_http_module.xml @ 2769:16f6fa718be2
Updated TLSv1.3 support notes.
Previous notes described some early development snapshot of OpenSSL 1.1.1
with disabled TLSv1.3 by default. It was then enabled in the first alpha.
Further, the updated text covers later major releases such as OpenSSL 3.0.
author | Sergey Kandaurov <pluknet@nginx.com> |
---|---|
date | Thu, 30 Sep 2021 16:29:20 +0300 |
parents | 96d6d66d36e4 |
children | 7b7dbaa7d777 |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) 2006, 2007 Anton Yuzhaninov Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_mail_auth_http_module" link="/ru/docs/mail/ngx_mail_auth_http_module.html" lang="ru" rev="11"> <section id="directives" name="Директивы"> <directive name="auth_http"> <syntax><value>URL</value></syntax> <default/> <context>mail</context> <context>server</context> <para> Задаёт URL HTTP-сервера аутентификации. Протокол описан <link id="protocol">ниже</link>. </para> </directive> <directive name="auth_http_header"> <syntax><value>заголовок</value> <value>значение</value></syntax> <default/> <context>mail</context> <context>server</context> <para> Добавляет указанный заголовок к запросам, посылаемым на сервер аутентификации. Заголовок можно использовать в качестве shared secret для проверки, что запрос поступил от nginx. Например: <example> auth_http_header X-Auth-Key "secret_string"; </example> </para> </directive> <directive name="auth_http_pass_client_cert"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>mail</context> <context>server</context> <appeared-in>1.7.11</appeared-in> <para> Добавляет заголовок <header>Auth-SSL-Cert</header> с <link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">клиентским</link> сертификатом в формате PEM (закодирован в формате urlencode) к запросам, посылаемым на сервер аутентификации. </para> </directive> <directive name="auth_http_timeout"> <syntax><value>время</value></syntax> <default>60s</default> <context>mail</context> <context>server</context> <para> Задаёт таймаут общения с сервером аутентификации. </para> </directive> </section> <section id="protocol" name="Протокол"> <para> Для общения с сервером аутентификации используется протокол HTTP. Данные в теле ответа игнорируются, информация передаётся только в заголовках. </para> <para> Примеры запросов и ответов: </para> <para> Запрос: <example> GET /auth HTTP/1.0 Host: localhost Auth-Method: plain # plain/apop/cram-md5/external Auth-User: user Auth-Pass: password Auth-Protocol: imap # imap/pop3/smtp Auth-Login-Attempt: 1 Client-IP: 192.0.2.42 Client-Host: client.example.org </example> Хороший ответ: <example> HTTP/1.0 200 OK Auth-Status: OK Auth-Server: 198.51.100.1 Auth-Port: 143 </example> Плохой ответ: <example> HTTP/1.0 200 OK Auth-Status: Invalid login or password Auth-Wait: 3 </example> </para> <para> Если заголовка <header>Auth-Wait</header> нет, то после выдачи ошибки соединение будет закрыто. В текущей реализации на каждую попытку аутентификации выделяется память, которая освобождается только при завершении сессии. Поэтому число неудачных попыток аутентификации в рамках одной сессии должно быть ограничено — после 10-20 попыток (номер попытки передаётся в заголовке <header>Auth-Login-Attempt</header>) сервер должен выдать ответ без заголовка <header>Auth-Wait</header>. </para> <para> При использовании APOP или CRAM-MD5 запрос и ответ будут выглядеть так: <example> GET /auth HTTP/1.0 Host: localhost Auth-Method: apop Auth-User: user Auth-Salt: <238188073.1163692009@mail.example.com> Auth-Pass: auth_response Auth-Protocol: imap Auth-Login-Attempt: 1 Client-IP: 192.0.2.42 Client-Host: client.example.org </example> Хороший ответ: <example> HTTP/1.0 200 OK Auth-Status: OK Auth-Server: 198.51.100.1 Auth-Port: 143 Auth-Pass: plain-text-pass </example> </para> <para> Если в ответе есть заголовок <header>Auth-User</header>, то он переопределяет имя пользователя, используемое для аутентификации с бэкендом. </para> <para> Для SMTP в ответе дополнительно учитывается заголовок <header>Auth-Error-Code</header> — если он есть, то используется как код ответа в случае ошибки. Если его нет, то по умолчанию к <header>Auth-Status</header> будет добавлен код 535 5.7.0. </para> <para> Например, если от сервера аутентификации будет получен ответ: <example> HTTP/1.0 200 OK Auth-Status: Temporary server problem, try again later Auth-Error-Code: 451 4.3.0 Auth-Wait: 3 </example> то по SMTP клиенту будет выдана ошибка <example> 451 4.3.0 Temporary server problem, try again later </example> </para> <para> Если при проксировании SMTP не требуется аутентификация, запрос будет выглядеть так: <example> GET /auth HTTP/1.0 Host: localhost Auth-Method: none Auth-User: Auth-Pass: Auth-Protocol: smtp Auth-Login-Attempt: 1 Client-IP: 192.0.2.42 Client-Host: client.example.org Auth-SMTP-Helo: client.example.org Auth-SMTP-From: MAIL FROM: <> Auth-SMTP-To: RCPT TO: <postmaster@mail.example.com> </example> </para> <para> Для клиентского соединения по протоколу SSL/TLS (1.7.11) добавляется заголовок <header>Auth-SSL</header>, и если директива <link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client"/> включена, заголовок <header>Auth-SSL-Verify</header> содержит результат проверки клиентского сертификата: “<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>” и, если сертификат не был предоставлен, “<literal>NONE</literal>”. <note> До версии 1.11.7 результат “<literal>FAILED</literal>” не содержал строку <value>reason</value>. </note> Если клиентский сертификат был предоставлен, информация о нём передаётся в следующих заголовках запроса: <header>Auth-SSL-Subject</header>, <header>Auth-SSL-Issuer</header>, <header>Auth-SSL-Serial</header> и <header>Auth-SSL-Fingerprint</header>. Если директива <link id="auth_http_pass_client_cert"/> включена, сам сертификат передаётся в заголовке <header>Auth-SSL-Cert</header>. Протокол и шифр установленного соединения передаются в заголовках <header>Auth-SSL-Protocol</header> и <header>Auth-SSL-Cipher</header> (1.21.2). Запрос будет выглядеть так: <example> GET /auth HTTP/1.0 Host: localhost Auth-Method: plain Auth-User: user Auth-Pass: password Auth-Protocol: imap Auth-Login-Attempt: 1 Client-IP: 192.0.2.42 Auth-SSL: on Auth-SSL-Protocol: TLSv1.3 Auth-SSL-Cipher: TLS_AES_256_GCM_SHA384 Auth-SSL-Verify: SUCCESS Auth-SSL-Subject: /CN=example.com Auth-SSL-Issuer: /CN=example.com Auth-SSL-Serial: C07AD56B846B5BFF Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad </example> </para> <para id="proxy_protocol"> При использовании <link doc="ngx_mail_core_module.xml" id="proxy_protocol">протокола PROXY</link>, информация о нём передаётся в следующих заголовках запроса: <header>Proxy-Protocol-Addr</header>, <header>Proxy-Protocol-Port</header>, <header>Proxy-Protocol-Server-Addr</header> и <header>Proxy-Protocol-Server-Port</header> (1.19.8). </para> </section> </module>