XIA Interposition Library

Table of Contents Introduction How Do We Do It? What's Covered? What's Not Covered? Mapping DAGs to IP/ports Processing Example Host0 Host1 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 getaddrinfo, 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.

Mapping DAGs to IP/ports

Under the interposition library, applications act on IP addresses and ports and have idea that they are running over an XIA network. This is accomplished by turning the IP/port pair into an identifier in the form of On the server side, XIA creates a new DAG when <code>bind is called and creates forward and reverse mappings between the ID both internally to itself and in the mapping server. An additional hostname/port based mapping is also registered with the mapping server.

If a client calls a name resolution function such as gethostbyname or getaddrinfo, the request is redirected to the mapping server and a DAG is returned. xwrap then creates a fake IP address to associate with the name and returns it to the calling app.

When the client attempts to connect or sendto, the IP/port is used to lookup the DAG internally in the wrapper. If found, the associated DAG is used. If not found, the IP/port pair is converted to an ID and is looked up on the mapping server. The DAG received is not mapped internally so no future trips to the mapping server are required. In this way, xwrap can support both IP and name based lookups.

When data is received, the DAG is used to find the associated IP, port, and socket. The data is then sent up to the application over that socket.

Processing Example

Host0

xwrap netcat -lk 6666

1. launch netcat using the interposition library and tell it to listen on port 6666. The port number doesn't matter as long as it is known to the client. However, it is only used to create an mapping identifier, the actual TCP or UDP port is not used for networking.
2. xwrap.so loads into the process space and hooks the socket related APIs
3. other libraries load into the process space
4. 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
5. 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
     • create an identifier using the hostname and port
     • register the IP ID and DAG in the mapping server
     • register the host ID and DAG in the mapping server
   • call (X)listen and (X)accept using the DAG and wait for connections
   • receive a connection on the DAG
   • lookup the associated sockaddr in the internal mapping tables
   • notify netcat that a connection has been accepted
   • Go into a (X)send/(X)recv loop
     • calls are mapped onto the XIA versions and data is sent normally across the network.
     • netcat thinks it's using IPv4 communication and functions normally

Host1

 xwrap netcat host0 6000

Steps 1-4 are the same as above aside from telling netcat to connect to host0 on port 6666

• netcat starts to run
  • call (x)getaddrinfo to lookup host0 and port 6666
    • create an ID using the hostname and port #
    • look for the ID in the local mapping table
    • if ID is not found contact the mapping server with ID
    • receive the DAG registered by host0
    • create a fake IP address to associate with the DAG locally and generate an ID using it
    • create a mapping between the DAG and the ID
    • return a sockaddr to netcat containing the fake IP and port
  • create a (X)socket
  • call (X)fcntl and set socket to non-blocking
  • call connect using the received sockaddr
    • lookup DAG in local tables using the sockaddr
    • create a DAG for this socket and create a mapping between it and the local IP/port
    • associate the new DAG with this socket
    • call Xconnect and connect to host0 using the remote DAG
• Go into a (X)send/(X)recv loop
  • calls are mapped onto the XIA versions and data is sent normally across the network.
  • netcat thinks it's using IPv4 communication and functions normally

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