Concept

Before continue we must clarify the basic terminology and new concepts introduced in SoftwareShield first.

Product Name

ProductName is your application name or game title, it is a user-friendly string that can be displayed as UI form caption.

Product ID

In SoftwareShield, a product is associated with a world-wide unique string identifier, usually it is a UUID string (9d062304-6249-4180-9b84-46c6ea5ec916) and can be used as a primary database key in local or server side license store.

Build ID

BuildId is an auto-increased integer version tag for each application build in IDE. When game runs, the buildId is used by SoftwareShield core to upgrade old license status from local storage, at server side, the buildId helps the server locate the correct version of keygen data.

Since SoftwareShield 5.2 (Dec. 16, 2013) the IDE retrieves the latest BuildID from CheckPoint server for every build; It ensures the buildId is unique and incremental for each project.

Entity

It is a new concept in SoftwareShield. An entity is an object to be protected in your application, a conceptual object that can be physically mapped to almost anything that need to be protected or eligible for licensing and sale.

For example, you want to sell a game with 10 levels, you can map 10 Entities to each level so that all game levels can be separately purchased. you might also assign entities to multiple game add-ons and extra packages such as game weapon, maps.

You can define any file as an entity so its accessibility is license-controlled. You can even assign parts of a video file to different entities so the customer can purchase a video streaming service in pay-as-you-go manner.

Another good example is for eBook protection. The first three chapters can be free and other chapters are protected by licenses. When the user browse to the target URL link (or whatever trigger to access the protected resources) and if there is no valid license available then he/she will be prompted to buy the license for this chapter, or a background process is going on to consume a small license fee from eBook web site from the reader’s web account; you can also virtually define a special big entity that is mapped to the whole book, and defines 10 small entities for individual 10 chapters, and when the user has paid for the big entity, you automatically unlock all chapters in the ad hoc license model.

The most simple case is the classical application protection: the whole application is mapped to an entity to control whether the application can run or not, that is exactly what we do in all previous SoftwareShield versions and most of other DRM solutions.

By introducing multiple licensable entities, SoftwareShield supports \emph{micro-transaction}, that is, a digital product can be delivered in multiple stages and purchased in different parts on demand.

Entity ID

Each entity is assigned an application-wide unique string identifier called Entity ID, it is used as the only key to retrieve any entity-related information from the internal system database. Entity Name and Entity Description are simply friendly and optional string properties to display in IDE. The (productId, entityId) pair works as database key to locate an entity.

Entity Attribute

Entity has the following attributes:

• ENTITY_ATTRIBUTE_UNLOCKED

Entity's license is fully activated, no expire or trial limits at all.

If entity is unlocked, the **ENTITY_ATTRIBUTE_ACCESSIBLE is always true.

• ENTITY_ATTRIBUTE_LOCKED

Entity is locked down. An entity can be locked down by applying action ACT_LOCK or after its license's trial period expires. Entity can leave locked state by applying an ACT_UNLOCK action, or a license-specific action (i.e. increase the trial period, trial times, etc.)

If an entity is locked, the ENTITY_ATTRIBUTE_ACCESSIBLE is always false.

• ENTITY_ATTRIBUTE_ACCESSIBLE

Entity is currently accessible; the license attached to this entity is evaluated as Valid, the license might have been unlocked (fully purchased) or is still within the trial period.

If an entity is accessible, you can call entity accessing apis to start using it.

• ENTITY_ATTRIBUTE_ACCESSING

Entity is being accessed, which means, the game level or file resources are active or available for accessing.

• ENTITY_ATTRIBUTE_AUTOSTART

Auto-Start Entity is an entity that, when application launches, is accessed automatically instead of calling gsEntityBeginAccess() manually from source code. You can set up those entities as auto-started if the resources protected by the entities must be accessible and mandatory in order to run the application properly.

When SoftwareShield protected application launches, before the application code running, the SoftwareShield runtime will try to open the auto-started entities, triggering entity access events and the corresponding event handlers will pop up license UI to unlock the entity.

Entity and Resource Binding

In SoftwareShield, as mentioned previously, an entity can be mapped to anything needs protecting, one important use case is application resource protection. You can specify that a data file (picture, audio or video clips, etc.) should be associated or bundled with an entity in SoftwareShield IDE, at the same time you can also specify that the data file be encrypted. When game running, if the game binary tries to access these data files, SoftwareShield kernel will try to detect if the associated entity is accessible, i.e. the licenses attached to the entity should be happy with the access request, then the decrypting keys are loaded into the central key store so the encrypted data files can be accessed normally.

