Configuring Voice Platform security

You can set up secure connections for Voice Platform using the certificates and keys that you used while securing the connections in Speech Suite. To secure the connections, you must complete the procedures to configure the application server and the Voice Browser service parameters.

Creating JKS client and server keystores for testing purposes

Several methods are available for creating keystores. These instructions provide one example and are not recommended for a production environment.

You can create a keystore using Java Keytool with the following command:

> keytool -genkeypair -alias alias -keyalg RSA -dname "CN=IP_address,OU=dept,O=company,L=city,S=state,C=country" -keypass keypassword -keystore name.jks -storepass storepassword
Argument

Description
alias The identifier to be used for access to this keystore entry (case-insensitive).
IP_address The IP address of the client or the server.
dept The department or organizational unit of the company.
company The name of the company or organization.
city The city where the company is located.
state The state or province where the company is located.
country The two-letter code for the country in which the company is located.
keypassword The password required for access to this keystore entry.
name.jks The full pathname to the JKS keystore.
storepassword The password used to protect the integrity of the keystore.

You need to create the test client keystore and the test server keystore. For example, you could use the following commands to create the client keystore called client.jks:

> keytool -genkey -alias clientkey -keyalg RSA -dname "CN=10.200.50.15,OU=Development,O=Highwinds,L=Winter Park,S=FL,C=US" -keypass mypass -storepass hell0 -keystore client.jks

Adding the client public certificate to the test server keystore

Each keystore has a private key within it which cannot be exported. To allow the client to share a certificate with the server, you use Java Keytool to export a public version of the private key as a certificate. Once you obtain the certificate, you can import it into the server keystore.

You can generate the certificate using Java Keytool with the following command:

> keytool -exportcert -alias clientcert -file client-public.cer -keystore client.jks -storepass storepassword

Where:

Argument

Description
clientcert The alias that was assigned to the test client keystore.
client-public.cer The full pathname for a file to which the client’s public certificate is to be extracted.
client.jks The location of the client keystore.
storepassword The password used with the -storepass option when the client keystore was created.

Importing the client certificate into the server keystore puts that certificate on the list of trusted certificates for the server. You can import the certificate into the test server keystore using Java Keytool with the following command:

> keytool -importcert -keystore server.jks -alias clientcert -file client-public.cer -storepass storepassword -noprompt

Where:

Argument

Description
clientcert The alias used for the certificate within the server.jks keystore.
client-public.cer The full pathname to the exported client certificate.
client.jks The location of the client keystore.
storepassword The password used with the -storepass option when the server keystore was created.

Adding the server public certificate to the test client keystore

Export the test server keystore’s public certificate using Java Keytool with the following command:

> keytool -exportcert -alias serverkey -file server-public.cer -keystore server.jks -storepass storepassword

Where:

Argument

Description
serverkey The alias assigned to the server keystore.
server-public.cer The full pathname for a file to which the server’s public certificate is to be extracted.
server.jks The location of the server keystore.
storepassword The password used with the -storepass option when the server keystore was created.

Import the server key into the test client keystore using Java Keytool with the following command:

> keytool -importcert -keystore client.jks -alias servercert -file server-public.cer -storepass storepassword -noprompt

Where:

Argument

Description
client.jks The location of the client keystore.
servercert

The alias to be used for the certificate within the client.jks keystore.
server-public.cer The full pathname for a file to which the server’s public certificate is to be extracted.
storepassword The password used with the -storepass option when the server keystore was created.

Configure the application server to use the JKS server keystore

The following instructions assume you are using Apache Tomcat as your application server, and you have added your certificates and keys to the client and server keystores in your production environment. If you use a different application server, you must secure it as directed in that specific product’s documentation.

To configure the application server:

  1. Navigate to %Voice Platform_HOME%\appservice\applications\conf and open the server.xml file.

  2. Add a <Connector> element to the server.xml file:

    <Connector port=https_port clientAuth="false" protocol="HTTP/1.1" maxThreads="150" keystoreFile="absolute_path_to_jks" keystoreType="JKS" keystorePass="keypassword" truststoreFile="absolute_path_to_jks" truststoreType="JKS" truststorePass="storepassword" SSLEnabled="true" scheme="https" secure="true" sslProtocol="TLS" />

    Where:

    • port is the for the secure connection for Voice Platform. Recommended port: 8091. By convention, the port reserved for HTTPS is 8443; however, this may cause a conflict in a configuration where Management Station is on the same host as the application container service. In such a configuration, Management Station already uses port 8443 for its own secure connection. When this is the case, you must use a different port number for the application container service secure connection.
    • clientAuth determines if the connection is one-way or two-way SSL. Set to false if you want one-way SSL. Set to true if you want two-way (mutual) SSL.
    • keystoreFile is the full path to the server keystore. For example: keystoreFile="c:\Program Files\Nuance\Voice Platform\appservice\applications\certs\server.jks"
    • keystorePass is the keystore password defined for the server -keypass option when the keystore was created.
    • truststoreFile is the full path to the service's truststore file. For example: truststoreFile="c:\Program Files\Nuance\Voice Platform\appservice\applications\certs\server.jks"
    • truststorePass is the encrypted passphrase for the service's truststore file.
  3. Save your changes.
  4. Open the web.xml file in %Voice Platform_HOME%\appservice\applications\conf folder.

  5. Add three security constraint sections to the web.xml file to redirect HTTP requests to use the HTTPS instead. Open the web.xml file in a text editor, and add the following text at the very end of web.xml, right before the closing tag:

    <security-constraint>
  <web-resource-collection>
    <web-resource-name>Security page </web-resource-name>
    <url-pattern>/*</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>
 
<security-constraint>
  <web-resource-collection>
    <web-resource-name>EventSink Security page</web-resource-name>
    <url-pattern>/EventSink</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>NONE</transport-guarantee>
  </user-data-constraint>
</security-constraint>
 
<security-constraint>
  <web-resource-collection>
    <web-resource-name>Generate Alarm</web-resource-name>
     <url-pattern>/httpGenerateAlarm</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>NONE</transport-guarantee>
  </user-data-constraint>
</security-constraint>
  6. Save your changes.
  7. Restart the application server.

Configure the Voice Browser service for SSL

You must configure the Voice Browser service to use a secure socket layer (SSL) connection in Management Station.

To configure the service properties:

  1. Set browser.security.ssl.keyStoreURL to specify the location of the client keystore.
  2. Set browser.security.ssl.keyStorePassword to specify the password to the client keystore.
  3. Set browser.security.ssl.TrustStoreURL to specify the location of the server truststore.
  4. Set browser.security.ssl.keyTrustStorePassword to specify the password to the server truststore.

If there's an interim period when the certificates are temporarily invalid, you can use browser.security.ssl.disableCertVerification to ignore them.