auth_admin.xml

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

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

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This is a module that provides common functions that are needed by
		other authentication related modules. Also, it can perform 
		authentication taking username and password from pseudo-variables.
    </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>
		<title>Nonce Security</title>
    <para>
        The authentication mechanism offers protection against sniffing intrusion.
        The module generates and verifies the nonces so that they can be used only
        once (in an auth response). This is done
        by having a lifetime value and an index associated with every nonce.
        Using only an expiration value is not good enough because,as this value
        has to be of few tens of seconds, it is possible for someone to sniff
        on the network, get the credentials and then reuse them in another packet
        with which to register a different contact or make calls using the others's
        account. The index ensures that this will never be possible since it
		is generated as unique through the lifetime of the nonce.
	</para>
	<para>
		The default limit for the requests that can be authenticated is 100000 
		in 30 seconds.
		If you wish to adjust this you can decrease the lifetime of a nonce(
		how much time to wait for a reply to a challenge). However, be aware not to
		set it to a too smaller value.
    </para>
		<para>
		However this mechanism does not work for architectures using a cluster
		of servers that share the same dns name for load balancing. In this case
		you can disable the nonce reusability check by setting the module parameter
		'disable_nonce_check'.
	</para>
</section>

	<section id="dependencies" xreflabel="Dependencies">
		<title>Dependencies</title>
		<section>
			<title>&osips; Modules</title>
			<para>
			The module depends on the following modules (in the other words 
			the listed modules must be loaded before this module):
			<itemizedlist>
			<listitem>
				<para><emphasis>signaling</emphasis> -- Signaling module</para>
			</listitem>
			</itemizedlist>
			</para>
		</section>
		<section>
			<title>External Libraries or Applications</title>
			<para>
			The following libraries or applications must be installed 
			before running &osips; with this module loaded:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>none</emphasis></para>
				</listitem>
			</itemizedlist>
		</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section>
		<title><varname>secret</varname> (string)</title>
		<para>
		Secret phrase used to calculate the nonce value.
		</para>
		<para>
		The default is to use a random value generated from the random source in the core.
		</para>
		<para>
		If you use multiple servers in your installation, and would like to authenticate
		on the second server against the nonce generated at the first one its necessary
		to explicitly set the secret to the same value on all servers. 
		However, the use of a shared (and fixed) secret as nonce is insecure, much better
		is to stay with the default. Any clients should send the reply to the server that
		issued the request.
		</para>
		<example>
		<title>secret parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "secret", "johndoessecretphrase")
</programlisting>
		</example>
	</section>

	<section id="param_nonce_expire" xreflabel="nonce_expire">
		<title><varname>nonce_expire</varname> (integer)</title>
		<para>
		Nonces have limited lifetime. After a given period of time nonces 
		will be considered invalid. This is to protect replay attacks. 
		Credentials containing a stale nonce will be not authorized, but the 
		user agent will be challenged again. This time the challenge will 
		contain <varname>stale</varname> parameter which will indicate to the
		client that it doesn't have to disturb user by asking for username 
		and password, it can recalculate credentials using existing username 
		and password.
		</para>
		<para>
		The value is in seconds and default value is 30 seconds.
		</para>
		<example>
		<title>nonce_expire parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "nonce_expire", 15)   # Set nonce_expire to 15s
</programlisting>
		</example>
	</section>

	<section id="param_rpid_prefix" xreflabel="rpid_prefix">
		<title><varname>rpid_prefix</varname> (string)</title>
		<para>
		Prefix to be added to Remote-Party-ID header field just before 
		the URI returned from either radius or database.
		</para>
		<para>
		Default value is <quote></quote>.
		</para>
		<example>
		<title>rpid_prefix parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "rpid_prefix", "Whatever &lt;")
</programlisting>
		</example>
	</section>

	<section id="param_rpid_suffix" xreflabel="rpid_suffix">
		<title><varname>rpid_suffix</varname> (string)</title>
		<para>
		Suffix to be added to Remote-Party-ID header field after the URI 
		returned from either radius or database.
		</para>
		<para>
		Default value is 
			<quote>;party=calling;id-type=subscriber;screen=yes</quote>.
		</para>
		<example>
		<title>rpid_suffix parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "rpid_suffix", "@1.2.3.4>")
</programlisting>
		</example>
	</section>

	<section id="param_realm_prefix" xreflabel="realm_prefix">
		<title><varname>realm_prefix</varname> (string)</title>
		<para>
			Prefix to be automatically strip from realm. As an alternative to
			SRV records (not all SIP clients support SRV lookup), a subdomain
			of the master domain can be defined for SIP purposes (like 
			sip.mydomain.net pointing to same IP address as the SRV
			record for mydomain.net). By ignoring the realm_prefix 
			<quote>sip.</quote>, at authentication, sip.mydomain.net will be
			equivalent to mydomain.net .
		</para>
		<para>
		Default value is empty string.
		</para>
		<example>
		<title>realm_prefix parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "realm_prefix", "sip.")
