Configure WebSocket connections

censhare uses WebSocket connections for bi-directional communication between censhare Web and the censhare Server. For security reasons, these WebSocket connections cannot be used by external websites by default. You can add exceptions for your own websites in the censhare Admin Client.

Context

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.

Prerequisites

none

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

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.

Key steps

After your system update, or a new installation of censhare Server, always consider the following:

Security check is active, and no other domains need access: Nothing to configure. The system is already working as expected.
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 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

Go to the Launcher configuration in Configuration -> Server in the censhare Admin Client.
Double click the entry and go to the JVM properties section.
The security check is enabled 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!
The whitelist is stored in the property com.censhare.websocket.allowed.origins. By default, the whitelist is empty.

If you update from an older system without the security check, the entries for the security check and the whitelist are missing. You can easily add the entries:

Click the Plus button at the end of the JVM properties section.
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.

If you update from an older version, you only need to edit the Launcher configuration if you want to change the default settings. For more information, see What to configure after system update.

Allow access for a website

Go to the Property com.censhare.websocket.allowed.origins in the Launcher configuration.
Enter the domain name of the desired website into the value field of the property, for example, "report.myCompany.com".
To add multiple websites, use a comma-separated list. For example: "report.myCompany.com, financial.myCompany.com".

Disable the security check

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

Go to the Property com.censhare.websocket.origincheck in the Launcher configuration.
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

You must restart the censhare Server afterwards if you have changed the Launcher configuration to become your changes effective.

Monitoring: log messages

In the following situations, a log entry is created.

If the security check blocks a website from accessing censhare:

CODE

... 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:

CODE

... 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:

CODE

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 access 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:

CODE

... 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 system update

Desired situation:

Security check is active, and no other domains need access: Nothing to configure. The system is already working as expected.
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 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.