SoftActivate Licensing SDK Documentation

SoftActivate Licensing SDK Documentation

Contents

About SoftActivate Licensing SDK

SoftActivate Licensing SDK uses the latest advances in elliptic curve cryptography to provide you with one of the most secure and flexible license key generation and license management software solutions on the market. It supports short, easy to read license key generation, license key validation and software activation. It has native C, C++ and .NET interfaces. It has a fully managed implementation written in C# in addtition to the C/C++ native implementation. For more information on features, please see our website product page.

Using SoftActivate Licensing SDK

Using the Samples

Many sample applications written in various languages (C++/C/C#/VB.NET) are provided with SoftActivate Licensing SDK in order to help you use the technology correctly and efficiently.

  • Key generators and validators in C, C++, and C#
  • Activation samples in C++ and C#
  • Hardware Id generation samples

The samples are found in the samples\C, samples\C++, Samples\C# and samples\VB.NET folders

Installing and Using the Licensing Server

Please note: you do not need to install the licensing server in order to use the source code samples. They already use a demo licensing server installed on SoftActivate web site.

SoftActivate Licensing Server is a composed of two web applications:

  • a web service which processes software activation requests sent by the products at activation time. It also processes requests from payment processors, generates and sends emails with license keys.
  • a web management console for managing products, orders, license keys, etc.

    • It has two versions. The Node.js version, written in Javascript, and the .NET version, written in C#/ASP.NET Core. Both versions can be installed on either shared hosting accounts or full servers running NodeJS or Microsoft IIS respectively. Both servers use SQLite3 (for development purposes) and MySQL or SQL Server for production.

    Installing the .NET SoftActivate Licensing Server on Windows with IIS

    • Make sure IIS is installed on your machine (more here)
    • Install .NET Core hosting bundle for IIS from Microsoft
    • Restart IIS
    • Using IIS Manager, create two application pools, one named LicensingService with binding to port 3001, and one named LicensingControlPanel with binding to port 3000
    • Using IIS Manager, create two web sites: LicensingService pointing to ./bin/server/dotnet/LicensingService SDK folder and using the LicensingService app pool, and LicensingControlPanel pointing to ./bin/server/dotnet/LicensingControlPanel SDK folder and using the LicensingControlPanel app pool
    You can now access the license management console by pointing your browser to http://localhost:3000 (default user: admin, default password: SoftActivate) You can also test the licensing service which has the URL http://localhost:3001 but it will not work with a browser since it is a web service. Just open the Licensing Tool, go to Define Licenses vertical tab, Activation horizontal tab and replace the activation server with "http://localhost:3001". You can then go to the "Activate Keys" tab and activate a sample license key (press the Generate Sample license key button). The server will return an activation key which is displayed on screen.

    In the server's appsettings.json files from the LicensingService and LicensingControlPanel folders, you will have to enter your purchased SDK license key (or leave the included demo key). Otherwise the server will run in demo mode.

    Installing the NodeJS version of the SoftActivate Licensing Server

    SoftActivate Licensing SDK includes a NodeJS licensing server. The NodeJS licensing server is written in Javascript and uses Sqlite3 (for development), MySQL or SQL Server (for production purposes).
    Server installation steps on Linux (our example assumes a fresh instance of Amazon Linux - a popular choice for Amazon EC2 Linux virtual machines):

    • Install NodeJS on the test machine using the installer specific to your Linux distribution (or Windows installation). This may include commands like "yum install nodejs" or "rpm install nodejs" or downloading and running the Windows MSI installer from NodeJS website. npm (Node Package Manager) will usually also be installed along with NodeJS. If not, also install npm. On Windows, make sure Node.exe and npm are in the PATH so you can easily run them from any folder.
    • Go to the ./bin/server/nodejs/lms subfolder of the SDK and run "npm install". This will install required dependency packages.
    • Go to the ./bin/server/nodejs/lms-console/backend subfolder of the server and run "npm install". This will install required dependency packages.
    • Go to the ./bin/server/lms-console/frontend subfolder and run "bower install". This will install required dependency packages.
    • To run the LMS server, go to the lms folder of the server, and type "node index.js". This will start the server which (by default) will be listening on port 3001. If successful, the message "Licensing server started" should appear in the console.
    • To run the LMS console, go to the lms-console folder of the server, and type "node index.js". This will start the web managemenet console which will be listening on port 3000.
    • In order to access the LMS console, open a web browser and go to "http://localhost:3000". The console should appear asking you to login. The default username and password are "admin" and "SoftActivate".

    The samples "ActivationCS", "ActivationCPP", "EasyLicensingCS", "WinFormsAppCS" and "WinFormsAppVB" from the Licensing SDK connect to the server and perform sample product activations and show how to use the trial versions feature. For more information about how the activation is performed, please see the section "Understanding and Using Product Activation" in this document.

    Compiling and Linking

    Choosing the Correct Libraries

    The following libraries are provided in precompiled form by the SoftActivate Licensing SDK for each of the x86-windows, x64-windows, x64-linux and .NET platforms. Please note, you can additionally compile the SDK on a variety of platforms including Linux, MacOS with Intel, Apple and ARM-based hardware

    • Dynamic library (.dll\.so) (bin\client\x86-windows|x64-windows|x64-linux\licensing.dll|liblicensing.so)
      This is a dynamically linked library containing support for product key generation/validation and activation. It should only be used in-house for license key generation/validation and server-side software activation. A corresponding import library is supplied, named lib\win32|x64\Release\licensing.lib.
    • Static library using the C runtime as static library (lib\x86-windows-mt|x64-windows-mt\licensing.lib)
      This is the recommended way to embed the Licensing SDK into your application, because it will be directly embedded into your main binary (or you could embed the relevant source code directly). License key software binary code should never be put in a separate module, like a DLL, for entry point security purposes. This library is intended to use when you are linking your application with the static version of CRT libraries ( the /MT compiler option ).
    • Static library using the C runtime as shared DLL (lib\x86-windows|x64-windows\licensing.lib
      This is the recommended way to embed the Licensing SDK into your application, because it will be directly embedded into your main binary (or you could embed the relevant source code directly). Licensing code should never be put in a separate binary, like a DLL, for entry point security purposes. This library is intended to use when you are linking your application with the dynamic version of CRT libraries ( the /MD compiler option ).
    • .NET library (bin\client\dotnet\Licensing.Net.dll)
      This library contains the pure .NET code for the library. It supports key generation, validation and software activation. However, this is not a recommended and secure way to include the Licensing SDK in your .NET application. The most secure way is to embed the source code of the SDK directly into the source tree for your main executable. The .NET SDK source code is lightweight enough to not add significant bulk or complexity to your application.

    Static Linking

    Static Linking refers to using the static Licensing SDK libraries in your application. In Visual Studio, you can accomplish this by editing your project properties and adding the library to Linker->Input->Additional Dependencies. Also, you have to define the preprocessor symbol LICENSING_STATIC. To do this, edit your application properties by going to C/C++->Preprocessor->Preprocessor Definitions and add the LICENSING_STATIC symbol. Static linking is the preferred way to use SoftActivate Licensing SDK libraries in your applications. Another secure way is to embed the SDK source code directly into your application.

    Dynamic Linking

    Dynamic linking refers to using the DLL versions of the Licensing SDK libraries. It is the easiest and the most compatible way to use the SDK libraries. You just have to link with the corresponding import library. In Visual Studio, you can accomplish this by editing your project properties and adding the import library to Linker->Input->Additional Dependencies.

    Initializing and registering the SDK

    Initializing and Registering the SDK

    There is no initialization required (and neither is it recommended) for the SDK if it will be used for license key validation, or client-side software activation. Thus, in your end-user application there is no initialization required. If the SDK will be used for license key generation or public/private key pair generation (for example in your key generator application),the first required step is initializing the SDK by entering the purchased SDK license key. This is done via SDKRegistration::SetLicenseKey(). If this license key is not entered, the SDK will function in demo mode. This means that only certain, pre-defined private/public keys for license key generation are generated/accepted for use by the SDK. Since the predefined private keys are known by anyone and can be generated by anyone, these cannot be securely used to sign the generated license keys. Initializing the SDK by calling SDKRegistration::SetLicenseKey() and setting your purchased developer license key into your end-user application is NOT recommended.

    Adding licensing and activation to your software with only one line of source code (BETA)

    Adding licensing and activation to your software with only one line of source code (BETA)

    Starting with version 3.1, SoftActivate Licensing SDK includes a new .NET component called UILicenseManager and located in LicensingUI.Net.dll assembly. This component provides all the registration logic, including a customizable HTML-based user interface. This component has only one method: UILicenseManager.Run(). For more information, please see the EasyLicensingCS sample in the SDK's Samples\CS subfolder.

    Creating License Key Templates

    SoftActivate license keys are very flexible in their format, security and contents. You can choose your own format for your application, based on your needs. A license key template is a collection of properties used to define a license key's format, security and contents.

    Currently, the following properties are available in a license key template:

    • License Key Format
      • Number of character groups.This is the number of groups of characters a license key has. The key 3XTZWJ-V5N4JB-MXDBAA-K9CYK7-2XUWSU has 5 character groups.
      • Number of characters per group.This is the number of characters contained by each character group. The key 3XTZWJ-V5N4JB-MXDBAA-K9CYK7-2XUWSU has 6 characters per group.
      • Group separator.This is a string of characters used to separate character groups. The key 3XTZWJ-V5N4JB-MXDBAA-K9CYK7-2XUWSU has uses "-" as string separator. The new line character can also be used, causing key groups to be split one on each line. This is useful for very long license keys.
      • Character encoding.This specifies what encoding is used to convert the license keys from their binary format into an easy to handle text format. Currently two encodings are available: BASE32X and BASE64X. The BASE32X encoding is a variation of the BASE32 with some modifications in order to ensure that license key's characters are not confused. The BASE64X format is a variation of BASE64, and it's typically used in very long license keys, like this:

        --BEGIN LICENSE--
        XUWCNDfqhlzPxhAnr
        sdvPOCf77FgGfP4ip
        BwnruQKOQjJdIftPQ
        0topIPEJcWtPLhbVE
        fF8Wy/V7W69qAocpU
        --END LICENSE--
      • License Key Header. This is a line of text preceding the actual license key. See "--BEGIN LICENSE--" from the above example. It is typically used on very long license keys.
      • License Key Header. This is a line of text ending the actual license key. See "--END LICENSE--" from the above example. It is typically used on very long license keys.
    • License Key Security
      • Signature size. This parameter chooses the license key signature size in bits, and thus is has an impact on key security. The allowed sizes are currently between 76 and 322. The bigger the signature size, the stronger the key security. But also the bigger the signature size, the longer the license key must be. So you must make a compromise here (see below).
    • License Key Data Contents
      • Embedded Data A license key can contain various informations. The information is divided into fields. Each field can contain one of three types of data: integer, string or raw. It is up to the developer's choice what data fields does a key contain. The key contents are digitally signed, so they cannot be altered. The embedded data size is limited by the license key size.
      • Validation Data In addition to the data embedded in the license key, supplemental information can be used to validate a license key. This information is not embedded in the key. For example, you may want to use a registration name or a hardware id to validate a license key against. The registration name is regarded as validation data. The validation data is not embedded in the key, so it can be any information, of any size or type.

    Choosing the Right Template for Your Application

    Since not any combination of license key length, license key security and license key contents can be used (due to size constrains), you must make a compromise between license key ease of use, security and the contained information. The BASE32X format stores 5 bits for each license key character (excluding separators), so the license key 3XTZWJ-V5N4JB-MXDBAA-K9CYK7-2XUWSU can store 150 bits. From these, a part is taken up by the digital signature, and the remaining part can be used to store various information. For example, if you choose a 130-bit signature (which is quite secure), you have 20 bits left to store data.

    Generating License Keys Linked to Registration Names

    Often, in order to limit illegal license key distribution developers opt to require the registration name used when purchasing in order to validate the license key. Thus, if someone distributes a license key, he must also distribute the registration name together with the key (otherwise the key would be useless since it could not be validated by others). This creates an additional barrier for potential software pirates, because no one wants his name associated with violating the law. A good license key software must provide for this sceanario. With SoftActivate Licensing SDK, linking lincese keys to registration names can be done by adding a validation field of type string to the license key template. Linking license keys to registration names has some drawbacks, however. You cannot generate license keys to be used for retail boxes or printing on CD's, for example, because you don't know in advance the name of the customer who buys a particular box. Thus, this approach is mostly used for online distribution.

    Generating License Keys Linked to Specific Hardware

    Sometimes, in order to drastically limit illegal license key distribution or using a license key on more than one computer, developers may want particular license keys to only validate on particular computers. Each key is generated for a specific computer, and it cannot be used on other computers. With SoftActivate Licensing SDK, linking license keys to particular computers can be done by adding a validation field of type string (or binary) to the license key template. The Licesing SDK includes a helper API to help you determine a unique hardware id for a computer in the form of a string. This id can then be used to generate a license key, and to validate it. Linking license keys to specific hardware id's requires knowing the hardware id at key generation time. So a customer must supply his hardware id, the software vendor must generate the license key and send it back to the customer. In order for the customer to supply his hardware id, the software vendor must make available a tool by which the customer can find his computer's hardware id. This tool can use SoftActivate Licensing SDK helper API for hardware id management. Linking license keys to specific hardware has some drawbacks, since the customer must take additional steps to purchase a product. Also, keys of this type cannot be distributed in large quantities, like in retail boxes or CD prints.

    Using XML License Key Templates

    SoftActivate Licensing SDK provides a convenient way to store license key validation/generation information in XML templates.

    Generating License Keys

    The following steps must be taken in order to generate license keys:

    • Create a license key template object.
    • Initialize the license key template object either from an XML template or programatically. Specify the license key format, security, content fields and optionally validation fields.
    • Create a license key generator object.
    • Specify the template to the license key generator object.
    • Set license key content data.
    • Optionally, set license key validation data (for example, if you need to link the license key to a registration name).
    • Generate the license key

    Validating License Keys

    The following steps must be taken in order to validate license keys:

    • Create a license key template object.
    • Initialize the license key template object either from an XML template or programatically. Specify the license key format, security, content fields and optionally validation fields.
    • Create a license key validator object.
    • Specify the template to the license key validator object.
    • Set the license key to the validator object
    • Optionally, set license key validation data (for example, if the key was linked to a registration name or email).
    • Validate the license key (by calling KeyValidator::IsKeyValid() )
    • If the key is valid, retrieve the data from the license key and also validate this data (for example, check if the product id from the key matches your product)

    Obtaining Stored Data from License Keys

    Embedded key data can be read using LicenseKeyValidator::QueryKeyData method

    Understanding and Using Software Activation

    Software activation is a way to make sure that a software product can only be used on a specific computer. It involves an activation server to which your software connects (once) in order to activate the product.

    The activation server receives the product key (issued when the user purchased the product) and a hardware id (a special string generated by the Licensing SDK which is unique to each computer) and returns an activation key. The activation key si a signed piece of information, similar to a license key except for the fact that it can only be validated in the presence of the hardware id string used to generate it. When checking if a product is activated, the LicensingClient class first makes sure that the activation key is valid and was signed by the activation server, and then compares the hardware id with the actual computer's hardware id. The activation key also contains an expiration date information, which is also checked. If all three conditions are met (signature verification, hardware id match, current date earlier than the expiration date) then the product is considered activated. Please note that the activation verification does not involve connecting to the activation server because it is not necessary. Since the public verification key is embedded into the product, the activation key signature can be validated using the stored public key. Activation by phone is also possible: the customer transmits the license key and hardware id to the phone operator, and the phone operator generates the activation key and transmits it to the customer. The customer enters this activation key into the product, and the product is activated. The license key, hardware id and activation key are all easy to read strings that can easily be transmitted in a phone conversation.

    In summary, there are three pieces of information that make up the activation data: license key, hardware id and activation key. The LicensingClient class is used to verify the software activation status and perform activation if necessary.

    Understanding and Using Hardware Id (Hardware Fingerprint) Strings

    Sometimes the need arises to generate strings that uniquely identify the hardware configuration of a computer. One such example is software activation. SoftActivate Licensing SDK makes it possible to generate such strings, called hardware id strings.

    SoftActivate Licensing SDK generates hardware id strings taking into consideration the following computer parameters: MAC addresses, fixed disk serial numbers, processor type and the amount of RAM memory. All this information is combined into an easy to use/type/dictate string, of the form XXXXX-XXXXX-XXXXX-XXXXX-XXXXX (5 character groups of 5 characters each). This string can then be matched to a computer in order to find out if the computer is the same computer for which the hardware id string was previously generated. The KeyHelper class contains methods for both hardware id generation and verification (matching).

    Implementing Trial Versions in Your Software Application

    A common scenario in commercial software development is the one in which a trial version of an application must be provided to customers so that they can try the application first before purchasing it. You may want your potential customers to be able to try the product at no charge for a certain number of days.

    SoftActivate Licensing SDK achieves this by using online software activation. This is a very secure process which does not involve hiding the product expiration date on a computer. Basically, your product includes a "trial license key" which is specially marked as such on the licensing service database. After installing a product on a certain computer, when a user presses the "Start Trial" button, the licensing server receives the trial license key and hardware id of the computer, and it will issue a digitally signed activation key containing the absolute (not relative) expiration date of the trial version. This activation key is also linked to the hardware id of that computer. At each startup, the product verifies the license key, activation key and hardware id using the LicensingClient class. After the activation key is deemed valid, the product can query the trial expiration date of the product. If the expiration date is less than the current date, the product is allowed to run. If not, a message can be displayed to the user informing that the trial period has expired and he needs to enter a purchased license key, etc.

    With SoftActivate Licensing SDK, you can achieve goal via the following steps:

    • Designate a certain license key as a "trial license key". Usually, this license key is a regular license key, it does not need to contain certain bits of data to mark it as trial.
    • Using SQL Server Management Studio or other similar tool, enter this license key into the LicenseKeys table of the licensing service, and set the database columns for this key as follows:
      • Set MaxUniqueHardwareIds to 0. This means that any number of computers can activate this key (this trial key will be used by all your potential customers).
      • Set MaxActivationsPerHardwareId to 1. This means that each computer can activate this license key only once.
      • Set MaxActivations to 0. This means that there is no limit of overall activation count for this license key
      • Set LicenseDuration to the number of trial days that you desire (example: use "30" for one-month trial).
      • Set LicenseHistoryDuration to a number of days after which you want to allow a computer to trial your product again after the initial trial period expires. Example: you may want that after 12 months (365 days) a computer to be allowed again to trial your product for one month. If you set this column to 0 or NULL, a computer is never allowed again to trial your product after the trial period expires. This is not recommended.

    Detecting Clock Manipulation Attempts

    SoftActivate Licensing SDK provides specific methods for detecting clock manipulation attempts. The SDK scans the system for evidence that the system clock was deliberately turned back in order to avoid license expiration.

    The specific method to call is KeyHelper::DetectClockManipulation(). This method is usually called after the IsLicenseValid() method returns true (whether in "trial" or "full" licenses) in order to ensure that the clock was not deliberately changed in order to extend the license validity interval.

    For more information, please see the sample code included in the ActivationCPP, ActivationCS, WinFormsAppCS and WinFormsAppVB samples

    Integrating SoftActivate Licensing Server with Payment Services

    SoftActivate Licensing Server now fully supports integration with the most popular payment services: PayPal, RegNow, ShareIt. What does this mean ? It means that the server can be used to automatically generate license keys for the products sold via these payment services. Each payment service has a method to call a specified URL (sometimes called "CGI") to generate license keys for a particular product. Since PayPal does not support sending emails with license keys to customers, SoftActivate Licensing Server can send customizable emails to customers, containing automatically generated license keys. The LicensingService.mdf database contains some new tables:

    • The Products table contains information about your products. You can edit this table and add one row for each product sold. Each row contains the following columns:
      • Id. This column specifies the product id. This id can optionally be embedded in the generated license keys
      • PayPalId. This column specifies the item number from the PayPal "Buy Now" button used to sell this product. When you create a PayPal "Buy Now" button to sell a product, PayPal asks for an optional "item number". The item number you enter when creating the button must also be inserted in this column.
      • RegNowId. This column specifies the RegNow product identifier for your product (eg. "12168-5"). You can get this identifier from the RegNow control panel.
      • ShareItId. This column specifies the ShareIt product identifier for your product (eg. "300001285"). You can get this identifier from the ShareIt control panel.
      • ProductName. This column specifies the name of your product
      • LicenseExpirationDays. If you want your license keys to include an expiration date, set this integer to the number of days after which the license keys will expire. Setting it to 365 means 1 year. The generated license keys will contain an expiration date obtained by adding this number of days to the current date. Note that in order to use this feature you must also insert an appropriate license key template in the LicenseKeyTemplate column: the license key template must contain a data field named "ExpirationDate" with a size of at least 14 bits.
      • LicenseKeyTemplate. This field specifies the XML license key template used for generating license keys. The XML template must be on one line of text, so remove all the newlines from the XML before inserting it into the database. This template's fields specify what is included in the generated license keys.
        • If a ProductId integer data field is present, then the Id column value is embedded in the generated license keys.
        • If an "ExpirationDate" named integer data field at least 14 bits long is present, then an expiration date (between 01/01/2010 and 12/31/2041) is included in the license key. This expiration date is calculated by adding the value from the LicenseExpirationDays column to the current date. For information about how the expiration date is packed into the 14-bit value and how it can be unpacked, please see samples KeyGenCS (C#) or KeyGenCPP (C++).
        • If a "RegistrationName" validation field is present, then the customer name (first name + " " + last name) is used as validation data for key generation, and therefore must be provided at validation time for successful license key validation (for more information please see the documentation for license key validation fields).
        • If a "RegistrationEmail" validation field is present, then the customer email (trimmed and lowercased) is used as validation data for key generation, and therefore must be provided at validation time for successful license key validation.
      • SupportEmail. In PayPal integration, all the email messages sent to customers appear to come from this email address.
    • The Purchases table contains logged information about each product sale. Logged information includes product id, license key, license expiration date, customer name, customer email, customer country, payment amount and payment currency. This table can be used to create sales statistics, to run email marketing campaigns for existing customers, etc.

    • The LicenseKeys table contains information about how certain license keys are behaving when they are used for activation.

      The following columns are included in this table:

      • Id. Self-incrementing counter for referencing this column.
      • ProductId. The product id for which this license key is generated. When a license key is sent from an application to the licensing server, the corresponding product information is looked up using this column.
      • LicenseKey. The license key
      • MaxUniqueHardwareIds. This specifies the maximum number of distinct computers which can use this license key for activation purposes. Usually best set to NULL for commercial, non-trial license keys (and let the MaxActivations column enforce this limit) and 0 for trial keys, since a trial key is used by many computers. Setting it to 0 means unlimted computers, setting it to NULL causes the DefaultMaxUniqueHardwareIdsPerLicenseKey column for the corresponding product from the Products table to be govern this limit.
      • MaxActivationsPerHardwareId. This specifies the maximum number of activations allowed for the same computer. Usually best set to NULL for non-trial license keys (and let the MaxActivations column enforce the limit), and "1" for trial keys. Setting it to 0 means unlimited activations for the same computer, setting it to NULL causes the DefaultMaxUniqueHardwareIdsPerHardwareId for the corresponding product from the Products table to govern this limit.
      • MaxActivations. This specifies the maximum total number of activations for a license key, regardless of which computer. Best set to 5-10 for commercial, non-trial license keys (in order to allow for a small number of product and OS reinstallations), and "0" for trial license keys. Setting it to 0 means unlimited number of activations, setting to NULL causes the DefaultMaxActivationsPerLicenseKey column for the corresponding product from the Products table to govern this limit.
      • LicenseDuration. This specifies the number of days after which an activation key issued for this license key, expires. For trial keys, set it to the number of trial days (eg. "30"). For commercial keys, set it to how long should this license be valid (eg. "365"). Setting it to 0 means the license will never expire. Setting it to NULL means the DefaultLicenseDuration column for the corresponding product from the Products table to govern this limit.
      • LicenseHistoryDuration. This specifies the number of days after which an expired license is not taken into account anymore when limits are calculated (even if a record if this license is still kept in the Activations table). For example, if for a trial license key we set this column to "180" (days) it means that even if that license key was activated once for a certain computer, it will still be allowed a new activation after 180 days (even if the MaxActivationsPerHardwareId was set to "1").
    • The LicenseKeysPool table. In case you don't want the license keys to be automatically generated by the licensing server for each sale, you can insert a list of license keys here and for each sale a license key is removed from this table and returned to the payment service (or in the PayPal case, emailed to the customer). This table can be of use if license key generation is very strictly controlled within a company and keys are generated on a secure server not connected to the Internet. If the LicenseKeyTemplate column does not contain a license key template (value is NULL), the server tries to get the license keys from this table.

    PayPal Integration

    The SoftActivate Licensing Server uses PayPal IPN (Instant Payment Notification) API to both generate license keys for products sold via PayPal, and also send these license keys to customers via customizable email templates. In order to have the SoftActivate Licensing Server automatically generate license keys for your PayPal product:

    • Insert a new product into the licensing server database using the licensing server's web control panel, with a chosen product id, product name, license key template, email template, etc.
    • Create a "Buy Now" button in your PayPal account, setting the item number to the same product id inserted in the Products table;
    • Set the "notify_url" custom variable of the Buy Now button to the following URL: <licensing server url>\PayPal.ashx (example: http://www.mycompany.com/licensingservice/PayPal.ashx )
    • Replace the sample SMTP settings with valid settings in the appsettings.json (for .NET) or config.json (for NodeJS) file of the licensing server (set server, port, username, password, ssl yes/no)
    • Test the system by setting the product price of the Buy Now button to 0.01 USD (also set the same price of 0.01 in the PaymentAmount of the Products table, don't forget to set the PaymentCurrency column to 'USD') and then place the button on a test web page and effectively press the button and complete a transaction. You should receive an email with a license key.
    • Look for any exceptions in the licensing server's control panel, in the 'Event Log' section

    RegNow Integration

    In order to have the SoftActivate Licensing Server automatically generate license keys for your RegNow products, simply edit the product properties in the RegNow control panel and select the remote CGI license generator option, setting the license key generator URL to: <licensing server url>\RegNow.ashx (example: http://www.mycompany.com/licensingservice/RegNow.ashx ). You must also insert a corresponding product into the licensing server database using the licensing server's web control panel. You can then complete a test order and check if everything works. Look for any exeptions in the licensing server's control panel, in the 'Event Log' section.

    ShareIt Integration

    In order to have the SoftActivate Licensing Server automatically generate license keys for your ShareIt products, simply edit the product properties in the ShareIt control panel and select the remote CGI license generator option, setting the license key generator URL to: <licensing server url>\ShareIt.ashx (example: http://www.mycompany.com/licensingservice/ShareIt.ashx ). You must also insert a corresponding product into the licensing server database using the licensing server's web control panel. You can then complete a test order and check if everything works. Look for any exeptions in the licensing server's control panel, in the 'Event Log' section.

    Preventing unauthorized parties from generating license keys via the payment services handlers

    Access to the pages RegNow.ashx and ShareIt.ashx should be restricted in web.config file to only certain IP addresses (see ASP.NET documentation for how to achieve this). Only the authorized IP addresses of the RegNow and ShareIt servers should be allowed to access these pages. These payment services publish their IP addresses in their respective documentation. PayPal already supports a reliable authentication mechanism so accessing the PayPal.ashx page by unauthorized parties is not possible. We will develop this section more in the near future.

    Security Guidelines

    Using SoftActivate Licensing SDK does not guarantee a complete stop of software piracy or complete license enforcement if some basic security guidelines are not followed. Make sure you follow these guidelines in order to make you application as secure as possible:

    • Keep the signing private keys secret. By knowing the private keys used to generate product keys, an unauthorized party can generate keys for your products. It is important to keep your private keys secret, and only distribute you public keys with your application for license key validation purposes.
    • Make sure your executable code cannot be altered. By altering your executable code, a malicious user can completely bypass your licensing mechanism. This is a rule to be followed for any licensing solution you would use. There are some professionally available tools that can help in this regard by making it very difficult for unauthorized users to alter the code, but the security is not 100% guaranteed. However, with the arrival of the new hardware-based trusted computing platforms in the near future, preventing executable code altering should become an achievable goal.
    • For native code (win32 and x64): Prefer statically linking with the SDK libraries. You should NOT keep your license management software into a separate binary module which can be targeted by malicious parties. Or, if you prefer dynamic linking, make sure you are calling a legitimate dll. The most secure ways to integrate the SDK into your application is via static linking or direct source code embedding.
    • For .NET code: We strongly recommend merging the Licensing.Net.Dll assembly into your main executable and obfuscating your resulting assembly.

      Merging can be accomplished using Microsoft ILMerge tool, which is a free tool available here:
      http://www.microsoft.com/en-us/download/details.aspx?id=17630.

      For .NET assembly obfuscation, we recommend the free Eazfuscator.NET tool, available for download here:
      http://www.foss.kharkov.ua/g1/projects/eazfuscator/dotnet/Default.aspx.

    • Perform license checking in different parts of the code, at diffrent program execution times. Ideally, you should not keep your license management software code into a separate binary module which can be targeted by hackers. Or, if you prefer dynamic linking, make sure you are calling a legitimate dll. You could, as a simple example, verify a signature of the licensing library dll before attempting library calls. Of course this rule is to be followed with any licensing solution.

    Uninstalling SoftActivate Licensing SDK

    To uninstall the SDK, please go to Control Panel -> Add/Remove Programs, right-click on the "SoftActivate Licensing SDK" software and choose "Uninstall"

    Programming Reference

    SDKRegistration Class

    SDKRegistration::SetLicenseKey

    Initalizes the SDK by entering the purchased SDK license key. This method must NOT be called if the SDK will only be used for license key validation or client-side software activation, as for example in your end-user application. This should be the first method called before using the SDK for license key generation or public/private key pair generation, as for example in your key generator application. If this method is not called when the SDK will be used for license key generation or public/private key pair generation, the SDK will function in DEMO mode, which means that only certain private/public keys are generated and accepted by the SDK for generating license keys. Since the predefined demo private keys can be generated by anyone, these are not secure to use in generating license keys.

    Prototype

    SDKRegistration::SetLicenseKey(const char_t * licenseLey);(C++)

    SDKRegistration.SetLicenseKey(string licenseKey)(C#)

    Parameters

    • licenseKey
      [in] The purchased license key

    KeyGenerator Class

    KeyGenerator::KeyGenerator

    Initializes a KeyGenerator object.

    Prototype

    KeyGenerator::KeyGenerator();

    Parameters

    None.

    Return Values

    None.

    KeyGenerator::~KeyGenerator

    Destroys a KeyGenerator object, freeing all associated resources.

    Prototype

    KeyGenerator::~KeyGenerator();

    Parameters

    None.

    Return Values

    None.

    KeyGenerator::SetKeyTemplate

    Sets the template used to generate license keys.

    Prototype

    void KeyGenerator::SetKeyTemplate(LicenseTemplate & keyTemplate);

    Parameters

    • keyTemplate
      [in] The template used to generate license keys.

    Return Values

    None.

    Remarks

    None.

    KeyGenerator::SetKeyData

    Sets the contents of a data field.

    Prototype

    void KeyGenerator::SetKeyData(const char_t * fieldName, const void * rawData, unsigned len);
    void KeyGenerator::SetKeyData(const char_t * fieldName, unsigned intData);
    void KeyGenerator::SetKeyData(const char_t * fieldName, const char_t * stringData);

    Parameters

    • fieldName
      [in] The name of the field for which to set the data.
    • rawData
      [in] Pointer to a buffer containing the field data.
    • len
      [in] Length of the rawData buffer.
    • intData
      [in] An int value to set for the field.
    • stringData
      [in] A string value to set for the field.

    Return Values

    None.

    Remarks

    If the field size (as specified in the template) is smaller than the data size, the data is truncated to fit the field.

    KeyGenerator::SetValidationData

    Sets the contents of a validation field.

    Prototype

    void KeyGenerator::SetValidationData(const char_t * fieldName, const void * rawData, unsigned len);
    void KeyGenerator::SetValidationData(const char_t * fieldName, unsigned intData);
    void KeyGenerator::SetValidationData(const char_t * fieldName, const char_t * stringData);

    Parameters

    • fieldName
      [in] The name of the field for which to set the data.
    • rawData
      [in] Pointer to a buffer containing the field data.
    • len
      [in] Length of the rawData buffer.
    • intData
      [in] An int value to set for the field.
    • stringData
      [in] A string value to set for the field.

    Return Values

    None.

    Remarks

    If the field size (as specified in the template) is smaller than the data size, the data is truncated to fit the field.

    KeyGenerator::GenerateKey

    Generates a license key.

    Prototype

    const char_t * LicenseTemplate::GenerateKey();

    Parameters

    None.

    Return Values

    Pointer to a NULL-terminated string containing the license key. This string is statically allocated, do not attempt to free it.

    KeyValidator Class

    KeyValidator::KeyValidator

    Initializes a KeyValidator object.

    Prototype

    KeyValidator::KeyValidator();

    Parameters

    None.

    Return Values

    None.

    KeyValidator::~KeyValidator

    Destroys a KeyValidator object, freeing all associated resources.

    Prototype

    KeyValidator::~KeyValidator();

    Parameters

    None.

    Return Values

    None.

    KeyValidator::SetKeyTemplate

    Sets the template used to generate license keys.

    Prototype

    void KeyValidator::SetKeyTemplate(LicenseTemplate & keyTemplate);

    Parameters

    • keyTemplate
      [in] The template used to generate license keys.

    Return Values

    None.

    Remarks

    None.

    KeyValidator::SetValidationData

    Sets the contents of a validation field.

    Prototype

    void KeyValidator::SetValidationData(const char_t * fieldName, const void * rawData, unsigned len);
    void KeyValidator::SetValidationData(const char_t * fieldName, unsigned intData);
    void KeyValidator::SetValidationData(const char_t * fieldName, const char_t * stringData);

    Parameters

    • fieldName
      [in] The name of the field for which to set the data.
    • rawData
      [in] Pointer to a buffer containing the field data.
    • len
      [in] Length of the rawData buffer.
    • intData
      [in] An int value to set for the field.
    • stringData
      [in] A string value to set for the field.

    Return Values

    None.

    Remarks

    If the field size (as specified in the template) is smaller than the data size, the data is truncated to fit the field.

    KeyValidator::SetKey

    Sets the license key to validate and to query data from.

    Prototype

    void KeyValidator::SetKey(const char_t * licenseKey);

    Parameters

    • licenseKey
      [in] A NULL-terminated string containing the license key.

    Return Values

    None.

    Remarks

    None.

    KeyValidator::IsKeyValid

    Validates the license key set using KeyValidator::SetKey().

    Prototype

    bool KeyValidator::IsKeyValid();

    Parameters

    None.

    Return Values

    Returns true if the license key is valid, false if not.

    Remarks

    None.

    KeyValidator::QueryKeyData

    Obtains data from the license key.

    Prototype

    void KeyValidator::QueryKeyData(const char_t * fieldName, void * buf, unsigned * len);

    Parameters

    • fieldName
      [in] The name of the field to query the data from.
    • buf
      [out] Pointer to a buffer receiving the field data.
    • len
      [in, out] Pointer to an integer receiving the data size in bytes. At input, this must contain the buffer size in bytes.

    Return Values

    None.

    Remarks

    None.

    LicensingClient Class

    LicensingClient::LicensingClient

    Constructs a LicensingClient object.

    Prototype

    LicensingClient::LicensingClient();

    Parameters

    None.

    Return Values

    None.

    LicensingClient::SetActivationServiceUrl

    This method is used to set the url of the activation server.

    Prototype

    void LicensingClient::SetActivationServerUrl(const char * url);

    Parameters

    • url
      [in] The URL of the activation service

    Return Values

    None.

    Remarks

    None.

    LicensingClient::SetActivationKeyTemplate

    This method is used to set the template of the activation key. This MUST correspond to the server activation key template. In the template, only the number of character groups in the key, number of characters per group, public key, and signature size must be set, and these must be identical to the ones at the activation server.

    Prototype

    void LicensingClient::SetActivationKeyTemplate(LicenseTemplate * tmpl);

    Parameters

    • tmpl
      [in] Pointer to the key template used to define the activation key

    Return Values

    None.

    Remarks

    None.

    LicensingClient::SetActivationKey

    This method is used to set the activation key used in the activation verification process.

    Prototype

    void LicensingClient::SetActivationKey(const char * key);

    Parameters

    • key
      [in] The activation key that was returned by the activation server at activation time.

    Return Values

    None.

    Remarks

    None.

    LicensingClient::GetActivationKey

    This method is used to retrieve the activation key returned by the activation server at software activation.

    Prototype

    const char * LicensingClient::GetActivationKey();

    Parameters

    • key
      [in] The license key.

    Return Values

    None.

    Remarks

    None.

    LicensingClient::SetLicenseKey

    This method is used to set the product key (license key) of the product. The activation server needs the key in order to generate an activation key. The product key is also used when validating the activation key.

    Prototype

    void LicensingClient::SetLicenseKey(const char * key);

    Parameters

    • key
      [in] The license key.

    Return Values

    None.

    Remarks

    None.

    LicensingClient::SetHardwareId

    This method is used to set the hardware id string previously saved after the product's activation process. This string is used during activation validation.

    Prototype

    void LicensingClient::SetHardwareId(const char * hwid);

    Parameters

    • key
      [in] The activation key that was returned by the activation server at activation time.

    Return Values

    None.

    Remarks

    None.

    LicensingClient::GetHardwareId

    This method is used to retrieve the hardware id generated by the SDK in order to complete the activation process.

    Prototype

    const char * LicensingClient::GetHardwareId();

    Parameters

    • hwid
      [in] The hardware id string.

    Return Values

    None.

    Remarks

    None.

    LicensingClient::AcquireLicense

    This method sends the product key and hardware id to the activation server, and receives the signed activation key.

    Prototype

    void LicensingClient::AcquireLicense();

    Parameters

    None.

    Return Values

    None.

    Remarks

    None.

    LicensingClient::IsLicenseValid

    This method checks if the activation key signature and then checks if the hardware id matches this computer.

    Prototype

    void LicensingClient::IsLicenseValid();

    Parameters

    None.

    Return Values

    true if the activation key is valid, the hardware id matches this computer and the license is not expired. false otherwise.

    Remarks

    None.

    LicensingClient::GetLicenseActivationStatus

    This method retrieves the activation status after a call to IsLicenseValid().

    Prototype

    void LicensingClient::GetLicenseActivationStatus();

    Parameters

    None.

    Return Values

    An ActivationStatus value which can be: Success, InvalidHardwareId, InvalidActivationKey, LicenseExpired

    Remarks

    None.

    LicenseTemplate Class

    LicenseTemplate::LicenseTemplate

    Constructs a LicenseTemplate object.

    Prototype

    LicenseTemplate::LicenseTemplate();

    Parameters

    None.

    Return Values

    None.

    LicenseTemplate::~LicenseTemplate

    Destroys a LicenseTemplate object freeing all associated resources.

    Prototype

    LicenseTemplate::~LicenseTemplate();

    Parameters

    None.

    Return Values

    None.

    LicenseTemplate::SetNumberOfGroups

    This method is used to set the number of character groups a license key contains.

    Prototype

    void LicenseTemplate::SetNumberOfGroups(unsigned numGroups);

    Parameters

    • numGroups
      [in] The number of character groups in the license key.

    Return Values

    None.

    Remarks

    None.

    LicenseTemplate::GetNumberOfGroups

    Gets the number of character groups contained by a license key.

    Prototype

    unsigned LicenseTemplate::GetNumberOfGroups();

    Parameters

    None.

    Return Values

    The number of groups.

    Remarks

    None.

    LicenseTemplate::SetCharactersPerGroup

    Sets the number of characters in each license key character group.

    Prototype

    void LicenseTemplate::SetCharactersPerGroup(unsigned charsPerGroup);

    Parameters

    • charsPerGroup
      [in] The number of characters per group.

    Return Values

    None.

    Remarks

    None.

    LicenseTemplate::GetCharactersPerGroup

    Gets the number of characters in each license key character group.

    Prototype

    unsigned LicenseTemplate::GetCharactersPerGroup();

    Parameters

    None.

    Return Values

    The number of characters per group.

    Remarks

    None.

    LicenseTemplate::SetVersion

    Sets the license key template version.

    Prototype

    void LicenseTemplate::SetVersion(unsigned version);

    Parameters

    • version
      [in] The template version.

    Return Values

    None.

    Remarks

    The default version is 1. In this SDK version, specifying any other version than 1 will cause an exception to be thrown.

    LicenseTemplate::GetVersion

    Retrieves the license key template version.

    Prototype

    unsigned LicenseTemplate::GetVersion();

    Parameters

    None.

    Return Values

    The license key template version. Currently, a value of 1 is returned.

    Remarks

    None.

    LicenseTemplate::SetGroupSeparator

    Sets the string or character that separates license key character groups.

    Prototype

    void LicenseTemplate::SetGroupSeparator(const char_t * groupSeparator);

    Parameters

    • groupSeparator
      [in] The group separator string.

    Return Values

    None.

    Remarks

    The default group separator is the character '-'.

    LicenseTemplate::GetGroupSeparator

    Sets the string or character that separates license key character groups.

    Prototype

    const char_t * LicenseTemplate::GetGroupSeparator();

    Parameters

    None.

    Return Values

    Pointer to a string containing the license key group separator string.

    Remarks

    The returned string is statically allocated and must not be freed.

    LicenseTemplate::SetEncoding

    Sets the character encoding for the license key.

    Prototype

    void LicenseTemplate::SetEncoding(LICENSE_KEY_ENCODING encoding);

    Parameters

    • encoding
      [in] The character encoding. This can be on of ENCODING_BASE32X or ENCODING_BASE64X.

    Return Values

    None.

    Remarks

    None.

    LicenseTemplate::GetEncoding

    Gets the encoding used for the license keys.

    Prototype

    LICENSE_KEY_ENCODING LicenseTemplate::GetEncoding();

    Parameters

    None.

    Return Values

    The encoding used. This can be either ENCODING_BASE32X or ENCODING_BASE64X.

    Remarks

    None.

    LicenseTemplate::SetHeader

    Sets the contents of an optional line of text preceding the license key.

    Prototype

    void LicenseTemplate::SetHeader(const char_t * header);

    Parameters

    • header
      [in] The header string.

    Return Values

    None.

    Remarks

    None.

    LicenseTemplate::GetHeader

    Gets the encoding used for the license keys.

    Prototype

    const char_t * LicenseTemplate::GetHeader();

    Parameters

    None.

    Return Values

    The license key header.

    Remarks

    The returned string is statically allocated and must not be freed.

    LicenseTemplate::SetFooter

    Sets the contents of an optional line following the license key.

    Prototype

    void LicenseTemplate::SetFooter(const char_t * header);

    Parameters

    • header
      [in] The header string.

    Return Values

    None.

    Remarks

    None.

    LicenseTemplate::GetFooter

    Gets the encoding used for the license keys.

    Prototype

    const char_t * LicenseTemplate::GetFooter();

    Parameters

    None.

    Return Values

    The license key footer.

    Remarks

    The returned string is statically allocated and must not be freed.

    LicenseTemplate::SetDataSize

    Sets the size of data embedded in the license key.

    Prototype

    void LicenseTemplate::SetDataSize(unsigned dataSize);

    Parameters

    • dataSize
      [in] The size of data in bits.

    Return Values

    None.

    Remarks

    This method could throw an exception if the data size is too big for the chosen key format parameters and signature size.

    LicenseTemplate::GetDataSize

    Retrieves the size of data embedded in the license key.

    Prototype

    unsigned LicenseTemplate::GetDataSize();

    Parameters

    None.

    Return Values

    The size in bits of the embedded license key data.

    Remarks

    None.

    LicenseTemplate::AddDataField

    Adds a field of data which will be included in the license key.

    Prototype

    void LicenseTemplate::AddDataField(const char_t * fieldName, FIELD_TYPE fieldType, unsigned sizeInBits, unsigned startPos = -1);

    Parameters

    • fieldName
      [in] The name of the data field.
    • fieldType
      [in] The type of the data field. It can be one of FIELD_TYPE_INTEGER, FIELD_TYPE_STRING, FIELD_TYPE_RAW.
    • sizeInBits
      [in] The size of the data field in bits.
    • startPos
      [in] The starting position (relative to bit 0) of the field in the license key data. Omitting this value adds the field to the next available position.

    Return Values

    None.

    Remarks

    This method could throw an exception if the field size is too big for the chosen data size.

    LicenseTemplate::EnumDataFields

    Enumerates license key data fields.

    Prototype

    bool EnumDataFields(void **enumHandle, char_t * fieldName, unsigned * fieldNameSize, FIELD_TYPE * fieldType, unsigned * fieldSize, unsigned * startPos);

    Parameters

    • enumHandle
      [in, out] Pointer to a pointer used to store a handle to the enumeration state. A pointer to a NULL handle must be passed at the first call.
    • fieldName
      [in, out] Pointer to a buffer which will be filled with the field name.
    • fieldNameSize
      [in, out] Pointer to an unsigned which will receive the size of the field name string. At input this must contain the size of the buffer.
    • fieldType
      [out] Pointer who will receive the type of the field.
    • fieldSize
      [out] Pointer to an unsigned who will receive the field size in bits.
    • startPos
      [out] Pointer to an unsigned who will receive the field start position in license key data.

    Return Values

    If the enumeration is over, returns false and the output parameters are not filled. Otherwise returns true.

    Remarks

    None.

    LicenseTemplate::SetValidationDataSize

    Sets the size of the data used to validate the license key.

    Prototype

    void LicenseTemplate::SetValidationDataSize(unsigned sizeInBits);

    Parameters

    • sizeInBits
      [in] The size of validation data in bits.

    Return Values

    None.

    Remarks

    None.

    LicenseTemplate::GetValidationDataSize

    Retrieves the size of the data used to validate the license key.

    Prototype

    unsigned LicenseTemplate::GetValidationDataSize();

    Parameters

    None.

    Return Values

    The size in bits of the validation data.

    Remarks

    None.

    LicenseTemplate::AddValidationDataField

    Adds a field of data used for license key validation. Validation fields are not included in the license key, but they are used for validation.

    Prototype

    void LicenseTemplate::AddValidationDataField(const char_t * fieldName, FIELD_TYPE fieldType, unsigned sizeInBits, unsigned startPos = -1);

    Parameters

    • fieldName
      [in] The name of the data field.
    • fieldType
      [in] The type of the field. It can be one of FIELD_TYPE_INTEGER, FIELD_TYPE_STRING, FIELD_TYPE_RAW.
    • sizeInBits
      [in] The size of the field in bits.
    • startPos
      [in] The starting position (relative to bit 0) of the field in the license key validation data. Omitting this value adds the field to the next available position.

    Return Values

    None.

    Remarks

    This method could throw an exception if the field size is too big for the chosen validation data size.

    LicenseTemplate::EnumDataFields

    Enumerates the fields of data used for license key validation.

    Prototype

    bool EnumValidationFields(void **enumHandle, char_t * fieldName, unsigned * fieldNameSize, FIELD_TYPE * fieldType, unsigned * fieldSize, unsigned * startPos);

    Parameters

    • enumHandle
      [in, out] Pointer to a pointer used to store a handle to the enumeration state. A pointer to a NULL handle must be passed at the first call.
    • fieldName
      [in, out] Pointer to a buffer which will be filled with the field name.
    • fieldNameSize
      [in, out] Pointer to an unsigned which will receive the size of the field name string. At input this must contain the size of the buffer.
    • fieldType
      [out] Pointer who will receive the type of the field.
    • fieldSize
      [out] Pointer to an unsigned who will receive the field size in bits.
    • startPos
      [out] Pointer to an unsigned who will receive the field start position in license key data.

    Return Values

    If the enumeration is over, returns false and the output parameters are not filled. Otherwise returns true.

    Remarks

    None.

    LicenseTemplate::SetSignatureSize

    This method is used to set the license key signature size.

    Prototype

    void LicenseTemplate::SetSignatureSize(unsigned size);

    Parameters

    • size
      [in] The desired size for the license key signature. The size must be in the 76-322 range.

    Return Values

    None.

    Remarks

    The license key signature size governs license key security. Care must be taken when choosing the signature size.

    LicenseTemplate::GetSignatureSize

    Retrieves the size of the data used to validate the license key.

    Prototype

    unsigned LicenseTemplate::GetSignatureSize();

    Parameters

    None.

    Return Values

    The signature size in bits.

    Remarks

    None.

    LicenseTemplate::LoadXml

    Loads license key template parameters from an XML string.

    Prototype

    void LicenseTemplate::LoadXml(char * xmlString);

    Parameters

    • xmlString
      [in] The XML template representation string, UTF-8 encoded.

    Return Values

    None.

    Remarks

    This method throws an exception if the template string is invalid.

    LicenseTemplate::SaveXml

    Saves the XML representation of the template into a string.

    Prototype

    const char * LicenseTemplate::SaveXml();

    Parameters

    None.

    Return Values

    Pointer to a string containing an UTF-8 encoded XML represenation of the template parameters.

    Remarks

    The returned string is statically allocated and should not be freed.

    LicenseTemplate::SetPublicKey

    Sets the public key used for license key validation.

    Prototype

    void LicenseTemplate::SetPublicKey(const void * keyBuf, unsigned keyLen);
    void LicenseTemplate::SetPublicKey(const char_t * base64Key);

    Parameters

    • keyBuf
      [in] Pointer to a buffer containing the public key.
    • keyLen
      [in] The length in bytes of the public key buffer.
    • base64Key
      [in] The BASE64 representation of the public key.

    Return Values

    None.

    Remarks

    The public key is only used for license key validation. You do not have to set the public key when you use the template only for license key generation.

    LicenseTemplate::GetPublicKey

    Sets the public key used for license key validation.

    Prototype

    void LicenseTemplate::GetPublicKey(const void * keyBuf, unsigned * keyLen);

    Parameters

    • keyBuf
      [in] Pointer to a buffer receiving the public key.
    • keyLen
      [in] Pointer to an unsigned receiving the length in bytes of the public key. At input, this must contain the length of the buffer pointed to by keyBuf.

    Return Values

    None.

    Remarks

    The public key is only used for license key validation. You do not have to set the public key when you use the template only for license key generation.

    LicenseTemplate::SetPrivateKey

    Sets the public key used for license key validation.

    Prototype

    void LicenseTemplate::SetPrivateKey(const void * keyBuf, unsigned keyLen);
    void LicenseTemplate::SetPrivateKey(const char_t * base64Key);

    Parameters

    • keyBuf
      [in] Pointer to a buffer containing the public key.
    • keyLen
      [in] The length in bytes of the public key buffer.
    • base64Key
      [in] The BASE64 representation of the public key.

    Return Values

    None.

    Remarks

    The public key is only used for license key validation. You do not have to set the public key when you use the template only for product key generation.

    LicenseTemplate::GetPrivateKey

    Gets the private key used for license key generation.

    Prototype

    void LicenseTemplate::GetPrivateKey(const void * keyBuf, unsigned * keyLen);

    Parameters

    • keyBuf
      [in] Pointer to a buffer receiving the private key.
    • keyLen
      [in] Pointer to an unsigned receiving the length in bytes of the private key. At input, this must contain the length of the buffer pointed to by keyBuf.

    Return Values

    None.

    Remarks

    The private key is only used for license key generation. You do not have to set the private key when you use the template only for license key validation (eg. on the customer app).

    LicenseTemplate::GenerateSigningKeyPair

    Generates a pair of private/public keys used for license key generation/validation.

    Prototype

    void LicenseTemplate::GenerateSigningKeyPair();

    Parameters

    None.

    Return Values

    None.

    Remarks

    The signing key pair is generated according to the signature size, so you must call LicenseTemplate::SetSignatureSize() first. You can retrieve the generated keys using LicenseTemplate::GetPrivateKey(), LicenseTemplate::GetPublicKey() or LicenseTemplate::SaveXml().

    KeyHelper Class

    KeyHelper::GetCurrentHardwareId

    Returns a string which uniquely identifies the device (computer) on which the method is called.

    Prototype

    static string KeyHelper::GetCurrentHardwareId();

    Parameters

    None.

    Return Values

    The hardware id string.

    Note that this method is not thread safe.

    KeyHelper::MatchCurrentHardwareId

    Checks if the supplied harware id string matches this computer. Note that there are certain hardware components changes permitted until this method returns false.

    Prototype

    static bool KeyHelper::MatchCurrentHardwareId(string hardwareId);

    Parameters

    • hardwareId
      [in] The hardware id to be matched to the current hardware state of this computer.

    Return Values

    A bool value specifying if the computer matches the supplied hardware id

    KeyHelper::DetectClockManipulation

    This method is used to find evidence that the clock was deliberately turned back with the purpose of prolonging license validity.

    Prototype

    bool KeyHelper::DetectClockManipulation(DateTime thresholdDate);

    Parameters

    • thresholdDate
      [in] The method searches for evidence that the system time was once set after the threshold date

    Return Values

    A bool value indicating if evidence was found that the system clock was deliberately turned back.

    Remarks

    This method may take a few seconds to complete so it is best to call it on a worker thread.