modules_k/cfgutils: Added exported function for core_hash()

- This means you can calculate hashes on strings within the
  configuration file.

modules_k/cfgutils/README

@@ -24,7 +24,7 @@ Daniel-Constantin Mierla
 
    <[email protected]>
 
-   Copyright © 2007, 2008, 2004 1und1 Internet AG, BASIS AudioNet GmbH,
+   Copyright © 2007, 2008, 2004 1und1 Internet AG, BASIS AudioNet GmbH,
    Elena-Ramona Modroiu, FhG FOKUS
      __________________________________________________________________
 
@@ -59,6 +59,7 @@ Daniel-Constantin Mierla
               4.14. is_gflag(flag)
               4.15. lock(key)
               4.16. unlock(key)
+              4.17. core_hash(string1, string2, size)
 
         5. MI Commands
 
@@ -98,16 +99,17 @@ Daniel-Constantin Mierla
    1.18. is_gflag() usage
    1.19. lock() usage
    1.20. unlock() usage
-   1.21. rand_set_prob usage
-   1.22. rand_reset_prob usage
-   1.23. rand_get_prob usage
-   1.24. check_config_hash usage
-   1.25. get_config_hash usage
-   1.26. set_gflag usage
-   1.27. reset_gflag usage
-   1.28. is_gflag usage
-   1.29. get_gflags usage
-   1.30. RANDOM pseudo-variable usage
+   1.21. core_hash() usage
+   1.22. rand_set_prob usage
+   1.23. rand_reset_prob usage
+   1.24. rand_get_prob usage
+   1.25. check_config_hash usage
+   1.26. get_config_hash usage
+   1.27. set_gflag usage
+   1.28. reset_gflag usage
+   1.29. is_gflag usage
+   1.30. get_gflags usage
+   1.31. RANDOM pseudo-variable usage
 
 Chapter 1. Admin Guide
 
@@ -140,6 +142,7 @@ Chapter 1. Admin Guide
         4.14. is_gflag(flag)
         4.15. lock(key)
         4.16. unlock(key)
+        4.17. core_hash(string1, string2, size)
 
    5. MI Commands
 
@@ -163,10 +166,10 @@ Chapter 1. Admin Guide
 
    The cfgutils module can be used to introduce randomness to the
    behaviour of the server. It provides setup functions and the
-   "rand_event" function. This function return either true or false,
+   “rand_event� function. This function return either true or false,
    depending on a random value and a specified probability. E.g. if you
    set via fifo or script a probability value of 5%, then 5% of all calls
-   to rand_event will return true. The pseudovariable "$RANDOM" could be
+   to rand_event will return true. The pseudovariable “$RANDOM� could be
    used to introduce random values e.g. into a SIP reply.
 
    The benefit of this module is the probability of the decision can be
@@ -176,20 +179,20 @@ Chapter 1. Admin Guide
 
    The module exports commands to FIFO server that can be used to change
    the global settings via FIFO interface. The FIFO commands are:
-   "set_prob", "reset_prob" and "get_prob".
+   “set_prob�, “reset_prob� and “get_prob�.
 
    This module can be used for simple load-shedding, e.g. reply 5% of the
    Invites with a 503 error and a adequate random Retry-After value.
 
    The module provides as well functions to delay the execution of the
-   server. The functions "sleep" and "usleep" could be used to let the
+   server. The functions “sleep� and “usleep� could be used to let the
    server wait a specific time interval.
 
    It can also hash the config file used from the server with a (weak)
    cryptographic hash function on startup. This value is saved and can be
    later compared to the actual hash, to detect modifications of this file
    after the server start. This functions are available as the FIFO
-   commands "check_config_hash" and "get_config_hash".
+   commands “check_config_hash� and “get_config_hash�.
 
    The gflags functionality (global flags) keeps a bitmap of flags in
    shared memory and may be used to change behaviour of server based on
@@ -206,7 +209,7 @@ Chapter 1. Admin Guide
 
    The module exports external commands that can be used to change the
    global flags via Management Interface. The MI commands are:
-   "set_gflag", "reset_gflag" and "is_gflag".
+   “set_gflag�, “reset_gflag� and “is_gflag�.
 
 2. Dependencies
 
