===== SSL Proxy =====

==== General information ====

The Symbion SSL Proxy is a network server application. It listens on a TCP port, accepts SSL connections, and forwards them to an other (local or remote) TCP port, or UNIX domain socket. It is NOT a HTTPS server itself, but it can act as a HTTPS server, if you run an SSL Proxy server on port 443 which forwards the connections to port 80. SSL Proxy is tested with HTTP, but it should work with any SSL protocols, I think.

==== Security ====
SSL Proxy was developed with security in mind. When it allocated the server TCP port and loaded everything from the filesystem, it chroot()s to a (possibly empty) directory and changes the process's real and effective user id to a specified user.

==== Install ====
Make sure you have installed OpenSSL, than run make in the main directory. Copy ssl_proxy to anywhere you want :)

==== Key generation ====

SSL Proxy can not generate keys, use ssleay's req utility to do it:
<code sh>
mkdir /etc/symbion; cd /etc/symbion
openssl req -days 365 -nodes -new -x509 -out cert.pem -keyout key.pem
chmod go-rwx key.pem
</code>

==== Usage ====

SSL Proxy does not has a config file, it simply has some command line options.

=== General options: ===
<code>
        -h                      Usage information.
        -d                      Turn on debugging. SSL Proxy will not go into
                                the background and it will print a lot of
                                debug information to stderr.
        -f                      Do not detach from the terminal and run in the
                                forground. Useful if you want to run SSL Proxy
                                from Symbion Daemon Tool.
        -i                      Provide some info to the server about the
                                client (see below)
        -s [<server host>:]<server port>
                                Specify the port, which SSL Proxy will listen
                                on (or address to bind to a specific interface).
        -c [<client host>:]<client port>
                                Specify the TCP port, which SSL Proxy will
                                connect to as a client (The forwarding port).
        -c unix:<socket path>
                                Specify the UNIX domain socket, which SSL Proxy
                                will connect to as a client (The forwarding port
        -m <max connection>     SSL Proxy will accept maximum this number of
                                connections.
</code>
=== SSL options: ===
<code>
        -C <certificate file>   SSL Public Certificate file (see Key generation)
        -K <key file>           SSL Private Key File (see Key generation).
        -p <cipher list>        SSL cipher list
</code>
=== Security options: ===
<code>
        -u <user/uid>           Change real and effective UID to this after
                                initialization.
        -r <chroot dir>         Chroot to the specified directory after
                                initialization.
</code>
=== Buffer size options: ===
<code>
        -U <upward buffer>      The size of the buffer used for
                                client -> server data transfer.
        -D <downward buffer>    The size of the buffer used for
                                server -> client data transfer.
</code>

=== Defaults: ===
<code bash>
    # ssl_proxy -s 443 -c localhost:80 -m 32 -C /etc/symbion/cert.pem \
            -K /etc/symbion/key.pem -U 2048 -D 8192
</code>

==== Notes ====
SSL Proxy 1.0.0 introduced the ability to connect to UNIX domain sockets, not just TCP sockets. Please note that if you use UNIX domain sockets and you also use the -r (chroot) feature to make your system more secure, than the socket file must reside under the chrooted directory. The path specified in the -c option must be relative to the chrooted directory. Also note that if you use UNIX domain sockets with the -u (setuid) feature, then the user must have read and write permission to the socket file. The TCP sockets has no similar limitations, because they are not associated
with filesystem objects.

The file provided with the -v option can contain several CA certificates in PEM format. If you use the -V (certificate directory) option, then each file have to contain exactly ONE certificate. The files are looked up by the CA subject name hash value, which must be available. You can create symlinks with
the c_rehash utility, contained in the openssl package.

==== Client info feature ====
SSL Proxy can provide client information to the server in a special format.

This is a new feature in version 1.0.7, so I do not know of any server software that can use this information except my own special purpose software. If I receive information about any software available that uses this information, I will publicate it on our website, www.symbion.hu.

The usage is very simple. You provide the -i option to SSL Proxy. When a client connects, SSL Proxy connects to the server the usual way. But before the data sent by the client is forwarded to the server, SSL Proxy sends an information line to the server. This is an example of a HTTPS connection with the -i option:

<code>
szilu@maia:[~]$ nc -l -p 8080
#@ip=127.0.0.1 port=57223
GET / HTTP/1.1
Host: localhost:8443
User-Agent: Links (2.1pre37; Linux 2.6.27-11-eeepc i686; 80x24)
Accept: */*
Accept-Encoding: gzip, deflate
...
</code>

As you can see, an extra line beginning with '#@' is sent to the server. It contains the IP address and the TCP port of the client and optionally the common name (cn) of the client, if it has provided a certificate.

This information can be used for example for logging or access control purposes.

==== Examples ====
If you are running a HTTP server at port 80 which does not has SSL support, and you want it to work on SSL too, than defaults are good for you:
<code bash>
ssl_proxy
</code>

If you would like to use maximal security level, you can use:
<code bash>
mkdir /etc/symbion/chroot_dir
ssl_proxy -u nobody -r /etc/symbion/chroot_dir
</code>

==== How to report bugs ====
To report a bug, send mail to //sslproxy-users at lists dot sourceforge dot net//.
In the mail include:

  * The version
  * Information about your system. For instance:
    * What operating system and version
    * What version of OpenSSL
    * What version of the C library
  * Anything else you think is relevant.
    * How to reproduce the bug.
    * The text that was printed out (Debug information).

You can also use tha SourceForge bugtracking system at
    http://sourceforge.net/tracker/?group_id=21298

==== Patches ====
Patches can be sent to tha //sslproxy-users at lists dot sourceforge dot net// mailing list. Please include your name and email address.

If the patch fixes a bug, it is usually a good idea to include all the information described in "How to Report Bugs".