Skip to end of metadata
Go to start of metadata

Overview

Icon

This tutorial makes use of SRTP and TLS. SRTP support was added in Asterisk 1.8, TLS was added in 1.6.

So you'd like to make some secure calls.

Here's how to do it, using Blink, a SIP soft client for Mac OS X, Windows, and Linux. You can find some brief instructions for installing Blink on Ubuntu on the wiki.

These instructions assume that you're running as the root user (sudo su -).

Part 1 (TLS)

Transport Layer Security (TLS) provides encryption for call signaling. It's a practical way to prevent people who aren't Asterisk from knowing who you're calling. Setting up TLS between Asterisk and a SIP client involves creating key files, modifying Asterisk's SIP configuration to enable TLS, creating a SIP peer that's capable of TLS, and modifying the SIP client to connect to Asterisk over TLS.

Keys

First, let's make a place for our keys.

mkdir /etc/asterisk/keys

Next, use the "ast_tls_cert" script in the "contrib/scripts" Asterisk source directory to make a self-signed certificate authority and an Asterisk certificate.

./ast_tls_cert -C pbx.mycompany.com -O "My Super Company" -d /etc/asterisk/keys -b 2048
  • The "-C" option is used to define our host - DNS name or our IP address.
  • The "-O" option defines our organizational name.
  • The "-d" option is the output directory of the keys.
  • The "-b" option specifies the size of the private key file, default is 1024 unless on master branch.
  1. You'll be asked to enter a pass phrase for /etc/asterisk/keys/ca.key, put in something that you'll remember for later.
  2. This will create the /etc/asterisk/keys/ca.crt file.
  3. You'll be asked to enter the pass phrase again, and then the /etc/asterisk/keys/asterisk.key file will be created.
  4. The /etc/asterisk/keys/asterisk.crt file will be automatically generated.
  5. You'll be asked to enter the pass phrase a third time, and the /etc/asterisk/keys/asterisk.pem will be created, a combination of the asterisk.key and asterisk.crt files.

Next, we generate a client certificate for our SIP device.

./ast_tls_cert -m client -c /etc/asterisk/keys/ca.crt -k /etc/asterisk/keys/ca.key -C phone1.mycompany.com -O "My Super Company" -d /etc/asterisk/keys -o malcolm -b 2048
  • The "-m client" option tells the script that we want a client certificate, not a server certificate.
  • The "-c /etc/asterisk/keys/ca.crt" option specifies which Certificate Authority (ourselves) that we're using.
  • The "-k /etc/asterisk/keys/ca.key" provides the key for the above-defined Certificate Authority.
  • The "-C" option, since we're defining a client this time, is used to define the hostname or IP address of our SIP phone
  • The "-O" option defines our organizational name.
  • The "-d" option is the output directory of the keys."
  • The "-o" option is the name of the key we're outputting.
  • The "-b" option specifies the size of the private key file, default is 1024 unless on master branch.
  1. You'll be asked to enter the pass phrase from before to unlock /etc/asterisk/keys/ca.key.

Now, let's check the keys directory to see if all of the files we've built are there. You should have:

asterisk.crt
asterisk.csr
asterisk.key
asterisk.pem
malcolm.crt
malcolm.csr
malcolm.key
malcolm.pem
ca.cfg
ca.crt
ca.key
tmp.cfg

Next, copy the malcolm.pem and ca.crt files to the computer running the Blink soft client.

.p12 Client Certificates

Icon

If your client requires a .p12 certificate file instead, you can generate that using openssl like:

 

Asterisk chan_pjsip configuration

Now, let's configure Asterisk's PJSIP channel driver to use TLS.

In the pjsip.conf configuration file, you'll need to enable a TLS-capable transport.  An example of one would resemble:

[transport-tls]
type=transport
protocol=tls
bind=0.0.0.0:5061
cert_file=/etc/asterisk/keys/asterisk.crt
priv_key_file=/etc/asterisk/keys/asterisk.key
method=sslv23

Note the protocol, cert_file, priv_key_file, and method options.  Here, we're using the TLS protocol, we're specifying the keys that we generated earlier for cert_file and priv_key_file and we're setting the method to SSLv23.

