Dialogic Support Helpweb
Dialogic® Host Media Processing (HMP) Software
Secure RTP - A Basic Demo
A simplified demo of SRTP (Secure Real Time Protocol) using Dialogic HMP
Download demo code
Problem Description
The Dialogic Internet Protocol Media Library (IPML) API supports Secure Real Time Protocol. (SRTP) While there is a section in the IP Media Library API for Host Media Processing document that explains SRTP, it only contains small code snippets to illustrate its points. It does not provide any self-contained, working examples of code.
Solution Summary
This tech note remedies the situation by presenting a simple example of process to process secure RTP streaming. To keep matters simple, SIP or other call control is not used. Instead, two processes are started and secured audio is streamed between them. The first process a file, encodes the voice and plays it into an outbound RTP stream. The second receives the stream, decodes the encrypted audio and writes the results to a file.
Technical Discussion
Demo Structure
Since this is a very simple demo, it is done in a synchronous programming mode. It is recommended that any Dialogic telecom application beyond a simple demo be written asynchronously.
The demo begins by parsing startup parameters, and then opening a single IPML media device and a voice device. The two devices are then cross-connected on the virtual CT-Bus using xx_GetXmitSlot() and xx_Listen().
SRTP parameters are kept in several nested structs:
#define BS64KEYSIZE 40 // recommended size for a base-64 key
char bs64Mkey1[BS64KEYSIZE];
IPM_SRTP_PARMS srtp_parms;
IPM_SECURITY_KEY MasterKey;
IPM_SECURITY_BASE64_KEY Masterbs64Key;
Each of the structs is passed to its own initialization macro, and is then assigned to the appropriate field of its parent struct. See the code for details.
Key generation is done by calling:
ipm_SecurityGenMasterKeys(ipm_handle, &MasterKey, 1, EV_SYNC)
The resulting key (a base 64 key using MIME readable characters) is then saved to a text file and may be used to encrypt or decrypt a media stream. Note that the same key must be used for both encryption and decryption. Normally, the key is delivered via transport layer security (TLS) in the session description protocol (SDP) part of SIP Invite message. Here, we simply copy the same key to both sides.
Playing/encryption and recording/decryption both begin by opening the key file. The IP_MEDIA_INFO struct is then populated. It is used to specify the remote IP address, RTP and RTCP ports, local and remote audio codecs. Security parameters, set in the structs described above, are also assigned to IP_MEDIA_INFO.
RTP streaming is then started:
ipm_StartMedia(channel_handle, &MediaInfo, DATA_IP_TDM_BIDIRECTIONAL, EV_SYNC)
Depending on the media function (play/record) of the process, it then either records incoming media or loops 3 times over playing a voice file. The operation terminates, and the user is prompted for a CR to end the session. Devices are disconnected and closed, and the program exits.
This demo only shows the very basics of SRTP. Further illustrations of the more advanced features, as well as demos using SRTP with TLS are planned.
Building the Demo
The demo code is accompanied by Microsoft Visual C++ 6.0 project files. This, or a later version of one of Microsoft’s development environments, can be used to build and run the demo.
Running the Demo
The SRTP demo may be run in one of several modes:
* Key Generation mode – generates a base-64 master key and exits. A pre-generated key also accompanies the code
* Play mode – plays a voice file, encrypts voice into SRTP and streams to opposite endpoint
* Record mode – receives RTP stream, decrypts voice, and records to a file
These modes are controlled by the flags given when the process is started:
srtpdemo –k|-p|-r remote_ip_address remote_rtp_port channel_number
Only one of the modes may be given on startup. The IP address of the remote system, remote RTP port and channel number for streaming and voice are mandatory.
It is possible to run the two processes on the same system, but care must be taken so that resources are partitioned correctly between them. In this case, the remote IP address is the system’s own, and two different remote RTP ports and channel numbers must be used. For example, the two processes may be started with:
srtpdemo –p 192.168.1.10 49152 2
srtpdemo –r 192.168.1.10 49154 1
This translates into the play side opening ipmB1C2 and dxxxB1C2 and streaming its media to port 49152. The record side opens ipmB1C1 and dxxxB1C1 and streams to port 49154. Default RTP ports in HMP are numbered as follows:
ipmB1C1 49152
ipmB1C2 49154
ipmB1C3 49156
ipmB1C4 40158
The demo also prints out its local IP address and RTP port on startup.
Start the record side first, followed by the play side. Play and record intervals should allow enough time to capture a full recording of the voice being played.
Verifying Demo Operation
The demo does not provide interactive audio – for example, allowing a SIP phone to call in and listen to the result. But, there is another way to verify that the RTP stream “on the wire” is indeed encrypted and that the resulting recording is properly decrypted.
This may be done using two freely available utilities. Ethereal, an IP “packet sniffing” package can be used to capture the RTP stream, and save it to an audio file. There, it can be replayed using Audacity, an audio analyzer. Audacity can also be used to verify that the recording is normal.
If Ethereal is used, two separate systems must run the play and record sessions. It is not possible to capture packets on the local loopback interface on Windows, which is used if the both are run on the same system.
Here is the procedure for capturing and verifying encrypted and decrypted audio:
Start Ethereal on record-side system
* Capture->Options
* Check off - Update Packets in Real Time, Auto Scrolling, Hide Capture Info
* Start
Run the two sides of the srtpdemo. When record is done
* Stop packet capture
* Select a UDP packet
* Assign packet type - Analyze->Decode As->RTP
* Look at RTP streams - Statistics->RTP->Show All Streams
* Pick the stream from the Play system to the Record system and hit Analyze
* Save Payload, select forward channel, and give a file name ending in .au
Start Audacity to hear file just produced
* Select file just saved - File->Open->Browse to file
* Recording waveform should be visible, hit green Play button
Audio will be unintelligible – it has been encrypted!
Use Audacity to listen to recorded file “recording.vox” in project folder
* Select file as above
* When waveform is visible, change rate to 6000Hz - Recording->Set Rate->Other
* Hit green Play button
Audio should be clean and understandable – it has been decrypted!
Product List
* Dialogic HMP 3.0 Windows - http://resource.dialogic.com/telecom/support/HMPWin/hmp30/index.htm
* Microsoft Windows XP or Server 2003 with appropriate service packs
* Audacity - http://audacity.sourceforge.net/
* Ethereal - http://www.openxtra.co.uk/downloads/ethereal-download.php or
http://www.ethereal.com/download.html
Glossary of Acronyms / Terms
MIME Multipurpose Internet Mail Extensions
RTP Real Time Protocol
RTCP Real Time Control Protocol
SDP Session Description Protocol
SIP Session Description Protocol
SRTP Secure Real Time Protocol
TLS Transport Layer Security
Related Documentation
IP Media Library API for Host Media Processing Programming Guide
IP Media Library API for Host Media Processing Library Reference
First Published
03/19/2007
Last Updated
03/19/2007
