Phpshadow7.0 Userguide

USER GUIDE
Version 7.0
17 May 2014
2009 - 2014 Error 404 Ltd (Wellington, New Zealand)
Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)
Table of Contents
1 INTRODUCTION ................................................................................................................. 3
1.1
1.2
1.3
1.4
ABOUT THE PRODUCT .......................................................................................................... 3

BACKGROUND ...................................................................................................................... 3
WHATS INCLUDED .............................................................................................................. 3
WHAT ELSE IS NEEDED ........................................................................................................ 4
2 QUICK-START GUIDE ...................................................................................................... 5

2.1 PURPOSE ............................................................................................................................... 5
2.2 INSTRUCTIONS ...................................................................................................................... 5
3 OBTAINING PHPSHADOW .............................................................................................. 6
3.1 WHERE TO GET PHPSHADOW ............................................................................................... 6
4 INSTALLING PHPSHADOW ............................................................................................ 7
4.1 INSTALLING THE PHP SERVER EXTENSION ......................................................................... 7
4.2 INSTALLING THE ENCODER TOOL ...................................................................................... 10
4.3 INSTALLING THE LICENCE FILE (OPTIONAL) ..................................................................... 10
5 ENCRYPTING PHP SOURCE CODE ............................................................................. 11
5.1 ENCRYPTING SOURCE CODE USING THE ENCODER TOOL.................................................. 11
5.2 ENCRYPTING SOURCE CODE USING OUR CLOUD SERVICE ................................................ 13
6 ADVANCED FUNCTIONS ............................................................................................... 14
6.1 VIEWING PHPSHADOW INFORMATION ............................................................................... 14
7 BEST PRACTICE GUIDELINES..................................................................................... 15
7.1
7.2
7.3
7.4
7.5
TEST FIRST .......................................................................................................................... 15

HIDE ERROR MESSAGES ...................................................................................................... 15
KEEP SOURCE CODE OFF THE SERVER ................................................................................ 15
AVOID OVERWRITING WHEN ENCRYPTING ......................................................................... 15
AVOID UNNECESSARY INCLUSION OF THE DYNAMIC EXTENSION LOADER ........................ 16
8 WEB HOSTING .................................................................................................................. 17

8.1 VIRTUAL PRIVATE SERVER ................................................................................................ 17
8.2 SHARED HOSTING............................................................................................................... 17
10 SUPPORT .......................................................................................................................... 18
10.1 FREQUENTLY ASKED QUESTIONS ..................................................................................... 18
10.2 FREE EMAIL SUPPORT ....................................................................................................... 18
11 APPENDICES ................................................................................................................... 19
11.1
11.2
11.3
11.4
11.5
DETERMINING THE LOCATION OF THE EXTENSIONS DIRECTORY .................................... 19

DETERMINING THE LOCATION OF THE PHP.INI CONFIGURATION FILE ............................ 19
DETERMINING THE DOCUMENT ROOT PATH ................................................................... 19
TAKING A COPY OF THE PHP.INI CONFIGURATION FILE ................................................... 20
TAKING COPIES OF SYSTEM EXTENSIONS ........................................................................ 21
Page 2 of 21
Introduction
1.1
About The Product
PHPshadow is software that enables you to protect your PHP code by encrypting it in
such a way that it cannot be read by others, but that it still functions properly on a web
server. This is achieved by using a PHP server extension to decrypt the contents onthe-fly when a page is requested.
It is designed to work fast and to have a minimal impact on the server.
1.2
Background
Traditionally there were very few options available to PHP developers wishing to hide
their source code. One of the common approaches was to obfuscate the code. This is a
process whereby the code is made more difficult to read, using tricks like renaming
variables to nonsense names and using Base-64 encoding. Obfuscated code is a weak
protection mechanism because it is not encrypted and it can be easily reversed.
PHPshadow uses encryption to scramble the source code into an unreadable string of
characters. Now PHP developers need not worry about releasing their application to
customers, or publishing it on a shared hosting environment. PHPshadow aims to
provide a low-cost yet strong protection mechanism.
1.3
Whats Included
All items are available from the Download section of the PHPshadow website
(www.phpshadow.com).
!
PHP Server Extension

