tlsops_user.sgml

来自「性能优秀的SIP Proxy」· SGML 代码 · 共 340 行

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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.1 $</revnumber>
		<date>$Date: 2006/05/22 15:12:23 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>
		This module implements TLS related functions to use in the routing script, and exports 
		pseudo variables with certificate and TLS parameters.
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; core</title>
		<para>
		&ser; must be compiled with TLS=1.
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>openssl (libssl)</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>


	<section>
	<title>Exported Parameters</title>
		<para>
		None!
		</para>
	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">is_peer_verified</function>
		</title>
		<para>
		Returns 1 if the message is received via TLS and the peer was verified 
		during TLS connection handshake, otherwise it returns -1
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>is_peer_verified</function> usage</title>
		<programlisting format="linespecific">
...
if (is_peer_verified()) {
        xlog("L_INFO","request from verified TLS peer\n");
} else {
        xlog("L_INFO","request not verified\n");
}
...
</programlisting>
		</example>
	</section>
	</section>


	<section>
	<title>Pseudo-Variables</title>
	<para>
	This module exports the follong pseudo-variables:
	</para>
	<para>
	Some pseudo variables are available for both, the peer'S certificate and 
	the local certificate. Further, some parameters can be read from the 
	<quote>Subject</quote> field or the <quote>Issuer</quote> field.
	</para>
	<itemizedlist>
		<listitem>
			<para>
			<emphasis>$tls_version</emphasis> - the TLS/SSL version which is 
			used on the TLS connection from which the message was received. 
			String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_description</emphasis> - the TLS/SSL description 
			of the TLS connection from which the message was received. String 
			type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_cipher_info</emphasis> - the TLS/SSL cipher which 
			is used on the TLS connection from which the message was received. 
			String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_cipher_bits</emphasis> - the number of cipher bits
			which are used on the TLS connection from which the message was 
			received. String and Integer type.
			</para>
		</listitem>

		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_version</emphasis> - the version of the 
			certificate. String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_serial</emphasis> - the serial number 
			of the certificate. String and Integer type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]</emphasis> - ASCII dump 
			of the fields in the issuer/subject section of the certificate. 
			String type.
			</para>
			<example>
				<title>Example of <varname>$tls_[peer|my]_[subject|issuer]</varname></title>
<programlisting format="linespecific">
/C=AT/ST=Vienna/L=Vienna/O=enum.at/CN=enum.at
</programlisting>
			</example>
		</listitem>
		
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_cn</emphasis> - 
			commonName in the issuer/subject section of the certificate. 
			String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_locality</emphasis> - 
			localityName in the issuer/subject section of the certificate. 
			String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_country</emphasis> - 
			countryName in the issuer/subject section of the certificate. 
			String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_state</emphasis> - 
			stateOrProvinceName in the issuer/subject section of the 
			certificate. String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_organization</emphasis> -
			organizationName in the issuer/subject section of the certificate. 
			String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_[subject|issuer]_unit</emphasis> - 
			organizationalUnitName in the issuer/subject section of the 
			certificate. String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_san_email</emphasis> - email address in 
			the <quote>subject alternative name</quote> extension. String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_san_hostname</emphasis> - hostname (DNS) 
			in the <quote>subject alternative name</quote> extension. String 
			type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_san_uri</emphasis> - URI in the 
			<quote>subject alternative name</quote> extension.
			String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_[peer|my]_san_ip</emphasis> - ip address in the 
			<quote>subject alternative name<quote> extension.
			String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_peer_verified</emphasis> - Returns 1 if the peer's 
			certificate was successful verified. Otherwise it returns 0.
			String and Integer type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_peer_revoked</emphasis> - Returns 1 if the peer's 
			certificate was revoked. Otherwise it returns 0.
			String and Integer type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_peer_expired</emphasis> - Returns 1 if the peer's 
			certificate is expired. Otherwise it returns 0.
			String and Integer type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_peer_selfsigned</emphasis> - Returns 1 if the 
			peer's certificate is selfsigned. Otherwise it returns 0.
			String and Integer type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_peer_notBefore</emphasis> - Returns the notBefore 
			validity date of the peer's certificate.
			String type.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>$tls_peer_notAfter</emphasis> - Returns the notAfter 
			validity date of the peer's certificate.
			String type.
			</para>
		</listitem>
	</itemizedlist>

	<para>If you want to debug TLS connections, put the following log 
	statements into your &ser;.cfg.
	This will dump all available TLS pseudo variables.
	</para>
	<example>
		<title>Example of TLS logging</title>
