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 ec42f0b15d0ff013fb01f73cef9a790fb46d0b63..b79492abdbd306b71669d72e023821d20de4941f 100644 (file)
--- 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 (file)
index 0000000..d6ce2ed
--- /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 546edfa38fd571e0443f0b30bef2c0d0b0f9fa0d..1bbbd541c05d36cb943b9f43748c9ccffd51d084 100644 (file)
--- 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
 --------------