You are here: start » ref_manual » transport » tls

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

ref_manual:transport:tls [2009/05/05 00:37]
janakj created 		ref_manual:transport:tls [2009/05/05 01:11] (current)
janakj
Line 1: Line 1:
 ====== TLS/SSL Support ====== ====== TLS/SSL Support ======
 +//(text from an email announcement by Jan)//
  
 +There is a new module called TLS in the cvs repository. The module attempts
 +to merge the TLS code from experimental cvs module (maintained by Cesc) and
 +Andrei's implementation, to get the best of both. Furthermore the module
 +contains some new functions for script based certificate verification.
 +
 +The TLS module is much more stable than the original implementation. The
 +original (experimental) code works only when there are no simultaneous TLS
 +connections/attempts. The original code would either crash or block SER in
 +seconds under heavy load so it is not really suitable for production use.
 +
 +The code in TLS module is much more stable, it contains several fixes
 +(icluding fix of openssl) and does not seem to crash even under load
 +Unfortunately we discovered a problem during testing of TLS code which can
 +lead to SER being blocked for the duration of tls_send_timeout interval. After
 +that time it would recover. Andrei can probably elaborate more on this issue,
 +but as far as I know there is no easy wayto fix it.
 +
 +In conclusion the TLS code in the tls module is more stable than the original
 +code from experimental but is not yet ready for production deployments (unless
 +you can risk SER being blocked for some time).  TLS select functions
 +
 +The current HEAD SER version contains a mechanism which we internaly call the
 +"select" framework. The select framework makes it possible to register
 +functions from modules which can extract pieces of information from the SIP
 +message, transports or IP datagrams. Select functions are denoted by @
 +character in the configuration file. The name of the select consists of tokens
 +(optionally followed by a number in square brackes) and denoted by ., for
 +example:
 +
 +  @contact[2].uri.params.transport
 +
 +Would return the value of transport URI parameter from the second Contact URI
 +in the SIP message.
 +
 +TLS module makes use of this mechanism and contains several functions that can
 +be used to retrieve TLS related information in the configuration
 +script. Currently implemented are the following functions:
 +
 +  * ''@tls'': String description of the TLS layer
 +  * ''@tls.version'': Protocol version being used
 +  * ''@tls.desc'': The same as @tls
 +  * ''@tls.cipher'': Cipher name being used
 +  * ''@tls.cipher.bits'': Number of bits used for encryption
 +  * ''@tls.peer'': Peer certificate subject common name
 +  * ''@tls.me'': Local certificate subject common name
 +  * ''@tls.peer.subject'': same as @tls.peer
 +  * ''@tls.peer.issuer'': Peer certificate issuer common name
 +  * ''@tls.peer.verified'': True if peer cert has been verified
 +  * ''@tls.{peer,my}.version'': Peer/local certificate version
 +  * ''@tls.{peer,my}.sn'': Peer/local certificate number
 +  * ''@tls.{peer,my}.not_before'': Certificate validity start
 +  * ''@tls.{peer,my}.not_after'': Certificate validity end
 +  * ''@tls.{peer,my}.email'': Email address from subj alternative name
 +  * ''@tls.{peer,my}.host'': DNS anme from subj alternative name
 +  * ''@tls.{peer,my}.uri'': URI from subj alternative name
 +  * ''@tls.{peer,my}.ip'': IP address from subj alternative name
 +  * ''@tls.{peer,my}.{subj,issuer}.locality'': locality component
 +  * ''@tls.{peer,my}.{subj,issuer}.country'': Issuer/subject country
 +  * ''@tls.{peer,my}.{subj,issuer}.state'': Issuer/subject state
 +  * ''@tls.{peer,my}.{subj,issuer}.organization'': Subject/issuer organization
 +  * ''@tls.{peer,my}.{subj,issuer}.unit'': Subject/issuer organizational unit
 +  * ''@tls'': String description of the TLS connection currently being used, for example ''AES256-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(256) Mac=SHA1''
 +
 +=== @tls.version ===
 +The version of TLS procotol being used for the actual connection
 +
 +Example:
 +   if (@tls.version == "SSLv2") ...
 +
 +=== @tls.desc ===
 +Same as @tls
 +
 +=== @tls.cipher ===
 +Name of the cipher being used in the current TLS connection.
 +
 +Example:
 +   'AES256-SHA'
 +
 +=== @tls.cipher.bits ===
 +Number of encryption bits used by the current TLS connection.
 +
 +=== @tls.peer ===
 +Common name of the peer certificate subject.
 +
 +Example:
 +   if (@tls.peer == "Bob") ...
 +
 +=== @tls.me ===
 +The local (server for inboud, client for outbound TLS connections) certificate subject Common Name
 +
 +=== @tls.peer.subject ===
 +same as @tls.peer (just alias for completeness)
 +
 +=== @tls.peer.issuer ===
 +The common name of peer certificate issuer.
 +
 +=== @tls.peer.verified ===
 +True if peer provided a certificate and the certificate has been
 +successfuly verified. False if there was no peer certificate or it
 +has not been verified.
 +
 +=== @tls.{peer,my}.version ===
 +Peer/local certificate version
 +
 +=== @tls.{peer,my}.sn ===
 +Peer/local certificate serial number assigned by the certificate authority
 +
 +=== @tls.{peer,my}.not_before ===
 +Certificate validity start
 +
 +Format: 'Jun 17 15:03:20 2005 GMT'
 +
 +=== @tls.{peer,my}.not_after ===
 +Certificate validity end (format is same as in @tls.peer.not_before)
 +
 +=== @tls.{peer,my}.email ===
 + Email address component from the subject alternative name.
 +
 +=== @tls.{peer,my}.host ===
 +DNS name from the certificate subject alternative name.
 +
 +=== @tls.{peer,my}.uri ===
 +URI from certificate subject alternative name.
 +
 +=== @tls.{peer,my}.ip ===
 +IP address from certificate subject alternative name.
 +
 +=== @tls.{peer,my}.{subj,issuer}.locality ===
 +Certificate subject/issuer locality.
 +
 +=== @tls.{peer,my}.{subj,issuer}.country ===
 +Certificate subject/issuer country name.
 +
 +=== @tls.{peer,my}.{subj,issuer}.state ===
 +Certificate subject/issuer state code.
 +
 +=== @tls.{peer,my}.{subj,issuer}.organization ===
 +Certificate subject/issuer organization name.
 +
 +=== @tls.{peer,my}.{subj,issuer}.unit ===
 +Certificate subject/issuer organizational unit.
 +
 +===== SSL Certificate Authentication =====
 +The functions can be used to implement SSL certificate based authentication in
 +the configuration script:
 +
 +  if (proto == TLS && @tls.peer != "Bob") {
 +       sl_reply("403", "Forbidden");
 +       break;
 +  }
 +
 +This will reject any request received through TLS unless the client provides a
 +client certificate which has subject common name set to "Bob".
 +
 +Select @tls is useful for storing information about the TLS connection (the
 +string can be stored in accounting table, for example, appended to the
 +outgoing message as a header, and so on).  Multi-domain configuration
 +
 +The original (experimental) code contained the support for multi-domain
 +configuration. This mechanism was extended a little bit in the tls module. In
 +addition to server based TLS domains there is also preliminary support for TLS
 +client domains. TLS client domains are used when SER attempts to connect to a
 +remote party using TLS. This makes it possible to configure different TLS
 +client certificates for different destinations.
 +
 +In addition to that almost all TLS parameters can be now set on per-domain
 +basis. This includes: - Certificate file - Private key file - Enable/disable
 +certificate verification - Certificate verification depth - CA file -
 +Request/do not request certificate from peer - Cipher list - TLS method
 +
 +TLS domains are identified using IP and port, this is the destination IP and
 +port of the TLS connections, in server TLS domains this must be one of the IP
 +and port configured through listen directives. In TLS client domains this is
 +the IP and port of the remote peer.
 +
 +There is always one default server domain and one default client domain. These
 +are used when no matching server/client domain can be found for IP/port pair.
 +
 +TLS domains are configured through modparams, most tls modparams accept the
 +parameter value with the following syntax: <ip>:<port>=<value.
 +
 +If no IP and port has been specified then the parameters of the default domain are set:
 +
 +  modparam("tls", "method", "1.2.3.4:5090=SSLv23")
 +  modparam("tls", "verify_certificate", "1")
 +  modparam("tls", "require_certificate", "0")
 +  modparam("tls", "private_key", "/usr/local/etc/seri/alice_prik.key")
 +  modparam("tls", "private_key", "1.2.3.4:5090=key.pem")
 +  modparam("tls", "ca_list", "/usr/local/etc/ser/rootca.cert.pem")
 +  modparam("tls", "certificate", "/usr/local/etc/ser/alice_cert.crt")
 +  modparam("tls", "handshake_timeout", 120)
 +  modparam("tls", "send_timeout", 120)
 +  modparam("tls", "tls_log", 2)
 +
 +This configuration is somewhat suboptimal and may change yet. Currently there
 +is no possibility to configure TLS client domains (it will be added soon).
 +Example configuration
 +
 +Here is a configuration example which demonstrates a couple of interesting
 +things that can be done with the TLS module, XMLRPC management interface and
 +new serctli tools. This configuration file snippet makes it possible to run
 +serctl remotely. It uses the XMLRPC procotol which is encrypted using
 +TLS. Futhermore TLS certificate authentication is used so only people having a
 +correct client certificate are allowed to execute the kill command (this
 +command will stop ser):
 +
 +<code>
 +loadmodule "./modules/tls/tls.so"
 +loadmodule "./modules/sl/sl.so"
 +loadmodule "./modules/xmlrpc/xmlrpc.so"
 +
 +listen=tls:1.2.3.4:5061
 +
 +modparam("tls", "method", "SSLv23")
 +modparam("tls", "verify_certificate", "1")
 +modparam("tls", "require_certificate", "0")
 +modparam("tls", "private_key", "/usr/local/etc/ser/alice_prik.key")
 +modparam("tls", "ca_list", "/usr/local/etc/ser/rootca.cert.pem")
 +modparam("tls", "certificate", "/usr/local/etc/ser/alice_cert.crt")
 +
 +route {
 +    if (proto == TLS && (method == "POST" || method == "GET")) {
 +        create_via(); # XMLRPC requests do not contain via, create it
 +
 +        if (!@tls.peer.verified) {
 +            # Client did not provide certificate or it is not valid
 +     xmlrpc_reply("400", "Unauthorized");
 +     break;
 +        }
 +
 +        if (@xmlrpc.method == "core.kill") {
 +             # Make sure the client has the permission to execute the command
 +             if (@tls.peer != "SER-Killer") {
 +          xmlrpc_reply("400", "Access to core.kill denied");
 +          break;
 +     }
 +        }
 +
 +        dispatch_rpc();
 +        break;
 +    }
 +}
 +</code>

Trace:

Navigation

Wiki

Other

QR Code
QR Code ref_manual:transport:tls (generated for current page)