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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
			<revnumber>$Revision: 1827 $</revnumber>
			<date>$Date: 2007-03-12 17:22:53 +0200 (Mon, 12 Mar 2007) $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>


	<section>
		<title>Overview</title>
		<para>
		TLS is an optional part of the &ser;'s core, not a module. TLS, as 
		defined in SIP RFC 3261, is a mandatory feature for proxies and can 
		be used to secure the SIP signalling on a hop-by-hop basis 
		(not end-to-end). TLS works on top of TCP. DTLS, or TLS over UDP is 
		already defined by IETF and may become available in the future.
		</para>
	</section>

	<section>
		<title>History</title>
		<para>
		The TLS support was originally developed by Peter Griffiths and posted
		as a patch on SER development mailing list. Thanks to Cesc 
		Santasusana, several problems were fixed and some improvements were 
		added.
		</para>
		<para>
		The TLS support was simultaneously added in both projects. In SER,
		the support was committed in a separate <quote>experimental</quote> 
		CVS tree, as patch to the main CVS tree. In OpenSER, the support was
		integrated directly into the CVS tree, as a built-in component, and is
		part of stable OpenSER since release >=1.0.0.
		</para>
	</section>

	<section>
		<title>Scenario</title>
		<para>
		By the increased number of providers the SIP world is continuously 
		growing. More users means more calls and more calls means a high 
		probability for a user to receive calls from totally unknown people 
		or, in the worst case, to receive unwanted calls. To prevent this, a 
		defense mechanism must be adopted by the SIP provider. Since only the 
		called user is fully able to classify a call as being unwanted, the 
		SIP server, based on all information regarding the call should notify
		the user about the desirability of the call. Information like the 
		caller domain, the received source or the incoming protocol can be 
		very useful for a SIP server to establish the nature of the call.
		</para>
		<para>
		As this information is quite limited, is very improbable for a server
		to be able detect the unwanted calls - there are many calls that it 
		cannot predict anything about its status (neutral calls). So, instead 
		on alerting the called user about unwanted calls, the server can 
		notify the user about calls that are considered trusted - calls for 
		which the server is 100% sure there are not unwanted.
		</para>
		<para>
		So, a trust concept must be defined for SIP servers. Which calls 
		are trusted and which are not? A call is trusted if the caller can 
		be identify as a trustable user - a user about we have reliable 
		information.
		</para>
		<para>
		Since all the user from its domain are authenticated (or should be), 
		a SIP server can consider all the calls generated by its user as 
		trusted. Now we have to extend the trust concept to the multi-domain
		level. A mutual agreement, between several domains, can establish a 
		trusting relationship. So, a domain (called A) will consider also as 
		trusted calls all the calls generated by user from a different domain 
		(called B) and vice-versa. But just an agreement is not enough; since 
		the authentication information is strictly limited to a domain 
		(a domain can authenticate only its own user, not the user from other 
		domains), there is still the problem of checking the authenticity of 
		the caller - he can impersonate (by a false FROM header) a user from 
		a domain that is trusted.
		</para>
		<para>
		The answer to this problem is TLS (Transport Layer Security). All 
		calls via domain A and domain B will be done via TLS. Authentication 
		in origin domain plus TLS transport between domains will make the 
		call 100% trusted for the target domain.
		</para>
		<para>
		For such a mechanism to work, the following requirements must be met:
		</para>
		<itemizedlist>
			<listitem>
			<para>
			all UA must have set as outbound proxy their home server.
			</para>
			</listitem>
			<listitem>
			<para>
			all SIP servers must authenticated all the calls generated by 
			their own users.
			</para>
			</listitem>
			<listitem>
			<para>all SIP servers must relay the calls generated be their 
			user to a trusted domain via TLS.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		Based on this, a server can classify as trusted a call for one of 
		its user only if the call is also generated by one of its users or 
		is the call is received from a trusted domain ( which is equivalent 
		with a call received via TLS). Untrusted call will be calls received 
		from users belonging to untrusted domains or from users from trusted 
		domains, but whose calls are not routed via their home server 
		(so, they are not authenticated by there home servers).
		</para>
		<para>
		Once the server is able to tell if the call is trusted or not, the 
		still open issue is about the mechanism used by server to notify the 
		called user about the nature of the incoming call.
		</para>
		<para>
		One way to do it is by remotely changing the ringing type of the 
		called user's phone. This can be done by inserting special header 
		into the INVITE request. Such feature is supported by now by several 
		hardphones like CISCO ATA, CISCO 7960 and SNOM. This phones can 
		change their ringing tone based on the present or content of the 
		"Alert-Info" SIP header as follows:
		</para>
		<itemizedlist>
			<listitem>
			<para><emphasis>CISCO ATA</emphasis> - it has 4 pre-defined 
			ringing types. The Alert-Info header must look like 
			<quote>Alert-info: Bellcore-drX EOH"</quote> where X can be 
			between 1 and 4. Note that 1 is the phone default ringing tone.
			</para>
			</listitem>
			<listitem>
			<para><emphasis>CISCO 7960</emphasis> - it has 2 pre-defined 
			ringing types and the possibility of uploading new ones. 
			The <quote>Alert-Info</quote> header must look like 
			<quote>Alert-info: X EOH</quote> where X can be whatever number.
			When this header is present, the phones will not change the 
			ringing tone, but the ringing pattern. Normally, the phone rings 
			like [ring.........ring..........ring] where [ring] is the 
			ringing tone; if the header is present, the ringing pattern will 
			be [ring.ring.........ring.ring........]. So, to be able to hear 
			some difference between the two patterns (and not only as length),
			its strongly recommended to have a highly asymmetric ringing type
			(as the pre-defined are not!!).
			</para>
			</listitem>
			<listitem>
			<para><emphasis>SNOM</emphasis> - The <quote>Alert-Info</quote>
			header must look like <quote>Alert-info: URL EOH"</quote> where 
			URL can be a HTTP URL (for example) from where the phone can 
			retrieve a ringing tone.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		A script example which implements this scenario can be found in 
		<xref linkend="tls-example">.
		</para>
	</section>

	<section>
		<title>Compiling TLS support</title>
		<para>
		To compile &ser; with the TLS support, the environment variable 
		TLS must be set. Note that this is required for all make commands 
		(and not only for compiling). To set the variable, there are 
		several ways to do it:
		</para>
		<itemizedlist>
			<listitem>
			<para>
			run all make commands like 
			<quote>TLS=1 make all|clean|install|etc</quote>
			</para>
			</listitem>
			<listitem>
			<para>
			before starting, export the TLS variable like 
			<quote>export TLS=1</quote> (in bash) and use the make 
			commands as usual. NOTE: the exported variable will be available
			only in current shell!
			</para>
			</listitem>
			<listitem>
			<para>
			comment (to disable) or uncomment (to enable) the 
			<quote>TLS=1</quote> line in the Makefile file; use the make 
			commands as usual without any limitations.
			</para>
			</listitem>
		</itemizedlist>
		<section>
			<title>Dependencies of external libraries</title>
			<para>
				&ser; TLS support requires the following packages:
				<itemizedlist>
					<listitem>
					<para><emphasis>openssl</emphasis> or 
						<emphasis>libssl</emphasis> >= 0.9.6
					</para>
					</listitem>
					<listitem>
					<para><emphasis>openssl-dev</emphasis> or 
						<emphasis>libssl-dev</emphasis>
					</para>
					</listitem>
				</itemizedlist>
			</para>
		</section>
	</section>

	<section>
		<title>TLS setup</title>
		<para>
		TLS provides for strong authentication mechanism, as well as 
		encryption following authentication. Of course, null encryption can 
		be used, as well as weak authentication mechanisms (for example, 
		anonymous, that is, no authentication).
		</para>
		<para>
		How does verification work? Verification is the process by which 
		the authentication data provided by the peers is checked. This data 
		consists usually of a peer certificate, plus a chain of trusted 
		certification authorities. If for whatever reason, either of the 
		peers thinks that the handshake is not valid, the ssl connection is 
		not established. The reasons could be many: untrusted server 
		certificate, too-weak algorithm, invalid client cert, no client 
		authentication, ...
		</para>
		<para>
		This paragraph describe how to generate all the needed keys and 
		certificates for establishing TLS connection with SER. The described
		TLS setup is based on the assumption that we run our own certificate 
		authority (CA) and we want to connect via TLS several &ser; servers 
		(SIP domain).
		</para>
		<warning><para>
		In this setup the private key is not encrypted. The client 
		and server keys must not be encrypted (or else &ser; will ask you for 
		a password on startup or will fail to load the certificates), but 
		you should use a password at least for your CA private key.
		</para></warning>

		<section>
			<title>Creating CA root certificate</title>
			<para>
			This part must be done only once, disregarding the number of 
			how many interconnected &ser;'s we want to have.
			</para>
			<para>
			Using <quote>openserctl tls rootCA</quote>, you may create a local 
			root CA.
			</para>
			<para>
			The script will produce the private key (which will be used to
			sign client/server certificates) and the self-signed certificate 
			authority.
			</para>
		</section>

		<section>
			<title>Creating a server/client certificate</title>
			<para>
			This part must be done for each OpenSER server interconnected 
			into your TLS enabled network: build a certificate request and
			sign it with a root CA (yourself or from third party).
			</para>
			<para>
			For this purpose you may use the 
			<quote>openserctl tls userCERT</quote>
			</para>
			<para>
			The output of the script will be a directory containing all needed
			TLS files for configuring the &ser; proxy (private key, signed 
			certificate and CA list)
			</para>
		</section>

		<section id="tls-set-ca">
			<title>Setting &ser; to use the certificate</title>
			<para>
			Append to the CA list file all the  CA root certificates 
			( this list must contain all CA root certificates to be 
			accepted by your server):
			</para>
			<para>
			If you use the <quote>openserctl tls userCERT</quote>, it will 
			create an one element CA list with the CA used to sign the 
			certificate.
			</para>
			<para>
			To add more CAs to your list, just do:
			</para>
			<itemizedlist>
				<listitem>
				<para>cat add_cacert.pem >> calist.pem</para>
				</listitem>
			</itemizedlist>
			<para>
			Now copy intended &ser; certificate, private key and ca list 
			file (basically the whole content of the openserX directory) to 
			your intended machine in some directory (which will be further 
			refer by path <quote>path</quote>).
			</para>
			<para>
			There are some &ser; TLS specific parameter that must be set up 
			in &ser; configuration file to use the certificate:
			</para>
			<itemizedlist>
				<listitem>
				<para>set up ser.cfg to use the certificate :</para>
				<para>tls_certificate=/path/cert.pem</para>
				</listitem>
				<listitem>
				<para>set up ser to use the private key :</para>
				<para>tls_private_key=/path/privkey.pem</para>
				</listitem>
				<listitem>
				<para>set up ser to use the CA list (optional - make sens 
				only if tls_verify is turned on)</para>
				<para>tls_ca_list=/path/calist.pem</para>
				</listitem>
			</itemizedlist>
		</section>

		<section id="tls-auth-model">
			<title>TLS &ser; authentication behavior</title>
			<para>
			The "tls_verify_server", "tls_verify_client" and "tls_require_client_certificate" 
			are &ser;-names for the OpenSSL defined flags:
			</para>
			<para>
			<itemizedlist>
				<listitem>
				<para>SSL_VERIFY_PEER is tls_verify_client/tls_verify_server</para>
				</listitem>
				<listitem>
				<para>SSL_VERIFY_FAIL_IF_NO_PEER_CERT is 
				tls_require_client_certificate (tls_require_client_certificate is only 
				used if tls_verify_client=1)</para>
				</listitem>
			</itemizedlist>
			<para>
			If your &ser; is acting as a server (incoming TLS connections), 
			it will always send its 
			server-side certificate to the client. If tls_verify_client is disabled
			(set to 0), your &ser; will not request the client a 
			client-certificate. This means that the client is not 
			authenticated.
			If tls_verify_client=1, your &ser; (the server) sends a 
			client-certificate request to the client. But the client is free 
			to not provide any. In this case,  tls_require_client_certificate comes
			into play:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>tls_require_client_certificate=0</emphasis> - the 
				verification process will succeed if the client does not 
				provide a certificate, or if it provides one, it verifies 
				correctly against the server's list of trusted certification 
				authorities.
				</para>
				</listitem>
				<listitem>
				<para><emphasis>tls_require_client_certificate=1</emphasis> - the 
				verification process will only succeed if the client 
				provides a certificate and this verifies correctly
				against the server's list of trusted CAs.
				</para>
				</listitem>
			</itemizedlist>
			<para>
			If your &ser; is acting as a client (outgoing TLS connections), it will
			always receive a certificate from the peer. If tls_verify_server is disabled
			(set to 0), your &ser; will not verifiy the certificate and allows TLS
			connections to servers which do not present a valid certificate.
			If tls_verify_server=1, your &ser; (the client) verifies the server
			certificate and will close the TLS connection if the server certificate is
			not valid.
			</para>
			<para>
			For more details see page man verify(1).
			</para>
		</section>

	</section>

	<section>
		<title>&ser; TLS configuration parameters</title>
		<para>
		All these parameters can be used from the openser.cfg file, 
		to configure the behavior of &ser;-TLS.
		</para>
		<section>
			<title><varname>disable_tls</varname>=integer</title>
			<para>
			Disables TLS (no server is created on the listen addresses, 
			no outgoing connections can be set up). A non 0 value means
			disable.
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value is 1 (TLS disabled).
			</emphasis></para>
			<example>
				<title>Set <varname>disable_tls</varname> variable</title>
				<programlisting format="linespecific">
