Automatic licensing of the Carrida software

Revision: 1.1
Date: 2019-05-25
Contact: support@carrida-technologies.com
Copyright: 2017-2019 Carrida Technologies GmbH, Ettlingen, Germany
Author: Carrida Technologies

Home page

Table of Contents

1   Introduction

This framework is aimed at the fully automatic licensing process of the Carrida software on multiple devices (intelligent cameras, PC's etc) combined with a local network. This can be needed for the cases where any manual intervention is unwanted, e.g. if the number of devices to activate is so big that the manual license activation would cost a lot of time. Also, this framework is designed to support activation on devices that do not have direct Internet access. A typical case is a camera needed to be activated during the production.

The usual license activation pipeline consists of the following steps:

  1. A hardware fingerprint file (c2v) is generated on a target device (e.g. with the help of the fplc command line tool in Linux, or GUI program in Windows)
  2. This file needs to be sent to the Carrida support stuff - a corresponding license activation file (v2c) will be sent back. Alternatively, online license file acquisition is also possible.
  3. The received v2c file needs to be applied to a target device.

The proposed client-server framework combines all of these steps. It consists of two major parts:

  1. Local PC Client running on Windows OS. The client needs to be connected to the Internet as well as it has to be able to communicate with the target devices.
  2. A small one-time server running on each device that is needed to be activated.
./images/server-client.png

Licensing framework architecture.

The automatic licensing pipeline works as follows:

  1. Once started, a server on a target device collects fingerprint information and sends it to the PC client.
  2. PC client listens for messages from 1. and forwards the contained fingerprint to the Carrida license server.
  3. An activation file will be sent back from the Carrida license server to the local PC client.
  4. The client forwards this file to the corresponding device from 1.
  5. The device server applies license activation using this file and quits - the device is activated now.

The whole automatic activation process takes about 15-20 seconds per device. A PC client can simultaneously communicate with multiple devices.

Note

Note Sign A prerequisite for the PC client in point 2. is a valid product key. This key will be issued upon purchase of Carrida 4 licenses.

2   Server side

A server is a command line tool that has to be executed once for each device that needs to be activated. The activation tools rely on three parameters for communication:

  • A Multicast Address. This is the IP address for the server to send broadcast messages to, so that the client knows it is online (default 239.192.13.240)
  • A Broadcast Port. The port to which the messages are sent (default: 7130).
  • A Listen Port. The specific port on which the server listens for connections (default: 7140).

The above three parameters are defined in the tool as default values, but can easily be changed in the code if necessary (see below). Once started, the tool acting as a server sends a broadcast message and will be discovered by the PC client SW which runs on a Windows PC in the local network (see next Section below).

A connection is established and data exchange is started according to the client settings.

2.1   Server Activation Implementation

The installation package provided with Carrida 4 provides the source code for a small activation tool on the device side, which is fully functional. It can be used to automatically license the device by creating and sending a c2v file to a local server, and by receiving and activating the corresponding v2c file.

Basically, the tool provides only one function activateCarrida. This function opens all necessary communication channels with the local activation server and handles the necessary calls to the SW licensing functions.

The very simple entry point for the tool, taken from the source code module main.cpp, looks as follows:

int main(int argc, char **argv)
{
    // parse command line arguments
    // IPaddress = argv[1];
    // ...

    try
    {
        // we use all the default values
            activateCarrida();

    }
    catch (std::exception& e)
    {
        std::cerr << e.what() << std::endl;
    }

    return 0;
}

The activation function looks as follows, note that the default communication parameters can be overridden with custom values, if necessary.

/*
 * =====================================================================
 * Carrida activation function.
 *
 * Starting the communication threads and takng care of the
 * high level communication.
 *
 * =====================================================================
 *
 */
void activateCarrida(const int activationPeriod = 20000, // milliseconds
                     const int timeOut          = 1000,
                     std::string IPaddress      = DEFAULT_IPV4_ADDRESS,
                     const int broadcastPort    = MULTICAST_PORT,
                     const int listeningPort    = LISTEN_PORT);

Above given functionality can easily be integrated into custom applications. The code above uses default values for IP addresses, ports, and time- outs, but those can be overridden by using function arguments. The default communication ports which are used by the tool are as follows:

const std::string DEFAULT_IPV4_ADDRESS = "239.192.13.240";
const std::string DEFAULT_IPV6_ADDRESS = "ff18::CADA:ACAE";
const unsigned short MULTICAST_PORT    = 7130;
const unsigned short LISTEN_PORT       = 7140;

Note

Note Sign The low- level API functions to create c2v data and to activate the license are a part of the Carrida 4 SDK. Their use is exemplified within the source code modules of the activation tools.

3   Client side

Each device that needs to be activated communicates with a client program running on the local network. This client program is a Windows GUI tool with an interface as shown in the following image.

./images/gui-client.png

Local PC client.

The client can simultaneously communicate with multiple devices. It can be seen as a transition point between devices, needed to be activated and the Carrida server. The activation process can be explained as follows.

  1. The client listens for incoming Hello messages on a predefined broadcast IP-address and port.
  2. Once a Hello message is received, a connection to the corresponding remote device (sending that Hello message) is established.
  3. At this point, the client starts to send tasks to the server running on a device that is needed to be activated. This includes:
    1. Retrieving the device hardware fingerprint. Once retrieved, the client sends this fingerprint to the Carrida server over the Internet and gets a corresponding activation code back.
    2. Activating/updating Carrida license on a target device. The client forwards the activation code to the server, and the server performs the activation/updating of the Carrida license.
    3. Retrieving the activation status. The server checks the activation status and sends it to the client.
  4. Once the activation process is finished, the server quits and the connection will be closed.

The prerequisite for the automatic activation process is the presence of a valid production key that has to be obtained from the Carrida Tech support. The product key is needed to establish a connection with the Carrida server to be able to make online activations. One key allows 1 to N activations depending on the purchase. A product key can be recharged on demand - e.g. if the number of remaining activations is getting too small.

Following two tables describe each Client parameter in detail. The Client saves values of all its text fields internally - once the program is restarted, the last used configuration will be reloaded.

3.1   Camera actions.

These parameters relate to the intern server-client communication including the local network interface and protocols to use as well as tasks to perform. The default values are usually sufficient and do not need to be changed unless there is a reason for that. The parameter Tasks defines what actions have to be performed. Once all parameters are set/ checked, the button "Listen" can be pressed - the Client will be set to the operational mode.

p1
All active connections, as well as the history of all connections, are displayed here. For each connection, following information is shown:
Fingerprint. A hardware fingerprint of a device.
Interfaces. List of network interfaces that are available on a device. Each interface consists of a pair "interface - mac address."
IPv4 Address / IPv6 Address - IPv4/IPv6 address of the device, depending on what version of the IP protocol is used in the local network.
Last Connected. Local date and time of each connection.
Status. Activation status. A value 0 means the device has been successfully activated. All other values represent the activation error code (for the description of the error codes please refer to the lprlicense.h file in the Carrida distribution).
p2
Broadcast address and port to listen for incoming connections. The default is 239.192.13.240:7130, but this can be freely changed. For the address, only first two numbers 239.192 have to be kept, as they are designed for the broadcast messages.
Note: if these two parameters are supposed to be changed, they have to be set to the same values on the server side!
p3
Port to communicate with a local server. The default is 7140 but this can be freely changed.
Note: if this parameter is supposed to be changed, it has to be set to the same value on the server side.
p4
Different options for the activation process are available here:
Collect Fingerprints. Collect fingerprints of each device and store them locally. This can be useful if the client is not connected to the Internet. Stored fingerprints can be used at a later point.
Collect & Activate. Perform full license activation pipeline including the fingerprint collection, sending it to the Carrida server, receiving back an activation file and sending it to the target device server.
Collect & Update. Similar to previous one, except that an update of an existing license instead of a new activation will be performed.
p8 Different network interface options for internal client-server communication are displayed here. The content of the list can be varying depending on what interfaces are available on a Client PC. A user can select the appropriate option depending on the architecture of its local network.
p9
Once all parameters are set up, the Client can be set to the listening mode. The text in green color at the top of the main window "Server running" indicates that the Client is ready for the incoming local connections.
Note: If either a camera action parameter, the tasks to perform or the network interface has been changed, the Client has to be restarted by pressing the Stop/Listen button.
p10 Export all hardware fingerprints collected during the current session to a specific folder as a set of c2v files. This can be used if the client is not connected to the Internet (and thus, does not have a connection to the Carrida server). In that case, Tasks has to be set to Collect Fingerprints. The client will aggregate fingerprints of all local devices that initiate connections.
p11 Set version of the TCP/IP protocol used on the local network.

3.2   Activation Configuration.

Following parameters relate to the Client - Carrida server communication. They can be skipped if the Client is not connected to the Internet.

p5
Credentials for the Carrida server:
Product Key. A valid product key received from the Carrida Tech. A product key allows 1 to N license creations. The text above tells how many activations are left for this product key.
Base URL. URL of the Carrida licensing server obtained from Carrida Tech.
Comment (optional). Optionally, arbitrary comment text.

Note: on each change of the first two parameters, the button "Set Credentials" has to be used to refresh the credentials.
p6 When pressed, detailed information about the used product key will be displayed.
p7
Refresh credentials information for the Carrida server. If no error messages are displayed, parameters are successfully set.
Note: when the program is started, the last used credentials will be set automatically. This button is needed only if credentials data has been changed within the active session.