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