<?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 replaces the common system dns resolver functions from core
		with the DNSSEC wrappers provided by libval. Practically, by loading
		the module, &kamailio; will make use of extensions to DNS which provide
		origin authentication of DNS data, authenticated denial of existence,
		and data integrity.
	</para>
	<para>
		There is no module parameter that should be set nor function that has to
		be executed by the configuration file. Existing SIP server deployments
		can be updated to use DNSSEC by loading this module and setting
		appropriate DNS server to the operating system.
	</para>
	<para>
		Installing libval can be done from
		<ulink url="https://www.dnssec-tools.org/">https://www.dnssec-tools.org</ulink>.
	</para>
	<para>
		More details about DNSSEC are available at:
		<ulink url="http://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions">
			http://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions</ulink>.
	</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>No dependencies on other &kamailio; modules</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>libval</emphasis> - check
				<ulink url="https://www.dnssec-tools.org/">https://www.dnssec-tools.org</ulink>
				for installation guidelines.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
<section>
     <title>Parameters</title>
 
     <section>
       <title><varname>general_query_flags</varname> (integer)</title>
 
 
 		<para> Set this parameter to an integer value containing of an ORed result of one or more of the following
		values
		(constant present only for documentation process, as they are mostly mapped to libval flags).Setting this
		parameter will cause the libval defaults to be completely overwritten</para> 
 		<para>QUERY_DONT_VALIDATE == 1&lt;&lt;0
		causes the validator to disable validation for this query.</para>

		<para>QUERY_IGNORE_SKEW == 1&lt;&lt;1
		causes the validator to disable checking signature inception and expiration times on RRSIGs.</para>

		<para>QUERY_AC_DETAIL == 1&lt;&lt;2 
		causes the validator to copy the authentication chain details into the val_rc_answer member within the returned val_result_chain structure.
		</para>

		<para>
		QUERY_NO_DLV == 1&lt;&lt;3
		causes the validator to disable DLV processing for this query. This is only available if the libval(3) library has been compiled with DLV support.
		</para>
		<para>
		QUERY_NO_EDNS0_FALLBACK = 1&lt;&lt;4
		In querying various name servers, libsres will also attempt multiple EDNS0 sizes, ending with a query that has EDNS0 disabled (i.e. no CD bit set). This option causes libval to disable EDNS0 fallback for the query.
		</para>
		<para>
		QUERY_RECURSE == 1&lt;&lt;5
		forces libval to recursively answer the query by iteratively querying various name servers in the delegation hierarchy, instead of requesting this information from any caching name server that may be configured in dnsval.conf
		</para>
		<para>
		SKIP_RESOLVER == 1&lt;&lt;6
		forces libval to only look at its cache while trying to resolve a name.
		</para>
		<para>
		SKIP_CACHE == 1&lt;&lt;7
		forces libval to ignore cached data while trying to resolve a name.
		</para>
       <para><emphasis> Default value is 0(no changes)</emphasis></para>
 
       <example>
         <title>Set <varname>general_query_flags</varname> parameter</title>
 
         <programlisting format="linespecific">
 ...
 modparam("dnssec", "general_query_flags", 1) # QUERY_DONT_VALIDATE disable validation  
 modparam("dnssec", "general_query_flags", 10) # QUERY_IGNORE_SKEW | QUERY_NO_DLV
 ...
 </programlisting>
       </example>
     </section>
	 </section>
</chapter>