In the above image for example, there are two entities defined in the application. The first entity is protected by its license and bundled with four data files, the second entity has its own associated license and also bundled with 3 data files. These settings can be prepared in SoftwareShield IDE without any coding.

When Software is wrapped and running, if the application tries to access file A via a programming API, such as c++'s fopen() or win32 kernel's CreateFileA/W(), the SoftwareShield runtime will have a chance to query if the file to be accessed is associated with any entity? in this example, the file A is bundled with entity 1, so the SoftwareShield runtime continues query if the entity 1 is accessible? if the entity 1 is already unlocked or its trial license is not expired yet, then SoftwareShield runtime returns a valid file handle to the file access api, otherwise an invalid file handle returns and an error code is set.

License

A license is a dynamic and self-contained logic black-box, the inputs might be local hardware finger prints, or current date time or any interested parameters, the output is a single boolean signal of VALID or NOT-VALID.

An entity can be accessible if and only if its associated license evaluates as VALID.

When a license is valid it might optionally inject some kinds of private information to the running environment. For example, a license might inject several predefined decryption keys to the active key-store so that those entity bundled data files can be decrypted correctly. Those keys might also be part of License Code payload streamed from remote server which remains transient and will be destroyed once game is terminated.

License Model

A License Model is a predefined licensing algorithm; there are various system built-in license models that can be instantiated out of the box, also SoftwareShield allows you to develop new license model via SDK in your own code.

The relationship between Entity, License and License Model is depicted as following:

It is a 1:1 mapping between entity and license (see \fref{fig:EntityAndLicense}), an entity can have only one license and one license can be bundled with only one entity; the license is an instance of registered license model (system built-in or user extended).

License Name, ID and Parameters

A license model has a License Name, a unique License ID and some license-specific parameters. In SoftwareShield all built-in license models supports introspection, that is, all of the license properties and usable actions can be enumerated at runtime.

The License ID of a license is the unique string identifier of the license model it is instantiated from.

Static and Dynamic License

The license defined in SoftwareShield's IDE is called STATIC license since its status is always persistent in local license storage, there is another kind of license called DYNAMIC license which exists in memory temporarily and attach to the target entity on the fly, usually this kind of license is created at runtime or transferred from the remote server to change the application's license status for a short term (per game session maybe).

SoftwareShield SDK allows advanced developers to implement totally new licensing logic by wrapping their own license model dll, these extended license models are of dynamic type that manages creating, persistence, binding to target entity by themselves.

License Status

A license can be in several internal states:

• STATUS_INVALID

  The license state is unknown due to unexpected runtime error.

• STATUS_LOCKED

  The license is disabled permanently. When a license is in a locked state, its associated entity cannot be accessed and when license evaluating, the licensing logic of the license model is not executed.

• STATUS_UNLOCKED

  The license is unlocked (fully activated, or purchased) permanently. When a license is in a unlocked state, its associated entity can be accessed, the licensing logic of the license model is not executed.

• STATUS_ACTIVE

  The license is not locked or unlocked, the license model's evaluating algorithm is executed to return valid or invalid status.

Initially a license is in the STATUS_ACTIVE state, when the entity is being accessed, the license evaluating algorithm is executed periodically to determine if the entity is accessible; if the license model is of a trial one, the license goes to STATUS_LOCKED state automatically after the license is expired, or goes to STATUS_UNLOCKED state if the license is unlocked by action ACT_UNLOCK.

Once in STATUS_UNLOCKED state, the entity cannot be accessed until:

• Goes to unlocked state by applying action ACT_UNLOCK;

  Once a license is expired, it becomes locked and the customer can buy a SN to fully unlock the application.

• Goes to STATUS_ACTIVE state for trial license model if trial parameters (duration, period, ending date, etc.) are modified by corresponding license model-specific actions.

  For example, once a trial by period license is expired, the customer can buy a SN to extend the expire period for another month. It is exactly the Pay as You Go mode.

If a license is fully unlocked, the only way it could leave this activated state is by applying action ACT_LOCK, which happens internally when the customer wants to transfer the local license status to another machine, or for some reason the application wants to terminate the accessibility of a specific entity.

License Transfer