<programlisting format="linespecific">
xlog("L_INFO","==================== start TLS pseudo variables =================='\n");
xlog("L_INFO","$$tls_version                    = '$tls_version'\n");
xlog("L_INFO","$$tls_description                = '$tls_description'\n");
xlog("L_INFO","$$tls_cipher_info                = '$tls_cipher_info'\n");
xlog("L_INFO","$$tls_cipher_bits                = '$tls_cipher_bits'\n");
xlog("L_INFO","$$tls_peer_subject               = '$tls_peer_subject'\n");
xlog("L_INFO","$$tls_peer_issuer                = '$tls_peer_issuer'\n");
xlog("L_INFO","$$tls_my_subject                 = '$tls_my_subject'\n");
xlog("L_INFO","$$tls_my_issuer                  = '$tls_my_issuer'\n");
xlog("L_INFO","$$tls_peer_version               = '$tls_peer_version'\n");
xlog("L_INFO","$$tls_my_version                 = '$tls_my_version'\n");
xlog("L_INFO","$$tls_peer_serial                = '$tls_peer_serial'\n");
xlog("L_INFO","$$tls_my_serial                  = '$tls_my_serial'\n");
xlog("L_INFO","$$tls_peer_subject_cn            = '$tls_peer_subject_cn'\n");
xlog("L_INFO","$$tls_peer_issuer_cn             = '$tls_peer_issuer_cn'\n");
xlog("L_INFO","$$tls_my_subject_cn              = '$tls_my_subject_cn'\n");
xlog("L_INFO","$$tls_my_issuer_cn               = '$tls_my_issuer_cn'\n");
xlog("L_INFO","$$tls_peer_subject_locality      = '$tls_peer_subject_locality'\n");
xlog("L_INFO","$$tls_peer_issuer_locality       = '$tls_peer_issuer_locality'\n");
xlog("L_INFO","$$tls_my_subject_locality        = '$tls_my_subject_locality'\n");
xlog("L_INFO","$$tls_my_issuer_locality         = '$tls_my_issuer_locality'\n");
xlog("L_INFO","$$tls_peer_subject_country       = '$tls_peer_subject_country'\n");
xlog("L_INFO","$$tls_peer_issuer_country        = '$tls_peer_issuer_country'\n");
xlog("L_INFO","$$tls_my_subject_country         = '$tls_my_subject_country'\n");
xlog("L_INFO","$$tls_my_issuer_country          = '$tls_my_issuer_country'\n");
xlog("L_INFO","$$tls_peer_subject_state         = '$tls_peer_subject_state'\n");
xlog("L_INFO","$$tls_peer_issuer_state          = '$tls_peer_issuer_state'\n");
xlog("L_INFO","$$tls_my_subject_state           = '$tls_my_subject_state'\n");
xlog("L_INFO","$$tls_my_issuer_state            = '$tls_my_issuer_state'\n");
xlog("L_INFO","$$tls_peer_subject_organization  = '$tls_peer_subject_organization'\n");
xlog("L_INFO","$$tls_peer_issuer_organization   = '$tls_peer_issuer_organization'\n");
xlog("L_INFO","$$tls_my_subject_organization    = '$tls_my_subject_organization'\n");
xlog("L_INFO","$$tls_my_issuer_organization     = '$tls_my_issuer_organization'\n");
xlog("L_INFO","$$tls_peer_subject_unit          = '$tls_peer_subject_unit'\n");
xlog("L_INFO","$$tls_peer_issuer_unit           = '$tls_peer_issuer_unit'\n");
xlog("L_INFO","$$tls_my_subject_unit            = '$tls_my_subject_unit'\n");
xlog("L_INFO","$$tls_my_issuer_unit             = '$tls_my_issuer_unit'\n");
xlog("L_INFO","$$tls_peer_san_email             = '$tls_peer_san_email'\n");
xlog("L_INFO","$$tls_my_san_email               = '$tls_my_san_email'\n");
xlog("L_INFO","$$tls_peer_san_hostname          = '$tls_peer_san_hostname'\n");
xlog("L_INFO","$$tls_my_san_hostname            = '$tls_my_san_hostname'\n");
xlog("L_INFO","$$tls_peer_san_uri               = '$tls_peer_san_uri'\n");
xlog("L_INFO","$$tls_my_san_uri                 = '$tls_my_san_uri'\n");
xlog("L_INFO","$$tls_peer_san_ip                = '$tls_peer_san_ip'\n");
xlog("L_INFO","$$tls_my_san_ip                  = '$tls_my_san_ip'\n");
xlog("L_INFO","$$tls_peer_verified              = '$tls_peer_verified'\n");
xlog("L_INFO","$$tls_peer_revoked               = '$tls_peer_revoked'\n");
xlog("L_INFO","$$tls_peer_expired               = '$tls_peer_expired'\n");
xlog("L_INFO","$$tls_peer_selfsigned            = '$tls_peer_selfsigned'\n");
xlog("L_INFO","$$tls_peer_notBefore             = '$tls_peer_notBefore'\n");
xlog("L_INFO","$$tls_peer_notAfter              = '$tls_peer_notAfter'\n");
xlog("L_INFO","==================== end TLS pseudo variables =================='\n");	
</programlisting>
	</example>	

	</section>

</chapter>



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