How to enable HTTPS Secure Connection in Spectrum 7 using SSL Certification

Product Feature: Spectrum Server
How to set up HTTPS within Spectrum. 

There are three parts to this, the Client API, the client tools like Management Console, and the server side.  All three will be addressed here, in case you need the information.

 
SERVER:
 
The first step is to generate a Java KeyStore (JKS) file that will store the certificates that Spectrum will use.  You can use the JDK's keytool application to do this.  This is an example command that will create the keystore and generate a self-signed certificate that can be used for testing.  When prompted for your "first and last name", this is where you want to enter the computer name that will be hosting Spectrum.  You will have to generate a second certificate pair to reference the IP address if they will ever be connecting that way.  One important note is that, for Windows, the JKS must reside on the same hard drive as Spectrum.  For example, if Spectrum is installed on the D: drive, the JKS must also be stored on D:.
 
D:\>keytool -keystore testks -genkeypair -keyalg RSA -validity 10000 -storepass password -keypass password
What is your first and last name?
  [Unknown]:  er005de-g1lan
What is the name of your organizational unit?
  [Unknown]:  Pitney Bowes
What is the name of your organization?
  [Unknown]:  PB
What is the name of your City or Locality?
  [Unknown]:  Lanham
What is the name of your State or Province?
  [Unknown]:  MD
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=er005de-g1lan, OU=Pitney Bowes, O=PB, L=Lanham, ST=MD, C=US correct?
  [no]:  yes
 
Now that you have a JKS for Spectrum, you'll need to modify the attached XML file and save it to the <SpectrumRoot>/server/app/conf/spring directory.  There are four properties in this file that you need to change:

 
<property name="port" value="8443"/>
<property name="keystore" value="/Program Files/Pitney Bowes/Spectrum/keystore"/>
<property name="password" value="password"/>
<property name="keyPassword" value="password"/>
 
"port" is obviously where you want Spectrum to be listening for HTTPS connections.  "keystore" is the path to the JKS you created earlier.  "password" is the JKS password, i.e. the value you specified for the -storepass option above.  "keyPassword" is the password for the certificate you want to access, i.e. the value of -keypass from above.
 
Once this file is in place, stop and start the Spectrum process.  You should now be able to access https://server:ssl-port from a browser and see the Spectrum Welcome Page.  You'll probably get a security exception from the browser since the certificate is not signed by a trusted certificate authority (CA).  That's fine for now, as I assume an enterprise company will eventually get a certificate from a trusted CA.
 
CLIENT TOOLS:
 
In order to use a secure connection with Management Console and Enterprise Designer, you may need to import a certificate into the Windows certificate store.  You will definitely need to do this if you intend to test with a self-signed certificate from above.
 
The first thing is to get the certificate to import.  The easiest way is to open Internet Explorer and go to https://server:ssl-port to see the welcome page.  In IE 7 and 8, click the lock next to the address bar, then click View Certificates.  Click over to the Details tab, then click the Copy to File button at the bottom.  Go through the wizard and make sure the certificate is exported as a "DER encoded binary X.509" format.  You now have the certificate from the server. 
 
The next step is to import that certificate into the Windows store.  To do this, click Start > Run.  Type "mmc" and click OK.  Click File > Add/Remove Snap-in.  Click the Add button and find Certificates in the list.  Then click Add.  Make sure you choose "Computer Account" and "Local computer" when asked and click Finish.  Then click Close and OK so you're back to the main MMC window.  Expand the Certificates node on the left and find Trusted Root Certification Authorities > Certificates.  Right-click there and choose All Tasks > Import.  Go through the wizard and browse to the file you created from IE.  Make sure it's placed in the Trusted Root Certification Authorities store and finish out the wizard.
 
You should now be able to use a secure connection with Management Console and Enterprise Designer.  Again, these steps are not necessary if the certificate on the Spectrum server is signed by a trusted CA like VeriSign.  You only have to do these steps if your certificate is not signed by a known CA.
 
CLIENT API:
 
Just like the client tools, if the certificate is signed by a trusted CA, you don't have to do anything special here.  Just set the Server.CONNECTION_TYPE to "HTTPS" and set the correct port.  The Java API will take care of the rest.  However, if you're using a self-signed certificate or one that's not signed by a known CA, you'll have to add that certificate to the trusted CA certificates store for Java.  The default trusted CA store for Java is JAVA_HOME/jre/lib/security/cacerts.  You can either import your certificate directly into this file or you can make a copy of this file for testing. 
 
To import the certificate, you can run a command like this:
 
keytool -keystore mycacerts -storepass changeit -import -alias spectrum -file myIEcert.cer
 
Where the -file parameter is the name of the certificate file you exported from IE earlier and the value of -keystore is the cacerts file you are using.  Java will now trust your self-signed certificate.  "changeit" is the default password for the cacerts file.  If you're using a copy of the original cacerts file, you'll need to tell Java where to find it by adding the "-Djavax.net.ssl.trustStore=<name of cacerts>" option to the java command line, like this:
 
java -classpath .;g1clientSDK-7.0.jar -Djavax.net.ssl.trustStore=D:\sourcecode\java\LESJavaSample\mycacerts SpectrumTester
 
WEB SERVICES:
 
Unfortunately, I can't really tell you what the process here is.  In Visual Studio and soapUI, all I need to do is add a Service Reference and point it to https://server:ssl-port/services/ValidateAddress?wsdl for it to use a secure connection.  There are a number of Java utilities out there for generating SOAP messages and each one is different.  I would imagine that you'll need to go through the steps for adding a self-signed certificate to a cacerts file, but I can't really comment beyond that.
 
 
UPDATED:  October 20, 2017