nginx中文文档-ngx_mail_ssl_module

ngx_mail_ssl_module模块为工作在SSL/TSL协议的邮件代理服务器提供了必要的支持。该模块默认不会构建,需要通过–with-mail_ssl_module配置参数启用。该模块需要OpenSSL库。

示例配置
为了减少处理器的负载,建议:

  • 设置工作进程数等于处理器数
  • 启用共享会话缓存
  • 禁用built-in会话缓存
  • 增加会话有效期(默认是5分钟):
worker_processes auto;

mail {

    ...

    server {
        listen              993 ssl;

        ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/nginx/conf/cert.pem;
        ssl_certificate_key /usr/local/nginx/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        ...
    }

ssl

语法:ssl on | off
默认:ssl off
上下文:mail, server

为给定服务器启用SSL/TLS协议。

ssl_certificate

语法:ssl_certificate file
默认:—
上下文:mail, server

为给定服务器指定一个PEM格式的证书文件。如果除了初级证书之外,还要指定中级证书,则它们需要在同一个文件中按如下顺序指定:先是初级证书,然后是中级证书。PEM格式的密钥也需要在同一个文件中指定。

ssl_certificate_key

语法:ssl_certificate_key file
默认:—
上下文:mail, server

为给定的服务器指定PEM格式的密钥文件。
可以指定engine:name:id值以代替文件(1.7.9+),这个值会从OpenSSL引擎name中加载指定的id的密钥。

ssl_ciphers

语法:ssl_ciphers ciphers
默认:ssl_ciphers HIGH:!aNULL:!MD5;
上下文:mail, server

指定启用的加密算法。加密算法指定为OpenSSL支持的格式,例如:
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
完整的列表可以通过“openssl ciphers”命令查看。
之前版本的nginx默认使用不同的加密算法。

ssl_client_certificate

语法:ssl_client_certificate file
默认:—
上下文:mail, server
版本:1.7.11+

指定用于验证客户端证书的PEM格式的可信CA证书文件。
证书列表将会发送到客户端。如果不希望这样,可以使用ssl_trusted_certificate指令。

ssl_crl

语法:ssl_crl file
默认:—
上下文:mail, server
版本:1.7.11+

指定用于验证客户端证书的PEM格式的吊销证书文件。

ssl_dhparam

语法:ssl_dhparam file
默认:—
上下文:mail, server
版本:0.7.2+

指定带DH参数的DHE算法文件。

ssl_ecdh_curve

语法:ssl_ecdh_curve curve
默认:ssl_ecdh_curve auto
上下文:mail, server
版本:1.1.0+1.0.6+

为ECDHE算法指定curve。
当使用OpenSSL1.0.2或更高版本,可以指定多个curves(1.11.0+),例如:
ssl_ecdh_curve prime256v1:secp384r1;
特殊值auto(1.11.0)指示nginx在使用OpenSSL 1.0.2或更高版本时使用一个构建于OpenSSL库中的列表,在老版本中使用prime256v1。
在1.11.0版本之前,默认使用prime256v1 curve。

ssl_password_file

语法:ssl_password_file file
默认:—
上下文:mail, server
版本:1.7.3+

指定一个密钥的密码文件,每个密码单独占一行。密码在加载密钥时会轮流尝试。
例子:

mail {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name mail1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name mail2.example.com;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}

ssl_prefer_server_ciphers

语法:ssl_prefer_server_ciphers on | off
默认:ssl_prefer_server_ciphers off
上下文:mail, server

当使用SSLv3和TLS协议时,指定服务器的加密算法优先于客户端的加密算法。

ssl_protocols

语法:ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]
默认:ssl_protocols TLSv1 TLSv1.1 TLSv1.2
上下文:mail, server

启用指定的协议。TLSv1.1和TLS1.2参数只有在OpenSSL库版本不低于1.0.1时有效。
TLSv1.1和TLSv1.2参数从1.1.13和1.0.12版本开始支持,所以当OpenSSL版本1.0.1或更高版本用于老的nginx版本中时,这些协议工作,但不能禁用。

ssl_session_cache

语法:ssl_session_cache off | none | [builtin[:size]] [shared:name:size]
默认:ssl_session_cache none
上下文:mail, server

设置存储会话参数的缓存类型和大小。一个缓存可以是下面的任何类型:
off
使用会话缓存是严格禁止的:nginx明确的告诉客户端会话不能重用。

none
使用会话缓存是不允许的:nginx告诉客户端会话可以重用,但实际并不在缓存中保存会话参数。

builtin
建立在OpenSSL中的缓存。只使用一个工作进程。缓存的大小指定在会话中。如果大小没有给出,它等于20480个会话。使用built-in缓存可以引起内存碎片。

