How-To : Using HOOPS Communicator with SSL

HOOPS Communicator
, , ,
1

TL;DR

If you’re are interested in checking a specific detail, there is a step by step guide toward the end of this page to setup SSL on Windows and Linux.

Introduction

The purpose of this document is to give a general overview of the steps required to enable SSL connections using the HOOPS Server as configured in the standard Communicator package. The information in this guide is meant to be used as a point of departure for configuring SSL to work with Communicator in your specific environment.

Configuring the HOOPS Server to use SSL is quite straightforward. All one needs to do is specify the certificate, the key file, and enable SSL in the config.

Confusion arises, however surrounding what exactly needs to be done to ensure the certificate itself is trusted by clients attempting to view models. These steps largely do not involve Communicator itself.

If you are using the SC Streaming Server without the included HOOPS Server, the information in this guide may still be useful as a basic introduction to certificates. In this case, your SSL certificate and key are specified via the command line.

Configuration with a Cert from a known Certificate Authority

Maybe the most common example. In this case we have a certificate issued by a known CA, such as GoDaddy or Verisign and we would like to use it to enable secure connections with the HOOPS Server.

Note, that often the CA will provide multiple files consisting of the certificate for your site and an intermediate certificate from the issuer. In this case, you will need to create a single file which contains all the certificates . When creating this file, the order of the individual certificates matter. You should include your certificate first before any additional certificated provided by the Issuer.

With your certificate in hand, the main key to getting this to work is that the URL used to access the resource in a secure manner must match the DNS that the certificate was issued for.

For example, if your Certificate is was issued for a FQDN such as communicator.yourcompany.com you would need to ensure that the websocket request URL is in the form of: wss://communicator.yourcompany.com:11180.

Likewise, if you have a wildcard certificate that was issued for *.yourcompany.com then your websocket request can have any subdomain, so in this case both wss://communicator.yourcompany.com:11180 and wss://viewer.yourcompany.com:11180 would be acceptable.

When enabling SSL in the HOOPS Server configuration file, you should set the publicHostname field to a string that will match your issued certificate DNS or IP.

In the example above, we should set this value to: communicator.yourcompany.com.

Note that we do not include the protocol or the port number in this field.

For more information on how to configure your HOOPS Server to enable SSL refer to the Configure the server section in the Step by step guide at the end of the document.

You can view the request URL by examining the Websocket requests in your browsers Development tools. Ensure that the request matches the domains that are secured by your certificate.

Note: In order to ensure that requests have the correct URL you will need to ensure that DNS is properly setup for your server.

For example, if you are using a service such as Route 53 you will need to create a record set that routes communicator.yourcompany.com to the IP or CNAME of the server which is running HOOPS.

The specific instructions for doing that can vary widely depending on your infrastructure and are not covered in this document.

Configuration with Self Signed Certificates

There may be a desire to use self-signed certificates for local HTTPS development with the HOOPS Server. The HOOPS Server is built on Nodejs which maintains its own list of known certificate authorities.

It does provide an environment variable which we can use to specify additional CAs so it can validate a self-signed certificate.

For information about how to setup a Certificate Authority and how to create a SSL certificate refer to the Step by step guide at the end of this document.

For more information on how to configure your HOOPS Server to enable SSL refer to the Configure the server section in the Step by step guide at the end of the document.

By default node.js does not use system’s custom certificates so you have to set the NODE_EXTRA_CA_CERTS to the path of your certificate so node.js will consider this CA as valid

After starting the HOOPS Server, you can verify everything is working by visiting: https://localhost:11180/hoops_web_viewer_sample.html?model=microengine

Examining the Connection we can see that it is secure to localhost:

image-20200612-171555

Step by Step Guide

SSL Setup

Let’s start by creating our certificate authority and our self signed certificate

For Windows users

These steps have been tested using git bash. If you find that the commands presented below hang in your terminal, you can prefix them with winpty which should resolve the issue.

Create a Certificate Authority

To generate your CA you must start by creating a CA RSA key with the following command:

openssl genrsa -aes256 -out ca-key.pem 4096

It will generate the private key file ca-key.pem for your CA so that you can sign certificates.

Choose a pass phrase and store it to be able to sign certificates later.

Now let’s generate the CA itself

openssl req -new -x509 -sha256 -days 3650 -key ca-key.pem -out ca.pem

You will need to enter your pass phrase to generate the certificate.

Then you will have to fill a few information prompts, what you enter in this prompt has no impact for self signed certificates.

The -key argument of the command must contain the path to the CA key you generated earlier.

The -days argument of the command represent the duration of the certificate in days, feel free to adapt the value to your needs

You can see the certificates details using the following command:
openssl -x509 -in ca.pem -text

This command will generate your certificate authority file as ca.pem.

Create the SSL Certificate

As we did with the CA, we need to create an RSA key so we can sign data with it.

openssl genrsa -out cert-key.pem 4096

This time there’s no need for a pass phrase.

