on all Linux Platforms
Document History
Sept 20, 2000 | Shahrzad Ghafarpour | The initial draft |
Oct 17, 2000 | Updated, minor information was added to clarify the packet filtering | |
Contents
This document is intended for members of Quality Assurance and Development teams of client group, in an intention to assist the reader in designing black box test plans
Internal Documents
clientshim.html
shim-test.doc
(Text file)
shim.doc(Text
file)
zkshim_test_grid.html
Freedom Network Famous Ports
frNetworkDefaults.h
External Documents - maybe useful as introduction
Introduction
to Linux Kernel Modules
Linux
Networking Overview How-to
Useful Applications:
tcpdump
What is the Shim
Shim is a Kernel Module.
What does it do
Clientshim functionality may be summarized into two main functions:
Packet filtering: Shim Intercept all outgoing and forwarded packets
and filters them based on the rules given to it. If the packet matches
none of the rules it is given back to the firewall module.
Socket filtering: Shim Intercepts all socket connections and filters
them based on the rules given. If no rules are found that matches the socket,
the connection is permitted.
What does it requires
ZKShim requires kernel firewall support since the packets are intercepted
by firewall and then passed to the shim.
If the kernel does not have support for firewall the user will be prompted
an error while installing the kernel (complaining about unresolved symbols).
The difference between server shim and the client shim
Socket filtering is the main difference between the client and server
functionality. This feature was added for redirecting the outgoing
connections to our freedom proxies.
How do we know if the shim is installed
To get a list of all loaded modules, 'lsmod' is the command to use.
List of installed modules may also be obtained for /proc/modules.
How do we know if the shim is working
To test the basic functionality of the clientshim, unit tests can be
used. Unit tests cover the main API of the clientshim.
They open the device, add a rule, delete a rule, write to the device
(A single packet), read from the device and then close the device.
How do we know if the shim is working correctly
This is the main objective of this document. Clientshim is a part of
freedom client, freedom application adds a set of rules to clientshim after
initialization the stage. The test plan makes an attempt to prove that
clientshim behaves as expected under this set, and further it does not
leak any information (packets) about the outgoing destination while a nym
is selected.
Where can I see the log/debug messages from the shim
If the debug version of the shim is installed, the debug information
can be seen at /proc/kmsg
Basics
Clientshim.html explains the design of
the shim module
Clientshim Rules contains list
of rules added to clientshim module while freedom is running. Rules can
also be found under /proc/net/clientshim when the module is loaded.
Basically before integration of firewall, Freedom Client behavior in
relation to packet filtering was shaped by the rules added to the clientshim.
After the firewall integration, (and yes the firewall code has been
integrated into the Linux client but the configuration is not supported
) the packet filtering is divided into two areas of the code. The Clientshim
module still does filter the packets base on the rules added to it's rule
chain but packets also get filtered in the firewall based on the firewall's
default rule set. Firewall default behavior hence is supported by Linux
Freedom Client and the document that explains these rules may be found
here.
The default behavior on Linux client is to block all ports if the port
is not supported by our proxy servers, this is different from the default
behavior on windows client since the default behavior for this platform
is to allow all the ports unless they are blocked by the firewall configuration
for detailed information refer to bug 6694.
One reason for the existence of packet filtering in addition to firewall's
default behavior, is the multi user characteristics of Linux operating
system as all of us are aware of. Since this characteristic does
not exist in windows operating system this issue was not considered in
the design of the firewall hence the addition of packet filtering rules
in the clientshim module on top of firewall functionality. This means
that packet flows through stack to the clientshim kernel module then gets
filtered based on the clientshim rules then it is redirected back to the
stack and received by the the freedom client and filtered through
the firewall rules. At this point packets are wrapped into UDP headers
, encrypted and they are sent back to the clientshim module to be sent
to the wormhole. This is one of many paths that data may take. In
addition to the packet filtering, clientshim is used for filtering the
socket connect calls. In summary the socket filtering functionality is
added to redirect the socket connections to freedom proxies. The socket
filtering rules can be summarized in the following table.
Clientshim Socket filtering Specifications:
As shown in the Clientshim rule set, all TCP connections from all processes that have the same user ID as Freedom user, are redirected to our proxy servers as shown below:
State: Nym Selected
Protocol | Destination port | Proxy port |
SSL | 443 | 51207 |
TELNET | 22,23 | 51206 |
IRC | 7000,6670,6669-6661 | 51205 |
HTTP | 80,8080 | 51203 |
SSL | 119 | 51204 |
SMTP | 25 | 51202 |
POP | 110 | 51201 |
State: True Identity
Protocol | Destination port | Proxy port |
SSL | 443 | 51207 |
HTTP | 80,8080 | 51203 |
SSL | 119 | 51204 |
SMTP | 25 | 51202 |
POP | 110 | 51201 |
The exception being the connections that are made from freedom process, these connections are not redirected.
Clientshim Packet filtering Specification
All packets with destination address set to 51103 (Token server), 51104
(Nym server), 51107 (NIBD/NIQS server), 51110 (FMGMAIP server) are dropped
unless they are oroginated from freedom.
All UDP packets with destination port 51101 sent by freedom pass through
unmodified.
All packets with source and destination set to localhost (127.0.0.1)
pass through unmodified.
The rest of packets are diverted back to the user space.
Exceptions, and rules that effect packet filtering but are not included in clientshim rule set or firewall document.
An exception to the rules mentioned in above tables, is the outgoing
ICMP packet of type destination unreachable and code port unreachable.
These packets are silently dropped as a security measure. TCP/IP
Stack automatically generates these packets if it recieves any packet that
it is not expected, the IP header of the original (unecpected) packet
recieved is sent out as a part of ICMP packet in the clear and this
definitely could reveal a lot of information on the traffic that
has been through the wormhole. Refer to Bugzilla for detailed information
behind this bug fix.
Another exception to above rules is the bug fix for bug number 5827.
All DNS queries are sniffed for request that can generate MX response (to
resolve address of a mail exchange server ) , if the request contain a
query for MX record, instead of sending the query out to the network,
Linux client sends a reply to that request, this reply resolves any address
to the freedomize.safedns domain.
Advanced
1. Freedom and firewalls
If a Linux firewall is configured to run for the same user that
is running the freedom client what ports are absolutely necessary?
Obviously the Freedom client requires to make connections to the Freedom
network.
The following Outgoing connections cannot be blocked by firewalls:
UDP 51101 (Connections to the AIP)
TCP 51102 (Connections to the AIP)
TCP 51103 (Connection to the Token server)
TCP 51104 (Connection to the Nym server)
TCP 51107 (Connection to the NIB?NIQS server)
TCP 51109 (Connections to the freedom key Query server)
TCP 51114 (Connections to Freedom pop server)
2. Freedom and IP Masquerading
Why?
How?
Problems?
Multiple processor machines (never been tested )
Multiple interfaces (currently not supported)
Multiple users running freedom on the same machine at the same time
(currently not supported)
Support for 2.4 Kernels (currently not supported)