This is a PHP add-in module that is installed on the web server. This module
decrypts the code on-the-fly for PHP to run.
Encoder Tool
This is the command-line tool that encrypts your PHP scripts.
User Guide
The document you are reading now.
Page 3 of 21
1.4
What Else Is Needed
To encrypt your PHP code you will need to either:

!
Purchase a licence for the Encoder Tool, OR:
Encrypt your code using our cloud service.
Note: The Encoder Tool can be used without a licence (i.e. as a free trial), but a 10-second delay
will be introduced when your code is executed. It is otherwise fully functional.
Both options are available through Purchase section of the PHPshadow website
Page 4 of 21
Quick-Start Guide
2.1
Purpose
The purpose of the quick-start guide is for advanced users to install and begin using
the product as quickly as possible. Quick-start instructions are not detailed for this
very reason; however more detailed instructions are given in subsequent sections.
2.2
Instructions
Step 1:
Install the extension
Place a copy of phpshadow.so in the extensions directory on the web server.

Add the following line to the php.ini configuration file:
extension=phpshadow.so
Note: On a shared hosting platform you may not have enough file permissions to install the
extension in the manner described. In this case, refer to Installing the PHP Server
Extension on a Shared Hosting Platform on page 8.
Step 2:
Install the encoder tool
Place a copy of phpshadow-encoder in your home directory on your workstation.

Step 3:
Install the licence file
On your workstation place a copy of phpshadow.licence in either /etc/phpshadow or

your home directory.
Step 4:
Encrypt your code
Encrypt your code by issuing the following command:

./phpshadow-encoder -l path_to_licence_file path_to_project
Notes:
Replace path_to_licence_file with the correct path to the licence file.
Replace path_to_project with the correct path to your PHP project.
For a free trial, use the following syntax:
./phpshadow-encoder -t path_to_project
Step 5:
Publish your project
Copy your encrypted project to the appropriate directory on the web server.
Page 5 of 21
Obtaining PHPshadow
3.1
Where to get PHPshadow
The latest copy of PHPshadow (comprising the PHP Server Extension and the Encoder
Tool) can be downloaded from the Download section of the PHPshadow website
Page 6 of 21
Installing PHPshadow
4.1
Installing the PHP Server Extension
This section provides installation instructions for both types of server environments:
!
You have access to your own server, or you lease a virtual private server (VPS)
You are using a shared hosting platform
4.1.1
Installing the PHP Server Extension on Your Own Server or VPS
Follow these instructions if your web site is hosted on your own server, or on a virtual
private server.
Step 1:
!
Install the PHPshadow server extension
Place a copy of phpshadow.so in the extensions directory on the web server.

Note: If you are not sure of the location of the extensions directory, refer to Determining
the Location of the Extensions Directory on page 19.
Step 2:
!
Modify the php.ini file
Add the following line to the php.ini configuration file:

If you are not sure where to locate the php.ini configuration file, refer to Determining the
Location of the php.ini Configuration File on page 19.
Page 7 of 21
4.1.2
Installing the PHP Server Extension on a Shared Hosting Platform
Installation of the server extension on a shared hosting platform is considerably more

difficult because you do not have full access to the server. There are two options
available to you:
Option 1
Download the correct version of PHPshadow for the web server. Send the PHP Server
Extension (the file named phpshadow.so) to your hosting provider and ask them to
place it in the extensions directory.
If this method is not successful, try Option 2 below.
Option 2
Follow these instructions if you cannot try Option 1 or if it was unsuccessful.
Step 1:
Prepare a custom php.ini file
Note: It is assumed your hosting provider allows use of .htaccess. If you are not sure whether
this is the case, you can still attempt the installation below.
!
Create a file called .htaccess (note the leading dot) with the following content, and
upload it to the document root (the root directory of your web site):
SetEnv PHPRC " path"
Note: Replace path with the full path to the document root. If you are not sure of the path,
refer to Determining the Document Root Path on page 19.
For example:
SetEnv PHPRC "/home/john/www"
!
Take a copy the php.ini configuration file and copy it to the document root.
Note: If you are not sure how to take a copy of the php.ini file, refer to Taking a Copy of
the php.ini Configuration File on page 20.
Change the line in the php.ini file that enables the dl() function to:
enable_dl = On
Change the line in the php.ini file that defines the extension directory to:
extension_dir = " path"
Note: Replace path with the full path to the document root. Also, if the line begins with a
semi-colon make sure you remove it. The line should only contain what is shown above.
For example:
extension_dir = "/home/john/www"
!
Add the following line to the php.ini file:

