doc: documented the new SSL cosocket feature.
This commit is contained in:
Yichun Zhang (agentzh)
Родитель
fd3f4ee250
Коммит
2b40b44dcd
130
README.markdown
130
README.markdown
|
|
@ -1005,6 +1005,11 @@ Directives
|
|||
* [lua_socket_pool_size](#lua_socket_pool_size)
|
||||
* [lua_socket_keepalive_timeout](#lua_socket_keepalive_timeout)
|
||||
* [lua_socket_log_errors](#lua_socket_log_errors)
|
||||
* [lua_ssl_ciphers](#lua_ssl_ciphers)
|
||||
* [lua_ssl_crl](#lua_ssl_crl)
|
||||
* [lua_ssl_protocols](#lua_ssl_protocols)
|
||||
* [lua_ssl_trusted_certificate](#lua_ssl_trusted_certificate)
|
||||
* [lua_ssl_verify_depth](#lua_ssl_verify_depth)
|
||||
* [lua_http10_buffering](#lua_http10_buffering)
|
||||
* [rewrite_by_lua_no_postpone](#rewrite_by_lua_no_postpone)
|
||||
* [lua_transform_underscores_in_response_headers](#lua_transform_underscores_in_response_headers)
|
||||
|
|
@ -2080,6 +2085,87 @@ This directive was first introduced in the `v0.5.13` release.
|
|||
|
||||
[Back to TOC](#directives)
|
||||
|
||||
lua_ssl_ciphers
|
||||
---------------
|
||||
|
||||
**syntax:** *lua_ssl_ciphers <ciphers>*
|
||||
|
||||
**default:** *lua_ssl_ciphers DEFAULT*
|
||||
|
||||
**context:** *http, server, location*
|
||||
|
||||
Specifies the enabled ciphers for requests to a SSL/TLS server in the [tcpsock:sslhandshake](#tcpsocksslhandshake) method. The ciphers are specified in the format understood by the OpenSSL library.
|
||||
|
||||
The full list can be viewed using the “openssl ciphers” command.
|
||||
|
||||
This directive was first introduced in the `v0.9.11` release.
|
||||
|
||||
[Back to TOC](#directives)
|
||||
|
||||
lua_ssl_crl
|
||||
-----------
|
||||
|
||||
**syntax:** *lua_ssl_crl <file>*
|
||||
|
||||
**default:** *no*
|
||||
|
||||
**context:** *http, server, location*
|
||||
|
||||
Specifies a file with revoked certificates (CRL) in the PEM format used to verify the certificate of the SSL/TLS server in the [tcpsock:sslhandshake](#tcpsocksslhandshake) method.
|
||||
|
||||
This directive was first introduced in the `v0.9.11` release.
|
||||
|
||||
[Back to TOC](#directives)
|
||||
|
||||
lua_ssl_protocols
|
||||
-----------------
|
||||
|
||||
**syntax:** *lua_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]*
|
||||
|
||||
**default:** *lua_ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2*
|
||||
|
||||
**context:** *http, server, location*
|
||||
|
||||
Enables the specified protocols for requests to a SSL/TLS server in the [tcpsock:sslhandshake](#tcpsocksslhandshake) method.
|
||||
|
||||
This directive was first introduced in the `v0.9.11` release.
|
||||
|
||||
[Back to TOC](#directives)
|
||||
|
||||
lua_ssl_trusted_certificate
|
||||
---------------------------
|
||||
|
||||
**syntax:** *lua_ssl_trusted_certificate <file>*
|
||||
|
||||
**default:** *no*
|
||||
|
||||
**context:** *http, server, location*
|
||||
|
||||
Specifies a file path with trusted CA certificates in the PEM format used to verify the certificate of the SSL/TLS server in the [tcpsock:sslhandshake](#tcpsocksslhandshake) method.
|
||||
|
||||
This directive was first introduced in the `v0.9.11` release.
|
||||
|
||||
See also [lua_ssl_verify_depth](#lua_ssl_verify_depth).
|
||||
|
||||
[Back to TOC](#directives)
|
||||
|
||||
lua_ssl_verify_depth
|
||||
--------------------
|
||||
|
||||
**syntax:** *lua_ssl_verify_depth <number>*
|
||||
|
||||
**default:** *lua_ssl_verify_depth 1*
|
||||
|
||||
**context:** *http, server, location*
|
||||
|
||||
Sets the verification depth in the server certificates chain.
|
||||
|
||||
This directive was first introduced in the `v0.9.11` release.
|
||||
|
||||
See also [lua_ssl_trusted_certificate](#lua_ssl_trusted_certificate).
|
||||
|
||||
[Back to TOC](#directives)
|
||||
|
||||
lua_http10_buffering
|
||||
--------------------
|
||||
|
||||
|
|
@ -2303,6 +2389,7 @@ Nginx API for Lua
|
|||
* [udpsock:settimeout](#udpsocksettimeout)
|
||||
* [ngx.socket.tcp](#ngxsockettcp)
|
||||
* [tcpsock:connect](#tcpsockconnect)
|
||||
* [tcpsock:sslhandshake](#tcpsocksslhandshake)
|
||||
* [tcpsock:send](#tcpsocksend)
|
||||
* [tcpsock:receive](#tcpsockreceive)
|
||||
* [tcpsock:receiveuntil](#tcpsockreceiveuntil)
|
||||
|
|
@ -5660,6 +5747,7 @@ ngx.socket.tcp
|
|||
Creates and returns a TCP or stream-oriented unix domain socket object (also known as one type of the "cosocket" objects). The following methods are supported on this object:
|
||||
|
||||
* [connect](#tcpsockconnect)
|
||||
* [sslhandshake](#tcpsocksslhandshake)
|
||||
* [send](#tcpsocksend)
|
||||
* [receive](#tcpsockreceive)
|
||||
* [close](#tcpsockclose)
|
||||
|
|
@ -5762,6 +5850,48 @@ This method was first introduced in the `v0.5.0rc1` release.
|
|||
|
||||
[Back to TOC](#nginx-api-for-lua)
|
||||
|
||||
tcpsock:sslhandshake
|
||||
--------------------
|
||||
**syntax:** *session, err = tcpsock:sslhandshake(reused_session?, server_name?, ssl_verify?)*
|
||||
|
||||
**context:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.**
|
||||
|
||||
Does SSL/TLS handshake on the currently established connection.
|
||||
|
||||
The optional `reused_session` argument can take a former SSL
|
||||
session userdata returned by a previous `sslhandshake`
|
||||
call for exactly the same target. For short-lived connections, reusing SSL
|
||||
sessions can usually speed up the handshake by one order by magnitude but it
|
||||
is not so useful if the connection pool is enabled. This argument defaults to
|
||||
`nil`. If this argument takes the boolean `false` value, no SSL session
|
||||
userdata would return by this call and only a Lua boolean will be returned as
|
||||
the first return value; otherwise the current SSL session will
|
||||
always be returned as the first argument in case of successes.
|
||||
|
||||
The optional `server_name` argument is used to specify the server
|
||||
name for the new TLS extension Server Name Indication (SNI). Use of SNI can
|
||||
make different servers share the same IP address on the server side. Also,
|
||||
when SSL verification is enabled, this `server_name` argument is
|
||||
also used to validate the server name specified in the server certificate sent from
|
||||
the remote.
|
||||
|
||||
The optional `ssl_verify` argument takes a Lua boolean value to
|
||||
control whether to perform SSL verification. When set to `true`, the server
|
||||
certificate will be verified according to the CA certificates specified by
|
||||
the [lua_ssl_trusted_certificate](#lua_ssl_trusted_certificate) directive.
|
||||
You may also need to adjust the [lua_ssl_verify_depth](#lua_ssl_verify_depth)
|
||||
directive to control how deep we should follow along the certificate chain.
|
||||
Also, when the `ssl_verify` argument is true and the
|
||||
`server_name` argument is also specified, the latter will be used
|
||||
to validate the server name in the server certificate.
|
||||
|
||||
For connections that have already done SSL/TLS handshake, this method returns
|
||||
immediately.
|
||||
|
||||
This method was first introduced in the `v0.9.11` release.
|
||||
|
||||
[Back to TOC](#nginx-api-for-lua)
|
||||
|
||||
tcpsock:send
|
||||
------------
|
||||
**syntax:** *bytes, err = tcpsock:send(data)*
|
||||
|
|
|
|||
|
|
@ -1742,6 +1742,72 @@ This directive can be used to toggle error logging when a failure occurs for the
|
|||
|
||||
This directive was first introduced in the <code>v0.5.13</code> release.
|
||||
|
||||
== lua_ssl_ciphers ==
|
||||
|
||||
'''syntax:''' ''lua_ssl_ciphers <ciphers>''
|
||||
|
||||
'''default:''' ''lua_ssl_ciphers DEFAULT''
|
||||
|
||||
'''context:''' ''http, server, location''
|
||||
|
||||
Specifies the enabled ciphers for requests to a SSL/TLS server in the [[#tcpsock:sslhandshake|tcpsock:sslhandshake]] method. The ciphers are specified in the format understood by the OpenSSL library.
|
||||
|
||||
The full list can be viewed using the “openssl ciphers” command.
|
||||
|
||||
This directive was first introduced in the <code>v0.9.11</code> release.
|
||||
|
||||
== lua_ssl_crl ==
|
||||
|
||||
'''syntax:''' ''lua_ssl_crl <file>''
|
||||
|
||||
'''default:''' ''no''
|
||||
|
||||
'''context:''' ''http, server, location''
|
||||
|
||||
Specifies a file with revoked certificates (CRL) in the PEM format used to verify the certificate of the SSL/TLS server in the [[#tcpsock:sslhandshake|tcpsock:sslhandshake]] method.
|
||||
|
||||
This directive was first introduced in the <code>v0.9.11</code> release.
|
||||
|
||||
== lua_ssl_protocols ==
|
||||
|
||||
'''syntax:''' ''lua_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]''
|
||||
|
||||
'''default:''' ''lua_ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2''
|
||||
|
||||
'''context:''' ''http, server, location''
|
||||
|
||||
Enables the specified protocols for requests to a SSL/TLS server in the [[#tcpsock:sslhandshake|tcpsock:sslhandshake]] method.
|
||||
|
||||
This directive was first introduced in the <code>v0.9.11</code> release.
|
||||
|
||||
== lua_ssl_trusted_certificate ==
|
||||
|
||||
'''syntax:''' ''lua_ssl_trusted_certificate <file>''
|
||||
|
||||
'''default:''' ''no''
|
||||
|
||||
'''context:''' ''http, server, location''
|
||||
|
||||
Specifies a file path with trusted CA certificates in the PEM format used to verify the certificate of the SSL/TLS server in the [[#tcpsock:sslhandshake|tcpsock:sslhandshake]] method.
|
||||
|
||||
This directive was first introduced in the <code>v0.9.11</code> release.
|
||||
|
||||
See also [[#lua_ssl_verify_depth|lua_ssl_verify_depth]].
|
||||
|
||||
== lua_ssl_verify_depth ==
|
||||
|
||||
'''syntax:''' ''lua_ssl_verify_depth <number>''
|
||||
|
||||
'''default:''' ''lua_ssl_verify_depth 1''
|
||||
|
||||
'''context:''' ''http, server, location''
|
||||
|
||||
Sets the verification depth in the server certificates chain.
|
||||
|
||||
This directive was first introduced in the <code>v0.9.11</code> release.
|
||||
|
||||
See also [[#lua_ssl_trusted_certificate|lua_ssl_trusted_certificate]].
|
||||
|
||||
== lua_http10_buffering ==
|
||||
|
||||
'''syntax:''' ''lua_http10_buffering on|off''
|
||||
|
|
@ -4740,6 +4806,7 @@ This feature was first introduced in the <code>v0.5.7</code> release.
|
|||
Creates and returns a TCP or stream-oriented unix domain socket object (also known as one type of the "cosocket" objects). The following methods are supported on this object:
|
||||
|
||||
* [[#tcpsock:connect|connect]]
|
||||
* [[#tcpsock:sslhandshake|sslhandshake]]
|
||||
* [[#tcpsock:send|send]]
|
||||
* [[#tcpsock:receive|receive]]
|
||||
* [[#tcpsock:close|close]]
|
||||
|
|
@ -4833,6 +4900,45 @@ The support for the options table argument was first introduced in the <code>v0.
|
|||
|
||||
This method was first introduced in the <code>v0.5.0rc1</code> release.
|
||||
|
||||
== tcpsock:sslhandshake ==
|
||||
'''syntax:''' ''session, err = tcpsock:sslhandshake(reused_session?, server_name?, ssl_verify?)''
|
||||
|
||||
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*''
|
||||
|
||||
Does SSL/TLS handshake on the currently established connection.
|
||||
|
||||
The optional <code>reused_session</code> argument can take a former SSL
|
||||
session userdata returned by a previous <code>sslhandshake</code>
|
||||
call for exactly the same target. For short-lived connections, reusing SSL
|
||||
sessions can usually speed up the handshake by one order by magnitude but it
|
||||
is not so useful if the connection pool is enabled. This argument defaults to
|
||||
`nil`. If this argument takes the boolean `false` value, no SSL session
|
||||
userdata would return by this call and only a Lua boolean will be returned as
|
||||
the first return value; otherwise the current SSL session will
|
||||
always be returned as the first argument in case of successes.
|
||||
|
||||
The optional <code>server_name</code> argument is used to specify the server
|
||||
name for the new TLS extension Server Name Indication (SNI). Use of SNI can
|
||||
make different servers share the same IP address on the server side. Also,
|
||||
when SSL verification is enabled, this <code>server_name</code> argument is
|
||||
also used to validate the server name specified in the server certificate sent from
|
||||
the remote.
|
||||
|
||||
The optional <code>ssl_verify</code> argument takes a Lua boolean value to
|
||||
control whether to perform SSL verification. When set to `true`, the server
|
||||
certificate will be verified according to the CA certificates specified by
|
||||
the [[#lua_ssl_trusted_certificate|lua_ssl_trusted_certificate]] directive.
|
||||
You may also need to adjust the [[#lua_ssl_verify_depth|lua_ssl_verify_depth]]
|
||||
directive to control how deep we should follow along the certificate chain.
|
||||
Also, when the <code>ssl_verify</code> argument is true and the
|
||||
<code>server_name</code> argument is also specified, the latter will be used
|
||||
to validate the server name in the server certificate.
|
||||
|
||||
For connections that have already done SSL/TLS handshake, this method returns
|
||||
immediately.
|
||||
|
||||
This method was first introduced in the <code>v0.9.11</code> release.
|
||||
|
||||
== tcpsock:send ==
|
||||
'''syntax:''' ''bytes, err = tcpsock:send(data)''
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче