doc/userguide: document lua hashlib

doc/userguide/lua/index.rst

@@ -5,3 +5,4 @@ Lua support
 
    lua-usage
    lua-functions
+   libs/index

doc/userguide/lua/libs/hashlib.rst

@@ -0,0 +1,99 @@
+Hashing
+-------
+
+Hashing functions are exposed to Lua scripts with ``suricata.hashing``
+library. For example::
+
+  local hashing = require("suricata.hashing")
+
+SHA-256
+~~~~~~~
+
+``sha256_digest(string)``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SHA-256 hash the provided string returning the digest as bytes.
+
+``sha256_hex_digest(string)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SHA-256 hash the provided string returning the digest as a hex string.
+
+``sha256()``
+^^^^^^^^^^^^
+
+Returns a SHA-256 hasher that can be updated multiple times, for
+example::
+
+  local hashing = require("suricata.hashing")
+  hasher = hashing.sha256()
+  hasher.update("www.suricata")
+  hasher.update(".io")
+  hash = hasher.finalize_to_hex()
+
+The methods on the hasher object include:
+
+* ``update(string)``: Add more data to the hasher
+* ``finalize()``: Finalize the hash returning the hash as a byte string
+* ``finalize_to_hex()``: Finalize the hash returning the has as a hex string
+
+SHA-1
+~~~~~
+
+``sha1_digest(string)``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+SHA-1 hash the provided string returning the digest as bytes.
+
+``sha1_hex_digest(string)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SHA-1 hash the provided string returning the digest as a hex string.
+
+``sha1()``
+^^^^^^^^^^
+
+Returns a SHA-1 hasher that can be updated multiple times, for
+example::
+
+  local hashing = require("suricata.hashing")
+  hasher = hashing.sha1()
+  hasher.update("www.suricata")
+  hasher.update(".io")
+  hash = hasher.finalize_to_hex()
+
+The methods on the hasher object include:
+
+* ``update(string)``: Add more data to the hasher
+* ``finalize()``: Finalize the hash returning the hash as a byte string
+* ``finalize_to_hex()``: Finalize the hash returning the has as a hex string
+
+MD5
+~~~
+
+``md5_digest(string)``
+^^^^^^^^^^^^^^^^^^^^^^
+
+MD5 hash the provided string returning the digest as bytes.
+
+``md5_hex_digest(string)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MD5 hash the provided string returning the digest as a hex string.
+
+``md5()``
+^^^^^^^^^
+
+Returns a MD5 hasher that can be updated multiple times, for example::
+
+  local hashing = require("suricata.hashing")
+  hasher = hashing.md5()
+  hasher.update("www.suricata")
+  hasher.update(".io")
+  hash = hasher.finalize_to_hex()
+
+The methods on the hasher object include:
+
+* ``update(string)``: Add more data to the hasher
+* ``finalize()``: Finalize the hash returning the hash as a byte string
+* ``finalize_to_hex()``: Finalize the hash returning the hash as a hex string

doc/userguide/lua/libs/index.rst

@@ -0,0 +1,11 @@
+Lua Libraries
+=============
+
+Suricata provides Lua extensions, or libraries to Lua scripts with the
+``require`` keyword. These extensions are particularly important in
+Lua rules as Lua rules are executed in a restricted sandbox
+environment without access to additional modules.
+
+.. toctree::
+
+   hashlib

src/util-lua-hashlib.c

@@ -27,17 +27,16 @@
  * -- One shot hash
  * hash = hashing.sha256_digest("www.suricata.io")
  *
+ * -- One shot hash to hex
+ * hash = hashing.sha256_hexdigest("www.suricata.io")
+ *
  * -- Incremental hashing
  * hasher = hashing.sha256()
  * hasher:update("www.")
  * hasher:update("suricata.io")
  * hash = hasher:finalize()
  *
- * Support hashes:
- *
- * - sha256: sha256(), sha256_digest()
- * - sha1: sha1(), sha1_digest()
- * - md5: md5(), md5_digest()
+ * Support hashes: sha256, sha1, md5
  */
 
 #include "util-lua-hashlib.h"