-
Notifications
You must be signed in to change notification settings - Fork 4
/
README
657 lines (492 loc) · 20.9 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
AF - Active Port Forwarder 0.8.5 - README
Copyright (C) 2003-2007 jeremian - <jeremian [at] poczta.fm>
=================================================================
================================================================================
GRAY-WORLD.NET / Active Port Forwarder
======================================
The Active Port Forwarder program is part of the Gray-World.net projects.
Our Gray-World Team presents on the http://gray-world.net website the projects
and publications we are working on which are related to the NACS (Network
Access Control System) bypassing research field and to the computer and
network security topics.
================================================================================
=======
SUMMARY
=======
INTRO
1. INSTALLATION
1.1 Instructions
1.2 Required libs
1.3 Tested platforms
2. USAGE
2.1 afserver
2.2 afclient
3. REMOTE ADMINISTRATION
3.1 Usage
3.2 Commands
3.3 States
3.3.1 Users
3.3.2 Clients
3.4 Relay mode
4. LOGGING
5. MODULES
6. MULTI TUNNELS
7. EXAMPLES
7.1 tcp mode
7.2 reverse udp mode
8. BUGS/PROBLEMS
NOTES
THANKS
================================================================================
=====
INTRO
=====
Active port forwarder is a software tool for secure port forwarding.
It uses ssl to increase security of communication between a server and a client.
Originally, it was developed to forward data point to point. However, the need
for bypassing firewalls in order to connect to internally located computers
influenced the further development of the project.
AF is dedicated for people, who don't have an external ip number and want to
make some services available across the net.
Moreover, zlib is used to compress the transferred data.
Using one, permanent data/control channel with flow control / packet buffering
provides good performance and reasonably small latency.
Multiple clients allow to create more sophisticated tunneling scheme.
================================================================================
===============
1. INSTALLATION
===============
1.1 Instructions
----------------
1. Download the compressed sources from http://www.gray-world.net/pr_af.shtml
2. Unpack them with tar zxvf
3. Type "./configure"
4. Type "make"
5. Type "make install" while logged as root
6. If something goes wrong - mail the author or post a message on
http://gray-world.net/board/
1.2 Required libs
-----------------
1. openssl - http://www.openssl.org/
2. zlib - http://www.gzip.org/zlib/
1.3 Tested platforms
--------------------
1. Linux:
Gentoo, Slackware, Mandrake - built without any problems
2. Windows:
win32 - cygwin version is available on the project homepage
================================================================================
========
2. USAGE
========
2.1 afserver
------------
Basic options:
-n, --hostname - it's used when creating listening sockets
(default: '')
-l, --listenport - listening [host:]port - users connect to it
(default: 50127)
-m, --manageport - manage [host:]port - afclient connects to it
(default: 50126)
-V, --version - display version number
-h, --help - prints this help
Authorization:
--pass - set the password used for client identification
(default: no password)
Configuration:
-c, --cerfile - the name of the file with certificate
(default: server-cert.pem)
-A, --cacerfile - the name of the file with CA certificates
(if used, require clients to have valid certificates)
-d, --cerdepth - the maximum depth of valid certificate-chains
-k, --keyfile - the name of the file with RSA key (default: server.rsa)
-f, --cfgfile - the name of the file with the configuration for the
active forwarder (server)
-D, --dateformat - format of the date printed in logs (see 'man strftime'
for details) (default: %d.%m.%Y %H:%M:%S)
-t, --timeout - the timeout value for the client's connection
(default: 5)
--maxidle - the maximum idle time for the client's connection
(default: disabled)
-u, --users - the amount of users allowed to use this server
(default: 5)
-C, --clients - the number of allowed clients to use this server
(default: 1)
-r, --realm - set the realm name (default: none)
-R, --raclients - the number of allowed clients in remote administration
mode to use this server (default: 1)
-U, --usrpcli - the number of allowed users per client (default: $users)
-M, --climode - strategy used to connect users with clients (default: 1)
Available strategies:
1. fill first client before go to next
-p, --proto - type of server (tcp|udp) - what protocol it will be
operating for (default: tcp)
-b, --baseport - listenports are temporary and differ for each client
-a, --audit - additional information about connections are logged
--nossl - ssl is not used to transfer data (but it's still used
to establish a connection) (default: ssl is used)
--nozlib - zlib is not used to compress data (default: zlib is
used)
--dnslookups - try to obtain dns names of the computers rather than
their numeric IP
Logging:
-o, --log - log choosen information to file/socket
-v, --verbose - to be verbose - program won't enter the daemon mode
(use several times for greater effect)
IP family:
-4, --ipv4 - use ipv4 only
-6, --ipv6 - use ipv6 only
2.2 afclient
------------
Basic options:
-n, --servername - where the second part of the active
port forwarder is running (required)
-m, --manageport - manage port number - server must be
listening on it (default: 50126)
-d, --hostname - the name of this host/remote host - the final
destination of the packets (default: the name
returned by hostname function)
-p, --portnum - the port we are forwarding connection to (required)
--localname - local machine name for connection with afserver
(used to bind socket to different interfaces)
--localport - local port name for connection with afserver
(used to bind socket to different addressees)
--localdesname - local machine name for connections with destination
application (used to bind socket to different interfaces)
-V, --version - display version number
-h, --help - prints this help
Authorization:
-i, --id - sends the id string to afserver
--pass - set the password used for client identification
(default: no password)
--ignorepkeys - ignore invalid server's public keys
Configuration:
-k, --keyfile - the name of the file with RSA key (default: client.rsa)
-c, --cerfile - the name of the file with certificate
(default: no certificate used)
-f, --cfgfile - the name of the file with the configuration for the
active forwarder (client)
-s, --storefile - the name of the file with stored public keys
(default: known_hosts)
-D, --dateformat - format of the date printed in logs (see 'man strftime'
for details) (default: %d.%m.%Y %H:%M:%S)
-K, --keep-alive N - send keepalive packets every N seconds
(default: not send keepalive packets)
Auto-reconnection:
--ar-start - enable auto-reconnection when afserver is not
reachable on start (default: disabled)
--ar-quit - enable auto-reconnection after normal afserver quit
(default: disabled)
--noar - disable auto-reconnection after premature afserver
quit (default: enabled)
-A, --ar-tries N - try N times to reconnect (default: unlimited)
-T, --ar-delay N - wait N seconds between reconnect tries (default: 5)
Modes:
-u, --udpmode - udp mode - client will use udp protocol to
communicate with the hostname:portnum
-U, --reverseudp - reverse udp forwarding. Udp packets will be forwarded
from hostname:portnum to the server name:manageport
-r, --remoteadmin - remote administration mode. (using '-p #port' will
force afclient to use port rather than stdin-stdout)
Logging:
-o, --log - log choosen information to file/socket
-v, --verbose - to be verbose - program won't enter the daemon mode
(use several times for greater effect)
IP family:
-4, --ipv4 - use ipv4 only
-6, --ipv6 - use ipv6 only
Modules:
-l, --load - load a module for user's packets filtering
-L, --Load - load a module for service's packets filtering
================================================================================
========================
3. REMOTE ADMINISTRATION
========================
3.1 Usage
---------
Afclient can be started in remote administration mode by '-r, --remoteadmin'
option. Required option: '-n, --servername NAME'.
After successful authorization stdin/stdout is used to communicate with user.
All the commands parsing is done by afserver.
3.2 Commands
------------
Currently available commands are:
help
display help
lcmd
lists available commands
info
prints info about server
rshow
display realms
cshow X
display clients in X realm
ushow X
display users in X realm
quit
quit connection
timeout N X
set timeout value in X realm
audit {0|1} X
set audit mode in X realm
dnslookups {0|1} X
set dnslookups mode in X realm
dateformat S
set dateformat
kuser S
kick user named S
kclient N
kick client with number N
3.3 States
----------
3.3.1 Users
-----------
Connected users can be in several states:
running
user is properly connected and can send/receive data
opening
user is connected to afserver, but afclient hasn't confirmed connection
with the destination. There is no traffic allowed in this situation.
opening (closed)
user was in 'opening' state, but 'kuser' command has been used and it's
now queued for closing as soon as afclient will be ready to confirm
this
stopped
user wasn't responsible, so all the packets addressed to it are queued.
Afclient is informed to not receive any packets for this user.
closing
connection with user has been lost. Afclient has to confirm user
deletion
unknown
probably afserver internal state has been corrupted.
3.3.2 Clients
-------------
Connected clients can be in several states:
running
client is properly connected and can serve user's requests
ssl handshake
connection with client has been initialized and now ssl routines are
negotiating all the details needed to establish secure tunnel. This
stage with 'authorization' must not exceed the time set by 'timeout'
option.
authorization
ssl tunnel is ready and afclient has to authorize itself to the
afserver. This stage with 'ssl handshake' must not exceed the time set
by 'timeout' option.
unknown
probably afserver internal state has been corrupted.
3.4 Relay mode
--------------
Afclient with '-p, --portnum PORT' option listens for connection from user at
NAME:PORT. NAME is set by '-d, --hostname' option or hostname() function, when
the option is missing.
When user quits (close the connection or send 'quit' command), afclient exits.
================================================================================
==========
4. LOGGING
==========
Logging can be enabled by '-o, --log' option. The argument to this option must
be in the form:
target,description,msgdesc
Where
target is file or sock
description is filename or host,port
msgdesc is the subset of:
LOG_T_ALL,
LOG_T_USER,
LOG_T_CLIENT,
LOG_T_INIT,
LOG_T_MANAGE,
LOG_T_MAIN,
LOG_I_ALL,
LOG_I_CRIT,
LOG_I_DEBUG,
LOG_I_DDEBUG,
LOG_I_INFO,
LOG_I_NOTICE,
LOG_I_WARNING,
LOG_I_ERR
written without spaces.
Example:
file,filename,LOG_T_MANAGE,LOG_I_ALL
================================================================================
==========
5. MODULES
==========
Afclient can use external modules for user's packets filtering ('-l, --load')
and service's packets filtering ('-L, --Load'). Module file has to declare three
functions:
char* info(void);
info() return values:
- info about module
Example:
char*
info(void)
{
return "Module tester v0.1";
}
int allow(char* host, char* port);
allow() return values:
0 - allow to connect
!0 - drop the connection
Example:
int
allow(char* host, char* port)
{
return 0; /* allow to connect */
}
int filter(char* host, unsigned char* message, int* length);
filter() return values:
0 - allow to transfer
1 - drop the packet
2 - drop the connection
3 - release the module
4 - drop the packet and release the module
5 - drop the connection and release the module
Example:
int
filter(char* host, unsigned char* message, int* length)
{
int i;
for (i = 1; i < *length; ++i) {
if (message[i-1] == 'M') {
if (message[i] == '1') {
return 1; /* ignored */
}
if (message[i] == '2') {
return 2; /* dropped */
}
if (message[i] == '3') {
return 3; /* release */
}
if (message[i] == '4') {
return 4; /* ignored + release */
}
if (message[i] == '5') {
return 5; /* dropped + release */
}
}
}
return 0; /* allow to transfer */
}
Modules have to be compiled with '-fPIC -shared' options.
================================================================================
================
6. MULTI TUNNELS
================
Since version 0.8 it's possible to transfer multiple tunnels in the one
afclient <-> afserver connection.
On the afserver we have to specify multiple listen ports with the same manage
port.
When we set several '-p' options on the afclient, the new user connections will
be distributed according to the sequence of the options, i.e. new user
connecting to the second UsrCli pair (with the same manage ports) will be
transferred to the destination pointed by the second '-p' option.
================================================================================
===========
7. EXAMPLES
===========
7.1 tcp mode
------------
local network |FireWall| Internet
||
|| User 1
|| /(tcp)
AF Client <---Encrypted/Compressed channel---> AF Server
/ || | \(tcp)
/(tcp) || (tcp)| User 2
/ || \
Http server || User 3
||
The use of it is extremely simple. Let's suppose we want to create a http server
on our computer and we are behind a masquerade or a firewall:
1) We have to find some machine on the net with an external ip and a shell
account.
2) Use "make" to compile everything on that machine. (you can freely remove the
afclient and client.rsa files)
3) You can edit the config file or just type from the console (to use the config
type -f <cfgfile>) :
$ ./afserver
This will work, if you want to use default values:
- hostname will be taken from hostname function (it would be ideally, if
there is appropriate registration in /etc/hosts)
- server will be listening for users on port 50127
- server will be listening for client on port 50126
- server will be for maximum 5 users
- server will forward tcp packets
- there will be no logging and no verbose messages
- there will be no password identification
- ip protocol family will be unspecified
4) We use "make" on our machine (we can delete everything apart from afclient
and client.rsa)
5) We are typing from the console:
$ ./afclient -n <name of the server> -p 80
Where <name of the server> is a string like : 'bastion.univ.gda.pl' or
'153.19.7.200'
6) We can now enter with a web-browser to: <name of the server>:50127 and we
will enter to our computer in the fact.
7.2 reverse udp mode
--------------------
local network |FireWall| Internet
|| (udp)
|| User 1-------AF Client
|| /(tcp)
AF Client <---Encrypted/Compressed channel---> AF Server
/ || |
/(udp) || (tcp)|
/ || /
Game server || AF Client-------User 2
|| (udp)
Let's see how to use af to forward udp packets. Suppose we want to create a game
server on our computer (udp port 27960 on our machine):
1) - 4) is the same like in example 1. (but we add option: -p udp)
5) We are typing from the console:
$ ./afclient -u -n <name of the server> -p 27960
Where <name of the server> is a name (or ip) of a host where our server is
running.
6) Connecting to our game is more complicated. The user must use afclient to do
this. He has to specify the server he is connecting to and the port, which
his program will be listening on:
$ ./afclient -U -d <hostname> -p <portnum> -n <name of the server> \
-m <server port>
Where <hostname> is the name of the user machine (who wants to connect to our
game). <portnum> is the port he will be connecting to. <name of the server>
is the name of the host where our server is running. <server port> is the
port on which the server is listening for users. In order to connect to our
game, the user has to connect to <hostname>:<portnum>.
================================================================================
================
8. BUGS/PROBLEMS
================
There are no known/open bugs at the moment.
================================================================================
=====
NOTES
=====
Active port forwarder is still under development, so please sent any comments,
bugs notices and suggestions about it to <jeremian [at] poczta.fm>
If you have some problems or want to share your opinions with others, feel free
to post a message at http://gray-world.net/board/
================================================================================
======
THANKS
======
Big thanks to the GW Team:
to Alex <alex [at] gray-world.net>
and Simon <scastro [at] entreelibre.com> for testing AF and a lot of advices.
Thanks to Ilia Perevezentsev <iliaper [at] mail.ru> who read and corrected the
README file.
Thanks to Marco Solari <marco.solari [at] koinesistemi.it> for a lot of
requests, suggestions and ideas.
Thanks to Joshua Judson Rosen <rozzin [at] geekspace.com> for the patch adding
certificate-based authentication to the APF.
And thanks for using this software!
LICENSE
-------
Active Port Forwarder is distributed under the terms of the GNU General
Public License v2.0 and is copyright (C) 2003-2007 jeremian <jeremian
[at] poczta.fm>. See the file COPYING for details.
In addition, as a special exception, the copyright holders give permission to
link the code of portions of this program with the OpenSSL library under
certain conditions as described in each individual source file, and distribute
linked combinations including the two.