Using SSL With Pulse

To enable SSL with Pulse, there are three main steps:

1. Create your own Keystore and Certificate Signing Request (CSR)

2. Import your X.509 Certificate into your Keystore

3. Update your server’s Connector setting

   • Option 1: Using your updated Keystore

   • Option 2: Using a PFX file instead

1. Open a Command Line Window using Run As Administrator

2. Use the cd command to change the directory to the conf directory where Pulse is installed:

   cd C:Program FilesPulse for TM1conf

    

3. Create your own keystore and generate a Certificate Signing Request:

   ..jrebinkeytool -genkey -alias tomcat -keyalg RSA -keystore pulse.keystore -keysize 2048

   Remember the alias value you have specified here as this will be used later to import your main certificate. On this documentation, we have used tomcat as the alias of the main certificate

    

4. Enter a password and write it down so you can use it later:

   Enter keystore password: xxx

    

5. Enter the details for the certificate:

    

   • First and last name (Common Name (CN)): Enter the domain of you are going to use for Pulse (i.e. pulse.mycompany.org) in the “first- and lastname” field.. It looks like “www.company.com” or “company.com”. NOTE: The Common Name above must match the URL people are going to use to access Pulse

   • Organizational Unit (OU): This field is optional; but can be used to help identify certificates registered to an organization, i.e. the name of the department making the request.

   • Organization (O): If your company or department, exclude any special characters such as & or @ from the name.

   • Locality or City (L): The locality field is the city or town name, for example: New York.

   • State or Province (S): Spell out the state completely; do not abbreviate the state or province name, for example: Florida

   • Country Name (C): Use the two-letter code for the country, for example: US, AU, UK, etc.

      

6. Confirm the detail are correct, type y and press enter:

   Is CN=demo.pulsefortm1.com, OU=Unknown, O=Cubewise, L=St Leonards, ST=New South Wales, C=AU correct?
   [no]: y

    

7. Press return and use the same password as entered in Step 4

   Enter key password for <pulse>
   (RETURN if same as keystore password): [Enter]

    

8. Generate a Certificate Signing Request (CSR) to be used by a certificate Authority (Symantec, Thawte, DigiCert, GeoTrust, Go Daddy, etc)

   ..jrebinkeytool -certreq -alias tomcat -file pulse.csr -keystore pulse.keystore

   Notes:

   • Use the alias of the main certificate you have specified in step 3.  On this documentation, we have used tomcat as the alias of the main certificate.

   • Chrome does not accept the CN property of a certificate as the hostname. For Chrome the Subject Alternate Name(s) for the machine need to be specified. If SANs are not specified in the command, Chrome will show an SSL exception.

     For this, when creating the certificate request, the following parameter needs to be added to the command:

     ..jrebinkeytool -certreq -alias tomcat -file pulse.csr -keystore pulse.keystore -ext san=dns:www.example.com,dns:example

      

9. Enter the password your created in step 4:

   Enter keystore password:

    

10. Follow the steps of your Certificate Authority to purchase a new certificate using the pulse.csr file that was created in the previous step.

    NOTE: The pulse.csr file will be in the conf directory where Pulse is installed

     

11. At this point you should make a copy of the pulse.keystore file so you have a backup if you encounter problems when importing certificates

1. Open a Command Line Window using Run As Administrator

2. Use the cd command to change the directory to the conf directory where Pulse is installed

   cd C:Program FilesPulse for TM1conf

3. First, import any root and intermediate certificate(s) as instructed by your Certificate Authority. These needs to be imported BEFORE your certificate is imported: 

   As an example, you might be given three files:

   • root.cer (assumed to be the file name of the root certificate)

   • intermediate.cer (assumed to be the file name of the intermediate certificate)

   • pulse.cer (assumed to be the file name of the main certificate; we will use this later in Step 4 of this section) 

4. Save these certificates provided to you into Pulse’ conf directory i.e. root.cer

5. For each certificate excluding the main one (on our case this is pulse.cer), execute the following and enter your keystore password after each,

   ..jrebinkeytool -import -trustcacerts -alias root -keystore pulse.keystore -file root.cer

   ..jrebinkeytool -import -trustcacerts -alias intermediate -keystore pulse.keystore -file intermediate.cer

   Note that, if you have more intermediate certificates, you will need to import them too, replacing the -alias and -file value for each. For example, if you have another intermediate2.cer file: 

   ..jrebinkeytool -import -trustcacerts -alias intermediate2 -keystore pulse.keystore -file intermediate2.cer

6. Import your actual certificate into the keystore: 

   • Save the certificate to the conf directory, i.e. pulse.cer

   • Execute the following, replacing the value passed to -alias with the alias you have specified in Step 3 when you where creating your keystore. On this documentation, we have used tomcat:

   ..jrebinkeytool -import -trustcacerts -alias tomcat -keystore pulse.keystore -file pulse.cer

   • Enter the keystore’s password you have specified in Step 3 when you where creating your keystore, and press enter.

7. If you get: Certificate reply was installed in keystore. The certificate has been successfully installed in the keystore

   If you receive this error, keytool error: java.lang.Exception: Failed to establish chain from reply, you need to install the appropriate intermediate certificates.

1. Open conf/server.xml (in the Pulse install directory)

2. Find the SSL Connector (search for port 8093)

3. Change the keystoreFile to the name of the keystore from above, i.e. conf/pulse.keystore.

4. Update the keystorePass to the password you used above if it is different the default one.

5. Change the port number if you would like to use a different port to 8093 (443 is the default for SSL).

6. After clientAuth=”false” insert keyAlias=”tomcat” (or the alias value you have used earlier in Step 3 when you created the keystore)

7. Save the file, you may have to save it to your desktop first and copy it to the directory to get around the Windows UAC security settings.

8. Restart the “Pulse for TM1 Application Server” Windows service.

A PFX file can be used without importing individual certificates into the keystore. You will need the following:

• your PFX file (*.pfx)

• the password of your PFX file

To use a PFX file into your Pulse server,

1. Copy your PFX file into Pulse for TM1’s conf folder

2. Using a command line, navigate into Pulse for TM1’s conf directory

3. One of the information the setup needs is the keyAlias; execute the following command to get it

..jrebinkeytool -list -v -storetype pkcs12 -keystore CODE02-P.pfx

Look for the line that says or similar to “Alias name” and copy the value it refers to (i.e. for the above, our keyAlias will be 215aa689-80f7-4f41-8ddf-6c69365f7c60)

4. Open up conf/server.xml in Pulse for TM1 directory and add or update the following properties into the secure connector:

• keystoreFile – the path of your PFX file; this can be a relative path using Pulse for TM1 folder as the point of reference (i.e. conf/MyServer.pfx)

• keystoreType – update as “PKCS12”

• keystorePass – update with the password for the PFX file

• keyAlias – update with the text we have grabbed from step 3

<Connector port="8093" protocol="HTTP/1.1" SSLEnabled="true" URIEncoding="UTF-8" scheme="https" secure="true" sslProtocol="TLS"            sslEnabledProtocols="TLSv1.2"        ciphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"                    keystoreFile="conf/CODE02-P.pfx" keystoreType="PKCS12" keystorePass="password"        keyAlias="215aa689-80f7-4f41-8ddf-6c69365f7c60"                clientAuth="false"         compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json"        compression="on"        compressionMinSize="2048"        maxHttpHeaderSize="32768"        xpoweredby="false" server="Pulse"    />

Command for checking the keyAlias:

keyAlias on this case would be: edbd642b-e2b4-447a-b63a-0c75416072e6