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

              1.5.1. $tls_version
              1.5.2. $tls_description
              1.5.3. $tls_cipher_info
              1.5.4. $tls_cipher_bits
              1.5.5. $tls_[peer|my]_version
              1.5.6. $tls_[peer|my]_serial
              1.5.7. $tls_[peer|my]_[subject|issuer]
              1.5.8. $tls_[peer|my]_[subject|issuer]_cn
              1.5.9. $tls_[peer|my]_[subject|issuer]_locality
              1.5.10. $tls_[peer|my]_[subject|issuer]_country
              1.5.11. $tls_[peer|my]_[subject|issuer]_state
              1.5.12. $tls_[peer|my]_[subject|issuer]_organization
              1.5.13. $tls_[peer|my]_[subject|issuer]_unit
              1.5.14. $tls_[peer|my]_san_email
              1.5.15. $tls_[peer|my]_san_hostname
              1.5.16. $tls_[peer|my]_san_uri
              1.5.17. $tls_[peer|my]_san_ip
              1.5.18. $tls_peer_verified
              1.5.19. $tls_peer_revoked
              1.5.20. $tls_peer_expired
              1.5.21. $tls_peer_selfsigned
              1.5.22. $tls_peer_notBefore
              1.5.23. $tls_peer_notAfter

        1.6. Debug TLS connections

   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.
     __________________________________________________________

1.5.1. $tls_version

   $tls_version - the TLS/SSL version which is used on the TLS
   connection from which the message was received. String type.
     __________________________________________________________

1.5.2. $tls_description

   $tls_description - the TLS/SSL description of the TLS
   connection from which the message was received. String type.
     __________________________________________________________

1.5.3. $tls_cipher_info

   $tls_cipher_info - the TLS/SSL cipher which is used on the TLS
   connection from which the message was received. String type.
     __________________________________________________________

1.5.4. $tls_cipher_bits

   $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.
     __________________________________________________________

1.5.5. $tls_[peer|my]_version

   $tls_[peer|my]_version - the version of the certificate. String
   type.
     __________________________________________________________

1.5.6. $tls_[peer|my]_serial

   $tls_[peer|my]_serial - the serial number of the certificate.
   String and Integer type.
     __________________________________________________________

1.5.7. $tls_[peer|my]_[subject|issuer]

   $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
     __________________________________________________________

1.5.8. $tls_[peer|my]_[subject|issuer]_cn

   $tls_[peer|my]_[subject|issuer]_cn - commonName in the
   issuer/subject section of the certificate. String type.
     __________________________________________________________

1.5.9. $tls_[peer|my]_[subject|issuer]_locality

   $tls_[peer|my]_[subject|issuer]_locality - localityName in the
   issuer/subject section of the certificate. String type.
     __________________________________________________________

1.5.10. $tls_[peer|my]_[subject|issuer]_country

   $tls_[peer|my]_[subject|issuer]_country - countryName in the
   issuer/subject section of the certificate. String type.
     __________________________________________________________

1.5.11. $tls_[peer|my]_[subject|issuer]_state

   $tls_[peer|my]_[subject|issuer]_state - stateOrProvinceName in
   the issuer/subject section of the certificate. String type.
     __________________________________________________________

1.5.12. $tls_[peer|my]_[subject|issuer]_organization

   $tls_[peer|my]_[subject|issuer]_organization - organizationName
   in the issuer/subject section of the certificate. String type.
     __________________________________________________________

1.5.13. $tls_[peer|my]_[subject|issuer]_unit

   $tls_[peer|my]_[subject|issuer]_unit - organizationalUnitName
   in the issuer/subject section of the certificate. String type.
     __________________________________________________________

1.5.14. $tls_[peer|my]_san_email

   $tls_[peer|my]_san_email - email address in the "subject
   alternative name" extension. String type.
     __________________________________________________________

1.5.15. $tls_[peer|my]_san_hostname

   $tls_[peer|my]_san_hostname - hostname (DNS) in the "subject
   alternative name" extension. String type.
     __________________________________________________________

1.5.16. $tls_[peer|my]_san_uri

   $tls_[peer|my]_san_uri - URI in the "subject alternative name"
   extension. String type.
     __________________________________________________________

1.5.17. $tls_[peer|my]_san_ip

   $tls_[peer|my]_san_ip - ip address in the "subject alternative
   name' extension. String type. '"
     __________________________________________________________

1.5.18. $tls_peer_verified

   $tls_peer_verified - Returns 1 if the peer's certificate was
   successful verified. Otherwise it returns 0. String and Integer
   type.
     __________________________________________________________

1.5.19. $tls_peer_revoked

   $tls_peer_revoked - Returns 1 if the peer's certificate was
   revoked. Otherwise it returns 0. String and Integer type.
     __________________________________________________________

1.5.20. $tls_peer_expired

   $tls_peer_expired - Returns 1 if the peer's certificate is
   expired. Otherwise it returns 0. String and Integer type.
     __________________________________________________________

1.5.21. $tls_peer_selfsigned

   $tls_peer_selfsigned - Returns 1 if the peer's certificate is
   selfsigned. Otherwise it returns 0. String and Integer type.
     __________________________________________________________

1.5.22. $tls_peer_notBefore

   $tls_peer_notBefore - Returns the notBefore validity date of
   the peer's certificate. String type.
     __________________________________________________________

1.5.23. $tls_peer_notAfter

   $tls_peer_notAfter - Returns the notAfter validity date of the
   peer's certificate. String type.
     __________________________________________________________

1.6. Debug TLS connections

   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_loc
ality'\n");
xlog("L_INFO","$$tls_peer_issuer_locality       = '$tls_peer_issuer_loca
lity'\n");
xlog("L_INFO","$$tls_my_subject_locality        = '$tls_my_subject_local
ity'\n");
xlog("L_INFO","$$tls_my_issuer_locality         = '$tls_my_issuer_locali
ty'\n");
xlog("L_INFO","$$tls_peer_subject_country       = '$tls_peer_subject_cou
ntry'\n");
xlog("L_INFO","$$tls_peer_issuer_country        = '$tls_peer_issuer_coun
try'\n");
xlog("L_INFO","$$tls_my_subject_country         = '$tls_my_subject_count
ry'\n");
xlog("L_INFO","$$tls_my_issuer_country          = '$tls_my_issuer_countr
y'\n");
xlog("L_INFO","$$tls_peer_subject_state         = '$tls_peer_subject_sta
te'\n");
xlog("L_INFO","$$tls_peer_issuer_state          = '$tls_peer_issuer_stat
e'\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_org
anization'\n");
xlog("L_INFO","$$tls_peer_issuer_organization   = '$tls_peer_issuer_orga
nization'\n");
xlog("L_INFO","$$tls_my_subject_organization    = '$tls_my_subject_organ
ization'\n");
xlog("L_INFO","$$tls_my_issuer_organization     = '$tls_my_issuer_organi
zation'\n");
xlog("L_INFO","$$tls_peer_subject_unit          = '$tls_peer_subject_uni
t'\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_hostnam
e'\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://www.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://lists.openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://lists.openser.org/cgi-bin/mailman/listinfo/devel

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

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

   3.4. How can I report a bug?

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