@@ -225,7 +228,7 @@ Chapter 1. Admin Guide
 
    The initial value of the probability.
 
-   Default value is "10".
+   Default value is “10�.
 
    Example 1.1. initial_probability parameter usage
 modparam("cfgutils", "initial_probability", 15)
@@ -245,7 +248,7 @@ modparam("cfgutils", "hash_file", "/etc/kamailio/kamailio.cfg")
 
    The initial value of global flags bitmap.
 
-   Default value is "0".
+   Default value is “0�.
 
    Example 1.3. initial parameter usage
 modparam("cfgutils", "initial_gflags", 15)
@@ -255,7 +258,7 @@ modparam("cfgutils", "initial_gflags", 15)
    Size of lock set - the value is used as power of two to compute the
    size of lock array.
 
-   Default value is "0" - no lock set created.
+   Default value is “0� - no lock set created.
 
    Example 1.4. lock_set_size parameter usage
 modparam("cfgutils", "lock_set_size", 4)
@@ -278,6 +281,7 @@ modparam("cfgutils", "lock_set_size", 4)
    4.14. is_gflag(flag)
    4.15. lock(key)
    4.16. unlock(key)
+   4.17. core_hash(string1, string2, size)
 
 4.1. rand_event()
 
@@ -296,9 +300,9 @@ if (rand_event()) {
 
 4.2. rand_set_prob(probabiltiy)
 
-   Set the "probability" of the decision.
+   Set the “probability� of the decision.
 
-   "probability" can have a value from the range 0..100.
+   “probability� can have a value from the range 0..100.
 
    Example 1.6. rand_set_prob() usage
 ...
@@ -322,7 +326,7 @@ rand_reset_prob();
 ...
 rand_get_prob();
 
-4.5. sleep(time)
+4.5.  sleep(time)
 
    Waits "time" seconds.
 
@@ -337,7 +341,7 @@ rand_get_prob();
 sleep("1");
 ...
 
-4.6. usleep(time)
+4.6.  usleep(time)
 
    Waits "time" milli-seconds.
 
@@ -352,7 +356,7 @@ sleep("1");
 usleep("500");
 ...
 
-4.7. abort()
+4.7.  abort()
 
    Debugging function that aborts the server. Depending on the
    configuration of the server a core dump will be created.
@@ -365,7 +369,7 @@ usleep("500");
 abort();
 ...
 
-4.8. pkg_status()
+4.8.  pkg_status()
 
    Debugging function that dumps the status for the private (PKG) memory.
    This information is logged to the default log facility, depending on
@@ -380,7 +384,7 @@ abort();
 pkg_status();
 ...
 
-4.9. pkg_summary()
+4.9.  pkg_summary()
 
    Debugging function that dumps the summary for the private (PKG) memory
    usage. This information is logged to the default log facility,
@@ -395,7 +399,7 @@ pkg_status();
 pkg_summary();
 ...
 
-4.10. shm_status()
+4.10.  shm_status()
 
    Debugging function that dumps the status for the shared (SHM) memory.
    This information is logged to the default log facility, depending on
@@ -410,7 +414,7 @@ pkg_summary();
 shm_status();
 ...
 
-4.11. shm_summary()
+4.11.  shm_summary()
 
    Debugging function that dumps the summary for the shared (SHM) memory
    usage. This information is logged to the default log facility,
@@ -427,9 +431,9 @@ shm_summary();
 
 4.12. set_gflag(flag)
 
-   Set the bit at the position "flag" in global flags.
+   Set the bit at the position “flag� in global flags.
 
-   "flag" can have a value in the range of 0..31.
+   “flag� can have a value in the range of 0..31.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
@@ -441,9 +445,9 @@ set_gflag("4");
 
 4.13. reset_gflag(flag)
 
-   Reset the bit at the position "flag" in global flags.
+   Reset the bit at the position “flag� in global flags.
 
-   "flag" can have a value in the range of 0..31.
+   “flag� can have a value in the range of 0..31.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
@@ -455,9 +459,9 @@ reset_gflag("4");
 
 4.14. is_gflag(flag)
 
-   Check if bit at the position "flag" in global flags is set.
+   Check if bit at the position “flag� in global flags is set.
 
-   "flag" can have a value in the range of 0..31.
+   “flag� can have a value in the range of 0..31.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
@@ -480,7 +484,7 @@ if(is_gflag("4"))
    after another lock() unless you are sure the keys hit different array
    entries.
 
-   "key" can be static string or string with PVs.
+   “key� can be static string or string with PVs.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
@@ -494,7 +498,7 @@ lock("$rU");
 
    Unlock the key.
 
-   "key" can be static string or string with PVs.
+   “key� can be static string or string with PVs.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
@@ -504,6 +508,24 @@ lock("$rU");
 unlock("$rU");
 ...
 
+4.17. core_hash(string1, string2, size)
+
+   Exported function that enables the core_hash() function to be used from
+   the configuration file.
+
+   Parameters:
+     * “string1� first string to hash
+     * “string2� (optional) second string to hash (set to "" if not
+       needed)
+     * “size� size of the hash space (used as a power of 2)
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.21. core_hash() usage
+...
+core_hash("$ci", "", 4);
+...
+
 5. MI Commands
 
    5.1. rand_set_prop
@@ -528,7 +550,7 @@ unlock("$rU");
 
    The parameter value must be a number from 0 to 100.
 
-   Example 1.21. rand_set_prob usage
+   Example 1.22. rand_set_prob usage
 ...
 $ kamctl fifo rand_set_prob 10
 ...
@@ -539,7 +561,7 @@ $ kamctl fifo rand_set_prob 10
 
    This command don't need a parameter.
 
-   Example 1.22. rand_reset_prob usage
+   Example 1.23.  rand_reset_prob usage
 ...
 $ kamctl fifo rand_reset_prob
 ...
@@ -550,7 +572,7 @@ $ kamctl fifo rand_reset_prob
 
    The function return the actual probability value.
 
-   Example 1.23. rand_get_prob usage
+   Example 1.24. rand_get_prob usage
 ...
 $ kamctl fifo get_prob
 The actual probability is 50 percent.
@@ -564,7 +586,7 @@ The actual probability is 50 percent.
    there are not identical, 404 if no file for hashing has been configured
    and 500 on errors. Additional a short text message is printed.
 
-   Example 1.24. check_config_hash usage
+   Example 1.25. check_config_hash usage
 ...
 $ kamctl fifo check_config_hash
 The actual config file hash is identical to the stored one.
@@ -577,7 +599,7 @@ The actual config file hash is identical to the stored one.
    The function returns 200 OK and the hash value on success or 404 if no
    file for hashing has been configured.
 
-   Example 1.25. get_config_hash usage
+   Example 1.26. get_config_hash usage
 ...
 $ kamctl fifo get_config_hash
 1580a37104eb4de69ab9f31ce8d6e3e0
@@ -590,7 +612,7 @@ $ kamctl fifo get_config_hash
    The parameter value must be a bitmask in decimal or hexadecimal format.
    The bitmask has a 32 bit size.
 
-   Example 1.26. set_gflag usage
+   Example 1.27. set_gflag usage
 ...
 $ kamctl fifo set_gflag 1
 $ kamctl fifo set_gflag 0x3
@@ -603,7 +625,7 @@ $ kamctl fifo set_gflag 0x3
    The parameter value must be a bitmask in decimal or hexadecimal format.
    The bitmask has a 32 bit size.
 
-   Example 1.27. reset_gflag usage
+   Example 1.28.  reset_gflag usage
 ...
 $ kamctl fifo reset_gflag 1
 $ kamctl fifo reset_gflag 0x3
@@ -619,7 +641,7 @@ $ kamctl fifo reset_gflag 0x3
    The function returns TRUE if all the flags from the set are set and
    FALSE if at least one is not set.
 
-   Example 1.28. is_gflag usage
+   Example 1.29. is_gflag usage
 ...
 $ kamctl fifo set_gflag 1024
 $ kamctl fifo is_gflag 1024
@@ -642,7 +664,7 @@ TRUE
    Return the bitmap with all flags. The function gets no parameters and
    returns the bitmap in hexadecimal and decimal format.
 
-   Example 1.29. get_gflags usage
+   Example 1.30.  get_gflags usage
 ...
 $ kamctl fifo get_gflags
 0x3039
@@ -657,7 +679,7 @@ $ kamctl fifo get_gflags
 
    Returns a random value from the [0 - 2^31) range.
 
-   Example 1.30. RANDOM pseudo-variable usage
+   Example 1.31. RANDOM pseudo-variable usage
 ...
 if (rand_event()) {
   $avp(i:10) = ($RANDOM / 16777216); # 2^24

modules_k/cfgutils/cfgutils.c

@@ -118,6 +118,9 @@ static int pv_get_random_val(struct sip_msg *msg, pv_param_t *param,
 static int fixup_prob( void** param, int param_no);
 static int fixup_gflags( void** param, int param_no);
 
+static int fixup_core_hash(void **param, int param_no);
+static int w_core_hash(struct sip_msg *msg, char *p1, char *p2, char *p3);
+
 int bind_cfgutils(cfgutils_api_t *api);
 
 static int mod_init(void);
@@ -172,6 +175,8 @@ static cmd_export_t cmds[]={
 		ANY_ROUTE},
 	{"unlock",       (cmd_function)cfg_unlock,  1,   fixup_spve_null, 0,
 		ANY_ROUTE},
+	{"core_hash",    (cmd_function)w_core_hash, 3,   fixup_core_hash, 0,
+		ANY_ROUTE},
 	{"bind_cfgutils", (cmd_function)bind_cfgutils,  0,
 		0, 0, 0},
 	{0, 0, 0, 0, 0, 0}
@@ -802,6 +807,46 @@ int cfgutils_unlock(str *lkey)
 	return cfg_lock_helper(lkey, 1);
 }
 
+static int fixup_core_hash(void **param, int param_no)
+{
+	if (param_no == 1)
+		return fixup_spve_null(param, 1);
+	else if (param_no == 2)
+		return fixup_spve_null(param, 1);
+	else if (param_no == 3)
+		return fixup_igp_null(param, 1);
+	else
+		return 0;
+}
+
+static int w_core_hash(struct sip_msg *msg, char *p1, char *p2, char *p3)
+{
+        str s1, s2;
+        int size;
+
+        if (fixup_get_svalue(msg, (gparam_p) p1, &s1) != 0)
+        {
+                LM_ERR("invalid s1 paramerer\n");
+                return -1;
+        }
+        if (fixup_get_svalue(msg, (gparam_p) p2, &s2) != 0)
+        {
+                LM_ERR("invalid s2 paramerer\n");
+                return -1;
+        }
+        if (fixup_get_ivalue(msg, (gparam_p) p3, &size) != 0)
+        {
+                LM_ERR("invalid size paramerer\n");
+                return -1;
+        }
+
+        if (size <= 0) size = 2;
+        else size = 1 << size;
+
+	/* Return value _MUST_ be > 0 */
+        return core_hash(&s1, s2.len ? &s2 : NULL, size) + 1;
+}
+
 /**
  * @brief bind functions to CFGUTILS API structure
  */

modules_k/cfgutils/doc/cfgutils_admin.xml

@@ -521,6 +521,38 @@ lock("$rU");
 ...
 unlock("$rU");
 ...
+</programlisting>
+		</example>
+	</section>
+	<section>
+		<title><function moreinfo="none">core_hash(string1, string2, size)</function></title>
+		<para>
+		Exported function that enables the core_hash() function to be used
+		from the configuration file.
+		</para>
+		<para>Parameters:</para>
+		<itemizedlist>
+			<listitem>
+				<para><quote>string1</quote> first string to
+					hash</para>
+			</listitem>
+			<listitem>
+				<para><quote>string2</quote> (optional) second
+					string to hash (set to "" if not
+					needed)</para>
+			</listitem>
+			<listitem>
+				<para><quote>size</quote> size of the hash space
+					(used as a power of 2)</para>
+			</listitem>
+		</itemizedlist>
+		<para>This function can be used from ANY_ROUTE.</para>
+		<example>
+		<title><function moreinfo="none">core_hash()</function> usage</title>
+		<programlisting format="linespecific">
+...
+core_hash("$ci", "", 4);
+...
 </programlisting>
 		</example>
 	</section>