TL;DR

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.

...

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

...

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

...

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. 

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.

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.

...

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:

...

Step by Step Guide

SSL Setup

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

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

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

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

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

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

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.

\uD83D\uDCCB Related articles

...

the full guide, check out our forum post.