Open topic with navigation

Tutorial 1: Wrapping an Application

This tutorial will step through the process of wrapping an application using the SOLO Server test author account. The tutorial will use the Demo Application included with the Instant Protection PLUS 3 installation, but you may use your application with this tutorial instead of the Demo Application.

The unprotected Demo Application can be found in the Instant Protection PLUS 3 installation folder. By default this is %PROGRAMFILES(X86)%\SoftwareKey\Instant PLUS\samples\DemoApplication\DemoApplication.exe. The Demo Application is a standard 32-bit native Windows application created with Microsoft Visual Studio.

The images shown will generally only show the wizard section of Instant Protection PLUS 3 rather than the entire application unless needed.

If you are planning to use the Instant Protection PLUS 3 DLL, you may still follow the steps in this tutorial as the wizard and activation process is nearly the same. We will point out when the process diverges.

The first step should always be planning the licensing requirements. Our Take Time to Save Time: 4 Reasons to List Licensing Requirements blog post explains why this is important.

For this tutorial, we have the following requirements:

  1. The application will start as a 15-day trial.
  2. The application will allow online and manual activations (by email, phone, etc).
  3. The application will activate with a perpetual license. Once activated the application will be allowed to run indefinitely unless the license is deactivated, revoked by SOLO Server, or is deemed invalid by Instant Protection PLUS 3.
  4. The application will be copy-protected. If a licensed version is copied to another machine, the license will not be valid.
  5. The application will validate the license online with SOLO Server every run.

That will cover our requirements and we can now begin creating our project with Instant Protection PLUS 3.

Am I limited to only one type of license when I protect my application?

While this tutorial will only demonstrate activating a perpetual license, other license types are supported such as subscription licenses. You only need to wrap your application once with the proper settings in order to have a single application executable that supports multiple types of activations.

Open Instant Protection PLUS 3.

Helpful Information

Each wizard step in Instant Protection PLUS 3 shows documentation specific for the step in the left frame of the application.

Select "Start a new project" if not already selected and click Next.

You may use the link at the top of this wizard at any time step to sign up for a free SOLO Server account which allows more features, although this tutorial only demonstrates using the test author account.

Select "Protection + Automation" if it is not already selected then click Next.

Click the Use the Test Author Account credentials for testing purposes button, which auto populates the following credentials for the SOLO Server test author account:

Author ID: 2461927
User ID: test
Password: test

After entering the credentials press the Synchronize button.

A list of available Products for this author account is displayed in the top list with the selected Product's Options in the bottom list.

Select the "Instant Protection PLUS 3 Sample" Product in the top list. The bottom list contains the Product Options available for the "Instant Protection PLUS 3 Sample" Product. Select the "Perpetual License" Product Option then click Next.

What is the "Create a new Product in SOLO Server" button at the top of the wizard step?

The button at the top of this wizard step will open a browser window to the Add Product Wizard in SOLO Server. The test author account is a "locked" account and does not allow the creation of new products, therefore the Add Product Wizard is unavailable when using the test author account as we do in this tutorial.

Helpful Information

In SOLO Server, a product is defined to describe your application as a whole, and may contain one or many Product Options. At least one product option is defined for each type of license your application will support and require activation to use.

Helpful Information

It may appear you need to have a wrapped build of your application for each Product Option, but this is not the case. As long as the Product Options are under the same Product (optional) and the Trigger Code Seed, RegKey 2 Seed, and OffAct Key (offline activation key) values are the same between Product Options, you only need to have a single wrapped application. For example, using the above Product "Instant Protection PLUS 3 Sample", we see there are three Product Options for it: "1 Year License", "90 Day License", and "Perpetual License". Synchronizing to any one of these Product Options will allow licenses for any of the other two Product Options to work as well on the protected application. This is because in SOLO Server we have set the Trigger Code Seed, RegKey 2 Seed, and OffAct Key to the same values for each of these three Product Options. And while a license for each of these Product Options will work on the same application, each will activate the application's license in a different way. See this manual topic for more details.

