Skip to content

Latest commit

 

History

History
131 lines (100 loc) · 7.39 KB

README.md

File metadata and controls

131 lines (100 loc) · 7.39 KB

Jabber4Linux

It is annoying that companies always forget to implement their software for the most important operating system. Cisco even offers a native Linux AnyConnect client - but no Cisco Jabber Linux client. Unfortunately, the Windows binary doesn't perform well via Wine and I couldn't get any other Linux-native 3rd party softphone working with our Cisco telephone system, that's why we need another solution.

Jabber4Linux is an unoffical Linux port of the Cisco Jabber application for macOS and Windows, written in pure Python. Warning: extremely experimental. Please note that the scope of this project is to emulate the softphone functionality compatible with Cisco CUCM. For chat/XMPP you can use other clients like Pidgin.

Please note that this implementation does not support OAuth since I don't have access to a CUCM server with OAuth enabled. OAuth is a more comfortable alternative to the client certificate negotiation via CAPF. If you can provide a test account for this to implement, please contact me.

What it can:

  • server auto discovery via DNS SRV record _cisco-uds._tcp
  • getting user's device information via Cisco UDS REST API
  • mimic Cisco Jabber SIP(S) registration
    • optional: force registration (disconnect an other client which is already active and holds the line)
  • initiate and accept calls
  • realtime de-/encoding of RTP packets with codecs: PCMA, PCMU, Opus (HD telephony)
  • company phone book search
  • local address book with option to set custom ringtones per contact
  • handle "tel:" parameter/links (from websites)
  • SIPS (encrypted registration)
  • call subjects

What (currently) doesn't:

  • input/output audio device (headset) and ringtone devices selection
  • presence / instant messaging
  • voice mail access
  • conference features
  • call transfer
  • video telephony
  • SRTP/ZRTP encrypted calls

You can put Jabber4Linux in your autostart with parameter --hidden to start it only with the tray icon. --new-instance allows you to start a second instance for using multiple softphones at once.

For debugging / reporting bugs, please start Jabber4Linux from Terminal with parameter --debug and have a look and report the debug output.

Stars & contributions welcome!

Installation

Debian Package

You can download and install the .deb package from the latest release on GitHub.

Manual Installation

For Debian & Ubuntu >= 22.04:

# install system-wide dependencies from Debian/Ubuntu repos
apt install python3-requests python3-dnspython python3-pyqt5 portaudio19-dev python3-watchdog python3-cryptography python3-filelock python3-pip python3-venv python3-setuptools libopus0 libbcg729-0

# create a new Python venv dir
python3 -m venv --system-site-packages venv

# install it with requirements which are not available in Debian/Ubuntu repos in the venv
venv/bin/pip3 install .

# start manually
venv/bin/jabber4linux

# install launcher shortcut
cp assets/jabber4linux.desktop /usr/local/share/applications
sudo update-desktop-database

Dark Mode

Qt applications automatically adopt the system theme on Linux Mint (Cinnamon desktop) due to the preinstalled qt5-gtk2-platformtheme. For plain Ubuntu/Debian using the Gnome desktop, you need to install this package and set the environment variable QT_QPA_PLATFORMTHEME=gtk2 before starting the app. Alternatively, you can use the package qgnomeplatform-qt5 with the environment variable QT_QPA_PLATFORMTHEME=gnome (only on newer Ubuntu versions).

SIP Transport Encryption (SIPS)

Your CUCM administrator can choose whether your softphone should operate encrypted using SIPS (this option is called "Secure" in the management interface) or unencrypted using plaintext SIP ("Non-Secure").

Besides SIP, SIPS is also supported by Jabber4Linux. For the TLS connection, a client certificate (called "LSC" - Locally Significant Certificate) is necessary, which is signed using the Cisco CAPF protocol on port 3804 of a specific CUCM server in your cluster.

The pitfall is that such a certificate is only issued once; every further signing request will be denied by the CUCM server. If you already used Cisco Jabber on Windows before, you need to export the softphone certificate from the Windows cert store. Alternatively, you can contact your CUCM admin who can reset your softphone configuration. This will allow your client to get a new certificate once again. Jabber4Linux will automatically try to get such a certificate when doing the SIP registration.

The normal workflow seems to be that the phone has to operate at least once in "Non-Secure" mode first to get the LSC (Trust On First Use, TOFU principle). Then, the softphone is manually set to "Secure" by a CUCM administrator. Only after that, the connection is TLS encrypted.

Export Client SIPS Certificate from Windows Cert Store
  1. Log in into Cisco Jabber on a Windows machine.
  2. Open the user cert store (certmgr.msc) and navigate to "Own Certificates" -> "Certificates".
  3. Export your Cisco Jabber certificate by right-clicking it -> "All Tasks" -> "Export".
    • Choose "Yes, export private key".
    • Choose format "PKCS #12 (.PFX)".
    • Choose a password to protect the file.
  4. On your Linux machine, convert the file into PEM format: openssl pkcs12 -in jabbercert.pfx -out jabbercert.pem -nodes.
  5. Move the PEM file into ~/.config/jabber4linux/client-certs. Create the directory if it does not exist.
  6. Start Jabber4Linux and login.
UDS/SIPS Server Certificate Pinning

In addition to that, server certificates of Cisco CUCM used for SIPS are often self-signed (unlike those used for the UDS API and web interface). You can put all server certificates which should be trusted inside ~/.config/jabber4linux/server-certs and they will automatically be loaded.

Development

I18n

# 1. Create translation files from code
pylupdate5 certuploader.py -ts lang/de.ts

# 2. Use Qt Linguist to translate the file

# 3. Compile translation files for usage
lrelease lang/de.ts

Resources

Reverse engineering findings were documented in the docs folder. Wireshark was the biggest help for this project.

Helpful links:

Support

You can hire me for commercial support or adjustments for this project. Please contact me if you are interested.