From: Jason Ish <jason.ish@oisf.net>
Date: Tue, 21 Jan 2025 22:57:31 +0000 (-0600)
Subject: doc/userguide: document lua hashlib
X-Git-Tag: suricata-8.0.0-beta1~519
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c8b28b1512141c57e1d5cf5216aea07ba13371bf;p=thirdparty%2Fsuricata.git

doc/userguide: document lua hashlib
---

diff --git a/doc/userguide/lua/index.rst b/doc/userguide/lua/index.rst
index d6bbf70964..fcb558408f 100644
--- a/doc/userguide/lua/index.rst
+++ b/doc/userguide/lua/index.rst
@@ -5,3 +5,4 @@ Lua support
 
    lua-usage
    lua-functions
+   libs/index
diff --git a/doc/userguide/lua/libs/hashlib.rst b/doc/userguide/lua/libs/hashlib.rst
new file mode 100644
index 0000000000..be8fe77e51
--- /dev/null
+++ b/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
diff --git a/doc/userguide/lua/libs/index.rst b/doc/userguide/lua/libs/index.rst
new file mode 100644
index 0000000000..09e67ca9a6
--- /dev/null
+++ b/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
diff --git a/src/util-lua-hashlib.c b/src/util-lua-hashlib.c
index 537d885653..9c8bf7dab2 100644
--- a/src/util-lua-hashlib.c
+++ b/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"