Next, you'll need to configure a TLS-capable endpoint.  An example of one would resemble:

[malcolm]
type=aor
max_contacts=1
remove_existing=yes
 
[malcolm]
type=auth
auth_type=userpass
username=malcolm
password=useabetterpasswordplease
 
[malcolm]
type=endpoint
aors=malcolm
auth=malcolm
context=local
disallow=all
allow=g722
dtmf_mode=rfc4733
media_encryption=sdes
 

Note the media_encryption option for the endpoint.  In this case, we've configured an endpoint that will be using SDES encryption for RTP.

You might be tempted to add a transport=transport-tls to the endpoint but in pjproject versions at least as late as 2.4.5, this will cause issues like Connection refused in a few situations.  Let pjproject do the transport selection on its own.  If you still see issues, set rewrite_contact = yes in the endpoint configuration.

Asterisk chan_sip configuration

Or, if you are using chan_sip, you can use the following to assist.

In the sip.conf configuration file, set the following:

tlsenable=yes
tlsbindaddr=0.0.0.0
tlscertfile=/etc/asterisk/keys/asterisk.pem
tlscafile=/etc/asterisk/keys/ca.crt

Here, we're enabling TLS support.
We're binding it to our local IPv4 wildcard (the port defaults to 5061 for TLS).
We've set the TLS certificate file to the one we created above.
We've set the Certificate Authority to the one we created above.

Next, you'll need to configure a SIP peer within Asterisk to use TLS as a transport type. Here's an example:

[malcolm]
type=peer
secret=malcolm ;note that this is NOT a secure password
host=dynamic
context=local
dtmfmode=rfc2833
disallow=all
allow=g722
transport=tls

Notice the transport option. The Asterisk SIP channel driver supports three types: udp, tcp and tls. Since we're configuring for TLS, we'll set that. It's also possible to list several supported transport types for the peer by separating them with commas.

Configuring a TLS-enabled SIP client to talk to Asterisk

Next, we'll configure Blink.

First, let's add a new account.

Then, we need to modify the Account Preferences, and under the SIP Settings, we need to set the outbound proxy to connect to the TLS port and transport type on our Asterisk server. In this case, there's an Asterisk server running on port 5061 on host 10.24.13.224.

Now, we need to point the TLS account settings to the client certificate (malcolm.pem) that we copied to our computer.

Then, we'll point the TLS server settings to the ca.crt file that we copied to our computer.

Press "close," and you should see Blink having successfully registered to Asterisk.

Depending on your Asterisk CLI logging levels, you should see something like:

  -- Registered SIP 'malcolm' at 10.24.250.178:5061
     > Saved useragent "Blink 0.22.2 (MacOSX)" for peer malcolm

Notice that we registered on port 5061, the TLS port.

Now, make a call. You should see a small secure lockbox in your Blink calling window to indicate that the call was made using secure (TLS) signaling:

Problems with server verification

If the host or IP you used for the common name on your cert doesn't match up with your server then you may run into problems when your client is calling Asterisk. Make sure the client is configured to not verify the server against the cert.

When calling from Asterisk to Blink or another client, you might run into an ERROR on the Asterisk CLI similar to this:

[Jan 29 16:04:11] DEBUG[11217]: tcptls.c:248 handle_tcptls_connection:  SSL Common Name compare s1='10.24.18.124' s2='phone1.mycompany.com'
[Jan 29 16:04:11] ERROR[11217]: tcptls.c:256 handle_tcptls_connection: Certificate common name did not match (10.24.18.124)

This is the opposite scenario, where Asterisk is acting as the client and by default attempting to verify the destination server against the cert.

You can set tlsdontverifyserver=yes in sip.conf to prevent Asterisk from attempting to verify the server.

;tlsdontverifyserver=[yes|no]
;        If set to yes, don't verify the servers certificate when acting as
;        a client.  If you don't have the server's CA certificate you can
;        set this and it will connect without requiring tlscafile to be set.
;        Default is no.

 

Part 2 (SRTP)

Now that we've got TLS enabled, our signaling is secure - so no one knows what extensions on the PBX we're dialing. But, our media is still not secure - so someone can snoop our RTP conversations from the wire. Let's fix that.