After an application is activated in a machine, sometimes the customers might want to tranfer the current license status to another machine. SoftwareShield provides two ways to do this:

• License Transfer Online

Activated Licenses can be revoked to Checkpoint server. The serial number associated activation seat counter will be increased once the license revoke is successful.

• License Export and Import Offline

The current license data can be exported as a file which should be kept in a safe place; after the hardware upgrade is finished, or the SoftwareShield protected application is installed in another machine, the SoftwareShield can import the previous exported data file.

Action

An action is an atomic operator that can be applied to a license to change its current license status. For example, you can use actions to lock /unlock any license, reset or extend expiry settings of demo licenses. The license status can only be officially modified by itself (according to its own business logic) or by license actions. Multiple actions can be coded in a single Request Code or License Code for a batch operation.

Action Name, ID and Parameters

Action can be uniquely identified by a string Action Name or system assigned integer Action ID, each action also optionally has one or multiple action parameters that defines the action content. The action parameters can be enumerated and manipulated in the same way as the user defined variables.

Action Target

Action can target different objects:

• Generic Action

  Generic Action targets none or all licenses. For example, the action ACTION_FP_FIX fixes fingerprint mismatch issue occurs when the current hardware parameters differs from the original hardware, it targets no specific license; on the other hand, the action ACTION_LOCK and ACTION_UNLOCK can be applied to all types of license models, locking or unlocking the targeted license(s) respectively.

• License Specific Action

  License-Specific Action only make sense when applying to one type of license model. For example, the action ACTION_ADD_EXPIRE_PERIOD extends the trial period by adding predefined seconds to the current trial limit. It does not make sense and will do nothing when it is applied to the \emph{Expire by Duration} license model or any other license models.

Given a license, SoftwareShield SDK provides apis to enumerate all available actions (both generic and license-specific) that can be applied to this license. When developing a license model, the developer can develop ad-hoc actions for it so that the license (status, parameters) can be manipulated by these actions.

Usage Control: One-Shot or Multiple Apply

Depending on the operation of an action by design, it can be applied only once (\emph{One-Shot Action}) or can be used multiple times.

For example, if the action is to extend a monthly subscription based service by topping another month to current trial period, then it should be restricted to apply only once, otherwise the service can be used forever without full purchase.

If an action is to activate the application, then it should be able to apply multiple times so that the customer can re-install and re-activate the application multiple times on the same machine.

For serial number based online activation, the usage control can also be enforced on server side, you can specify the maximum activation limit for each serial number.

Code Exchange

In SoftwareShield, Code Exchange is the official channel of license information exchange between software end-user ( customer ) and software vendor:

• License Requesting

  After the customer has installed your application and wants to activate it, a request code is automatically generated, the customer sends this request code to your staff over phone, by email (offline activation) or web service calling (online activation).

• License Code Generation

  Upon receiving the request code from the client side, you double-check the validity of request code, generates the appropriate license code (via our CheckPoint web management UI or simply running project-specific key generator software) and send it back to the client side.

• License Code Apply

  After the customer gets the license code, he or she inputs the license code to the application's license UI and press "Apply" button, then the application's license status is modified according to what the license code defines.

Of course, the above mentioned code change work-flow is only conceptional, it can be greatly simplified by web-based online activation.

Request Code

Request Code is a string consists of the following information:

Request Code Payload

• Product ID A short array of bits representing which product this request code belongs to, it can help prevent miss-using request code for unmatched product.

• Fingerprint Code A array of bits holding condensed hardware fingerprint informations. The fingerprint is taken from the current hardware configuration, not from the saved fingerprint information in local license storage.

• Actions Requested: What to do

  The action is an operator to manipulate license state. The action(s) embedded in the request code represents what kind(s) of modification(s) to the local license the request code is asking for.

  For example, to activate an entity, the application might generate a request code embedding an action ACT_UNLOCK targeting the entity. Depending on the use case, it is also possible that there is no action specified at all in the request code, or simply a do-nothing action ACT_DUMMY. For online activation, it is the SN (serial number)'s role to describe what to do so it is not necessary to embed any action in the request code.

  The request code embedded actions only express the idea at the client side what the customer wants to do, it is you (the game vendor) or checkpoint server's responsibility to double-check the request and customer identity and authorize what the customer can do by embedding the appropriate actions into the License Code.

Request Code Format

