tls_user.sgml

性能优秀的SIP Proxy

			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:
-->