Corrade features a TCP server that is included in Corrade and allows you to retrieve notifications with or without SSL encryption. There are cases where a frontend is created that is not capable of accepting inbound connections. In the latter case, the fronted can initiate a persistent TCP connection to Corrade and ask that certain specified notifications be sent over the initiated TCP connection. Furthermore, the TCP server allows Corrade commands to be executed as well as receiving notifications.

The protocol is built onto the already existing Corrade communication semantics. Here is a rough sketch of how the initial handshake and the ensuing communication between a frontend and Corrade takes place:

Where the individual numbered stages can be described as:

1. The frontend initiates the connection to Corrade's TCP notification port and sends a request for a notification. This is done similar to sending commands by sending:
   • The group name or UUID passed as the value of the group key.
   • The group password passed as the value to the password key.
   • The notification type that Corrade should send to the frontend (for example, local for messages on local chat, etc…).
2. Corrade then tries to authenticate the group and password pair, additionally checking whether the group, if successfully authenticated is allowed to receive the requested notification type. Depending on whether the former succeeds, Corrade sends the success status set to True or False in the success key.
3. In case the former step was successful, Corrade will send notification data to the connected frontend as it arrives. Corrade will then keep posting notification data to the TCP frontend until the connection is severed.

After the connection is severed, any new connection will have to first complete the handshake and authenticate to Corrade before Corrade will accept to send the data.

Corrade can run the TCP server with or without encryption depending on whether a certificate file is found or not. Note that all data between a frontend and the Corrade TCP server is sensitive such that it is imperative to ensure that the channel is private. In case you want to use encryption you will need to generate a certificate for Corrade to use. This is due to some of the data such as group passwords possibly being transmitted in plaintext in the absence of the AES output filter.

To generate the certificates on Windows, you would have to download the Windows SDK in order to install the makecert.exe and pvk2pfx utilities. After downloading the Windows SDK, the only tools needed are the .NET tools.

After installing, you can start a special command-shell that will include them in your path. On Windows 7, after installing the Windows SDK, you can navigate to Start→All Programs→Microsoft Windows SDK v7.0→CMD Shell to start the shell.

With the shell open, change directory to some place where you want to generate the certificate (a good option is in Corrade's folder) and issue the following commands:

makecert.exe -r -pe -n "CN=CORRADE" -sky exchange -sv CORRADE.pvk CORRADE.cer

where:

• CORRADE can be changed to anything you want,

The next step is to convert using pvk2pfx by issuing:

pvk2pfx -pi PASSWORD -pvk CORRADE.pvk -spc CORRADE.cer -pfx CORRADE.pfx

where:

• CORRADE should be the same value you chose earlier on
• PASSWORD is a password for your certificate file and will have to be supplied later in Corrade's Configurator tool.

Next, import the certificate: simply right click the generated file ending in pfx (it should have a distinguishable icon - document with a key) and then select Install from the menu. Follow the prompts and just accept the defaults.

Finally, open Corrade's Configurator tool and navigate to the TCP tab (may need to change the experience level for the tab to be unghosted) and then click the Load… button and select the pfx file you have generated in the previous steps. If you have used a password as instructed, then enter the password in the corresponding box on the TCP tab of the configurator. Corrade should now allow you to tick the box and enable TCP notifications.

Assuming that an SSL certificate is provided and the TCP server is secured, let the Corrade TCP notifications server be set-up such that:

• 192.168.1.16 is the IP address on which Corrade is configured to listen for connections to retrieve TCP notifications and that his IP address is accessible from the current machine.
• 8095 is the port on which Corrade is configured to listen for connections to retrieve TCP notifications.
• We have a configured Corrade group that is allowed to receive local notifications - for retrieving local chat in-world. That group is named My Group and the group password is mypassword.
• The TCP notification certificate is installed and configured in the TCP tab of the Corrade configurator.

Then, using openssl under Linux (and OS X via Terminal), we can test the TCP notifications by first issuing a connect request on the command shell:

openssl s_client -tls1_2 -connect 192.168.1.16:8095

where -tls1_2 indicates that we wish a TLS 1.2 SSL protocol - note that some protocols may not be supported by your openssl binary and will need an upgrade. Otherwise, you can switch the protocol type using the Corrade configurator tool. It is a good idea to avoid SSLv3 because it is broken and your communication can be compromised.

this command will attempt a TCP connection to the IP address 192.168.1.16 and port 8095 where Corrade should be listening. This command, if successful, will output details on the SSL connection and then it will stop indefinitely. If the command was not successful, control will return to the command shell.

Assuming that the connection was successful, we issue a request to retrieve local notifications (to retrieve local chat messages in-world). So, we just type the request:

group=My Group&password=mypassword&type=local

If the set-up is correct, we will obtain success=True, after which, if we talk on local chat next to Corrade in Second Life, the notification data will be sent to the terminal.

The following script demonstrates accessing Corrade's internal TCP server from Node.JS:

/*************************************************************************/
/*    Copyright (C) 2018 Wizardry and Steamworks - License: CC BY 2.0    */
/*************************************************************************/
/*                                                                       */
/* Short example for using Corrade's built-in TCP server in node.js. The */
/* script will access Corrdade's TCP server and bind to the "message"    */
/* and "group" notifications that will be displayed on the console.      */
/*                                                                       */
/*************************************************************************/
 
/*************************************************************************/
/*                          CONFIGURATION                                */
/*************************************************************************/
const group = 'My Group';
const password = 'mypassword';
const type = 'group,message';
const TCPHost = 'server.tld';
const TCPPort = '8085';
const TCPCertificate = 'client1-crt.pem';
const TCPCertificateKey = 'client1-key.pem';
const TCPCertificateAuthority = 'ca-crt.pem';
 
/*************************************************************************/
/*                            INTERNALS                                  */
/*************************************************************************/
// Import packages.
var tls = require('tls');
var fs = require('fs');
var rl = require('readline');
var eol = require('os').EOL;
 
// If the certificates are self-signed then this parameter needs to be set.
process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
 
/*
 * Certificates have to be generated because Corrade's TCP server only
 * accepts secure TCP connections.
 */
var  tlsOptions = {
    host: TCPHost,
    port: TCPPort,
    cert: fs.readFileSync(TCPCertificate),
    key: fs.readFileSync(TCPCertificateKey),
    ca: fs.readFileSync(TCPCertificateAuthority)
};
 
// Start TLS connection to Corrade's TCP server.
var client = tls.connect(tlsOptions, function() {
    console.log('Connected');
 
    // Corrade only uses UTF-8 encoded data.
    client.setEncoding('utf8');
 
    // Perform Corrade authentication and bind to group and message
    // notifications.
    client.write(
        'group=' + group +  
        '&password=' + password + 
        '&type=' + type 
        + eol
    );
 
    /*
     * Corrade's TCP server sends messages delimited by newlines such that
     * a line-oriented is needed on top of the TCP stream.
     */
    var i = rl.createInterface(client, client);
    i.on('line', function (line) {
        /*
         * Display any notification data on the console.
         */
        console.log('Received: >' + line + '<');
    });
});
 
client.on('close', function() {
	console.log('Connection closed');
});
 
client.on('error', function(error) {
    console.log(error);
});