pvtpl: new module to process pv templates loaded from files

zaleos · Mar 20, 2024 · 3e3e903 · 3e3e903
1 parent 951ab11
commit 3e3e903
Show file tree

Hide file tree

Showing 6 changed files with 674 additions and 0 deletions.
diff --git a/src/modules/pvtpl/Makefile b/src/modules/pvtpl/Makefile
@@ -0,0 +1,9 @@
+#
+# WARNING: do not run this directly, it should be run by the main Makefile
+
+include ../../Makefile.defs
+auto_gen=
+NAME=pvtpl.so
+LIBS=
+
+include ../../Makefile.modules
diff --git a/src/modules/pvtpl/README b/src/modules/pvtpl/README
@@ -0,0 +1,118 @@
+PVTPL Module
+
+Daniel-Constantin Mierla
+
+   asipto.com
+   <[email protected]>
+
+Edited by
+
+Daniel-Constantin Mierla
+
+   <[email protected]>
+
+   Copyright © 2024 http://www.asipto.com
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Parameters
+
+              3.1. tpl (str)
+
+        4. Functions
+
+              4.1. pvtpl_apply(tplname, res)
+
+   List of Examples
+
+   1.1. Set tpl parameter
+   1.2. gcrypt_aes_encrypt usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Parameters
+
+        3.1. tpl (str)
+
+   4. Functions
+
+        4.1. pvtpl_apply(tplname, res)
+
+1. Overview
+
+   The module reads content of files at startup and can evaluate the
+   variables inside during runtime.
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * None.
+
+2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
+     * None.
+
+3. Parameters
+
+   3.1. tpl (str)
+
+3.1. tpl (str)
+
+   The definition of a template file:
+     * "name=_string_;fpath=_number_;bsize=_number_"
+
+   The parameter can be set multiple times to get more templates in same
+   configuration file.
+     * name - name of the template.
+     * fpath - path to the template file.
+     * bsize - buffer size to evaluate the template (default: 1024).
+
+   Default value is NULL.
+
+   Example 1.1. Set tpl parameter
+...
+modparam("pvtpl", "tpl", "name=tpl1;fpath=/etc/kamailio/tpl1.pvtpl;bsize=512;")
+modparam("pvtpl", "tpl", "name=tpl2;fpath=/etc/kamailio/tpl2.pvtpl;bsize=256;")
+...
+
+4. Functions
+
+   4.1. pvtpl_apply(tplname, res)
+
+4.1.  pvtpl_apply(tplname, res)
+
+   Encrypts the text with the key using AES256 ECB encryption algorithm.
+   The result is encoded in base64 format and stored in res. The parameter
+   res must be a read-write variables. The parameters text and key can be
+   static strings or strings with variables (dynamic strings).
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.2. gcrypt_aes_encrypt usage
+...
+gcrypt_aes_encrypt("$rb", "my-secret-key", "$var(encrypted)");
+...
diff --git a/src/modules/pvtpl/doc/Makefile b/src/modules/pvtpl/doc/Makefile
@@ -0,0 +1,4 @@
+docs = pvtpl.xml
+
+docbook_dir = ../../../../doc/docbook
+include $(docbook_dir)/Makefile.module
diff --git a/src/modules/pvtpl/doc/pvtpl.xml b/src/modules/pvtpl/doc/pvtpl.xml
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
+%docentities;
+
+]>
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+    <bookinfo>
+	<title>PVTPL Module</title>
+	<productname class="trade">&kamailioname;</productname>
+	<authorgroup>
+	    <author>
+		<firstname>Daniel-Constantin</firstname>
+		<surname>Mierla</surname>
+		<affiliation><orgname>asipto.com</orgname></affiliation>
+		<email>[email protected]</email>
+		<address>
+		<otheraddr>
+		<ulink url="http://www.asipto.com">http://www.asipto.com</ulink>
+		</otheraddr>
+		</address>
+	    </author>
+	    <editor>
+		<firstname>Daniel-Constantin</firstname>
+		<surname>Mierla</surname>
+		<email>[email protected]</email>
+	    </editor>
+	</authorgroup>
+	<copyright>
+	    <year>2024</year>
+	    <holder>http://www.asipto.com</holder>
+	</copyright>
+    </bookinfo>
+    <toc></toc>
+
+    <xi:include href="pvtpl_admin.xml"/>
+
+</book>
diff --git a/src/modules/pvtpl/doc/pvtpl_admin.xml b/src/modules/pvtpl/doc/pvtpl_admin.xml
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
+%docentities;
+
+]>
+<!-- Module User's Guide -->
+
+<chapter>
+
+	<title>&adminguide;</title>
+
+	<section>
+	<title>Overview</title>
+	<para>
+		The module reads content of files at startup and can evaluate the variables
+		inside during runtime.
+	</para>
+	</section>
+	<section>
+	<title>Dependencies</title>
+	<section>
+		<title>&kamailio; Modules</title>
+		<para>
+		The following modules must be loaded before this module:
+			<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>None</emphasis>.
+			</para>
+			</listitem>
+			</itemizedlist>
+		</para>
+	</section>
+	<section>
+		<title>External Libraries or Applications</title>
+		<para>
+		The following libraries or applications must be installed before running
+		&kamailio; with this module loaded:
+			<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>None</emphasis>.
+			</para>
+			</listitem>
+			</itemizedlist>
+		</para>
+	</section>
+	</section>
+	<section>
+	<title>Parameters</title>
+	<section id="pvtpl.p.tpl">
+		<title><varname>tpl</varname> (str)</title>
+		<para>
+		The definition of a template file:
+		</para>
+		<itemizedlist>
+		<listitem>
+		<para>
+		"name=_string_;fpath=_number_;bsize=_number_"
+		</para>
+		</listitem>
+		</itemizedlist>
+		<para>
+			The parameter can be set multiple times to get more templates in
+			same configuration file.
+		</para>
+		<itemizedlist>
+		<listitem>
+		<para>
+			<emphasis>name</emphasis> - name of the template.
+		</para>
+		</listitem>
+		<listitem>
+		<para>
+			<emphasis>fpath</emphasis> - path to the template file.
+		</para>
+		</listitem>
+		<listitem>
+		<para>
+			<emphasis>bsize</emphasis> - buffer size to evaluate the template
+			(default: 1024).
+		</para>
+		</listitem>
+		</itemizedlist>
+		<para>
+		<emphasis>
+			Default value is NULL.
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>tpl</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("pvtpl", "tpl", "name=tpl1;fpath=/etc/kamailio/tpl1.pvtpl;bsize=512;")
+modparam("pvtpl", "tpl", "name=tpl2;fpath=/etc/kamailio/tpl2.pvtpl;bsize=256;")
+...
+</programlisting>
+		</example>
+	</section>
+	</section>
+
+	<section>
+	<title>Functions</title>
+	<section id="pvtpl.f.pvtpl_apply">
+	    <title>
+		<function moreinfo="none">pvtpl_apply(tplname, res)</function>
+	    </title>
+	    <para>
+		Encrypts the text with the key using AES256 ECB encryption algorithm.
+		The result is encoded in base64 format and stored in res. The parameter
+		res must be a read-write variables. The parameters text and key can
+		be static strings or strings with variables (dynamic strings).
+		</para>
+		<para>
+		This function can be used from ANY_ROUTE.
+		</para>
+		<example>
+		<title><function>gcrypt_aes_encrypt</function> usage</title>
+		<programlisting format="linespecific">
+...
+gcrypt_aes_encrypt("$rb", "my-secret-key", "$var(encrypted)");
+...
+</programlisting>
+	    </example>
+	</section>
+	</section>
+
+</chapter>