New features in SourceGuardian 5.0

The new SourceGuardian 5 loaders are fully compatible with all SourceGuardian 4.x scripts. The New loaders can execute encoded scripts created with the SourceGuardian 4.x and SourceGuardian 5 encoder.

The following error message will be displayed if you attempt to run SourceGuardian 5 encoded scripts with earlier loaders:

A new protection algorithm for external script license protection has been introduced in SourceGuardian 5.0. This algorithm gives your scripts much stronger protection from reverse engineering, unlocking and bytecode stealing, but it also gives you the most flexible way to generate trial versions of your products and to lock scripts to your customer's machine.

This method requires the use of a *license file* for your protected scripts to run. This is most powerful and flexible way to protect your scripts. We recommend you to use external license files for all your script protection.

This new algorithm uses the idea of two keys. The first key (Project Id) is stored in the encrypted area of the protected script and is used to decrypt an external license file. The second key (Project Key) is stored in the license file and it is used to decrypt the bytecode from the protected script.

Using the new algorithm protects your product by preventing a full working copy from being created from, for example, a demo version. To decrypt and run a protected script a true license file for the full version of your product is required. Otherwise it's impossible to decrypt and run the bytecode.

Project Id and Project Key values are required if the external license protection method is chosen.

GUI users: Project Id and Project Key are automatically generated as random values for any new project. These values are stored in the SourceGuardian project file and usually should not be changed. You may copy or change these values if needed, but it is recommended not to.

Command line users: You should specify Project Id (--projid) and Project Key (--projkey) values using options in the command line for "encode4" or "encode5" commands. Project Id and Project Key may be any words, numbers or random sequence but for security reasons these two values *should not* be calculated from each other. They should be independent. Also you should specify the *same* Project Id, Project Key pair for "licgen" command when generating a license for previously protected scripts.

encode4 --external script.lic --projid "19Gh42Ki" --projkey "Ab65qZ32" myscript.php

If you have licenses for multiple SourceGuardian installations you may encode scripts on one machine and generate license files on another machine. The only condition is to set the same Project Id and Project Key values for your project on different machines.

If a script is run with an incorrect license file the following error message will appear:

If script is run with a license file with correct Project Id but incorrect Project Key (this may be a cracking attempt or accidental modification of the license file or script) the following error message will appear:

(!) Remember your Project Id and Project Key. It's impossible to restore the values from somewhere if forgotten. They are required for generating licenses for your customers. GUI users - Project Id and Project Key are stored in SourceGuardian project file.

(!) When generating the Project Id and Project Key manually, please use independent values.

You may still encode your scripts with an embedded license. In this case Project Id and Project Key values are not required. Project Id will be required for "conjunction" feature (see below).

SourceGuardian will keep the first line unchanged of the script if it begins with a #! UNIX shell script prefix (ex. #!/usr/bin/php) This lets protected scripts run from the shell. The first line of the script will not be encoded but the whole script including this line will be still protected with a checksum and so remains protected from unauthorized modifications.

SourceGuardian also lets you define custom named constants during an encoding process, or within an external script license. Constant name/value pairs are stored internally in the encrypted area of the protected script or external license. They may be used for custom script locking or any other actions if you need to store a custom value in the protected script or script license file and then retrieve it from your PHP code.

GUI users: You may define custom constants in the SourceGuardian options dialog (these constants will be used for every project) and in Advanced mode - 'Custom constants'. See Custom Constants section for details. When you generate a license you can define custom constants too.

Command line users: Use --const name=value option in encode4, encode5 or licgen command. Use quotes if your constant name or its value contains any spaces or other special symbols:

You may define only one constant with each --const option but you may add as many --const options as you need into the command line.

To get a predefined constant value from the PHP code use sg_get_const() function. This function is defined in the SourceGuardian loader.

sg_get_const("encoder")	Returns the name of encoder "SourceGuardian"
sg_get_const("version")	Returns the encoder version number
sg_get_const("encode_date")	Returns UNIX timestamp when the script was encoded
sg_get_const("license_date")	Returns UNIX timestamp when the script license was created. It's may differ from "encode_date" when external script license is used
sg_get_const("expire_date")	Returns script expiration date as UNIX timestamp if it's defined in the script license or internally via script binding options during encoding

You may add custom error handling functions which will catch script licensing errors. Error handler should be a function which accepts two parameters:

You may use any name for this function. Also you may have different functions for different script errors. The first argument will contain an error code. The second one will contain a default error message.

GUI users: You may define custom error handlers in Advanced mode. See Custom error handling section.

Command line users: To set a custom error handler use --catch option in encode4 or encode5 command:

Where "err" is one of predefined constants and "function" is error handler function name.

Err	Code	Default message
ERR_LICENSE	01,02,03	script cannot run on this machine
ERR_EXTLICCRC	06	script license is invalid
ERR_EXPIRED	09	script has expired
ERR_EXTLIC	13	script requires license file to run
ERR_OFFLINE	20	script requires an internet connection to run
ERR_ALL	-	-