...
disable_tls = 1
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>listen</varname>=interface</title>
			<para>
			Not specific to TLS. Allows to specify the protocol 
			(udp, tcp, tls), the IP address and the port where the 
			listening server will be.
			</para>
			<example>
				<title>Set <varname>listen</varname> variable</title>
				<programlisting format="linespecific">
...
listen = tls:1.2.3.4:5061
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_port_no</varname>=number</title>
			<para>
			Sets the default TLS listening port.
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value is 5061.
			</emphasis></para>
			<example>
				<title>Set <varname>tls_port_no</varname> variable</title>
				<programlisting format="linespecific">
...
tls_port_no = 5062
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_method</varname>=value</title>
			<para>
			Sets the TLS protocol method which can be: 
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>TLSv1</emphasis> - means &ser; will 
				accept only TLSv1 connections (rfc3261 conformant).
				</para>
				</listitem>
				<listitem>
				<para><emphasis>SSLv3</emphasis> - means &ser; will 
				accept only SSLv3 connections 
				</para>
				</listitem>
				<listitem>
				<para><emphasis>SSLv2</emphasis> - means &ser; will 
				accept only SSLv2 connections (almost all old clients
				support this).
				</para>
				</listitem>
				<listitem>
				<para><emphasis>SSLv23</emphasis> - means &ser; will 
				accept any of the above methods, but the initial SSL 
				hello must be v2 (in the initial hello all the supported 
				protocols are advertised enabling switching to a higher 
				and more secure version). The initial v2 hello means it 
				will not accept connections from SSLv3 or TLSv1 only 
				clients.
				</para>
				</listitem>
			</itemizedlist>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value is SSLv23.
			</emphasis></para>
			<warning><para>
			Best is to use SSLv23, for extended compatibility. Using any 
			of the other will restrict the version to just that one 
			version. In fact, SSLv2 is disabled in the source code; to 
			use it, you need to edit tls/tls_init.c
			</para></warning>
			<para>
			If you want RFC3261 conformance and all your clients support 
			TLSv1 (or you are planning to use encrypted "tunnels" only 
			between different &ser; proxies) use TLSv1. If you want to 
			support older clients use SSLv23 (in fact most of the 
			applications with SSL support use the SSLv23 method).
			</para>
			<example>
				<title>Set <varname>tls_method</varname> variable</title>
				<programlisting format="linespecific">
