"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 General information
2 ===================
3
4 The Symbion SSL Proxy is a network server application. It listens on a TCP
5 port, accepts SSL connections, and forwards them to an other (local or remote)
6 TCP port, or UNIX domain socket.
7 It is NOT a HTTPS server itself, but it can act as a HTTPS server, if you run
8 an SSL Proxy server on port 443 which forwards the connections to port 80.
9 SSL Proxy is tested with HTTP, but it should work with any SSL protocols, I
10 think.
11
12 Security
13 ========
14 SSL Proxy was developed with security in mind. When it allocated the server
15 TCP 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
17 id to a specified user.
18
19 Install
20 =======
21 Make sure you have installed OpenSSL, than run make in the main directory.
22 Copy ssl_proxy to anywhere you want :)
23
24 Key generation
25 ==============
26 SSL Proxy can not generate keys, use ssleay's req utility to do it:
27 # mkdir /etc/symbion; cd /etc/symbion
28 # openssl req -days 365 -nodes -new -x509 -out cert.pem -keyout key.pem
29 # chmod go-rwx key.pem
30
31 Usage
32 =====
33 SSL Proxy does not has a config file, it simply has some command line
34 options.
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 -i Provide some info to the server about the
44 client (see below)
45 -s [<server host>:]<server port>
46 Specify the port, which SSL Proxy will listen
47 on (or address to bind to a specific interface).
48 -c [<client host>:]<client port>
49 Specify the TCP port, which SSL Proxy will
50 connect to as a client (The forwarding port).
51 -c unix:<socket path>
52 Specify the UNIX domain socket, which SSL Proxy
53 will connect to as a client (The forwarding port).
54 -m <max connection> SSL Proxy will accept maximum this number of
55 connections.
56 SSL options:
57 -C <certificate file> SSL Public Certificate file (see Key generation).
58 -K <key file> SSL Private Key File (see Key generation).
59 Security options:
60 -u <user/uid> Change real and effective UID to this after
61 initialization.
62 -r <chroot dir> Chroot to the specified directory after
63 initialization.
64 Buffer size options:
65 -U <upward buffer> The size of the buffer used for
66 client -> server data transfer.
67 -D <downward buffer> The size of the buffer used for
68 server -> client data transfer.
69 Defaults:
70 # ssl_proxy -s 443 -c localhost:80 -m 32 -C /etc/symbion/cert.pem \
71 -K /etc/symbion/key.pem -U 2048 -D 8192
72
73 Notes
74 =====
75 SSL Proxy 1.0.0 introduced the ability to connect to UNIX domain sockets, not
76 just TCP sockets. Please note that if you use UNIX domain sockets and you also
77 use the -r (chroot) feature to make your system more secure, than the socket
78 file must reside under the chrooted directory. The path specified in the -c
79 option must be relative to the chrooted directory.
80 Also note that if you use UNIX domain sockets with the -u (setuid) feature,
81 then the user must have read and write permission to the socket file.
82 The TCP sockets has no similar limitations, because they are not associated
83 with filesystem objects.
84
85 The file provided with the -v option can contain several CA certificates in
86 PEM format. If you use the -V (certificate directory) option, then each file
87 have to contain exactly ONE certificate. The files are looked up by the CA
88 subject name hash value, which must be available. You can create symlinks with
89 the c_rehash utility, contained in the openssl package.
90
91 Client info feature
92 ===================
93 SSL Proxy can provide client information to the server in a special format.
94
95 This is a new feature in version 1.0.7, so I do not know of any server software
96 that can use this information except my own special purpose software. If I
97 receive information about any software available that uses this information, I
98 will publicate it on our website, www.symbion.hu.
99
100 The usage is very simple. You provide the -i option to SSL Proxy. When a
101 client connects, SSL Proxy connects to the server the usual way. But before
102 the data sent by the client is forwarded to the server, SSL Proxy sends an
103 information line to the server. This is an example of a HTTPS connection with
104 the -i option:
105
106 -----8<-----
107 szilu@maia:[~]$ nc -l -p 8080
108 #@ip=127.0.0.1 port=57223
109 GET / HTTP/1.1
110 Host: localhost:8443
111 User-Agent: Links (2.1pre37; Linux 2.6.27-11-eeepc i686; 80x24)
112 Accept: */*
113 Accept-Encoding: gzip, deflate
114 ...
115 ----->8-----
116
117 As you can see, an extra line beginning with '#@' is sent to the server. It
118 contains the IP address and the TCP port of the client and optionally the
119 common name (cn) of the client, if it has provided a certificate.
120
121 This information can be used for example for logging or access control purposes.
122
123 Examples
124 ========
125 If you are running a HTTP server at port 80 which does not has SSL support,
126 and you want it to work on SSL too, than defaults are good for you:
127 # ssl_proxy
128 If you would like to use maximal security level, you can use:
129 # mkdir /etc/symbion/chroot_dir
130 # ssl_proxy -u nobody -r /etc/symbion/chroot_dir
131
132 How to report bugs
133 ==================
134 To report a bug, send mail to sslproxy-users@lists.sourceforge.net.
135 In the mail include:
136
137 * The version
138
139 * Information about your system. For instance:
140
141 - What operating system and version
142 - What version of OpenSSL
143 - What version of the C library
144
145 And anything else you think is relevant.
146
147 * How to reproduce the bug.
148
149 * The text that was printed out (Debug information).
150
151 You can also use tha SourceForge bugtracking system at
152 http://sourceforge.net/tracker/?group_id=21298
153
154 Patches
155 =======
156
157 Patches can be sent to tha sslproxy-users@lists.sourceforge.net mailing list.
158 Please include your name and email address.
159
160 If the patch fixes a bug, it is usually a good idea to include
161 all the information described in "How to Report Bugs".
162
163 Szilard Hajba <szilu@symbion.hu>