This page is about the <b>open source 3GPP IMS-IPSec implementation</b> in <a target=_blank href="https://code.google.com/p/doubango/">Doubango VoIP framework</a> from <a target=_blank href="http://doubango.org/">Doubango Telecom</a>. <br />
In this page we'll try to explain how security mechanisms are negotiated between an IMS Client and the Proxy-CSCF and how to setup SAs using <a href="http://ipsec-tools.sourceforge.net/"> Linux IPSec-Tools</a> and our demo clients (console app and <a href="https://code.google.com/p/boghe/">Boghe IMS Client</a>). <br />
Our code have been fully tested against <a href="http://www.openimscore.org/">OpenIMSCore</a> and many other comercial IMS Cores. <br />
- @ref _Anchor_TIPSec_Overview_Intro "1/ IPSec implementation in Doubango VoIP framework"
<h2>@anchor _Anchor_TIPSec_Overview_Intro 1/ IPSec implementation in Doubango VoIP framework</h2>
The IPSec implementation in Doubango VoIP framework is distributed as standalone plugins (<b>pluginWinIPSecVista.DLL</b>, <b>pluginWinIPSecXP.DLL</b> and <b>pluginWinIPSecLinux.SO</b>).
This allows having a single installer for all platforms as the right implementation is loaded at runtime (versus at link-time). Right now only <b>pluginWinIPSecVista.DLL</b> is open sourced. <br />
<b>pluginWinIPSecVista.DLL</b> as it's name says, requires Windows Vista or later and uses <a href="http://msdn.microsoft.com/en-us/windows/hardware/gg463267.aspx">Windows Filtering Platform</a> to manually setup the IPSec SAs. <br />
<b>pluginWinIPSecVista.DLL</b> supports:
<ul>
<li>IPProto: "udp", "tcp" and "icmp"</li>
<li>Modes: "tun" (tunnel) and "trans" (transport)</li>
<li>Encryption algorithm: "des-ede3-cbc", "aes-cbc" and "null"</li>
<li>Authentication algorithm: "hmac-sha-1-96" and "hmac-md5-96"</li>
<li>IPsecProto:"esp", "ah" and "ah/esp"</li>
</ul>
The utility functions used to load/unload the plugins and the wrappers for the high level APIs are in <b>tinyIPSec</b> project. <b>tinyIPSec</b> depends on <b>tinySAK </b>. <br />
The main purpose of Security agreement (<a href="http://www.ietf.org/rfc/rfc3329.txt">RFC 3329</a>) is to agree on which mechanisms, algorithms or security parameters to use.
There are five main mechanisms used in VoIP networks: <br />
<ul>
<li>digest</li>
<li>tls</li>
<li>ipsec-ike</li>
<li>ipsec-man</li>
<li><b>ipsec-3gpp</b></li>
</ul>
We will focus on <b>ipsec-3gpp</b> because it's <b>mandatory</b> for IMS. This requires SIP <b>AKAv1/v2</b> authentication. <br />
The security mechanism to use is known after the negotiation between the IMS Client and the Proxy-CSCF succeeds. This negotiation is performed during the IMS registration and authentication procedures.
Three new SIP header fields have been defined, namely <b>Security-Client</b>, <b>Security-Server</b> and <b>Security-Verify</b>.
- In step <b>(1)</b> the IMS Client sends an unprotected registration request including the security-client header. The Client must indicate that it is able to negotiate security mechanism by adding "Require" and "Proxy-Require" headers. The security-client header includes two ports (client and server ports) that the client wants to negotiate with the proxy CSCF.
- In step <b>(2)</b> the Proxy CSCF forwards the request to the Serving CSCF.
- In step <b>(3)</b> the Serving CSCF (registrar) challenges the Proxy CSCF. The 401 response is sent to the Proxy CSCF (challenge parameters are under WWW-Authenticated header). The Serving CSCF must include the "Security-Server" header.
- In step <b>(4)</b> the Proxy CSCF forwards the 401/494 response to the IMS Client. At this stage the Proxy CSCF opens the IPsec security association (SA) for the IMS Client. The IMS Client also setup a SA (this is a temporary SA).
- The lifetime of the created SA (between the IMS Client and the Proxy CSCF) is equal to the value of reg-await-auth timer.
- In step <b>(5)</b> the IMS Client sends a new registration (to the Proxy CSCF) request including its credentials and copies the content of security-server header to the security-verify header. Before forwarding the request to the Serving CSCF, the Proxy CSCF will check that the previous security-server header and the security-verify headers (added by the IMS Client) are the same. If these values are different, the Proxy CSCF sends an error message to the IMS Client and terminates the created SAs.
- In step <b>(6)</b> the Proxy CSCF forwards the request to the Serving CSCF.
- In step <b>(7)</b> the Serving CSCF authenticates the IMS Client, and responds with 200 OK.
- In step <b>(8)</b> the Proxy CSCF forwards the response to the IMS Client. At this step new SAs will be created. The temporary SAs will be destroyed (or not) by the Proxy CSCF.
<h2>@anchor _Anchor_TIPSec_Overview_IPSecTools 3/ Setting up SAs using Linux Tools</h2>
Here we suppose that: <br />
- We are using Ubuntu (Linux Kernel 2.6 + KAME-tools)
- the Proxy-CSCF address is '192.168.0.10' and Mercuro IMS Client address is '192.168.0.11'
- for secure ports see above SIP capture
- protocol is esp
- algorithm is 'hmac-md5'
- encrypt-algorithm is 'des-ede3-cbc'
- mode is 'transport'
- confidentiality key is '123456789012123456789012' (see function f2345 in 3GPP milenage algorithms)
- integrity key is '1234567890123456' (see function f2345 in 3GPP milenage algorithms)
<b>1. Install the tools</b>
@code
sudo apt-get install ipsec-tools
@endcode
<b>2. Edit /etc/ipsec-tools file and add the following script</b>
@code
#Incoming Requests [US <- PC]
spdadd 192.168.0.10/32[5066] 192.168.0.11/32[5064] udp -P in ipsec esp/transport//require;
add 192.168.0.10 192.168.0.11 esp 2222 -m transport -E des-ede3-cbc "123456789012123456789012" -A hmac-md5 "1234567890123456";
#Incoming Replies [UC <- PS]
spdadd 192.168.0.10/32[5068] 192.168.0.11/32[5062] udp -P in ipsec esp/transport//require;
add 192.168.0.10 192.168.0.11 esp 1111 -m transport -E des-ede3-cbc "123456789012123456789012" -A hmac-md5 "1234567890123456";
#Outgoing Requests [UC -> PS]
spdadd 192.168.0.11/32[5062] 192.168.0.10/32[5068] udp -P out ipsec esp/transport//unique:1;
add 192.168.0.11 192.168.0.10 esp 4444 -m transport -u 1 -E des-ede3-cbc "123456789012123456789012" -A hmac-md5 "1234567890123456";
#Outgoing Replies [US -> PC]
spdadd 192.168.0.11/32[5064] 192.168.0.10/32[5066] udp -P out ipsec esp/transport//unique:2;
add 192.168.0.11 192.168.0.10 esp 3333 -m transport -u 2 -E des-ede3-cbc "123456789012123456789012" -A hmac-md5 "1234567890123456";
@endcode
<b>3. Run the script</b>
@code
sudo /etc/init.d/setkey start
@endcode
<h2>@anchor _Anchor_TIPSec_Overview_IPSecAPI 4/ Using tinyIPSec API</h2>
This section explain how to setup the IPSec SAs using our API for a client (for the server it's obvisious). The values (SPIs, Ports, IP addresses...) are from previous sections. <br />
In this section:
- <b>UC</b> means UE acting as client (i.e sending a SIP request)
- <b>US</b> means UE acting as server (i.e receiving a SIP request)
- <b>PC</b> means P-CSCF acting as client (i.e sending a SIP request)
- <b>PS</b> means P-CSCF acting as server (i.e receiving a SIP request)
<b>/!\\VERY IMPORTANT:</b> On Windows the application (or Visual Studio if you're debugging the code) must be started as "Administrator" (Right click then <b>Run as administrator</b>) to be autorized to setup IPSec SAs (otherwise <b>error code 5</b>).
<h3>@anchor _Anchor_TIPSec_Overview_IPSecAPI_LoadPlugin 4.1/ Loading the Plugin</h3>
Before calling any API function from <b>tinyIPSec</b> it's required to load the standalone plugin like this:
Because <a href="http://msdn.microsoft.com/en-us/windows/hardware/gg463267.aspx">Windows Filtering Platform</a> doesn't allow setting arbitrary SPIs we must create temporary SAs in order to have client SPIs for the initial REGISTER request.
Temporary SAs requires information about the local address and ports. Remote port is not required but expected for better filtering to avoid IPSec restrictions for <b>any</b> in/out data towards the local ports. <br />
<b>2) Create temporary SAs and request local SPIs</b>
Now you can send the initial REGISTER (unprotected).
<b>3) Setting remote information</b>
Once the initial REGISTER is sent the server will send back a 494 response with one or several <b>Security-Server</b> headers. Select the best one and extract the information (SPIs, Ports, alogs,...) from it:
@code
err = tipsec_ctx_set_remote(
p_ctx,
3333, // SPI-C for the P-CSCF
4444, // SPI-S for the P-CSCF
5066, // PORT-C for the P-CSCF
5068, // PORT-S for the P-CSCF
1800 // lifetime (in seconds) (at least the registration timeout)
<b>At this step, any data sent using PORT-C or receieved using PORT-S is (and must be) encrypted.</b>
<b>4) Setting the CK and IK keys</b>
The CK (Confidentiality) and IK (Integrity) keys are computed using the 3GPP milenage functions like this: <a href="https://code.google.com/p/doubango/source/browse/branches/2.0/doubango/tinySIP/src/authentication/tsip_challenge.c?r=765#85">https://code.google.com/p/doubango/source/browse/branches/2.0/doubango/tinySIP/src/authentication/tsip_challenge.c?r=765#85</a>. <br />
<h2>@anchor _Anchor_TIPSec_FAQ_Stable Is IPSec implementation in Doubango stable?</h2>
Our IPSec implementation is <b>3 years old</b> and have been tested against OpenIMSCore and many other IMS Cores. <br />
By default, IPSec was desabled and it was up to the developer to rebuild the code to enable it. The new code is also clean and use standalone plugins.
<h2>@anchor _Anchor_TIPSec_FAQ_Systems Which operating systems are supported?</h2>
For now only <b>Windows Vista and later</b>. We've code for <b>Windows XP</b> and <b>Linux</b> but it's not published yet. <br />
Ask on our <a href="https://groups.google.com/forum/#!forum/doubango">dev-group</a> to get the complete source code.
<h2>@anchor _Anchor_TIPSec_FAQ_Logs Where are Boghe logs?</h2>
On vista: C:\\Users\\your identity here\\AppData\\Roaming\\Doubango\\Boghe IMS Client\\Boghe.log.
<h2>@anchor _Anchor_TIPSec_FAQ_ReportIssues I'm using Boghe IMS Client to test IPSec but it's not working. How to report issues?</h2>
Make sure that you're:
- using the latest <a href="https://code.google.com/p/boghe/downloads/list">Boghe</a> version (December 2013)
- using Windows Vista or later
- started the app as administrator (right click then, "Run as administrator") or disabled UAC
If you still have problems then, share them on our <a href="https://groups.google.com/forum/#!forum/doubango">dev-group</a>. You <b>must</b> share your @ref _Anchor_TIPSec_FAQ_Logs "logs".
<h2>@anchor _Anchor_TIPSec_FAQ_CheckSAs How to check SAs are up?</h2>
Go to "Control Panel" -> "Administrative Tools" -> "Windows Firewall with Advanced Security" -> "Security Associations" -> "Quick Mode" and check that your SAs are listed there.
<h2>@anchor _Anchor_TIPSec_FAQ_Error5 I see "Error code 5" when I try to setup a SA. How can I fix this?</h2>
On Windows, error code 5 means "Access denied". You must start your app (or Visual Studio) as administrator or disable the UAC.
*/
/**@page _Page_Main_Medium_Level_API_Overview Medium level API (C++)