...
tls_method = TLSv1
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_certificate</varname>=file</title>
			<para>
			Public certificate file for &ser;. It will be used as 
			server-side certificate for incoming TLS connections, and as 
			a client-side certificate for outgoing TLS connections.
			</para>
			<para>
			See previous chapter <xref linkend="tls-set-ca"> for more
			information.
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value is "CFG_DIR/cert.pem".
			</emphasis></para>
			<example>
				<title>Set <varname>tls_certificate</varname> variable
					</title>
				<programlisting format="linespecific">
...
tls_certificate="/mycerts/certs/openser_server_cert.pem"
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_private_key</varname>=file</title>
			<para>
			Private key of the above certificate. I must be kept in a 
			safe place with tight permissions!
			</para>
			<para>
			See previous chapter <xref linkend="tls-set-ca"> for more 
			information.
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value is "CFG_DIR/cert.pem".
			</emphasis></para>
			<example>
				<title>Set <varname>tls_private_key</varname> variable
					</title>
				<programlisting format="linespecific">
...
tls_private_key="/mycerts/private/prik.pem"
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_ca_list</varname>=file</title>
			<para>
			List of trusted CAs. The file contains the certificates 
			accepted, one after the other. It MUST be a file, not 
			a folder.
			</para>
			<para>
			See previous chapter <xref linkend="tls-set-ca"> for more 
			information.
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value is "".
			</emphasis></para>
			<example>
				<title>Set <varname>tls_ca_list</varname> variable</title>
				<programlisting format="linespecific">
