feature: implemented the new ssl.verify_client() API to require a client certificate during TLS handshake (#289)

Author: ArchangelSDY

lib/ngx/ssl.lua

@@ -35,6 +35,7 @@ local ngx_lua_ffi_set_cert
 local ngx_lua_ffi_set_priv_key
 local ngx_lua_ffi_free_cert
 local ngx_lua_ffi_free_priv_key
+local ngx_lua_ffi_ssl_verify_client
 
 
 if subsystem == 'http' then
@@ -78,6 +79,9 @@ if subsystem == 'http' then
     void ngx_http_lua_ffi_free_cert(void *cdata);
 
     void ngx_http_lua_ffi_free_priv_key(void *cdata);
+
+    int ngx_http_lua_ffi_ssl_verify_client(void *r,
+        void *cdata, int depth, char **err);
     ]]
 
     ngx_lua_ffi_ssl_set_der_certificate =
@@ -97,6 +101,7 @@ if subsystem == 'http' then
     ngx_lua_ffi_set_priv_key = C.ngx_http_lua_ffi_set_priv_key
     ngx_lua_ffi_free_cert = C.ngx_http_lua_ffi_free_cert
     ngx_lua_ffi_free_priv_key = C.ngx_http_lua_ffi_free_priv_key
+    ngx_lua_ffi_ssl_verify_client = C.ngx_http_lua_ffi_ssl_verify_client
 
 elseif subsystem == 'stream' then
     ffi.cdef[[
@@ -140,6 +145,9 @@ elseif subsystem == 'stream' then
     void ngx_stream_lua_ffi_free_cert(void *cdata);
 
     void ngx_stream_lua_ffi_free_priv_key(void *cdata);
+
+    int ngx_stream_lua_ffi_ssl_verify_client(void *r,
+        void *cdata, int depth, char **err);
     ]]
 
     ngx_lua_ffi_ssl_set_der_certificate =
@@ -159,6 +167,7 @@ elseif subsystem == 'stream' then
     ngx_lua_ffi_set_priv_key = C.ngx_stream_lua_ffi_set_priv_key
     ngx_lua_ffi_free_cert = C.ngx_stream_lua_ffi_free_cert
     ngx_lua_ffi_free_priv_key = C.ngx_stream_lua_ffi_free_priv_key
+    ngx_lua_ffi_ssl_verify_client = C.ngx_stream_lua_ffi_ssl_verify_client
 end
 
 
@@ -380,6 +389,25 @@ function _M.set_priv_key(priv_key)
 end
 
 
+function _M.verify_client(ca_certs, depth)
+    local r = get_request()
+    if not r then
+        error("no request found")
+    end
+
+    if not depth then
+        depth = -1
+    end
+
+    local rc = ngx_lua_ffi_ssl_verify_client(r, ca_certs, depth, errmsg)
+    if rc == FFI_OK then
+        return true
+    end
+
+    return nil, ffi_str(errmsg[0])
+end
+
+
 do
     _M.SSL3_VERSION = 0x0300
     _M.TLS1_VERSION = 0x0301

lib/ngx/ssl.md