The output cert-key.pem is the private key of your certificate.

Now we need to create a certificate sign request to pass to our CA.

openssl req -new -sha256 -subj "/CN=yourcn" -key cert-key.pem -out cert.csr

The -subj parameter value is not really important for self signed certificate you can set it to

-subj "CN/whateveryouwant".

We now have a sign request to submit to our CA, let’s do it.

:warning: Here comes the most important step of this part of the guide.

You must set the DNS name or the IP of your certificate to what you use to access it in the browser.

This is an example for localhost and IP 127.0.0.1.

echo "subjectAltName=DNS:localhost,IP:127.0.0.1" >> extfile.cnf

This will generate a configuration file for your certificate request.

Now we have everything ready to generate our certificate.

openssl x509 -req -sha256 -days 3650 -in cert.csr -CA ca.pem -CAkey ca-key.pem -out cert.pem -extfile extfile.cnf -CAcreateserial

Once again you can edit the days parameter to set the duration of the certificate

The -CAcreateserial parameter is useful if you generate several certificates it adds a serial number to them.

Finally enter the CA pass phrase and your certificate is generated.

You can remove the .csr file now.

Install the CA

You will need to install the certificate authority so that the self-signed certificates we generate with this CA can be validated. Additionally, some browsers like Firefox by default does not use the system to validate certificates refers to the browser documentation to install the CA.

Windows 10

  • From the Start menu choose run... And enter certmgr.msc
  • From the Tree menu select: Trusted Root Certification Authorities → Certificates
  • From the Menu bar select: Action → All Tasks → Import
  • Select the ca.pem file created above.

Debian (tested on Ubuntu):

# move the CA to the system's certificates directory
sudo mv ca.pem /usr/local/share/ca-certificates/ca.crt

# update the ca store
sudo update-ca-certificates

MacOS

  • With Finder, open the folder containing your ca.pem
  • Double click on ca.pem, it should open the KeyChain dialog
  • Follow the guide to install the certificate, go to its details to select Always Trust

Configure the Server

Edit your server_config.js to set these parameters:

var config = {
  // ...
  publicHostname: "localhost",
  sslCertificateFile: "path/to/cert.pem", 
  sslPrivateKeyFile: "path/to/cert-key.pem", 
  sslEnableFileServer: true,
  sslEnableSpawnServer: true,
  sslEnableScServer: true,
  // ...
};

Then export the path to your CA is store as a node environment variable:

# In a windows .bat script
@set NODE_EXTRA_CA_CERTS=D:/techsoft3d/scratch/localhost_ca_root.pem

# In a unix .sh script
export NODE_EXTRA_CA_CERTS="path/to/ca.crt"

On Linux you may have the following error in the console:

Fri Aug 19 15:50:48 2022.0.858:info: sendHttpPost: url='https://localhost:11182/api/spawns/898c4330-05f5-49da-a220-aec0a5299541?liveliness=disconnect'
Fri Aug 19 15:50:48 2022.0.859:warn: Failed to send HTTP ping: response='error setting certificate verify locations:
  CAfile: /etc/pki/tls/certs/ca-bundle.crt
  CApath: none'

Curl expect to find your certificate in /etc/pki/tls/certs/ca-bundle.crt while at this point it is stored in /usr/local/share/ca-certificates/ca.crt. You can fix this error by adding a symlink to the expected path.
You can now run the server with your SSL certificate.

2

I use the HC 2023 for testing https server. Here is the error, how to fixed it. Thanks a lot!

“2023-8-18 11:48:33 AM:error: file-server: proxy-error: Error [ERR_TLS_CERT_ALTNAME_INVALID]: Hostname/IP does not match certificate’s altnames: IP: 127.0.0.1 is not in the cert’s list:”

I have installed the CA use the “certmgr.msc”.

server_config_127_0_0_1.js

publicHostname: "127.0.0.1",

sslCertificateFile: "./quick_start/cert.crt",

sslPrivateKeyFile: "./quick_start/cert.key",

// Determines if SSL is enabled for the file-server.
sslEnableFileServer: true,

// Determines if SSL is enabled for the spawn-server.
sslEnableSpawnServer: true,

// Determines if SSL is enabled for the spawned stream-cache servers.
sslEnableScServer: true,

start_server.bat

:: Script is relative to this directory 
@cd "%~dp0"

@set node_install_dir=%~dp0\..\3rd_party\node
@set NODE_EXTRA_CA_CERTS=%~dp0\cert.crt

:: Must start the server from the node dir 
@cd ../server/node

:: Perform the node command directly here to pass in the quick-start config and not the server/node config 
@call "%node_install_dir%\node.exe" --expose-gc ./lib/Startup.js --config-file ../../quick_start/server_config_127_0_0_1.js
3

Hello @1435389123,

Rather than using:
publicHostname: "127.0.0.1",

…let’s try this instead:
publicHostname: "localhost",

Thanks,
Tino

1 Like