Event

SoftwareShield uses event-listener design pattern. When an event is broadcasting, all registered event listeners are notified with an event id and event object.

There are 3 different public event sources:

Application Events

The Application Events are generated when the SoftwareShield launches the application:

• EVENT_APP_BEGIN (1): Application just gets started

  At this stage all dependent libraries are loaded and the application is about to run. The Licensing system is already initialized and the local license storage is connected, so any licensing related information is available.

• EVENT_APP_END (2) : Application is going to terminate

  It's the last event sent out to all listeners, the licensing system has shut down and the application is about to exit. No licensing information can be retrieved at this stage.

• EVENT_APP_RUN (5) : Application is going to run.

  It's the last event sent before the \emph{OEP} (original entry point) is executed.

• EVENT_APP_CLOCK_ROLLBACK (3) : Application detects the clock is rolled back.

  When the system clock is rolled back, the application will be terminated after this event is handled.

  Because some built-in license models relies on the correctness of begin / end time point, a cracker might want to cheat the license logic by modifying the local clock so that the license can always be valid.

  Another reason why a clock can be rolled back is that when the CMOS battery on motherboard becomes low it may not hold correct clock time, so when the machine is powered off and powered on again, the local clock may be wrong (far behind the current date time).

  The following license models rely on correct clock:

  • Expire by Hard Date;
  • Expire by Period;

  The license model has a parameter (rollbackTolerance) which is the maximum seconds the clock can jump backward.

  In SoftwareShield, the clock roll-back detection is disabled when:

  • the rollbackTolerance is set to 0;
  • the license already is unlocked; (licence’s status is STATUS_UNLOCKED)

• EVENT_APP_INTEGRITY_CORRUPT (4) : Application's integrity is corrupted. Usually it means that some read-only files which are monitored by SoftwareShield is changed from the original file state when the game is wrapped. When the system integrity is corrupted, the application will be terminated after this event is handled.

License Events

These events are from the license storage when loading license information:

• EVENT_LICENSE_NEWINSTALL (101)}: Original license is saved to license storage for the first time.

  When a new SoftwareShield protected application is installed on a client machine and launched for the very first time, this event is fired when the original license data (usually embedded in the software binary) is persisted to the local license storage.

• EVENT_LICENSE_READY (102)}: The application's license storage is connected /initialized successfully

  When application launches, the SoftwareShield runtime tries to search and retrieve existent license information from the local storage, if the application-specific license information can be loaded and decoded successfully, this event is fired so you can start accessing the application's license status safely.

• EVENT_LICENSE_FAIL (103)}: The application's license storage cannot be connected /initialized properly.

  When application starts and SoftwareShield runtime tries to open the product's license information, something goes wrong. Currently the error event is fired when the following issue occurs:

  1. License storage is corrupted Even though SoftwareShield has tried hard to implement the license storage algorithm as stable as possible, there is still very rare chances that the persisted license information bytes could be physically corrupted. In this case, the only way to recover from this data corruption is clean up the product's license data and roll back to the original license status.

  2. Hardware fingerprint mismatch is detected If the project turns on the fingerprint feature and hardware has been modified after the application's first run, the event is fired.

     It could happen when the end user has made a big change to the hardware which exceeds the project's predefined fingerprint error tolerance. This event can also be fired while the application is running and hardware is changed at runtime.

     To fix fingerprint mismatch issue, the end user have to ask customer service for help, the customer service representative gives the end user a serial number (bundled with an ACT_FIX action) to re-take a snapshot of current hardware status.

Entity Events

Entity events are posted while internal state transition happens either by SDK api calling or license state changes:

• EVENT_ENTITY_TRY_ACCESS (201)}: The entity is to be accessed.

  The listeners might be able to modify the license store here, The internal licenses status is not touched yet. (inactive if not accessed before)

• EVENT_ENTITY_ACCESS_STARTED (202)}: The entity is being accessed.

  The listeners can enable any protected resources here. (inject decrypting keys, etc.) The internal licenses status have changed to active mode.

• EVENT_ENTITY_ACCESS_ENDING (203)}: The entity is leaving now.

  The listeners can revoke any protected resources here. (remove injected decrypting keys, etc.) Licenses are still in active mode.

• EVENT_ENTITY_ACCESS_ENDED (204)}: The entity is deactivated now.

  The listeners can revoke any protected resources here. (remove injected decrypting keys, etc.) License is switched to inactive mode.

• EVENT_ENTITY_ACCESS_INVALID (205)}: Entity access is expired or becomes invalid for some reason.

  In current implementation, once the event is posted, the application will be terminated so the listeners should take this chance to display a license UI before the application quits silently.

• EVENT_ENTITY_ACCESS_HEARTBEAT (206)}: event indicating entity is still alive.

• EVENT_ENTITY_ACTION_APPLIED (208)}: The status of attached licenses have been modified by applying license action.

  It is called after the change has been made, so you have a chance to read latest license status to update in-memory variables. gsLMRun uses this event so once the end user has activated the product no more nag screen should be popped up.