SRTP support is provided by libsrtp. libsrtp has to be installed on the machine before Asterisk is compiled, otherwise you're going to see something like:

[Jan 24 09:29:16] ERROR[10167]: chan_sip.c:27987 setup_srtp: No SRTP module loaded, can't setup SRTP session.

on your Asterisk CLI. If you do see that, install libsrtp (and the development headers), and then reinstall Asterisk (./configure; make; make install).

With that complete, let's first go back into our peer definition in sip.conf. We're going to add a new encryption line, like:

[malcolm]
type=peer
secret=malcolm ;note that this is NOT a secure password
host=dynamic
context=local
dtmfmode=rfc2833
disallow=all
allow=g722
transport=tls
encryption=yes
context=local

Next, we'll set Blink to use SRTP:

Reload Asterisk's SIP configuration (sip reload), make a call, and voilà:

We're making secure calls with TLS (signaling) and SRTP (media).

  • No labels

44 Comments

  1. gilles

    Thanks for this doc!
    But one point remains unclear,
    while the ca.crt has been automatically handled by windows, where should I put the user.pem file (using zoiper biz on a windows machine) ?

    Gilles

    1. Malcolm Davenport

      I don't have Zoiper Biz or Windows. My best guess, by looking at the Free version for Mac, which does not support TLS or SRTP, says it should probably go in the box here:

      You might have to watch the port number configured there as well; TLS runs, by default, on 5061, not 5060.

      1. gilles

        I tried my registered biz version (2.30) and the free version of Zoipper (2.36) for Windows, in both this TLS Certificate file option isn't there. However, I can see it disabled in the Linux version (1.18). So I'm now using PhonerLite where I could find it. Thanks for that.

        But, by default, TLS works fine without the user certificate.
        And I can't see any client certificate request from the server in Wireshark, should I set it somewhere ?
        I couldn't find anything in sip.conf or in Asterisk 1.8 doc about it.

        Also, when my client registers, I get something like :
        – Registered SIP 'phonerlite' at 10.100.5.61:49296
        But in Wireshark, I can see that, on the server side, the signaling goes through port 5061.

        Many people use the following variables in their dialplan when setting sRTP :
        _SIP_SRTP_SDES=1
        _SIPSRTP=enable
        _SIPSRTP_CRYPTO=enable
        Why don't you use it ? Are they unnecessary ?
        Do you know if they are documented somewhere ?

        When I set SRTP (both on clients and server sides), the only difference I can see with TLS is that the media goes through the server and not straight to the other client. Like with TLS only, for the media, I don't see the UDP/RTP layer anymore, but UDP/Data. Also, with or without sRTP set, UDP/Data begins with 800 hex code, like with UDP, that makes me think sRTP doesn't work for me. Also, I always get this error message :
        29:14 WARNING9646: res_srtp.c:338 ast_srtp_unprotect: SRTP unprotect: authentication failure
        What does it mean ? What do I need to do to make it work ?

        Thanks for your help,
        Gilles

        1. Malcolm Davenport

          The asterisk-users list is a great place for long discussions and lots of questions.

          [Jan 28 17:29:14] WARNING9646: res_srtp.c:338 ast_srtp_unprotect: SRTP unprotect: authentication failure
