Configure WebSocket connections

• The WebSocket protocol itself does not prevent cross-site Web Socket Hijacking (CSWSH).

• The attack is only possible for web browsers.

• censhare prevents cross-site Web Socket Hijacking in censhare Web through a security check.

Introduction

WebSocket connections are a common way for bidirectional communication between a web browser and a server. If there is an established WebSocket connection, another website can bypass the authentication and create its own WebSocket connection to attack the application. This kind of attack is called Cross-Site Web Socket Hijacking (CSWSH).

A CSWSH attack only works if a user executes the attacking website within the web browser that established the WebSocket connection. The WebSocket protocol itself does not protect against CSWSH. As of that, the application itself must prevent this kind of attack. censhare has a security check for this purpose. This article explains how to configure it.

Security configuration

We strongly advise not to deactivate the security checks. Any deactivating of the security checks is at your own risk. censhare shall not be responsible or accountable for any resulting damages.

Security check

The attack is only possible if an external website can access the censhare Server through a WebSocket connection. censhare checks if the web browser (censhare Web or an external website) tries to access the censhare Server. By default, the security check blocks all external websites. The security check is configured in the censhare Admin Client and enabled by default.  

Allowed websites

Other websites can require to access the censhare Server. For example, they use data from censhare to create reports and present the result in the web browser. By default, the security check prevents any website to access censhare through the web browser. To allow other websites to access the censhare Server, you must add the URL of the website to the whitelist in the censhare Admin Client.

Cloud Gateway

To comply with the Cross-Site WebSocket Hijacking protection in the censhare Server, the security checks for the Cloud Gateway connection must be set up and activated. 

Security checks

The Security check is active by default.

For a new installation of censhare Server, consider the following:

• Security check is active and additional domains need access:

  • Add com.censhare.WebSocket.origincheck = "true" to the Launcher configuration.

  • Add domains to the Whitelist.
    
    

• Security check is active and Cloud Gateway must be activated:
  The property com.censhare.websocket.allowed.origins must be updated with the actual host:port value of the current Cloud Gateway installation.
  • Add com.censhare.websocket.allowed.origins ="<host:port>".

• Security check is not active (not recommended and at your own risk!):

  • Disable the security check.

  • Add com.censhare.websocket.allowed.origins = "" to the Launcher configuration.

Access the configuration

1. In the censhare Admin Client, go to Configuration > Server, and double-click the Launcher configuration.

2. Go to the JVM properties section.

3. The security check is activated in the property com.censhare.websocket.origincheck. The default value is true.

   Warning: Disabling the security check can cause severe damage to your system and data. Never disable the security check on a production system!

4. The whitelist is stored in the property com.censhare.websocket.allowed.origins. By default, the whitelist is empty.

5. The host and port settings for Cloud Gateway are stored in the property com.censhare.websocket.allowed.origins. 

If you update from an older system without security checks, the entries for the security check, the whitelists, and for Cloud Gateway are missing.

You must add the entries as follows:

1. Click the + button at the end of the JVM properties section.

2. Enter the property name in the Property field and the value of the property in the field behind.

The check is also active if there are no configuration settings in the Launcher configuration.

For details, see the following sections.

Allow access to a website

1. Go to the Property com.censhare.websocket.allowed.origins in the Launcher configuration.

2. Enter the domain name of the desired website into the value field of the property, for example, "report.myCompany.com".

3. To add multiple websites, use a comma-separated list. For example: "report.myCompany.com, financial.myCompany.com".

Activate security check for Cloud Gateway

This step is mandatory.

• Go to the Property com.censhare.websocket.allowed.origins in the Launcher configuration.

• Enter the host:port value of the current Cloud Gateway installation into the value field of the property, for example, "localhost:8082".

• If this property already contains a value, you must add one more value.

• To add multiple hosts, use a comma-separated list. For example: "localhost:8082, otherhost:9090".

Disable the security check

We advise you not to deactivate the security checks. Any deactivating of the security checks is at your own risk. censhare shall not be responsible or accountable for any resulting damages.