In SoftwareShield, depending on its content payload, the length of request code is not fixed and is grouped in 5 characters as following:

CE4P9-TRE7Z-IA6ES

CLC6O-NBMHP-XHOTR-6DMGF

XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

The valid code points are:

3,4,5,6,7,9, A..Z (26 English upper-case characters)

When transferring the request code string between customers and game vendor, the following error correction mapping is applied at the receiver side to avoid possible code error:

Also please be aware that there are some extra random bits added to the request code encoder, as a result each time a request code is generated, it will be a different one even though its payload is the same.

License Code (Activation Code)

License Code is a string sent from software vendor or web server to the end-user; Your staff member or back-end system must somehow validate that the user has the right to receive an License Code. This could for example be manually performed by your staff looking-up the user in your database as having already paid for the activation. Once authenticated, an License Code is generated and then provided back to the user for activation.

License Code Payload

Just like request code, it has several parts of information:

• Product ID

  A short array of bits representing which product this request code belongs to; it is a copy from request code and can help prevent miss-using license code for unmatched product.

• Fingerprint Code

  A array of bits holding condensed hardware fingerprint informations. It is also copied from the input request code. When applying the license code at client side, the current hardware fingerprint will be detected and compared with the fingerprint code extracted from the license code, if they does not match then the license code is considered invalid and won't take effect.

• Actions Granted: What can do

  Like request code, the License Code is also a container of multiple granted license actions. It is issued from the Manual Activator software or CheckPoint web server after the request code is parsed and verified (and modified if necessary). Basically it tells the client side \emph{What you can do} to the current licenses.

License Code Algorithm

Depending on the license code algorithm being used, there are two kinds of license code:

• DSA-based License Code

  DSA (Digital Signature Algoruthm) is a built-in license code generation algorithm that can be enabled in SoftwareShield IDE:

  

  When DSA-KeyGen is enabled, a public key is stored as part of local license status, and the corresponding private key is stored in keygen data that is uploaded to the server side, each activation code generated from server side will be digital-signed so that it is hard for the crackers to write a fake keygen without the private key.

  For DSA-based license code, it is encoded as a long text string as following:

Tn2ga-9osNG-W6lI3-8@1FW-KeUi0-IxCEB

-oebdK-QEOAX-K%4XT-6szm2-cHsIK-YqZUh

-IBgU@-oZJ9q-gCK13-zScZr-m9WKz-Upk2

The DSA-based license code is secure but has a rather long string, however, if you are using online activation, the user only needs to input a SN, the long license code is processed by computer so the length of code won't be a problem for practical usage.

