Index (v2)
----------

1. What is this project ?
2. Who are we ?
3. Requirments !
4. Architecture.
5. Library description.
6. Samples.
7. What's next ?
8. Contact us.

1. What is this project ?
-------------------------

When I first started to learn about the world of security (and hacking)
I had some knowledge of basic exploits and networking.

I knew that if I want to find exploits my self I will have to deal with the nuts and bolts of the networking protocols.

And so on, I began investigating the matter until I found sockets 2.
Altough you must have nt2k to run this. (soon everyone will have)

After a 2 month of writing this library. (you won't believe how many little things like wrong bits, slowed my pace)

I'm releasing it so other programmers/hackers can learn/use this library.

Altough this is not much (currently), I haven't found anything better during the time I coded
this library. (beside ICMP sample)

2. Who are we ?
---------------

We are a new group at the scene of hacking/security, you can visit us at : http://www.komodia.com

3. Requirments !
----------------

OS : win2k (Some samples work on NT, ICMP and regular tcp and udp will work well on NT)
To compile : you will need the recent DDK or SDK for win2k. (Recomended)

Link: add ws2_32.lib to the input list (link settings)
Console mode: add the following lines (seen in the console samples)

#undef _DEBUG

typedef int                 BOOL;

#define TRUE 1
#define FALSE 0
#define NULL 0

4. Architecture.
-----------------------
This library uses sockets 2.

It has two main features:

1. It opens up a raw socket, and sets it in a way it alows to send raw IP headers. 
   (so you can do IP spoofing, and play with the bits and bolts of the protocol)
2. You can use it as a regular sockets, why - when I programmed my ATL server, I tried to open a socket,
   but since the MFC frameworks takes the instance with AfxGetInstance, the ATL server crashed, my application
   takes the application instance dynamicly.

The base class is CSpoofSocket, which is the main IP carrier protocol.
The other three classes are CTCPSocket,CUDPSocket and CICMPSocket both are tcp and udp, which inherit from CSpoofSocket.

There are two helper classes CIPOptions, CTCPOptions which control the options for both protocols
(Currently IP options are supported for raw operations only)

If you feel you need to have more control over the IP header, you can :

A. Change my code.
B. Inherit my class and override ConstructIPHeader.

There are two basic ways to use the library :

A. Raw sockets
--------------

Allocate the desired class
Set it's properties to raw
Start messing around
(This way the socket is blocking)

B. Regular messaging
--------------------

Allocate the desired class
Set the application instance (In my samples I set some to NULL and it still worked)
Create it (Here my frameworks creates an handler for all the async requests, each time the socket
           status changes, it calls the appropriate OnSocketEvent i.e. for receive OnSocketReceive.
           In my samples I inherited from the classes and overided those functions)
Start working

5. Library description.
-----------------------

CSpoofSocket
------------

Functions :

BOOL ShutdownSockets() 
----------------------

When the program ends, you must call this function to free all resources allocated by the OS.

BOOL Listen(int iBackLog)
-------------------------

Listen to incoming data.
Currently doing problems.

return value - Non zero for success.

void SetTTL(unsigned char ucTTL)
--------------------------------

Set time to live on the packet.
Could be used for tracing routes.

unsigned short CalculatePseudoChecksum(char *buf, 
				       int BufLength,
				       LPCSTR lpDestinationAddress,
				       int iPacketLength)
---------------------------------------------------------

Calculate checksum for TCP and UDP which require calculating along a pseudo header.

buf - The packet to checksum.
BufLength - Size of the buf.
lpDestinationAddress - Destination address of the packet.
iPacketLength - Packet length.

return value - The checksum.

void SetSourceAddress(LPCSTR lpSourceAddress)
---------------------------------------------

Set the source address of the socket.
Calling bind before, will set the source address to the bind,
but calling bind after won't change the value seted by the user.

(this can be used to IP spoofing, setting the address to a diffrent one)


BOOL InitializeSockets()
------------------------

Must call on the beginning of your program.
Initialize the socket engine.

return value - Non zero for success.

BOOL Close()
------------

Close the socket and frees the resources.

return value - Non zero for success.


virtual BOOL Bind(LPCSTR lpSourceAddress)
-----------------------------------------

Binds the socket to a specific network (i.e. nic).

return value - Non zero for success.

int GetLastError()
------------------

return value - The last error that occured, zero if no error.

virtual BOOL Send(LPCSTR lpDestinationAddress,
		  char* buf,
		  int bufLength)
--------------------------------

Send data using IP protocol.

lpDestinationAddress - The destination address.
buf - The buffer to send (can be other higher level protocols like tcp and udp)
bufLength - Length of the buffer.

return value - Non zero for success.

BOOL Create(int iProtocol)
--------------------------

iProtocol - The protocol to use. (defined in the header)

return value - Non zero for success.

void SetBlocking(BOOL bBlock)
-----------------------------

bBlock - Will block ?

Function will set the blocking option for a socket (run before create)

BOOL ValidAddress(LPCTSTR lpAddress)
------------------------------------

lpAddress - The address to check.

return value - True if the address is valid.
	
BOOL SetTimeout(int iMs)
------------------------

Set the timeout for a socket operation (Calls OnReceiveTimeout)

iMs - Timeout in Miliseconds.

return value - True for success.

BOOL KillTimer()
----------------

Kills the timer, should be called as soon as a socket event occurs.

return value - True for success.

char FAR * LongToString(long lAddr)
-----------------------------------

Converts an IP address stored as long to string.

lAddr - The address to convert.

return value - The string address.

virtual int Receive(char* buf,int bufLen)
-----------------------------------------

Receives data from the socket buffer.

buf - Buffer to receive data to.
bufLen - Buffer length.

return value - Number of bytes read, SOCKET_ERROR for error.

void SetInstance(HINSTANCE hInst)
---------------------------------

Sets the socket notification mechanism, application handle. (Needed only for async operations)

hInst - The application handle.

CIPOptions* GetOptions()
------------------------

Used to get the option structure the header contains.

return value - options structure.

void SetOptions(BOOL bOptions)
------------------------------

Allows options to be used within the socket.

bOptions - True to allow options.

void SetRaw(BOOL bRaw)
----------------------

Sets socket to raw or regular (need to be set before Create)

bRaw - True for raw.

BOOL ShutdownSockets()
----------------------

Clears the system resources, socket's and this library async mechanism.

return value - True for success.

BOOL Listen(int iBackLog)
-------------------------

Set the socket mode to listen (TCP only), need to call bind before.

iBackLog - Socket backlog.

return value - True for success.

virtual BOOL OnSocketConnect(int iErrorCode)
virtual BOOL OnSocketAccept(int iErrorCode)
virtual BOOL OnSocketClose(int iErrorCode)
virtual BOOL OnSocketOOB(int iErrorCode)
virtual BOOL OnSocketWrite(int iErrorCode)
virtual BOOL OnSocketReceive(int iErrorCode)
--------------------------------------------

Overide these functions to receive notification of the network events.

iErrorCode - If an error occured, a non zero error code.

return value - True for success.

virtual BOOL OnSocketTimeout()
------------------------------

Overide this function to receive notification of a timeout.

return value - False to indicate the message has been handled.


CIPOptions
----------

void AddOption_Option
---------------------

Add that option to the options list (for a complete detail of each option, go to the IP RFC)

void AddOption_ENDLIST()
------------------------

Indicates end of options.

void Reset()
------------

Delete all options

void SetAutoPad(BOOL bAutoPAD)
------------------------------

Set the pading option (If to put zeros so the option will align to 4 bytes)

bAutoPad - True to pad


CTCPSocket
----------

Currently I can only start a handshake, but since sockets2 still doesn't allow to listen
on raw sockets, it can only be used for syn attacks. (but if you want full TCP you don't need my library)

functions :

BOOL Connect(int iSourcePort,
	     LPCSTR lpDestinationAddress,
             int iDestinationPort)
----------------------------------

iSourcePort - Source port to connect from (zero for any)
lpDestinationAddress - Destination address.
iDestinationPort - Destination port to connect to (zero for any)

return value - Non zero for success.

BOOL Create()
-------------

Create the socket (using TCP) - RAW

return value - Non zero for success.


BOOL CreateRegular()
--------------------

Create the socket (Regular socket)

return value - Non zero for success.

long GetPeerAddress()
---------------------

return value - Address of the remote address (only for listening sockets)

BOOL Accept(CTCPSocket* tSok)
-----------------------------

Accepts a connection to a pre exists socket.

tSok - The user socket.

return value - True for success


CTCPSocket* Accept()
--------------------

Constructs a new socket and accept the connection into it.

return value - NULL for error, if not then the new socket address.

CTCPOptions* GetTCPOptions()
----------------------------

return value - The TCP option structure.

void SetTCPOptions(BOOL bOptions)
---------------------------------

Allows the usage of TCP options.

bOptions - True to enable options.
	

CTCPOptions
-----------

Same as IP options.


CUDPSocket
----------

Can be used for udp packet sending.

functions:

BOOL SetBroadcast(BOOL bBroadcast)
----------------------------------

Allows the socket to broadcast.

return value - Non zero for success.

BOOL Send(int iSourcePort, 
	  LPCSTR lpDestinationAddress, 
	  int iDestinationPort,
	  char* buf,
	  int BufLength)
------------------------

iSourcePort - Source port to connect from (zero for any)
lpDestinationAddress - Destination address.
iDestinationPort - Destination port to connect to (zero for any)
buf - Buffer to send over.
BufLength - Buffer length.

return value - Non zero for success.

BOOL Create()
-------------

Create the socket (using TCP)

return value - Non zero for success.


CICMPSocket
-----------

SendType
--------

Sends an ICMP message of that type (for a complete description go to the ICMP RFC)

virtual BOOL ProccessICMP(char* buf)
------------------------------------

this is an internal function to proccess the incoming ICMP data (separates the IP header)

virtual BOOL OnSocketReceive(int iErrorCode)
--------------------------------------------

This function receives notification of incoming data, receives it and proccesses it.

unsigned long GetLastDataSize()
-------------------------------

return value - Data size of the last incoming packet.

const LPIpHeader GetLastIPHeader()
----------------------------------

return value - The last proccess IP header.

const LPICMPHeader GetLastICMPHeader()
--------------------------------------

return value - The last proccessed ICMP header.


6. The samples.
--------------

Samples:

1.Attacker - Simple MFC program that employs 3 known attacks, just to demonstrate the library.
2.kping - Sample ping program. (Console)
3.ktracert - Sample trace route. (Console)
4.TCPServer - Sample of a very basic TCP server. (Console)

7. What's next ?
----------------

Currently we are working to expand the library (to version 3):

A. Add fragmantation support.
B. Allow TCP to fully connect. (Raw)
C. Fix some bugs (which will be found)
D. Add more samples, like UDP scanner.

8. Contact us.
--------------

Site : http://www.komodia.com
email : barak@komodia.com
