Freeswitch SIP Encryption

По общепринятому соглашению SIP сигнализация использует порт 5060 UDP (TCP тоже), a SIP с SSL/TLS шифрованием порт 5061, известное как SIPS.

Для передачи RTP используется UDP протокол.
Используемые порты назначаются динамически из заданного SIP протоколом диапазона.

Анатомия SIP соединений

Во-первых, давайте рассмотрим анатомию SIP-соединения, чтобы устранить любую путаницу, которая может возникнуть из предположения, что любое шифрование подразумевает, что аудио (RTP) потоки зашифрованы.

Рис 1: SIP Connection

На рисунке 1 мы видим три раздельных соединения, одно контрольное TCP и два аудио потока - входящий и нисходящий UDP. Канал управления облегчает многие задачи сигнализации, но по факту любой сниффер может перехватить передающиеся в нем данные, например тональные сигналы PIN кодов и т.п.

SIPS соединение

Рис 2: Secure SIP Connection

Решение этой проблемы представлено на рисунке 2 и представляет собой шифрование контрольных пакетов при помощи SSL или TLS. В этом случае уже непросто перехватить и расшифровать переданные данные. Но аудио потоки по прежнему не зашифрованы и доступны для прослушивания.

SIPS и SRTP

Рис 3: Secure SIP & Secure RTP

На третьем рисунке представлена схема при которой шифруется и SIP и RTP. RTP пакеты шифруются и передаются как SRTP. только в этом случае моно утверждать, что разговор полностью зашифрован. это также важно для DTMF сигналов передающихся inband. Только совместное использование SIPS и SRTP может дать какие-то гарантии шифрования.

Возможности шифрования FreeSWITCH

Данный документ рассматривает TLS/SSL и SRTP. ZRTP рассматривается только вскользь.

TLS/SSL и SRTP шифрование

FreeSWITCH поддерживает SIPS через SSL и/или TLS, совместно с SRTP шифрованием. Шифрование видео не поддерживается в данный момент.

ZRTP шифрование

ZRTP поддерживается Freeswitch «из коробки».

Гибридное шифрование

FS может шифровать трафик проходящий через него. Т.е. если к вас есть IP телефоны не поддерживающие шифрование, FS может шифровать трафик проходящий через него для другой стороны, поддерживающей шифрование.
Это находит свое применение во множестве практических ситуаций.

Рис 4

Тоже самое касается и шифрования SIPS совместно с SRTP.

Сравнение методов шифрования FS

Freeswitch предоставляет разные методы шифрования:

• ZRTP - Шифрование голоса,не требующее заранее сгенерированных ключей. Обмен ключами непосредственно в медиаканале. Недостатки: поддерживается малым количеством клиентов.
• TLSV1 шифрует и передает SIP сигнализацию по TCP. К недостаткам можно отнести большИе задержки при использовании TCP для передачи голоса по сравнению с UDP.
• SSLV23 - шифрует SIP сигнализацию по TCP с использованием SSL сертификатов. Если требуется шифрование голоса, SSLV23 нужно использовать с SRTP. SRTP шифрует аудио/медиа передающиеся по UDP.

UDP предпочтительней для RTP трафика т.к. минимизирует задержки. Ключи шифрования SRTP передаются по TCP с SSLV23 шифрованием. Связка SSLV23 + SRTP хорошо проходит файерволы. А также, что немаловажно, проста в настройке и поддерживается большим количеством IP телефонов и софтфонов.

Настройка TLS/SSL в Freeswitch

Fs должен быть скомпилирован с поддержкой ssl:

• libssl-dev (openssl-devel) пакет должен быть предварительно установлен.
• Если FS был скомпилирован до установки данного пакета, его надо перекомпилировать наново.

1 - Корневой сертификат УЦ (CA Root)

Скрипт для генерации поставляется с исходниками: {tarball}/scripts/gentls_cert или в /{prefix}/freeswitch/bin/gentls_cert.
Если FS установлен из репозитория - /usr/bin/gentls_cert:

./gentls_cert setup -cn pbx.freeswitch.org -alt DNS:pbx.freeswitch.org -org freeswitch.org