• {Non-DSA-based License Code

  If DSA is not enabled for your license project, then the license code will be a short string with variable length grouped in 4 characters as following:

BY7T-35BI-9EBP-FNUM-EPUB

SN: Serial Number

The client (end user) enters a Serial Number for online activation. Normally they acquire this Serial Number as a result of a purchase from you. These Serial Numbers could have been pre-generated or dynamically generated as a result of a sale.

It is important to remember that SN is a short string playing the following role in SoftwareShield:

• Proof that the end-user is a valid customer

  The SN is distributed from you to the end users after they have made payments, so if a input SN can be found in server side database then the client should be considered as a valid customer.

  For a customer, it is his or her responsibility to keep the SN in a secret and safe place just like a credit card PIN number. If a SN is leaked to the public and abused by other people, the usage of this SN might be blocked by you at server side.

• Digital label of a bulk of actions

  If the SN is a valid one, then the SN-bundled actions (defined when creating the SN) are copied to the license code as action payload, so you can think of the SN is a digital label of a package of predefined actions. In this online activation scenario, the input request code does not have any action payload (or just a dummy action), the license behaviour is totally controlled by these SN bundled actions.

In SoftwareShield, you can manage each product's serial numbers and activations online at the CheckPoint License Management Web Portal, You can specify serial number format pattern and pre-generated many serial numbers, or import multiple serial numbers of your own format. You can also specify that a SN can serve multiple activations from different client machines, so that a product can be installed on multiple machines in an office with a single SN.

In SoftwareShield, a SN can also be restricted to be used only once, or has a limited shelf-time, we will talk about the SN usage later in more details.

Activation

SoftwareShield uses two types of activations. It is important to understand the difference between the two.

Offline Manual Activation

The following is a demo of the typical work-flow of manual activation:

1. Customer uses your Software

The customer downloads software from your web site, install and launch it;

2. Customer is given an request code

Customer press the \emph{Activate} button on your software's license user interface, it brings the customer to the activation UI and displays a Request Code string

3. Customer contacts Customer Service to buy Software

Customer calls or emails the customer service representative and gives their request code. Your customer service representative help the customer complete the process of purchasing the software. It's also possible that the customer buy software from one of your e-commerce providers and get a receipt or SN as a proof of payment. In this case, the customer will give the receipt to your staff.

4. Customer Service Representative generates the License Code

After verifying the customer has made the full payment for the software, your staff can now generate a license code corresponding to the customer's request code.

It can be done by either running the Key Generator (gsKeyGen.exe) software offline, or goes to the CheckPoint Management Web Site and generate the license code online.

Customer Service Representative gives License Code to Customer over phone, by email.

5. Customer inputs the License Code

Software unlocks whatever is defined by the license code.

Online Auto-Activation

The following is a demo of the typical work-flow of online activation:

1. Customer uses your Software The customer downloads software from your web site, install and launch it.(see \fref{fig:GameAppStart})

2. Customer Buy Software There are two ways to buy software:

• Online

  After pressing the \emph{Buy Now} button, the customer is directed to a webpage that allows them to purchase your software. It may be your own web server or one of your e-commerce provider that guide the customer complete the purchase.

  Upon the customer has made payment, the web back-end server retrieves a serial number either from a data base or generated dynamically by calling SoftwareShield CheckPoint Web service api, then the serial number is returned as part of the transaction's receipt sent to customer.

• Retail Store

  The software vendor generates serial numbers in bulk on the CheckPoint Management Web Site; customer buys the software from a retail store and gets a valid serial number printed on the label of package box.

3. Customer inputs the Serial Number

   Customer inputs the serial number, the software communicates to CheckPoint web server to get a license code, and apply the license code to the local license, as a result the software unlocks whatever is defined by the license code.

Variables and Parameters

In SoftwareShield, you can define or create at runtime a \emph{variable} that can be used in your application logic, the advantage of using a SoftwareShield variable is that you can access it in your native or javascript code so that your application will be tightly bundled with the SoftwareShield runtime kernel binaries. It will make cracking even harder because your application code relies on the SoftwareShield runtime kernel in order to run properly.

The SoftwareShield SDK allows you to create, retrieve and enumerate all public variables published in the SoftwareShield runtime.

A variable is a simple object which has:

• name: string name;

• typeId: data type id;

  Variable Attributes Supported

  Data Type	Type Id	Type String
  Integer	VAR_TYPE_INT32 (7)	"int32"
  Float	VAR_TYPE_FLOAT (9)	"float"
  Boolean	VAR_TYPE_BOOL (11)	"bool"
  String	VAR_TYPE_STRING (20)	"string"
  Date Time	VAR_TYPE_TIME (30)	"utc_time"
  Integer 64bit	VAR_TYPE_INT64 (8)	"int64"
  Double	VAR_TYPE_DOUBLE(10)	"double"

• value: data value;

• attribute: The meta data defining if the variable can be read, write or persisted.

  Variable Attributes Supported

  Attribute	Mask	String	Description
  Read	0x01	"r"	Variable is readable
  Write	0x02	"w"	Variable is writable
  Persistent	0x04	"p"	Variable is persisted (not a temporary one)
  Secure	0x08	"s"	Variable is secured in memory
  Remote	0x10	"R"	Variable is persisted on server side
  Hidden	0x20	"h"	Variable cannot be enumerated by SDK apis
  System	0x40	"S"	Variable is reserved for internal system usage

There are three categories of variables in SoftwareShield:

User Defined Variables

In SoftwareShield IDE, you can define multiple variables in the license project settings. These variables can be accessed by SDK APIs in the native code (of your application or custom license model) or javascript in the \emph{LMApp} web pages.

License / Action Parameters

In SoftwareShield, the \emph{license} has its own status parameters which is exposed and can be accessed in the same way as user defined variables, the most important difference is that these license parameters are most likely read-only to SDK caller and can only be modified internally by an qualified action.

The action, similarly, has multiple control parameters which can be accessed in the same interface as variable. When creating an action, you set up the appropriate action parameters as necessary, these actions are persisted and packed as part of payload in code exchange.

Session Variables

When customizing your own license UI, you can define and use application session variable which lifespan is the time period between application start and termination.