</programlisting>
		</example>
	</section>

	<section id="param_rpid_avp" xreflabel="rpid_avp">
		<title><varname>rpid_avp</varname> (string)</title>
		<para>
			Full AVP specification for the AVP which 
			stores the RPID value. It used to transport the RPID value from
			authentication backend modules (auth_db or auth_radius) or from
			script to the auth function append_rpid_hf and is_rpid_user_e164.
		</para>
		<para>
			If defined to NULL string, all RPID functions will fail at 
			runtime.
		</para>
		<para>
		Default value is <quote>$avp(rpid)</quote>.
		</para>
		<example>
		<title>rpid_avp parameter example</title>
		<programlisting format="linespecific">
modparam("auth", "rpid_avp", "$avp(caller_rpid)")
		</programlisting>
		</example>
	</section>

	<section id="param_username_spec" xreflabel="username_spec">
		<title><varname>username_spec</varname> (string)</title>
		<para>
		This name of the pseudo-variable that will hold the username.
		</para>
		<para>
		Default value is <quote>NULL</quote>.
		</para>
		<example>
		<title><varname>username_spec</varname> parameter usage</title>
		<programlisting format="linespecific">
modparam("auth", "username_spec", "$var(username)")
</programlisting>
		</example>
	</section>

	<section id="param_password_spec" xreflabel="password_spec">
		<title><varname>password_spec</varname> (string)</title>
		<para>
		This name of the pseudo-variable that will hold the password.
		</para>
		<para>
		Default value is <quote>NULL</quote>.
		</para>
		<example>
		<title><varname>password_spec</varname> parameter usage</title>
		<programlisting format="linespecific">
modparam("auth", "password_spec", "$var(password)")
</programlisting>
		</example>
	</section>

	<section id="param_calculate_ha1" xreflabel="calculate_ha1">
		<title><varname>calculate_ha1</varname> (integer)</title>
		<para>
		This parameter tells the server whether it should expect plaintext
		passwords in the pseudo-variable or a pre-calculated HA1 string.
		</para>
		<para>
		If the parameter is set to 1 then the server will assume that the
		<quote>password_spec</quote> pseudo-variable contains plaintext passwords
		and it will calculate HA1 strings on the fly. If the parameter is set to 0
		then the server assumes the pseudo-variable contains the HA1 strings directly
		and will not calculate them.
		</para>
		<para>
		Default value of this parameter is 0.
		</para>
		<example>
		<title><varname>calculate_ha1</varname> parameter usage</title>
		<programlisting format="linespecific">
modparam("auth", "calculate_ha1", 1)
</programlisting>
		</example>
	</section>

	<section id="param_disable_nonce_check" xreflabel="disable_nonce_check">
		<title><varname>disable_nonce_check</varname> (int)</title>
		<para>
		By setting this parameter you disable the security mechanism 
		that protects against intrusion sniffing and does not allow
		nonces to be reused. But, because of the current implementation,
		having this enabled breaks auth for an architecture where load
		is balanced by having more servers with the same dns name.
		This parameter has to be set in this case.
		</para>
		<para>
		Default value is <quote>0</quote> (enabled).
		</para>
		<example>
		<title><varname>disable_nonce_check</varname> parameter usage</title>
		<programlisting format="linespecific">
