16.3.18. TLS

TLS details are exposed to Lua scripts with the suricata.tls library, for example:

local tls = require("suricata.tls")

16.3.18.1. 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

16.3.18.2. API

16.3.18.2.1. 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.

16.3.18.2.2. Client Methods

16.3.18.2.2.1. 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

16.3.18.2.2.2. 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

16.3.18.2.2.3. 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

16.3.18.2.2.4. 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

16.3.18.2.2.5. 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

16.3.18.2.2.6. 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

16.3.18.2.2.7. 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

16.3.18.2.3. Server Methods

16.3.18.2.3.1. 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

16.3.18.2.3.2. 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

16.3.18.2.3.3. 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

16.3.18.2.3.4. 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

16.3.18.2.3.5. 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