Будет создан сертификат УЦ и ключ в ../freeswitch/conf/ssl/CA и сертификат УЦ в ../freeswitch/conf/ssl директории.
Или же:

ls -1 /etc/freeswitch/tls/CA | grep pem
...
cacert.pem
cakey.pem
...

ls -1 /etc/freeswitch/tls | grep ca
...
cafile.pem
...

Вы можете изменить «DAYS=2190» параметр в файле gentls_cert, чтобы продлить действие сертификата подольше.

2 - Сертификат сервера

Команда:

./gentls_cert create_server -cn pbx.freeswitch.org -alt DNS:pbx.freeswitch.org -org freeswitch.org

создает сертификат сервера и приватный ключ /{prefix}/freeswitch/conf/ssl/agent.pem или /etc/freeswitch/tls/agent.pem . Файл agent.pem содержит сертификат и приватный ключ. Они в свою очередь содержат доменное имя в полях «common» и «alternate». Если требуется создать сертификат для стороннего сервера, задайте имя сертификата после флага -out, чтобы указать скрипту и скопируйте созданный файл на удаленный сервер.

Просмотр сертификата

Вы можете посмотреть данные сертификата командой:

 openssl x509 -noout -inform pem -text -in /etc/freeswitch/tls/agent.pem

3 - Настройка Sofia SIP Profile

Для работы в качестве TLS сервера FS использует только один файл: agent.pem. Именно он содержит сертификат и ключ шифрования.

chmod 640 /etc/freeswitch/tls/agent.pem

chmod 640 /etc/freeswitch/tls/CA/cacert.pem

chown root.freeswitch /etc/freeswitch/tls/agent.pem 

chown root.freeswitch /etc/freeswitch/tls/CA/cacert.pem

vars.xml:

  <!--
      SIP and TLS settings.
  -->
  <X-PRE-PROCESS cmd="set" data="sip_tls_version=sslv23"/>
 
  <!-- Internal SIP Profile -->
  <X-PRE-PROCESS cmd="set" data="internal_auth_calls=true"/>
  <X-PRE-PROCESS cmd="set" data="internal_sip_port=5060"/>
  <X-PRE-PROCESS cmd="set" data="internal_tls_port=5061"/>
  <X-PRE-PROCESS cmd="set" data="internal_ssl_enable=false"/>
  <X-PRE-PROCESS cmd="set" data="internal_ssl_dir=$${base_dir}/conf/ssl"/>
 
  <!-- External SIP Profile -->
  <X-PRE-PROCESS cmd="set" data="external_auth_calls=false"/>
  <X-PRE-PROCESS cmd="set" data="external_sip_port=5080"/>
  <X-PRE-PROCESS cmd="set" data="external_tls_port=5081"/>
  <X-PRE-PROCESS cmd="set" data="external_ssl_enable=false"/>
  <X-PRE-PROCESS cmd="set" data="external_ssl_dir=$${base_dir}/conf/ssl"/>

Также TLS параметры могут назначаться в конкретном SIP профиле:

 <!-- TLS: выключено по умолчанию, уст. "true" чтобы вкл. -->
    <param name="tls" value="true"/>
    <!-- Установите "true" чтобы использовать только TLS port -->
    <param name="tls-only" value="false"/>
    <!--Транспорт для TLS. А может быть другой? -->
    <param name="tls-bind-params" value="transport=tls"/>
    <!-- Порт на котором слушаются TLS запросы. (5061 по умолч. если ничего не назначено) -->
    <param name="tls-sip-port" value="5061"/>
    <!-- Местоположение  agent.pem and cafile.pem ssl сертификатов (для TLS сервера) -->
    <param name="tls-cert-dir" value="$${base_dir}/tls"/>
    <!-- Опционально установите кодовое слово  openSSL (если задано для приватного ключа) -->
    <param name="tls-passphrase" value=""/>
    <!-- Проверять срок годности TLS сертификата -->
    <param name="tls-verify-date" value="true"/>
