USI++ README
============

0. About
--------

USI++ was (is) a product developed by S. Krahmer, krahmer@cs.uni-potsdam.de
It is a low-level network-library for sending/receiving IP-packets
directly on so called 'raw sockets'. It can be used for network-monitoring
also. Since version 1.2 it uses the packet capture library libpcap that
is a portable library for fetching network-traffic on the datalink-layer.

USI++ in lattest version is always available on
http://www.cs.uni-potsdam.de/homepages/students/linuxer


1. License
----------

USI++ comes under the GPL. See file COPYING for more
details. 

 *	This product includes software developed by the Computer Systems
 *	Engineering Group at Lawrence Berkeley Laboratory.

(libpcap)

Due to a technical feature of C++ compilers it was needed to
patch the pcap headerfiles to work with C++ compilers/functions.
The changes are minor and doesn't affect your installation. The modified
files are in the pcap directory.

Since USI++ is GPL there is ABSOLUTELY NO WARRANTY. YOU USE IT AT YOUR OWN RISK.
Some exapmles that are shipped with this library may look strange to you.
All the code was written FOR EDUCATIONAL PURPOSES ONLY! This includes the so called
'sniffers', 'spoofers' and so on. 
NOTE that it is maybe illegal in your country to use such programs. So only use
it on/against your own computers without other involved persons!

2. Install
----------

# configure
# make
# make install

Please report any problems to krahmer@cs.uni-potsdam.de

3. Compiling the examples
-------------------------

# c++ foo.cc -lusi++

4. Function-description
-----------------------

Right now there are 4 different classes:

	o IP
	o ICMP
	o UDP	(former RAW_UDP)
	o TCP	(former RAW_TCP)

that let you handle all the network-stuff. Assume you want to open
a TCP 'socket':

	...
	TCP tcp("foo.bar.com");
	...
thats all you need. The destination is foo.bar.com and could also be
a IP-adress such as 11.11.11.11. The sourceadress is set by the library 
itself. Source and destination-port must be set by the user:

	...
	tcp.set_dstport(23);		// set destinationport
	tcp.set_srcport(1024);		// set sourceport
	...

Flags can be set using the set_flags() member.
Packets are now send by

	...
	tcp.sendpack("Boo");
	...

or, if not a string via

	...
	tcp.sendpack(buf, len);
	...

Obtaining a packet via either:

	...
	tcp.recvpack(buf, len);
	...

Since most OS's differ in their behaivior of reading packets from RAW-sockets,
it's recommented to use sniffpack() instead:

	...
	tcp.init_device("eth0", 1, 500);  // use first ethernet-card, switch to
					  // promiscous mode (1) and fetch first 500 
                                          // bytes of packet
	tcp.sniffpack(buf, len);	  // do it
	...

Wow! Thats simple. Eh?
By using the TCP class the so called packetfilter (packetfilters are used
to say the kernel what kind of packets we need, for example you can tell him
to drop all udp-packets) only gives TCP packets. IP, ICMP and UDP are
straight forward. YOu can modify the filter by calling

	...
	tcp.setfilter("ip and src foo.bar.com");
	...

for example. Please look at the tcpdump manpage. USI++ uses the
same filter-parsing mechanisms (pcap_compile).
Ofcorse there is a lot more to do to initiate a TCP-connection.
You will find well documented example code in samples directory.
They should show you how to use USI++ and not being programs to
use.


5. BUGS/TODO
------------

The USI++ library now works proper with ethernet-frames.
PPP is difficult but hopefully comes in the next days.
IP or TCP-options are not supportet yet. They will be added as
soon as possible.
All the examples (and lib itself) compiles clean on RedHat 6.0
system and FreeBSD 3.x with egcs 1.1.2.. On FreeBSD 3.1 you need
to install this or a newer version b/c the default C++ compiler
doesn't support namespaces.
Ports to NetBSD and OpenBSD are planned. Commercial systems
are not planned to be supportet, except the vendors sponsor it.

6. Some words about GPL
-----------------------

As you know, libusi++ comes under the GPL. Thus you don't need
to pay for such programs that are under this license. But this also
means that the authors of such GPL-programs don't get money for it.
However the developement itself costs some money such as online-costs,
new hardware, disks, software and new linux-distributions.
If you want to support the developement of libusi++ you may spend
accounts, hardware, linux-distris or whatever. Please contact
me at krahmer@cs.uni-potsdam.de if you feel so. Especially the
'big' linux-distributors may push my work with spending their
actual distribution so i can port it faster and easier.
Such support ofcorse would not affect the license or any
other things of libusi++ so you can be sure that the lib
is developed free of restrictions.


Papers, books,...
-----------------

[1] RFC 793
[2] http://www.packetfactory.net
[3] UNIX Network Programming, W. R. Stevens, Prentice Hall 1998

