<?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>
		This module provides various cryptography tools for use
		in &kamailio; configuration file using libgcrypt.
	</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>libgcrypt</emphasis> - part of GnuPG project
				(https://gnupg.org/software/libgcrypt/index.html).
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Parameters</title>
	<section id="gcrypt.p.init_vector">
		<title><varname>init_vector</varname> (str)</title>
		<para>
			The initialization vector used for the cryptographic operations.
			This needs to be a string value with 16 bytes lengths.
		</para>
		<para>
		<emphasis>
			Default value is set in the C code.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>init_vector</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("gcrypt", "init_vector", "abcdefghijklmnop")
...
</programlisting>
		</example>
	</section>
	<section id="gcrypt.p.aes_mode">
		<title><varname>aes_mode</varname> (int)</title>
		<para>
			Set it to 1 in order to do AES CBC encryption mode. By default,
			it does AES ECB mode.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>aes_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("gcrypt", "aes_mode", 1)
...
</programlisting>
		</example>
	</section>

	<section id="gcrypt.p.register_callid">
		<title><varname>register_callid</varname> (int)</title>
		<para>
			Set it to 1 in order to register a callback to core for generation
			of callid values for requests generated by &kamailio; tm module.
		</para>
		<para>
			This callid generator uses libcrypt random and hashing functions
			for generating RFC 4122 version 4 UUID with high quality entropy.
			It is useful when wanting to have new callids that cannot be
			predicted from previous values.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>register_callid</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("gcrypt", "register_callid", 1)
...
</programlisting>
		</example>
	</section>

	</section>

	<section>
	<title>Functions</title>
	<section id="gcrypt.f.gcrypt_aes_encrypt">
	    <title>
		<function moreinfo="none">gcrypt_aes_encrypt(text, key, 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 id="gcrypt.f.gcrypt_aes_decrypt">
	    <title>
		<function moreinfo="none">gcrypt_aes_decrypt(text, key, res)</function>
	    </title>
	    <para>
		Decrypts the text with the key using AES256 ECB encryption algorithm.
		The text has to be encoded in base64 format. 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_decrypt</function> usage</title>
		<programlisting format="linespecific">
...
gcrypt_aes_decrypt("$var(encrypted)", "my-secret-key", "$var(text)");
...
</programlisting>
	    </example>
	</section>
	</section>
</chapter>