...
tls_ca_list="/mycerts/certs/ca_list.pem"
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_ciphers_list</varname>=string</title>
			<para>
			You can specify the list of algorithms for authentication 
			and encryption that you allow. To obtain a list of ciphers 
			and then choose, use the openssl application:
			</para>
			<itemizedlist>
				<listitem>
				<para>openssl ciphers 'ALL:eNULL:!LOW:!EXPORT'</para>
				</listitem>
			</itemizedlist>
			<warning><para>
			Do not use the NULL algorithms (no encryption) ... only for testing!!!
			</para></warning>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				It defaults to the OpenSSL default ciphers.
			</emphasis></para>
			<example>
				<title>Set <varname>tls_ciphers_list</varname> variable
					</title>
				<programlisting format="linespecific">
...
tls_ciphers_list="NULL"
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_verify_client</varname>=number and 
				<varname>tls_require_client_certificate</varname>=number</title>
			<para>
			Technically, tls_verify_client activates SSL_VERIFY_PEER in the 
			ssl_context. tls_require_client_certificate does the same with 
			SSL_VERIFY_FAIL_IF_NO_PEER_CERT, which is only possible if 
			SSL_VERIFY_PEER is also turned on.
			</para>
			<para>
			These two parameters are used for incoming TLS connections, where
			&ser; acts as server.
			</para>
			<para>
			See previous chapter <xref linkend="tls-auth-model"> for 
			more information.
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value for both is 1.
			</emphasis></para>
			<example>
				<title>Set <varname>tls_verify_client & tls_require_client_certificate
					</varname> variable</title>
				<programlisting format="linespecific">
