The Freedom ZKShim

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

Audience

Related Docs and Useful Links

Introduction

Design

Future Considerations

Audience

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

Related Docs and Useful Links

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
 
 

Introduction

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

Design
 

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?
 

Future Considerations

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)