tls_user.sgml

性能优秀的SIP Proxy

				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_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 0 (TLS enabled).
			</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 ... only for testing!!!
			</para></warning>
			<para>
			It's usable only if TLS support was compiled.
			</para>
			<para><emphasis>
				Default ciphers chosen by OpenSSL.
			</emphasis></para>
			<example>
				<title>Set <varname>tls_ciphers_list</varname> variable
					</title>
				<programlisting format="linespecific">
...
tls_ciphers_list="NULL-SHA:NULL-MD5:AES256-SHA:AES128-SHA"
...
				</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 0.
			</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 0.
			</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