When you install the vCommander® VM Access Proxy, a Secure Sockets Layer (SSL) certificate is installed to its tomcat web server that confirms the identity of the server when vCommander connects remote control sessions. This default certificate is self-signed, which means that your users have to make a decision whether or not to trust it when they initiate their session, because no certificate authority (CA) has validated the identity with a CA certificate.

The image below shows the how this decision will be presented by Firefox:

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 screenshots and paths referenced in this article are based on the VM Access Proxy 2.10 and earlier. For VM Access Proxy 2.11 and later, wherever tomcat7 appears in a path, replace it with tomcat. Commands that reference the tomcat7 service need to reference tomcat8 instead.


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 unqiuely 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.

  1. Login to the Console Proxy appliance:

    Username - vcommander
    Password - gRHrB211

  2. Browse the correct directory by issuing the command cd /var/lib/tomcat7/conf

  3. Issue the command sudo keytool -delete -alias tomcat -keystore "keystore" -storepass changeit
  4. Enter the root password again when prompted.


  5. Confirm that the deletion was successful by issuing the following command keytool -list -v -keystore "keystore" -storepass changeit

Important: If the tomcat7 service was stopped prior to deleting the certificate, it cannot be started until you have completed the next procedure. Attempting to do so will result in exceptions about the missing certificate.
 

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.

  1. Still in the same directory used for the procedure above, issue the command:

    sudo keytool -genkey -alias tomcat -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -validity 3650 -keystore "keystore" -storepass changeit

  2. Enter the root password again when prompted.
  3. 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 Access Proxy server. For example, proxy.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.

  4. Confirm that the keystore has one entry by issuing the following command:
    keytool -list -v -keystore "keystore" -storepass changeit

If the tomcat7 service was previously stopped, it can now be started again without any exceptions because a new certificate has been created and installed.

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.

  1. Still in the same directory used for the procedure above, issue the command:

    VM Access Proxy 2.11 and Later
    sudo keytool -certreq -keyalg RSA -alias tomcat -file tkproxy2017.csr -keystore "keystore" -ext san=dns:localhost,dns:your.address.one,dns:your.address.two,ip:127.0.0.1,ip:10.10.20.123,ip:10.10.20.123 -storepass changeit

    (Replace your.address.one, your.address.two and the corresponding IP address with those relevant for your deployment.)

    VM Access Proxy 2.10 and Earlier
    sudo keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore "keystore" -storepass changeit 


  2. Issue the command: sudo service ssh start
  3. Launch Filezilla FTP Client.
  4. Under the File menu, choose Site Manager.
  5. Click New Site and name it Console Proxy.
  6. Enter the hostname or IP address of the console proxy in the Host field.
  7. Choose SFTP – SSH File Transfer Protocol from the Protocol menu.
  8. Choose Normal as the Logon Type.
  9. Enter the Username (vcommander), and Password (gRHrB211).
  10. Click Connect
  11. You may receive a warning that the connection is untrusted. Check Always trust this host, add this key to the cache and click OK.

  12. Enter /var/lib/tomcat7/conf in the Remote site pane.

  13. Double-click certreq.csr to download it onto your local computer, in the location shown in the Local site pane.

Send the file to your certificate authority, or Active Directory Certificate services.

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


Use the process below to import the certificates. Note that depending on your provider, the instructions may vary. If you have a support agreement with the Certificate Authority, you may wish to arrange a call with them, and can request Embotics Technical Support be present to assist.

  1. Launch Filezilla FTP Client.
  2. Under the File menu, choose Site Manager.
  3. Choose Console Proxy and click Connect.
  4. Enter /home/vcommander in the Remote site pane.
  5. Drag and drop the file returned from the certificate authority on the remote site file listing to copy the file (for example, certnew.p7b) onto the console proxy in a writable directory.
  6. Login to the Console Proxy appliance.
  7. Issue the command:
    cd
    to move to the home directory where you copied the file.
  8. Issue the following command: sudo apt-get install mtools to install mTools. Enter the vCommander password when prompted.

  9. Issue the following command:
    sudo mcopy certnew.p7b /var/lib/tomcat7/conf Enter the root password again when prompted.
  10. Browse to the correct directory by issuing the command:
    cd /var/lib/tomcat7/conf

  11. Issue the following command:
    sudo keytool -import -trustcacerts -alias tomcat -file certnew.p7b -keystore "keystore" -storepass changeit

  12. When prompted, enter Yes to confirm you wish to install the reply.

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.

Once you have installed the certificate, you must reset the connection in vCommander.
  1. Browse to Configuration > System Configuration. Switch to the Integration tab.
  2. Under Console Proxy click Edit.
  3. Click OK.

vCommander then reads the new SSL certificate and will communicate securely going forward.