3 Zebedee --- a simple, free, secure TCP and UDP tunnel program
11 B<zebedee> B<-s> [B<-dDtu>] [B<-c> I<host>] [B<-f> I<file>] [B<-k>
12 I<keybits>] [B<-n> I<name>] [B<-o> I<logfile>] [B<-r> I<ports>]
13 [B<-T> I<port>] [B<-v> I<level>] [B<-x> I<config>] [B<-z> I<level>]
18 B<zebedee> [B<-dDlmtu>] [B<-e> I<command>] [B<-f> I<file>]
19 [B<-k> I<keybits>] [B<-n> I<name>] [B<-o> I<log>] [B<-T> I<port>] [B<-v>
20 I<level>] [B<-x> I<config>] [B<-z> I<level>] [server] [I<tunnel-spec> ...]
24 B<zebedee> B<-p> [B<-f> I<file>]
26 B<zebedee> B<-P> [B<-p>] [B<-f> I<file>]
28 =item Hash generation:
30 B<zebedee> B<-h> [I<file ...>]
32 B<zebedee> B<-H> I<string> ...
34 =item Windows Service:
36 B<zebedee> [B<-n> I<name>] B<-S> [install[=I<file>] | remove | run]
42 B<Zebedee> is a simple program to establish an encrypted, compressed "tunnel"
43 for TCP/IP or UDP traffic between two systems. This allows data from, for
44 example, B<telnet>, B<ftp> and B<X> sessions to be protected from snooping.
45 You can also use compression, either with or without data encryption, to gain
46 performance over low-bandwidth networks.
48 The main goals for B<Zebedee> are to:
54 Provide client and server functionality under both UNIX and Windows 95/98/NT.
58 Be easy to install, use and maintain with little or no configuration required.
62 Have a small footprint, low wire protocol overhead and give significant
63 traffic reduction by the use of compression.
67 Use only algorithms that are either unpatented or for which the patent has
72 Be entirely free for commercial or non-commercial use and distributed under
73 the term of the GNU General Public Licence (see L<CREDITS AND LEGALITIES>).
77 Of course, B<Zebedee> is by no means the first, or only secure tunnel program
78 available. It does not pretend to compete with the likes of B<ssh> or B<SSL>
79 in terms of breadth of function but if you want something quick, simple and
80 I<completely free> then it may be the tool for you.
82 This document describes the features of B<Zebedee> as at release 2.1.0.
84 =head2 What's in a name?
86 In case you were wondering, or even if you weren't, B<Zebedee> is named after
87 its three main components:
97 B<B>lowfish encryption and
101 B<D>iffie-Hellman key agreement.
109 To set up a secure connection between your local machine and a remote host you
110 need first to run B<Zebedee> in server mode on the remote system. The easiest
111 way to do this is to run B<Zebedee> with the B<-s> option. Like this:
115 If all goes well (and it should!) B<Zebedee> will detach from the terminal (or
116 console window under Windows) and run in the background. It will then be
117 listening for incoming requests from clients.
119 On your local machine you then run B<Zebedee> in client mode. You need to
120 specify the name of the remote machine and the name of the service or number
121 of the port to which the tunnel should be established --- we will call this
122 the "target" port. If the remote machine is called C<remhost> and you want to
123 set up a secure B<telnet> session then you would run:
125 zebedee remhost:telnet
127 In fact, if you don't specify a service or port the default is B<telnet> so
131 would do just as well in this instance. When you run this command it will
132 print out a message telling you the port number which is the local end of the
133 tunnel. B<Zebedee> will then detach from the terminal and run in the
134 background waiting for you to connect to the local port. If, for example, the
135 port number it printed out was 1234 then to connect to C<remhost> using the
136 secure tunnel you would run:
138 telnet localhost 1234
140 By default, B<Zebedee> will continue to listen for connections and tunnel
141 them, handling multiple simultaneous connections if necessary, until you
142 terminate the process.
144 Sometimes you will want to start B<Zebedee> and then run a command that
145 connects to the port straight away. You can do this in a single invocation of
146 B<Zebedee> as follows:
148 zebedee -e "telnet localhost %d" remhost
150 The "C<%d>" in the string is automatically replaced with the local port number
151 so there is no need for B<Zebedee> to print it out. If you specify a command
152 like this then the local B<Zebedee> client will exit once the command closes
155 You may want or need to control the local port number that the client uses.
156 This is necessary if the command whose connection you are trying to protect
157 expects to connect only to a specific port. In this case you can also specify
158 the local port number by invoking B<Zebedee> as follows:
160 zebedee clientport:hostname:targetport
162 So, for example, the command:
164 zebedee 8000:webhost:80
166 will allow you to secure all HTTP connections to B<webhost> if accessed via
167 port 8000 on the client system. See L<EXAMPLES> for more details.
169 You can also use a single B<Zebedee> client to handle multiple simultaneous
170 tunnels to different target ports on the same remote host. In this case the
171 client and target port specifications are lists of ports. For example:
173 zebedee 9001,9002,9003:somehost:daytime,telnet,ftp
175 This will tunnel traffic on the clientport 9001 to the B<daytime> port on the
176 remote target system, traffic on 9002 to the B<telnet> port and traffic on
177 9003 to the B<ftp> port.
179 This combination of client listening ports, target host and destination
180 ports is called a "tunnel speciification". See the
181 B<L<tunnel|/item_tunnel>> keyword for more details.
183 =head2 UDP Tunnelling
185 Originally B<Zebedee> was designed only to be able to handle TCP/IP traffic.
186 As of version 2.0.0 it can also handle connectionless UDP data. To enable
187 this start B<Zebedee> with the B<-u> option (or use the
188 B<L<udpmode|/item_udpmode>> keyword). For example:
192 on the server host and
194 zebedee -u 10000:somehost:echo
196 on the client. Note that a single client or server can only handle TCP or UDP
197 data, not both. If you need to tunnel both types of data you must run two
198 separate instances. It is safe run both a TCP-mode and a UDP-mode server on
199 the same system because they use different ports.
201 The tunnel between B<Zebedee> clients and servers still uses a TCP/IP
202 connection even in UDP-mode. This connection is timed out after a certain
203 period of inactivity. It must be re-established if more data arrives. For
204 this reason the performance in UDP mode may appear poor, depending on the
205 nature of the application using it. You should note that there is also a limit
206 on the size of UDP datagrams that can be handled.
208 For further details see the B<L<maxbufsize|/item_maxbufsize>>,
209 B<L<udpmode|/item_udpmode>> and B<L<udptimeout|/item_udptimeout>> keywords.
211 =head2 Some Terminology
213 Usually there will only be two systems involved when you set up a tunnel
214 using B<Zebedee>. You will run a client on one and communicate with it
215 via connections to local ports. On the other you will run a server which
216 will speak to services local to that machine. However, there can be up
217 to four different systems involved, as shown below:
219 [source] <===> [client] <=====> [server] <===> [target]
221 +- insecure | + insecure
222 connection | connection
225 The B<Zebedee> client runs on the "client" system and the server runs on the
226 "server" host. The inital connection that causes a tunnel to be established
227 between client and server originates from the "source" machine. This could be
228 a different system than where the B<Zebedee> client is running, although it is
229 usually the same. The server will ultimately communicate with the "target"
230 system. Again, this is usually the local machine but does not have to be.
232 Most of the time you will not have to be concerned with the distinction
233 between source and client and server and target. The terminology is, however,
234 reflected in a number of the keywords described in the following section so
235 you should bear it in mind when reading their descriptions.
237 In addition to the different systems involved in B<Zebedee> tunnel there are
238 also several different types of keys used to secure connection. The client and
239 server generate or are provided with B<private key> values. These are used to
240 calculate public values which are exchanged and used to derive a B<shared
241 secret key> using the Diffie-Hellman key agreement mechanism. From this
242 shared key a unique B<session key> is derived to secure an individual
243 connections between client and server.
245 =head2 Multiple Destinations
247 Prior to version 2.1.0 a single B<Zebedee> client/server pair could only
248 handle tunnels to a single target system. It is now possible, however,
249 to direct tunnels to multiple targets.
251 When a server is started it can be given a list of valid targets either
252 on the command-line or by using the B<L<target|/item_target>> keyword.
253 Each target is a host name optionally followed by a list of ports to
254 which connections may be made. Consider the following command run on a
255 machine called B<serverhost>:
257 zebedee -s target1:daytime,telnet target2:telnet target3
259 the server will allow connections to the B<daytime> and B<telnet> ports
260 on B<target1>, the B<telnet> port on B<target2> and any port on
263 Given this server invocation, a client may be started as follows:
265 zebedee serverhost 10000:target1:telnet 20000:target3:telnet
267 This will connect to the B<Zebedee> server on B<serverhost> and use it
268 to establish tunnels to the B<telnet> port on B<target1> via the client
269 port 10000 and tunnels to the B<telnet> port on B<target2> via 20000.
270 Note that the name of the host on which the server is running is given
271 as the first parameter. If the server name is omitted it is determined
272 from the first tunnel specification. So if the server had been running
273 on B<target3> then the above command could have been given as:
275 zebedee 20000:target3:telnet 10000:target1:telnet
277 In fact, a server also maintains a notion of a default target. This is the
278 host name of the I<last> target specified. In the example above the default
279 target becomes B<target3>. This is the target used when the server and target
280 names specified by the client are the same. Be careful of this because you
281 may get results that you not expect. For example, if the server was started
284 zebedee -s target2:telnet target3 target1:daytime,telnet
286 then the previous client invocation would result in connections to port
287 20000 being tunnelled to B<target1> and not B<target3>. This is because
288 when the server and target specified by the client are the same then the
289 traffic goes to the server's default target. To avoid confusion, if you
290 want to include the server host in a list of multiple destinations then
291 always name it last. Note that as well as a default target host it is also
292 possible to specify a list of default target ports where none are otherwise
293 given. See the B<L<redirect|/item_redirect>> keyword for more details.
295 As with the B<L<target|/item_target>> keyword for the server, the
296 equivalent of the command-line parameter for the client is the
297 B<L<tunnel|/item_tunnel>> keyword (and B<L<serverhost|/item_serverhost>>
298 in order to specify the server host explictly).
300 =head2 Server-Initiated Connections
302 In normal use a B<Zebedee> client inititates connections to the server when a
303 connection has been made to it from a source system. Sometimes, for example
304 when using B<Zebedee> through a restrictive firewall, it may be necessary for
305 the server to initiate the connection back to the client --- to operate in
306 "reverse." For details on how to do this see the
307 B<L<clienthost|/item_clienthost>> and B<L<listenmode|/item_listenmode>>
310 =head2 Configuration File
312 The behaviour of B<Zebedee> is probably best controlled through the use
313 of a configuration file. A configuration file can be specified using the B<-f>
314 command-line option. The file is read at the point at which the option is
315 encountered so later command-line options may override the contents of the
318 Lines are of the form:
320 keyword value # optional comment
322 The I<keyword> is a single, case-insensitive word. The value is either a single
323 word or a string. Strings are enclosed either in double quotes (C<"like
324 this">) or single quotes (C<'like this'>). Double quotes may appear in single
325 quoted strings and vice versa (C<"here's an example">). Case is preserved in
326 the values where appropriate.
328 Blank lines and lines beginning with a "C<#>" (after any leading whitespace)
329 are ignored. Long strings may be continued onto the next line by ending the
330 line with a "C<\>" character. This character is eliminated and the next line
331 is joined on to the end. Note that there is a limit of a total of 1024
332 characters on any line and its continuations. Line continuation happens before
333 anything else, including comment recognition so the lines:
336 # This comment continues on the next line \
339 will leave the value of B<server> as B<false>.
341 The keywords and their meanings are as described below. There is a brief
342 description of all the keywords in the L<Quick-Reference Summary>
343 section. Some, but not all, keywords have equivalent command-line
344 options. These are shown where available. There are also a few
345 command-line options that have no equivalent in the configuration file.
346 These are described at the end of this section.
348 If a keyword is described as being a boolean then its value must be one of the
349 words B<true> or B<false>.
351 Several keywords require a list of ports to be specfied. Where this the case
352 the value is string that consists of a comma or white-space delimited list of
353 port names, numbers or numeric ranges. For example "C<telnet, ftp 5900-5903>".
354 This is equivalent to the list "C<23,21,5900,5901,5902,5903>".
356 A number of the keywords are either only applicable to clients or only
357 applicable to servers. The same B<Zebedee> program runs as either client or
358 server and will silently ignore inappropriate options for the current type of
359 usage. The choice of client or server behaviour is controlled by the
360 B<L<server|/item_server>> keyword:
364 =item B<server> (command-line B<-s>)
366 This is a boolean indicating whether the program should run as a client or a
367 server. The default is to run as a client if this keyword is not specified. The
368 command-line B<-s> option is equivalent to setting this keyword to B<true>.
372 =head3 Client-Only Keywords
374 The following keywords apply only to B<Zebedee> clients:
378 =item B<command> (command-line B<-e>)
380 When running as a client, this is a command that will be spawned to run
381 connected to the tunnel. If the value contains the character sequence "C<%d>"
382 this will be replaced at run-time with the local port number (see the
383 B<L<tunnel|/item_tunnel>> keyword). As this is done using B<sprintf>
384 the conventions of that routine apply with regards to escaping "C<%>"
385 characters (i.e. use "C<%%>" to generate a single "C<%>"). In addition,
386 specifying more that one "C<%d>" or other format sequence will very likely
389 Once the command closes its connection B<Zebedee> will exit. Using this
390 keyword or option implicitly turns off multi-use mode (see
391 B<L<multiuse|/item_multiuse>>). You can not use automatic command spawning
392 when a single B<Zebedee> client is handling multiple connections in
393 B<L<multiuse|/item_multiuse>> mode or when a list of ports has been specified
394 with the B<L<tunnel|/item_tunnel>> keyword or on the command-line.
396 =item B<listenmode> (command-line B<-l>)
398 In normal use a B<Zebedee> client inititates connections to the server when a
399 connection has been made to it from a source system. Sometimes, for example
400 when using B<Zebedee> through a restrictive firewall, it may be necessary for
401 the server to initiate the connection with a client --- to operate in
404 The B<listenmode> keyword, if true, causes a B<Zebedee> client to listen for
405 connections initiated by the server rather than to connect directly. A
406 connection from a server will not be accepted until a matching connection from
407 the source system has been made. However, server connections could originate
408 from arbitrary addresses when giving the client no control over the
409 destination of the tunnel. To avoid this the client will validate that the
410 address of the server's connection matches that specified, whether on the
411 command-line, via the B<L<serverhost|/item_serverhost>> keyword or as part of
412 the first tunnel specification.
414 As a special case, if the server name is "C<*>" then connections will be
415 accepted from any server address. Use of the L<identity checking|Identity
416 Checking> features is also recommended to ensure that the correct server
419 If a connection from a server is not received within a certain period
420 then the connection back to the source system will be closed and the
421 process abandoned. This timeout is controlled by the
422 B<L<connecttimeout|/item_connecttimeout>> keyword. The default is 300
425 See the B<L<clienthost|/item_clienthost>> keyword for the description of the
426 server side of this process.
430 If this value is B<true> then the client will only accept connections
431 originating from the local machine. In other words the "source" system must be
432 the same as the "client" system.
434 The default is for this value to be B<false> and for connections to be allowed
435 from any arbitrary source machine.
437 =item B<multiuse> (command-line B<-m>)
439 If this value is B<true>, which is the default, then the B<Zebedee> client will
440 handle multiple (potentially simultaneous) connection requests and will
441 establish a new tunnel to the server for each one. If it is false, the client
442 runs in "single-use" mode and exits after the first connection to the server
445 The command-line B<-m> option is equivalent to setting this to B<true>. This
446 is the default behaviour in the current version of B<Zebedee> and the option
447 is retained only for backwards-compatibility reasons.
449 Any client listening on multiple ports will automatically run in "multi-use"
450 mode, even if this is set B<false> (see B<L<clientport|/item_clientport>>).
454 This is the name of the host on which a B<Zebedee> server is running and to
455 which a tunnel is to be connected. There is no default and a host name must
456 be specified either in a configuration file or on the command line.
458 See the B<L<listenmode|/item_listenmode>> keyword for the treatment of this
459 value when using server-initiated connections.
461 Prior to version 2.0.0 this was known as the B<remotehost> keyword. This
462 is still recognised for backwards compatibility.
466 This is a string that consists of three parts separated by colons, for
469 10000-10002:targethost:echo,telnet,daytime
471 The first part is the list of ports on which the B<Zebedee> client will listen
472 for connections. The second part is the name of the target host to which the
473 tunnelled data should be directed. The final part is the list of target ports
474 that correspond to the ports on which the client is listening. The numbers of
475 entries in the client and target port lists must match.
477 As a special case, if only a single tunnel specification is given with only a
478 single target port then the client port list (and separating colon) may be
479 omitted. The client port will be assigned automatically (and a message will be
480 printed to the terminal giving the port number). This is to allow for
481 backwards compatibility and for use with the B<L<command|/item_command>>
482 keyword. If the target port is also omitted then it will default to B<telnet>
485 As described in the section L<Multiple Destinations> if the B<Zebedee> server
486 host is not explicitly specified, either as the first argument on the
487 command-line or via the B<L<serverhost|/item_serverhost>> keyword, then it
488 will be taken from the first tunnel specification found.
490 There is also one final variant of the tunnel specification. In this case the
491 targethost is replaced by a "C<*>". This wild-card form is used either with
492 the client running in "listen-mode" (see B<l<listenmode|/item_listenmode>> for
493 further details) or when you want to specify tunnelling to the server's
494 default target, whatever it may be. This latter form is useful in a
495 configuration file when you want the file to be generically applicable to any
496 server. For example, a file like this:
499 tunnel 10000:*:daytime
501 tunnel 30000:*:telnet
503 can be used to set up tunnels on ports 10000, 20000 and 30000 to whatever host
504 may be specified on the command-line like this:
506 zebedee -f configfile serverhost
510 =head3 Server-Only Keywords
512 The following keywords apply only when running as a server:
516 =item B<clienthost> (command-line B<-c>)
518 If a B<clienthost> value is specified then the server will
519 immediately attempt to connect to the specified host (on the port given by
520 B<L<serverport|/item_serverport>>). There must already be a client running in
521 "listen-mode" (see B<L<listenmode|/item_listenmode>>) at that address.
522 Once a connection to the client has been established the protocol exchanges
525 Each time a connection has been accepted by the client the server
526 tentatively opens up another one so that the client could establish
527 further tunnels if necessary. If the connection is not accepted within a
528 certain period then it will be closed and the server will exit once all
529 currently active tunnels have been closed. The timeout is controlled by
530 the B<L<connecttimeout|/item_connecttimeout>> keyword. The default is
533 Note that B<Zebedee> does not itself provide a mechanism for co-ordinating the
534 starting of client and server to set up a "reverse" tunnel. That must be
535 handled by some "out-of-band" mechanism.
537 =item B<redirect> (command-line B<-r>)
539 This is a list of the ports on the target system to which the server will
540 accept requests to redirect data. For example "C<telnet, ftp, 5900-5910>".
541 If no B<redirect> keyword is specified then requests to redirect traffic to
542 any port will be accepted. While this is convenient for testing it may pose a
543 security risk so you should specify an explict list of allowed ports if at all
546 The keyword (or B<-r> option) may be specified multiple times in which case
547 redirection will be allowed to any of the ports specified.
551 =head3 Compression and Encryption Keywords
553 The following keywords control the compression and encryption of data passing
554 through the tunnel. They apply to both clients and servers:
558 =item B<compression> (command-line B<-z>)
560 B<Zebedee> can support both B<zlib> and, if enabled when it is built, B<bzip2>
561 compression. This keyword specifies the type and level of compression to be
562 used. The value is of the form I<type:level> where I<type> is either "C<zlib>"
563 or "C<bzip2>" and I<level> is an integer from 0 to 9. As a special case an
564 integer without any prefix implicitly selects a B<zlib> compression level.
566 The level specifies the maximum compression level to used (9 is the maximum
567 and 0 is no compression). The actual compression level used will be the
568 minimum of the client's and server's values. For these purposes all B<bzip2>
569 levels (except 0) are considered to be greater than all B<zlib> levels so if
570 either client or server does not support B<bzip2> the protocol degrades
571 gracefully to using B<zlib>. The default compression value is "C<zlib:6>".
573 Note that, because of the way that B<bzip2> compression works and the buffer
574 sizes that B<Zebedee> uses, B<bzip> will probably only be useful if continuous
575 streams of data are flowing. On smaller transfers, such as those in a normal
576 B<telnet> session, B<zlib> will usually win. You will have to experiment to
577 see what works best for you. In addition, because the buffer size is small
578 there is no gain from using B<bzip2> levels above 1 and B<Zebedee> will round
579 any higher values down to this level.
581 You can see exactly how much compression is gaining you at verbosity levels 2
582 and above when basic statistics are printed out on connection termination. For
585 zebedee(232/210): read 166 bytes (265 expanded) in 3 messages
586 zebedee(232/210): wrote 20969 bytes (30499 expanded) in 247 messages
590 This is the "generator" for the Diffie-Hellman key exchange and is a
591 hexadecimal string. The default value is "2". I recommend that you don't mess
592 with this unless you know what you are doing.
594 =item B<keygencommand>
596 If this key is specified its value is a command string that will be executed
597 in order to generate a private key. The command should write a single line of
598 hexadecimal digits to F<stdout>. This line must be a string of at least 10
603 This is an integer between 0 and 2 inclusive that determines how strong the
604 private key generation in B<Zebedee> should be. The default is 2 (the
605 strongest) and you should generally not change this unless connection set-up
606 performance becomes unacceptable.
608 Briefly, on UNIX-like systems the level-2 key generation mechanism uses
609 C</dev/urandom> or C</dev/random>, if either of these devices is available, to
610 obtain good pseudo-random data based on the state of the running kernel. If no
611 random-data device is available or the level is set to 1 then data from the
612 current contents of the C</proc> file-system, if there is one, will be used
613 otherwise at level 0 only data from the current process will be used.
615 On Windows systems there is currently no distinction between different key
616 generation strength levels and this keyword is effectively ignored.
618 =item B<keylength> (command-line B<-k>)
620 This is an integer specifying the maximum key length (in bits) for the
621 Blowfish encryption. It should be a multiple of 4 between 4 and 576.
622 The key length used will be the minimum of the client's and server's
623 values (subject to any setting of B<L<minkeylength|/item_minkeylength>>).
625 The default valuse is 128. As a special case setting this value to 0 will turn
626 off key negotiation and encryption.
630 If the value of this parameter is non-zero it causes the client to request the
631 re-use of a previously established shared secret key for deriving session keys
632 for subsequent connections. This means that on the first connection between a
633 B<Zebedee> client and server the full key exchange dialogue will take place to
634 establish a shared secret key. On subsequent connections, until the key
635 expires, the same secret key will be reused to generate a new session key.
636 Once the key expires a new key exchange will automatically be performed when
639 This keyword specifies how long a shared secret key is valid
640 before it must be renegotiated. This does not affect connections that have
641 already been established, only new connections.
643 The value is in seconds and must be less than or equal to 65535, which is a
644 little over 18 hours. By default it is set to 3600 seconds (one hour). Setting
645 this value to zero effectively disables the use of reusable keys and a full
646 negotiation of a shared key will be performed for each connection --- assuming
647 that both client and server also generate a new private key each time. This
648 will impact performance and is recommended only if you have a very high
651 =item B<minkeylength>
653 If supplied this specified the minimum acceptable key length to be used by
654 client or server. If a client requests a lower level of a server the server
655 will reply with this minimum. If a server replies with a lower level to a
656 client then the client will terminate the connection.
658 The default value is zero.
662 The value of this key is a hexadecimal string specifying the modulus value for
663 the Diffie-Hellman key exchange. Don't alter this unless you are both paranoid
664 and know what you are doing.
666 The default modulus is the 1024-bit prime:
668 f488fd584e49dbcd 20b49de49107366b 336c380d451d0f7c 88b31c7c5b2d8ef6
669 f3c923c043f0a55b 188d8ebb558cb85d 38d334fd7c175743 a31d186cde33212c
670 b52aff3ce1b12940 18118d7c84a70a72 d686c40319c80729 7aca950cd9969fab
671 d00a509b0246d308 3d66a45d419f9c7c bd894b221926baab a25ec355e92f78c7
673 This was taken from the file F<testdh.h> in Peter Gutman's B<CryptLib>. The
674 comment in this code says that the value was among those "generated by Colin
675 Plumb for SKIP". It further says that "these values were chosen as
676 representative well-known public values to allay fears of possible trapdoors
677 in self-generated values. The generation method and actual values can be
678 checked against the SKIP standards document."
682 By default B<Zebedee> will generate a new private key each time one is
683 required. If, however, you wish to use a fixed key then it can be specified
684 as a string of hexadecimal digits. You will definitely need to do this if you
685 wish to use the L<identity checking|Identity Checking> feature. Note that the
686 key must be at least 10 digits long.
690 =head3 Miscellaneous Keywords
692 The following keywords apply equally to clients and servers:
698 This names a file that contains a set of identities that will be checked
699 before allowing a connection to be completed. This is described further in the
700 description of L<identity checking|Identity Checking>. You may specify
701 only one identity file. If this keyword appears multiple times only the
702 last value will be used.
704 If a B<L<keylength|/item_keylength>> of zero
705 has been agreed then no identity checking will be performed.
707 =item B<connecttimeout>
709 When B<Zebedee> is used in "reverse-mode" (see
710 B<L<listenmode|/item_listenmode>> and B<L<clienthost|/item_clienthost>>)
711 the timeout on waiting for connections to be accepted is controlled by
712 this keyword. Its value is in seconds and may be no greater than 65535.
713 The default is 300 seconds.
715 =item B<debug> (command-line B<-D>)
717 This is a boolean indicating that B<Zebedee> should run in "debug" mode. In
718 this case a server (or client running in B<L<multiuse|/item_multiuse>> mode)
719 only accepts and handles a single connection at a time and does so "inline"
720 without creating another process or thread. This is useful when running the
721 program under the control of a debugger. It is false by default. The
722 command-line option B<-D> is equivalent to setting this to B<true>.
724 Note that this setting will not work correctly in UDP mode, so don't bother
727 =item B<detached> (command-line B<-d>)
729 This is a boolean indicating whether the process should detach itself from the
730 controlling terminal and run in the background (in UNIX terms, to run as a
731 "daemon"). This is valid for both client and server and is true by default.
732 The command-line option B<-d> is equivalent to setting this to B<false>.
734 Note that this does not always seem to work from an interactive command prompt
735 under Windows systems. The symptom is that output to the console window will
736 stop and interrupt signals will be ignored but the console prompt will not be
737 issued until B<Zebedee> terminates. In order to work around this you can use
738 the "start" command as in the following example:
740 DOS> start zebedee -f server.zbd
742 This will start B<Zebedee> in a new console session from which it will then
743 detach. You may see a console window appear briefly before it detaches but
744 B<Zebedee> should be running in the background when it disappears.
746 =item B<include> (command-line B<-f>)
748 This specifies the name of another configuration file to read and parse at
749 this point before continuing with the remainder of the file. It might be used,
750 for example, where a private key is stored in a separate, more tightly
751 protected file. There is a limit of 5 levels deep of include processing
752 (counting the initial configuration file as level 1). This avoids
753 unintentional recursion.
757 This specifies the size, in bytes, of the buffer B<Zebedee> will use to read
758 data from applications. The actual size of buffer used will be the minimum of
759 the client's and server's values.
761 By default B<Zebedee> attempts to read data from the client or server programs
762 at each end of the tunnel in chunks of 8192 bytes. There may be occasions when
763 you want to decrease this if, for example, you have a highly interactive
764 application and the response seems sluggish because you end up waiting for
765 large data transfers. You can reduce the buffer size to one byte, but unless
766 you are trying to debug misbehaviour or have time to waste I don't recommend
767 it! Conversely, you may increase the buffer size up to a maximum of 16383
768 bytes to attempt to gain the most from data compression where large blocks of
769 data are being transferred. Note that the B<maxbufsize> value does not affect
770 how much memory is allocated by B<Zebedee>, only the size of data chunks read.
772 When running in UDP mode this buffer size will also affect the maximum size of
773 any datagram that can be handled. Datagrams larger than the current buffer
774 size will be fragmented, which will likely cause whatever application is
775 consuming them to fail. Datagrams larger than 16383 bytes can not be handled
780 The specifies a string that will be logged at verbosity level 1 when it is
781 encountered in the configuration file.
783 =item B<name> (command-line B<-n>)
785 This is the name of the program that is to be used in messages rather than the
786 executable file name. Under Windows it is also the name of any service to be
787 installed or removed.
789 =item B<logfile> (command-line B<-o>)
791 This is the name of the file to which messages will be written. If it is not
792 specified then messages are written to F<stderr>.
794 Two special "file names" are also recognised as valid values. If the name is
795 B<NULL> the all messages will be turned off. If the name is B<SYSLOG> then
796 messages will be written to the host system log. On Windows systems this is
797 the system application event log. Elsewhere messages are written to the
800 =item B<serverport> (command-line <-T>)
802 This is the port on which the B<Zebedee> server will listen for tunnel
803 connections. The default is 11965 (0x2EBD) when running in TCP mode and 11230
804 (0x2BDE) in UDP mode. The keyword causes a server to listen on this port and a
805 client to attempt to connect to this port on the server system.
807 If using server-initiated connections (see B<L<listenmode|/item_listenmode>>
808 and B<L<clienthost|/item_clienthost>>) then this is also the port on which the
809 client listens for the server's incoming connections.
811 =item B<timestamplog> (command-line B<-t>)
813 This is a boolean value indicating whether log messages should contain a
814 time-stamp. The default is not to do so. The command-line option B<-t> is
815 equivalent to setting this to B<true>.
817 =item B<udpmode> (command-line B<-u>)
819 By default B<Zebedee> handles connection-oriented TCP/IP traffic. If this
820 keyword is set true handles UDP/IP connectionless traffic instead.
822 The tunnel between B<Zebedee> clients and servers still uses a TCP/IP
823 connection. A separate connection is established for each different
824 originating UDP network endpoint. Because UDP is connectionless there is no
825 easy way to tell when the data traffic has been completed. For this reason the
826 B<Zebedee> connection must be timed out after a period of inactivity. This
827 period is controlled by the B<L<udptimeout|/item_udptimeout>> value.
829 If more data subsequently arrives from a source the tunnel for which has been
830 timed out, the connection must be re-established. For this reason the
831 performance in UDP mode may appear poor, depending on the nature of the
832 application using it. Altering the B<L<keylifetime|/item_keylifetime>> value
833 may improve this by minimizing connection setup times and changing the
834 B<L<udptimeout|/item_udptimeout>> value may also help.
836 The command-line B<-u> option is equivalent to setting this to B<true>.
840 By default, UDP-mode tunnels will shut down after 300 seconds of inactivty.
841 This value can be changed by using this keyword to specify the timeout in
842 seconds. It must be no greater than 65535. Setting it to zero is legal but may
843 result in no data being transferred!
845 =item B<verbosity> (command-line B<-v>)
847 This is an integer specifying the level of message logging with 0 being just
848 error messages and 5 giving excruciating detail of the message
849 traffic. The default (and generally most useful level) is 1.
851 Messages are written to F<stderr> (unless redirected using the B<-o>
852 command-line option or B<L<logfile|/item_logfile>> keyword). The general form
853 of messages is something like:
855 zebedee(54/119): Listening on local port 1172
857 The numbers in brackets represent the process and thread identifiers of the
858 code logging the message. All error messages are logged at level 0 and are
859 preceded by the word C<ERROR>, as follows:
861 zebedee(54/119): ERROR: failed to connect to localhost:11965
863 Messages are indented according to the level at which they are logged.
867 =head3 Obsolete Keywords
869 As B<Zebedee> has evolved over time some of the keywords have been changed to
870 reflect this. In a few cases keywords have been superseded and made obsolete.
871 These obsolete keywords are still recognised in order to retain backwards
872 compatibility with old configuration files but they should not be used in new
879 This keyword has been superseded by the more general B<L<tunnel|/item_tunnel>>
882 This is the port or list of ports on which the B<Zebedee> client will listen
883 for connections. It is equivalent to the first part of a
884 B<L<tunnel|/item_tunnel>> specification.
888 This was the name of the B<L<clientport|/item_clientport> keyword prior to
889 version 2.0.0 of B<Zebedee>.
891 =item B<redirecthost>
893 This was the name of the B<L<targethost|/item_targethost> keyword prior to
894 version 2.0.0 of B<Zebedee>.
898 This was the name of the B<L<targetport|/item_targetport> keyword prior to
899 version 2.0.0 of B<Zebedee>.
903 This keyword has been superseded by the more general B<L<target|/item_target>>
906 This keyword gives the name of a host to which a B<Zebedee> server will
907 redirect all incoming tunnelled data, rather than to ports on the local
912 This keyword has been superseded by the more general B<L<tunnel|/item_tunnel>>
915 It gives the port or list of ports to which the client will request that
916 B<Zebedee> server should establish connections on the target host. It is
917 equivalent to the final part of a B<L<tunnel|/item_tunnel>> specification.
923 There are a few command-line options that have no equivalent in the
924 configuration file. These are described below.
930 This causes B<Zebedee> to generate a private key value and to write
931 it to standard output in a form that can be used in a configuration
932 file (see B<L<privatekey|/item_privatekey>>). For example:
934 privatekey "c480bd48f707c69dec54c9e7b6e22dd04cac659e"
938 This causes B<Zebedee> to generate a public "identity" suitable for use by
939 the L<identity checking|Identity Checking> feature. The result is written
940 to standard output. For example:
942 ef8153a0e392df005f67321ca2f0ace5bb8c5a1f myhostname
944 This option must either be specified with a configuration file that contains a
945 private key value or must be used in conjunction with B<-p> to generate
946 private and public keys simultaneously.
950 This option causes the remaining command-line arguments to be treated as the
951 names of files. Each file is read in 8192 byte chunks and the SHA hash is
952 calculated. If no arguments are specified or the argument is "C<->" then the
953 standard input is read and the hash of that is calculated. For example:
955 $ zebedee -h /etc/passwd
956 bb1e734aeffd2111417761f5938dea3b53759598 /etc/passwd
957 $ zebedee -h < /etc/passwd
958 bb1e734aeffd2111417761f5938dea3b53759598 -
962 This is similar to the B<-h> option except that each argument is treated
963 as a literal string and the SHA hash of the string is calculated and
966 $ zebedee -H hello world
967 ac62a630ca850b4ea07eda664eaecf9480843152 hello
968 86bf25ecb8a40b40b885c097c683b6e236fc8085 world
970 =item -S (Windows only)
972 On Windows systems B<Zebedee> can be installed and run as a "service" --- an
973 independently running process that is started automatically at system boot
976 B<Zebedee> can be installed as a service by specifying the B<install>
977 parameter with the name of a configuration file, for example:
979 zebedee -Sinstall=c:\zebedee\service.zbd
981 You should always specify the full path to the configuration file. This will
982 be read at service start-up and must contain all the parameters required for
985 By default, the name of the installed service will be taken from the name of
986 the program file, and hence is usually B<zebedee>, but you can change this by
987 using the B<-n> option:
989 zebedee -n "Zebedee Client Service" -Sinstall=c:\zebedee\clientsvc.zbd
991 Once the service has been installed it will be automatically started the next
992 time that the system reboots. Alternatively you can start it manually using
993 the Service Control Panel (under Windows NT).
995 To remove the service specify first stop it and then use the B<remove>
996 parameter to the B<-S> option, along with any necessary service name using
999 zebedee -n "Zebedee Client Service" -Sremove
1001 There is one further valid parameter to the B<-S> option and this is B<run>.
1002 This is used internally by B<Zebedee> to invoke the service start-up code and
1003 should not be used directly.
1007 This option can be used to set those configuration parameters that do not have
1008 any other direct command-line equivalent. It takes a string as an argument and
1009 this string is treated as if it were a line read from a configuration files
1010 (including comments but without "\" line continuation). So, for example:
1012 zebedee -x " server true # It's a server!"
1014 is a rather perverse way of achieving the same effect as:
1020 =head3 Quick-Reference Summary
1022 The following table lists the recognised keywords, their argument types,
1023 command-line equivalents, validity for client, server or both and a
1026 checkidfile filename CS Checks peer identities against the
1027 clienthost hostname -c S Server initiates connection to client host
1028 command string -e C Specified command to run connected to tunnel
1029 compression level -z CS Requested maximum compression level
1030 connecttimeout seconds CS Timeout for connections to be accepted
1031 debug boolean CS Run in single-threaded "debug" mode
1032 detached boolean -d CS Detach from the terminal/console
1033 generator string CS Hexadecimal Diffie-Hellman generator value
1034 include filename -f CS Read in the named configuration file
1035 keygencommand string CS Command to run to generate key
1036 keygenlevel level CS Key generation strength level (0 to 2)
1037 keylength bits CS Requested maximum keylength in bits
1038 keylifetime seconds CS Lifetime of shared secret keys
1039 listenmode boolean -l C Client listens for server connections
1040 localsource boolean C Only accepts connections from local machine
1041 logfile filename -o CS Set the output log file
1042 maxbufsize bytes CS Specify buffer size for data reads
1043 message string CS Output the specified string
1044 minkeylength bits CS Acceptable minimum keylength in bits
1045 modulus string CS Hexadecimal Diffie-Hellman modulus value
1046 multiuse boolean -m C Handle multiple connections
1047 name string CS Specify the name of the program
1048 privatekey string CS Hexadecimal private key string
1049 redirect ports -r S Ports to which server will redirect traffic
1050 server boolean -s CS Selects server-mode or client-mode
1051 serverhost hostname C Name of server host to which to connect
1052 serverport port -T CS Set the port on which the server listens
1053 target spec S Specifies allowed target host and ports
1054 timestamplog boolean -t CS Add timestamps to the log file
1055 tunnel spec C Specifies client ports and matching targets
1056 udpmode boolean -u CS Handle UDP traffic
1057 udptimeout seconds CS Inactivity timeout for UDP tunnels
1058 verbosity level -v CS Set the message logging level
1060 Other options that have no keyword equivalents:
1062 -p Generate a private key
1063 -P Generate a public "identity"
1065 Hash file contents and print results
1067 Hash string arguments and print results
1069 Install Windows service with specified configuration file
1071 Remove Windows service
1075 =head2 Identity Checking
1077 By default B<Zebedee> just establishes an encrypted channel between two
1078 points. While you know that the data is protected from snooping "on the wire"
1079 there is no guarantee that the channel ends up where you think it does. It is
1080 open to "man-in-the-middle" attacks. If you are concerned primarily with using
1081 data compression or protecting against casual "network sniffing" then you may
1082 be happy with this situation. If, however, you want more assurance that your
1083 connection is not being redirected then B<Zebedee> provides some basic
1084 facilities for doing so.
1086 If the same modulus, generator and private key are used they will always
1087 generate the same public value for use in the Diffie-Hellman key exchange
1088 protocol. If you use a fixed private key (specified using the
1089 B<L<privatekey|/item_privatekey>>)
1090 keyword in a configuration file) then B<Zebedee> can generate a key
1091 "fingerprint" by hashing together the modulus, generator and public key value.
1092 This is done using the B<-P> option, for example, if the file F<server.key>
1093 contains the following value:
1095 privatekey "1e34d6769502bae1087c18d2e8c8776e4a17ddaf"
1099 $ zebedee -P -f server.key > server.id
1101 will generate output something like this:
1103 135f04050961d37553731250d5c6f7495f088b32 myhostname
1105 The initial string of hexadecimal digits is the "fingerprint". Anything else
1106 on the line is a comment describing the owner of the identity. By default it
1107 is the name of the host on which the identity string was generated.
1109 If the B<L<checkidfile|/item_checkidfile>> keyword is specified in a
1110 configuration file then its value is the name of a file containing
1111 "fingerprint" lines. If the identity of the system at the other end of the
1112 connection does not match any of those in the file then the connection will be
1115 =head2 Notes on Other Security Issues
1119 =item Message Integrity
1121 In keeping with the desire to keep the protocol overhead as low as possible,
1122 B<Zebedee> does not perform any data integrity validation on the transmitted
1123 data stream. It is, therefore, possible for an attacker to alter data packets
1124 in transit. The encryption used should make it extremely hard for someone to
1125 transform them arbitrarily at will --- for example turning "C<ls -l>" into
1126 "C<rm -f>" --- but do not depend on B<Zebedee> to protect your application from
1127 the effects of being fed random data!
1129 =item Replay and Insertion Attacks
1131 One possible attack on many networked systems is that of capturing data
1132 streams that have a known effect --- for example, a B<telnet>
1133 session during which an administrator was known to be performing certain
1134 "dangerous" actions --- and then replaying it at some later time. This does not
1135 require cracking the encrypted data stream itself, merely knowing that the
1136 same network packets sent to a server will elicit the same response.
1138 When B<Zebedee> is operating in "anonymous" mode the risk of such an attack
1139 being successful is low because different keys will be generated and used for
1140 every session. However, if the L<identity checking|Identity Checking> features
1141 are used the keys will be fixed and replay could be a possibility. B<Zebedee>
1142 protects against this by generating a unique session key for each connection.
1143 Following that, the final part of the connection setup also involves a
1144 challenge-response exchange that verifies that the system at the other end of
1145 the connection really knows the shared secret key and is not just parrotting
1146 back previously recorded data.
1148 In addition, B<Zebedee> uses Blowfish encryption in "cipher feedback" mode
1149 which means that decryption of any part of the data depends upon successful
1150 decryption of all the data packets that have gone before it. The
1151 challenge-response exchange "salts" the data-stream so even if the protocol
1152 being tunnelled is determined a "known plain-text" attack is made more
1155 =item Key Generation
1157 A poorly-chosen key can compromise even the strongest encryption mechanism.
1158 When generating keys B<Zebedee> attempts to gather as much hard-to-guess state
1159 data as possible and then "stir" it using the SHA hashing algorithm. On modern
1160 UNIX systems this generation process should give pretty good keys.
1162 On Windows the available state data is somewhat more predictable, particularly
1163 if an attacker has access to the system. Having said that, it should be quite
1164 acceptable for most purposes. The comments in the code explain this in more
1165 detail if you are interested.
1167 If you are unhappy with the key generation mechanisms then you should call out
1168 to an external key generation program using the
1169 B<L<keygencommand|/item_keygencommand>> option in a configuration file.
1170 Suggestions for improving the built-in capabilities will also be gratefully
1175 =head1 TROUBLESHOOTING
1177 Although B<Zebedee> should work "out of the box" you might encounter some
1178 problems. These are most likely during connection setup --- once that has been
1179 accomplished the data transfer generally goes smoothly. The eaisest way to see
1180 what is happening during the setup process is to use the B<-v> option. You
1181 will usually want to combine this with the B<-d> and B<-D> options to stop
1182 B<Zebedee> from the terminal and to force it to handle only a single
1183 connection at a time. So, for example, you might use the following command to
1188 Setting the logging level to 3 should show you the main exchanges during
1189 connection setup. If you believe there is a problem after this then levels 4
1190 and 5 will show you what message traffic is being exchanged.
1194 In the B<Zebedee> distribution there are a number of example configuration
1195 files. The following sections describe how they can be used as well as how
1196 to use B<Zebedee> to tunnel some specific protocols.
1198 =head2 Example Server Configuration
1200 There is an example server configuration file (F<server.zbd>) shipped with the
1201 B<Zebedee> distribution. This shows most of the common options.
1204 # Sample Zebedee server configuration file
1206 # This shows the use of many, but not all, of the configuration file
1207 # options available for use by a server.
1210 verbosity 2 # Slightly more than basic messages
1212 server true # Yes, it's a server!
1213 detached true # Run detached from terminal
1214 udpmode false # Are we operating in UDP mode?
1216 # Uncomment the following line to log messages to a file
1218 # logfile './server.log'
1220 # Or to log to the system logging facility uncomment this:
1224 # Uncomment the following line if you want to use a fixed private
1225 # key stored in a static file. The file should contain a line of
1226 # the form "privatekey hexadecimal-key-string"
1228 # include './server.key'
1230 keygenlevel 2 # Generate maximum strength private keys
1232 # To validate the identity of clients uncomment the following
1235 # checkidfile './clients.id'
1237 # Set up allowed redirection ports.
1238 # These should be pretty safe -- but it's not a good idea
1239 # to open up all ports.
1241 redirect "telnet ftp" # Basic services
1242 redirect 5900-5999 # VNC traffic
1243 redirect 6000-6010 # X Window System
1244 redirect "daytime chargen" # Ports useful for testing
1246 targethost localhost # Redirection is to the local machine
1248 compression zlib:9 # Allow maximum zlib compression
1249 keylength 256 # Allow keys up to 256 bits
1250 keylifetime 36000 # Shared keys last 10 hours
1251 maxbufsize 16383 # Allow maximum possible buffer size
1253 To test the identity checking facilities you can uncomment the
1254 B<L<checkidfile|/item_checkidfile>> line and then use one of the supplied
1255 F<client1.key> or F<client2.key> files on the client side.
1259 One of the reasons behind writing B<Zebedee> was to use it over dial-up lines
1260 with VNC. VNC is a free system to provide remote display capabilities using a
1261 "remote frame-buffer" concept. You can use it to display Windows desktops
1262 remotely or, with an "Xvnc" server to access an "X desktop" from any
1263 VNC client machine, or even a Java-enabled browser! See
1264 http://www.uk.research.att.com/vnc/ for more details.
1266 The supplied sample server configuration file F<server.zbd> is configured to
1267 allow redirection of ports 5900-5999 which will allow tunnelling of VNC
1268 sessions. This file can be used on both UNIX and Windows but note that on
1269 Windows you must set the "AllowLoopback" flag in the registry in order for
1270 tunnelling to work. Saving the following snippet (without any leading spaces)
1271 in file a and then importing it into B<regedit> will do the trick:
1275 [HKEY_LOCAL_MACHINE\SOFTWARE\ORL\WinVNC3]
1276 "AllowLoopback"=dword:00000001
1278 [HKEY_LOCAL_MACHINE\SOFTWARE\ORL\WinVNC3\Default]
1279 "AllowLoopback"=dword:00000001
1281 You will find a file with these contents in the B<Zebedee> distribution by the
1282 name F<vncloopback.reg>. Having set these registry entries then the file
1283 F<vncviewer.zbd> can be used to invoke a VNC viewer tunnelled to the host
1284 named on the command line. Here are the contents of the file F<vncviewer.zbd>:
1287 # Zebedee configuration file to start up a tunnelled VNC session
1289 # Usage: zebedee -f vncviewer.zbd remote-host:vnc-port
1292 verbosity 1 # Basic messages only
1294 server false # It's a client
1295 detached true # Detach from terminal
1297 message "Starting VNC viewer"
1299 # On Windows systems you might use the following:
1301 command '"c:\Program Files\ORL\VNC\vncviewer.exe" localhost:%d'
1303 # On UNIX systems you might use the following:
1305 # command 'vncviewer localhost:%d'
1307 compression 6 # Request normal Zlib compression
1309 So using this file as follows:
1311 zebedee -f vncviewer.zbd somehost:5901
1313 will start a VNC viewer tunnelled to the VNC server on I<somehost> port 5901
1314 (the server you would usually refer to in VNC-parlance as "B<somehost:1>").
1316 VNC also supports a Java viewer. If the server is running on port 59xx then
1317 the viewer can be downloaded via port 58xx. However, it appears that the
1318 Java viewer communicates the main VNC port number to the client. So, to
1319 tunnel traffic when using the Java viewer you must make sure that the
1320 local and remote ports use the same numbers. So, for example, to tunnel
1321 traffic to a VNC server using port 5901 you should do something like:
1323 zebedee 5801,5901:remotehost:5801,5901
1325 This will be problematic if you already have a VNC server running locally on
1326 port 5901, but you can usually arrange local and remote VNC servers so that
1329 There is one last point worth mentioning. If you are using compression
1330 with VNC it is worth experimenting a bit with the VNC protocol encoding. I
1331 have found that "raw" encoding often compresses best and sometimes gives better
1332 performance with B<Zebedee> over slow links. But, as they say, your mileage
1335 =head2 Use with the X Window System
1337 The X Window System uses ports in the range 6000 onwards.
1339 Let's assume that your local machine called B<xlocal> is running an X server
1340 on port 6000. This would be the port normally used by the display known as
1341 B<xlocal:0>. You now want to send a secure B<xterm> session back to your local
1342 display from a machine called B<xremote>. To do this you might run the
1343 following command on B<xlocal>:
1347 Then on B<xremote> you could run:
1349 zebedee 6001:xlocal:6000
1351 This means that if the B<DISPLAY> environment variable on B<xremote> is set to
1352 C<localhost:1> then X traffic will end up on B<xlocal>. So, for example, to
1353 send a secured B<xterm> session from B<xremote> to B<xterm> you would run a
1354 command like this on B<xremote>:
1356 xterm -display localhost:1
1358 Note that in order for this to work correctly you must also add an entry for
1359 B<localhost> to the access control list for the X server on B<xlocal>. You
1360 can do this by running the following command on B<xlocal>:
1364 =head2 Securing HTTP traffic
1366 B<Zebedee> can be used to secure or just compress all traffic to and from a
1367 Web server. So, for example, if a Web server is running on the machine
1368 B<webhost> on port 80 and it is also running a B<Zebedee> server then the
1371 zebedee 8000:webhost:80
1373 will set up a tunnel via port 8000 on the client host. Now any URLs that
1374 previously were addressed via B<webhost>, for example:
1376 http://webhost/private/index.html
1378 can now be accessed securely as follows:
1380 http://localhost:8000/private/index.html
1382 You could redirect all HTTP traffic via the secure tunnel by setting
1383 "C<localhost:8000>" as your proxy. Be careful, however, only to set this as
1384 the proxy for HTTP connections --- other protocols (including Secure HTTP)
1385 should be directed elsewhere. It is also possible to configure most browsers
1386 to use different proxies for different domains and so secure connections
1387 selectively. Consult your browser's documentation for details on how to do
1390 =head2 Securing FTP traffic
1392 It is possible to protect the FTP control connection (over which the username
1393 and password are sent) for many FTP servers using B<Zebedee> "out of the box"
1394 by following the instructions below. It is also possible to protect the
1395 control connection for other servers and even "passive-mode" data connections
1396 by using B<Zebedee> in conjunction with the B<ftpgw.tcl> script in the
1397 B<Zebedee> distribution.
1399 The simplest approach, which works with some FTP servers, is to run the
1400 B<Zebedee> server as follows:
1402 zebedee -s -r ftp ftpserverhost
1404 Note that even if you are running B<Zebedee> on the same machine as the FTP
1405 server you should explictly name it on the command line (or using the
1406 B<L<redirecthost|/item_redirecthost>> keyword). Do not refer to it as
1407 B<localhost>. On the client system you could then run B<Zebedee> as follows to
1408 set up a tunnel via port 10000:
1410 zebedee 10000:ftpserverhost:ftp
1412 To connect to the FTP server you would then use a command like:
1414 ftp clienthost 10000
1416 Again, use the local client host name not, B<localhost>. If your FTP client
1417 does not support specifying the port on the command line, as is the case with
1418 the standard Windows FTP client program, you may be able to use the command
1419 "C<open clienthost 10000>" from within the program. If you are not running
1420 an FTP server on the client machine you could also try running B<Zebedee> as:
1422 zebedee ftp:ftpserverhost:ftp
1424 and then just invoking the FTP client program as:
1428 The approach just described will work for FTP servers that do not check that
1429 the FTP control and data connections appear to come from the same source.
1430 However, some servers such as the widely-used B<wu-ftpd> are more strict about
1431 this --- for good security reasons. If you can apparently establish a
1432 connection to the server but directory listing and file retrievals fail or
1433 hang then it is likely that your server is one of the strict ones.
1435 To help overcome this problem there is an "FTP gateway" script in the
1436 B<Zebedee> distribution called B<ftpgw.tcl>. This is a program, written using
1437 the freely-available B<Tcl> scripting language (see http://www.scriptics.com)
1438 that intercepts FTP requests and re-writes them so that a server is shielded
1439 from the presence of B<Zebedee>. You should run this on the same system as the
1440 B<Zebedee> server. Assuming that the FTP server is also running on the same
1441 system you can just run this as:
1445 This will start the gateway listening on port 2121. Obviously, in real usage
1446 you will probably want to start this in the background. You then start the
1447 B<Zebedee> server as:
1451 Note that in this case you do not have to specify the local host name,
1452 although you may do so if you wish. On the client side you can now run:
1454 zebedee 2121:ftpserverhost:2121
1460 You must still, however, use the client host name here.
1462 This configuration will allow you to tunnel the FTP control connection but
1463 will not affect any data connections. Using B<ftpgw.tcl> it is, however,
1464 also possible to secure the data channels provided that your FTP client can
1465 operate in "passive" mode. Examples of clients that can do this are Netscape
1466 Navigator and the Windows program WS_FTP.
1468 To secure passive-mode data connections you must choose a range of ports on
1469 the server that will be used for data connections. In this example we will use
1470 30000 to 30100. You then start B<ftpgw.tcl> with the B<-p> option to specify
1473 tclsh ftpgw.tcl -p 30000-30100
1475 The B<Zebedee> server would then be started as:
1477 zebedee -s -r 2121,30000-30100
1481 zebedee 2121,30000-30100:ftpserverhost:2121,30000-30100
1483 To access the server with both control and data connections secured using
1484 Netscape you would then supply a URL of the form:
1486 ftp://username@clienthost:2121/
1488 where I<username> is your user-name on the FTP server host.
1490 =head1 CREDITS AND LEGALITIES
1492 The following information can also be found in the file F<LICENCE.txt> in the
1493 B<Zebedee> distribution.
1495 Copyright (c) 1999, 2000 by Neil Winton. All Rights Reserved.
1497 This program is free software; you can redistribute it and/or modify
1498 it under the terms of the GNU General Public License as published by
1499 the Free Software Foundation; either version 2 of the License, or
1500 (at your option) any later version.
1502 This program is distributed in the hope that it will be useful,
1503 but WITHOUT ANY WARRANTY; without even the implied warranty of
1504 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1505 GNU General Public License for more details.
1507 You should have received a copy of the GNU General Public License
1508 along with this program; if not, write to the Free Software
1509 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
1512 A copy of the GNU General Public License can be found in the file F<GPL2.txt>.
1514 You may obtain the latest copy of B<Zebedee>, including full source code from
1515 http://www.winton.org.uk/zebedee/ and other enquiries about B<Zebedee>
1516 can be e-mailed to the author at zebedee@winton.org.uk
1518 B<Zebedee> would not have been possible without the use of a large amount of
1519 freely-available software to do all the really hard stuff. I gratefully
1520 acknowledge the contributions made by the authors of the following software
1523 B<Zebedee> uses the "Blowfish" encryption algorithm devised by Bruce Schneier.
1524 For more information on Blowfish see http://www.counterpane.com/blowfish.html .
1525 The implementation used is by Eric Young and is covered by the following
1528 Copyright (C) 1995-1997 Eric Young (eay@mincom.oz.au)
1529 All rights reserved.
1531 This package is an Blowfish implementation written
1532 by Eric Young (eay@mincom.oz.au).
1534 This library is free for commercial and non-commercial use as long as
1535 the following conditions are aheared to. The following conditions
1536 apply to all code found in this distribution.
1538 Copyright remains Eric Young's, and as such any Copyright notices in
1539 the code are not to be removed.
1541 Redistribution and use in source and binary forms, with or without
1542 modification, are permitted provided that the following conditions
1544 1. Redistributions of source code must retain the copyright
1545 notice, this list of conditions and the following disclaimer.
1546 2. Redistributions in binary form must reproduce the above copyright
1547 notice, this list of conditions and the following disclaimer in the
1548 documentation and/or other materials provided with the distribution.
1549 3. All advertising materials mentioning features or use of this software
1550 must display the following acknowledgement:
1551 This product includes software developed by Eric Young (eay@mincom.oz.au)
1553 THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
1554 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1555 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1556 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
1557 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1558 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
1559 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1560 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
1561 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
1562 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1565 The license and distribution terms for any publically available version or
1566 derivative of this code cannot be changed. i.e. this code cannot simply be
1567 copied and put under another distrubution license
1568 [including the GNU Public License.]
1570 The reason behind this being stated in this direct manner is past
1571 experience in code simply being copied and the attribution removed
1572 from it and then being distributed as part of other packages. This
1573 implementation was a non-trivial and unpaid effort.
1575 B<Zebedee> uses the B<zlib> compression library by Jean-loup Gailly and
1576 Mark Adler. It is covered by the following copyright notice:
1578 (C) 1995-1998 Jean-loup Gailly and Mark Adler
1580 This software is provided 'as-is', without any express or implied
1581 warranty. In no event will the authors be held liable for any damages
1582 arising from the use of this software.
1584 Permission is granted to anyone to use this software for any purpose,
1585 including commercial applications, and to alter it and redistribute it
1586 freely, subject to the following restrictions:
1588 1. The origin of this software must not be misrepresented; you must not
1589 claim that you wrote the original software. If you use this software
1590 in a product, an acknowledgment in the product documentation would be
1591 appreciated but is not required.
1592 2. Altered source versions must be plainly marked as such, and must not be
1593 misrepresented as being the original software.
1594 3. This notice may not be removed or altered from any source distribution.
1596 Jean-loup Gailly Mark Adler
1597 jloup@gzip.org madler@alumni.caltech.edu
1599 B<Zebedee> may use the B<bzip2> compression library by Julian Seward which is
1600 covered by the following licence:
1602 This program, "bzip2" and associated library "libbzip2", are
1603 copyright (C) 1996-1999 Julian R Seward. All rights reserved.
1605 Redistribution and use in source and binary forms, with or without
1606 modification, are permitted provided that the following conditions
1609 1. Redistributions of source code must retain the above copyright
1610 notice, this list of conditions and the following disclaimer.
1612 2. The origin of this software must not be misrepresented; you must
1613 not claim that you wrote the original software. If you use this
1614 software in a product, an acknowledgment in the product
1615 documentation would be appreciated but is not required.
1617 3. Altered source versions must be plainly marked as such, and must
1618 not be misrepresented as being the original software.
1620 4. The name of the author may not be used to endorse or promote
1621 products derived from this software without specific prior written
1624 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
1625 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1626 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1627 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
1628 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1629 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
1630 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
1631 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
1632 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
1633 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
1634 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1636 Julian Seward, Cambridge, UK.
1638 bzip2/libbzip2 version 0.9.5 of 24 May 1999
1640 By default B<Zebedee> is built using an aribtrary precision integer arithmetic
1641 library derived from the sources to C<mirrordir-0.10.49> which in turn derived
1642 this from the B<Python> sources. The copyright is as follows:
1644 huge-number.c: arbitrary precision integer library from Python sources
1645 This has nothing to do with cryptography.
1646 Copyright (C) 1998 Paul Sheer
1648 This program is free software; you can redistribute it and/or modify
1649 it under the terms of the GNU General Public License as published by
1650 the Free Software Foundation; either version 2 of the License, or
1651 (at your option) any later version.
1653 This program is distributed in the hope that it will be useful,
1654 but WITHOUT ANY WARRANTY; without even the implied warranty of
1655 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1656 GNU General Public License for more details.
1658 You should have received a copy of the GNU General Public License
1659 along with this program; if not, write to the Free Software
1660 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
1662 This file was taken from the Python source for `long' type
1663 integers. I have changed it to compile independently of the
1664 Python source, and added the optimisation that GNU C can
1665 use 31 bit digits instead of Python's 15 bit. You can download
1666 the original from www.python.org. This file bears little
1667 resemblance to the original though - paul
1669 Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
1674 Permission to use, copy, modify, and distribute this software and its
1675 documentation for any purpose and without fee is hereby granted,
1676 provided that the above copyright notice appear in all copies and that
1677 both that copyright notice and this permission notice appear in
1678 supporting documentation, and that the names of Stichting Mathematisch
1679 Centrum or CWI or Corporation for National Research Initiatives or
1680 CNRI not be used in advertising or publicity pertaining to
1681 distribution of the software without specific, written prior
1684 While CWI is the initial source for this software, a modified version
1685 is made available by the Corporation for National Research Initiatives
1686 (CNRI) at the Internet address ftp://ftp.python.org.
1688 STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
1689 REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
1690 MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
1691 CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
1692 DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
1693 PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
1694 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
1695 PERFORMANCE OF THIS SOFTWARE.
1697 B<Zebedee> uses the Secure Hash Algorith (SHA) the code for which was derived
1698 from Uwe Hollerbach's SHA module for B<perl>. The code contains the following
1701 NIST Secure Hash Algorithm
1702 heavily modified by Uwe Hollerbach <uh@alumni.caltech edu>
1703 from Peter C. Gutmann's implementation as found in
1704 Applied Cryptography by Bruce Schneier
1706 This code is in the public domain
1708 Under Windows, B<Zebedee> uses an implementation of the F<getopt> function
1709 covered by the following copyright:
1711 Copyright (c) 1987, 1993, 1994
1712 The Regents of the University of California. All rights reserved.
1714 Redistribution and use in source and binary forms, with or without
1715 modification, are permitted provided that the following conditions
1717 1. Redistributions of source code must retain the above copyright
1718 notice, this list of conditions and the following disclaimer.
1719 2. Redistributions in binary form must reproduce the above copyright
1720 notice, this list of conditions and the following disclaimer in the
1721 documentation and/or other materials provided with the distribution.
1722 3. All advertising materials mentioning features or use of this software
1723 must display the following acknowledgement:
1724 This product includes software developed by the University of
1725 California, Berkeley and its contributors.
1726 4. Neither the name of the University nor the names of its contributors
1727 may be used to endorse or promote products derived from this software
1728 without specific prior written permission.
1730 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
1731 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1732 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1733 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
1734 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1735 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
1736 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1737 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
1738 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
1739 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1744 Special thanks go to those people who have taken the trouble to give me
1745 feedback and suggestions for improvement!
1747 $Id: zebedee.pod,v 1.3 2000/09/27 05:58:18 tnaka Exp $