XIA Interposition Library

Table of Contents Introduction How Do We Do It? What's Covered? What's Not Covered? Detailed Description Processing Mapping between IPv4 and XIA Example Host0 Client Usage Captured APIs Redirected to XIA Information Only

Introduction

The XSockets API is useful when writing a new socket application from scratch. It would be nice if it were possible to simply recompile an existing socket application and link to the Xsocket library and have it work over XIA. Unfortunately there are enough differences that this is not as easy as one would like. There are minor issues that can be dealt with via search and replace such as address family and the need to append an X to the socket API calls. The main issue is the difference in addressing. A DAG is very different from an IP address, and XIA has nothing similar to a port. The service is simply part of the DAG. So any code that looks up services and directly manipulates the sockaddr structure needs to be changed as well.

Porting a simple application such as netcat can be done in a few hours, but a larger application such as Firefox is a major undertaking. And there is no way to port proprietary applications with no source code. To improve the transition to XIA an interposition library has been created that will let unmodified socket applications work on with XIA.

The interposition library is perpetual beta state as we add new functionality required by applications being tested.

How Do We Do It?

The interposition library is implemented as a shared library (xwrap.so). It is loaded into the process space before any systems libraries and takes ownership of all of the function calls that can be used with sockets. This is accomplished by using the LD_PRELOAD environment variable. Each function in the library inspects the function parameters (usually just the file descriptor) to determine if the call should be redirected to the Xsockets API, or if can be passed through to the default API.

• Any call that specifies the AF_INET family is captured and AF_XIA is used instead. The only major downside of this is that we cannot currently support applications that might want to use both IP and XIA at the same time. This restriction does not affect IPv6. Examples functions are socket and inet_ntop among others.
• All name related calls such as getaddrinfo and gethostbyname are essentially nat'ed internally. A more detailed description follows below.
• Any function that takes a file descriptor is checked to see if the descriptor is associated with an Xsocket. If so, the call is redirected to the appropriate XIA API. If not, it's handled normally.

What's Covered?

• All of the traditional socket APIs such as socket, bind, connect, send, and setsockopt have direct XIA analogs and use a simple remapping.
• Address related APIs such as <cod>getaddrinfo&lt;/code&gt;</cod>, gethostbyname and gethostbyaddr are remapped so that the IP/port pair is associated with a DAG.
• poll and select are implemented so that they can be used with Xsockets and file descriptors simultaneously.
• Some non-socket related APIs such as fork are also captured because of how sockets are dealt with under the covers.

What's Not Covered?

• Anything that uses a FILE object is not currently supported. This mainly affects old code like some early versions of ftp. At one point the library tried to handle these functions, but it proved problematic and support has been removed.
• Xsockets currently supports a subset of the available socket options. For the most part, success is returned when setting options and a reasonable default is returned when querying. In a few cases an error is returned. Full support for unhandled options is being added as the need is encountered.
• Because there is no comparable socket type in the standard library, applications that use content chunks must use the caching API. However, programs may add caching function calls while leaving the existing socket code alone to be run inside the interposition library.
• XIA doesn't currently have support for dup'ing a socket.
• we are still adding support to deal with issues caused by exec
• Existing apps that use raw socket will most likely fail as they write the packet headers themselves.

Detailed Description

Processing

Mapping between IPv4 and XIA

Example

Host0

xwrap netcat -lk 6666

• launch netcat using the interposition library and tell it to listen on port 6666. The port number doesn't matter as it is only used to create an identifier, the actual TCP or UDP port is not used for networking.
• xwrap.so loads into the process space and hooks the socket related APIs
• other libraries load into the process space
• xwrap initialization
  • read configuration from the environment (in this instance no switches were set, so xwrap disables all logging)
  • save addresses of the original socket APIs
  • register the host name (host0) in the mapping server with the AD/HID of the host machine. This will be used later for calls such as gethostbyname
• netcat starts to run
  • create a (X)socket
  • call (X)getaddrinfo to create a sockaddr for the local IP/port and receives a valid IPv4 sockaddr_in
  • call (X)bind which causes the wrapper to:
    • create a new AD/HID/SID DAG
    • create an internal mapping between the sockaddr and the DAG
    • create an identifier using the IP and port
    • register the ID and DAG in the mapping server
    • using the port, create another ID mapping the hostname and port to the same DAG
  • bind to port 6666

Client

 xwrap netcat -lk 6000

 #machine 2
 xwrap netcat host0 6000

Usage

The XWRAP script is provided to simplify launching your application with the interposition library. It sets the appropriate environment variables and then launches the application with the xwrap.so library injected and loaded before the standard libraries.

xwrap myapp myapp_arguments

The XWRAP man page provides information on other command line options. provides several command line switches for generating log messages that can be useful when porting your application.

* The '''-t''' switch (trace) is useful when first looking at an application to see what function calls are used. It logs calls irregardless of whether they are remapped onto XIA. * The '''-i''' switch causes the wrapper to log informative and debug messages. These are generally more useful for the development of the wrapper than applications using it. * The '''-x''' switch logs a message whenever an API call is redirected to the Xsocket API. This switch can be quite useful for debugging problems. * The '''-w''' switch logs warnings and errors and can be useful to determine why a wrapped application is not working.

==Captured APIs==

===Redirected to XIA===

* accept * accept4 * bind * close * connect * fcntl * fork * freeaddrinfo * freeifaddrs * gai_strerror * getaddrinfo * gethostbyaddr * gethostbyaddr_r * gethostbyname * gethostbyname2 * gethostbyname_r * gethostbyname2_r * getifaddrs * getpeername * getsockname * getsockopt * listen * poll * read * readv * recv * recvfrom * recvmsg * select * send * sendmsg * sendto * setsockopt * shutdown * socket * socketpair * write * writev

===Information Only===

The functions below are not either not supported by XIA, or don't provide enough information in their parameters to allow them to be mapped to a corresponding XIA function. However they have been wrapped so that log messages can be generated to indicate that porting issues may be present.

* getnameinfo * getservbyname * getservbyname_r * getservbyport * getservbyport_r * execve * clone