|
New features in SourceGuardian 7.0 |
Top Previous Next |
|
GUI changes
New features:
Engine and command line changes
Encoding of HTML templates and other non-PHP files
We have added an option for encoding HTML templates, or other non-PHP files, using the SourceGuardian encoder. HTML template or other non-PHP files may be encoded by the encoder and read and decrypted from the protected script itself. Within this document we will refer to these as "templates" for short, as there is no difference to the encoder between HTML templates, other templates or any other non-PHP files. Template files which are encoded as a part of a project may be used only from protected scripts which were encoded as a part of the same project. It's impossible to use protected templates from unencoded scripts or from scripts encoded with a different SourceGuardian project.
Internal project_id and project_key values are used for identifying the project and used as the encryption key for encoding templates. So please make sure to specify project_id (--projid option) with the command line encoder as well as project_key (--projkey option) for the project and external script license when generating the license with licgen tool. It's a good idea to specify the project_id for all your projects (unique for each) and additionally the project_key when an external license is used.
The SourceGuardian GUI interface generates a project_id and a project_key automatically for each new project. So you need to use only the same project for adding/changing encoded templates otherwise old templates cannot be used with newly encoded scripts and v.v. You may save your project_id and project_key values in a safe place for future use. The project_key value is also needed for correct license generation if you use it.
Encoded templates will look like this: SourceGuardianAAwAAAAFCgAAAAZ0jwEA/9QAMUp+g+GpvG3vbvYj4Is=
Command line interface.
Use the -t option to specify files, filemasks or filelist for template files.
Example 1: >encode5 -r -t"myproject/templates/*.tpl" "myproject/*"
You may specify multiple -t options if you need. All other files which are not specified as templates will be encoded as PHP scripts. If you use -f option (see below) to specify files to encode then files specified by -f options will be encoded as PHP scripts, files specified by -t options will be encoded as templates and all other files will not be encoded and will be copied into output directory as-is if it was specified by -o option.
You may use filelists for specifying template files and use filemasks as well as normal filenames in the list for it.
Example 2: if mytemplates contains: *.tpl *.html *.htm templates/mytemplate.txt
>encode5 -r -t @mytemplates -o output_dir source_dir This command will encode templates/mytemplate.txt, *.tpl, *.html and *.htm files in source_dir as tempates and will encode all other files in source_dir as PHP scripts.
Example 3: if additionally myphpfiles contains: *.php *.inc
>encode5 -r -t @mytemplates -f @myphpfiles -o output_dir source_dir This command will encode *.tpl, *.html and *.htm files in source_dir as temptemplatesphp and *.inc files as PHP scripts and will leave all other files from source_dir unencoded but copied into the output_dir. (see details below about new -f option)
Use of encoded templates from protected scripts.
An encoded template may be loaded from the protected script with the sg_load_file($filename) SourceGuardian API function. It returns the decoded file contents as a string result or generates an error.
$template_data = sg_load_file($filename);
sg_load_file() may generate following errors:
SourceGuardian Loader - template file is not found "filename" [21] (loader could not find specified template file)
SourceGuardian Loader - incompatible loader version when loading template file "filename" [22] Please download and install latest loaders (you are trying to load the template encoded with a newer version of the encoder but have an older loader installed)
SourceGuardian Loader - template file decryption error "filename" [23] (an error was detected at the decoding stage, possibly because the loading template was encoded for another SourceGuardian project - different project_id or project_key)
SourceGuardian Loader - template file loading error "filename" [24] (system error when loading the template file - insufficient memory, read error etc)
All errors are E_USER_ERROR and may be caught by custom error handler.
Using protected templates with the Smarty template engine
We have created an updated version of the Smarty template engine which can read encoded templates. This version is available from our site http://sourceguardian.com/scripts/Smarty-2.6.14-SG.tar.gz. The current version, as of writing this document, is 2.6.14 but it should be easy to update other versions too. Please read the details below about the changes we have done:
To enable loading of encoded *.tpl files the following simple changes are required:
Smarty.class.php
function _read_file($filename) { //SourceGuardian patch if ( function_exists("sg_load_file") ) { if ( file_exists($filename) ) { return sg_load_file($filename); } else { return false; } }
if ( file_exists($filename) && ($fd = @fopen($filename, 'rb')) ) { $contents = ''; while (!feof($fd)) { $contents .= fread($fd, 8192); } fclose($fd); return $contents; } else { return false; } }
To enable additional protection of precompiled template files the following additional changes are required:
In the file Smarty.class.php in function fetch() and function _smarty_include()
replace:
include($_smarty_compile_path);
with:
//SourceGuardian patch sg_eval(sg_load_file($_smarty_compile_path));
In the file internals/core.write_file.php in function smarty_core_write_file()
replace:
if (!($fd = @fopen($_tmp_file, 'wb'))) { $_tmp_file = $_dirname . DIRECTORY_SEPARATOR . uniqid('wrt'); if (!($fd = @fopen($_tmp_file, 'wb'))) { $smarty->trigger_error("problem writing temporary file '$_tmp_file'"); return false; } }
fwrite($fd, $params['contents']); fclose($fd);
with:
//SourceGuardian patch if ( function_exists("sg_encode_file") ) { sg_encode_file($_tmp_file, $params['contents']); } else { if (!($fd = @fopen($_tmp_file, 'wb'))) { $_tmp_file = $_dirname . DIRECTORY_SEPARATOR . uniqid('wrt'); if (!($fd = @fopen($_tmp_file, 'wb'))) { $smarty->trigger_error("problem writing temporary file '$_tmp_file'"); return false; } }
fwrite($fd, $params['contents']); fclose($fd); }
After all the changes are done the Smarty engine can work with normal unencoded templates when runs from an unprotected script and encoded templates when runs from the SourceGuardian protected script. It is not required to encode the Smarty engine itself - this is optional and does not affect the security of your protected scripts or templates.
Creating custom encoded files from protected scripts.
If your script generates files online and you need to secure them, it's now possible with SourceGuardian 7.0. Use sg_encode_file($filename, $data) SourceGuardian API function for creating the encoded file. This file will be encrypted in the same way as the SourceGuardian encoder encodes template files.
sg_encode_file($filename, $data);
Security note! The built-in SourceGuardian API encoder (sg_encode_file() API function) is suited only for encoding templates, data files and other non-PHP files. It does not perform compilation into bytecode and should not be used for securing source PHP scripts. Always use the SourceGuardian encoder for protecting PHP scripts as only bytecode compilation with encryption and compression can give maximum security for your PHP source scripts.
sg_encode_file() may generate the following error:
SourceGuardian Loader - error writing file "filename" [25] (loader failed to create an output file because of permissions, disk space etc problems)
This error is E_USER_ERROR and may be caught by custom error handler.
Files encoded using the sg_encode_file() SourceGuardian API function may be read by the sg_load_file() SourceGuardian API function described above. Files are encrypted using the current protected script's project identifier and key and so may be read only by the protected script encoded in the same SourceGuardian project.
If your protected script was encoded using advanced ip_encrypt or domain_encrypt options then the protected template file written by sg_encode_file() will be additionally encrypted using the current IP address (or domain name) as a key. This allows this protected template to be decrypted only on the machine with same IP (domain name).
Using encoding SourceGuardian API from unprotected script.
SourceGuardian API functions are part of the SourceGuardian loader and so are only available when the SourceGuardian loader is loaded into PHP. This may be done automatically by the run-time loader of the SourceGuardian protected script, or when the SourceGuardian loader is installed server-wide in php.ini and loaded when PHP starts.
sg_load_file() SourceGuardian API function will return the file's data as-is without decryption when: - it runs from unprotected script with loader installed server-wide (this is useful for debugging purposes, see below) - it loads the template or data file which was not encoded by SourceGuardian
sg_encode_file() SourceGuardian API function will write the file's data as-is without encryption: - when run from an unprotected script with the loader installed server-wide
Debugging of scripts which work with encoded templates.
Usually the SourceGuardian API function are not available until SourceGuardian is loaded by the protected script. The exception to this is when the SourceGuardian loader is installed server-wide in php.ini. It may be not obvious how to debug scripts using the SourceGuardian API because of this. For convenience and easy debugging we suggest two possible way for debugging scripts which use the SourceGuardian encoding API:
1) Install an appropriate SourceGuardian loader server-wide in php.ini as a PHP extension. Usually it's possible to do on development machine as normally PHP installation is over developer's control there. With using this way SourceGuardian API functions will be always available. When called from the unencoded source scripts sg_encode_file() and sg_load_file() functions are both work with unprotected data for reading and writing and so it's easy to debug and check content of the output file or loaded template file etc. When project debugging is finished and project is encoded, SourceGuardian API functions will start working in normal (protected) mode with reading and writing encoded templates/non-PHP files data.
2) Use our SourceGuardian API stub script sgapistub.php (http://sourceguardian.com/scripts/sgapistub.php) This is very simple PHP script which simulates sg_load_file() and sg_encode_file() functions without doing any encoding or decoding. When run from protected script and SourceGuardian API functions are available this script does nothing and lets real API functions to work. To use this stub script you need to include it from your script which uses SourceGuardian encoding API. When running from unprotected script, functions defined in this stub script will read and write templates or data files as-is which lets to debug the script and check content of the output file or loaded template file. When project debugging is finished and project is to be encoded with SourceGuardian you need to encode the stub script with all other PHP scripts in your project. When run from the protected script the stub file itself will do nothing as real SourceGuardian API functions will be used. This is done for convenience and you don't need to search your scripts and remove or comment the include operator which includes the stub script. Please read comments in the beginning of sgapistub.php script before using.
Please feel free to choose the better way for you for debugging your protected scripts. The second method does not require to have access to php.ini even in development environment.
Excluding files from encoding but still copying to output directory
We have added an option into the command line encoder to specify which files should be encoded (-f). You may specify what files will be encoded by filenames, filemasks or filelist. All other files which have been added for processing or found by expanding filemasks will be copied into the output directory "as-is" without encoding. If you don't specify the -f option then all specified files will be encoded by default.
Example 1: >encode5 -r -f "*.php" -o "output_dir" "*" All (with recursion) *.php files from the current directory will be encoded and copied into the output_dir. All other files from the current directory will be copied into output_dir as-is (unencoded).
You may specify multiple filenames or filemasks with using of multiple -f options:
Example 2: >encode5 -r -f "*.php" -f "includes/*.inc" -f @myphpfiles -o "output_dir" "*"
If you don't specify the output directory but use -f option then only files specified with -f option will be encoded. All other files will remain unchanged.
Encoding directory content without specifying filemasks
Now it's possible to use shorter syntax for directory encoding. All specified directories will be recognized and the "*" filemask will be added: >encode5 -r source_dir
instead of the following in previous versions: >encode5 -r "source_dir/*"
Fixed binding to a domain name
Problem with binding to a domain name was fixed when the pages are accessed with the port number specified.
Fixed directory recursion
There were some internal limits with directory recursion in the command line version in the previous version of our encoder. This has been fixed.
|