README
1General information
2===================
3
4The Symbion SSL Proxy is a network server application. It listens on a TCP
5port, accepts SSL connections, and forwards them to an other (local or remote)
6TCP port, or UNIX domain socket.
7It is NOT a HTTPS server itself, but it can act as a HTTPS server, if you run
8an SSL Proxy server on port 443 which forwards the connections to port 80.
9SSL Proxy is tested with HTTP, but it should work with any SSL protocols, I
10think.
11
12Security
13========
14SSL Proxy was developed with security in mind. When it allocated the server
15TCP port and loaded everything from the filesystem, it chroot()s to a
16(possibly empty) directory and changes the process's real and effective user
17id to a specified user.
18
19Install
20=======
21Make sure you have installed OpenSSL, than run make in the main directory.
22Copy ssl_proxy to anywhere you want :)
23
24Key generation
25==============
26SSL Proxy can not generate keys, use ssleay's req utility to do it:
27 # mkdir /etc/symbion; cd /etc/symbion
28 # ssleay req -nodes -new -x509 -out cert.pem -keyout key.pem
29 # chmod go-rwx key.pem
30
31Usage
32=====
33SSL Proxy does not has a config file, it simply has some command line
34options.
35 General options:
36 -h Usage information.
37 -d Turn on debugging. SSL Proxy will not go into
38 the background and it will print a lot of
39 debug information to stderr.
40 -f Do not detach from the terminal and run in the
41 forground. Useful if you want to run SSL Proxy
42 from Symbion Daemon Tool.
43 -s [<server host>:]<server port>
44 Specify the port, which SSL Proxy will listen
45 on (or address to bind to a specific interface).
46 -c [<client host>:]<client port>
47 Specify the TCP port, which SSL Proxy will
48 connect to as a client (The forwarding port).
49 -c unix:<client port>
50 Specify the UNIX domain socket, which SSL Proxy
51 will connect to as a client (The forwarding port).
52 -m <max connection> SSL Proxy will accept maximum this number of
53 connections.
54 SSL options:
55 -C <certificate file> SSL Public Certificate file (see Key generation).
56 -K <key file> SSL Private Key File (see Key generation).
57 Security options:
58 -u <user/uid> Change real and effective UID to this after
59 initialization.
60 -r <chroot dir> Chroot to the specified directory after
61 initialization.
62 Buffer size options:
63 -U <upward buffer> The size of the buffer used for
64 client -> server data transfer.
65 -D <downward buffer> The size of the buffer used for
66 server -> client data transfer.
67Defaults:
68 # ssl_proxy -s 443 -c localhost:80 -m 32 -C /etc/symbion/cert.pem \
69 -K /etc/symbion/key.pem -U 2048 -D 8192
70
71Notes
72=====
73SSL Proxy 1.0.0 introduced the ability to connect to UNIX domain sockets, not
74just TCP sockets. Please note that if you use UNIX domain sockets and you also
75use the -r (chroot) feature to make your system more secure, than the socket
76file must reside under the chrooted directory. The path specified in the -c
77option must be relative to the chrooted directory.
78Also note that if you use UNIX domain sockets with the -u (setuid) feature,
79then the user must have read and write permission to the socket file.
80The TCP sockets has no similar limitations, because they are not associated
81with filesystem objects.
82
83Examples
84========
85If you are running a HTTP server at port 80 which does not has SSL support,
86and you want it to work on SSL too, than defaults are good for you:
87 # ssl_proxy
88If you would like to use maximal security level, you can use:
89 # mkdir /etc/symbion/chroot_dir
90 # ssl_proxy -u nobody -r /etc/symbion/chroot_dir
91
92How to report bugs
93==================
94To report a bug, send mail to sslproxy-users@lists.sourceforge.net.
95In the mail include:
96
97* The version
98
99* Information about your system. For instance:
100
101 - What operating system and version
102 - What version of OpenSSL
103 - What version of the C library
104
105 And anything else you think is relevant.
106
107* How to reproduce the bug.
108
109* The text that was printed out (Debug information).
110
111You can also use tha SourceForge bugtracking system at
112 http://sourceforge.net/tracker/?group_id=21298
113
114Patches
115=======
116
117Patches can be sent to tha sslproxy-users@lists.sourceforge.net mailing list.
118Please include your name and email address.
119
120If the patch fixes a bug, it is usually a good idea to include
121all the information described in "How to Report Bugs".
122
123 Szilard Hajba <szilu@symbion.hu>
124