@@ -475,6 +475,31 @@ This function was first added in version `0.1.7`.
 
 [Back to TOC](#table-of-contents)
 
+verify_client
+------------
+**syntax:** *ok, err = ssl.verify_client(ca_certs?, depth?)*
+
+**context:** *ssl_certificate_by_lua**
+
+Requires a client certificate during TLS handshake.
+
+The `ca_certs` is the CA certificate chain opaque pointer returned by the
+[parse_pem_cert](#parse_pem_cert) function for the current SSL connection.
+The list of certificates will be sent to clients. Also, they will be added to trusted store.
+If omitted, will not send any CA certificate to clients.
+
+The `depth` is the verification depth in the client certificates chain.
+If omitted, will use the value specified by `ssl_verify_depth`.
+
+Returns `true` on success, or a `nil` value and a string describing the error otherwise.
+
+Note that TLS is not terminated when verification fails. You need to examine Nginx variable `$ssl_client_verify`
+later to determine next steps.
+
+This function was first added in version `0.1.20`.
+
+[Back to TOC](#table-of-contents)
+
 Community
 =========
 

t/ssl.t

@@ -2330,3 +2330,177 @@ got TLS1 version: TLSv1.3,
 [error]
 [alert]
 [emerg]
+
+
+
+=== TEST 23: verify client with CA certificates
+--- http_config
+    lua_package_path "$TEST_NGINX_LUA_PACKAGE_PATH";
+
+    server {
+        listen unix:$TEST_NGINX_HTML_DIR/nginx.sock ssl;
+        server_name   test.com;
+        ssl_certificate_by_lua_block {
+            local ssl = require "ngx.ssl"
+
+            local f = assert(io.open("t/cert/test.crt"))
+            local cert_data = f:read("*a")
+            f:close()
+
+            local cert, err = ssl.parse_pem_cert(cert_data)
+            if not cert then
+                ngx.log(ngx.ERR, "failed to parse pem cert: ", err)
+                return
+            end
+
+            local ok, err = ssl.verify_client(cert, 1)
+            if not ok then
+                ngx.log(ngx.ERR, "failed to verify client: ", err)
+                return
+            end
+        }
+
+        ssl_certificate ../../cert/test2.crt;
+        ssl_certificate_key ../../cert/test2.key;
+
+        location / {
+            default_type 'text/plain';
+            content_by_lua_block {
+                print('client certificate subject: ', ngx.var.ssl_client_s_dn)
+                ngx.say(ngx.var.ssl_client_verify)
+            }
+            more_clear_headers Date;
+        }
+    }
+--- config
+    location /t {
+        proxy_pass                  https://unix:$TEST_NGINX_HTML_DIR/nginx.sock;
+        proxy_ssl_certificate       ../../cert/test.crt;
+        proxy_ssl_certificate_key   ../../cert/test.key;
+        proxy_ssl_session_reuse     off;
+    }
+
+--- request
+GET /t
+--- response_body
+SUCCESS
+
+--- error_log
+client certificate subject: [email protected],CN=test.com
+
+--- no_error_log
+[error]
+[alert]
+[emerg]
+
+
+
+=== TEST 24: verify client without CA certificates
+--- http_config
+    lua_package_path "$TEST_NGINX_LUA_PACKAGE_PATH";
+
+    server {
+        listen unix:$TEST_NGINX_HTML_DIR/nginx.sock ssl;
+        server_name   test.com;
+        ssl_certificate_by_lua_block {
+            local ssl = require "ngx.ssl"
+
+            local ok, err = ssl.verify_client()
+            if not ok then
+                ngx.log(ngx.ERR, "failed to verify client: ", err)
+                return
+            end
+        }
+
+        ssl_certificate ../../cert/test2.crt;
+        ssl_certificate_key ../../cert/test2.key;
+
+        location / {
+            default_type 'text/plain';
+            content_by_lua_block {
+                print('client certificate subject: ', ngx.var.ssl_client_s_dn)
+                ngx.say(ngx.var.ssl_client_verify)
+            }
+            more_clear_headers Date;
+        }
+    }
+--- config
+    location /t {
+        proxy_pass                  https://unix:$TEST_NGINX_HTML_DIR/nginx.sock;
+        proxy_ssl_certificate       ../../cert/test.crt;
+        proxy_ssl_certificate_key   ../../cert/test.key;
+        proxy_ssl_session_reuse     off;
+    }
+
+--- request
+GET /t
+--- response_body
+FAILED:self signed certificate
+
+--- error_log
+client certificate subject: [email protected],CN=test.com
+
+--- no_error_log
+[error]
+[alert]
+[emerg]
+
+
+
+=== TEST 25: verify client but client provides no certificate
+--- http_config
+    lua_package_path "$TEST_NGINX_LUA_PACKAGE_PATH";
+
+    server {
+        listen unix:$TEST_NGINX_HTML_DIR/nginx.sock ssl;
+        server_name   test.com;
+        ssl_certificate_by_lua_block {
+            local ssl = require "ngx.ssl"
+
+            local f = assert(io.open("t/cert/test.crt"))
+            local cert_data = f:read("*a")
+            f:close()
+
+            local cert, err = ssl.parse_pem_cert(cert_data)
+            if not cert then
+                ngx.log(ngx.ERR, "failed to parse pem cert: ", err)
+                return
+            end
+
+            local ok, err = ssl.verify_client(cert, 1)
+            if not ok then
+                ngx.log(ngx.ERR, "failed to verify client: ", err)
+                return
+            end
+        }
+
+        ssl_certificate ../../cert/test2.crt;
+        ssl_certificate_key ../../cert/test2.key;
+
+        location / {
+            default_type 'text/plain';
+            content_by_lua_block {
+                print('client certificate subject: ', ngx.var.ssl_client_s_dn)
+                ngx.say(ngx.var.ssl_client_verify)
+            }
+            more_clear_headers Date;
+        }
+    }
+--- config
+    location /t {
+        proxy_pass                  https://unix:$TEST_NGINX_HTML_DIR/nginx.sock;
+        proxy_ssl_session_reuse     off;
+    }
+
+--- request
+GET /t
+--- response_body
+NONE
+
+--- error_log
+client certificate subject: nil
+
+--- no_error_log
+[error]
+[alert]
+[emerg]