# How-To : Using HOOPS Communicator with SSL

**URL:** <https://forum.techsoft3d.com/t/how-to-using-hoops-communicator-with-ssl/1339>\
**Category:** HOOPS Visualize Web\
**Tags:** learn, knowledge-base, how-to, server\
**Created:** [November 4, 2021, 4:00am UTC](https://forum.techsoft3d.com/t/how-to-using-hoops-communicator-with-ssl/1339 "2021-11-04T04:00:00Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![gabriel.peragine](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.techsoft3d.com/gabriel.peragine/32/1535_2.png) [@gabriel.peragine](https://forum.techsoft3d.com/u/gabriel.peragine)\
**Post date:** [November 4, 2021, 4:00am UTC](https://forum.techsoft3d.com/t/how-to-using-hoops-communicator-with-ssl/1339/1 "2021-11-04T04:00:00Z")

</div>

> # 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](https://docs.techsoft3d.com/communicator/latest/api_ref/data_import/converter-command-line-options.html).

# 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](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) such as [communicator.yourcompany.com](http://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](https://en.wikipedia.org/wiki/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](http://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**](http://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](https://nodejs.org/api/cli.html#cli_node_extra_ca_certs_file) which we can use to specify additional _ **CA** _s 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](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](https://us1.discourse-cdn.com/flex020/uploads/techsoft3d/original/1X/eb1ed2bc0bb29f3fa9e93245969648bae525b304.png)

# 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](https://www.atlassian.com/git/tutorials/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.

> ⚠ 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** _):

```auto
# 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:

```auto
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** :

```auto
# 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:

```auto
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.

---

<div class="post-metadata">

**Author:** ![1435389123](https://avatars.discourse-cdn.com/v4/letter/1/ebca7d/32.png) [@1435389123](https://forum.techsoft3d.com/u/1435389123)\
**Post date:** [August 18, 2023, 3:50am UTC](https://forum.techsoft3d.com/t/how-to-using-hoops-communicator-with-ssl/1339/2 "2023-08-18T03:50:33Z")

</div>

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**

```auto
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**

```auto
:: 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

```

---

<div class="post-metadata">

**Author:** ![tino](https://avatars.discourse-cdn.com/v4/letter/t/9dc877/32.png) [@tino](https://forum.techsoft3d.com/u/tino)\
**Post date:** [August 18, 2023, 11:31am UTC](https://forum.techsoft3d.com/t/how-to-using-hoops-communicator-with-ssl/1339/3 "2023-08-18T11:31:29Z")

</div>

Hello @1435389123,

Rather than using:  
`publicHostname: "127.0.0.1",`

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

Thanks,  
Tino