Page 8 of 21
Step 2:
!
Copy system extensions
Take copies of all the system extensions and copy them into the document root.
Note: If you are not sure how to take copies of the system extensions, refer to Taking
Copies of System Extensions on page 21.
Step 3:
Install the PHPshadow server extension
Place a copy of phpshadow.so in the document root on the web server.
Set the permissions of phpshadow.so on the server to 755.

Note: The command for this in FTP is:
chmod phpshadow.so 755
Page 9 of 21
4.2
Installing the Encoder Tool
Place a copy of phpshadow-encoder in /usr/local/bin or any other convenient

location on your workstation.
4.3
Installing the Licence File (Optional)
If you are using the Encoder Tool to encrypt your files (as opposed to encryption
through our cloud service), you will first need to purchase a licence.
You will be sent a licence file called phpshadow.licence. Place this file in either
/etc/phpshadow or your home directory.
Page 10 of 21
Encrypting PHP Source Code
5.1
Encrypting Source Code using the Encoder Tool
5.1.1
Command line syntax
The syntax for the command line tool is a follows:

phpshadow-encoder [-d] [-f] [-l lpath] [-o] [-s filename] [-t] [-x extension] path
The parameters are described below:

-d
Using this parameter will leave out the dynamic extension loader (without this
parameter the dynamic extension loader will be included in the encrypted files).
If your web server already has PHPshadow installed (or if you have installed it
yourself), it is recommended that you use this parameter. If the web server does
not already have PHPshadow installed, or if you are not sure, then do not use this
parameter.
-f
Forces re-encryption of any files that have already been encrypted (without this
parameter files that are already encrypted are ignored).
-l lpath
Looks for the licence file in lpath instead of in /etc/phpshadow.
-o
Overwrites your original source files with the encrypted versions (without this
parameter the original files are first copied to a separate directory as a backup).
-s filename
Skips any files named filename. This directive can be used multiple times in the
one command.
-t
Use this flag if you want to take advantage of the free trial (no licence required).
Note that the free trial introduces a 10 second delay when you load the page.
-x extension
Encrypts files with names that end in .extension. By default only files with names
ending in .php will be encrypted. This directive can be used to add additional
extensions, such as .php3. Note that the dot should not be included (i.e. use -x
php3 and not -x .php3).
path
The full or relative path to either a directory or a PHP file. In the case of a
directory, the entire directory contents including any subdirectories will be
encoded. In the case of a PHP file, only that file will be encoded. This parameter
can be used multiple times in the one command.
Page 11 of 21
5.1.2
Example 1
This example is the simplest and most common way to encrypt your PHP project. To
encrypt a project located in /home/myproject and with the licence file located in
/home, the command would be:
phpshadow-encoder -l /home/phpshadow.licence /home/myproject
5.1.3
Example 2
The same example as above but with the licence file located in /etc/phpshadow you can
omit the l flag. The command would be:
phpshadow-encoder /home/myproject
5.1.4
Example 3
The same example as above but using the d flag to leave out the dynamic extension
loader. The command would be:
phpshadow-encoder -d /home/myproject
5.1.5
Example 4
The following example shows how to encrypt two projects at once:

phpshadow-encoder /home/myproject1 /home/myproject2
5.1.6
Example 5
You can choose to encrypt only part of your project. To encrypt only the files db.php
and priv.php located in /home/myproject, the command would be:
phpshadow-encoder /home/myproject/db.php /home/myproject/priv.php
Note that when encrypting only part of your project without the o parameter, copies
of the original (unencrypted) files and directories will kept in the same directory as the
encrypted files. You will probably want to move these before publishing your project.
5.1.7
Example 6
You can encrypt a project leaving a configuration file unencrypted. Assuming your
project is located in /home/myproject and the configuration file is config.php, you
would issue the following command:
phpshadow-encoder -s config.php /home/myproject
5.1.8
Example 7
You can encrypt a project saved with the file extension .php3. Assuming your project
is located in /home/myproject, you can encrypt it using the following command:
phpshadow-encoder -x php3 /home/myproject
Page 12 of 21
5.2
Encrypting Source Code using our Cloud Service
5.2.1
About the Cloud Encryption Service
The cloud encryption service is a mechanism to encrypt your PHP source code by
uploading your PHP files to the PHPshadow website. It does away with the need to
use the Encoder Tool.
All you need is a web browser.
This option is quick, easy, and the most cost effective. Whats more, you can try it
FREE of charge.
5.2.2
Instructions
Go to the PHPshadow website (www.phpshadow.com).

Click Cloud and follow the instructions on the screen.
Page 13 of 21
Advanced Functions
6.1
Viewing PHPshadow information
Create a new PHP file with the following contents:

<?php phpshadow_info(); ?>
Publish the file to the web server and view it through a web browser (i.e. navigate to its
URL).
It will show the version of PHPshadow and the release date of that version.
Page 14 of 21
Best Practice Guidelines
7.1
Test first
Before you encrypt your entire project and publish it, run a test with a few standalone
PHP scripts to make sure your server configuration is fine, and that PHPshadow is
compatible with your operating system and with your PHP installation.
7.2
Hide error messages
Many PHP configurations allow error messages to show inline on the page. On a
public website you should suppress error messages from displaying on the page and
instead redirect them to a log file, which you should service regularly.
You can do this by adding the following lines to your php.ini file (or amending them if
they already exist):
display_errors = Off
log_errors = On
error_log = "path_to_log_file"
(Replace path_to_log_file with the full path to the log file, e.g. /home/logs/php.txt)
Keep the following points in mind:
!
The log file should not be inside a directory from which web files are served.
The log file must be readable by the web server process.
The log file must be writable by the web server process.
7.3
Keep source code off the server
Never publish raw source code to the server. All your development files should
remain either on your workstation, or better still, on a file server on your internal
network.
When you are ready to publish, first encrypt the PHP files using the encoder tool, then
upload them to the web server.
7.4
Avoid overwriting when encrypting
Avoid using the o parameter with the Encoder Tool because you risk losing your
original source files if you have not saved a copy elsewhere beforehand.
Page 15 of 21
7.5
Avoid unnecessary inclusion of the dynamic extension loader
Use the d parameter with the Encoder Tool if the PHP server extension has been fully
installed on your web server.
Using this parameter will omit the dynamic extension loader from your encoded files,
resulting in slightly better performance.
Page 16 of 21
Web Hosting
8.1
Virtual Private Server
The best option is a virtual private server. You are given full access to the server (i.e.
root access) and therefore installation of software such as PHPshadow is much simpler.
This option is typically more expensive than shared hosting.
8.2
Shared Hosting
Shared hosting costs less than a virtual private server, but because you do not have full
access to the server the method of installing PHPshadow is more complex. Depending
on your hosting provider, it may not be possible to install PHPshadow.
PHPshadow is certified to work with all GlowHost shared hosting plans. Visit
http://www.glowhost.com for more information.
Page 17 of 21
10
Support
10.1
Frequently asked questions
We have published a list of frequently asked questions under the Support section of
the PHPshadow website.
10.2
Free email support
PHPshadow comes with free email-based support. See the Support section of the
PHPshadow website to contact us.
Page 18 of 21
11
Appendices
11.1
Determining the Location of the Extensions Directory
Upload the following PHP script to your web server and browse to its URL:
<?php
header('Content-type: text/plain');
echo ini_get('extension_dir');
?>
It will display the extensions directory.
11.2
Determining the Location of the php.ini Configuration File
<?php
echo php_ini_loaded_file();
?>
It will display the location of the php.ini file.
11.3
Determining the Document Root Path
<?php
echo $_SERVER['DOCUMENT_ROOT'];
?>
It will display the document root path.
Page 19 of 21
11.4
Taking a Copy of the php.ini Configuration File
<?php
if (isset($_REQUEST['submit'])) {
$header = 'Content-disposition: attachment; ';
$header .= 'filename="php.ini"';
header($header);
header('Content-Type: application/octet-stream');
echo file_get_contents(php_ini_loaded_file());
}
else {
echo '<form method="post">';
echo '<input name="submit" type="submit" ';
echo 'value="Download php.ini">';
echo '</form>';
}
?>
Click the button labelled Download php.ini . Once downloaded, you can upload the
php.ini file to your web servers document root.
Page 20 of 21
11.5
Taking Copies of System Extensions
<?php
if (isset($_REQUEST['filename'])) {
$header = 'Content-disposition: attachment; filename=';
$header .= '"'.urlencode($_REQUEST['filename']).'"';
header($header);
header('Content-Type: application/octet-stream');
$filename = ini_get('extension_dir');
$filename .= '/';
$filename .= $_REQUEST['filename'];
echo file_get_contents($filename);
} else {
if ($handle = opendir(ini_get('extension_dir'))) {
while (false !== ($filename = readdir($handle))) {
if ($filename != "." && $filename != "..") {
echo '<form method="post">';
echo '<input type="hidden" name="filename" ';
echo 'value="'.htmlspecialchars($filename).'">';
echo '<input type="submit" value="Download ';
echo htmlspecialchars($filename).'">';
echo '</form>';
}
}
closedir($handle);
}
}
?>
It will display a download button for each extension file. Once you have downloaded
all of the extension files, you can upload them to your web servers document root.
Page 21 of 21