modparam("auth", "disable_nonce_check", 1)
</programlisting>
		</example>
	</section>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_www_challenge" xreflabel="www_challenge()">
		<title>
			<function moreinfo="none">www_challenge(realm[, qop[, algorithms]])</function>
		</title>
		<para>
		The function challenges a user agent. It will generate one or
		more WWW-Authorize header fields containing a digest challenges, it will
		put the header field(s) into a response generated from the request the
		server is processing and will send the reply. Upon reception of such a
		reply the user agent should compute credentials and retry the
		request. For more information regarding digest authentication 
		see RFC2617, RFC3261 and RFC8760.
		</para>
		<para id="www_challenge_params" xreflabel="www_challenge() parameters meaning">
                    Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>realm</emphasis> (string) - Realm is an opaque string that 
			the user agent should present to the user so it can decide what 
			username and password to use. Usually this is domain of the host 
			the server is running on.
			</para>
			<para>
			If an empty string <quote></quote> is used then the server will 
			generate it from the request. In case of REGISTER request's To 
			header field, domain will be used (because this header field 
			represents a user being registered), for all other messages From 
			header field domain will be used.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>qop</emphasis> (string, optional) - Value of this
			parameter can be either <quote>auth</quote>, <quote>auth-int</quote>
			or both (separated by <emphasis>,</emphasis>). When this parameter is
			set the server will put a qop parameter in the challenge. It
			is recommended to use the qop parameter, however there are still some
			user agents that cannot handle qop properly so we made this optional.
			On the other hand there are still some user agents that cannot handle
			request without a qop parameter too.
			</para>
			<para>Enabling this parameter does not improve security at the moment,
			because the sequence number is not stored and therefore could not be
			checked. Actually there is no information kept by the module during
			the challenge and response requests.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>algorithms</emphasis> (string, optional) - Value of this
			parameter is a comma-separated list of digest algorithms to be offered for
			the UAC to use for authentication. Possible values are:</para>
			<itemizedlist>
				<listitem><quote>MD5</quote></listitem>
				<listitem><quote>MD5-sess</quote></listitem>
				<listitem><quote>SHA-256</quote></listitem>
				<listitem><quote>SHA-256-sess</quote></listitem>
				<listitem><quote>SHA-512-256</quote></listitem>
				<listitem><quote>SHA-512-256-sess</quote></listitem>
			</itemizedlist>
			<para>When the value is empty or not set, the only offered digest
			algorithm is <emphasis>MD5</emphasis>, to provide compatibility
			with pre-RFC8760 UAC implementations.</para>
			<para>Values can be listed in any order. The actual order of individual
			challenges in SIP response is defined by the RFC8760: from stronger
			algorithm to a weaker one.</para>
                </listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>

		<example>
		<title>www_challenge usage</title>
		<programlisting format="linespecific">
...
if (!www_authorize("siphub.net", "subscriber")) {
	www_challenge("siphub.net", "auth,auth-int", "MD5,SHA-512-256");
}
...
</programlisting>
		</example>
	</section>

	<section id="func_proxy_challenge" xreflabel="proxy_challenge()">
		<title>
			<function moreinfo="none">proxy_challenge(realm[, qop[, algorithms]])</function>
		</title>
		<para>
		The function challenges a user agent. It will generate a 
		Proxy-Authorize header field containing a digest challenge, it will 
		put the header field into a response generated from the request the 
		server is processing and will send the reply. Upon reception of such a 
		reply the user agent should compute credentials and retry the request.
		For more information regarding digest authentication see RFC2617,
		RFC3261 and RFC8760.
		</para>
		<para>See the paragraph on <xref linkend="www_challenge_params"/> for
		    the description of the parameters.</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title>proxy_challenge usage</title>
		<programlisting format="linespecific">
...
$var(secure_algorithms) = "sha-256,sha-512-256";
...
if (!proxy_authorize("", "subscriber")) {
...
	proxy_challenge("", "auth", $var(secure_algorithms));  # Realm will be autogenerated
							       # MD5 won't be allowed
}
...
</programlisting>
		</example>
	</section>
	<section id="func_consume_credentials" xreflabel="consume_credentials()">
		<title>
			<function moreinfo="none">consume_credentials()</function>
		</title>
		<para>
		This function removes previously authorized credentials from the 
		message being processed by the server. That means that the downstream 
		message will not contain credentials there were used by this server. 
		This ensures that the proxy will not reveal information about 
		credentials used to downstream elements and also the message will be 
		a little bit shorter. The function must be called after 
		<function moreinfo="none">www_authorize</function> or 
		<function moreinfo="none">proxy_authorize</function>. 
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title>consume_credentials example</title>
		<programlisting format="linespecific">