shared
共享于所有工作进程之间的缓存。缓存大小指定位字节。1M的缓存可以保存大约4000个会话。每个共享的缓存都有独有的名字。相同名字的缓存可以在多个服务器中使用。
缓存类型可以同时使用,例如:
ssl_session_cache builtin:1000 shared:SSL:10m;
但只使用共享缓存不使用built-in缓存会更有效。

ssl_session_ticket_key

语法:ssl_session_ticket_key file
默认:—
上下文:mail, server
版本:1.5.7+

设置用于加密解密TLS会话凭证的密钥文件。如果相同的关键字在多个服务器之间共享,这个指令是必要的。默认情况下,关键字是随机生成的。
如果指定多个关键字,只有第一个用于加密TLS会话凭证。这允许配置关键词轮询,例如:

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

这个文件必须包含48字节的随机数据,它们可以使用下面命令创建:
openssl rand 48 > ticket.key

ssl_session_tickets

语法:ssl_session_tickets on | off
默认:ssl_session_tickets on
上下文:mail, server
版本:1.5.9+

启用或禁用通过TLS会话凭证的会话恢复。

ssl_session_timeout

语法:ssl_session_timeout time
默认:ssl_session_timeout 5m
上下文:mail, server

指定一个时间,在这个期间内客户端可以从用保存在缓存中的会话参数。

ssl_trusted_certificate

语法:ssl_trusted_certificate file
默认:—
上下文:mail, server
版本:1.7.11+

指定一个PEM格式的可信CA证书文件用户验证客户端证书。
相比于ssl_client_certificate指令设置的证书,这里的证书列表不会发送到客户端。

ssl_verify_client

语法:ssl_verify_client on | off | optional | optional_no_ca
默认:ssl_verify_client off
上下文:mail, server
版本:1.7.11+

启用验证客户端证书。验证结果通过验证请求的“Auth-SSL-Verify”头传递。
optional参数请求客户端证书,如果证书存在就验证它。
optional_no_ca参数请求客户端证书但是不需要它是可信CA签发的证书。这用于nginx外部服务器验证实际的证书。证书的内容可以通过发送到认证服务器的请求访问。

ssl_verify_depth

语法:ssl_verify_depth number
默认:ssl_verify_depth 1
上下文:mail, server
版本:1.7.11+

设置验证客户端证书链的深度。

starttls

语法:starttls on | off | only
默认:starttls off
上下文:mail, server

on
允许使用POP3的STLS命令以及IMAP的STARTTLS命令。

off
不允许使用STLS和STARTTLS命令。

only
需要初级TLS过渡。

nginx中文文档-ngx_mail_proxy_module

proxy_buffer

语法:proxy_buffer size
默认:proxy_buffer 4k|8k
上下文:mail, server

设置用于代理的缓冲区大小。默认情况下,缓冲区等于一页内存。大小为4k或8k取决于平台。

proxy_pass_error_message

语法:proxy_pass_error_message on | off
默认:proxy_pass_error_message off
上下文:mail, server

指示在与后端认证过程中得到的错误信息是否传给客户端。
通常,如果nginx认证成功,后端不能返回错误。如果它返回了错误,意味着有一些内部错误发生了。这种情况下,后端的信息可以包含不显示给客户端的信息。但是,对某些POP3服务器来说,对正确的密码响应一个错误是正常的行为。例如,CommuniGatePro告诉用户关于邮箱溢出或其他偶尔输出的认证错误的事件。指令在这种情况下应该启用。

proxy_timeout

语法:proxy_timeout timeout
默认:proxy_timeout 24h
上下文:mail, server

设置与客户端或被代理服务器连接是,两次成功的读或写操作之间的超时时间。如果在此期间没有数据传输,连接会被关闭。

xclient

语法:xclient on | off
默认:xclient on
上下文:mail, server

启用或禁用连接到SMTP后端时,传递带客户端参数的XCLIENT命令。
MTA可以写客户端信息到日志中并应用基于这个数据的多种限制。
如果XCLIENT启用则nginx在连接后端时传递下面的指令:

  • 与服务器名称的EHLO
  • XCLIENT
  • EHLO或HELO由客户端传递

如果名称被发现是指向同一个地址的客户端IP地址,它将通过XCLIENT命令的NAME参数传递。如果名称没有发现,指向不同的IP地址或没有指定解析器,[UNAVAILABLE]将通过NAME参数传递。如果在解析过程中发生了错误,使用[TEMPUNAVAIL]值。
如果XCLIENT禁用,则如果客户端传递EHLO,nginx在与后端连接时,传递带有服务器名称的EHLO命令,否则传递HELO。