When you install Embotics® vCommander®, a Secure Sockets Layer (SSL) certificate is installed to the apache-tomcat web server that confirms the identity of the server when your users access the system. This default certificate is self-signed, which means that your users have to make a decision whether or not to trust it when they access Embotics vCommander, because no certificate authority (CA) has validated the identity with a CA certificate.This means users will be prompted by their web browsers to make a decision, which will look like this:
Users can choose to trust the certificate or you can purchase and install a CA certificate that will be automatically trusted by web browsers, by following the procedures below.
Note: The instructions in this article were not prepared specifically for use with certificates that you already possess, or wild card certificates. You cannot skip any steps just because you already have a certificate, or else you may run into issues with the information in the web server not matching that encrypted information in the certificate. Modifications to the keystore or server.xml file to bypass this process are not supported by Embotics.
Remove the Default Self-Signed Certificate
The first thing that you must do is remove the default self-signed certificate that was created during the installation of Embotics vCommander, because there are no details uniquely identifying your organization. Before doing so, take a snapshot of the Embotics vCommander server so that you can restore to a known good state if anything goes wrong.
- On the Embotics vCommander server, open a command prompt and browse to <INSTALL DIRECTORY>\Embotics\vCommander\jre\bin.
- Issue the command keytool -delete -alias tomcat -keystore "C:\Program Files\Embotics\vCommander\tomcat\conf\keystore" -storepass changeit. If your path includes a space, you must enclose the path in quotes.
Generate a New Self-Signed Certificate
The next step is to install a new self-signed certificate which will contain details about your organization that must be shared with the certificate authority. This makes sure that when you create the signing request, all of your organization’s details are included in the tomcat web server.
- Still in the same directory used for the procedure above, issue the command keytool -genkey -alias tomcat -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -validity 3650 -keystore "C:\Program Files\Embotics\vCommander\tomcat\conf\keystore" -storepass changeit .
- You are prompted to provide and confirm the information the certificate contains.
- First and Last Name: Enter the fully qualified domain name (FQDN) of the vCommander server. For example, vcommander.embotics.com.
- Organizational Unit: The name of your department within the larger organization. For example, Engineering.
- Organization: The name of your organization. For example, Embotics Corporation.
- City or Locality: The city where your organization is based. For example, Ottawa.
- State or Province: The state of province where your organization is based. For example, Ontario.
- Two-letter Country Code: The country where your organization is based. For example, CA for Canada or US for the United States of America. See a complete list.
-
Key Password for Alias: Embotics does not recommend using a password, just strike the ENTER key to proceed past this prompt.
Create the Certificate Signing Request
The next step is to create a certificate signing request (CSR) file which you will submit to a certificate authority. This proves the identity of the server you are asking them to validate. Alternatively, you can use Active Directory Certificate Services as your authority.
Depending on the certificate authority you are working with, you will provide the CSR file either by uploading it via their customer service portal or emailing it to your sales representative. If you aren’t sure how to provide it to your certificate authority, contact their technical support or sales teams.
- Still in the same directory used for the procedure above, issue the command like one of the following examples:
keytool -certreq -keyalg RSA -alias tomcat -file embotics2017.csr -keystore "C:\Program Files\Embotics\vCommander\tomcat\conf\keystore" -ext san=dns:localhost,dns:sammy.pv.embotics.com,dns:sammy,ip:127.0.0.1,ip:10.10.10.78,ip:10.10.10.78 -storepass changeit.keytool -certreq -keyalg RSA -alias tomcat -file embotics2017.csr -keystore "C:\Program Files\Embotics\vCommander\tomcat\conf\keystore" -ext san=dns:vcommander_FQDN.domain.com -storepass changeit.
If your path includes a space, you must enclose the path in quotes.
You must include at least one subject alternative name in order for Google Chrome 58 and later to work. To do so, replace the dns: and ip: values in this portion of the command, using the specifics that match your vCommander server. Examples:
san=dns:fqdn.yourvcommander.com,ip:xxx.xxx.xxx.xxx
san=dns:fqdn.yourvcommander.com
Use commas to add as many alternative names as you require.
When requesting a certificate, make sure that the certificate authority will provide one with SHA-2 or better encryption. Modern browsers no longer accept SHA-1 as secure.
- Retrieve the file certreq.csr created in the working directory and provide it to your certificate authority.
Import the CA Signed Certificates
In this next step, you will import the certificate that was provided to you by the certificate authority. In most cases, you will have to install both an intermediate certificate as well as the one specific to the request that you submitted. If you do not install a certificate authority’s intermediate certificate when one is required, you will receive the following error when attempting to import the certificate for your request:
keytool error: java.lang.Exception: Failed to establish chain from reply
See the following articles for specific instructions related to installing intermediate certificate for particular certificate authorities:
Once you have installed any required intermediate certificate, follow the procedure below to import the signed certificate into the Embotics vCommander server’s keystore.
- Save the .crt file provided to you by the certificate authority into the same directory used for the procedure above.
- Still in the same directory used for the procedure above, issue the command keytool -import -trustcacerts -alias tomcat -file yourfile.crt -keystore ..\..\tomcat\conf\keystore -storepass changeit using the correct filename for your .crt file. If your path includes a space, you must enclose the path in quotes.
- The message Certificate reply was installed in keystore indicates that the new certificate is installed and may be used. Restart the vCommander Windows service.
Important: If you receive the error message keytool error: java.security.cert.CertificateException: java.io.EOFException you most likely have a trailing space in your signed certificate. Open the certificate file in a text editor such as notepad and remove any spaces leading into or trailing the encrypted content, and import the certificate again.