From: Jeff Lucovsky Date: Mon, 12 May 2025 12:27:52 +0000 (-0400) Subject: doc/tls: Update Lua TLS functions X-Git-Tag: suricata-8.0.0-rc1~250 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F13275%2Fhead;p=thirdparty%2Fsuricata.git doc/tls: Update Lua TLS functions Issue: 7608 Update the documentation to reflect the new and expanded functions available form the Lua TLS library There are now "server" and "client" versions of most functions. The TLS object getter is now "get_tx" --- diff --git a/doc/userguide/lua/libs/index.rst b/doc/userguide/lua/libs/index.rst index ec42f0b15d..b79492abdb 100644 --- a/doc/userguide/lua/libs/index.rst +++ b/doc/userguide/lua/libs/index.rst @@ -20,4 +20,5 @@ environment without access to additional modules. rule smtp ssh + tls ja3 diff --git a/doc/userguide/lua/libs/tls.rst b/doc/userguide/lua/libs/tls.rst new file mode 100644 index 0000000000..d6ce2eda3a --- /dev/null +++ b/doc/userguide/lua/libs/tls.rst @@ -0,0 +1,261 @@ +TLS +### + +.. role:: example-rule-emphasis + +TLS details are exposed to Lua scripts with the +``suricata.tls`` library, for example:: + + local tls = require("suricata.tls") + +Setup +***** + +If your purpose is to create a logging script, initialize the buffer as: + +:: + + function init (args) + local needs = {} + needs["protocol"] = "tls" + return needs + end + +Otherwise if a detection script:: + + function init (args) + return {} + end + +API +*** + +Transaction +=========== + +TLS is transaction based, and the current transaction must be +obtained before use:: + + local tx, err = tls.get_tx() + if tx == nil then + print(err) + end + +All other functions are methods on the transaction table. + +Client Methods +============== + +``get_client_version`` +~~~~~~~~~~~~~~~~~~~~~~ + +Get the negotiated version in a TLS session as a string through ``get_client_version``. + +Example: + +:: + + function log (args) + t, err = tls.get_tx() + version = t:get_client_version() + if version ~= nil then + -- do something + end + end + +``get_client_cert_chain`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Make certificate chain available to the script through ``get_client_cert_chain`` + +The output is an array of certificate with each certificate being an hash +with `data` and `length` keys. + +Example: + +:: + + -- Use debian lua-luaossl coming from https://github.com/wahern/luaossl + local x509 = require"openssl.x509" + + chain = t:get_client_cert_chain() + for k, v in pairs(chain) do + -- v.length is length of data + -- v.data is raw binary data of certificate + print("data length is" .. v["length"] .. "\n") + cert = x509.new(v["data"], "DER") + print(cert:text() .. "\n") + end + +``get_client_cert_info`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +Make certificate information available to the script through ``get_client_cert_info`` + +Example: + +:: + + function log (args) + version, subject, issuer, fingerprint = t:get_client_cert_info() + if version ~= nil then + -- do something + end + end + +``get_client_cert_not_after`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the Unix timestamp of end of validity of certificate. + +Example: + +:: + + function log (args) + notafter = t:get_client_cert_not_after() + if notafter < os.time() then + -- expired certificate + end + end + +``get_client_cert_not_before`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the Unix timestamp of beginning of validity of certificate. + +Example: + +:: + + function log (args) + notbefore = t:get_client_cert_not_before() + if notbefore > os.time() then + -- not yet valid certificate + end + end + +``get_client_serial`` +~~~~~~~~~~~~~~~~~~~~~ + +Get TLS certificate serial number through ``get_client_serial``. + +Example: + +:: + + function log (args) + serial = t:get_client_serial() + if serial ~= nil then + -- do something + end + end + +``get_client_sni`` +~~~~~~~~~~~~~~~~~~ + +Get the Server name Indication from a TLS connection. + +Example: + +:: + + function log (args) + asked_domain = t:get_client_sni() + if string.find(asked_domain, "badguys") then + -- ok connection to bad guys let's do something + end + end + +Server Methods +============== + +``get_server_cert_info`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +Make certificate information available to the script through ``get_server_cert_info`` + +Example: + +:: + + function log (args) + version, subject, issuer, fingerprint = t:get_server_cert_info() + if version ~= nil then + -- do something + end + end + +``get_server_cert_chain`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Make certificate chain available to the script through ``get_server_cert_chain`` + +The output is an array of certificate with each certificate being an hash +with `data` and `length` keys. + +Example: + +:: + + -- Use debian lua-luaossl coming from https://github.com/wahern/luaossl + local x509 = require"openssl.x509" + + chain = t:get_server_cert_chain() + for k, v in pairs(chain) do + -- v.length is length of data + -- v.data is raw binary data of certificate + print("data length is" .. v["length"] .. "\n") + cert = x509.new(v["data"], "DER") + print(cert:text() .. "\n") + end + + +``get_server_cert_not_after`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the Unix timestamp of end of validity of certificate. + +Example: + +:: + + function log (args) + notafter = t:get_server_cert_not_after() + if notafter < os.time() then + -- expired certificate + end + end + +``get_server_cert_not_before`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the Unix timestamp of beginning of validity of certificate. + +Example: + +:: + + function log (args) + notbefore = t:get_server_cert_not_before() + if notbefore > os.time() then + -- not yet valid certificate + end + end + +``get_server_serial`` +~~~~~~~~~~~~~~~~~~~~~ + +Get TLS certificate serial number through ``get_server_serial``. + +Example: + +:: + + function log (args) + serial = t:get_server_serial() + if serial ~= nil then + -- do something + end + end + diff --git a/doc/userguide/lua/lua-functions.rst b/doc/userguide/lua/lua-functions.rst index 546edfa38f..1bbbd541c0 100644 --- a/doc/userguide/lua/lua-functions.rst +++ b/doc/userguide/lua/lua-functions.rst @@ -25,7 +25,7 @@ For output logs, follow the pattern below. (The complete script structure can be function init (args) local needs = {} - needs["protocol"] = "http" + needs["protocol"] = "tls" return needs end @@ -206,149 +206,6 @@ HttpGetResponseHeaders print(n,v) end -TLS ---- - -For log output, initialize with: - -:: - - function init (args) - local needs = {} - needs["protocol"] = "tls" - return needs - end - -For detection, initialization is as follows: - -:: - - function init (args) - local needs = {} - needs["tls"] = tostring(true) - return needs - end - -TlsGetVersion -~~~~~~~~~~~~~ - -Get the negotiated version in a TLS session as a string through TlsGetVersion. - -Example: - -:: - - function log (args) - version = TlsGetVersion() - if version then - -- do something - end - end - -TlsGetCertInfo -~~~~~~~~~~~~~~ - -Make certificate information available to the script through TlsGetCertInfo. - -Example: - -:: - - function log (args) - version, subject, issuer, fingerprint = TlsGetCertInfo() - if version == nil then - return 0 - end - end - -TlsGetCertChain -~~~~~~~~~~~~~~~ - -Make certificate chain available to the script through TlsGetCertChain. - -The output is an array of certificate with each certificate being an hash -with `data` and `length` keys. - -Example: - -:: - - -- Use debian lua-luaossl coming from https://github.com/wahern/luaossl - local x509 = require"openssl.x509" - - chain = TlsGetCertChain() - for k, v in pairs(chain) do - -- v.length is length of data - -- v.data is raw binary data of certificate - cert = x509.new(v["data"], "DER") - print(cert:text() .. "\n") - end - - -TlsGetCertNotAfter -~~~~~~~~~~~~~~~~~~ - -Get the Unix timestamp of end of validity of certificate. - -Example: - -:: - - function log (args) - notafter = TlsGetCertNotAfter() - if notafter < os.time() then - -- expired certificate - end - end - -TlsGetCertNotBefore -~~~~~~~~~~~~~~~~~~~ - -Get the Unix timestamp of beginning of validity of certificate. - -Example: - -:: - - function log (args) - notbefore = TlsGetCertNotBefore() - if notbefore > os.time() then - -- not yet valid certificate - end - end - -TlsGetCertSerial -~~~~~~~~~~~~~~~~ - -Get TLS certificate serial number through TlsGetCertSerial. - -Example: - -:: - - function log (args) - serial = TlsGetCertSerial() - if serial then - -- do something - end - end - -TlsGetSNI -~~~~~~~~~ - -Get the Server name Indication from a TLS connection. - -Example: - -:: - - function log (args) - asked_domain = TlsGetSNI() - if string.find(asked_domain, "badguys") then - -- ok connection to bad guys let's do something - end - end - Streaming Data --------------