PLUSManaged: Manual Activation (Offline Method)

Important

If you are using or planning to use PLUSManagedGui in your application, this content may not be relevant to you since PLUSManagedGui automatically handles common functionality.

When Internet access is not available and online activation is not possible, manual activation is the recommend method for activating an installation and obtaining a license file from SOLO Server. This involves the end-user copying the activation request or saving it to a file that they would take to another computer with Internet access. They would then paste the request or upload the file to SOLO Server's manual request page, which processes the request and generates a response. The end-user must then copy this response or save it to a file and return to the computer they are attempting to activate. Finally, they must paste in the response or point the application to the file. The application can then parse the response and determine which action to take.

The following demonstrates manually activating an installation, retrieving a license file from SOLO Server, and saving that license file to disk.

Generating and Encrypting the Request

The PLUSManaged library has built-in functions for generating requests for the SOLO Server XML Activation Service and XML License File Service web services. Use of these functions avoids having to manually build the web service XML request document. If necessary, further control over generation of the requests may be achieved via the WebServiceCall classes.

The following code snippet demonstrates generating the manual activation request:

C#
string request = m_License.GetActivationInstallationLicenseFileRequest(licenseID, password);
VB.NET
Dim request As String = m_License.GetActivationInstallationLicenseFileRequest(licenseID, password)

This excerpt of code assumes m_License is a reference to an instance of your applications License or WritableLicense implementation class, licenseID is an Int32 object obtained from the user, and password is a string obtained from the user. Now your application may allow the user to copy the request (so it may be pasted to SOLO Server's manual request page), or it may allow the user to save the file (which may be uploaded via SOLO Server's manual request page).

Using the SOLO Server Manual Request Page

Once the user generates the manual activation request, they must take it to a computer with Internet access where they can paste it in or upload it to the SOLO Server manual request page. If SOLO Server is able to successfully process the manual request it will generate a response that must be taken back to the computer being activated. Otherwise, it will display an error message and it may be necessary for the end-user to contact support for help and possibly have to start the process over.

Important

The above SOLO Server Manual Request link is for use with Instant SOLO Server only. If you are using a dedicated or externally-hosted SOLO Server, this will need to be updated to point to your specific domain.

Manual Request HTML Files

Manual request HTML files are convenient for your users since the files can help automate submitting manual requests. In short, these files can be generated easily with PLUSManaged using the ManualRequestFile class. The file will contain the generated request, and can automatically post the request to SOLO Server's manual request page. The code example below shows how you can use this class to automatically save a file to the user's desktop, which he or she may then copy to another computer, and then double click it to process the request using the default web browser.

C#
string requestFilePath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.Desktop), "ActivateXyzProduct.html");
ManualRequestFile requestFile = new ManualRequestFile(request, requestFilePath);
requestFile.Save();
VB.NET
Dim requestFilePath As String = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.Desktop), "ActivateXyzProduct.html")
Dim requestFile As New ManualRequestFile(request, requestFilePath)
requestFile.Save()

The code provided above should be modified to specify a file name other than "ActivateXyzProduct.html" (so that it reflects the name of your application instead), and it can also be updated to use a path selected by the user as well (thus allowing the user to use a browse dialog to specify the location instead, if preferred).

Important

If the user is pasting in a response instead of loading a response file, there are a few potential issues to be aware of:

These issues do not occur when the encryption response is loaded from a file.

Decrypting and Parsing the Response

After the end-user returns to the computer being activated with the encrypted response, it must be decrypted and verified.

C#
string lfContent = "";
bool successful = m_License.ProcessActivateInstallationLicenseFileResponse(response, ref lfContent);
VB.NET
Dim lfContent As String = ""
Dim successful As Boolean = m_License.ProcessActivateInstallationLicenseFileResponse(response, lfContent)

In the above code, it is assumed that m_License is an instance of your License or WritableLicense implementation class, and response contains the response received from SOLO Server's manual request page. Once you create an XML document from the license string you can save it to disk. If the response is successfully decrypted and verified, successful will be set to true, and you may then save the value of lfContent to disk as your application's new license file. Otherwise, if the response could not be decrypted or verified or indicates another error, successful will be set to false, and additional details about the error will be available in the m_License.LastError property.

Important

These basic source code examples omit important and necessary error checking for the sake of clarity. Many of the functions used could fail for one reason or another, and it is important that you make sure each function call succeeds before passing the result from one function to another. Otherwise, you may not be able to tell exactly where a problem originated if and when one occurs.

Session Code Validation

Session code validation to prevents the end-user from processing the same response multiple times, which is known as a replay attack. A random session code is generated and included in each web service request. This session code must be saved somewhere on the system so it can later be retrieved and compared to the session code found in the web service response. If the session codes match then you know the response was the response associated with the original web service request. Otherwise, the response should be consider invalid. Your license implementation class will inherit the CurrentSessionCode property and the ResetSessionCode method from License or WritableLicense. You may use the CurrentSessionCode property to read the session code value (to store a session code after generating a request), and you can set the property to restore a prior value before processing a response. The ResetSessionCode method generates a new session code, and should always be called after successfully processing a response. Additionally, you may opt to be a little more strict and do this when any response processing is attempted, as doing so would be more secure (although it means customers have to generate a new request after each attempt, even if it fails, which could pose some inconvenience depending on how much effort is involved with the customer using a different computer to activate).