Custom error handler function should be defined before an error may occur. The best place for it is in "prepend header" code as it's loaded *before* any license checking is done and so error handler will be always available if defined here. But you may also define a custom error handler function in another encoded file which will be included before the script which may cause a license error. Don't put any passwords etc secret data if you use a "prepend header" code for defining an error handler as this code is stored unencoded.

You may catch some SourceGuardian errors with the standard PHP error handling mechanism. This may be useful if you already have an error handler in your code. Below is an example of an error handler to catch SourceGuardian errors.

You may get information about protected scripts or an external script license. This may be useful for supporting your customers, checking scripts or licenses passed to them etc. You may know the date of parameters such as encode, expiration date, binding options etc from the protected script or script license.

GUI users: Use 'Info tools' menu to open "Script and License information" dialogues. See Information tools section for details.

Command line users: Use the sginfo tool which is installed with the SourceGuardian encoder. You may pass the encoded script name or script license as a parameter to this tool.

Optionally you may need to specify a project key (--projkey), target ip (--tag-ip) and/or target domain (--tag-domain) to let the script information tool decrypt the encoded file and display the info. Also you need to specify the project id (--projid) value to decode and display the script license information.

It's possible to display script information only for scripts created *with the same installation* of SourceGuardian. To display script license information from an external file you need to know and specify the project id.

SourceGuardian 5 loaders may be loaded as Zend extensions. This allow you to specify the full absolute path to the loader regardless of the extension_dir setting. Of course the PHP or webserver process should have enough permissions to access the loader in that location.

For *threaded* PHP use zend_extension_ts option in php.ini: (mod_php apache module is always threaded under windows)

Also you should specify an appropriate loader for your OS and PHP version. See the "server wide install" section in our user's manual about loaders names.

This feature was introduced in SourceGuardian 4 and restricts executing of any unencoded php script included from the protected script. In SourceGuardian 5 it was changed to allow including and executing only scripts from the same project (with the same Project Id value). This lets you develop and encode parts of your project on multiple machines (with multiple SourceGuardian licenses) and keep the "conjunction" option on for maximum protection.

We recommend to always use this feature if your project has any secure data embedded in scripts such as usernames, password, database names etc.

In SourceGuardian 5 the "conjunction" option is always applied to the script during encoding and not to the external script license.

If you use a time lock option for your scripts you may wish to let the script get the world time from the online time service for expiry checks rather than using the server time. You may specify a list of time services during encoding.

GUI users: You may specify time services IP addresses or domain names in options dialogue. See Settings section for details.

Command line users: Use --time-server option to specify time servers. You may specify multiple servers IP addresses or domain names separated with "," or ";"

If you have used a time-server option then your script will *require* an internet connection to run. Time servers will be checked in the specified order. If no server from the list can be accessed an error message will be displayed and the script will stop execution:

It's a good idea to specify 2-3 time servers which will let your script to work even if some of the time servers will be temporary down.

If you have multiple scripts included from each other and some of them were encoded with a time-server option then the script will access the time server only once for the first script for better performance and will use the time value from the time-server for other included scripts.

You may also use the time-server option to lock your script to run only online. Use time-server option as usual for this but don't specify an expiration date for the script. The script will try to access the online time service and will fail if it's not possible.

sg_get_mac_addresses() function is defined in SourceGuardian loaders and is available within protected scripts. It may be useful for creating custom locking schemas etc. This function returns an array of hardware addresses for all network interfaces installed on the machine where the script is running.

Each mac addresses is returned as formatted string which includes 6-byte hardware address: XX:XX:XX:XX:XX:XX Up to 32 network hardware addresses may be returned.

* The @ (silent) operator is not used anymore before dl() in the protected script header. This lets us locate a problem easier if the SourceGuardian loader was successfully found by the protected script but it could not be loaded or if an error occurs during a dl() call.

You may exclude some files or directories from encoding when using the command line encoder. Use --exclude=mask option to specify file(s) and/or dir(s) to exclude from processing. You may specify either a strict name, relative path with a directory name or a mask (with ? and/or *).

UNIX users: Always quote masks under UNIX. Otherwise the shell will replace your mask with real file and dir names and the result may be unexpected. You should always quote masks that specifies files to encode too (like "*.php" in the example below).

This will encode all *.php files in the current directory and all directories recursively but all files in the "doc" directory and all files (and dirs if any!) named "config.php" will not be encoded.

You may enumerate all the files you want to exclude from encoding using a file list to specify multiple files. A file list is a text file with either full or relative file paths of all the files to encode, separated by a new line (masks are supported, use '*' and '?' for it). You should use an @ sign before the filelist name in the command line. Usage: -x @filelistname

Prepend header code option -p and Loader error code option -j may now load the source from a file. Use @filename as a parameter for -p or -j.

The code is loaded during encoding and stored as is *non encoded* as that code should be executable when no ixed loader is loaded yet.

A file list passed to the SourceGuardian encoder for batch processing from the command line may contain file masks now. Standard ? and * symbols are available.

* Added 'Off/Low/Normal/Max' title on compression level slider in options dialogue

* Fixed dialogue that asks if you wish to show warning about file missing in your project on loading it (Yes/No buttons were confused)

* New feature - SourceGuardian encoded scripts installers. Local server and remote server installers. See Installers section for details.