
tlsops Module

Klaus Darilion

   enum.at

Edited by

Klaus Darilion

   Copyright  2006 enum.at
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSER core
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters
        1.4. Exported Functions

              1.4.1. is_peer_verified

        1.5. Pseudo-Variables

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. is_peer_verified usage
   1-2. Example of $tls_[peer|my]_[subject|issuer]
   1-3. Example of TLS logging
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   This module implements TLS related functions to use in the
   routing script, and exports pseudo variables with certificate
   and TLS parameters.
     _________________________________________________________

1.2. Dependencies

1.2.1. OpenSER core

   OpenSER must be compiled with TLS=1.
     _________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * openssl (libssl).
     _________________________________________________________

1.3. Exported Parameters

   None!
     _________________________________________________________

1.4. Exported Functions

1.4.1. is_peer_verified

   Returns 1 if the message is received via TLS and the peer was
   verified during TLS connection handshake, otherwise it returns
   -1

   This function can be used from REQUEST_ROUTE.

   Example 1-1. is_peer_verified usage
...
if (is_peer_verified()) {
        xlog("L_INFO","request from verified TLS peer\n");
} else {
        xlog("L_INFO","request not verified\n");
}
...
     _________________________________________________________

1.5. Pseudo-Variables

   This module exports the follong pseudo-variables:

   Some pseudo variables are available for both, the peer'S
   certificate and the local certificate. Further, some
   parameters can be read from the "Subject" field or the
   "Issuer" field.

     * $tls_version - the TLS/SSL version which is used on the
       TLS connection from which the message was received. String
       type.
     * $tls_description - the TLS/SSL description of the TLS
       connection from which the message was received. String
       type.
     * $tls_cipher_info - the TLS/SSL cipher which is used on the
       TLS connection from which the message was received. String
       type.
     * $tls_cipher_bits - the number of cipher bits which are
       used on the TLS connection from which the message was
       received. String and Integer type.
     * $tls_[peer|my]_version - the version of the certificate.
       String type.
     * $tls_[peer|my]_serial - the serial number of the
       certificate. String and Integer type.
     * $tls_[peer|my]_[subject|issuer] - ASCII dump of the fields
       in the issuer/subject section of the certificate. String
       type.
       Example 1-2. Example of $tls_[peer|my]_[subject|issuer]
/C=AT/ST=Vienna/L=Vienna/O=enum.at/CN=enum.at
     * $tls_[peer|my]_[subject|issuer]_cn - commonName in the
       issuer/subject section of the certificate. String type.
     * $tls_[peer|my]_[subject|issuer]_locality - localityName in
       the issuer/subject section of the certificate. String
       type.
     * $tls_[peer|my]_[subject|issuer]_country - countryName in
       the issuer/subject section of the certificate. String
       type.
     * $tls_[peer|my]_[subject|issuer]_state -
       stateOrProvinceName in the issuer/subject section of the
       certificate. String type.
     * $tls_[peer|my]_[subject|issuer]_organization -
       organizationName in the issuer/subject section of the
       certificate. String type.
     * $tls_[peer|my]_[subject|issuer]_unit -
       organizationalUnitName in the issuer/subject section of
       the certificate. String type.
     * $tls_[peer|my]_san_email - email address in the "subject
       alternative name" extension. String type.
     * $tls_[peer|my]_san_hostname - hostname (DNS) in the
       "subject alternative name" extension. String type.
     * $tls_[peer|my]_san_uri - URI in the "subject alternative
       name" extension. String type.
     * $tls_[peer|my]_san_ip - ip address in the "subject
       alternative name' extension. String type. '"
     * $tls_peer_verified - Returns 1 if the peer's certificate
       was successful verified. Otherwise it returns 0. String
       and Integer type.
     * $tls_peer_revoked - Returns 1 if the peer's certificate
       was revoked. Otherwise it returns 0. String and Integer
       type.
     * $tls_peer_expired - Returns 1 if the peer's certificate is
       expired. Otherwise it returns 0. String and Integer type.
     * $tls_peer_selfsigned - Returns 1 if the peer's certificate
       is selfsigned. Otherwise it returns 0. String and Integer
       type.
     * $tls_peer_notBefore - Returns the notBefore validity date
       of the peer's certificate. String type.
     * $tls_peer_notAfter - Returns the notAfter validity date of
       the peer's certificate. String type.

   If you want to debug TLS connections, put the following log
   statements into your OpenSER.cfg. This will dump all available
   TLS pseudo variables.

   Example 1-3. Example of TLS logging
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_lo
cality'\n");
xlog("L_INFO","$$tls_peer_issuer_locality       = '$tls_peer_issuer_loc
ality'\n");
xlog("L_INFO","$$tls_my_subject_locality        = '$tls_my_subject_loca
lity'\n");
xlog("L_INFO","$$tls_my_issuer_locality         = '$tls_my_issuer_local
ity'\n");
xlog("L_INFO","$$tls_peer_subject_country       = '$tls_peer_subject_co
untry'\n");
xlog("L_INFO","$$tls_peer_issuer_country        = '$tls_peer_issuer_cou
ntry'\n");
xlog("L_INFO","$$tls_my_subject_country         = '$tls_my_subject_coun
try'\n");
xlog("L_INFO","$$tls_my_issuer_country          = '$tls_my_issuer_count
ry'\n");
xlog("L_INFO","$$tls_peer_subject_state         = '$tls_peer_subject_st
ate'\n");
xlog("L_INFO","$$tls_peer_issuer_state          = '$tls_peer_issuer_sta
te'\n");
xlog("L_INFO","$$tls_my_subject_state           = '$tls_my_subject_stat
e'\n");
xlog("L_INFO","$$tls_my_issuer_state            = '$tls_my_issuer_state
'\n");
xlog("L_INFO","$$tls_peer_subject_organization  = '$tls_peer_subject_or
ganization'\n");
xlog("L_INFO","$$tls_peer_issuer_organization   = '$tls_peer_issuer_org
anization'\n");
xlog("L_INFO","$$tls_my_subject_organization    = '$tls_my_subject_orga
nization'\n");
xlog("L_INFO","$$tls_my_issuer_organization     = '$tls_my_issuer_organ
ization'\n");
xlog("L_INFO","$$tls_peer_subject_unit          = '$tls_peer_subject_un
it'\n");
xlog("L_INFO","$$tls_peer_issuer_unit           = '$tls_peer_issuer_uni
t'\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_hostna
me'\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");
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. What is the difference between the TLS directory and the
          TLSOPS module directory? 

   3.2. Where can I find more about OpenSER?
   3.3. Where can I post a question about this module?
   3.4. How can I report a bug?

   3.1. What is the difference between the TLS directory and the
   TLSOPS module directory?

   The code in the TLS directory implements the TLS transport
   layer. The TLSOPS module implements TLS related functions
   which can be used in the routing script.

   3.2. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.3. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.4. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.
