Skip to content

Commit 2b40b44

Browse files
agentzhagentzh
committed
doc: documented the new SSL cosocket feature.
1 parent fd3f4ee commit 2b40b44

File tree

2 files changed

+236
-0
lines changed

2 files changed

+236
-0
lines changed

‎README.markdown

+130
Original file line numberDiff line numberDiff line change
@@ -1005,6 +1005,11 @@ Directives
10051005
* [lua_socket_pool_size](#lua_socket_pool_size)
10061006
* [lua_socket_keepalive_timeout](#lua_socket_keepalive_timeout)
10071007
* [lua_socket_log_errors](#lua_socket_log_errors)
1008+
* [lua_ssl_ciphers](#lua_ssl_ciphers)
1009+
* [lua_ssl_crl](#lua_ssl_crl)
1010+
* [lua_ssl_protocols](#lua_ssl_protocols)
1011+
* [lua_ssl_trusted_certificate](#lua_ssl_trusted_certificate)
1012+
* [lua_ssl_verify_depth](#lua_ssl_verify_depth)
10081013
* [lua_http10_buffering](#lua_http10_buffering)
10091014
* [rewrite_by_lua_no_postpone](#rewrite_by_lua_no_postpone)
10101015
* [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.
20802085

20812086
[Back to TOC](#directives)
20822087

2088+
lua_ssl_ciphers
2089+
---------------
2090+
2091+
**syntax:** *lua_ssl_ciphers <ciphers>*
2092+
2093+
**default:** *lua_ssl_ciphers DEFAULT*
2094+
2095+
**context:** *http, server, location*
2096+
2097+
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.
2098+
2099+
The full list can be viewed using the “openssl ciphers” command.
2100+
2101+
This directive was first introduced in the `v0.9.11` release.
2102+
2103+
[Back to TOC](#directives)
2104+
2105+
lua_ssl_crl
2106+
-----------
2107+
2108+
**syntax:** *lua_ssl_crl <file>*
2109+
2110+
**default:** *no*
2111+
2112+
**context:** *http, server, location*
2113+
2114+
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.
2115+
2116+
This directive was first introduced in the `v0.9.11` release.
2117+
2118+
[Back to TOC](#directives)
2119+
2120+
lua_ssl_protocols
2121+
-----------------
2122+
2123+
**syntax:** *lua_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]*
2124+
2125+
**default:** *lua_ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2*
2126+
2127+
**context:** *http, server, location*
2128+
2129+
Enables the specified protocols for requests to a SSL/TLS server in the [tcpsock:sslhandshake](#tcpsocksslhandshake) method.
2130+
2131+
This directive was first introduced in the `v0.9.11` release.
2132+
2133+
[Back to TOC](#directives)
2134+
2135+
lua_ssl_trusted_certificate
2136+
---------------------------
2137+
2138+
**syntax:** *lua_ssl_trusted_certificate <file>*
2139+
2140+
**default:** *no*
2141+
2142+
**context:** *http, server, location*
2143+
2144+
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.
2145+
2146+
This directive was first introduced in the `v0.9.11` release.
2147+
2148+
See also [lua_ssl_verify_depth](#lua_ssl_verify_depth).
2149+
2150+
[Back to TOC](#directives)
2151+
2152+
lua_ssl_verify_depth
2153+
--------------------
2154+
2155+
**syntax:** *lua_ssl_verify_depth <number>*
2156+
2157+
**default:** *lua_ssl_verify_depth 1*
2158+
2159+
**context:** *http, server, location*
2160+
2161+
Sets the verification depth in the server certificates chain.
2162+
2163+
This directive was first introduced in the `v0.9.11` release.
2164+
2165+
See also [lua_ssl_trusted_certificate](#lua_ssl_trusted_certificate).
2166+
2167+
[Back to TOC](#directives)
2168+
20832169
lua_http10_buffering
20842170
--------------------
20852171

@@ -2303,6 +2389,7 @@ Nginx API for Lua
23032389
* [udpsock:settimeout](#udpsocksettimeout)
23042390
* [ngx.socket.tcp](#ngxsockettcp)
23052391
* [tcpsock:connect](#tcpsockconnect)
2392+
* [tcpsock:sslhandshake](#tcpsocksslhandshake)
23062393
* [tcpsock:send](#tcpsocksend)
23072394
* [tcpsock:receive](#tcpsockreceive)
23082395
* [tcpsock:receiveuntil](#tcpsockreceiveuntil)
@@ -5660,6 +5747,7 @@ ngx.socket.tcp
56605747
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:
56615748

56625749
* [connect](#tcpsockconnect)
5750+
* [sslhandshake](#tcpsocksslhandshake)
56635751
* [send](#tcpsocksend)
56645752
* [receive](#tcpsockreceive)
56655753
* [close](#tcpsockclose)
@@ -5762,6 +5850,48 @@ This method was first introduced in the `v0.5.0rc1` release.
57625850

57635851
[Back to TOC](#nginx-api-for-lua)
57645852

5853+
tcpsock:sslhandshake
5854+
--------------------
5855+
**syntax:** *session, err = tcpsock:sslhandshake(reused_session?, server_name?, ssl_verify?)*
5856+
5857+
**context:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.**
5858+
5859+
Does SSL/TLS handshake on the currently established connection.
5860+
5861+
The optional `reused_session` argument can take a former SSL
5862+
session userdata returned by a previous `sslhandshake`
5863+
call for exactly the same target. For short-lived connections, reusing SSL
5864+
sessions can usually speed up the handshake by one order by magnitude but it
5865+
is not so useful if the connection pool is enabled. This argument defaults to
5866+
`nil`. If this argument takes the boolean `false` value, no SSL session
5867+
userdata would return by this call and only a Lua boolean will be returned as
5868+
the first return value; otherwise the current SSL session will
5869+
always be returned as the first argument in case of successes.
5870+
5871+
The optional `server_name` argument is used to specify the server
5872+
name for the new TLS extension Server Name Indication (SNI). Use of SNI can
5873+
make different servers share the same IP address on the server side. Also,
5874+
when SSL verification is enabled, this `server_name` argument is
5875+
also used to validate the server name specified in the server certificate sent from
5876+
the remote.
5877+
5878+
The optional `ssl_verify` argument takes a Lua boolean value to
5879+
control whether to perform SSL verification. When set to `true`, the server
5880+
certificate will be verified according to the CA certificates specified by
5881+
the [lua_ssl_trusted_certificate](#lua_ssl_trusted_certificate) directive.
5882+
You may also need to adjust the [lua_ssl_verify_depth](#lua_ssl_verify_depth)
5883+
directive to control how deep we should follow along the certificate chain.
5884+
Also, when the `ssl_verify` argument is true and the
5885+
`server_name` argument is also specified, the latter will be used
5886+
to validate the server name in the server certificate.
5887+
5888+
For connections that have already done SSL/TLS handshake, this method returns
5889+
immediately.
5890+
5891+
This method was first introduced in the `v0.9.11` release.
5892+
5893+
[Back to TOC](#nginx-api-for-lua)
5894+
57655895
tcpsock:send
57665896
------------
57675897
**syntax:** *bytes, err = tcpsock:send(data)*

‎doc/HttpLuaModule.wiki

+106
Original file line numberDiff line numberDiff line change
@@ -1742,6 +1742,72 @@ This directive can be used to toggle error logging when a failure occurs for the
17421742
17431743
This directive was first introduced in the <code>v0.5.13</code> release.
17441744
1745+
== lua_ssl_ciphers ==
1746+
1747+
'''syntax:''' ''lua_ssl_ciphers <ciphers>''
1748+
1749+
'''default:''' ''lua_ssl_ciphers DEFAULT''
1750+
1751+
'''context:''' ''http, server, location''
1752+
1753+
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.
1754+
1755+
The full list can be viewed using the “openssl ciphers” command.
1756+
1757+
This directive was first introduced in the <code>v0.9.11</code> release.
1758+
1759+
== lua_ssl_crl ==
1760+
1761+
'''syntax:''' ''lua_ssl_crl <file>''
1762+
1763+
'''default:''' ''no''
1764+
1765+
'''context:''' ''http, server, location''
1766+
1767+
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.
1768+
1769+
This directive was first introduced in the <code>v0.9.11</code> release.
1770+
1771+
== lua_ssl_protocols ==
1772+
1773+
'''syntax:''' ''lua_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]''
1774+
1775+
'''default:''' ''lua_ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2''
1776+
1777+
'''context:''' ''http, server, location''
1778+
1779+
Enables the specified protocols for requests to a SSL/TLS server in the [[#tcpsock:sslhandshake|tcpsock:sslhandshake]] method.
1780+
1781+
This directive was first introduced in the <code>v0.9.11</code> release.
1782+
1783+
== lua_ssl_trusted_certificate ==
1784+
1785+
'''syntax:''' ''lua_ssl_trusted_certificate <file>''
1786+
1787+
'''default:''' ''no''
1788+
1789+
'''context:''' ''http, server, location''
1790+
1791+
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.
1792+
1793+
This directive was first introduced in the <code>v0.9.11</code> release.
1794+
1795+
See also [[#lua_ssl_verify_depth|lua_ssl_verify_depth]].
1796+
1797+
== lua_ssl_verify_depth ==
1798+
1799+
'''syntax:''' ''lua_ssl_verify_depth <number>''
1800+
1801+
'''default:''' ''lua_ssl_verify_depth 1''
1802+
1803+
'''context:''' ''http, server, location''
1804+
1805+
Sets the verification depth in the server certificates chain.
1806+
1807+
This directive was first introduced in the <code>v0.9.11</code> release.
1808+
1809+
See also [[#lua_ssl_trusted_certificate|lua_ssl_trusted_certificate]].
1810+
17451811
== lua_http10_buffering ==
17461812
17471813
'''syntax:''' ''lua_http10_buffering on|off''
@@ -4740,6 +4806,7 @@ This feature was first introduced in the <code>v0.5.7</code> release.
47404806
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:
47414807
47424808
* [[#tcpsock:connect|connect]]
4809+
* [[#tcpsock:sslhandshake|sslhandshake]]
47434810
* [[#tcpsock:send|send]]
47444811
* [[#tcpsock:receive|receive]]
47454812
* [[#tcpsock:close|close]]
@@ -4833,6 +4900,45 @@ The support for the options table argument was first introduced in the <code>v0.
48334900
48344901
This method was first introduced in the <code>v0.5.0rc1</code> release.
48354902
4903+
== tcpsock:sslhandshake ==
4904+
'''syntax:''' ''session, err = tcpsock:sslhandshake(reused_session?, server_name?, ssl_verify?)''
4905+
4906+
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*''
4907+
4908+
Does SSL/TLS handshake on the currently established connection.
4909+
4910+
The optional <code>reused_session</code> argument can take a former SSL
4911+
session userdata returned by a previous <code>sslhandshake</code>
4912+
call for exactly the same target. For short-lived connections, reusing SSL
4913+
sessions can usually speed up the handshake by one order by magnitude but it
4914+
is not so useful if the connection pool is enabled. This argument defaults to
4915+
`nil`. If this argument takes the boolean `false` value, no SSL session
4916+
userdata would return by this call and only a Lua boolean will be returned as
4917+
the first return value; otherwise the current SSL session will
4918+
always be returned as the first argument in case of successes.
4919+
4920+
The optional <code>server_name</code> argument is used to specify the server
4921+
name for the new TLS extension Server Name Indication (SNI). Use of SNI can
4922+
make different servers share the same IP address on the server side. Also,
4923+
when SSL verification is enabled, this <code>server_name</code> argument is
4924+
also used to validate the server name specified in the server certificate sent from
4925+
the remote.
4926+
4927+
The optional <code>ssl_verify</code> argument takes a Lua boolean value to
4928+
control whether to perform SSL verification. When set to `true`, the server
4929+
certificate will be verified according to the CA certificates specified by
4930+
the [[#lua_ssl_trusted_certificate|lua_ssl_trusted_certificate]] directive.
4931+
You may also need to adjust the [[#lua_ssl_verify_depth|lua_ssl_verify_depth]]
4932+
directive to control how deep we should follow along the certificate chain.
4933+
Also, when the <code>ssl_verify</code> argument is true and the
4934+
<code>server_name</code> argument is also specified, the latter will be used
4935+
to validate the server name in the server certificate.
4936+
4937+
For connections that have already done SSL/TLS handshake, this method returns
4938+
immediately.
4939+
4940+
This method was first introduced in the <code>v0.9.11</code> release.
4941+
48364942
== tcpsock:send ==
48374943
'''syntax:''' ''bytes, err = tcpsock:send(data)''
48384944

0 commit comments

Comments
 (0)