Using TLS

Adding a TLS transport

In order to use a TLS transport you must

• compile the resiprocate project with the USE_SSL pre-processor define enabled
• create a Security object before creating a SipStack - pass the certificate file location to the Security constructor (default on windows is c:\sipCerts and default on linux is ~/.sipCerts/
• pass the created Security object to the SipStack constructor
• add a TLS transport by using the addTransport method of the SipStack interface (or DialogUsageManager interface - if using DUM):

      /** 
         Used by the application to add in a new built-in transport.  The transport is
         created and then added to the Transport Selector.
 
         @throws Transport::Exception If the transport couldn't be added, usually
                                      because the port was already bound.
 
         @param protocol              TCP, UDP, TLS, DTLS, etc.
 
         @param port                  Specifies which port to bind to.
 
         @param version               Protocol Version:  V4 or V6
 
         @param ipInterface           Specifies which ethernet interface to bind to. If set to 
                                      Data::Empty, bind to all interfaces.
 
         @param sipDomainname         Only allow messages to 
                                      be sent as the specified domain.  For default case, 
                                      you can pass in domainname = DnsUtil::getLocalDomainName().
 
         @param privateKeyPassPhrase  Private key pass phrase used to decrypt private key 
                                      certificates.  Note:  For now this parameter is not used
                                      we are loading PKCS7 keys, so a pass phrase is not required.
 
         @param sslType               Version of the TLS specification to use:  SSLv23 or TLSv1
      */      
      Transport* addTransport( TransportType protocol,
                         int port, 
                         IpVersion version=V4,
                         StunSetting stun=StunDisabled,
                         const Data& ipInterface = Data::Empty, 
                         const Data& sipDomainname = Data::Empty, // only used
                                                                  // for TLS
                                                                  // based stuff 
                         const Data& privateKeyPassPhrase = Data::Empty,
                         SecurityTypes::SSLType sslType = SecurityTypes::TLSv1);

• For acting as a TLS server - ensure a domain_cert_<domainname>.pem and domain_key_<domainname>.pem exists in the certificate store for the domainname bound to this transport
• For acting as a TLS client - ensure the proper certificate authority certificates (root_cert_<CA>.pem) exist in the certificate store

Cerificate Types and Naming conventions

There are five types of certificates that can be used by the resiprocate stack:

Root Certificates

Contains available public keys for CA's (Certificate Authorities)

root_cert_<name>.pem

eg.
    root_cert_verisign.pem
    root_cert_mycertauth.pem

Domain Ceritificates and Keys

Contains available certificates and private keys for the domains the system serves

domain_cert_<domainname>.pem
domain_key_<domainname>.pem

eg. 
    domain_cert_sip.example.com.pem
    domain_key_sip.example.com.pem

User Certificates and Keys

Contains available certificates and private keys for specific users (used for S/MIME)

user_cert_<username>.pem
user_key_<username>.pem