This feature lets
JTAPI applications communicate with CTIManager through a secure connection.
CTIManager runs a TLS listener socket to accept connections from JTAPI.
Establishing a TLS connection requires a client certificate, which the server
uses to authenticate the client, and a server certificate, which the client
uses to authenticate the server.
In the
Cisco Unified Communications Manager environment, the
server certificate exists in the form of CTL on the TFTP server, and JTAPI
downloads this certificate. The initial download of CTL is trusted and occurs
without verification, so Cisco strongly recommends performing this download in
a secure environment. One of the two System Administrator Security Tokens
(SAST) that are present in the CTL file signs the CTL; subsequent CTL downloads
get verified with the SAST from the old CTL file.
JTAPI connects to
CAPF by using the CAPF protocol to get the client certificate (LSC). You can
authenticate these certificates with the issuers certificate present in CTL.
CTI tracks the
number of provider connections that are created per client certificate.
Applications can create only one provider by using a client certificate. If
more than one instance of a provider is created, both providers get
disconnected from CTI and go out of service. JTAPI will retry the connection to
CTI to bring the original provider in service; however, if both instances of
provider continue to exist, after a certain number of retries, provider gets
permanently shut down, and the client certificate is marked as compromised. Any
further attempt to create a provider by using this client certificate fails.
Applications must contact the administrator to configure a new instanceId and
download a new client certificate to resume operation.
Note
|
Each client
certificate is associated with a unique instanceId configured in the
Cisco Unified Communications Manager database.
Applications can provide an instanceId in providerString as an optional
parameter to use a unique certificate while creating a CiscoProvider.
|
Note
|
From Release 15SU2 onwards, JTAPI supports TLS 1.3. However, TLS 1.3 support depends on the Java version used. Java version
1.8 (minor version 261) onwards supports TLS 1.3. CiscoJTAPI supports Java 1.8.
The supported ciphers when communicating with CAPF are as follows:
FIPS enabled: TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
FIPS disabled: TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
The supported ciphers when communicating with CTI Manager are as follows:
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA
|
To run multiple
instances of applications with TLS, ensure that the application user is
configured in the
Cisco Unified Communications Manager database with
multiple instanceIDs. Applications use these unique instanceIDs to get unique
client certificates for each instance.
The JTAPI
preferences application provides a graphic user interface to configure the
Security parameters and update server/client certificates. Application users
need to configure the TFTPServer IP address, CAPFServer IP address, Username,
InstanceID, and AuthorizationString parameters through the JTAPI preferences to
download/install certificates on the application server.
New interfaces are
provided for JTAPI client applications on the client layer object. For example,
a JTAPI client interface is provided on the CTIClientProperties class.
This feature is
backward compatible with previous releases as JTAPI Applications can still
connect to CTIManager on non-secure socket connections.
The following sections describe the interface changes for TLS support in JTAPI.
CiscoJtapiPeer.getProvider()
public javax.telephony.Provider getProvider(java.lang.String providerString)
throws javax.telephony.ProviderUnavailableException
This modified
interface takes a new optional parameter InstanceID. It returns an instance of
a Provider object, given a string argument that contains the desired service
name.
Optional
arguments may also be provided in this string, with the following format:
< service name > ; arg1 = val1; arg2 = val2; ...
Where <
service name > is not optional, and each optional argument = value pair that
follows is separated by a semicolon. The keys for these arguments are
implementation-specific, except for two standard-defined keys:
CiscoJtapiPeer
in providerString expects a new optional argument:
InstanceID is
needed when two or more instances of an application want to connect to Provider
(CTIManager) through a TLS connection from the same client machine. Each
instance of an application requires its own unique X.509 certificate to
establish a TLS connection. If JTAPI attempts to open more that one connection
with same username/instanceID, CTIManager rejects the TLS connection. If
instanceID is not provided, JTAPI randomly picks one of the instances of USER
and, in that case, the connection may fail if a connection for the selected
Instance already exists.
If the argument
is null, this method returns some default provider as determined by the
JtapiPeer object. The returned provider is in the Provider.OUT_OF_SERVICE
state.
- Post-conditions:
-
this.getProvider().getState() = Provider.OUT_OF_SERVICE
- Specified
by
-
getProvider
in
interface
javax.telephony.JtapiPeer
- Parameters
-
providerString
The name of the desired service plus an optional argument.
- Returns
-
An
instance of the Provider object.
- Throws
-
javax.telephony.ProviderUnavailableException
Indicates that a provider that corresponds to the given string is
unavailable.
CiscoJtapiProperties
JTAPI provides
an interface on CiscoJtapiProperties to enable or disable the security option
and install the client/server certificates that are required to establish a
secure TLS socket connection.
com.cisco.jtapi.extensions
Interface CiscoJtapiProperties
getSecurityPropertyForInstance
public java.util.Hashtable getSecurityPropertyForInstance()
This interface
returns a Hash table with all the parameters set for User/InstanceID. The Hash
table gets set with the following
"key–value"
pairs:
KEY
|
VALUE
|
"user"
|
userName
|
string
"instanceID"
|
InstanceID
|
string
"AuthCode"
|
authCode
|
string
"CAPF"
|
capfServer IP-Address
|
string
"CAPFPort"
|
capfServer IP-Address port
|
string
"TFTP"
|
tftpServer IP-Address
|
string
"TFTPPort"
|
tftpServer IP-Address port
|
string
"CertPath"
|
certificate Path
|
string
"securityOption"
|
Boolean security option(true for enable/ false for disabled)
|
string
"certificateStatus"
|
Boolean certificate status(true for updated/ false for not
updated)
|
Returns—Hash table in
the format described previously for the first user and instance.
getSecurityPropertyForInstance
public java.util.Hashtable getSecurityPropertyForInstance
(java.lang.String user, java.lang.String instanceID)
This interface
returns a Hash table with all the parameters set for User/InstanceID. The Hash
table is set with the following
"key–value"
pairs:
KEY
|
VALUE
|
"user"
|
userName
|
string
"instanceID"
|
InstanceID
|
string
"AuthCode"
|
authCode
|
string
"CAPF"
|
capfServer IP-Address
|
string
"CAPFPort"
|
capfServer IP-Address port
|
string
"TFTP"
|
tftpServer IP-Address
|
string
"TFTPPort"
|
tftpServer IP-Address port
|
string
"CertPath"
|
certificate Path
|
string
"securityOption"
|
Boolean security option(true for enable/ false for disabled)
|
string
"certificateStatus"
|
Boolean certificate status(true for updated/ false for not
updated)
|
Parameters:
user
- UserName
for which you want security parameters
instanceID
-
InstanceID for which you want security parameters
Returns—Hash table in
preceding format.
setSecurityPropertyForInstance
public void setSecurityPropertyForInstance(java.lang.String user, java.lang.String instanceID,
java.lang.String authCode,
java.lang.String tftp,
java.lang.String tftpPort,
java.lang.String capf,
java.lang.String capfPort,
java.lang.String certPath,
boolean securityOption)
You can use this
interface to set security properties for the following parameters:
Parameters:
user
—UserName
for which the security parameter is being updated
instanceID
—InstanceID for which the security parameter
is being updated
authCode
—Authorization string
capf
—IP-Address
of CAPF server
capfPort
—IP-Address port number on which the CAPF
server is running, as defined in a CallManager Service parameter. If the value
is null, the default value is 3804.
tftp
—IP-Address
of TFTP server
tftpPort
—IP-Address port number on which the TFTP
server is running. The
Cisco Unified Communications Manager TFTP server
usually runs on port 69. If the value is null, the default value is 69.
certPath
—Path
where certificate needs to be installed
updateCertificate
public void updateCertificate(java.lang.String user,
java.lang.String instanceID,
java.lang.String authcode,
java.lang.String ccmTFTPAddress,
java.lang.String ccmTFTPPort,
java.lang.String ccmCAPFAddress,
java.lang.String ccmCAPFPort,
java.lang.String certificatePath)
This interface
installs an X.509 client certificate for the USER instance in the certificate
store by connecting to the
Cisco Unified Communications Manager Certificate
Authority Proxy Function (CAPF) server. Italso downloads the Certificate Trust
List (CTL) from the
Cisco Unified Communications Manager TFTP server.
If the user
credentials are not valid, this method throws a PrivilegeViolationException. If
the TFTP server or CAPF server address is not correct, this method throws an
InvalidArgumentException. Every instance of an application requires a unique
client certificate. If a multiple instanceID is configured in the
Cisco Unified Communications Manager database,
applications can call this interface multiple times to install a client
certificate for every instance.
Pre-conditions—When
calling this interface, an application should have network connectivity with
the
Cisco Unified Communications Manager CAPF and TFTP
servers.
Post-conditions—This
process installs client and server certificates on the JTAPI application
machine.
Parameters:
user
—Name of the
CTI application user that is configured in the
Cisco Unified Communications Manager database
instanceID
—Application instance ID that is configured
in the
Cisco Unified Communications Manager database.
Everyinstance of an application requires a unique ID.
authCode
—Authorization string that is configured in the
Cisco Unified Communications Manager database. You can
use the authCode only once for getting certificates.
ccmTFTPAddress
—IP-Address of the
Cisco Unified Communications Manager TFTP server.
ccmTFTPPort
—IP-Address port number on which the
Cisco Unified Communications Manager TFTP server is
running. The
Cisco Unified Communications Manager TFTP server
usually runs on port 69. Ifnull, the default value is 69.
ccmCAPFAddress
—IP address of the
Cisco Unified Communications Manager CAPF server.
ccmCAPFPort
—Port
number on which the
Cisco Unified Communications Manager CAPF server is
running, as defined in the
Cisco Unified Communications Manager Service
parameters. If the value is null, the default value is 3804.
certificatePath
—Directory path where the certificate
needs to be installed
Throws:
InvalidArgumentException
—This exception gets thrown for
an invalid TFTP server or CAPF server address.
PrivilegeViolationException
—This exception gets thrown
for an invalid user, instanceID, or authCode.
IsCertificateUpdated
public boolean IsCertificateUpdated
(java.lang.String user, java.lang.String instanceID)
This interface
provides information about whether client and server certificates are updated
for a given user/instanceID.
Parameters:
user
—UserName as
defined in the
Cisco Unified Communications Manager Administration.
instanceID
—InstanceID for the specified UserName.
Returns—True if
certificates are already updated; false if certificates are not updated.
updateServerCertificate
public void updateServerCertificate(java.lang.String ccmTFTPAddress,
java.lang.String ccmTFTPPort,
java.lang.String ccmCAPFAddress,
java.lang.String ccmCAPFPort,
java.lang.String certificatePath)
This interface
installs an X.509 server certificate that is given the certificate path. If the
TFTP server address is not correct, this method throws an
InvalidArgumentException. Auto update applications should use this interface to
update the server certificate before invoking an HTTPS connection with
Cisco Unified Communications Manager.
Pre-conditions—When
calling this interface, applications should have network connectivity with the
TFTP server.
Post-conditions—This
interface installs the server certificate on the JTAPI application machine.
Parameters:
ccmTFTPAddress
—IP address of the Cisco CallManager TFTP
server.
ccmTFTPPort
—Port
number on which the
Cisco Unified Communications Manager TFTP server is
running.
If null, the
default value is 69.
certificatePath—Directory path for installing the certificate.
ccmCAPFAddress
—IP address of the
Cisco Unified Communications Manager CAPF server.
ccmCAPFPort
—Port
number on which the
Cisco Unified Communications Manager CAPF server is
running.
If the value is
null, the default value is 3804.
Throws:
InvalidArgumentException
—If the TFTP server address is
invalid.
Interface
Provided on JTAPI Preferences
The JTAPI
Preferences dialog box includes a Security tab to let application users
configure the username, instanceId, authCode, TFTP IP address, TFTP port, CAPF
IP server address, CAPF server port, and certificate path, and enable secure
connection.
-
"CAPF server port" number defaults to 3804.
You can configure this value in the Cisco Unified Communications Manager Administration service parameters window. The CAPF server port value entered through JTAPI Preferences should match the one that is configured
in Cisco Unified Communications Manager Administration.
-
"TFTP server port" number defaults to 69.
Do not change this value unless you are advised to do so by the System Administrator.
-
"Certificate Path" is where the application wants the sever and client certificates to be installed.
If this field is left blank, the certificates get installed in the ClassPath of JTAPI.jar.
-
"Certificate update Status" provides information on whether a certificate has been updated or not.
-
You must select "Enable Secure Connection" to enable a secure TLS connection to Cisco Unified Communications Manager.
If "Enable Security Connection" is not selected, JTAPI makes a non-secure connection to CTI even if the certificate is updated/installed.
-
The "Enable Security Tracing" check box lets you enable or disable tracing for the certificate installation operation.
If tracing is enabled, you can select three different levels, Error, Debug, or Detailed, from the drop-down menu.
You can use the
JTAPI Preference UI to configure a security profile for one or more than one
userName/instanceID pair. When application users revisit this window, and have
previously configured security profile for a userName/instanceID pair, the
security profile automatically gets populated when the user enters a
username/instanceID and clicks on other edit box.
The Trace Levels
tab in the JTAPI Preferences UI is renamed as JTAPI Tracing. This highlights
the fact that the JTAPI Tracing tab only lets you change trace setting for the
JTAPI layer. Tracing for the installation of Security certificates must be
enabled on the Security tab.