Mercurial > hg > nginx-site
view xml/en/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="Module ngx_mail_auth_http_module" link="/en/docs/mail/ngx_mail_auth_http_module.html" lang="en" rev="11"> <section id="directives" name="Directives"> <directive name="auth_http"> <syntax><value>URL</value></syntax> <default/> <context>mail</context> <context>server</context> <para> Sets the URL of the HTTP authentication server. The protocol is described <link id="protocol">below</link>. </para> </directive> <directive name="auth_http_header"> <syntax><value>header</value> <value>value</value></syntax> <default/> <context>mail</context> <context>server</context> <para> Appends the specified header to requests sent to the authentication server. This header can be used as the shared secret to verify that the request comes from nginx. For example: <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> Appends the <header>Auth-SSL-Cert</header> header with the <link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">client</link> certificate in the PEM format (urlencoded) to requests sent to the authentication server. </para> </directive> <directive name="auth_http_timeout"> <syntax><value>time</value></syntax> <default>60s</default> <context>mail</context> <context>server</context> <para> Sets the timeout for communication with the authentication server. </para> </directive> </section> <section id="protocol" name="Protocol"> <para> The HTTP protocol is used to communicate with the authentication server. The data in the response body is ignored, the information is passed only in the headers. </para> <para> Examples of requests and responses: </para> <para> Request: <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> Good response: <example> HTTP/1.0 200 OK Auth-Status: OK Auth-Server: 198.51.100.1 Auth-Port: 143 </example> Bad response: <example> HTTP/1.0 200 OK Auth-Status: Invalid login or password Auth-Wait: 3 </example> </para> <para> If there is no <header>Auth-Wait</header> header, an error will be returned and the connection will be closed. The current implementation allocates memory for each authentication attempt. The memory is freed only at the end of a session. Therefore, the number of invalid authentication attempts in a single session must be limited — the server must respond without the <header>Auth-Wait</header> header after 10-20 attempts (the attempt number is passed in the <header>Auth-Login-Attempt</header> header). </para> <para> When the APOP or CRAM-MD5 are used, request-response will look as follows: <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> Good response: <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> If the <header>Auth-User</header> header exists in the response, it overrides the username used to authenticate with the backend. </para> <para> For the SMTP, the response additionally takes into account the <header>Auth-Error-Code</header> header — if exists, it is used as a response code in case of an error. Otherwise, the 535 5.7.0 code will be added to the <header>Auth-Status</header> header. </para> <para> For example, if the following response is received from the authentication server: <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> then the SMTP client will receive an error <example> 451 4.3.0 Temporary server problem, try again later </example> </para> <para> If proxying SMTP does not require authentication, the request will look as follows: <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> For the SSL/TLS client connection (1.7.11), the <header>Auth-SSL</header> header is added, and <header>Auth-SSL-Verify</header> will contain the result of client certificate verification, if <link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">enabled</link>: “<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>”, and “<literal>NONE</literal>” if a certificate was not present. <note> Prior to version 1.11.7, the “<literal>FAILED</literal>” result did not contain the <value>reason</value> string. </note> When the client certificate was present, its details are passed in the following request headers: <header>Auth-SSL-Subject</header>, <header>Auth-SSL-Issuer</header>, <header>Auth-SSL-Serial</header>, and <header>Auth-SSL-Fingerprint</header>. If <link id="auth_http_pass_client_cert"/> is enabled, the certificate itself is passed in the <header>Auth-SSL-Cert</header> header. The protocol and cipher of the established connection are passed in the <header>Auth-SSL-Protocol</header> and <header>Auth-SSL-Cipher</header> headers (1.21.2). The request will look as follows: <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"> When the <link doc="ngx_mail_core_module.xml" id="proxy_protocol">PROXY protocol</link> is used, its details are passed in the following request headers: <header>Proxy-Protocol-Addr</header>, <header>Proxy-Protocol-Port</header>, <header>Proxy-Protocol-Server-Addr</header>, and <header>Proxy-Protocol-Server-Port</header> (1.19.8). </para> </section> </module>