Before reading the rest of this page, you should already understand the basics of license recovery. If not, please read License Recovery in this Feature Guide.

Recovery by Activation Code refers to simply when a user inputs an Activation Code which you have issued that will recover a license.

Like all other forms of request and activation, Recovery by Activation Code is a two step process called a "code exchange":

1. Your application provides an Authorization Request Code for a Recover License Authorization Definition. The user must communicate this code to you.

2. When you receive the request, you must generate a corresponding Activation Code that you send back to the user who will input it into your software to activate the recovery.

Performing a code exchange to recover a license can be done from inside the scope of the StartUp call (by your OnAttemptRecover event handler) or from outside its scope by your application calling RequestActivation and InputActivationCode. This page deals primarily with the later. For help on the former, instead see Prompt For Recovery in the reference. Functionally, to the user, the two methods will appear virtually identical - the real difference is in your implementation.

If you have decided not to set Prompt for Recovery in your license, when an inconsistent state occurs that would otherwise require recovery - the ClientProtector will silently return from the StartUp call with a return_code indicating the outcome. It will be your applications responsibility in this case to interpret the value in the return_code from the StartUp call to determine if a recovery is required and perform a code exchange. Recovery will be required in this case when the return_code contains one of the following values:

1. FALSE_LFS_NOT_CORROBORRATE

2. FALSE_NOT_VIRGIN_INSTALL

3. FALSE_LICENSE_NEEDS_RECOVERY **

** This code will actually only be returned if you have set Prompt for Recovery, but the OnAttemptRecover event handler returns to the ClientProtector without an Activation Code input by the user.

 To best understand when and where the ClientProtector will return from the StartUp call with one of the above retrun_codes (indicating that you need to perform a code exchange to facilitate recovery), please have a copy of the SoftwareShield ClientProtector Control Flow Charts on hand as you read the rest of this section.

Note that when you are not using the Prompt for Recovery option, your application will always return from the StartUp call without firing the OnAttemptRecover event - even if the license does in fact need recovery. You may find it easier to enable this option, allowing you define a special event handler to handle a recovery from inside the scope of the call. Prompt for Recovery is actually the preferred method as it is easier to implement and reasonably secure. (See Prompt for Recovery for more details).

However, when you choose to handle your own recovery code exchange you can choose to make it even more secure. Because the ClientProtector has returned from the StartUp call "silently" you can interpret the return_code and take action at some point later in the processing. In fact, it is best to delay the processing of the recovery as long as possible. You may wish to wait several seconds, minutes or even days before you actually take action. This delay results in the program code that caused the recovery requirement to arise to be more difficult for a cracker to find. If you need to wait between sessions, naturally you will have to persist this state somewhere. You could persist this somewhere of your own, or use the licenses Secure License Details area. If you don't need to wait between sessions, the best plan is to create a timer in a new thread and when it fires perform the code exchange - prompting the user only after the delay has elapsed.

Naturally, using Recover by Activation Code outside of the scope of the StartUp call will require more code on your part, but may give you added security or control over the exact communication between your application and the user.

Using Recover by Activation Code requires a code exchange to recover a license. While this may be a slight inconvenience for you and the user, it is much more secure against crackers since they will only be able to make one attack in this manner on your licensed software before they need to contact you to recover it. Repeated requests for a recovery code obviously indicate someone purposefully tampering with the licensing system and you can take corrective action. It is important to consider the tradeoffs here and make a careful decision about its use.

More Information

For help on understanding the flow of control during the call to StartUp and how the logic behind RequestActivation and InputActivationCode works, see SoftwareShield ClientProtector Control Flow-Charts in the ClientProtector Reference.

For detailed help on return_code values, see Return Codes in the SoftwareShield ClientProtector Reference.