<!-- Политики Проверки TLS сертификатов для исходящих или входящих регистраций и запросов
-->
<!-- Контролирует проверку сервер/клиент сертификатов.
'in' для входящих подключений
'out' для исходящиx
'all' для всех
а также 'in_subjects', 'out_subjects' и 'all_subjects'. Несколько политик могут быть заданы через '|' pipe - 'in_subjects|out'
'none' по умолчанию. -->
    <param name="tls-verify-policy" value="none"/>
    <!-- Certificate max verify depth to use for validating peer TLS certificates when the verify policy is not none -->
    <param name="tls-verify-depth" value="2"/>
    <!-- If the tls-verify-policy is set to subjects_all or subjects_in this sets which subjects are allowed, multiple subjects can be split with a '|' pipe -->
    <param name="tls-verify-in-subjects" value=""/>
    <!-- TLS version default: tlsv1,tlsv1.1,tlsv1.2 -->
    <param name="tls-version" value="$${sip_tls_version}"/>
 
    <!-- TLS ciphers default: ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH  -->
    <param name="tls-ciphers" value="$${sip_tls_ciphers}"/>

Дополнительные параметры TLS

Дополнительные параметры TLS могут быть назначены в SIP профиле. См.Sofia Tls.

Множество SIP TLS профилей

Если вы используете несколько Sofia SIP профилей с шифрованиеми и отдельными DNS записями для каждого профиля, то просто создайте директории в /etc/freeswitch/tls для каждой DNS записи и поместите в них agent.pem и cafile.pem. Далее укажите требуемую директорию содержащую нужный agent.pem в соответствующем параметре профиля tls-cert-dir:

  <param name="tls-cert-dir" value="/etc/freeswitch/tls/specific_dir"/>

4 - Настройка клиентов

Клиент должен, как минимум, иметь установленный сертификат удостоверяющего центра (УЦ), для обеспечения безопасности. Без включения проверки цепи (был ли сертификат сервера выпущен УЦ) возможна MITM (Человек Посередине) атака на клиент.

Дополнительно, возможно создать клиентский сертификат выпущенный УЦ. Для некоторых устройств это обязательно. Это можно сделать командой:

./gentls_cert create_client -cn Client1 -out Client1

Будет создан файл Client1.pem (пример), используйте собственное имя, какое угодно. Этот файл содержит пару «сертификат/ключ» и устанавливается на клиент (рекомендуется разные серт. для каждого клиента, но не обязательно). Эти серт. не требуется хранить на сервере.

Коммерческие сертификаты

Пример использования сертификата Letsencrypt в Freeswitch

