Thinfinity VirtualUI configuration

Managing licenses through the Thinfinity VirtualUI OEM Licensing API

Managing licenses through the Thinfinity VirtualUI OEM Licensing API

Introduction

To help bundling Thinfinity VirtualUI with their applications, companies applying for OEM licensing can take advantage of three new features: Server Configuration API, OEM Licensing API and White Labeling customization.
In this article we will cover the Thinfinity VirtualUI OEM Licensing API.

Thinfinity VirtualUI OEM Licensing API – How does it work?

If your product qualifies for OEM licensing, we will provide you with a Licensing Library, the Thinfinity VirtualUI OEM Licensing API that would enable OEM-licensed Companies to create and revoke end-user’s Thinfinity VirtualUI licenses.
There are two prerequisites:

  • The application that uses the OEM Licensing Library (Thinfinity.VirtualUI.OEM.dll) must be digitally signed.
  • You must have a valid OEM key.

To get an OEM key, you must provide Cybele Software with a digital certificate’s thumbprint. On each licensing request, three parameters will be used to validate the requestor:

  • The OEM-licensed Company´s e-mail.
  • The provided OEM key.
  • The digital certificate’s fingerprint, taken from the digital certificate that signs the executable making the OEM library call.

The generated OEM key and the digital certificate’s thumbprint, along with your customer identification (e-mail), will be used to securely validate the licensing requests your application will make.

How to Create and Revoke Licenses?

The OEM library provides two functions to create a license and two functions to revoke a license:

  • CreateLicenseW (Unicode version) and CreateLicenseA (ANSI version).
  • RevokeLicenseW (Unicode version) and RevokeLicenseA (ANSI version).

In order to test the license creation and activation process, you can enable the SanboxMode in OEM.ini file.

[LICENSE]
SandboxMode = True

OEM.ini file should be placed in both bin32 and bin64 paths under Thinfinity VirtualUI installation folder.
 

Adding external methods

In a Delphi program we must first  declare the external functions in their ANSI or Unicode version.
ANSI:

function CreateLicenseA(const email, oemkey, customerid: PAnsiChar;
     units: DWORD; serial: PAnsiChar): integer; stdcall;
     external 'Thinfinity.VirtualUI.OEM.dll';
function RevokeLicenseA(const email, oemkey, serial: PAnsiChar): integer; stdcall;
     external 'Thinfinity.VirtualUI.OEM.dll';

Unicode:

function CreateLicenseW(const email, oemkey, customerid: PWideChar;
     units: DWORD; serial: PWideChar): integer; stdcall;
     external 'Thinfinity.VirtualUI.OEM.dll';
function RevokeLicenseW(const email, oemkey, serial: PWideChar): integer; stdcall;
     external 'Thinfinity.VirtualUI.OEM.dll';

In order to access to external library functions in C# program, please declare:

[DllImport("Thinfinity.VirtualUI.OEM.dll",
CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]
private static extern int CreateLicenseW(string email, string oemkey,
                          string customerid, int units, StringBuilder serial);
[DllImport("Thinfinity.VirtualUI.OEM.dll",
CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]
private static extern int RevokeLicenseW(string email, string oemkey, string serial);

 

Creating licenses

To create a new Thinfinity VirtualUI license you must use the corresponding CreateLicense method with the following parameters:

EmailinOEM-licensed Company´s e-mail
OEMKeyinOEM Key.
CustomerIDinArbitrary customer identification for the new license. This can be an e-mail address, a serial number any other customer identification.
UnitsinNumber of units to enable in this license. Each unit contains a predefined number of concurrent users. If your OEM license has 5 users per unit, and you assign 2 units to the product license, the customer will have 10 concurrent users in total.
SerialoutSerial number of the successfully generated license.

 

A calling to the CreateLicense function will return one of the following error codes:

0No error. The “Serial” parameter will contain the generated serial number.
-1General error in license server.
-2Incorrect Email or OEM Key.
-3No more units available.
-4OEM License expired.
-5General error. Cannot create license.
-10Invalid response received from license server.
-20Malformed response received from license server.
-100General error in library.
-101Application invalid: not digitally signed.
>200HTTP status code.

 

The following example shows how to create a license in Delphi. Please note that you must replace CreateLicenseW by CreateLicenseA when using ANSI chars.

procedure CreateLicense;
var
    result: Integer;
    serial: WideString;
begin
   serial := StringOfChar(' ', 128);
   result := CreateLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'),
                            PChar('CUSTOMER_ID'), UNIT_COUNT, PWideChar(serial));
   // Check result
end;

To create a license in C#:

private void CreateLicense()
{
   StringBuilder sn = new StringBuilder(128);
   int result = CreateLicenseW("OEM_EMAIL", "OEM_KEY",
                               "CUSTOMER_ID", UNIT_COUNT), sn);
   string serial = “”;
   // Check result
   if (result == 0)
   {
      serial = sn.ToString().Trim();
   }
   else
   {
      // Error
   }
}

Note: In all these examples, please replace ‘OEM_EMAIL’ and ‘OEM_KEY’ with your Company’s OEM registration, ‘CUSTOMER_ID’ with the Customer identification and UNIT_COUNT with the desired value.

 

Revoking licenses

The RevokeLicense function is used to revoke a previously generated license. There are its parameters:

EmailinOEM-licensed Company´s e-mail
OEMKeyinOEM License Key.
SerialinSerial number to revoke.

 

This function will return  one of the following error codes:

0No error. The license was revoked.
-1General error in license server.
-2Incorrect Email or OEMKey.
-3Incorrect Serial number.
-4Incorrect Serial number.
-5General error. Cannot revoke license.
-10Invalid response received from license server.
-20Malformed response received from license server.
-50Error in HTTP request.
-100General error in library.
-101Application invalid: not digitally signed.
>200HTTP status code.

To revoke a license in Delphi:

procedure RevokeLicense;
   var result: Integer;
begin
   result := RevokeLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'), PChar('SERIAL_NUMBER');
   // Check result
end;

And to revoke a license in C#:

private void RevokeLicense() {
   int result = RevokeLicenseW("OEM_EMAIL", "OEM_KEY", "SERIAL_NUMBER");
   // Check result
}

Note: Please replace ‘OEM_EMAIL’ and ‘OEM_KEY’ with your Company’s OEM registration and replace SERIAL_NUMBER’ with the Serial to revoke.
Working with white labeled solutions?
Take a look to this other article to read more about VirtualUI White Labeling customization in details.

Have any questions?

Book a call today to learn more about how Thinfinity® can help your organization. We are always available to guide you and provide the best solution based on your specific needs.

Add Comment

Thinfinity_logo

Get a Demo

Experience how Universal ZTNA with Thinfinity® integrates with VDI and DaaS for unmatched security and flexibility.

Blogs you might be interested in

<span>Application Modernization</span>, <span>Developer</span>, <span>Independent software Vendor (ISV)</span>, <span>IT Admin</span>, <span>License Management</span>, <span>OEM Licensing API</span>, <span>SDK</span>, <span>Secure Application Delivery</span>, <span>Thinfinity VirtualUI</span>