Configure VoiceObjects for SSL
This How-To explains how VoiceObjects Server can be configured for SSL Communication
The process of configuring VoiceObject for SSL communication is divided into the following parts
- Private Key / Public Key generation and Certificate for VoiceObjects Server
This is mostly up to the customer SSL specialists as usually a CA-signed certificate will be needed.
- Importing the license into a keystore inside VoiceObjects (or create a new keystore)
- Configuring the web application server for SSL communication
- Configuring VoiceObjects for SSL communication
Create a New Keystore or Import into a Keystore
Usually there will be no keystore file inside VoiceObjects.
So unless you have VoiceObjects already running with SSL, you can create your own new keystore.
You can either create the keystore when building your own key as described in Appendix A - Java Keytool.
Or you include your existing certificate into an new or existing keystore:
keytool -importcert -keystore voiceobjects.keystore -file VoiceObjectsCertificate.crt
Both ways will create a keystore file voiceobjects.keystore which then needs to be configured in the Web Application Server. See the descriptions for the WAS delivered with VoiceObjects in Configuring VoiceObjects for https Communication.
See also the web:
Configuring VoiceObjects for https Communication
Configuring the Embeddded Jetty for SSL communication
In order to configure jetty for https communication, we need convert private key and certificate and add additional SSL Listener to jetty configuration We need to convert the pkcs12 format into JSSE keystore format and thus can be imported inside keystore when jetty is started.
java -classpath $JETTY_HOME/lib/org.mortbay.jetty.jar org.mortbay.jetty.security.PKCS12Import voiceobjects.pkcs12 voiceobjects.keystore
Adding SSL Listener to the Jetty configuration can be done by modifying the file VOServer.xml placed under the directory VoiceObjects\Platfom\WEB-INF\etc\Jetty6. Add the following lines:
<SystemProperty name="jetty.port" default="8443"/>
<Set name="Keystore">./etc/ca.keystore</Set> <!-- Provide your keystore. This can be relative to WEB-INF directory -->
<Set name="keyPassword">voadmin</Set> <!-_ Provide your key password here -->
<Set name="Password">voadmin</Set> <!-- Provide your keystore password here -->
In order to test, paste the link https://localhost:8443/VoiceObjects/ in the browser. This will result in browser asking whether to accept the certificate. Please accept it and you are communicating using SSL
Configuring the Embedded Tomcat for SSL Communication
Adding SSL Listener to the Tomcat configuration can be done by modifying the file VOServer.xml placed under directory VoiceObjects\Platfom\WEB-INF\etc\Tomcat6. Add the following lines:
<Connector port="8099" className="org.apache.coyote.tomcat5.CoyoteConnector"
scheme="https" secure="true" clientAuth="false" sslProtocol="TLS"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
-keystoreFile="<VOICEOBJECTS_HOME>/Platform/WEB-INF/etc/voiceobjects.keystore" <!-- Provide your keystore. This must be an absolute path!-->
-keystorePass="your password" <!-- Provide your key password over here -->
VoiceObjects versions prior to VoiceObjects 7.3 R2
Configuring can be done by adding following lines inside the file WEB-INF\properties\vo.properties for all server instances and the desktop.
# keystore location for SSL Communication
# cerfificate location for SSL Communication
#keystore password used for SSL Communication
#: ''vo.keypassword=voadmin ''
These properties specify the location of certificate and keystore to be used for SSL communication. Please specify the proper URL value for these properties. It is also required to provide the key password used to open the keystore file.
- Connector Object
- When a SSL connector should be used by VoiceObjects, the above described settings in the vo.properties need to be set in order to allow to accept the Connection to the SSL secured connector. The URL to the connector will then look like the following: https://<host>:<443>/VoiceObjects/Resources/''<yourCustom.file>''
- Control-Center Connection
- Please set up ControlCenter URL for the Server Object to access the server by using https and the correct port:https://<host>:<443>/VoiceObjects/Services/WSProvider?wsdl
- Desktop Connection
- The connection to the Desktop for Web using SSL is in general not different to the normal connection. The change in the URL need to be taken into account (https and the changed port).
- Desktop for Eclipse needs additionally the URL to the certificate file. To add this to the Network setup of DfE, please choose the "Advanced" button (1) in the Network Mode settings and add the URL to the certificate to the parameters of the connection to the desktop instance.(2). Then please check the connection parameters (https and port).
VoiceObjects versions beginning with VoiceObjects 7.3R2
- Connector Object
- The connector Object allows to define a certificate which allows to access the web server running the remote page.
- The certificate can be added to the Certificate URL box in the Authentication part of the connector object.
- Control-Center Connections
- Set the URL to the SSL-Certificate directly in the server object. The ControlCenter URL is the same as in the previous versions of VoiceObjects - please make sure to use https and the correct port.
- Desktop Connection
- The connection to Desktop for Web and Desktop for Eclipse has not changed with VoiceObjects 7.3R2. Thus please refer to the Desktop Connection description above.
Appendix A: Private Key/Public Key Generation
This is probably the easiest way to get a key and directly insert it into a keystore which then can be used in VoiceObjects.
To generate the Keystore
This section provides information on how to generate key pairs and certificates using the openssl tool.
For installing openssl please refer to following link http://www.openssl.org/.
Please see the commands to generate a key pair with openssl below:
First, we create a 1024-bit private key to use when creating our CA
openssl genrsa -des3 -out voiceobjects.key 1024
The screen will show
Loading 'screen' into random state - done
warning, not much extra random data, consider using the -rand option
Generating RSA private key, 1024 bit long modulus
e is 65537 (0x10001)
Enter pass phrase for voiceobjects.key: - choose a memorable pass phrase to use for this key, e.g. voadmin
Verifying - Enter pass phrase for voiceobjects.key: - type your pass phrase again for verification e.g.: voadmin
Next, we create a master certificate based on this key, to use when signing other certificates.
You are about to be asked to enter information that will be incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
openssl req -config openssl.conf -new -x509 -days 1001 -key voiceobjects.key -out voiceobjects.cer
Enter PEM pass phrase: - type your passphrase here.
Country Name (2 letter code) :DE
State or Province Name (full name) : NRW
Locality Name (e.g.: city) : Bergisch Gladbach
Organization Name (e.g.: company) :voxeo.com
Organizational Unit Name (e.g.: section) :
Common Name (e.g.: your websites domain name) :ssl.voxeo.com
Email Address :email@example.com
Note: This How-To explains on creating self signed certificates to be used inside development environment.
- For production environment, a Certificate Issuing Authority (CA, e.g. .Versign) should be requested to issue a certificate for your web application server.
- In order to request a certificate from the CA we require a Certificate Signing Request(CSR). This can be issued using following command
openssl req -new -key voiceobjects.key -out voiceobjects.csr
The CSR file generated above should be given to the CA. The CA then provides signed certificate in the form .cer file.
Finally, we export our CA certificate in PKCS12 format - this will allow Windows users to import the PKCS12 certificate into their Trusted Root Store, so they don't get warning messages every time they use one of our certificates.
openssl pkcs12 -export -out voiceobjects.pkcs12 -in voiceobjects.cer -inkey voiceobjects.key
The end result of this process results in creating following files
- voiceobjects.key - our private key
- voiceobjects.cer - our self signed certificate
- voiceobjects.pkcs12 - our self signed certificate in pkcs12 format
Appendix B: Links