<?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.
	</para>
	<para>
		It relies on OpenSSL libraries for cryptographic operations
		(libssl, libcrypto).
	</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>libcrypto</emphasis> - part of OpenSSL project
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Parameters</title>
	<section id="crypto.p.salt">
		<title><varname>salt</varname> (str)</title>
		<para>
			A keyword to generate salt for encryption. It must be
			at least 8 chars long. If set to empty, no salt is used
			for encryption.
		</para>
		<para>
			The salt is a binary array that is appended to the encryption
			password for better protection against dictionary attacks. Same
			salt and password need to be when encrypting and decrypting.
		</para>
		<para>
		<emphasis>
			Default value is "..." (see code).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>salt</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("crypto", "salt", "l0Bh2M8a")
...
</programlisting>
		</example>
	</section>
	<section id="crypto.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 libssl 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("crypto", "register_callid", 1)
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
	<section id="async.f.crypto_aes_encrypt">
	    <title>
		<function moreinfo="none">crypto_aes_encrypt(text, key, res)</function>
	    </title>
	    <para>
		Encrypts the text with the key using AES 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>crypto_aes_encrypt</function> usage</title>
		<programlisting format="linespecific">
...
crypto_aes_encrypt("$rb", "my-secret-key", "$var(encrypted)");
...
</programlisting>
	    </example>
	</section>

	<section id="async.f.crypto_aes_decrypt">
	    <title>
		<function moreinfo="none">crypto_aes_decrypt(text, key, res)</function>
	    </title>
	    <para>
		Decrypts the text with the key using AES 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>crypto_aes_decrypt</function> usage</title>
		<programlisting format="linespecific">
...
crypto_aes_decrypt("$var(encrypted)", "my-secret-key", "$var(text)");
...
</programlisting>
	    </example>
	</section>
	</section>
</chapter>
