Home

Awesome

zdtun

zdtun (short for "Zero Dependency Tunnel") is a C library which provides an API to integrate VPN like functionalities on existing programs without installing third-party software or drivers on the target device.

This library is used in PCAPdroid to capture network packets on Android without root.

The library implements parts of a TCP/IP stack, for example the tracking of sessions and handling of TCP sequence numbers and window size. However, zdtun does not implement any TCP retransmission logic, as this feature is already provided by the TCP sockets used internally.

Features

zdtun offers the following features:

Sample Integration

Here is how to use the zdtun api to integrate its VPN capabilities into an existing program:

#include "zdtun.h"

/* This is called when zdtun needs to send data to the client */
int send_client_callback(zdtun_t *tun, zdtun_pkt_t *pkt, const zdtun_conn_t *conn_info) {
  int cli_socket = *((int*) zdtun_userdata(tun));

  send(cli_socket, pkt->buf, pkt->len, 0);
}

int main() {
  /* A TCP socket connected to the client */
  socket_t cli_socket = ...;
  zdtun_callbacks_t callbacks = {
    .send_client = send_client_callback,
  };
  ...

  // ignore SIGPIPE, which can occur while sending data
  signal(SIGPIPE, SIG_IGN);

  zdtun_t *tun = zdtun_init(&callbacks, &cli_socket);

  while(1) {
    int max_fd = 0;
    fd_set fdset;
    fd_set wrfds;
  
    /* get zdtun own fds */
    zdtun_fds(tun, &max_fd, &fdset, &wrfds);

    /* Add client fd to the readable fds */
    FD_SET(cli_socket, &fdset);
    max_fd = max(max_fd, cli_socket);

    /* Wait for socket events */
    select(max_fd + 1, &fdset, &wrfds, NULL, NULL);

    if(FD_ISSET(cli_socket, &fdset)) {
      /* Got data from the client, forward it to the private network */
      size = recv(cli_socket, buffer, sizeof(buffer), 0);
      zdtun_easy_forward(tun, buffer, size);
    } else {
      /* let zdtun handle it */
      zdtun_handle_fd(tun, &fdset, &wrfds);
    }
  }

  zdtun_finalize(tun);
}

See zdtun_gateway.c for a complete example.

Run Local Gateway

The zdtun_gateway is a program which routes all the local/internet connections through zdtun via a TUN device. It can be useful to easily test the zdtun functionalities locally.

Motivation

The library was initially developed for Windows, as a way to provide VPN-like feature into an existing program, and later extended for the linux/Android world.

Tunneling traffic through Windows can be tricky:

Existing solutions are complex and not appropriate to be integrated as a library into an existing program.

See Also