What does it mean ? What do I need to do to make it work ?

          It probably means your client isn't capable of AES_CM_128_HMAC_SHA1_80, but instead only AES_CM_128_HMAC_SHA1_32. Asterisk invites back to the client only with AES_CM_128_HMAC_SHA1_80 currently. See:

          https://issues.asterisk.org/view.php?id=18674

  2. AZZOUZI

    Hi Malcolm,
    I work with Elastix but i don't find the "ast_tls_cert" script in the "contrib/scripts" Asterisk source directory!!!
    Can you post it in this forum please?

    Thank you!

    1. Malcolm Davenport

      Hi,

      It's only in the contrib/scripts directory for Asterisk 1.8, it's not present for older releases. You can download 1.8 to get it, check 1.8 out of SVN, or see it here:

      http://svn.digium.com/view/asterisk/branches/1.8/contrib/scripts/ast_tls_cert?view=log

      Cheers.

  3. AZZOUZI

    Hi,
    Thank you Malcolm!
    I'll try it!

  4. AZZOUZI

    Hi Malcolm,
    can you tell me please how to install the libsrtp? and if i reinstall Asterisk, i'll loose all my configurations??

    Thank you

    1. Malcolm Davenport

      Hi,

      Tutorials on how to install packages are beyond the scope of this Wiki. Google may be of some use, depending on your base Linux distribution. You said you were using Elastix. I do not think Elastix supports Asterisk 1.8, thus you can't use SRTP with Elastix until it does. Then, presumably, Palo Santo will have packaged Asterisk in a way that it is linked against the libsrtp dependency, so use of SRTP would then be simple. I cannot provide a tutorial here for how to repackage Asterisk for Elastix. (sad)

      1. AZZOUZI

        Hi,
        it's ok with my Elastix! i could download and install libsrtp!
        Now my problem is with Blink which said : "Not acceptable Here", when i try to make a call with SRTP.
        do you have an idea?

        Thank you very much

        AZZOUZI

        1. Malcolm Davenport

          Hi,

          Please take that question to the asterisk-users mailing list.

          Cheers.

  5. Ales Silar

    Hi,

    Does anybody have tutorial for Aastra phones with TLS and Asterisk?

    1. alejandro

      Hi Ales Silar,
      did you find a Aastra phones TLS tutorial?

      Thanks.

  6. Andrea Cristofanini

    Hi Azzouzi,
    your client have not the same audio codec used by asterisk,
    add it to allow order list in yoyr sip account settings.
    Regards Andrea

    1. AZZOUZI

      Hi Andrea, but it works without SRTP! I tested blink without (TLS/SRTP) and it can make calls!

  7. alejandro

    Hi,

    Great how-to, really!! I've tested with blink softphone and it works. But, I'd like to get working tls on Aastra phones (6755i particulary). Did you test this? Anyone here have tried to get TLS working in Aastra phones? I have a doubt. I fill the TLS Support blanks with the files names which I had put in my /tftpboot but it's not working, and the tftp server is working in my asterisk server (Debian 6.0, Asterisk 1.8). Any ideas? Any screenshot?

    Thanks so much.

    Alejandro.

  8. Carlo Rogialli

    Dear Malcolm, thanks for this great tutorial.
    One thing is unclear to me, and I believe it's worth an additional line.

    If the client is a mobile device (e.g. an iPhone running Bria hooked up to a mobile network or a wlan) how can anyone generate a certificate? The -C option requires an IP or a DNS name, but in the case I outlined above the IP is STRONGLY dynamic and the DNS doesn't exist...

    Must I assume that TLS is available only for on-lan, static clients? Or there is something I don't know?

    Thanks

    Carlo

  9. Umpana

    Great !!
    Thank you, Malcolm..

    What type of SRTP here? Is it SDES, DTLS, or MIKEY ?
    How can i see (debug) the type of this SRTP in terminal?

    Thanks (smile)

  10. insan laksana

    thanks malcolm for tutorial,,

    i'm trying to set up TLS in asterisk 1.8.4.3 and ubuntu 10.04. and blink as client in windows.
    I've done all the steps as you told, but when i'm trying to call, always error: TRANSPORT ERROR in blink.

    any ideas?
    thanks.

  11. Erwen Tang

    I'm running the latest freepbx with (*)1.8.19.1. I downloaded the script from SVN 1.8.19.1 tag and executed the instruction above. I'm getting the following error when I perform a 'sip reload'

    SSL error loading cert file. </etc/asterisk/keys/asterisk.pem>

    I made sure that the file is accessible and the contents of the file seem correct.

    cat /etc/asterisk/keys/asterisk.pem returns:

    ----- BEGIN RSA PRIVATE KEY -----
    <hidden>
    ----- END RSA PRIVATE KEY -----
    ----- BEGIN CERTIFICATE -----
    <hidden>
    ----- END CERTIFICATE -----

    Any ideas on what the problem might be?

    1. Rusty Newton

      Nope, and you'll want to ask that on the asterisk-users list, or the FreePBX mailing list, as the wiki is not a support forum.

    2. Farhan Ahmad

      You might want to check the permission on the folder 'keys' and files in it. 

  12. johnc

    Does selecting "use SRTP without TLS" mean SRTP key exchange happens in clear text? If so this not good. Is this the only way to get asterisk to work when using SRTP? This option is not available anyway in recent versions of blink.

    Can you give a snippet of dial-plan code you used to make this work? I had to use:

    CHANNEL(secure_bridge_signaling)=1

    Before calling Dial() to make TLS work. This isn't mentioned above.

    I tried the following in a similar fashion to get SRTP to work, unfortunately it didn't.

    CHANNEL(secure_bridge_media)=1

    The module is loaded. I've followed the guide above. Is there anything else to be done? Thanks.

  13. johnc

    I noticed you took down the picture with selecting "use SRTP without TLS" enabled. Have you tested this configuration with and without the option selected? What was the result? Can asterisk only exchange SRTP keys in clear text? Thanks again.

    1. Malcolm Davenport

      If you're configured for TCP then they'll be exchanged in clear text. If you're configured for TLS then they're only exchanged in the secured TLS.

      Since in this guide we were already doing TLS, things were fine. I changed the image to remove any ambiguity.

  14. Ameer

    Hello,
    I have been able to create the certificates but I am having alot of issues on the client end. I have tried Blink as suggested in the tutorial but I cannot import the client certificate to Blink as the column where the certificate is to be imported does not highlight. I have tried Jitsi, Microsip, 3cx, phone and phonerlite as well as so many other clients but I am still having difficulties as Asterisk keeps on generating an error message about the certificates.

    As much as I enjoy asterisk I would really appreciate any help as I have spent so much time on this particular stage and I would really like to get a move on.

    Cheers!

    1. Rusty Newton

      Ameer, Digium hosts several places for the community to ask questions and help each other out. You might try your question on the asterisk-users list or #asterisk IRC channel: http://www.asterisk.org/community/discuss or the forums at http://forums.asterisk.org/

      Very few users will see your question here, as most users don't watch or subscribe to particular wiki pages (like this one).

       

       

  15. Jose Adan Tapia

    Hi i do all the steps, i installed blink on my Win 7 Ultimate 64 bits, when i tried to import the ca.crt i receive and error saying: The certificate file is invalid: Base64 unexpected error, what could be the error?

    1. Rusty Newton

      I don't know. You can go to http://projects.ag-projects.com/projects/blinkc/wiki/Help_For_Blink_Pro to find help resources for Blink.

       

  16. Jose Adan Tapia

    Hi Rusty, i will try with grandstream gxp2124 because i used eyebearm softphone and don't work, i will let you know, thanks for the reply

    1. Rusty Newton

      It'll be more useful to bring your questions up on the asterisk-users mailing list. That is the primary place for community support at the moment. Thanks.

      1. Jose Adan Tapia

        Thanks Rusty, im trying to be more proactive, best regards (smile)

      2. Jose Adan Tapia

        Thanks Rusty, im trying to be more proactive, best regards (smile)

  17. Felix

    Just a comment regarding the secure signalling part and a solution to an issue I have encountered. If you are using a device with a static IP (and probably a fixed hostname), the CN field in the certificate should be set to that IP or hostname and everything will work fine.

     

    However, should you use a device with dynamic IP (roaming users), and you want to leverage TLS signalling, Asterisk will throw errors and terminate sessions if the CN on the certificate does not match the originating IP or hostname. An easy fix is to go into the tcptls.c file, remove the part on line 243 that returns a false if the hostname does not match the originating address and voila. I am not sure how that affects security (if at all) since I assume Asterisk checks whenever the signature on the certificate is the CA's (which is really the only cryptographic parameter that matters); but that's just my opinion. 

  18. Ed Guy

    Malcolm,

    what version of asterisk is required for this tutorial? 

    thanks

    /ed

    ( Hope you're enjoying vegas!) 

    1. Malcolm Davenport

      SRTP support was added in 1.8, TLS was added in 1.6.  The lessons contained within should apply to newer versions as well, though most of the differences are client differences - Blink doesn't have the same certificate file import screens that it used to.

      (big grin)

  19. Vladimir

    Hi! Can you help me in this situation: I have commercial certificate, and installed it as follows:

    sip.conf:

    [general]
    context=empty
    tlsenable=yes
    tlsbindaddr=0.0.0.0
    tlscertfile=/etc/asterisk/keys/cert.crt
    tlsprivatekey=/etc/asterisk/keys/private.key
    tlscafile=/etc/asterisk/keys/RapidSSL_CA_bundle.pem
    tlscipher=ALL
    tlsclientmethod=tlsv1
    [100]
    secret=pass100100
    type=peer
    host=dynamic
    nat=yes
    transport=tls
    [101]
    secret=pass101101
    type=peer
    host=dynamic
    nat=yes
    transport=tls

    iptables:

    -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
    -A INPUT -i lo -j ACCEPT
    -A INPUT -m conntrack --ctstate NEW -m tcp -p tcp --dport 22 -j ACCEPT
    -A INPUT -m conntrack --ctstate NEW -m udp -p udp --dport 5060 -j ACCEPT
    -A INPUT -m conntrack --ctstate NEW -m udp -p udp --dport 5061 -j ACCEPT
    -A INPUT -m udp -p udp --dport 10000:10100 -j ACCEPT
    -A INPUT -j REJECT --reject-with icmp-host-prohibited
    -A FORWARD -j REJECT --reject-with icmp-host-prohibited

    before I switched my configuration from udp to tls - users were registered and could to call each other

    now my sip-programs can't register, and in asterisk console there are no errors (with maximum verbose enabled). This situation difficult to troubleshoot, because traffic is encrypted, so tcpdump on port 5061 give me only encrypted information.

    and I'm sorry, I didn't find how to hide code into spoiler

  20. Ed Guy

    TLS is a TCP-based protocol.   You need to open tcp on port 5061 ( assuming you're using this port ) 
    You do not need udp on 5061. 

    /ed




     

  21. Vladimir

    thank you, Ed Guy.

    I repaired this problem in firewall.

    Now everything is ok on those SIP-softphones, which can to skip verifying ssl-certificate.

    If I'm trying to use program, which checks ssl-certificate, this program cannot connect, and in asterisk console I see:

    == Problem setting up ssl connection: error:14094418:SSL routines:SSL3_READ_BYTES:tlsv1 alert unknown ca
    [Dec 1 14:03:01] WARNING[1919]: tcptls.c:668 handle_tcptls_connection: FILE * open failed!

    May be it happens because certificate issued by non-root CA ?(rapid ssl)

     

    This happens even when I installed RapidSSL-CA in pem-format :

    mkdir /usr/share/ca-certificates/extra

    cp RapidSSL-CA.pem /usr/share/ca-certificates/extra/

    dpkg-reconfigure ca-certificates           # (and choose new CA via checkbox)


    Even when I put this file in zoiper -> settings -> advanced -> extra CA certificates -> path to CA file in pem format ; anyway, I still receive the same error in asterisk

     

    == Problem setting up ssl connection: error:14094418:SSL routines:SSL3_READ_BYTES : tlsv1 alert unknown ca


  22. Josh Adams

    Great article! I am working on implementing TLS/SRTP using PJSIP and am encountering errors with my certificate. Can you confirm that Asterisk PJSIP supports TLS encryption using a 2048-bit certificate?

    Thanks!

    Josh

    1. Rusty Newton

      I can't confirm, but I wanted to suggest bringing up that question on the asterisk-dev mailing list. A developer there would likely know or be able to find out.

      http://www.asterisk.org/community/discuss

      1. Josh Adams

        Good suggestion. Thanks!

  23. Evgeny Petrov

    openssl pkcs12 -export -out MySuperClientCert.p12 -inkey ca.key -in ca.crt -certfile asterisk.crt

    As far as i know, by doing it this way you will share your CA key file with all your users.

    Sad things may happen if there's a bad guy between them...

  24. Julien Le Van Suu

    Hi !

    Is it normal that if I don't put a client certificate, this works also ? The server don't seems to check client certificate ... Asterisk18 on openwrt