Documentation
Requirements
-
Windows, Linux or Mac OS X
-
Java Virtual Machine 6 or higher on client
-
Java Virtual Machine 6 or higher on gateway when you use the Java based gateway
-
PHP 5 when you use the PHP based gateway
Scottys is programmed in Java. On your local machine and the gateway you need a Java Virtual Machine. For the gateway we offer a java based application and a PHP based version. This works on
any WebHoster which supports PHP and allows web connections by using PHP.
Installation
You have three options for installing the gateway:
- Java based gateway: You can use the Java based gateway which works on any operating system supporting Java. You just have to start a jar file on the Java VM.
- PHP based gateway: For owners of a own webserver or hosting service you can upload a single PHP file. This PHP script acts as gateway.
- Google AppEngine based gateway: You can also use the free Google AppEngine. This executes the java gateway in the Google cloud.
Installation of the Java based gateway
The installation is very easy. Download our compiled scotty-gateway-standalone-0.9.2.jar file. You have to start the Scotty Gateway on your own server.
Execute the scotty-gateway-standalone-0.9.2.jar and set the port and other settings as parameter:
java -jar scotty-gateway-standalone-0.9.2.jar
Installation of the PHP based gateway
When you use the PHP based gateway then upload the gateway.php on your server (feel free to rename the file).
Ensure that the folder where the gateway.php script is located is writeable (chmod). Otherwise the gateway will be very very slow.
Installation of the Google AppEngine based gateway
You need a free Google AppEngine Account.
-
Download the Google AppEngine SDK for Java and install it.
-
Login into your Google AppEngine Account and create a new application by clicking the "Create Application" button.
-
Set an application identifier, set an application title and select "Open to all Google Accounts users (default)" and create application.
-
Download and unzip the scotty-gateway-gae-0.9.2.zip.
-
Insert in the WEB-INF/appengine-web.xml file the application identifier of your new Google AppEngine application:
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<application>your-application-identifier</application>
<version>2</version>
<threadsafe>true</threadsafe>
</appengine-web-app>
-
Now upload the scotty gateway by using the Google AppEngine SDK:
<appengine-sdk>\bin>appcfg update scotty-gateway-gae-0.9.2
(the third parameter scotty-gateway-gae-0.9.2 is the folder where you have unzipped the scotty-gateway-gae-0.9.2.zip).
In the following dialog you have to enter the email and password of your Google account.
Note: If you are using Google's two-factor authentication, you have to generate an application specific password for the appcfg script.
-
The URL of the gateway is http://your-application-identifier.appspot.com
Startup of scotty on your local computer
On your local computer inside the censored network you just have to start the local scotty proxy:
java -jar scotty-transporter-0.9.2.jar -p 8008 -g http://www.your-gateway-url.com:8008 -proxyHost proxy.yourcompany.de -proxyPort 8080
Example for PHP based usage (just another URL pointing to your PHP script):
java -jar scotty-transporter-0.9.2.jar -p 8008 -g http://www.your-gateway-url.com/gateway.php -proxyHost proxy.yourcompany.de -proxyPort 8080
After this two steps scotty is ready. Just set the proxy settings in your browser to localhost and the configured port (in this example 8008).
Configuration
Following configuration parameters are available for scotty proxy scotty-transporter-0.9.2.jar
| g |
The gateway url |
| p |
The local port where scotty listens for browsers requests |
| proxyHost |
The host of your current proxy (e.g. the proxy of your company) |
| proxyPort |
The port of your current proxy |
| c |
Create a new key pair for rsa encryption. The client and the server has a own rsa key pair. |
| privatekey |
The private key file of the client. Without this option scotty uses the default private key. |
| publickey |
The public key file of the client. Without this option scotty uses the default public key. |
| gatewayspublickey |
The public key file of the gateway. Without this option scotty uses the default gateway public key. |
| privatekeypassword |
The password for the private key (if one was set). |
Following configuration parameters are available for scotty gateway scotty-gateway-standalone-0.9.2.jar
| p |
The port of the gateway. |
| privatekey |
The private key file of the gateway. Without this option scotty uses the default private key. |
| publickey |
The public key file of the gateway. Without this option scotty uses the default public key. |
| clientspublickeys |
The file with all public keys of the allowed clients. Without this option scotty uses the default clients public keys. |
| privatekeypassword |
The password for the private key (if one was set). |
How to create own Key Pairs
You can generate easily your own keys. Otherwise you use the default keys which encrypts the data but people who know about scotty can decrypt your communication.
The gateway and the local proxy has their own key pairs. You have to generate a key pair (private and public key) for each one. Then the gateway has to know the
public key of the client and the client must know the public key of the gateway.
-
Generate KeyPair for your local proxy by using the command line parameter c:
#>java -jar scotty-transporter-0.9.2.jar -c
filename of private key: proxyprivatekey
filename of public key: proxypublickey
password for private key:
key pair successfully generated
private key successfully saved
public key successfully saved
private key successfully read
public key successfully read
-
Repeat this for the key pair of the gateway. For example we generate the keys c:\tmp\gatewayprivatekey and c:\tmp\gatewaypublickey for the gateway
the keys c:/tmp/proxyprivatekey and c:/tmp/proxypublickey for the scotty transporter proxy.
-
Java based gateway: Now start the gateway with the generated keys:
java -jar scotty-gateway-standalone-0.9.2.jar -privatekey c:/tmp/gatewayprivatekey -publickey c:/tmp/gatewaypublickey -clientspublickeys c:/tmp/proxypublickey -privatekeypassword yourpass
PHP based gateway: You have to insert your new generated keys in the gateway.php. Thats really easy. Open your generated key files and copy/paste them into the gateway.php:
...
// insert your public key between the ""
$publicKey = "<insert here your public key>";
// insert your private key between the ""
$privateKey = "<insert here your private key>";
// public keys of clients which are allowed to connect to this gateway
$clientPublicKeys = array(
"<insert here your scotty transporter public key>"
);
...
Google AppEngine gateway: Unzip the scotty-gateway-gae-0.9.2.zip file and replace the content of the
default keys in the WEB-INF/classes folder (clients, gw-defaultprivatekey, gw-defaultpublickey) with the content of your
own generated key files.
On PHP and Google AppEngine based gateways you can not use a password for the private key. On key generation you have to hit enter without any input
when scotty asks you for the private key password. This is not a security issue because the gateway server has to know the private key password in every
case to handle your requests.
-
In the censored network we start our local scotty transporter proxy with following options:
java -jar scotty-transporter-0.9.2.jar -g http://localhost:9000 -privatekey c:/tmp/proxyprivatekey -publickey c:/tmp/proxypublickey -gatewayspublickey c:/tmp/gatewaypublickey -privatekeypassword yourpass
