doc: documented ssl_psk_by_lua_block, ssl_psk_by_lua_file, ssl_psk_identity_hint, lua_ssl_psk_identity and lua_ssl_psk_key directives.

Author: Tuure Vartiainen

doc/HttpLuaModule.wiki

@@ -2159,6 +2159,98 @@ When a relative path like <code>foo/bar.lua</code> is given, they will be turned
 
 This directive was first introduced in the <code>v0.10.0</code> release.
 
+== ssl_psk_by_lua_block ==
+
+'''syntax:''' ''ssl_psk_by_lua_block { lua-script }''
+
+'''context:''' ''server''
+
+'''phase:''' ''right-before-SSL-handshake''
+
+This directive runs user Lua code when NGINX is about to start the SSL handshake for the downstream
+SSL (https) connections using TLS-PSK and is meant for setting the TLS pre-shared key on a per-request basis.
+
+The [https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/ssl.md ngx.ssl]
+ Lua module provided by the [https://github.com/openresty/lua-resty-core/#readme lua-resty-core]
+library is particularly useful in this context. You can use the Lua API offered by this Lua module
+to set the TLS pre-shared key for the current SSL connection being initiated.
+
+This Lua handler does not run at all, however, when NGINX/OpenSSL successfully resumes
+the SSL session via SSL session IDs or TLS session tickets for the current SSL connection. In
+other words, this Lua handler only runs when NGINX has to initiate a full SSL handshake.
+
+Below is a trivial example using the
+[https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/ssl.md ngx.ssl] module
+at the same time:
+
+<geshi lang="nginx">
+    server {
+        listen 443 ssl;
+        server_name   test.com;
+
+        ssl_psk_identity_hint Test_TLS-PSK_Identity_Hint;
+
+        ssl_psk_by_lua_block {
+            print("About to initiate a new TLS-PSK handshake!")
+        }
+
+        location / {
+            root html;
+        }
+    }
+</geshi>
+
+See more complicated examples in the [https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/ssl.md ngx.ssl]
+Lua module's official documentation.
+
+Uncaught Lua exceptions in the user Lua code immediately abort the current SSL session, so does the
+[[#ngx.exit|ngx.exit]] call with an error code like <code>ngx.ERROR</code>.
+
+This Lua code execution context *does not* support yielding, so Lua APIs that may yield
+(like cosockets, sleeping, and "light threads")
+are disabled in this context.
+
+Note, however, you still need to configure the [http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate ssl_certificate] and
+[http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key ssl_certificate_key]
+directives even though you will not use this static certificate and private key at all. This is
+because the NGINX core requires their appearance otherwise you are seeing the following error
+while starting NGINX:
+
+<geshi>
+    nginx: [emerg] no ssl configured for the server
+</geshi>
+
+Furthermore, one needs at least OpenSSL 1.0.0 for this directive to work.
+
+This directive was first introduced in the <code>v0.XX.YY</code> release.
+
+== ssl_psk_by_lua_file ==
+
+'''syntax:''' ''ssl_psk_by_lua_file <path-to-lua-script-file>''
+
+'''context:''' ''server''
+
+'''phase:''' ''right-before-SSL-handshake''
+
+Equivalent to [[#ssl_psk_by_lua_block|ssl_psk_by_lua_block]], except that the file specified by <code><path-to-lua-script-file></code> contains the Lua code, or, as from the <code>v0.5.0rc32</code> release, the [[#Lua/LuaJIT bytecode support|Lua/LuaJIT bytecode]] to be executed.
+
+When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
+
+This directive was first introduced in the <code>v0.XX.YY</code> release.
+
+== ssl_psk_identity_hint ==
+
+'''syntax:''' ''ssl_psk_identity_hint <tls_psk_identity_hint>''
+
+'''default:''' ''no''
+
+'''context:''' ''http, server''
+
+Specifies the TLS-PSK identity hint string which NGINX will send to a client during
+the SSL handshake for the downstream SSL (https) connections.
+
+This directive was first introduced in the <code>v0.XX.YY</code> release.
+
 == ssl_session_fetch_by_lua_block ==
 
 '''syntax:''' ''ssl_session_fetch_by_lua_block { lua-script }''
@@ -2498,6 +2590,30 @@ This directive was first introduced in the <code>v0.9.11</code> release.
 
 See also [[#lua_ssl_trusted_certificate|lua_ssl_trusted_certificate]].
 
+== lua_ssl_psk_identity ==
+
+'''syntax:''' ''lua_ssl_psk_identity <tls_psk_identity>''
+
+'''default:''' ''no''
+
+'''context:''' ''http, server, location''
+
+Specifies the TLS-PSK identity string which NGINX will send to a SSL/TLS server in the [[#tcpsock:sslhandshake|tcpsock:sslhandshake]] method.
+
+This directive was first introduced in the <code>v0.XX.YY</code> release.
+
+== lua_ssl_psk_key ==
+
+'''syntax:''' ''lua_ssl_psk_key <tls_psk_key>''
+
+'''default:''' ''no''
+
+'''context:''' ''http, server, location''
+
+Specifies the TLS-PSK key string which NGINX will try use with a SSL/TLS server in the [[#tcpsock:sslhandshake|tcpsock:sslhandshake]] method.
+
+This directive was first introduced in the <code>v0.XX.YY</code> release.
+
 == lua_http10_buffering ==
 
 '''syntax:''' ''lua_http10_buffering on|off''