| 1 |
General idea. |
| 2 |
|
| 3 |
FIXME: client, server. HTTP. |
| 4 |
|
| 5 |
All HTTP requests are made by the client, htc, and are served by the |
| 6 |
server, hts. |
| 7 |
|
| 8 |
Data is sent to the server using HTTP PUT requests. These have a |
| 9 |
Content-Length header line, which is obeyed strictly if the --strict |
| 10 |
option is used. tunnel.c provides a nice interface to the |
| 11 |
complexities of HTTP requests. See tunnel.h for information about the |
| 12 |
programming interface. |
| 13 |
|
| 14 |
In the other direction, data is transferred using HTTP GET requests. |
| 15 |
|
| 16 |
|
| 17 |
Proxy buffering. |
| 18 |
|
| 19 |
Some proxies buffer data in HTTP PUT or POST requests. FIXME: explain |
| 20 |
why this is a problem and how it is solved. |
| 21 |
|
| 22 |
|
| 23 |
Debugging. |
| 24 |
|
| 25 |
To enable debugging code, use --enable-debug with 'configure'. This |
| 26 |
will make htc and hts recognize a --debug switch. |
| 27 |
--debug 0 - no messages whatsoever |
| 28 |
--debug 1 - log_notice () - important events |
| 29 |
--debug 2 - log_error () - unexpected errors |
| 30 |
--debug 3 - log_debug () - sparse debugging |
| 31 |
--debug 4 - log_verbose () - debugging in innner loops |
| 32 |
--debug 5 - log_annoying () - system calls and more |
| 33 |
|
| 34 |
Without --enable-debug, log_notice() and log_error() will log using |
| 35 |
syslog() with level LOG_NOTICE and LOG_ERROR, respectively. |
| 36 |
log_debug(), log_verbose(), and log_annoying() will be disabled. |
| 37 |
|
| 38 |
|
| 39 |
Some notes about the protocol. |
| 40 |
|
| 41 |
The data sent in HTTP requests is in itself formatted according to a |
| 42 |
simple protocol. This is needed becase some HTTP proxy servers buffer |
| 43 |
data before sending it to its final destination. |
| 44 |
|
| 45 |
There are seven different requests in this protocol, and there are |
| 46 |
two types of requests. Requests with the 0x40 bit set consists of |
| 47 |
just one byte, with no additional data. Requests with the 0x40 bit |
| 48 |
clear have a two-byte length field and a variable length data field. |
| 49 |
|
| 50 |
TUNNEL_OPEN |
| 51 |
01 xx xx yy... |
| 52 |
xx xx = length of auth data |
| 53 |
yy... = auth data |
| 54 |
|
| 55 |
OPEN is the initial request. For now, auth data is unused, |
| 56 |
but should be used for authentication. |
| 57 |
|
| 58 |
TUNNEL_DATA |
| 59 |
02 xx xx yy... |
| 60 |
xx xx = lenth of data |
| 61 |
yy... = data |
| 62 |
|
| 63 |
DATA is the one and only way to send data. |
| 64 |
|
| 65 |
TUNNEL_PADDING |
| 66 |
03 xx xx yy... |
| 67 |
xx xx = lenth of padding |
| 68 |
yy... = padding (will be discarded) |
| 69 |
|
| 70 |
PADDING exists only to allow padding the HTTP data. This is |
| 71 |
needed for HTTP proxies that buffer data. |
| 72 |
|
| 73 |
TUNNEL_ERROR |
| 74 |
04 xx xx yy... |
| 75 |
xx xx = length of error message |
| 76 |
yy... = error message |
| 77 |
|
| 78 |
Report an error to the peer. |
| 79 |
|
| 80 |
TUNNEL_PAD1 |
| 81 |
45 |
| 82 |
PAD1 can be used for padding when a PADDING request would be |
| 83 |
too long with regard to Content-Length. PADDING should always |
| 84 |
be preferred, though, because it's easier for the recipent to |
| 85 |
parse one large request than many small. |
| 86 |
|
| 87 |
TUNNEL_CLOSE |
| 88 |
46 |
| 89 |
CLOSE is used to close the tunnel. No more data can be sent |
| 90 |
after this request is issued, except for a TUNNEL_DISCONNECT. |
| 91 |
|
| 92 |
TUNNEL_DISCONNECT |
| 93 |
47 |
| 94 |
DISCONNECT is used to close the connection temporarily, |
| 95 |
probably because Content-Length - 1 number of bytes of data |
| 96 |
has been sent in the HTTP request. |