...
# turn on the strictest and strongest authentication possible
tls_verify_client = 1
tls_require_client_certificate = 1
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_verify_server</varname>=number</title>
			<para>
			Technically, tls_verify_server activates SSL_VERIFY_PEER in the 
			ssl_context.
			</para>
			<para>
			This parameter is used for outgoing TLS connections, where
			&ser; acts as client.
			</para>
			<para>
			See previous chapter <xref linkend="tls-auth-model"> for 
			more information.
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value is 1.
			</emphasis></para>
			<example>
				<title>Set <varname>tls_verify_server </varname> variable</title>
				<programlisting format="linespecific">
...
# turn on the strictest and strongest authentication possible
tls_verify_server = 1
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_handshake_timeout</varname>=number and 
				<varname>tls_send_timeout</varname>=number</title>
			<para>
			Timeouts ... advanced users only
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value for both is 30.
			</emphasis></para>
			<example>
				<title>Set <varname>tls_handshake_timeout & 
					tls_send_timeout </varname> variable</title>
				<programlisting format="linespecific">
...
tls_handshake_timeout=119    # number of seconds
tls_send_timeout=121         # number of seconds
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_client_domain_avp</varname>=number</title>
			<para>
			This sets the interger AVP used for name based TLS server domains (please see
			tls_client_domain for more details). Setting the value to 0 disables name based
			TLS client domains.
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default value is 0.
			</emphasis></para>
			<example>
				<title>Set <varname>tls_client_domain_avp</varname> variable</title>
				<programlisting format="linespecific">
