Secure Communication for a Queue Agent
Configuration of secure WebSocket and HTTPS for Queue Agents is handled centrally and the necessary runtime configuration and certificates are published to each Queue Agent.
This requires secure WebSocket to be configured on the central server
before configuring it on the central Queue Agent.
Distributed Queue Agents each have their own set of certificates, which are stored and provisioned from the central server.
The same certificate will be used for both secure WebSocket and HTTPS, on distributed Queue Agents.
Enabling HTTPS for HTTP communication between Queue Agents and Central
The following flow chart illustrates the steps needed to enable HTTPS for HTTP communication between Queue Agents and Central. The steps are described in more detail below:
Precondition:
1. In the System Administration application, open the Parameters tab and locate the Agent Parameters section:
2. Select https as Central HTTP Protocol and Central HTTP Port to 8443.
3. Save the Parameters and restart the Orchestra service.
Enabling secure WebSocket on a Central Queue Agent
This step is only necessary if you have hardware devices, such as a printer or a GW1745 connected to your Central Queue Agent.
In this scenario, we will secure the communication for a central Queue Agent, as highlighted in the following picture:
The following flow chart illustrates the steps needed to enable Web Socket Secure between a Central Queue Agent and all connected devices, such as GW1745 / Hub:
2. Navigate to System Administration -> Queue Agents -> Agents. Select the Central Queue Agent.
3. In the Security section, under Prepared security configuration, enable the check box for WebSocket Secure enabled and select a port for WebSocket Secure port (default: 8989):
4. Click Save to stage the configuration.
5. Click Publish to enable secure WebSocket.
This action will cause the device controller ports (8888 and 8989) to be restarted on the central Queue Agent, causing all connected devices (e.g. gw1745, Cinematic, HubMedia, Intro17 etc) to reconnect.
This might cause an interruption for ongoing business and should therefore be done outside business hours.
6. Log in to the applicable device, for example Hub, in the Device Controller tab, enable SSL and set the WSS port to 8989. For more information, please read the applicable hardware manual, found on Qmatic World.
Enabling secure WebSocket on a Distributed Queue Agent
This step is only necessary if you have hardware devices, such as a printer, Hub or a GW1745 connected to a distributed Queue Agent.
In this scenario, we will secure the communication for a distributed Queue Agent, as highlighted in the following picture:
The following flow chart illustrates the steps needed to enable Web Socket Secure between a Distributed Queue Agent and all connected devices, such as Hub /GW1745. Each number (1a, etc) refers to a certificate type, described by a corresponding section below.
The Queue Agent will keep the previously configured keystore during the Agent Profile synchronization part of the remote upgrade. The file
keystore.jks will not match the one in the Agent Profile, centrally. Thus, the keystore must be managed through the
Security section, as described in this section.
1a: Certificate Generated by Orchestra, used as is
1. Navigate to System Administration -> Queue Agents -> Agents. Select the wanted Queue Agent.
2. In the Security -> Key pairs section, click the Create new button.
3. A new window, Create new key pair, will be shown. Below is an example of what it may look like when filled in:
Enter the necessary fields:
• Keystore alias: The name the alias/certificate will be referenced in the configuration. (Mandatory)
• Common name: This is the host name or IP address of the Queue Agent. (Mandatory)
• Organization unit: The organizational unit (e.g. a department name). (Optional)
• Organization name: The organizational name (e.g. the company name). (Optional)
• Locality name: The locality (e.g. city). (Optional)
• State name: The state/region. (Optional).
• Country: The country. (Optional)
• Subject alternate name: additional host names / IP addresses the certificate should be valid for, separated by a comma. (Mandatory).
Click Generate key pair when the fields are filled in.
These fields will be combined to form the fully distinguished name of the certificate.
Example, using these values :
Key store alias: myAgentAlias
Common name: 127.0.0.1
Organization unit: RnD
Organization name: Qmatic
Locality name: Molndal
State name: VGR
Country: SE
Subject alternate name: 127.0.0.1, localhost
This will generate a certificate entry with the distinguished name "cn=127.0.0.1, ou=RnD, o=Qmatic, l=Molndal, s=VGR, c=Sweden. This certificate will be valid for host names 127.0.0.1, localhost.
When the certificate is stored, the alias name will be suffixed with a timestamp (e.g.
myAgentAlias-2017-04-10T13:37:00). This is to avoid conflicts and overwriting previously used certificates.
4. Navigate to System Administration -> Queue Agents -> Agents. Select the wanted Queue Agent.
5. In the Security -> Prepared security configuration section, enable the check box for WebSocket secure enabled and select a port for WebSocket Secure port (default: 18989 for Distributed Queue Agents:
It is also possible to enter
Agent hostname here. This is the hostname of the Queue Agent and it must be resolvable by DNS. A Branch publish is needed for a hostname change to take effect.
6. Ensure that the selected alias in the WebSocket Secure key pair setting is correct. If not, select a different alias in the drop-down list in the Key pairs section and click Select to choose it as the active alias/certificate.
7. Click Save to stage the configuration.
8. Click Publish to enable secure WebSocket.
This action will cause the device controller ports (18888 and 18989) to be restarted on the Queue Agent, causing all connected devices (e.g. gw1745, Cinematic, HubMedia, Intro17 etc) to reconnect.
This might cause an interruption for ongoing business and should therefore be done outside business hours.
9. Log in to the applicable device, for example Hub, in the Device Controller tab, enable SSL and set the WSS port to 18989. For more information, please read the applicable hardware manual, found on Qmatic World.
1b: Certificate Generated by Orchestra, to be sent to a CA Authority for signing
1. Navigate to System Administration -> Queue Agents -> Agents. Select the wanted Queue Agent.
2. In the Security -> Key pairs section, click the Create new button.
3. A new window, Create new key pair, will be shown. Below is an example of what it may look like when filled in:
Enter the necessary fields:
• Keystore alias: The name the alias/certificate will be referenced in the configuration. (Mandatory)
• Common name: This is the host name or IP address of the Queue Agent. (Mandatory)
• Organization unit: The organizational unit (e.g. a department name). (Optional)
• Organization name: The organizational name (e.g. the company name). (Optional)
• Locality name: The locality (e.g. city). (Optional)
• State name: The state/region. (Optional).
• Country: The country. (Optional)
• Subject alternate name: additional host names / IP addresses the certificate should be valid for, separated by a comma. (Mandatory).
Click Generate key pair when the fields are filled in.
These fields will be combined to form the fully distinguished name of the certificate.
Example, using these values :
Key store alias: myAgentAlias
Common name: 127.0.0.1
Organization unit: RnD
Organization name: Qmatic
Locality name: Molndal
State name: VGR
Country: SE
Subject alternate name: 127.0.0.1, localhost
This will generate a certificate entry with the distinguished name "cn=127.0.0.1, ou=RnD, o=Qmatic, l=Molndal, s=VGR, c=Sweden. This certificate will be valid for host names 127.0.0.1, localhost.
When the certificate is stored, the alias name will be suffixed with a timestamp (e.g.
myAgentAlias-2017-04-10T13:37:00). This is to avoid conflicts and overwriting previously used certificates.
4. In the Key pairs section, in the drop-down list, select the certificate and click Manage signing, the following window will be opened:
Click the Download button. This will generate a Certificate Signer Request that will be downloaded in your browser.
5. Send the Certificate Signing Request file to the desired Certificate Authority to get it signed.
The response should be one file for the signer response as well as a number of files describing the trust chain of the Certificate Authority.
Supported file formats are .cer, .der and .crt.
6. Navigate to System Administration -> Queue Agents -> Agents. Select the wanted Queue Agent.
7. In the Security -> Key pairs section, select the correct alias in the drop-down box and click the Manage signing button. The following window will be opened:
8. Click the Choose Files button. Select the certificate signer response, as well as the files containing the trust chain of the Certificate Authority.
9. Click the Upload button.
10. The certificate is now fully signed and can be properly used.
11. Navigate to System Administration -> Queue Agents -> Agents. Select the wanted Queue Agent.
12. In the Security -> Prepared security configuration section, enable the check box for WebSocket secure enabled and select a port for WebSocket Secure port (default: 18989 for Distributed Queue Agents:
It is also possible to enter
Agent hostname here. This is the hostname of the Queue Agent and it must be resolvable by DNS. A Branch publish is needed for a hostname change to take effect.
13. Ensure that the selected alias in the WebSocket Secure key pair setting is correct. If not, select a different alias in the drop-down list in the Key pairs section and click Select to choose it as the active alias/certificate.
14. Click Save to stage the configuration.
15. Click Publish to enable secure WebSocket.
This action will cause the device controller ports (18888 and 18989) to be restarted on the Queue Agent, causing all connected devices (e.g. gw1745, Cinematic, HubMedia, Intro17 etc) to reconnect.
This might cause an interruption for ongoing business and should therefore be done outside business hours.
16. Log in to the applicable device, for example Hub, in the Device Controller tab, enable SSL and set the WSS port to 18989. For more information, please read the applicable hardware manual, found on Qmatic World.
2a & 2b: Already existing Certificate, signed by public CA or Private Body
Similar to a response from a Certificate Authority, a pre-signed certificate will contain one file with the key-pair and more files making up the trust chain of the Certificate Authority.
Supported file formats for the key-pair are
.pfx and
.p12.
Supported file formats for the trust chain are
.cer, .der and .
crt.1. Navigate to System Administration -> Queue Agents -> Agents. Select the wanted Queue Agent.
2. In the Security -> Key pairs section click the Upload new button. The following window will be opened:
3. Enter a new KeyStore alias name.
4. Click the Choose Files button and select the key-pair file as well as the files containing the trust chain of the Certificate Authority.
5. Enter the Key pair password for the key-pair file.
6. Click Upload.
7. The certificate and trust chain should now be imported and can be properly used.
8. Navigate to System Administration -> Queue Agents -> Agents. Select the wanted Queue Agent.
9. In the Security -> Prepared security configuration section, enable the check box for WebSocket secure enabled and select a port for WebSocket Secure port (default: 18989 for Distributed Queue Agents:
It is also possible to enter
Agent hostname here. This is the hostname of the Queue Agent and it must be resolvable by DNS. A Branch publish is needed for a hostname change to take effect.
10. Ensure that the selected alias in the WebSocket Secure key pair setting is correct. If not, select a different alias in the drop-down list in the Key pairs section and click Select to choose it as the active alias/certificate.
11. Click Save to stage the configuration.
12. Click Publish to enable secure WebSocket.
This action will cause the device controller ports (18888 and 18989) to be restarted on the Queue Agent, causing all connected devices (e.g. gw1745, Cinematic, HubMedia, Intro17 etc) to reconnect.
This might cause an interruption for ongoing business and should therefore be done outside business hours.
13. Log in to the applicable device, for example Hub, in the Device Controller tab, enable SSL and set the WSS port to 18989. For more information, please read the applicable hardware manual, found on Qmatic World.
Secure HTTPS communication for a Distributed Queue Agent.
To enable HTTPS for a distributed Queue Agent, first enable WebSocket Secure communication for the distributed Queue Agent.
Once that is done, the only thing that is needed is to restart the Queue Agent.
The HTTPS connector in Jetty will use the same certificate that was used when configuring WebSocket Secure.
Enabling HTTP to HTTPS redirect
To enable HTTP to HTTPS redirect:
1. Navigate to System Administration -> Queue Agents -> Agents. Select the wanted Queue Agent.
2. In the Security section check the HTTP to HTTPS redirect enabled check box. Save the settings.
3. Restart the Queue Agent.
Selecting HTTPS protocol strength
By default, only the TLSv1.2 HTTPS protocol is enabled.
Depending on the client environment, connected hardware, browsers etc, it might be necessary to enable weaker HTTPS protocols.
The protocols that can be enabled are:
• SSLv3
• TLSv1
• TLSv1.1
• TLSv1.2
SSLv3 is necessary if a Vision unit is going to be connected to the system. If no such units are going to be connected to the Central Queue Agent, this protocol should not be enabled.
TLS versions prior to 1.2 might be needed for older types of browsers, this would depend on the client environment.
Wildfly
Edit the app\wildfly-11.0.0.Final\standalone\configuration\standalone-full.xml file.
Locate the https-listener configuration tag, change the enabled-protocols attribute, so that it matches the requirements, example:
enabled-protocols="TLSv1,TLSv1.1,TLSv1.2"
Save the file and restart Orchestra.
