phproxy source code readme

_____________________________________________________________________

source code version 0.5b2 - january 20th 2007

latest version: http://www.sourceforge.net/projects/poxy/

copyright 2002-2007 abdullah arif

contact
_____________________________________________________________________

email: phproxy.support@gmail.com
website: http://whitefyre.com/

support and bug reports

_____________________________________________________________________

http://whitefyre.com/forums/
phproxy.support@gmail.com

table of contents
_____________________________________________________________________

1. license
2. what is phproxy?
3. how it works
4. requirements
5. installation
6. configurable script variables
7. available options
8. disclaimer
9. bugs and limitations
10. changelog, faq, todo, license, bugs, limitations
11. credits

1. license
_____________________________________________________________________

this source code is released under the gpl.

a copy of the license in provided in this package in the file
named license.txt

2. what is phproxy?
_____________________________________________________________________

phproxy is a web http proxy

designed to bypass proxy restrictions through
a web interface very similar to the popular cgiproxy
(http://www.jmarshall.com/tools/cgiproxy/). for example, in my
university, the it department blocks a lot of harmless websites
simply because of their popularity. so i use this porgram to access
those websites. the only thing that phproxy needs is a web server
with php installed (see requirements below).
be aware though, that the sever has to be able to access those
resources to deliver them to you.

3. how it works
_____________________________________________________________________

you simply supply a url to the form and click browse. the script then
accesses that url, and if it has any html contents, it modifies
any urls so that they point back to the script. of course, there is more
to it than this, but if you would like to know more in
detail, view the source code.
comments have yet to be added.

4. requirements
_____________________________________________________________________

- php version >= 4.2.0

- safe_mode turned off or at least having the fsockopen() function not disabled
- php version >= 4.3.0 and openssl for support for secure connections (https)
- zlib for output compression
- file_uploads turned on for http file uploads.

5. installation
_____________________________________________________________________

simply upload these files to a directory of your liking (prefrebly in its own
directory):

- index.php
- index.inc.php
- style.css

you can rename index.php without any problems, but not index.inc.php.

a good idea is to change these php settings in your php.ini file

or for instance apache's httpd.conf or per directory .htaccess files:

- register_globals = off (safer for your script)

- magic_quotes_gpc = off (avoids unnecessary, slow stripslashing in the script)
- always_populate_raw_post_data = off (no need for this extraneous data)
- zlib.output_compression = on (to enable output compression, better than doing it
inside the script)

your script will still function normally without these settings though.

all you need to do now is to access index.php and start browsing!

6. configurable script variables

_____________________________________________________________________

these variables are available at the beginning of the index.php file:

- $_config:
___________

url_var_name: name of the variable the contains the url

to be passed to the script. default: 'q'
flags_var_name: name of the variables the contains the flags
to be passed to the script. default: 'hl'
get_form_name: name of the get forms in case they were
passed through the proxy.
default: '____pgfa'
basic_auth_var_name: name of the variable when prompted for basic
authentication. default: '____pbavn'
max_file_size: maximum file size in bytes that can be
downloaded through the proxy.
use -1 for unlimited. default: -1
allow_hotlinking: whether to allow hotlinking or not.
default is not unless in $_hotlink_domains.
default:0
upon_hotlink: what to do if a website hotlinks through your
proxy. possible values:
- 1: show the url form (homepage)
- 2: issue a http 404 not found error
- any web address which the user will be
redirected to (e.g. goatse pic)
default: 1
compress_output: whether to use gzip compression or not.
this may or may not work depending on whether
your php installation has zlib loaded, and
whether the user's browser supports gzip
content encoding. turn this on if you're
worried about bandwidth. this might be a
bit taxing on your server if you have any kind of
substantial traffic. it is also better to enable
output compression through php.ini than here.
default: 0

- $_flags:
__________

this array contains the default values for the browsing options which
are explained in section 7.

- $_frozen_flags:
_________________

when a flag is frozen, it is no longer shown in the url forms, and the
user won't be able to change its value. a frozen flag will always
assume its value given in $_flags. this is useful for forcing
a specific url encoding, or forcing the mini url form to always be
there for instance.
0 is for not frozen. 1 is for frozen. default: all are unfrozen.

- $_labels:
___________
the labels on flags.

- $_hosts:
__________

each entry in this array is a seperate piece of regular expression

code that is matched against the host part of the currently browsed url.
if it evaluates to true, the user will not be allowed to access
that url.
the first default entry contains the regular expression for private
networks which are not supposed to be shown on the internet.

- $_hotlink_domains:
____________________

this array holds entries of domain names which are allowed to hotlink
through your proxy when allow_hotlinking is 0.

to allow "example.com" and "example2.com" to hotlink:

$_hotlink_domains = array('example.com', 'example2.com');

you don't need to include the "www" part as it is automatically

accounted for. your website's domain name is also automatically included
in this array.

- $_insert:
___________

this does nothing yet.

7. available options
_____________________________________________________________________

these options are available to you through the web interface.

you can also edit the default values in the $_flags in index.php
values can either be 1 (true) or 0 (false).

+-------------------------------------------------------------------+
| option | explanation |
+-------------------------------------------------------------------+
| include form | includes a mini url-form on every html page for |
| | easier browsing. |
| remove scripts | remove all sorts of client-side scripting |
| | (i.e. javascript). removal is not perfect. some |
| | scripts might slip by here and there. |
| accept cookies | accept http cookies |
| show images | show images. you might want to turn this off if |
| | you want to save your server's bandwith. |
| show referer | show referring website in http headers. this |
| | will show the base url for the website you're |
| | currently viewing. because many website disable |
| | hotlinking, this can be quite useful. |
| rotate13 | use rotate13 encoding on the url. * |
| base64 | use base64 encoding on the url. * |
| strip meta | strip meta html tags |
| strip title | strip website title |
| session cookies| store cookies for this current session only |
+-------------------------------------------------------------------+

* only one type of encoding will be used even if both are selected

8. disclaimer
_____________________________________________________________________

since this script basically bypasses restrictions that were imposed

on you, using it might be illegal in your country, school, office,
or whatever. even your host might not allow you to run it. use it at
your own risk. i will not be responsible for any damages done or any
harm that might result from using this script.

9. bugs and limitations

_____________________________________________________________________

php is retarded by nature, and as such, some problems arise that

would have not if this script were otherwise coded in another programming
language. the first example of this is dots in incoming variable names
from post and get. in a normal programming language, this wouldn't be
a problem as these variables could be accessed normally as they are
supplied, with dots included. in php, however, dots in get, post, and
cookie variable names are magically transformed into underscores
because of the stupid shit that is register_globals. things like yahoo!
mail which has dots in variable names will not work. there's no easy way
around this, but luckily, i have provided the solutions right here:

1. i've already taken care of cookies by manually transforming

the underscores manually into dots when needed.
2. for get variables, this shouldn't be a huge problem since the urls
are url-encoded into the url_var_name. the only time this should be
an issue is when a get form uses dots in input names, and this could
be recitified by using $_server['query_string'], and parsing that
variable. but this, luckily, doesn't happen too often.
3. as for post data, one solution is to use $http_raw_post_data. but then,
this variable might not be available in certain php configurations,
and it would need further parsing, and it still doesn't account
for uploaded files. this is extremely impractical and ugly.

the best thing you could do if you have enough control over your web server
and can compile custom builds of php is to delete a single line in a php source
code file called "php_variables.c" located in the "main" directory.
the function in question is called "php_register_variable_ex". i've only checked
this with php v4.4.4 and the exact line to delete is 117th line which basically
consists of this:

case '.':

now just compile and install php and everything should be fine. just make
sure that you have register_globals off or something might get messed up.
i've done this on my demo install on http://grab.cc/ and it's working
flawlessly.

another problem facing many web proxies is support for javascript.

currently, therse is no such thing in phproxy 0.5 but hopefully basic
support will be introduced for version 0.6. the best thing you could do
right now is to have the javascript disabled on your browsing options
as most sites degrade gracefully, such as gmail.

a third limitation for web proxies is content accessed from within proxied
flash and java applications and such. since the proxy script doesn't have access
to the source code of these applications, the links which they may decide
to stream or access will not be proxified. there's no easy solution for this
right now.

phproxy also doesn't support ftp. this may or may not be introduced
in future releases, but there are no current plans for ftp support.

10. changelog, todo, license

_____________________________________________________________________

refer to the accompanying files.

11. credits
_____________________________________________________________________

james marshall (http://www.jmarshall.com/) for his excellent cgiproxy

script which was a high inspiration and guide for me. the html
modification section is based off his script.

also massive thanks to everyone who emailed me or posted on forums bugs,

suggestions, and feedback. i really appreciate it.