willmafh · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026 · Oct 18, 2026 · Oct 18, 2026
diff --git a/README.markdown b/README.markdown
@@ -1177,11 +1177,14 @@ Directives
 * [ssl_session_fetch_by_lua_file](#ssl_session_fetch_by_lua_file)
 * [ssl_session_store_by_lua_block](#ssl_session_store_by_lua_block)
 * [ssl_session_store_by_lua_file](#ssl_session_store_by_lua_file)
+* [ssl_verify_by_lua_block](#ssl_verify_by_lua_block)
+* [ssl_verify_by_lua_file](#ssl_verify_by_lua_file)
 * [proxy_ssl_certificate_by_lua_block](#proxy_ssl_certificate_by_lua_block)
 * [proxy_ssl_certificate_by_lua_file](#proxy_ssl_certificate_by_lua_file)
 * [proxy_ssl_verify_by_lua_block](#proxy_ssl_verify_by_lua_block)
 * [proxy_ssl_verify_by_lua_file](#proxy_ssl_verify_by_lua_file)
 * [lua_shared_dict](#lua_shared_dict)
+* [lua_skip_openssl_default_verify](#lua_skip_openssl_default_verify)
 * [lua_socket_connect_timeout](#lua_socket_connect_timeout)
 * [lua_socket_send_timeout](#lua_socket_send_timeout)
 * [lua_socket_send_lowat](#lua_socket_send_lowat)
@@ -3241,6 +3244,86 @@ Note that: this directive is only allowed to used in **http context** from the `
 
 [Back to TOC](#directives)
 
+ssl_verify_by_lua_block
+-----------------------
+
+**syntax:** *ssl_verify_by_lua_block { lua-script }*
+
+**context:** *http, server*
+
+**phase:** *right-after-client-certificate-message-was-processed*
+
+This directive runs user Lua code when Nginx is about to post-process the SSL client certificate message for the downstream SSL (https) connections.
+
+It is particularly useful to parse downstream client certificate and do some custom operations in pure lua.
+
+When using `ssl_verify_by_lua` directive, the `ssl_verify_client` directive should not be off, that is, it should be `on`/`optional`/`optional_no_ca`, and you can still use the `$ssl_client_verify` variable to get the verification result.
+
+The [ngx.ssl.sslverify](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/ssl/sslverify.md) Lua module provided by the [lua-resty-core](https://github.com/openresty/lua-resty-core/#readme) library are particularly useful in this context.
+
+Below is a trivial example using the
+[ngx.ssl.sslverify](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/ssl/sslverify.md) module
+at the same time:
+
+```nginx
+
+ server {
+     listen 443 ssl;
+     server_name   test.com;
+     ssl_verify_client on;
+     ssl_certificate /path/to/cert.crt;
+     ssl_certificate_key /path/to/key.key;
+
+     ssl_verify_by_lua_block {
+         local ssl_vfy = require "ngx.ssl.sslverify"
+
+         local cert = ssl_vfy.get_verify_cert()
+
+         -- ocsp to verify cert
+         -- check crl
+
+         ssl_vfy.set_verify_result()
+         ...
+     }
+
+     location /t {
+         proxy_ssl_certificate /path/to/cert.crt;
+         proxy_ssl_certificate_key /path/to/key.key;
+         proxy_pass https://upstream;
+     }
+     ...
+ }
+```
+
+See more information in the [ngx.ssl.sslverify](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/ssl/sslverify.md)
+Lua module's official documentation.
+
+Uncaught Lua exceptions in the user Lua code immediately abort the current SSL session, so does the
+[ngx.exit](#ngxexit) call with an error code like `ngx.ERROR`.
+
+This Lua code execution context *does* support yielding, so Lua APIs that may yield
+(like cosockets, sleeping, and "light threads")
+are enabled in this context
+
+This directive requires OpenSSL 4.1.0 or greater.
+
+[Back to TOC](#directives)
+
+ssl_verify_by_lua_file
+----------------------
+
+**syntax:** *ssl_verify_by_lua_file &lt;path-to-lua-script-file&gt;*
+
+**context:** *http, server*
+
+**phase:** *right-after-client-certificate-message-was-processed*
+
+Equivalent to [ssl_verify_by_lua_block](#ssl_verify_by_lua_block), except that the file specified by `<path-to-lua-script-file>` contains the Lua code, or, as from the `v0.5.0rc32` release, the [LuaJIT bytecode](#luajit-bytecode-support) to be executed.
+
+When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
+
+[Back to TOC](#directives)
+
 proxy_ssl_certificate_by_lua_block
 ----------------------------------
 
@@ -3441,6 +3524,21 @@ This directive was first introduced in the `v0.3.1rc22` release.
 
 [Back to TOC](#directives)
 
+lua_skip_openssl_default_verify
+-------------------------------
+
+**syntax:** *lua_skip_openssl_default_verify on|off*
+
+**default:** *lua_skip_openssl_default_verify off*
+
+**context:** *http, server*
+
+When using `ssl_verify_by_lua` directive, `lua_skip_openssl_default_verify` controls whether to skip default openssl's verify function, that means using pure Lua code to verify downstream client certificate.
+
+This directive is turned `off` by default.
+
+[Back to TOC](#directives)
+
 lua_socket_connect_timeout
 --------------------------
 

diff --git a/config b/config
@@ -296,6 +296,7 @@ HTTP_LUA_SRCS=" \
             $ngx_addon_dir/src/ngx_http_lua_balancer.c \
             $ngx_addon_dir/src/ngx_http_lua_ssl_session_storeby.c \
             $ngx_addon_dir/src/ngx_http_lua_ssl_session_fetchby.c \
+            $ngx_addon_dir/src/ngx_http_lua_ssl_verifyby.c \
             $ngx_addon_dir/src/ngx_http_lua_ssl.c \
             $ngx_addon_dir/src/ngx_http_lua_proxy_ssl_certby.c \
             $ngx_addon_dir/src/ngx_http_lua_proxy_ssl_verifyby.c \
@@ -362,6 +363,7 @@ HTTP_LUA_DEPS=" \
             $ngx_addon_dir/src/ngx_http_lua_ssl_export_keying_material.h \
             $ngx_addon_dir/src/ngx_http_lua_ssl_session_storeby.h \
             $ngx_addon_dir/src/ngx_http_lua_ssl_session_fetchby.h \
+            $ngx_addon_dir/src/ngx_http_lua_ssl_verifyby.h \
             $ngx_addon_dir/src/ngx_http_lua_ssl.h \
             $ngx_addon_dir/src/ngx_http_lua_proxy_ssl_certby.h \
             $ngx_addon_dir/src/ngx_http_lua_proxy_ssl_verifyby.h \

diff --git a/src/ngx_http_lua_common.h b/src/ngx_http_lua_common.h
@@ -173,6 +173,7 @@ typedef struct {
 #define NGX_HTTP_LUA_CONTEXT_PROXY_SSL_VERIFY   0x00010000
 #define NGX_HTTP_LUA_CONTEXT_PRECONTENT         0x00020000
 #define NGX_HTTP_LUA_CONTEXT_PROXY_SSL_CERT     0x00040000
+#define NGX_HTTP_LUA_CONTEXT_SSL_VERIFY         0x00080000
 
 #define NGX_HTTP_LUA_FFI_NO_REQ_CTX         -100
 #define NGX_HTTP_LUA_FFI_BAD_CONTEXT        -101
@@ -373,6 +374,13 @@ struct ngx_http_lua_srv_conf_s {
         u_char                              *ssl_client_hello_src_key;
         u_char                              *ssl_client_hello_chunkname;
         int                                  ssl_client_hello_src_ref;
+
+        ngx_http_lua_srv_conf_handler_pt     ssl_verify_handler;
+        ngx_str_t                            ssl_verify_src;
+        u_char                              *ssl_verify_src_key;
+        u_char                              *ssl_verify_chunkname;
+        int                                  ssl_verify_src_ref;
+        ngx_flag_t                           skip_openssl_default_verify;
 #endif
 
         ngx_http_lua_srv_conf_handler_pt     server_rewrite_handler;

diff --git a/src/ngx_http_lua_control.c b/src/ngx_http_lua_control.c
@@ -394,7 +394,8 @@ ngx_http_lua_ffi_exit(ngx_http_request_t *r, int status, u_char *err,
                                        | NGX_HTTP_LUA_CONTEXT_SSL_CLIENT_HELLO
                                        | NGX_HTTP_LUA_CONTEXT_SSL_CERT
                                        | NGX_HTTP_LUA_CONTEXT_SSL_SESS_STORE
-                                       | NGX_HTTP_LUA_CONTEXT_SSL_SESS_FETCH,
+                                       | NGX_HTTP_LUA_CONTEXT_SSL_SESS_FETCH
+                                       | NGX_HTTP_LUA_CONTEXT_SSL_VERIFY,
                                        err, errlen)
         != NGX_OK)
     {
@@ -408,7 +409,8 @@ ngx_http_lua_ffi_exit(ngx_http_request_t *r, int status, u_char *err,
 #endif
                         | NGX_HTTP_LUA_CONTEXT_SSL_CLIENT_HELLO
                         | NGX_HTTP_LUA_CONTEXT_SSL_SESS_STORE
-                        | NGX_HTTP_LUA_CONTEXT_SSL_SESS_FETCH))
+                        | NGX_HTTP_LUA_CONTEXT_SSL_SESS_FETCH
+                        | NGX_HTTP_LUA_CONTEXT_SSL_VERIFY))
     {
 
 #if (NGX_HTTP_SSL)

diff --git a/src/ngx_http_lua_ctx.c b/src/ngx_http_lua_ctx.c
@@ -95,7 +95,8 @@ ngx_http_lua_ffi_get_ctx_ref(ngx_http_request_t *r, int *in_ssl_phase,
     *in_ssl_phase = ctx->context & (NGX_HTTP_LUA_CONTEXT_SSL_CERT
                                     | NGX_HTTP_LUA_CONTEXT_SSL_CLIENT_HELLO
                                     | NGX_HTTP_LUA_CONTEXT_SSL_SESS_FETCH
-                                    | NGX_HTTP_LUA_CONTEXT_SSL_SESS_STORE);
+                                    | NGX_HTTP_LUA_CONTEXT_SSL_SESS_STORE
+                                    | NGX_HTTP_LUA_CONTEXT_SSL_VERIFY);
     *ssl_ctx_ref = LUA_NOREF;
 
 #if (NGX_HTTP_SSL)
@@ -133,7 +134,8 @@ ngx_http_lua_ffi_set_ctx_ref(ngx_http_request_t *r, int ref)
     if (ctx->context & (NGX_HTTP_LUA_CONTEXT_SSL_CERT
                         | NGX_HTTP_LUA_CONTEXT_SSL_CLIENT_HELLO
                         | NGX_HTTP_LUA_CONTEXT_SSL_SESS_FETCH
-                        | NGX_HTTP_LUA_CONTEXT_SSL_SESS_STORE))
+                        | NGX_HTTP_LUA_CONTEXT_SSL_SESS_STORE
+                        | NGX_HTTP_LUA_CONTEXT_SSL_VERIFY))
     {
         ssl_ctx = ngx_http_lua_ssl_get_ctx(r->connection->ssl->connection);
         if (ssl_ctx == NULL) {

diff --git a/src/ngx_http_lua_module.c b/src/ngx_http_lua_module.c
@@ -32,6 +32,7 @@
 #include "ngx_http_lua_ssl_certby.h"
 #include "ngx_http_lua_ssl_session_storeby.h"
 #include "ngx_http_lua_ssl_session_fetchby.h"
+#include "ngx_http_lua_ssl_verifyby.h"
 
 #include "ngx_http_lua_proxy_ssl_certby.h"
 #include "ngx_http_lua_proxy_ssl_verifyby.h"
@@ -696,6 +697,27 @@ static ngx_command_t ngx_http_lua_cmds[] = {
       0,
       (void *) ngx_http_lua_ssl_sess_fetch_handler_file },
 
+    { ngx_string("ssl_verify_by_lua_block"),
+      NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_CONF_BLOCK|NGX_CONF_NOARGS,
+      ngx_http_lua_ssl_verify_by_lua_block,
+      NGX_HTTP_SRV_CONF_OFFSET,
+      0,
+      (void *) ngx_http_lua_ssl_verify_handler_inline },
+
+    { ngx_string("ssl_verify_by_lua_file"),
+      NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_CONF_TAKE1,
+      ngx_http_lua_ssl_verify_by_lua,
+      NGX_HTTP_SRV_CONF_OFFSET,
+      0,
+      (void *) ngx_http_lua_ssl_verify_handler_file },
+
+    { ngx_string("lua_skip_openssl_default_verify"),
+      NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_CONF_FLAG,
+      ngx_conf_set_flag_slot,
+      NGX_HTTP_SRV_CONF_OFFSET,
+      offsetof(ngx_http_lua_srv_conf_t, srv.skip_openssl_default_verify),
+      NULL },
+
 #if HAVE_LUA_PROXY_SSL
     /* same context as proxy_pass directive */
     { ngx_string("proxy_ssl_certificate_by_lua_block"),
@@ -1305,6 +1327,11 @@ ngx_http_lua_create_srv_conf(ngx_conf_t *cf)
      *      lscf->srv.ssl_sess_fetch_chunkname = NULL;
      *      lscf->srv.ssl_sess_fetch_src_key = NULL;
      *
+     *      lscf->srv.ssl_verify_handler = NULL;
+     *      lscf->srv.ssl_verify_src = { 0, NULL };
+     *      lscf->srv.ssl_verify_chunkname = NULL;
+     *      lscf->srv.ssl_verify_src_key = NULL;
+     *
      *      lscf->srv.server_rewrite_handler = NULL;
      *      lscf->srv.server_rewrite_src = { 0, NULL };
      *      lscf->srv.server_rewrite_chunkname = NULL;
@@ -1323,6 +1350,8 @@ ngx_http_lua_create_srv_conf(ngx_conf_t *cf)
     lscf->srv.ssl_cert_src_ref = LUA_REFNIL;
     lscf->srv.ssl_sess_store_src_ref = LUA_REFNIL;
     lscf->srv.ssl_sess_fetch_src_ref = LUA_REFNIL;
+    lscf->srv.ssl_verify_src_ref = LUA_REFNIL;
+    lscf->srv.skip_openssl_default_verify = NGX_CONF_UNSET;
 #endif
 
     lscf->srv.server_rewrite_src_ref = LUA_REFNIL;
@@ -1473,6 +1502,58 @@ ngx_http_lua_merge_srv_conf(ngx_conf_t *cf, void *parent, void *child)
         }
     }
 
+    if (conf->srv.ssl_verify_src.len == 0) {
+        conf->srv.ssl_verify_src = prev->srv.ssl_verify_src;
+        conf->srv.ssl_verify_src_ref = prev->srv.ssl_verify_src_ref;
+        conf->srv.ssl_verify_src_key = prev->srv.ssl_verify_src_key;
+        conf->srv.ssl_verify_handler = prev->srv.ssl_verify_handler;
+        conf->srv.ssl_verify_chunkname
+            = prev->srv.ssl_verify_chunkname;
+    }
+
+    if (conf->srv.ssl_verify_src.len) {
+        sscf = ngx_http_conf_get_module_srv_conf(cf, ngx_http_ssl_module);
+        if (sscf == NULL || sscf->ssl.ctx == NULL) {
+            ngx_log_error(NGX_LOG_EMERG, cf->log, 0,
+                          "no ssl configured for the server");
+
+            return NGX_CONF_ERROR;
+        }
+
+        if (sscf->verify == 0) {
+            ngx_log_error(NGX_LOG_EMERG, cf->log, 0,
+                    "ssl_verify_client can't be off "
+                    "when using ssl_verify_by_lua*");
+
+            return NGX_CONF_ERROR;
+        }
+#ifdef LIBRESSL_VERSION_NUMBER
+        ngx_log_error(NGX_LOG_EMERG, cf->log, 0,
+                      "LibreSSL does not support by ssl_verify_by_lua*");
+        return NGX_CONF_ERROR;
+
+#else
+
+#if defined(SSL_ERROR_WANT_RETRY_VERIFY) &&                                  \
+        OPENSSL_VERSION_NUMBER >= 0x40100000L
+
+        SSL_CTX_set_cert_verify_callback(sscf->ssl.ctx,
+                                         ngx_http_lua_ssl_verify_handler,
+                                         NULL);
+
+#else
+
+        ngx_log_error(NGX_LOG_EMERG, cf->log, 0,
+                      "OpenSSL too old to support ssl_verify_by_lua*");
+        return NGX_CONF_ERROR;
+
+#endif
+#endif
+    }
+
+    ngx_conf_merge_value(conf->srv.skip_openssl_default_verify,
+                         prev->srv.skip_openssl_default_verify, 0);
+
 #endif  /* NGX_HTTP_SSL */
 
     if (conf->srv.server_rewrite_src.value.len == 0) {

diff --git a/src/ngx_http_lua_ssl.h b/src/ngx_http_lua_ssl.h
@@ -24,8 +24,8 @@ typedef struct {
 
     ngx_str_t                session_id;
 
-#if HAVE_LUA_PROXY_SSL
     X509_STORE_CTX          *x509_store;
+#if HAVE_LUA_PROXY_SSL
     ngx_pool_t              *pool;
 #endif
 
@@ -48,6 +48,7 @@ typedef struct {
     unsigned                 entered_client_hello_handler:1;
     unsigned                 entered_cert_handler:1;
     unsigned                 entered_sess_fetch_handler:1;
+    unsigned                 entered_ssl_verify_handler:1;
 #if HAVE_LUA_PROXY_SSL
     unsigned                 entered_proxy_ssl_cert_handler:1;
     unsigned                 entered_proxy_ssl_verify_handler:1;