WebSocket Support

VTScada provides server-end support for WebSocket connections, compliant with RFC 6455. External clients can create a WebSocket on VTScada but there is currently no support for VTScada to create a WebSocket on an external server.

WebSockets and Security

  • For security, all WebSocket communication must be performed over a secured connection (HTTPS).
  • WebSocket upgrade requests must provide a valid HTTP Origin header that matches the name of the VTScada server the WebSocket is being created on.

 

A WebSocket upgrade request to a VTScada Internet Server will be permitted only if:

  1. There is a known "consumer" of the connection. (That is, VTScada code that has registered an interest in receiving the WebSocket.)
  2. The WebSocket has an acceptable Sec-Websocket-Version value.
  3. Authentication of the connection is successful.

Authentication is done either by HTTPServer via the VTScada Security Manager, which is used for authenticating users, or by an authentication mechanism provided by the consumer. This does not prevent the consumer from using the Security Manager to authenticate the credentials, rather than HTTPServer.

The size of WebSocket messages is limited by HTTPRequestMaxSize. The default provides security from actors attempting to consume large blocks of memory but the value may need to be increased if your application expects larger WebSocket messages.

Connection Process

The process begins by establishing a connection to a VTScada Internet Server. A request is issued to upgrade that connection to a WebSocket. Once upgraded, only the WebSocket protocol will be supported on that connection for the remainder of the connection's lifetime. WebSocket upgrade requests will be accepted only for subscribed consumers to HTTPServer. As endpoint verification is outside the control of the VTScada HTTPServer, the consumer must perform their own authority verification and sanitization of received data.

 

A WebSocket is created by the remote entity sending a valid WebSocket upgrade HTTP request with a Request-URI identifying a WebSocket request.

GET /{realm}/{application-GUID}/WEBSOCKET/{consumer-ID} HTTP/1.1

Where:

  • {realm} is a valid, configured realm name that a consumer has registered in interest in.
  • {application-GUID} is the GUID of the application containing the consumer.
  • WEBSOCKET is a literal verb.
  • {consumer-ID} is an identifier provided by the external entity requesting the connection be upgraded to a WebSocket. The format and content of this is determined by the consumer and external entity.

 

If the WebSocket upgrade request is successful, the consumer of a WebSocket will be presented with a bi-directional stream that encodes and decodes messages to WebSocket protocol without the consumer being required to have any knowledge of the underlying WebSocket protocol. A received set of WebSocket frames will be assembled into one message and presented in the stream to the consumer. Similarly each write the consumer makes to the stream will be transmitted as one WebSocket message, split into frames as required.

The application-GUID and RequestURI provided in the HTTP request to VTScada are used as a key to determine which consumer in VTScada the WebSocket will be passed to.

Write a WebSocket Consumer module

The consumer module within VTScada must register with HTTPServer via the WebSktSubscribe, HTTPServer subroutine. It must also provide a set of callback subroutine modules that are used during setup of a new WebSocket connection. The callback subroutines are described within the notes for WebSktSubscribe.