git ssb - cel/sslh@c02e2d7aeeba25cb53d8a81acad55318ce63a4c4

📄	ChangeLog
📄	Makefile
📄	README
📄	README.MacOSX
📄	basic.cfg
📄	common.c
📄	common.h
📄	echosrv.c
📄	example.cfg
📄	probe.c
📄	probe.h
📁	scripts
📄	sslh-fork.c
📄	sslh-main.c
📄	sslh-select.c
📄	sslh.pod
📄	t
📄	t_load

README

1 ===== sslh -- A ssl/ssh multiplexer. =====
2 
3 Sslh accepts connections on specified ports, and forwards
4 them further based on tests performed on the first data
5 packet sent by the remote client.
6 
7 Probes for HTTP, SSL, SSH, OpenVPN, tinc, XMPP are
8 implemented, and any other protocol that can be tested using
9 a regular expression, can be recognised. A typical use case
10 is to allow serving several services on port 443 (e.g. to
11 connect to ssh from inside a corporate firewall, which
12 almost never block port 443) while still serving HTTPS on
13 that port. 
14 
15 Hence sslh acts as a protocol demultiplexer, or a
16 switchboard. Its name comes from its original function to
17 serve SSH and HTTPS on the same port.
18 
19 ==== Compile and install ====
20 
21 sslh uses libconfig (http://www.hyperrealm.com/libconfig/)
22 and libwrap.
23 
24 For Debian, these are contained in packages libwrap0-dev and
25 libconfig8-dev.  
26 
27 For OpenSUSE, these are contained in packages libconfig9 and
28 libconfig-dev in repository
29 http://download.opensuse.org/repositories/multimedia:/libs/openSUSE_12.1/
30 
31 For Fedora, this package should work:
32 https://admin.fedoraproject.org/pkgdb/acls/name/libconfig
33 (feedback from Fedorans appreciated).
34 
35 If you can't find libconfig, or just don't want a
36 configuration file, set 'USELIBCONFIG=' in the Makefile.
37 
38 After this, the Makefile should work:
39 
40 make install
41 
42 There are a couple of configuration options at the beginning
43 of the Makefile: 
44 
45     USELIBWRAP compiles support for host access control (see
46     hosts_access(3)), you will need libwrap headers and
47     library to compile (libwrap0-dev in Debian).
48 
49     USELIBCONFIG compiles support for the configuration
50     file. You will need libconfig headers to compile
51     (libconfig8-dev in Debian).
52 
53 The Makefile produces two different executables: sslh-fork
54 and sslh-select. 
55 
56 sslh-fork forks a new process for each incoming connection.
57 It is well-tested and very reliable, but incurs the overhead
58 of many processes.  sslh-select uses only one thread, which
59 monitors all connections at once. It is more recent and less
60 tested, but only incurs a 16 byte overhead per connection.
61 Also, if it stops, you'll lose all connections, which means
62 you can't upgrade it remotely.
63 
64 If you are going to use sslh for a "small" setup (less than
65 a dozen ssh connections and a low-traffic https server) then
66 sslh-fork is probably more suited for you. If you are going
67 to use sslh on a "medium" setup (a few thousand ssh
68 connections, and another few thousand ssl connections),
69 sslh-select will be better. If you have a very large site
70 (tens of thousands of connections), you'll need a vapourware
71 version that would use libevent or something like that.
72 
73 
74 To install:
75 
76 make
77 cp sslh-fork /usr/local/sbin/sslh
78 cp scripts/etc.default.sslh /etc/default/sslh
79 
80 For Debian:
81 cp scripts/etc.init.d.sslh /etc/init.d/sslh
82 For CentOS:
83 cp scripts/etc.rc.d.init.d.sslh /etc/rc.d/init.d/sslh
84 
85 and probably create links in /etc/rc<x>.d so that the server
86 start automatically at boot-up, e.g. under Debian:
87 update-rc.d sslh defaults
88 
89 
90 
91 ==== Configuration ====
92 
93 You can edit settings in /etc/default/sslh:
94 
95 LISTEN=ifname:443
96 SSH=localhost:22
97 SSL=localhost:443
98 
99 A good scheme is to use the external name of the machine in
100 $LISTEN, and bind httpd to localhost:443 (instead of all
101 binding to all interfaces): that way, https connections
102 coming from inside your network don't need to go through
103 sslh, and sslh is only there as a frontal for connections
104 coming from the internet.
105 
106 Note that 'external name' in this context refers to the
107 actual IP address of the machine as seen from your network,
108 i.e. that that is not 127.0.0.1 in the output of
109 ifconfig(8).
110 
111 ==== Libwrap support ====
112 
113 Sslh can optionnaly perform libwrap checks for the sshd
114 service: because the connection to sshd will be coming
115 locally from sslh, sshd cannot determine the IP of the
116 client.
117 
118 ==== OpenVPN support ====
119 
120 OpenVPN clients connecting to OpenVPN running with
121 -port-share reportedly take more than one second between
122 the time the TCP connexion is established and the time they
123 send the first data packet. This results in sslh with
124 default settings timing out and assuming an SSH connexion.
125 To support OpenVPN connexions reliably, it is necessary to
126 increase sslh's timeout to 5 seconds.
127 
128 Instead of using OpenVPN's port sharing, it is more reliable
129 to use sslh's -o option to get sslh to do the port sharing.
130 
131 ==== Using proxytunnel with sslh ====
132 
133 If you are connecting through a proxy that checks that the
134 outgoing connection really is SSL and rejects SSH, you can
135 encapsulate all your traffic in SSL using proxytunnel (this
136 should work with corkscrew as well). On the server side you
137 receive the traffic with stunnel to decapsulate SSL, then
138 pipe through sslh to switch HTTP on one side and SSL on the
139 other.
140 
141 In that case, you end up with something like this:
142 
143 ssh -> proxytunnel -e --------ssh/ssl------> stunnel ---ssh---> sslh --> sshd
144 
145 Web browser --------http/ssl------> stunnel ---http---> sslh --> http:80
146 
147 Configuration goes like this:
148 
149 On the server side, using stunnel3:
150 stunnel -f -p mycert.pem  -d thelonious:443 -l /usr/local/sbin/sslh -- sslh -i  --http localhost:80 --ssh localhost:22
151 
152 stunnel options: -f for foreground/debugging, -p specifies
153 the key + certificate, -d specifies which interface and port
154 we're listening to for incoming connexions, -l summons sslh
155 in inetd mode.
156 
157 sslh options: -i for inetd mode, --http to forward http
158 connexions to port 80, and SSH connexions to port 22.
159 
160 ==== capapbilities support ====
161 
162 On Linux (only?), you can use POSIX capabilities to reduce a
163 server's capabilities to the minimum it needs (see
164 capabilities(8).  For sslh, this is CAP_NET_ADMIN (to
165 perform transparent proxy-ing) and CAP_NET_BIND_SERVICE (to
166 bind to port 443 without being root).
167 
168 The simplest way to use capabilities is to give them to the
169 executable as root:
170 
171 # setcap cap_net_bind_service,cap_net_admin+pe sslh-select
172 
173 Then you can run sslh-select as an unpriviledged user, e.g.:
174 
175 $ sslh-select -p myname:443 --ssh localhost:22 --ssl localhost:443
176 
177 This has 2 advantages over starting as root with -u:
178 - You no longer start as root (duh)
179 - This enables transparent proxying.
180 
181 Caveat: CAP_NET_ADMIN does give sslh too many rights, e.g.
182 configuring the interface. If you're not going to use
183 transparent proxying, just don't use it.
184 
185 ==== Transparent proxy support ====
186 
187 On Linux (only?) you can use the --transparent option to
188 request transparent proying. This means services behind sslh
189 (Apache, sshd and so on) will see the external IP and ports
190 as if the external world connected directly to them. This
191 simplifies IP-based access control (or makes it possible at
192 all).
193 
194 sslh needs extended rights to perform this: you'll need to
195 give it cap_net_admin capabilities (see appropriate chapter)
196 or run it as root (but don't do that).
197 
198 The firewalling tables also need to be adjusted as follow
199 (example to connect to https on 4443 -- adapt to your needs
200 (I don't think it is possible to have httpd listen to 443 in
201 this scheme -- let me know if you manage that))):
202 
203 # iptables -t mangle -N SSLH
204 # iptables -t mangle -A  OUTPUT --protocol tcp --out-interface eth0 --sport 22 --jump SSLH
205 # iptables -t mangle -A OUTPUT --protocol tcp --out-interface eth0 --sport 4443 --jump SSLH
206 # iptables -t mangle -A SSLH --jump MARK --set-mark 0x1
207 # iptables -t mangle -A SSLH --jump ACCEPT
208 # ip rule add fwmark 0x1 lookup 100
209 # ip route add local 0.0.0.0/0 dev lo table 100
210 
211 This will only work if sslh does not use any loopback
212 addresses (no 127.0.0.1 or localhost), you'll need to use
213 explicit IP addresses (or names):
214 
215 sslh --listen 192.168.0.1:443 --ssh 192.168.0.1:22 --ssl 192.168.0.1:4443
216 
217 This will not work:
218 sslh --listen 192.168.0.1:443 --ssh 127.0.0.1:22 --ssl 127.0.0.1:4443
219 
220 ==== Comments? Questions? ====
221 
222 You can subscribe to the sslh mailing list here:
223 http://rutschle.net/cgi-bin/mailman/listinfo/sslh
224 
225 This mailing list should be used for discussion, feature
226 requests, and will be the prefered channel for
227 announcements.
228 
229

Built with git-ssb-web

1	===== sslh -- A ssl/ssh multiplexer. =====
2
3	Sslh accepts connections on specified ports, and forwards
4	them further based on tests performed on the first data
5	packet sent by the remote client.
6
7	Probes for HTTP, SSL, SSH, OpenVPN, tinc, XMPP are
8	implemented, and any other protocol that can be tested using
9	a regular expression, can be recognised. A typical use case
10	is to allow serving several services on port 443 (e.g. to
11	connect to ssh from inside a corporate firewall, which
12	almost never block port 443) while still serving HTTPS on
13	that port.
14
15	Hence sslh acts as a protocol demultiplexer, or a
16	switchboard. Its name comes from its original function to
17	serve SSH and HTTPS on the same port.
18
19	==== Compile and install ====
20
21	sslh uses libconfig (http://www.hyperrealm.com/libconfig/)
22	and libwrap.
23
24	For Debian, these are contained in packages libwrap0-dev and
25	libconfig8-dev.
26
27	For OpenSUSE, these are contained in packages libconfig9 and
28	libconfig-dev in repository
29	http://download.opensuse.org/repositories/multimedia:/libs/openSUSE_12.1/
30
31	For Fedora, this package should work:
32	https://admin.fedoraproject.org/pkgdb/acls/name/libconfig
33	(feedback from Fedorans appreciated).
34
35	If you can't find libconfig, or just don't want a
36	configuration file, set 'USELIBCONFIG=' in the Makefile.
37
38	After this, the Makefile should work:
39
40	make install
41
42	There are a couple of configuration options at the beginning
43	of the Makefile:
44
45	USELIBWRAP compiles support for host access control (see
46	hosts_access(3)), you will need libwrap headers and
47	library to compile (libwrap0-dev in Debian).
48
49	USELIBCONFIG compiles support for the configuration
50	file. You will need libconfig headers to compile
51	(libconfig8-dev in Debian).
52
53	The Makefile produces two different executables: sslh-fork
54	and sslh-select.
55
56	sslh-fork forks a new process for each incoming connection.
57	It is well-tested and very reliable, but incurs the overhead
58	of many processes. sslh-select uses only one thread, which
59	monitors all connections at once. It is more recent and less
60	tested, but only incurs a 16 byte overhead per connection.
61	Also, if it stops, you'll lose all connections, which means
62	you can't upgrade it remotely.
63
64	If you are going to use sslh for a "small" setup (less than
65	a dozen ssh connections and a low-traffic https server) then
66	sslh-fork is probably more suited for you. If you are going
67	to use sslh on a "medium" setup (a few thousand ssh
68	connections, and another few thousand ssl connections),
69	sslh-select will be better. If you have a very large site
70	(tens of thousands of connections), you'll need a vapourware
71	version that would use libevent or something like that.
72
73
74	To install:
75
76	make
77	cp sslh-fork /usr/local/sbin/sslh
78	cp scripts/etc.default.sslh /etc/default/sslh
79
80	For Debian:
81	cp scripts/etc.init.d.sslh /etc/init.d/sslh
82	For CentOS:
83	cp scripts/etc.rc.d.init.d.sslh /etc/rc.d/init.d/sslh
84
85	and probably create links in /etc/rc<x>.d so that the server
86	start automatically at boot-up, e.g. under Debian:
87	update-rc.d sslh defaults
88
89
90
91	==== Configuration ====
92
93	You can edit settings in /etc/default/sslh:
94
95	LISTEN=ifname:443
96	SSH=localhost:22
97	SSL=localhost:443
98
99	A good scheme is to use the external name of the machine in
100	$LISTEN, and bind httpd to localhost:443 (instead of all
101	binding to all interfaces): that way, https connections
102	coming from inside your network don't need to go through
103	sslh, and sslh is only there as a frontal for connections
104	coming from the internet.
105
106	Note that 'external name' in this context refers to the
107	actual IP address of the machine as seen from your network,
108	i.e. that that is not 127.0.0.1 in the output of
109	ifconfig(8).
110
111	==== Libwrap support ====
112
113	Sslh can optionnaly perform libwrap checks for the sshd
114	service: because the connection to sshd will be coming
115	locally from sslh, sshd cannot determine the IP of the
116	client.
117
118	==== OpenVPN support ====
119
120	OpenVPN clients connecting to OpenVPN running with
121	-port-share reportedly take more than one second between
122	the time the TCP connexion is established and the time they
123	send the first data packet. This results in sslh with
124	default settings timing out and assuming an SSH connexion.
125	To support OpenVPN connexions reliably, it is necessary to
126	increase sslh's timeout to 5 seconds.
127
128	Instead of using OpenVPN's port sharing, it is more reliable
129	to use sslh's -o option to get sslh to do the port sharing.
130
131	==== Using proxytunnel with sslh ====
132
133	If you are connecting through a proxy that checks that the
134	outgoing connection really is SSL and rejects SSH, you can
135	encapsulate all your traffic in SSL using proxytunnel (this
136	should work with corkscrew as well). On the server side you
137	receive the traffic with stunnel to decapsulate SSL, then
138	pipe through sslh to switch HTTP on one side and SSL on the
139	other.
140
141	In that case, you end up with something like this:
142
143	ssh -> proxytunnel -e --------ssh/ssl------> stunnel ---ssh---> sslh --> sshd
144
145	Web browser --------http/ssl------> stunnel ---http---> sslh --> http:80
146
147	Configuration goes like this:
148
149	On the server side, using stunnel3:
150	stunnel -f -p mycert.pem -d thelonious:443 -l /usr/local/sbin/sslh -- sslh -i --http localhost:80 --ssh localhost:22
151
152	stunnel options: -f for foreground/debugging, -p specifies
153	the key + certificate, -d specifies which interface and port
154	we're listening to for incoming connexions, -l summons sslh
155	in inetd mode.
156
157	sslh options: -i for inetd mode, --http to forward http
158	connexions to port 80, and SSH connexions to port 22.
159
160	==== capapbilities support ====
161
162	On Linux (only?), you can use POSIX capabilities to reduce a
163	server's capabilities to the minimum it needs (see
164	capabilities(8). For sslh, this is CAP_NET_ADMIN (to
165	perform transparent proxy-ing) and CAP_NET_BIND_SERVICE (to
166	bind to port 443 without being root).
167
168	The simplest way to use capabilities is to give them to the
169	executable as root:
170
171	# setcap cap_net_bind_service,cap_net_admin+pe sslh-select
172
173	Then you can run sslh-select as an unpriviledged user, e.g.:
174
175	$ sslh-select -p myname:443 --ssh localhost:22 --ssl localhost:443
176
177	This has 2 advantages over starting as root with -u:
178	- You no longer start as root (duh)
179	- This enables transparent proxying.
180
181	Caveat: CAP_NET_ADMIN does give sslh too many rights, e.g.
182	configuring the interface. If you're not going to use
183	transparent proxying, just don't use it.
184
185	==== Transparent proxy support ====
186
187	On Linux (only?) you can use the --transparent option to
188	request transparent proying. This means services behind sslh
189	(Apache, sshd and so on) will see the external IP and ports
190	as if the external world connected directly to them. This
191	simplifies IP-based access control (or makes it possible at
192	all).
193
194	sslh needs extended rights to perform this: you'll need to
195	give it cap_net_admin capabilities (see appropriate chapter)
196	or run it as root (but don't do that).
197
198	The firewalling tables also need to be adjusted as follow
199	(example to connect to https on 4443 -- adapt to your needs
200	(I don't think it is possible to have httpd listen to 443 in
201	this scheme -- let me know if you manage that))):
202
203	# iptables -t mangle -N SSLH
204	# iptables -t mangle -A OUTPUT --protocol tcp --out-interface eth0 --sport 22 --jump SSLH
205	# iptables -t mangle -A OUTPUT --protocol tcp --out-interface eth0 --sport 4443 --jump SSLH
206	# iptables -t mangle -A SSLH --jump MARK --set-mark 0x1
207	# iptables -t mangle -A SSLH --jump ACCEPT
208	# ip rule add fwmark 0x1 lookup 100
209	# ip route add local 0.0.0.0/0 dev lo table 100
210
211	This will only work if sslh does not use any loopback
212	addresses (no 127.0.0.1 or localhost), you'll need to use
213	explicit IP addresses (or names):
214
215	sslh --listen 192.168.0.1:443 --ssh 192.168.0.1:22 --ssl 192.168.0.1:4443
216
217	This will not work:
218	sslh --listen 192.168.0.1:443 --ssh 127.0.0.1:22 --ssl 127.0.0.1:4443
219
220	==== Comments? Questions? ====
221
222	You can subscribe to the sslh mailing list here:
223	http://rutschle.net/cgi-bin/mailman/listinfo/sslh
224
225	This mailing list should be used for discussion, feature
226	requests, and will be the prefered channel for
227	announcements.
228
229

cel / sslh