Reconfiguring the front end service to use a secure port

Info

Note that you should always check that the new port you intend to use is not ALREADY being used by some other service.
See also Reconfiguring internal services to run on a custom port if you wish to reconfigure any of the internal services to run on another custom port.

Edit nginx.conf

CAST Imaging front end runs by default on port 80 in ≤ 2.0.0-beta5 or port 8083 (or the first free port available after 8083) in ≥ 2.0.0-beta6. To reconfigure the service to run over a secure connection (for example port 443), edit the following file:

Microsoft Windows traditional installer:
%APPDATA%\CAST\ImagingSystem\nginx\nginx.conf
    
Docker Installer extension (located in the folder created when unzipping the extension):
server\nginx\conf\nginx.conf

Info

Microsoft Windows via traditional installer

This file is located in the protected %APPDATA% location, therefore you must open the file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

Locate the “server {” block:

server {

	# Running port
	listen 8083;

Add/modify as follows - using settings to suit your environment:

server {

	# Running port
    listen              443 ssl;
    server_name         imaging.company.com;
    ssl_certificate     path/to/file.crt;
    ssl_certificate_key path/to/file.key;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ...

Save the file and ensure that you restart the CAST Imaging System - imaging-fe Windows service or the nginx Docker container in order for the new configuration to be taken into account.

CAST Imaging’s NGINX server requires a public/private key pair (.crt/.cer/.crt****and .key****files) in PEM****container format (i.e. the files defined by ssl_certificate and ssl_certificate_key**). Files presented in** **JKScontainer format for Java are not supported. In addition, self-signed certificates are not recommended - trusted certificates should be used where possible. For example,** to generate a private key and a CSR (certificate signing request) in PEM format which can be sent to a Certificate Authority (CA), run the following command on the host machine (see also https://docs.openssl.org/1.1.1/man1/req/):

openssl req -new -newkey rsa:2048 -nodes -keyout private_key.key -out csr.csr

Retain the private_key.key file and use the contents of the csr.csr file to generate the public_key.crt at your chosen Certificate Authority (CA). Note that OpenSSL (https://www.openssl.org/) is not shipped with Microsoft Windows, therefore you will need to obtain this tool first. If you have a recent release of git installed on the machine, openssl.exe is provided here: %PROGRAMFILES%\Git\usr\bin.

Info

You can find out more information here: http://nginx.org/en/docs/http/configuring_https_servers.html
If you are configuring a secure connection using self-signed certificates (not recommneded) as opposed to trusted certificates, you must ensure that any workstations which will be accessing CAST Imaging also have the self-signed certificates installed on them. If they do not, the browser will display a warning to state that the connection is insecure.

Dealing with encrypted SSL keys

Info

You can tell an SSL key is encrypted if you open the key using a text editor and either:

the first line says BEGIN ENCRYPTED PRIVATE KEY; or
one of the next lines says Proc-Type: 4,ENCRYPTED

If your organization is using encrypted SSL keys (this is unusual but does occur), the Nginx web server used by the CAST Imaging front end does not know how to deal with them and therefore the SSL configuration will not function as intended. In this situation there are two choices:

Convert the key

If you do not need to use an encrypted you can convert it to unencrypted using openssl via the following command (see https://serverpilot.io/docs/how-to-fix-an-encrypted-ssl-private-key/) - replace ssl.key.encrypted with the path and name of your own SSL key:

openssl rsa -in ssl.key.encrypted -out ssl.key.decrypted

Use the ssl_password_file parameter

If you must use an encrypted key, then you can make use of the Nginx**ssl_password_file** parameter to define a path to a file containing the passcode for the encrypted key, for example, where the file global.pass contains the passcode:

server {

	# Running port
    listen              443 ssl;
    server_name         imaging.company.com;
    ssl_certificate     path/to/file.crt;
    ssl_certificate_key path/to/file.key;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
	ssl_password_file   path/to/global.pass;
    ...

Edit imagingetl.bat or etl/app.config - 2.8.0-funcrel only

Info

This step is required in CAST Imaging****2.8.0-funcrel only (not required in subsequent or previous releases). Please read below and ensure you perform any required actions.

Edit the following file:

Microsoft Windows traditional installer:
%APPDATA%\CAST\ImagingSystem\imagingservice\imagingetl.bat
    
Docker Installer extension (located in the folder created when unzipping the extension):
etl/app.config

In this file, locate the following line:

Microsoft Windows traditional installer:
-HTTP_ENDPOINT="http://localhost:8083/imaging"

Docker Installer extension (located in the folder created when unzipping the extension):
"HTTP_ENDPOINT": "http://localhost:8083/imaging"

Change the URL**(https/port)** to match the changes you have made in the nginx.conf file. Save the file and ensure that you restart the CAST Imaging System - imaging-ETL Windows service or the etl Docker container in order for the new configuration to be taken into account.