uac_auth_admin.xml

<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>


	<section id="overview" xreflabel="Overview">
		<title>Overview</title>
		<para>
		UAC AUTH (User Agent Client Authentication) module provides a
		common API for building authentication headers.
		</para>
		<para>
		It also provides a common set of authentication credetials to
		be used by other modules.
		</para>
		<para>
		Note that authentication provided by this module supports both
		qop "auth" and qop "auth-int" but if both values are presented
		by the server, "auth" will be prefered.
		</para>

	<section id="rfc-8760-support" xreflabel="RFC 8760 Support">
	        <title>RFC 8760 Support (Strenghtened Authentication)</title>
	        <para>
			Starting with OpenSIPS 3.2, the <ulink url='auth'>auth</ulink>,
			<ulink url='auth_db'>auth_db</ulink> and
			<ulink url='uac_auth'>uac_auth</ulink>
			modules include support for two new digest authentication algorithms
			("SHA-256" and "SHA-512-256"), according to the
	        <ulink url="https://datatracker.ietf.org/doc/html/rfc8760">RFC 8760</ulink>
	        specs.
	        </para>
	</section>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
		<title>Dependencies</title>
		<section>
			<title>&osips; Modules</title>
			<itemizedlist>
			<listitem>
			<para><emphasis>None.</emphasis></para>
			</listitem>
			</itemizedlist>
		</section>
		<section>
			<title>External Libraries or Applications</title>
			<para>
				The following libraries or applications must be installed 
				before running &osips; with this module loaded:
				<itemizedlist>
				<listitem>
				<para>
					<emphasis>None</emphasis>
				</para>
				</listitem>
				</itemizedlist>
			</para>
		</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
	
		<section id="param_credential" xreflabel="credential">
			<title><varname>credential</varname> (string)</title>
			<para>
			Contains a multiple definition of credentials used to perform
			authentication.
			</para>
			<para>
			NOTE that the password can be provided as a plain text password or
			as a precalculated HA1 as a hexa (lower case) string
			(of 32 chars) prefixed with "0x" (so a total of 34 chars).
			</para>
			<para>
				<emphasis>
					This parameter is required if UAC authentication is used.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>credential</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_auth","credential","username:domain:password")
modparam("uac_auth","credential","username:domain:0xc17ba8157756f263d07e158504204629")
...
				</programlisting>
			</example>
		</section>

		<section id="param_auth_realm_avp" xreflabel="auth_realm_avp">
			<title><varname>auth_realm_avp</varname> (string)</title>
			<para>
			The definition of an AVP that might contain the realm to be used
			to perform authentication.
			</para>
			<para><emphasis>
				If you define it, you also need to define 
				<quote>auth_username_avp</quote> 
				(<xref linkend="param_auth_username_avp"/>) and 
				<quote>auth_password_avp</quote> 
				(<xref linkend="param_auth_password_avp"/>).
			</emphasis></para>
			<example>
				<title>Set <varname>auth_realm_avp</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_auth","auth_realm_avp","$avp(10)")
...
				</programlisting>
			</example>
		</section>

		<section id="param_auth_username_avp" xreflabel="auth_username_avp">
			<title><varname>auth_username_avp</varname> (string)</title>
			<para>
			The definition of an AVP that might contain the username to be used
			to perform authentication.
			</para>
			<para><emphasis>
				If you define it, you also need to define 
				<quote>auth_realm_avp</quote> 
				(<xref linkend="param_auth_realm_avp"/>) and 
				<quote>auth_password_avp</quote> 
				(<xref linkend="param_auth_password_avp"/>).
			</emphasis></para>
			<example>
				<title>Set <varname>auth_username_avp</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_auth","auth_username_avp","$avp(11)")
...
				</programlisting>
			</example>
		</section>

		<section id="param_auth_password_avp" xreflabel="auth_password_avp">
			<title><varname>auth_password_avp</varname> (string)</title>
			<para>
			The definition of an AVP that might contain the password to be used
			to perform authentication. The password can be provided as a plain
			text password or as a precalculated HA1 as a hexa (lower case) string
			(of 32 chars) prefixed with "0x" (so a total of 34 chars) (for example 
			"0xc17ba8157756f263d07e158504204629")
			</para>
			<para><emphasis>
				If you define it, you also need to define 
				<quote>auth_realm_avp</quote> 
				(<xref linkend="param_auth_realm_avp"/>) and 
				<quote>auth_username_avp</quote> 
				(<xref linkend="param_auth_username_avp"/>).
			</emphasis></para>
			<example>
				<title>Set <varname>auth_password_avp</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_auth","auth_password_avp","$avp(12)")
...
				</programlisting>
			</example>
		</section>

	</section>

</chapter>