...
if (www_authorize("", "subscriber")) {
    consume_credentials();
}
...
</programlisting>
		</example>
	</section>
	<section id="func_is_rpid_user_e164" xreflabel="is_rpid_user_e164()">
		<title>
			<function moreinfo="none">is_rpid_user_e164()</function>
		</title>
		<para>
		The function checks if the SIP URI received from the database or 
		radius server and will potentially be used in Remote-Party-ID header 
		field contains an E164 number (+followed by up to 15 decimal digits) 
		in its user part.  Check fails, if no such SIP URI exists 
		(i.e. radius server or database didn't provide this information).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title>is_rpid_user_e164 usage</title>
		<programlisting format="linespecific">
...
if (is_rpid_user_e164()) {
    # do something here
}
...
</programlisting>
		</example>
	</section>
	<section id="func_append_rpid_hf_no_params" xreflabel="append_rpid_hf()">
		<title>
			<function moreinfo="none">append_rpid_hf()</function></title>
		<para>
		Appends to the message a Remote-Party-ID header that contains header
		'Remote-Party-ID: ' followed by the saved value of the SIP URI 
		received from the database or radius server followed by the value of 
		module parameter radius_rpid_suffix.  The function does nothing if 
		no saved SIP URI exists.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		BRANCH_ROUTE.
		</para>
		<example>
		<title>append_rpid_hf usage</title>
		<programlisting format="linespecific">
...
append_rpid_hf();  # Append Remote-Party-ID header field
...
</programlisting>
		</example>
	</section>
	<section id="func_append_rpid_hf" xreflabel="append_rpid_hf()">
		<title>
			<function moreinfo="none">append_rpid_hf(prefix, suffix)</function>
		</title>
		<para>
		This function is the same as 
		<xref linkend="func_append_rpid_hf_no_params"/>. The only difference is
		that it accepts two parameters--prefix and suffix to be added to 
		Remote-Party-ID header field. This function ignores rpid_prefix and 
		rpid_suffix parameters, instead of that allows to set them in every 
		call.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>prefix</emphasis> (string) - Prefix of the 
			Remote-Party-ID URI. The string will be added at the beginning of 
			body of the header field, just before the URI.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>suffix</emphasis> (string) - Suffix of the Remote-Party-ID 
			header field. The string will be appended at the end of the 
			header field. It can be used to set various URI parameters, 
			for example.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		BRANCH_ROUTE.
		</para>
		<example>
		<title>append_rpid_hf(prefix, suffix) usage</title>
		<programlisting format="linespecific">
...
# Append Remote-Party-ID header field
append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes");
...
</programlisting>
		</example>
	</section>
	<section id="func_pv_www_authorize" xreflabel="pv_www_authorize()">
		<title>
			<function moreinfo="none">pv_www_authorize(realm)</function>
		</title>
		<para>
		The function verifies credentials according to 
		<ulink url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>. If the 
		credentials are verified successfully then the function will succeed 
		and mark the credentials as authorized (marked credentials can be later 
		used by some other functions). If the function was unable to verify the 
		credentials for some reason then it will fail and the script should 
		call <function moreinfo="none">www_challenge</function> which will 
		challenge the user again.
		</para>
		<para>Negative codes may be interpreted as follows:</para>
		<itemizedlist>
			<listitem><para>
			<emphasis>-5 (generic error)</emphasis> - some generic error
			occurred and no reply was sent out;
			</para></listitem>
			<listitem><para>
			<emphasis>-4 (no credentials)</emphasis> - credentials were not
			found in request;
			</para></listitem>
			<listitem><para>
			<emphasis>-3 (stale nonce)</emphasis> - stale nonce;
			</para></listitem>
			<listitem><para>
			<emphasis>-2 (invalid password)</emphasis> - valid user, but 
			wrong password;
			</para></listitem>
			<listitem><para>
			<emphasis>-1 (invalid user)</emphasis> - authentication user does
			not exist.
			</para></listitem>
		</itemizedlist>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>realm</emphasis> (string) - Realm is an opaque string that 
			the user agent should present to the user so he can decide what 
			username and password to use. Usually this is domain of the host 
			the server is running on.
			</para>
			<para>
			If an empty string <quote></quote> is used then the server will 
			generate it from the request. In case of REGISTER requests To 
			header field domain will be used (because this header field 
			represents a user being registered), for all other messages From 
			header field domain will be used.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">pv_www_authorize</function>
		usage</title>
		<programlisting format="linespecific">
...
$var(username)="abc";
$var(password)="xyz";
if (!pv_www_authorize("opensips.org")) {
	www_challenge("opensips.org", "auth");
}
...
</programlisting>
		</example>
	</section>

	<section id="func_pv_proxy_authorize" xreflabel="pv_proxy_authorize()">
		<title>
			<function moreinfo="none">pv_proxy_authorize(realm)</function>
		</title>
		<para>
		The function verifies credentials according to 
		<ulink url="http://www.ietf.org/rfc/rfc2617.txt">RFC2617</ulink>. If 
		the credentials are verified successfully then the function will 
		succeed and mark the credentials as authorized (marked credentials can 
		be later used by some other functions). If the function was unable to 
		verify the credentials for some reason then it will fail and
		the script should call 
		<function moreinfo="none">proxy_challenge</function> which will
		challenge the user again. For more about the negative return codes,
		see the above function.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>realm</emphasis> (string) - Realm is an opaque string that 
			the user agent should present to the user so he can decide what 
			username and password to use. Usually this is domain of the host 
			the server is running on.
			</para>
			<para>
			If an empty string <quote></quote> is used then the server will 
			generate it from the request. From header field domain will be 
			used as realm.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title>pv_proxy_authorize usage</title>
		<programlisting format="linespecific">
...
$var(username)="abc";
$var(password)="xyz";
if (!pv_proxy_authorize("")) {
	proxy_challenge("", "auth");  # Realm will be autogenerated
}
...
</programlisting>
		</example>
	</section>

	</section>
</chapter>