...
tls_client_domain_avp=400    # only integer named AVPs are supported
...
				</programlisting>
			</example>
		</section>

		<section>
			<title><varname>tls_server_domain, tls_client_domain</varname> section</title>
			<para>
			If you only run one domain, the main one is enough. If you 
			are running several TLS servers (that is, you have more than
			one listen=tls:ip:port entry in the config file), you can 
			specify some parameters for each of them separately (not all 
			the above).
			</para>
			<para>
			The wording 'TLS domain' means that this TLS connection will have different
			parameters than another TLS connection (from another TLS domain). Thus, TLS
			domains must are not directly related to different SIP domains, although they
			are often used in common. Depending on the direction of the TLS handshake, a 
			TLS domain is called 'client domain' (=outgouing TLS connection) or 'server domain'
			(= incoming TLS connection).
			</para>
			<para>
			For example, TLS domains can be used in virtual hosting scenarios with TLS.
			&ser; offers SIP service for multiple domains, e.g. atlanta.com and biloxi.com. Altough
			both domains will be hosted a single SIP proxy, the SIP proxy needs 2 certificates: One
			for atlanta.com and one for biloxi.com. For incoming TLS connections, the SIP proxy
			has to present the respective certificate during the TLS handshake. As the SIP proxy
			does not have received a SIP message yet (this is done after the TLS handshake), the SIP
			proxy can not retrieve the target domain (which will be usually retrieved from the domain in 
			the request URI). Thus, distinction for these domains must be done by using multiple sockets.
			The socket on which the TLS connection is received, identifies the respective domain. Thus 
			the SIP proxy is able to present the proper certificate.
			</para>
			<para>
			For outgoing TLS connections, the SIP proxy usually has to provide a client certificate. In 
			this scenario, socket based distinction is not possible as there is no dedicated outgoing socket.
			Thus, the certificate selection (selection of the proper TLS client domain) will be name based.
			For this purpose, TLS client domains can be associated with a name (e.g. the domain can be 
			used as name). If the SIP proxy establishes a new outgoing TLS connection, it checks 
			for the TLS client domain AVP (parameter tls_client_domain_avp). If this AVP is set (e.g.
			in &ser;.cfg), &openser; searches for a TLS client domain with the same name and uses
			the certificates defined in the respective tls_client_domain section.
			</para>
			<para>
			TLS client domains can also be socket based. If name based domains are disabled or no 
			name based AVP is found, &ser; searches for socket based TLS client domains. In this case	
			the mapping between to the TLS client domain is done based on the destination socket of the 
			underlying outgoing TCP connection.
			</para>
			<para>
			Note: If there is already an existing TLS connection to the remote target, it will be reused
			wether the TLS client domain AVP matches or not.
			</para>
			<para>
			NOTE: Make sure to also configure &ser; to listen on the specified 
			IP:port.
			</para>
			<para>
			NOTE: Except tls_handshake_timeout and tls_send_timeout all TLS parameters can be set
			per TLS domain. If a parameter is not explicit set, the default value will be used.
			</para>
			<para>
			NOTE: The tls_verify_client and tls_require_client_certificate options 
			can only be configured in TLS server domains,
			whereas the tls_verify_server option is only valid for configuring TLS client domains.
			</para>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<example>
				<title>Usage of <varname>tls_client_domain</varname> and
					<varname>tls_server_domain</varname> block
					</title>
				<programlisting format="linespecific">