1. Go to the Property com.censhare.websocket.origincheck in the Launcher configuration.

2. Change the value of the property to false.

If a website in the browser cannot access the censhare Server, you can temporally deactivate the security check to test if the security check is the reason. Do not leave the check deactivated!

Update the server settings

After you have changed the Launcher configuration, you must restart the censhare Server for the changes to become effective.

Monitor log messages

In the following situations, a log entry is created.

If the security check blocks a website from accessing censhare:

... WARNING: qtp588336293-1419: ServletServerChannel: Websocket host-check:
Host/Origin mismatch. Origin "report.myCompany.com" tried to access 
"censhare.myCompany.com:9443". Access is rejected

"report.myCompany.com" is the website that tries to access censhare at the URL "censhare.myCompany.com".  

If the security check grants access to a website that is on the whitelist:

... WARNING: qtp1149060125-209: ServletServerChannel: Websocket host-check: 
Host/Origin mismatch. Origin "report.myCompany.com" tried to access 
"censhare.myCompany.com:9443". Access is granted - Origin is configured in 
list of allowed hosts.

If the security check is deactivated, it writes a warning during the server restart:

Y O U R S E R V E R I S U N D E R R I S K 
- The security system property "com.censhare.websocket.origincheck" is DISABLED 
- Thus, the websocket of the server can be accessed by A N Y other host - worldwide 
- The websocket might be used for CSWSH (cross site web socket hijacking) attacks# 
P R O T E C T Y O U R S Y S T E M 
- Set property "com.censhare.websocket.origincheck" = "true" and enable it 
- Configure allowed hosts as a comma separated list in system property "com.censhare.websocket.allowed. 
Hint: the hostname of this server is not required to be listed

If the security check is disabled and a website accesses the censhare server through a WebSocket:

... WARNING: qtp1516252758-223: ServletServerChannel: Websocket host-check:
Host/Origin mismatch. Origin "report.myCompany.com" tried to access
"censhare.myCompany.com:9443". Access is granted - 
Origin check is D I S A B L E D. Enable it by setting 
property "com.censhare.websocket.origincheck" to true

What to configure after a system update?

If you update from an older censhare version, you need to edit the Launcher configuration depending on the desired situation.

By default, the security check is active.

Consider the following:

• Security check is active and additional domains need access:

  • Add the property com.censhare.websocket.origincheck = "true" to the Launcher configuration.

  • Add the property com.censhare.websocket.allowed.origins with the  ALLOWED_WEBSITE as value to the Launcher configuration.
    
    

• Security check for Cloud Gateway must be activated:
  The property com.censhare.websocket.allowed.origins must be updated with the actual host:port value of the current Cloud Gateway installation.
  • Add the property com.censhare.websocket.allowed.origins ="<host:port>" to the Launcher configuration.
  • If the property already contains a value, you must add one more value for the current cloud Gateway installation. Add com.censhare.websocket.allowed.origins ="<host:port>, <host:port>" to the Launcher configuration

• Security check is not active (not recommended and at your own risk!):

  • Add the property com.censhare.websocket.origincheck = "false" to the Launcher configuration.

  • Add the property com.censhare.websocket.allowed.origins = "" to the Launcher configuration.

Background

The following conditions are necessary for Cross-Site Web Socket Hijacking:

• A user accesses a web application through a web browser.

• The web application communicates with the web browser through a WebSocket connection.

• The user opens an external website with malicious code in the same web browser.

• The web application does not check if a request for a WebSocket connection is coming from the web browser itself or an external website.

When users want to access the web application, they must authenticate themselves. The web browser then receives an authentication token if this is successful. If a user opens an external website, this website can use the authentication token stored in the web browser. This token allows the foreign website to open its own WebSocket connection or read the communication of existing ones. The external website must not authenticate itself to the web application.  

The WebSocket protocol does not prevent this. The web application must do this itself. In the case of censhare, this is done by the security check.

Result

You know that censhare prevents Cross-Site Web Socket Hijacking. You know how the security check against this attack is enabled and how to add exceptions for well-known websites to the whitelist.