Connection

The web browser helps make a WebSocket connection easy.

Built-in WebSocket Service

Once a connection to a configured Web Server port (default 80 and 443) is made and upgraded from the default HTTP Protocol to the WebSocket Protocol, traffic must conform to the WebSocket specification. Except in the case discussed in Section 3.2 the JANOS Web Server uses a built-in server to handle all WebSocket messages then received. These must use the JSON format and the connection must be authenticated.

To initialize communications the client should send a blank or empty message. The following is acceptable.

{
  "Message":"" 
}

The connection will proceed depending on the authentication requirements established by the JNIOR configuration and the environment making the connection (browser, application, etc.).

Default Permissions

The Series 3 JNIOR (Models 310, 312, and 314) were shipped where by default web pages were not protected by login. The login requirement encountered when running the applets was the result of security in the JNIOR Protocol. Access to web pages could be controlled by permissions set on individual files or folders. For instance, removing the read attribute (R) from the /flash/www folder would force the browser to ask for login credentials and thus protect the pages. Unfortunately, a second login would then be required by the JNIOR Protocol which has to be separately protected since control and configuration were possible through it. Modifying folder permissions involved a console command (CHMOD) which tended to be unfamiliar to everyone.

The Series 4 JNIOR (Models 410, 412, and 414) use a new Registry key WebServer/Login to control web page access. This key by default is set to TRUE. The dynamic configuration pages therefore also request login credentials but a second login is not required due to the Websocket Protocol implementation which will be discussed in a moment. The WebSocket Protocol replaces the JNIOR Protocol just as the dynamic configuration pages replace the applets that have been dropped. You may still control access to areas of the JANOS website using file and folder permissions if desired. That would only be necessary should you disable the WebServer/Login requirement.

WebServer Login Enabled

With the Web Server Login requirement enabled any access to the JANOS website is challenged using the standard 401 Unauthorized response. The JANOS Web Server provides the necessary parameters so the browser can request the user’s login credentials. If the proper credentials are entered and verified by JANOS the page is promptly served. A session ID is assigned.

Subsequently, the Authorization information is supplied with requests for other pages required from the website. The JANOS Web Server recognizes the association between those credentials and the original login and therefore doesn’t challenge every page. When the browser then moves to open a WebSocket connection it uses the temporary session ID for authentication. A second is not required. This can be done because all of these connections are handled by the Web Server. This is unlike the JNIOR Protocol which is a separate server entirely and cannot be passed shared authentication information.

Once you have authenticated for the website, you can create WebSocket connections in the browser session without an additional login step. Immediately after opening the WebSocket connection, you will receive a “Monitor” message and you are good to go.

WebServer Login Disabled

If you set the WebServer/Login key to FALSE and assuming that permissions on files and folders have not been modified retaining the default Read Access flag, the browser will not need to request your login credentials. When a WebSocket is then made there are no preauthorized credentials. The login handshake in the WebSocket connection will be required before you may proceed using the WebSocket. This behavior assumes that the Websocket/Anonymous registry key has not been defined or is set to 0.

Upon opening the connection a “monitor” message will not be provided. The application needs to send a blank message and will receive the 401 Unauthorized error. The application will then need to request the user’s credentials and calculate the Auth-Digest response on its own. This is the same procedure performed by the browser. The dynamic configuration pages supplied with the JNIOR provide for this requirement. The Javascript can be used for reference.

Once the user credentials are processed the handshake can be completed and will proceed as follows.

{
  "Message":"" 
}

{
  "Message":"Error",
  "Text":"401 Unauthorized",
  "Nonce":"5d894efb48e1c3bc074fe78e7a5f" 
}

{
  "Auth-Digest":"jnior:65f2d1cb66ef63f7d17a764f3a2f2508" 
}

{
  "Message":"Authenticated",
  "Administrator":true,
  "Control":true
}

A “Monitor” message will likely immediately follow. This might even be received before the “Authenticated” message. That is the asynchronous nature of the connection. Please feel free to contact INTEG for assistance in implementing the digest calculation.

Anonymous Operation

If the Websocket/Anonymous registry key is set to a valid user ID (1 is generally the JNIOR Administrator’s ID), then no login will be required. The USERS console command can be used to determine the available user IDs. This, however, is extremely dangerous. Any application can then make a fully functional WebSocket connection. This gives anyone access to the unit with the ability to raise havoc with controls and to modify JNIOR configuration. This is not recommended. If there is physical security, meaning that access is only available to personnel on the local network and all those can be trusted, then this setting may be of use. Otherwise, you are allowing anonymous access to this connection at your own risk.

It is important to note that even if you have WebServer/Login set to TRUE and have to enter a username and password to bring up the website, the WebSocket interface is not secure if anonymous access is enabled. A separate application or copy of the website can get full control of your JNIOR.

With the anonymous key set to a valid user ID, the WebSocket connection will not require login. Immediately after making the connection you will receive the “Monitor” message. The connection is then available for full use.