This document is intended as a supplement to the official configuration guide. The configuration and troubleshooting of JTAPI using SSL will be covered with examples and diagrams.
Please reference the following Secure CTI configuration guide for complete and official instructions for configuring the secure CTI / JTAPI integration.
Enable the Certificate Authority Proxy Function (CAPF), Certificate Trust List Provider (CTL), and CTIManager services.
Run the CTL client with USB eTokens on a workstation to connect to the cluster, generate a CTL file, and move the cluster to Mixed Mode.
On the Device > Phone page check "Allow Control of Device from CTI" for the phone you want to monitor / control.
Associate your End User or Application User with the phone.
Add the user to the groups CTI Enabled, CTI Secure Connection, and CTI Allow Reception of SRTP Key Material (Note: Adding the user to the Secure CTI and SRTP Key Material groups means that this JTAPI user will ONLY be allowed to connect on the secure port of 2749 using certs. To connected on a non secure port later, remove the user from these secure groups)
Under Users > End / Application User CAPF Profile, select the certificate operation of Install / Upgrade for the JTAPI user.
After restarting the CUCM server you will now have CCM listening on TCP port 2443 for secure SCCP connections and CTIManager listening on 2749 for secure JTAPI/QBE connections. The TFTP process will be providing a CTL file. The CAPF service on the publisher will be providing certificates to any client that securely connects on TCP 3804 and has a certificate operation of Install / Upgrade.
JTAPI Client Config
Install the Cisco JTAPI Client on the server or client PC where JTAPI will be running. Make sure to download JTAPI for either Windows or Linux.
Under either the Start Menu, or the JTAPITools directory, find the JTAPI Preferences tool.
If you're trying to set this up for the first time I recommend turning on ALL the tracing
Add your CUCM CTIManager servers under Cisco Unified CM.
Under Security set the following settings and click "Update Certificate". The Authentication String and Instance ID must match the User's CAPF Profile.
Now we're ready to verify the secure connection with the JTrace tool below.
Now that we have the JTAPI integration configured we want to test that it actually works! We can do this by taking control of a single device with a Cisco provided JTAPI application. If you're ever unsure of whether the problem is with JTAPI, or a customer JTAPI application, you can use JTrace to verify.
In our JTAPITools directory (typically C:\Program Files\JTAPITools) look for the jtrace folder, and the readme.htm for full instructions.
JTrace takes arguments in the following form:
java jtrace.JTrace <CTI Server IP> <JTAPI user> <password> <directory number>
JTrace does not support Instance IDs. If you have one user with multiple Instance IDs (implying mutltiple certificates) do not use JTrace, or it may invalidate your existing certificates by marking them as comprimised since a connection may be made with the wrong certificate to the wrong instance.
You launch JTrace from a cmd window in the JTAPITools directory
When the JTAPI connection to CTIManager is successful and the line and device are opened, two windows pop up.
The first window logs information about the JTAPI Provider that is opened. It will list all of the lines and devices associated with the JTAPI user selected.
The second window will show the actual device that is opened, and any events that JTAPI receives for that device. Here we can see the opened phone (8012001) is receiving a call from 8011111.
The JTrace tool can help identify whether or not a JTAPI connection to the CTIManager server can be established and events received. The error messages displayed in the two new JTrace windows or the cmd window can also help diagnose any issues.
As a sanity check, leave security disabled in the JTAPI Client JTPrefs and run JTrace. Once a non secure connection can be established then enable security and test again. (Note: This requires adding and removing the user from the two secure CTI Groups in CCMAdmin)
For more advanced troubleshooting turn to the logs.
The logs can be found under the JTAPITools installation directory (by default C:\Program Files\JTAPITools) They follow the format of CiscoJTAPIXX.log.
Look for the following sequence of messages to verify the JTAPI client connected to the CTIManager server and logged in successfully.
Opening server "22.214.171.124" login "jasburns"
Trying to create TLS/SSL socket connection to 126.96.36.199
If at any point in the logs an error appears that is a large negative number or a large hex number starting with 0x8CC you can look it up with this magic CTI Error Decoder Ring.
One of the most common errors is
This error may appear either in the above hex, or if in decimal it can be converted using calc. The decoded text points to a problem with login credentials or the login process.
JTAPI Security Logs
Security logs will show important details regarding the CTL Download and the encapsulated CAPF Certificate. They follow the format of CiscoJtapiSecurityXX.log
Wireshark is a useful capture tool to analyze the steps in the secure JTAPI configuration and connection process. Almost everything about the secure JTAPI process can be learned by taking a packet capture on the PC or server where the JTAPI Client is installed.
The first important step happens when clicking "Update Certificate" in the JTAPI Configuration window. The JTAPI Client downloads a CTL file via TFTP (UDP port 69) from the configured TFTP server. This CTL file contains the CAPF Server Certificate
After downloading the CTL File and storing it in the keystore folder, the JTAPI Client has to make a TLS connection to the CAPF Server on TCP 3804. JTAPI compares the cert the CAPF server presents to the one embedded in the CTL file to make sure the connection is trusted. Filter on tcp.port == 3804. It will be necessary to right click any packet in this stream and select "Decode As" > "SSL" for both the source and destination ports so Wireshark knows to decode a stream on these ports as an SSL / TLS session.
If for some reason the CAPF Certificate in the CTL file doesn't match the CAPF certicicate presented in the TLS Handshake we need to walk through the following steps:
Verify the Subject CN and expiration date of the CAPF cert installed in the OS Admin of the publisher server.
Run the CTL Client to insert the latest CAPF certificate into the CTL file.
Restart the TFTP service.
After the JTAPI Client makes a secure connection to the CAPF service, we walk through the operation set in the CAPF Profile. In the case above that means "Install / Upgrade". A new Keystore will be created that contains the key and certificate obtained via CAPF in the default keystore location.
Now that the JTAPI Client has a CTL File and certificate we're ready to connect to the secure CTIManager. Fire up JTrace as mentioned earlier and filter on tcp.port == 2749. Don't forget to decode as SSL.