Взято из скрипта ./letsencrypt.sh FusionPBX

	#Убедитесь, что нужная директория существует
	mkdir -p /etc/freeswitch/tls
 
	#Удалите или переместите все существующие файлы из директории для ключей freeswitch
	rm /etc/freeswitch/tls/*
 
	#объедините сертификаты в один - all.pem
	cat /etc/letsencrypt/live/pbx.freeswitch.org/fullchain.pem > /etc/freeswitch/tls/all.pem
	cat /etc/letsencrypt/live/pbx.freeswitch.org/privkey.pem >> /etc/freeswitch/tls/all.pem
 
	#скопируйте сертификаты
	cp /etc/letsencrypt/live/pbx.freeswitch.org/cert.pem /etc/freeswitch/tls
	cp /etc/letsencrypt/live/pbx.freeswitch.org/chain.pem /etc/freeswitch/tls
	cp /etc/letsencrypt/live/pbx.freeswitch.org/fullchain.pem /etc/freeswitch/tls
	cp /etc/letsencrypt/live/pbx.freeswitch.org/privkey.pem /etc/freeswitch/tls
 
	#создайте символические ссылки
	ln -s /etc/freeswitch/tls/all.pem /etc/freeswitch/tls/agent.pem
	ln -s /etc/freeswitch/tls/all.pem /etc/freeswitch/tls/tls.pem
	ln -s /etc/freeswitch/tls/all.pem /etc/freeswitch/tls/wss.pem
	ln -s /etc/freeswitch/tls/all.pem /etc/freeswitch/tls/dtls-srtp.pem

cp /etc/letsencrypt/live/pbx.freeswitch.org/* /etc/freeswitch/tls/
cd /etc/freeswitch/tls/
cat fullchain.pem privkey.pem > wss.pem
cat cert.pem privkey.pem > agent.pem
cat chain.pem > cafile.pem

Использование Freeswitch как SSL/TLS клиент

Freeswitch может коммуницировать с другим сервером, выступая в качестве клиента. Для этого вы должны иметь cafile.pem на клиенте в директории /etc/freeswitch/tls с сертификатом УЦ. Вам также понадобится файл agent.pem (это может быть произвольно созданная пара открытого / закрытого ключа или действительный сертификат клиента) в той же папке, что и клиентский сертификат.

Быстрая настройка SSLv23 + SRTP

Быстрая настройка «Internal Profile», предположим, что имя хоста: pbx.freeswitch.org

./gentls_cert setup -cn pbx.freeswitch.org -alt DNS:pbx.freeswitch.org -org freeswitch.org
./gentls_cert create_server -cn pbx.freeswitch.org -alt DNS:pbx.freeswitch.org -org freeswitch.org

Если клиенты поддерживают проверку сертификата сервера, скопируйте cafile.pem на клиент

В конфиге vars.xml

<X-PRE-PROCESS cmd="set" data="sip_tls_version=sslv23"/>
<X-PRE-PROCESS cmd="set" data="internal_ssl_enable=true"/>

Укажите для клиентов порт 5061 вместо 5060 и включите TLS и SRTP на клиентах. Если клиент другой FS, установите «transport=tls», для параметра tls-bind-params в дополнение к вышепепечисленным параметрам сервера. И наконец, для включения поддержки SRTP используйте rtp_secure_media=true в строке набора.

Перезагрузите FS или mod_sofia и зарегистрируйте клиентов. Для повышения безопасности, проверьте все параметры TLS и включите проверку сертификатов (чтобы обезопаситься от Человека_посередине).

Step 5 - Securing the RTP Channels (optional)

Calls that originate from the phone have rtp_secure_media set if TLS is set up. Check the global extension. There is a section commented that out will require SRTP on the outbound leg if the inbound leg is encrypted. Enabling this will be problematic with most ITSPs since they do not support TLS.

For calls that originate from (or are routed through) FreeSWITCH and are terminated on the user/ endpoint (e.g., calls to a phone), the following change will enable SRTP if the endpoint registered with TLS. Note that it is a valid configuration to register with TLS but not require SRTP. This disables that valid configuration option for user/ endpoints. It would also require further refinement to support ZRTP on user/ endpoints that connect with TLS. In that case, a better approach would be to set something on the user's directory entry that specifies which RTP encryption to support. (In other words, there is a reason this is not the default setting.)

Edit conf/directory/default.xml and change the dial-string param to:

 <param name="dial-string" value="{rtp_secure_media=${regex(${sofia_contact(${dialed_user}@${dialed_domain})}|(transport=tls|transport=TLS))},presence_id=${dialed_user}@${dialed_domain}}${sofia_contact(${dialed_user}@${dialed_domain})}" />

rtp_secure_media=${regex(${sip_contact_params}|(transport=tls|transport=TLS))}

Why it's a good idea

In the SIP Encryption Primer above we discussed why encrypting the RTP data may be a good idea. This is largely done in the dialplan and has its own page dedicated to its functionality.

SRTP by itself without TLS is not secure since the keys are exchanged between the two endpoints in the clear over SIP, which is insecure without TLS or SSL.

See Secure RTP page of the FreeSWITCH Wiki for how to deploy SRTP.

For completely secure connection (signaling + media) use TLS + SRTP. TLS without SRTP secures SIP. SRTP without TLS does not really secure RTP!

Troubleshooting

Issues with TLSV1

If you've opted for this configuration in your sip_profile:

<param name="tls-version" value="tlsv1"/>

There are a number of gotchas and snafus possible with TLS. TLS runs on TCP, rather than UDP, so make sure any firewalls are configured to work with TCP. Generate the proper certificate, and make sure it's loaded into the phone or ATA. Also, ensure that the time is configured properly on your endpoint as you will get cryptic «bad certificate» error messages if the time is too far off, and it will fail to handshake properly. (For example, certificates have «not valid before» and «not valid after» attributes.) If your phone won't register, or fails to work properly, you might consider checking the Interoperability list, and/or your phones documentation and firmware revision. If it still fails to work properly, you might consider sslv23 as a fallback.

Issues with SSLV23

If you've opted for this configuration option in your sip_profile:

<param name="tls-version" value="sslv23"/>

This will give you the ability to encrypt the data. Security is similar to that of with web servers, certificate trusted roots can be checked, client certificate authentication is supported, subjects and cert dates can be validated (some of these do depend on client support for the feature). This may in fact be what you want, and considering that several phones do not support TLS, but do support SSL, you may want to configure accordingly.

If your SIP profile fails to start up

If you go into the FreeSWITCH CLI and type:

sofia status

You might find that your sip_profile for which you configured the TLS/SSL settings is missing. Should that be the case, you're probably missing the libssl-dev package or the agent.pem file is not in place or has incorrect permissions. Ensure the user FreeSWITCH runs as has read permissions to the certificates and keys. Turning on sofia tport debug logging to high will help print out errors on why it is not starting up properly. Refer to your distribution in order to install the OpenSSL development package. This is necessary for the code which performs the encryption within FreeSWITCH to be compiled into the binary. Enabling a higher level of debug in sofia (sofia loglevel all 9, or sofia loglevel tport 9 generally give enough) and in the console can help debug issues and handshake problems.

TLS Negotiation Error 'No matching cipher'

If you receive a 'no matching cipher' error message, first check to ensure you have concatenated your certificate key into your agent.pem file. If you still receive the error, regenerate both the key and the certificate and make a new agent.pem with the new key and certificate, then try again.

Further Debugging Steps

If you are still having issues getting TLS running the following are suggested:

• ) set sofia loglevel to 9 (<param name=«log-level» value=«9»/>) in autoload_configs/sofia.conf.xml
• ) Set freeswitch console loglevel to debug (F8)
• ) Reload mod_sofia and review the the logs
• ) If everything looks fine on the server side, try using freeswitch or a freeswitch based Softphones like FSClient or FSComm. These will allow you to do the same on the client side (including attach fs_cli to them to get log data) to try and see any errors the client may be having
• ) Last resort put all the logs on pastebin and ask for help.

Step 6 - DNS NAPTR & SRV Records (optional)

Configuring DNS NAPTR and SRV for TLS

This isn't required as TLS will function without it, but it is recommended. If you're going to set up TLS you might take the time to set up the correct DNS SRV and NAPTR records.

Here is an example of the NAPTR records you will need (make subtitutions for «domain.com» as necessary):

domain.com.               IN      NAPTR 10 0       "s"     "SIPS+D2T"  "" _sips._tcp.domain.com.                                                                              
domain.com.               IN      NAPTR 20 0       "s"     "SIP+D2T"   "" _sip._tcp.domain.com.                                                                                
domain.com.               IN      NAPTR 30 0       "s"     "SIP+D2U"   "" _sip._udp.domain.com.    

If you configure with –enable-sctp and have sctp loaded on Linux you can add this record:

domain.com.               IN      NAPTR 10 0       "s"     "SIPS+D2S"  "" _sip._sctp.domain.com.

Then you will want to set up these SRV records in addition to the above NAPTR:

_sips._tcp.domain.com.       IN      SRV 10 0 5061   sip.domain.com.                                                                                                       
_sip._udp.domain.com.        IN      SRV 10 0 5060   sip.domain.com.                                                                                                       
_sip._tcp.domain.com.        IN      SRV 10 0 5060   sip.domain.com.   

If you configure with –enable-sctp and have SCTP loaded on Linux you can add this record:

_sip._sctp.domain.com.       IN      SRV 10 0 5060   sip.domain.com.

Example: Snom phones will fully honor both the NAPTR and SRV as will Sofia-SIP on outbound calls originating from FreeSWITCH.

SIP TLS Device Interoperability

troubleshooting

• SERVICE_NOT_IMPLEMENTED - не поддерживается набор протоколов шифрования аудио