Using native modules in the Iguana Translator

While scripting in the Translator, you may require access to functionality that can best be provided by an external native library (other than Lua).

For example, one of our customers required access to SHA-2 functionality. Lua modules for SHA-2 exist for Lua 5.2, but Iguana is (currently) based on Lua 5.1. Since there are many freely available native SHA-2 implementations in C, we hypothesized that we could use the rich Lua C-API to leverage an external library such that it can be used in any Lua script.

To prove this theory, we created a native module around the BSD-licensed SHA-2 implementation created by Aaron Gifford. Then we simply “required” it as a dependency in our Lua script. Once required, we discovered that it behaves just like a Lua module in the Translator.

Note: Please note that this is simply a proof-of-concept! We are still experimenting with solutions to formulate best practices. We will publish additional documentation about how to create native modules like this once we finish this investigation.

How It Works

From the point-of-view of a Lua script, a native module is not that much different than any other module. The Lua run-time environment uses the package.cpath setting and rules to find native modules via require. The package.cpath can be modified at run-time to have a script look for the module almost anywhere, but the default is to look for the module in the current working directory (as either an .so file or .dll file). In the Iguana Translator, the default location is the same directory where Iguana is installed.

To install and use our SHA-2 module:

  1. Copy this file to the 64-bit Linux host where Iguana is running (placing the file in the root of the Iguana installation):  sha2.so
  2. Use require to find and load the module into a Translator script, as you would with any module.
  3. Invoke the module functions as needed.
-- Load the sha2.so or sha2.dll from the package.cpath
require "sha2"

-- Invoke the sha256hex() function provided by the module
local digest = sha2.sha256hex("abc")

-- digest should contain the string "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"