tls_user.sgml

性能优秀的SIP Proxy

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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
			<revnumber>$Revision: 1.7 $</revnumber>
			<date>$Date: 2006/05/22 15:08:18 $</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>gen_rootCA.sh</quote> located in tls/tools directory
			you may create a local root CA. Please refere to the local README
			file for instructions about how to use the script.
			</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>gen_usercert.sh</quote> 
			script which is located in tls/tools directory. Please refere to 
			the local README file for instructions about how to use the script.
			</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>gen_usercert.sh</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