Phpshadow7.0 Userguide

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Phpshadow7.0 Userguide

Încărcat de

Drepturi de autor:

Formate disponibile

USER GUIDE

2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

ABOUT THE PRODUCT .......................................................................................................... 3

2 QUICK-START GUIDE ...................................................................................................... 5

TEST FIRST .......................................................................................................................... 15

8 WEB HOSTING .................................................................................................................. 17

DETERMINING THE LOCATION OF THE EXTENSIONS DIRECTORY .................................... 19

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

About The Product

PHP Server Extension

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

What Else Is Needed

To encrypt your PHP code you will need to either:

Purchase a licence for the Encoder Tool, OR:

Encrypt your code using our cloud service.

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

Install the extension

Place a copy of phpshadow.so in the extensions directory on the web server.

Install the encoder tool

Place a copy of phpshadow-encoder in your home directory on your workstation.

Install the licence file

On your workstation place a copy of phpshadow.licence in either /etc/phpshadow or

Encrypt your code

Encrypt your code by issuing the following command:

Publish your project

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

Where to get PHPshadow

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

Installing the PHP Server Extension

You are using a shared hosting platform

Installing the PHP Server Extension on Your Own Server or VPS

Install the PHPshadow server extension

Place a copy of phpshadow.so in the extensions directory on the web server.

Modify the php.ini file

Add the following line to the php.ini configuration file:

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

Installing the PHP Server Extension on a Shared Hosting Platform

Installation of the server extension on a shared hosting platform is considerably more

Prepare a custom php.ini file

Add the following line to the php.ini file:

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

Copy system extensions

Install the PHPshadow server extension

Place a copy of phpshadow.so in the document root on the web server.

Set the permissions of phpshadow.so on the server to 755.

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

Installing the Encoder Tool

Place a copy of phpshadow-encoder in /usr/local/bin or any other convenient

Installing the Licence File (Optional)

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

Encrypting PHP Source Code

Encrypting Source Code using the Encoder Tool

Command line syntax

The syntax for the command line tool is a follows:

The parameters are described below:

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

The following example shows how to encrypt two projects at once:

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)

Encrypting Source Code using our Cloud Service

About the Cloud Encryption Service

Go to the PHPshadow website (www.phpshadow.com).

Copyright 2009 - 2014 Error 404 Ltd (Wellington, New Zealand)