This is where we choose which Instant Protection PLUS 3 options to use when wrapping the application. Select the same options from the screen shot below. As the tutorial continues, we will describe the options selected when reaching the wizard step for each option.

Click Next.

General Product Information

When synchronizing, Instant Protection PLUS 3 retrieved the name of the Product from SOLO Server and filled in the Product Name setting for us. This is the name of your product that is shown on the activation dialogs. You can modify the name as you see fit and it will not affect the synchronized data. Change it to "Tutorial Application".

Under Product Website enter www.softwarekey.com. When there is a value for the Product Website, the activation dialogs will show a "Go To Website" link that will open the customer's browser to the link you specified.

Add https://support.softwarekey.com/ or any valid URL to the Support Website edit box. When there is a value for the Support Website, the activation dialogs will show a "Click here for support" link that will open the customer's browser to the link you specified.

Instant Protection PLUS 3 filled in the Product Purchase Link from the data during synchronization. The default purchase URL was retrieved during synchronization and will create a new shopping cart in SOLO Server containing the selected Product Option. The Product Purchase Link can be modified to open the browser to a URL of your choosing, such as landing page on your website that lists the different options a customer can purchase.

Click Next.

License File Options

The license file is a binary encoded file created when the user first runs your application, or it can be created when wrapping and distributed with your application. This file will contain your application's license status as well as many other settings. We will leave the location of the license file at the default value "Auto-create in the current user registry". By selecting this option, an activation will only license that particular named user, not every user on the machine. This option does not require you to ship a license file with your application, and also eliminates the need to set elevated permissions when first opening the license and alias files due to the Windows UAC. When the protected application is first run, the license file will be created in the user's registry under HKEY_CURRENT_USER. Instant Protection PLUS 3 will automatically create the path in the registry and the license file. You can modify this path if needed, but most users will not need to change it. The License File Password is the key used to encrypt and decrypt the license file. Instant Protection PLUS 3 will create a random GUID for this value.

An application can utilize multiple license files. The first file opened is the primary or master license file. Multiple synchronized backup copies, or aliases, of this primary license file can be scattered on the user's system to prevent trial re-installation to gain more time. If the user were to restore from backup or delete a license file to attempt to gain additional use of your trial, one of the alias files can automatically restore the correct license information and defeat the hacker's tampering attempt. Leave the remainder of the settings at their default values. These settings control how many alias license files will be created and synced with the main license file.

Click Next.

Trial Options

For our trial, set the days to run to 15. When a user first runs the protected application, the countdown of trial days will begin. Once 15 days have passed they will no longer have the option at startup to evaluate the application and will be presented with only the options to purchase and activate. This satisfies our first requirement from Step 1: "The application will start as a 15-day trial".

We will leave the rest of the options as they are.

Click Next.

Copy-Protection Options

Copy-protection allows us to lock the license to a computer based on a hardware information. Leave the selection on "Use Enhanced Computer ID Algorithms". Once the protected application is activated, a "hardware signature" is stored in the license file. At each start of the application the hardware signature is created from the current PC's configuration and compared to the signature in the license file. If they do not match then the license is invalid and the user must activate with a valid license in order to run the application. This prevents a license being copied from an activated computer to another computer in order to circumvent the licensing as the hardware signature of the second PC will not match what is in the license file. This satisfies our 4th requirement from Step 1: "The application will be copy-protected".

Click Next.

Manual Activation Options

Manual activations happen when a customer calls a support telephone number to get activation codes or sends an email. Manual activations are not required when using SOLO Server, but we will allow them for this tutorial. You may modify the "Text displayed on activation dialog" to include the proper number and/or an email address. Leave the rest of the options at their default settings. This satisfies the last part of our 2nd requirement: "The application will allow online and manual activations".

Click Next.

Activation Options

