= Configuring PJSIP with TLS =

== Requirements ==

The TLS support in PJSIP requires OpenSSL development kit (headers and libs) to be installed. Please follow the following guide below for more info on how to install OpenSSL for each platform:
 - [wiki:Getting-Started/Installing-OpenSSL-Windows Windows: Installing OpenSSL]
 - [https://trac.pjsip.org/repos/wiki/Getting-Started/iPhone#OpenSSLSupport iOS: OpenSSL support]
 - [https://trac.pjsip.org/repos/wiki/Getting-Started/Android#OpenSSLSupport Android: OpenSSL support]
 - [https://trac.pjsip.org/repos/wiki/Getting-Started/BB10#EnablingTLSusingbundledOpenSSL BB10: using bundled OpenSSL]
 - TLS support on Symbian is implemented natively using CSecureSocket, hence it doesn't require OpenSSL development kit. Please see [wiki:TLS_on_Symbian Configuring TLS on Symbian] for the detailed information.

== Build PJSIP with TLS Support ==

SIP TLS transport is implemented based on the new PJLIB [http://www.pjsip.org/pjlib/docs/html/group__PJ__SSL__SOCK.htm secure socket abstraction], and its availability is based on {{{PJ_HAS_SSL_SOCK}}} macro value. For ''autoconf'' build system, the value is automatically detected based on OpenSSL availability. For other platforms such as Windows and Symbian, please declare this in your {{{config_site.h}}}:
{{{
#define PJ_HAS_SSL_SOCK 1
}}}

Note:
 - The {{{PJSIP_HAS_TLS_TRANSPORT}}} default value will be set to {{{PJ_HAS_SSL_SOCK}}} setting.
 - For PJSIP version prior to 1.5, where the macro PJ_HAS_SSL_SOCK has not been introduced yet, it is {{{PJSIP_HAS_TLS_TRANSPORT}}} macro that have to be set in the {{{config_site.h}}}.


== Running pjsua as TLS Server == #pjsua-tls-server

 1. You will need specify a TLS certificate, represented by three PEM files:
     a. The root certificate
     a. The server certificate
     a. The private key
 1. Run pjsua:
  {{{
$ ./pjsua --use-tls --tls-ca-file root.pem --tls-cert-file server-cert.pem --tls-privkey-file privkey.pem

  }}}
 1. To see more TLS options, run {{{./pjsua --help}}}.

== Running pjsua as TLS Client ==

To make call to SERVER using TLS:

{{{
$ ./pjsua --use-tls <sip:SERVER;transport=tls>
}}}

To see more TLS options, run {{{./pjsua --help}}}.


== Enable TLS mutual authentication == #mutual

Basically, it is done by two ways certificate verification, so both sides must provide TLS certificate (as described in [#pjsua-tls-server Running pjsua as TLS Server] above) and enable verification:
 - as TLS server: append pjsua option {{{--tls-verify-client}}},
 - as TLS client: append pjsua option {{{--tls-verify-server}}}.

To see about TLS in library level, check the TLS docs in the links section below.


== Links ==

 - [wiki:TLS_on_Symbian Configuring TLS on Symbian]
 - TLS in PJSUA-LIB: [http://www.pjsip.org/docs/latest/pjsip/docs/html/structpjsua__transport__config.htm#af5312dee746201415930e0c4fb445a7c pjsua_transport_config::tls_setting].
 - TLS in PJSIP: [http://www.pjsip.org/docs/latest/pjsip/docs/html/group__PJSIP__TRANSPORT__TLS.htm TLS SIP Signalling Transport].
 - TLS in PJLIB: [http://www.pjsip.org/docs/latest/pjlib/docs/html/group__PJ__SSL__SOCK.htm Secure socket I/O].