...
listen=tls:IP_2:port2
listen=tls:IP_3:port4
...
# set the TLS client domain AVP
tls_client_domain_avp = 400
...
# socket based TLS server domains (for virtual SIPS hosting)
tls_server_domain[IP_2:port2] {
    #specify parameters for a domain in particular, otherwise, 
    #it will use the default values. 
    tls_certificate = "/certs/atlanta.com/cert.pem"
    tls_private_key = "/certs/atlanta.com/privkey.pem"
    tls_ca_list     = "/certs/wellknownCAs"
    tls_method=tlsv1
}
tls_server_domain[IP_3:port3] {
    tls_certificate = "/certs/biloxy.com/cert.pem"
    tls_private_key = "/certs/biloxy.com/privkey.pem"
    tls_ca_list     = "/certs/wellknownCAs"
    tls_method=tlsv1
    tls_verify_client = 1
    tls_require_client_certificate = 1
}
# name based TLS client domains (for virtual SIPS hosting)
tls_client_domain["atlanta.com"] {
    tls_certificate = "/certs/atlanta.com/cert.pem"
    tls_private_key = "/certs/atlanta.com/privkey.pem"
    tls_ca_list     = "/certs/wellknownCAs"
    tls_method=tlsv1
    tls_verify_server = 1
}
tls_client_domain["biloxi.com"] {
    tls_certificate = "/certs/biloxy.com/cert.pem"
    tls_private_key = "/certs/biloxy.com/privkey.pem"
    tls_ca_list     = "/certs/wellknownCAs"
    tls_method=tlsv1
    tls_verify_server = 0
}
# socket based TLS server domains (for TLS based downstream from GW provider)
tls_server_domain[IP_5:port5] {
    tls_certificate = "/certs/local/cert.pem"
    tls_private_key = "/certs/local/privkey.pem"
    tls_ca_list     = "/certs/GWproviderSelfSignedCA"
    tls_method=tlsv1
    # TLS needed only for encryption, access is restricted via
    # IP access lists
    tls_verify_client = 0
}
# socket based TLS client domains (for TLS based upstream to GW provider)
# GW IP: 1.2.3.4, GW port: 6677
tls_client_domain[1.2.3.4:6677] {
    tls_certificate = "/certs/local/cert.pem"
    tls_private_key = "/certs/local/privkey.pem"
    tls_ca_list     = "/certs/GWproviderSelfSignedCA"
    tls_method=tlsv1
    # TLS needed only for encryption, access is restricted via
    # IP access lists
    tls_verify_server = 0
}
...
route{
...
    # calls to other SIP domains
    # set the proper SSL context (certificate) for local hosted domains
    avp_write("$fd","$avp(i:400)");
    t_relay(); # uses NAPTR and SRV lookups
    exit;
...
    # calls to the PSTN GW
    t_relay("tls:1.2.3.4:6677");
    exit;
...
				</programlisting>
			</example>
		</section>
	</section>

	<section id="tls-example">
		<title>&ser; with TLS - script example</title>
		<para>
		IMPORTANT: The TLS support is based on TCP, and for allowing &ser; 
		to use TCP, it must be started in multi-process mode. So, there is 
		a must to have the "fork" parameter set to "yes":
		</para>
		<para>
		NOTE: Since the TLS engine is quite memory consuming, increase the 
		used memory by the run time parameter "-m" (see &ser; -h for more 
		details).
		</para>
		<itemizedlist>
			<listitem>
				<para>fork = yes</para>
			</listitem>
		</itemizedlist>

		<example>
			<title>Script with TLS support</title>
		<programlisting format="linespecific">
  # ----------- global configuration parameters ------------------------
  debug=3
  fork=yes
  log_stderror=no

  check_via=no
  dns=no
  rev_dns=no
  listen=_your_serv_IP_
  port=5060
  children=4
  fifo="/tmp/openser_fifo"

  #TLS specific settings
  tls_certificate="/path/openserX_cert.pem"
  tls_private_key="/path/privkey.pem"
  tls_ca_list="/path/calist.pem"
  tls_verify=on
  tls_require_client_certificate=on

  alias=_DNS_ALIAS_

  # ------------------ module loading ----------------------------------

  loadmodule "modules/sl/sl.so"
  loadmodule "modules/rr/rr.so"
  loadmodule "modules/maxfwd/maxfwd.so"
  loadmodule "modules/mysql/mysql.so"
  loadmodule "modules/usrloc/usrloc.so"
  loadmodule "modules/registrar/registrar.so"
  loadmodule "modules/tm/tm.so"
  loadmodule "modules/auth/auth.so"
  loadmodule "modules/auth_db/auth_db.so"
  loadmodule "modules/textops/textops.so"
  loadmodule "modules/uri_db/uri_db.so"

  # ----------------- setting module-specific parameters ---------------

  # -- auth_db params --
  modparam("auth_db", "db_url", "sql_url")
  modparam("auth_db", "password_column", "password")
  modparam("auth_db", "calculate_ha1", 1)

  # -- registrar params --
  # no multiple registrations
  modparam("registrar", "append_branches", 0)

  # -- rr params --
  # add value to ;lr param to make some broken UAs happy
  modparam("rr", "enable_full_lr", 1)

  # -------------------------  request routing logic -------------------

  # main routing logic

  route{

  # initial sanity checks
  if (!mf_process_maxfwd_header("10")) {
      sl_send_reply("483","Too Many Hops");
      break;
  };

  # if somene claims to belong to our domain in From,
  # challenge him (skip REGISTERs -- we will chalenge them later)
  if (from_uri==myself) {
      setflag(1);
      if ( (method=="INVITE" || method=="SUBSCRIBE" || method=="MESSAGE")
      &&  !(src_ip==myself) ) {
          if  (!(proxy_authorize( "domA.net", "subscriber" ))) {
              proxy_challenge("domA.net","0"/*no-qop*/);
              break;
          };
          if (!check_from()) {
              log("LOG: From Cheating attempt in INVITE\n");
              sl_send_reply("403",
                  "That is ugly -- use From=id next time (OB)");
              break;
          };
      }; # non-REGISTER from other domain
  } else if ( method=="INVITE" && uri!=myself ) {
      sl_send_reply("403", "No relaying");
      break;
  };

  /* ********   do record-route and loose-route ******* */
  if (!(method=="REGISTER"))
      record_route();

  if (loose_route()) {
      append_hf("P-hint: rr-enforced\r\n");
      route(1);
      break;
  };

  /* ******* check for requests targeted out of our domain ******* */
  if ( uri!=myself ) {
      append_hf("P-hint: OUTBOUND\r\n");
      if (uri=~".*@domB.net") {
          t_relay_to_tls("domB.net","5061");
      } else if (uri=~".*@domC.net") {
          t_relay_to_tls("domC.net","5061");
      } else {
          route(1);
      };
      break;
  };

  /* ******* divert to other domain according to prefixes ******* */
  if (method!="REGISTER") {
      if ( uri=~"sip:201") {
          strip(3);
          sethost("domB.net");
          t_relay_to_tls("domB.net","5061");
          break;
      } else if ( uri=~"sip:202" ) {
          strip(3);
          sethost("domC.net");
          t_relay_to_tls("domC.net","5061");
          break;
      };
  };

  /* ************ requests for our domain ********** */
  if (method=="REGISTER") {
      if (!www_authorize( "domA.net", "subscriber" )) {
          # challenge if none or invalid credentials
          www_challenge( "domA.net" /* realm */, 
              "0" /* no qop -- some phones can't deal with it */);
          break;
      };
      if (!check_to()) {
          log("LOG: To Cheating attempt\n");
          sl_send_reply("403", "That is ugly -- use To=id in REGISTERs");
          break;
      };
      # it is an authenticated request, update Contact database now
      if (!save("location")) {
          sl_reply_error();
      };
      break;
  };

  # native SIP destinations are handled using USRLOC DB
  if (!lookup("location")) {
      # handle user which was not found
      sl_send_reply("404", "Not Found");
      break;
  };

  # remove all present Alert-info headers
  remove_hf("Alert-Info");

  if (method=="INVITE" && (proto==tls || isflagset(1))) {
      append_hf("Alert-info: 1\r\n");                     # cisco 7960
      append_hf("Alert-info: Bellcore-dr4\r\n");          # cisco ATA
      append_hf("Alert-info: http://foo.bar/x.wav\r\n");  # snom
  };

  # do forwarding
  if (!t_relay()) {
      sl_reply_error();
  };

  #end of script
  }
		</programlisting>
	</section>



</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("tls.sgml" "Book" "chapter")
End:
-->