The Activation Options allow some customization once an activation is processed. Here you can customize the message displayed if the activation succeeds or fails. Change any of the text you like and leave the other options at their default settings. This satisfies the rest of our 2nd requirement: "The application will allow online and manual activations".

Click Next.

We are not using License Key Injection.

Click Next.

We are not using Periodic Expiration in this tutorial. Normally, this is where you would set the options when you want your product to have a subscription license.

Click Next.

The Background Checking Options are how we configure the frequency the protected application communicates with SOLO Server in order to validate the license. Using these options allow the remote deactivation of a customer's license.

For this tutorial, check to "Validate with server every" and set the value to 1 runs. You may uncheck the next box to validate by days, but it is not necessary.

Helpful Information

Checking the license with SOLO Server may be excessive and can cause a small delay at the application start up while it communicates with the server. If you do not have a splash screen already in your product, it is a good idea to use the Instant Protection PLUS 3Splash Screen option as it will help mask the start up delay.

Modify the "License Revoked Message" as you see fit. Here, we modified it to "The license has been revoked by us remotely!". This satisfies our 5th requirement: "The application will validate the license online with every run".

Click Next.

Integration Method

It is at this point you choose whether you are using the Instant Protection PLUS 3 wrapper or the Instant Protection PLUS 3 DLL. The Instant Protection PLUS 3 wrapper will inject the licensing code with the settings we have created thus far into a Win32 PE file (Visual C++, Visual Basic 6, most applications and DLLs not written in .NET). The wrapper is the easiest integration method and includes extra protection such as compression and encryption of the protected application.

Helpful Information

If you have an application that is not supported by the wrapper (such as .Net) that can call functions in a 32-bit or 64-bit native DLL, you can easily use the Instant Protection PLUS 3 DLL rather than the wrapper. All of your settings created in Instant Protection PLUS 3 would be saved to an encrypted file. Your application will pass the path to this file along with the encryption key to a function in the Instant Protection PLUS 3 DLL which will execute the licensing the same as the wrapper and return a value letting you know if you should let your application continue to run. In addition, the Instant Protection PLUS 3 Integration Assistant, found in the Start Menu under SoftwareKey Licensing System, can be used to help generate the proper code to add to your application.

This tutorial will demonstrate using the wrapper to protect the application, therefore leave the default radio button selected.

Click Next.

  1. Click the small folder button next to the text box under File to Wrap. Browse to the Demo Applicationwhich is by default located in C:\Program Files (x86)\SoftwareKey\Instant PLUS\samples\Demo Application\. You may optionally use your own application instead of the Demo Application as the input file.
  2. Click the small folder button next to the text box under OutputFolder. Browse to the folder which will contain the protected application. Note: the output folder must not be the same as the input folder. The Windows Desktop folder is a good spot to output the protected application for this tutorial.

Leave the rest off the settings with their default values.

Helpful Information

If the wrapper reports any errors or fails to wrap your application, try turning off some of the features on this wizard step such as "Rebuild import table" or "Compress my application". Be sure to only turn off one feature then attempt to wrap the application which will allow you to discover if one of the wrapper features is causing the issue. Remember, if you are unable to wrap the application you may use the Instant Protection PLUS 3 DLL instead.

Click Next.

You will be asked to save your project before wrapping. Go ahead and do so.

Once the wrapper has completed you can click the Run App button to execute your protected application or browse to the output folder in Windows Explorer and run the protected application directly. Note: if your application requires supporting files (such as images, DLLs, etc), you should either copy them into the output folder, or copy the protected application file into the folder that has all the support files in order to run and test.

You will see a dialog similar to the one below.

Summary

In this tutorial you have learned how to synchronize your product with SOLO Server, and protect your application using the Instant Protection PLUS 3 wizard and wrapper.

In the next tutorial, we will continue by using the protected application created in this tutorial and demonstrate creating a test license in SOLO Server, activating our protected application, and remotely deactivating the license.

Continue to Tutorial 2.